Initial VPS operations handbook

docs/pdns-upstream.md

@@ -0,0 +1,81 @@
+# PowerDNS Authoritative — upstream documentation
+
+Use these when changing `/opt/pdns` on [hk2](../hosts/hk2.chans.xyz.md). Prefer official docs over blog posts.
+
+## Primary references
+
+| Topic | URL |
+|-------|-----|
+| Settings reference | https://doc.powerdns.com/authoritative/settings.html |
+| Primary / secondary modes | https://doc.powerdns.com/authoritative/modes-of-operation.html |
+| Generic PostgreSQL backend | https://doc.powerdns.com/authoritative/backends/generic-postgresql.html |
+| DNSSEC ops + SOA-EDIT | https://doc.powerdns.com/authoritative/dnssec/operational.html |
+| DNSSEC advice | https://doc.powerdns.com/authoritative/dnssec/advice.html |
+| TSIG | https://doc.powerdns.com/authoritative/tsig.html |
+| HTTP API | https://doc.powerdns.com/authoritative/http-api/ |
+| Security advisories | https://doc.powerdns.com/authoritative/security-advisories/ |
+| Docker image (`pdns-auth-50`) | https://hub.docker.com/r/powerdns/pdns-auth-50 |
+
+## Settings we care about on hk2 (ns1)
+
+| Concern | Upstream guidance | Our notes (post-2026-08-01) |
+|---------|-------------------|-----------------------------|
+| Version | Track advisories; upgrade when Mandatory | Pinned **`powerdns/pdns-auth-50:5.0.6`** (clears 2026-06 + 2026-07) |
+| Primary | `primary=yes`; zones type MASTER/PRIMARY | Set; zones `windy.me` / `wsvc.info` / `chans.xyz` are Master |
+| NOTIFY | `also-notify` always notified; empty `only-notify` disables NS-based NOTIFY | `also-notify=202.91.35.141`, `only-notify=` |
+| AXFR IP ACL | `allow-axfr-ips` limits **unsigned** AXFR | Global + per-zone `ALLOW-AXFR-FROM` → ns2 only |
+| TSIG AXFR | **Any host with the TSIG key may AXFR**, bypassing IP ACL | Zones use `TSIG-ALLOW-AXFR=mykey.` — rotate/rename key; protect secret |
+| DNSSEC | `gpgsql-dnssec=yes` + keys via `pdnsutil` | CSK ECDSAP256SHA256 on all three zones |
+| SOA-EDIT | Needed so non-PDNS secondaries see signature rolls; PDNS secondaries can also compare RRSIGs | `default-soa-edit(-signed)=INCEPTION-INCREMENT` OK (ns2 is PowerDNS). Dig SOA ≠ backend serial is expected |
+| API key | Prefer `pdnsutil hash-password` (plaintext still accepted) | **Deferred hardening:** live key is weak, plaintext, reused with DB password — rotate |
+| Webserver | Prefer trusted clients only | Host publishes `127.0.0.1:8081`; `webserver-allow-from` private ranges |
+| `gpgsql-host` | Prefer IP to avoid resolve chicken/egg | `db` (Compose DNS) is fine inside the stack |
+| `domains.master` | Used for SECONDARY upstreams | Cleared on MASTER zones (was self-IP noise) |
+
+## Intended `auth/pdns.conf` shape (no secrets)
+
+Live file: `/opt/pdns/auth/pdns.conf`. Secrets come from `auth/templates.d/secrets.j2` → `/etc/powerdns/pdns.d/secrets.conf` at container start.
+
+```
+local-address=0.0.0.0
+local-port=53
+
+launch=gpgsql
+gpgsql-host=db
+gpgsql-dnssec=yes
+include-dir=/etc/powerdns/pdns.d
+
+allow-axfr-ips=202.91.35.141
+also-notify=202.91.35.141
+only-notify=
+primary=yes
+secondary=no
+
+api=yes
+webserver=yes
+webserver-address=0.0.0.0
+webserver-port=8081
+webserver-allow-from=127.0.0.1,172.16.0.0/12,10.0.0.0/8,192.168.0.0/16
+
+version-string=anonymous
+disable-syslog=yes
+loglevel=4
+
+default-soa-edit=INCEPTION-INCREMENT
+default-soa-edit-signed=INCEPTION-INCREMENT
+
+disable-axfr=no
+```
+
+Drop-in (from `.env`, never commit): `gpgsql-dbname`, `gpgsql-user`, `gpgsql-password`, `api-key`.
+
+## Deferred hardening (not done yet)
+
+1. Rotate `PDNS_API_KEY` to a long random value; store hashed via `pdnsutil hash-password` if desired; update Poweradmin `.env` / recreate `auth` + `poweradmin`.
+2. Rotate `DB_PASS` / Postgres role separately from the API key.
+3. Rotate TSIG `mykey` (or rename); confirm ns2 still AXFRs; remember TSIG bypasses `allow-axfr-ips`.
+
+## Related ops docs
+
+- Host facts: [hosts/hk2.chans.xyz.md](../hosts/hk2.chans.xyz.md)
+- Health runbook: [runbooks/pdns-health.md](../runbooks/pdns-health.md)