CLAUDE.md

@@ -101,17 +101,21 @@ This ensures documentation matches the exact nixpkgs version (currently NixOS 25
 
 ### Directory Structure
 
-- `/flake.nix` - Central flake defining all 16 NixOS configurations
+- `/flake.nix` - Central flake defining all NixOS configurations
 - `/hosts/<hostname>/` - Per-host configurations
   - `default.nix` - Entry point, imports configuration.nix and services
   - `configuration.nix` - Host-specific settings (networking, hardware, users)
 - `/system/` - Shared system-level configurations applied to ALL hosts
   - Core modules: nix.nix, sshd.nix, sops.nix, acme.nix, autoupgrade.nix
   - Monitoring: node-exporter and promtail on every host
+- `/modules/` - Custom NixOS modules
+  - `homelab/` - Homelab-specific options (DNS automation, etc.)
+- `/lib/` - Nix library functions
+  - `dns-zone.nix` - DNS zone generation functions
 - `/services/` - Reusable service modules, selectively imported by hosts
   - `home-assistant/` - Home automation stack
   - `monitoring/` - Observability stack (Prometheus, Grafana, Loki, Tempo)
-  - `ns/` - DNS services (authoritative, resolver)
+  - `ns/` - DNS services (authoritative, resolver, zone generation)
   - `http-proxy/`, `ca/`, `postgres/`, `nats/`, `jellyfin/`, etc.
 - `/secrets/` - SOPS-encrypted secrets with age encryption
 - `/common/` - Shared configurations (e.g., VM guest agent)
@@ -137,6 +141,7 @@ All hosts automatically get:
 - Daily auto-upgrades with auto-reboot
 - Prometheus node-exporter + Promtail (logs to monitoring01)
 - Custom root CA trust
+- DNS zone auto-registration via `homelab.dns` options
 
 ### Active Hosts
 
@@ -279,14 +284,17 @@ This means:
 1. Create `/hosts/<hostname>/` directory
 2. Copy structure from `template1` or similar host
 3. Add host entry to `flake.nix` nixosConfigurations
-4. Add hostname to dns zone files. Merge to master. Run auto-upgrade on dns servers.
-5. User clones template host
-6. User runs `prepare-host.sh` on new host, this deletes files which should be regenerated, like ssh host keys, machine-id etc. It also creates a new age key, and prints the public key
-7. This key is then added to `.sops.yaml`
-8. Create `/secrets/<hostname>/` if needed
-9. Configure networking (static IP, DNS servers)
+4. Configure networking in `configuration.nix` (static IP via `systemd.network.networks`, DNS servers)
+5. (Optional) Add `homelab.dns.cnames` if the host needs CNAME aliases
+6. User clones template host
+7. User runs `prepare-host.sh` on new host, this deletes files which should be regenerated, like ssh host keys, machine-id etc. It also creates a new age key, and prints the public key
+8. This key is then added to `.sops.yaml`
+9. Create `/secrets/<hostname>/` if needed
 10. Commit changes, and merge to master.
 11. Deploy by running `nixos-rebuild boot --flake URL#<hostname>` on the host.
+12. Run auto-upgrade on DNS servers (ns1, ns2) to pick up the new host's DNS entry
+
+**Note:** DNS A records are auto-generated from the host's `systemd.network.networks` static IP configuration. No manual zone file editing is required.
 
 ### Important Patterns
 
@@ -313,5 +321,24 @@ All hosts ship metrics and logs to `monitoring01`:
 
 - `ns1` (10.69.13.5) - Primary authoritative DNS + resolver
 - `ns2` (10.69.13.6) - Secondary authoritative DNS (AXFR from ns1)
-- Zone files managed in `/services/ns/`
 - All hosts point to ns1/ns2 for DNS resolution
+
+**Zone Auto-Generation:**
+
+DNS zone entries are automatically generated from host configurations:
+
+- **Flake-managed hosts**: A records extracted from `systemd.network.networks` static IPs
+- **CNAMEs**: Defined via `homelab.dns.cnames` option in host configs
+- **External hosts**: Non-flake hosts defined in `/services/ns/external-hosts.nix`
+- **Serial number**: Uses `self.sourceInfo.lastModified` (git commit timestamp)
+
+Host DNS options (`homelab.dns.*`):
+- `enable` (default: `true`) - Include host in DNS zone generation
+- `cnames` (default: `[]`) - List of CNAME aliases pointing to this host
+
+Hosts are automatically excluded from DNS if:
+- `homelab.dns.enable = false` (e.g., template hosts)
+- No static IP configured (e.g., DHCP-only hosts)
+- Network interface is a VPN/tunnel (wg*, tun*, tap*)
+
+To add DNS entries for non-NixOS hosts, edit `/services/ns/external-hosts.nix`.