PowerDNS HTTP API

Lattice updates PowerDNS Authoritative after DHCP by PATCHing rrsets on the HTTP API. It does not speak the PowerDNS Recursor, and dhcpd never calls PowerDNS on the Ack path.

Adapter: powerdns_http.

Hub: integrations. BIND TSIG: bind-ddns. Why option 6 is not this API: dns-how.

Vendor documentation (setting names and zone JSON move between PowerDNS 4.x releases):

Our walkthrough is what Lattice sends after Ack. PowerDNS remains the source of truth for creating zones and enabling the API.

Just show me the steps — commands at the bottom, without the education.

1. What problem this solves

PowerDNS Auth stores zones (often in its own Postgres/MySQL/SQLite). Operators change records through the HTTP API (X-API-Key) or the web UI. Lattice is another API client: after Ack it REPLACE/DELETEs the A/AAAA/PTR for that lease.

That is the same role as TSIG against BIND, with a different wire: HTTPS (or HTTP on a private network) instead of RFC 2136.

Clients still query PowerDNS Auth (or a recursor in front) via DHCP option 6. The API URL is only for the worker.

Auth vs Recursor

Pointing powerdns_url at a recursor API (if any) will not update your zones.

2. Why an API key

The PowerDNS Auth API is powerful (create zones, wipe rrsets). Lattice only needs to PATCH records in zones you already created. Use a key you would give an automation user, not a shared default, in production.

Lattice stores powerdns_token_ref (env:LATTICE_POWERDNS_API_KEY or file:/etc/lattice/pdns.api-key). The API never returns the key after create. Mode 0600 on file/env.

3. What you must create in PowerDNS first

Lattice does not create zones. In pdnsutil, the API, or the UI:

1. Forward zone, e.g. office.example.com.
2. Reverse zone for each DHCP subnet, e.g. 20.20.10.in-addr.arpa.
3. SOA/NS that already match how you serve the zone
4. API enabled. Current docs use api=yes and api-key=… in pdns.conf (and the webserver must be up — default listen is 127.0.0.1:8081). Confirm against PowerDNS’s enable-API page for your version.

Confirm with:

curl -s -H "X-API-Key: $PDNS_KEY" \
  http://pdns.example.com:8081/api/v1/servers/localhost/zones/office.example.com.

You should see the zone JSON, not 404. A 404 here is a Lattice outbox failure later.

4. What Lattice sends

PATCH /api/v1/servers/localhost/zones/{zone}. with header X-API-Key.

Idempotent: repeating REPLACE is safe. Failures retry via the outbox; the lease is not rolled back.

The worker uses powerdns_url on the dns_server row (or LATTICE_POWERDNS_URL if the row has no URL).

5. Point Lattice at PowerDNS

Console More → DDNS adapters:

{
  "adapter": "powerdns_http",
  "name": "pdns",
  "powerdns_url": "https://pdns.example.com:8081",
  "powerdns_token_ref": "env:LATTICE_POWERDNS_API_KEY"
}

Production: HTTPS, not http://, unless worker and Auth share a private network you accept. Webhook-style URL rules do not apply here; still do not point this at a public recursor.

Subnet: DDNS on, adapter pdns, forward/reverse names exactly as PowerDNS knows them (usually with the same labels you used in the API, without inventing a new suffix).

Option 6: the addresses clients already use to query DNS (Auth VIP or recursor), not the :8081 API.

Firewall: worker → API port. dhcpd does not need it. HA: every worker host.

6. Troubleshooting

Just the steps

Confirm api= / listen address on PowerDNS’s HTTP API page for your version.

1. In Authoritative (not the Recursor): create the forward zone and each reverse zone. Enable the API (api=yes, api-key=…; webserver default 127.0.0.1:8081).
2. Prove the zone:

curl -s -H "X-API-Key: $PDNS_KEY" \
  http://pdns.example.com:8081/api/v1/servers/localhost/zones/office.example.com.

3. Put the API key on each worker (0600). Console More → DDNS adapters: powerdns_http, URL = Auth API (HTTPS in production), token ref env:LATTICE_POWERDNS_API_KEY or file:….
4. Subnet: DDNS on, that adapter, forward/reverse names exactly as PowerDNS has them. Option 6 is the query path (Auth VIP or recursor), not :8081.