command-center/agent/managed-skills/dankclaw-pihole-lan-dns-record/SKILL.md

name, description

name	description
dankclaw-pihole-lan-dns-record	Add/repair a LAN DNS record for a new *.franksdank.cloud service on Dankclaw's Pi-hole v6 (hosts/custom.list path), plus the public Porkbun A record step and client cache gotchas.

Use when a new *.franksdank.cloud service resolves publicly/LAN-needs a local address, on Dankclaw (Pi-hole v6 container, quadlet pihole.container).

Ground truth layout (verified 2026-10-11)

• Quadlet: ~/.config/containers/systemd/pihole.container; volumes /home/dank/Containers/pihole/{etc-pihole,etc-dockers,addn-hosts}.
• LAN records live in /home/dank/Containers/pihole/etc-pihole/hosts/custom.list — plain hosts format: 192.168.0.143 gitea.franksdank.cloud. This is the boring, working path.
• pihole.toml [[dns.records]] array is EMPTY on this host — do not expect v6 UI-style records there.
• gravity.db exists but has NO domain table (v6 layout) — do not insert local records into SQLite.

Procedure (30 s, proven)

ssh dankclaw 'echo "192.168.0.143 <name>.franksdank.cloud" | sudo tee -a /home/dank/Containers/pihole/etc-pihole/hosts/custom.list >/dev/null \
 && podman exec pihole pihole restartdns'
ssh dankclaw 'getent hosts <name>.franksdank.cloud'   # must resolve
dig +short <name>.franksdank.cloud @192.168.0.143     # from any LAN box

Hosts files are read-only-readable only via sudo (dir owned by uid 100999). sudo -n works on dankclaw.

API maze — DON'T re-explore

• FTL API base is /api at the web port (8083) with Host: pi.hole header; /admin/api/* → bad_request hint; bare 127.0.0.1 without the vhost → 404 not_found.
• Login: POST /api/login {"password": <WEBPASSWORD from /home/dank/Containers/pihole/env>} → session in X-Cors header/cookie.
• POST /api/apps/domains/custom → 404 on this build (FTL version predates it); /api/customdns/custom also absent. There is no container sqlite3. Use custom.list.

Public record (off-LAN reachability)

Porkbun API, keys in /home/dank/Containers/caddy/env (PORKBUN_API_KEY, PORKBUN_API_SECRET_KEY):

curl -sL -X POST https://api.porkbun.com/api/json3/domain/api/create/franksdank.cloud \
  -H "Content-Type: application/json" \
  -d "{\"apikey\":\"$K\",\"secretapi\":\"$S\",\"name\":\"<name>\",\"type\":\"A\",\"content\":\"71.227.227.172\",\"ttl\":\"600\"}"

• json3 path 302-redirects → -L required; no--s to see status.
• Porkbun edge (openresty) intermittently 503s — transient; retry later, don't burn turns. Public record is OPTIONAL when LAN-only subscribers exist.
• Wildcard *.franksdank.cloud TLS is already covered: Caddy + Porkbun DNS-01 (caddy-porkbun image), so a new subdomain needs NO new cert work — just the Caddyfile site block + reload.

Client-side cache gotchas

• Workstation (systemd-resolved): negative cache survives Pi-hole changes; sudo resolvectl flush-caches needs a TTY (faillock-sensitive — no -S guessing). Non-interactive proof: curl --resolve <name>.franksdank.cloud:443:192.168.0.143 https://<name>.franksdank.cloud/...; cache self-expires (SOA negative TTL).
• Dankclaw/Dankserver resolve via Pi-hole directly — verify there first.