CLAUDE.md

@@ -6,8 +6,9 @@ OVERRIDE any default behaviour and must be followed exactly.
 ## Repo purpose
 
 Configuration toolsets and docs for Wayne's Debian-based LAN machines.
-Two sections currently exist: `proxmox/` (Proxmox VE hosts) and
+Three sections currently exist: `proxmox/` (Proxmox VE hosts),
-`pihole/` (Pi-hole DNS/DHCP). Each has its own README.
+`pihole/` (Pi-hole DNS/DHCP), and `freeipa/` (FreeIPA identity
+management). Each has its own README.
 
 ## Safety rules (apply everywhere in this repo)
 
@@ -35,6 +36,10 @@ Two sections currently exist: `proxmox/` (Proxmox VE hosts) and
   rules above. `apply-config.sh` is the only script that touches a live
   host; treat its `<dest-host>` argument as production unless you're
   explicitly testing on a throwaway instance.
+- **FreeIPA:** `freeipa/` documents and scripts for the FreeIPA identity
+  management server (`domain-controller.sweet.home`, VMID 108 on `pve1`).
+  All scripts that SSH into the server are production operations — treat
+  them as off-limits without an explicit same-session go-ahead.
 
 ## Adding a new machine type
 

freeipa/README.md

@@ -9,7 +9,7 @@ Proxmox VM (VMID 108 on `pve1.sweet.home`).
 | Item | Value |
 |------|-------|
 | Host | `domain-controller.sweet.home` |
-| IP | `192.168.2.138` (static) |
+| IP | `192.168.2.253` (static) |
 | Realm | `SWEET.HOME` |
 | Domain | `sweet.home` |
 | IPA version | 4.13.x (Rocky Linux 9) |
@@ -21,8 +21,8 @@ Proxmox VM (VMID 108 on `pve1.sweet.home`).
 
 - **Kerberos KDC** — SSO tickets for the `SWEET.HOME` realm
 - **LDAP directory** — centralised user/group/host store (389-ds)
-- **Integrated DNS** — authoritative for `sweet.home`, forwarding
+- **Integrated DNS** — authoritative for `sweet.home` and primary LAN
-  everything else upstream to Pi-hole (`192.168.2.253`)
+  resolver for all hosts, forwarding everything else to the LAN gateway
 - **CA** — self-signed CA issuing certs for IPA services
 - **Web UI** — at `https://domain-controller.sweet.home/ipa/ui/`
 
@@ -60,19 +60,6 @@ kinit admin
 ipa passwd admin
 ```
 
-## DNS integration with Pi-hole
-
-Pi-hole must forward `sweet.home` DNS queries to this server so
-that Kerberos SRV records and IPA host records resolve correctly.
-Run `scripts/configure-pihole-dns.sh` once, or add the following
-to Pi-hole's custom DNS config manually:
-
-```
-server=/sweet.home/192.168.2.138
-```
-
-See `docs/pihole-dns.md` for the full setup.
-
 ## Ports required (firewalld)
 
 FreeIPA's firewalld config is applied by `ipa-server-install` automatically.

freeipa/docs/install.md

@@ -78,11 +78,13 @@ echo 'ssh-rsa AAAA... wayne@stream' > /tmp/admin-key.pub
 # (use the key from variables.nix adminSshKey)
 
 # Configure cloud-init
+# Use the LAN gateway as temporary DNS — IPA itself will be the DNS at
+# 192.168.2.253, but it's not running yet at this point in the install.
 sudo qm set <VMID> \
   --ciuser wayne \
   --sshkeys /tmp/admin-key.pub \
   --ipconfig0 ip=dhcp \
-  --nameserver 192.168.2.253 \
+  --nameserver 192.168.2.254 \
   --searchdomain sweet.home
 
 # Set boot order
@@ -138,10 +140,13 @@ echo '/swapfile none swap defaults 0 0' | sudo tee -a /etc/fstab
 CON=$(nmcli -t -f NAME con show --active | head -1)
 sudo nmcli con mod "$CON" \
   ipv4.method manual \
-  ipv4.addresses 192.168.2.138/24 \
+  ipv4.addresses 192.168.2.253/24 \
   ipv4.gateway 192.168.2.254 \
-  ipv4.dns 192.168.2.253 \
+  ipv4.dns 192.168.2.254 \
   ipv4.dns-search sweet.home
+# Note: using the gateway as DNS here — after IPA installs it becomes the
+# authoritative resolver at 192.168.2.253. Clients should then point to
+# 192.168.2.253 for sweet.home resolution.
 sudo nmcli con up "$CON"
 ```
 
@@ -149,7 +154,7 @@ sudo nmcli con up "$CON"
 
 ```bash
 sudo sed -i '/domain-controller/d' /etc/hosts
-echo '192.168.2.138 domain-controller.sweet.home domain-controller' \
+echo '192.168.2.253 domain-controller.sweet.home domain-controller' \
   | sudo tee -a /etc/hosts
 
 # Prevent cloud-init from resetting this on reboot
@@ -192,7 +197,7 @@ sudo ipa-server-install \
   --ds-password="$DM_PASS" \
   --admin-password="$ADMIN_PASS" \
   --setup-dns \
-  --forwarder=192.168.2.253 \
+  --forwarder=192.168.2.254 \
   --no-dnssec-validation \
   --no-ntp \
   --unattended
@@ -200,7 +205,7 @@ sudo ipa-server-install \
 
 Key flags:
 - `--setup-dns` — install BIND as IPA's authoritative DNS for `sweet.home`
-- `--forwarder=192.168.2.253` — forward non-sweet.home queries to Pi-hole
+- `--forwarder=192.168.2.254` — forward non-sweet.home queries to the LAN gateway
 - `--no-dnssec-validation` — skip DNSSEC (home lab has no DNSSEC chain)
 - `--no-ntp` — Proxmox handles time sync for guests; don't install chrony
 
@@ -223,18 +228,7 @@ dig +short _kerberos._udp.sweet.home SRV @127.0.0.1
 
 ---
 
-## Step 7 — Configure Pi-hole to forward sweet.home DNS
+## Step 7 — Back up the CA certificate
-
-See `docs/pihole-dns.md` and `scripts/configure-pihole-dns.sh`.
-
-The short version — add to Pi-hole's custom dnsmasq config:
-```
-server=/sweet.home/192.168.2.138
-```
-
----
-
-## Step 8 — Back up the CA certificate
 
 ```bash
 # On domain-controller (encrypted with Directory Manager password)

freeipa/docs/pihole-dns.md

@@ -1,70 +0,0 @@
-# Pi-hole DNS forwarding for sweet.home
-
-FreeIPA's BIND instance is the authoritative DNS server for the
-`sweet.home` zone. Pi-hole (at `192.168.2.253`) is the LAN resolver
-for everything else. To make Kerberos, LDAP, and host lookups work
-from all LAN clients, Pi-hole must forward `sweet.home` queries to
-the domain-controller.
-
-## What needs configuring
-
-One dnsmasq directive on Pi-hole:
-
-```
-server=/sweet.home/192.168.2.138
-```
-
-This makes Pi-hole forward every `*.sweet.home` query (and the bare
-`sweet.home` zone) to `192.168.2.138` (domain-controller) instead
-of its upstream resolver.
-
-## How to apply
-
-Use `scripts/configure-pihole-dns.sh` for an automated, idempotent
-application, or apply manually as below.
-
-### Manual — Pi-hole v6 (TOML config)
-
-Pi-hole v6 reads custom dnsmasq options from:
-```
-/etc/pihole/pihole.toml  →  dns.customDnsEntries
-```
-or from drop-in files in `/etc/dnsmasq.d/`. The drop-in approach
-is more robust across upgrades:
-
-```bash
-ssh <pihole-host>
-echo 'server=/sweet.home/192.168.2.138' \
-  | sudo tee /etc/dnsmasq.d/10-ipa-sweet-home.conf
-sudo pihole restartdns
-```
-
-Verify:
-```bash
-dig +short _kerberos._udp.sweet.home SRV @192.168.2.253
-# Should return: 0 100 88 domain-controller.sweet.home.
-dig +short domain-controller.sweet.home A @192.168.2.253
-# Should return: 192.168.2.138
-```
-
-## Why this is required
-
-FreeIPA clients use DNS SRV records to discover the KDC, LDAP server,
-and other IPA services. Without the forwarder, Pi-hole returns NXDOMAIN
-for `_kerberos._udp.sweet.home` and `_ldap._tcp.sweet.home`, which
-causes `kinit` and IPA client enrollment to fail — even if the IP
-address is reachable.
-
-## Records IPA publishes
-
-Once forwarding is set up, Pi-hole clients will be able to resolve:
-
-| Record | Type | Value |
-|--------|------|-------|
-| `domain-controller.sweet.home` | A | `192.168.2.138` |
-| `_kerberos._udp.sweet.home` | SRV | `0 100 88 domain-controller.sweet.home` |
-| `_kerberos._tcp.sweet.home` | SRV | `0 100 88 domain-controller.sweet.home` |
-| `_ldap._tcp.sweet.home` | SRV | `0 100 389 domain-controller.sweet.home` |
-| `_kpasswd._udp.sweet.home` | SRV | `0 100 464 domain-controller.sweet.home` |
-| `_kerberos.sweet.home` | TXT | `"SWEET.HOME"` |
-| `ipa-ca.sweet.home` | A | `192.168.2.138` |

freeipa/scripts/configure-pihole-dns.sh

@@ -1,46 +0,0 @@
-#!/usr/bin/env bash
-# Configure Pi-hole to forward sweet.home DNS queries to FreeIPA.
-#
-# Usage:
-#   bash configure-pihole-dns.sh <pihole-host>
-#   bash configure-pihole-dns.sh pihole.sweet.home
-#
-# Idempotent — safe to run multiple times.
-# Requires SSH access to the Pi-hole host as a user with sudo.
-
-set -euo pipefail
-
-PIHOLE_HOST="${1:-}"
-IPA_IP="192.168.2.138"
-IPA_DOMAIN="sweet.home"
-DNSMASQ_CONF="/etc/dnsmasq.d/10-ipa-${IPA_DOMAIN//./-}.conf"
-DIRECTIVE="server=/${IPA_DOMAIN}/${IPA_IP}"
-
-if [[ -z "$PIHOLE_HOST" ]]; then
-  echo "Usage: $0 <pihole-host>" >&2
-  exit 1
-fi
-
-echo "==> Configuring Pi-hole at $PIHOLE_HOST to forward $IPA_DOMAIN → $IPA_IP..."
-
-ssh "$PIHOLE_HOST" "
-  set -euo pipefail
-
-  if grep -qF '${DIRECTIVE}' '${DNSMASQ_CONF}' 2>/dev/null; then
-    echo '==> Forwarder already configured, skipping write.'
-  else
-    echo '${DIRECTIVE}' | sudo tee '${DNSMASQ_CONF}'
-    echo '==> Written to ${DNSMASQ_CONF}'
-  fi
-
-  echo '==> Restarting Pi-hole DNS...'
-  sudo pihole restartdns
-
-  echo '==> Verifying SRV record resolution via Pi-hole...'
-  sleep 2
-  dig +short _kerberos._udp.${IPA_DOMAIN} SRV @127.0.0.1 || true
-"
-
-echo "==> Done. Pi-hole now forwards ${IPA_DOMAIN} queries to ${IPA_IP}."
-echo "    Verify from a LAN client:"
-echo "      dig +short _kerberos._udp.${IPA_DOMAIN} SRV @${PIHOLE_HOST}"