64 lines
4.7 KiB
Markdown
64 lines
4.7 KiB
Markdown
# REPORT — agent v0.21.0: agent-managed split-horizon LAN resolver (2026-06-11)
|
|
|
|
**Repo:** `felhom-agent` · **Version:** 0.21.0 · **Pushed commit:** `a43e981` · paired with
|
|
`felhom-controller` v0.42.1 (real wildcard cert — the GATE this depends on).
|
|
|
|
## What shipped — `internal/lanresolver`
|
|
|
|
LAN clients reach their guest **directly** at the same public hostname with the same real wildcard
|
|
cert (no Cloudflare hairpin), via a host-side dnsmasq the agent manages. The host is the stable anchor
|
|
(static LAN IP); the guest stays DHCP/ephemeral and the agent tracks its live IP.
|
|
|
|
- **Renderer** — a base drop-in (`/etc/dnsmasq.d/felhom-resolver-base.conf`: `bind-interfaces`,
|
|
`listen-address=<host-LAN-IP>` + `127.0.0.1`, `no-resolv`, `server=<upstreams>`) + a per-customer
|
|
drop-in (`felhom-<customer-id>.conf`: `local=/<domain>/` + `address=/<domain>/<guest-ip>`). The
|
|
proven two-line shape: `local=` makes dnsmasq authoritative for the zone so **AAAA → NODATA** (no
|
|
Cloudflare-AAAA split-brain — the guest has only link-local v6); `address=` is the wildcard A;
|
|
everything else (and its AAAA) forwards upstream unchanged.
|
|
- **`Manager`** — `EnsureDnsmasq` (apt-install if absent, base config, `systemctl enable --now`),
|
|
`ReconcileGuest` (discover live IPv4 via `pct exec <vmid> -- ip -4 -o addr show dev eth0`; discover
|
|
domain from the guest controller's pulled `controller.yaml` — the v2 bootstrap omits it; write-if-
|
|
changed; `systemctl reload`), `Remove` (decommission). Tolerates the early-boot pre-lease window
|
|
(empty IP → skip+retry, never a blank record); logs IP transitions. Never touches `/etc/resolv.conf`.
|
|
- **`Loop`** — a 7th daemon goroutine; every interval (default 300s) enumerates provisioned guests
|
|
(`/var/lib/felhom-agent/guests/<vmid>/`) and reconciles each, so the resolver follows DHCP IP moves.
|
|
- Config `lan_resolver.{enable,host_ip,upstreams,interval_seconds,state_dir}` (host_ip defaults to the
|
|
local-API bridge IP). `--selftest=lanresolver -vmid N`. New `FELHOM_DNSMASQ` sudoers alias.
|
|
|
|
## 2A spike findings (host environment — all green, no blockers)
|
|
- **`:53` is FREE** on the host (no systemd-resolved/dnsmasq/named).
|
|
- **Host IP is STATIC** — `vmbr0 inet static 192.168.0.162/24` (the stable anchor the router points at).
|
|
- **Host DNS intact** — `/etc/resolv.conf` (→ Pi-hole `192.168.0.250`) is untouched; the host resolves
|
|
upstream for itself independent of the dnsmasq we add for LAN clients.
|
|
- **Domain sourcing** — `pct exec <vmid> -- docker exec felhom-controller cat …/controller.yaml` →
|
|
`customer.domain` (no new credential).
|
|
|
|
## Live validation (felhom-pve, guest 9201 = demo-felhom)
|
|
- `--selftest=lanresolver -vmid 9201`: installed dnsmasq, wrote base + per-customer config, discovered
|
|
IP `192.168.0.151` + domain `demo-felhom.eu`, dnsmasq listening on `192.168.0.162:53`.
|
|
- **Full loop from dooplex (real LAN client):** `felhom.demo-felhom.eu A → 192.168.0.151`,
|
|
**AAAA → NODATA**, `example.com → forwards`, real cert `200 ssl_verify=0`.
|
|
- **IP-change tracking:** poisoned the drop-in with a stale IP → reconcile detected the live IP differs,
|
|
re-rendered + reloaded → corrected.
|
|
- **Daemon loop** runs (`lanresolver: enabled host_ip=192.168.0.162 interval_s=300`); gracefully skips a
|
|
not-yet-leased / absent guest.
|
|
- **Box-down:** with dnsmasq stopped, the primary (`192.168.0.162`) refuses; a secondary (`1.1.1.1`)
|
|
still answers normal names — so a client configured `[host-IP, secondary]` fails over to the
|
|
Cloudflare path; recovery confirmed on restart (dnsmasq is `enable`d → starts on boot).
|
|
|
|
## Install step (the one irreducible manual action) + robustness
|
|
- **One-time:** set the customer router's DNS servers to **[host-IP (192.168.0.x) primary, an upstream
|
|
secondary (e.g. 1.1.1.1)]**. After that, split-horizon is automatic forever — new apps auto-resolve
|
|
locally (the wildcard `address=` covers every subdomain) and serve the real wildcard cert.
|
|
- **Box-down:** the secondary means a box reboot degrades to the public/Cloudflare (hairpin) path, not
|
|
total DNS loss. Client DNS-failover is imperfect but standard; this is a required install config, not
|
|
agent code.
|
|
- **Locked ISP routers** (can't repoint DNS): LAN-direct isn't achievable; the Cloudflare tunnel remains
|
|
the graceful fallback. Documented, not forced.
|
|
- New host dependency the agent ensures: **dnsmasq** (installed/enabled by `EnsureDnsmasq`).
|
|
|
|
## Notes / follow-ups
|
|
- Stale guest state (`/var/lib/felhom-agent/guests/<vmid>/` for a destroyed guest) makes the loop log a
|
|
harmless per-tick skip; a decommission lifecycle should remove that dir + call `Manager.Remove`. Left
|
|
for the decommission slice. (Cleaned the one stale `9200` dir on the demo by hand.)
|