vps/docs/pdns-upstream.md

PowerDNS Authoritative — upstream documentation

Use these when changing /opt/pdns on hk2. 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
• Health runbook: runbooks/pdns-health.md