LAN DNS

The homelab gives every service a name under franksdank.cloud. Users type a name; they never type a port number. This page covers how names reach users: the dnsmasq server, the G36 router hand-off, and the split between LAN and WAN resolution.

See Caddy for the reverse proxy that serves the names, and Network Architecture for the full topology.

Components

Component	Where	Role
dnsmasq	Dankclaw quadlet (`dankclaw/dnsmasq/`)	Answers the flat service names for LAN clients
SURFboard G36	192.168.0.1	Hands dnsmasq to clients as the DHCP DNS server
Porkbun	Registrar for `franksdank.cloud`	Answers the same names for the WAN
Caddy	Dankclaw (192.168.0.143:443)	Serves every name over HTTPS

How a name reaches a client

sequenceDiagram
    participant C as LAN client (laptop, phone)
    participant G as G36 router (192.168.0.1)
    participant D as dnsmasq (192.168.0.143:53)
    participant P as Porkbun (WAN)
    participant X as Caddy (192.168.0.143:443)

    C->>G: DHCP request
    G-->>C: lease + DNS = 192.168.0.143
    C->>D: dig romm.franksdank.cloud
    D-->>C: 192.168.0.143
    Note over D: addn-hosts answer<br/>(dankclaw/dnsmasq/addn-hosts)
    C->>X: https://romm.franksdank.cloud
    X-->>C: RomM (192.168.0.235:8085 upstream)
    C->>P: dig franksdank.cloud (unknown name)
    P-->>C: 71.227.227.172

dnsmasq answers only the names in addn-hosts. Every other query goes to the upstream resolvers 1.1.1.1 and 1.0.0.1. The zone apex and unknown subdomains fall through to Porkbun. This avoids a wildcard override.

Why split DNS

The G36 has no NAT loopback (hairpin). A LAN client that resolves a name to the WAN IP and then connects to it would time out. Split DNS removes the hairpin: LAN clients get the LAN IP, WAN clients get the public IP. Both use the same name and the same Let's Encrypt certificate. See Caddy for the TLS side.

dnsmasq quadlet

Location: dankclaw/dnsmasq/ — dnsmasq.container (quadlet), dnsmasq.conf, addn-hosts, Containerfile
Port: 53/udp + 53/tcp on 192.168.0.143
Host prerequisite 1: sysctl net.ipv4.ip_unprivileged_port_start=53 (persisted in /etc/sysctl.d/99-dnsmasq.conf)
Host prerequisite 2: DNSStubListener=no in /etc/systemd/resolved.conf (the resolved stub would otherwise hold port 53 inside the container netns)

Rebuild + restart after a change:

podman build -t dnsmasq:latest -f dankclaw/dnsmasq/Containerfile .
systemctl --user daemon-reload
systemctl --user restart dnsmasq

Add a new service name in two places:

dankclaw/dnsmasq/addn-hosts — 192.168.0.143 <name>.franksdank.cloud
Porkbun — A record <name> 71.227.227.172 (so WAN clients and the DNS-01 challenge work)

Then add the vhost to Caddy and run ./scripts/deploy.sh dankclaw.

G36 router DNS hand-off

The router must tell DHCP clients to use dnsmasq. Until that step is done, new clients get the router's own DNS relay and the flat names do not resolve for them. Existing clients that already use dnsmasq are unaffected.

Manual step (web GUI at https://192.168.0.1):

Open Gateway → Connection → Local IP Network → IPv4.
Uncheck DNS Proxy (disable the router DNS relay).
Set DNS to Statically configured.
Set Primary DNS to 192.168.0.143.
Leave the secondary field empty or set 0.0.0.0.
Apply, then re-lease DHCP on each client (sudo dhclient -r && sudo dhclient).

The router admin interface has no programmatic API in this firmware. The web GUI is the only control path. Keep the credentials out of this repo; the repo tracks no router secrets.

Verify after the change:

# on a LAN client
resolv.conf          # nameserver 192.168.0.143
dig romm.franksdank.cloud +short
# expected: 192.168.0.143

Dankclaw host DNS

The Dankclaw host itself resolves the flat names through dnsmasq:

/etc/systemd/resolved.conf: DNS=192.168.0.143 192.168.0.1 (dnsmasq first, router as fallback)

Without this, the host would resolve the names through the router to the WAN IP and time out (no hairpin).

WAN records (Porkbun)

The Porkbun zone franksdank.cloud carries an A record for every vhost plus the apex, all pointing at 71.227.227.172. TTL is 300. The zone has no wildcard record: unknown subdomains return NXDOMAIN. Caddy's DNS-01 challenges add and remove _acme-challenge.* TXT records through the same API during issuance. See Caddy for the TLS flow.

franksdank.casa is not in this Porkbun account. The plex.franksdank.casa vhost stays plain HTTP for that reason. The canonical Plex name is plex.franksdank.cloud (HTTPS).

Failure modes

Symptom	First check
Name does not resolve on a new client	`resolv.conf` shows 192.168.0.1, not .143 — the G36 hand-off step is missing
Name resolves to 71.227.x and times out on the LAN	Client used the router DNS — same root cause
`dig @192.168.0.143` fails entirely	dnsmasq quadlet down: `systemctl --user status dnsmasq`
HTTPS works from the host but not the WAN	No port forward on the G36 for that service (manual router step)
Cert renewal fails in Caddy logs	Porkbun API credentials in the Dankclaw `.env`; test with the Porkbun API `/ping` endpoint

5.4 KiB Raw Blame History