Skip to main content
Two small HTTP protocols that clients already speak, so they can change records in DNZ with an API token:
  • httpreq, lego’s protocol for ACME DNS-01 challenges, also used by Traefik and easy to call from a certbot hook;
  • DynDNS2, the dynamic DNS protocol of routers (MikroTik, OpenWrt, pfSense, Ubiquiti), ddclient and inadyn.
This page is the reference. For step-by-step client setup, see ACME certificates and Dynamic DNS.
DHCP servers, ExternalDNS and nsupdate can use standard DNS UPDATE messages (RFC 2136) with a TSIG key instead of a token. See Dynamic updates.

​
ACME DNS-01 (httpreq)

Both endpoints need an API token with records.write, preferably limited to the zones that need certificates. A signed-in session isn’t accepted. Authenticate with a Bearer token, or with HTTP Basic and the token as the password (any username), which is what lego and Traefik send.

​
Request body

​
string
required
The challenge name, e.g. _acme-challenge.example.com.. It must start with _acme-challenge..
​
string
required
The challenge value (the key authorization digest).
The answer is {"ok": true}.

​
What DNZ does

  • present creates a TXT record with a TTL of 60 in the matching zone: the most specific zone of the token’s division that the token can reach. Sending the same value twice doesn’t add a second record.
  • cleanup deletes that TXT record again.
  • Both changes are written to the audit log as <creator> via <token name>.
A name outside every zone the token can reach answers 400.
For the CA to verify the challenge, the zone must be delegated to DNZ (DNZ is its public nameserver), or _acme-challenge in public DNS must be a CNAME to a name DNZ serves. A record that only exists in an internal DNZ is invisible to Let’s Encrypt.

​
Client settings

lego and Traefik take the endpoint and token from their environment:
Full examples for lego, Traefik and certbot are in ACME certificates.

​
Dynamic DNS (DynDNS2)

Create a token with records.write, preferably limited to the zone that holds the hostname, and send it as the HTTP Basic password (any username):

​
Query parameters

​
string
required
One or more names, comma-separated, in zones the token can reach. At most 20 per request.
​
string
IPv4 and/or IPv6 addresses, comma-separated. When empty, the caller’s address is used. Behind a reverse proxy, set DNZ_TRUSTED_PROXIES so DNZ sees the real address.

​
What DNZ does

  • The name’s A and AAAA records are replaced with the new addresses. Only the address families you send change: an IPv4 address replaces the A records and leaves AAAA alone.
  • New records get a TTL of 60.
  • Names that have a CNAME are refused.
  • A proxied name stays behind its proxies; the new address becomes the origin.

​
Answers

The answer is plain text, one line per hostname:

​
Example

Configurations for ddclient, MikroTik and other clients are in Dynamic DNS.