RFC 2136 (Dynamic DNS)

Use RFC 2136 dynamic update to let CertAutoPilot add and remove the _acme-challenge TXT record on a DNS server you host yourself — BIND, PowerDNS, Knot, or a Windows DNS Server — instead of a cloud DNS API.

This is the answer to "my authoritative DNS is my own server; how do you write the challenge record?" You enable dynamic updates on the zone and point CertAutoPilot at the server.

How it works

For every DNS-01 challenge the worker sends a standard DNS UPDATE message (RFC 2136) to your DNS server: Present adds TXT _acme-challenge.<name>, the CA validates it, then CleanUp deletes it. Fully automatic on every renewal — no manual DNS edits.

Choose an authentication mode

Pick the Auth mode in the credential form; fill only that mode's fields.

Mode	Fields	Use when	Security
TSIG (shared key)	nameserver + tsig_key + tsig_secret (+ algorithm)	BIND / PowerDNS / Knot and other RFC 2845 servers	Good — HMAC-signed
GSS-TSIG	nameserver + the tsig_gss_* fields	Windows AD-integrated zone ("Secure only")	Best on Windows — Kerberos, ties to an AD account
Nonsecure	nameserver only	A zone explicitly set to accept unsigned updates	Weak — firewall + a dedicated zone

:::warning Windows DNS does not do plain TSIG Windows DNS Server does not implement RFC 2845 shared-key TSIG for dynamic updates. On Windows use GSS-TSIG (for "Secure only" zones) or Nonsecure. Plain TSIG is for BIND/PowerDNS/etc. If you'd rather not set up Kerberos on the CertAutoPilot host, use the Windows DNS (WinRM) provider instead — it writes the record over WinRM/PowerShell with no TSIG or Kerberos. :::

What is TSIG / GSS-TSIG?

TSIG (RFC 2845) authenticates a DNS UPDATE by signing it with a shared secret key (an HMAC); the server only accepts updates carrying a valid signature. This is what BIND and most non-Windows servers use.

GSS-TSIG (RFC 3645) is the same idea but the key is negotiated via Kerberos instead of a pre-shared secret — this is what Windows calls "secure dynamic update": the client authenticates as an Active Directory account and the DNS server checks its permission. No static secret to distribute.

Nonsecure means no signature — the server accepts any well-formed UPDATE. Only safe on an isolated/firewalled network.

TSIG setup (BIND / PowerDNS / …)

Generate a key and grant it update rights on the zone:

tsig-keygen -a hmac-sha256 acme-update. > acme.key

# named.conf
key "acme-update." { algorithm hmac-sha256; secret "BASE64SECRET=="; };
zone "example.com" {
    type primary;
    file "example.com.zone";
    update-policy { grant acme-update. name _acme-challenge.example.com. TXT; };
};

In the credential form choose Auth mode = TSIG and enter tsig_key = acme-update., tsig_secret = BASE64SECRET==, and the matching Algorithm (the one you passed to tsig-keygen -a, e.g. HMAC-SHA256). The algorithm must match the key — pick it from the dropdown.

GSS-TSIG setup (Windows secure dynamic update)

For a Windows AD-integrated "Secure only" zone. Uses an AD account's username + password — the CertAutoPilot host does not need to be domain-joined.

1. In DNS Manager keep the zone at Secure only. Grant an AD service account (e.g. svc-acme) Write on the zone (zone → Security tab), or delegate a _acme-challenge.<domain> sub-zone and grant it only there.
2. In the credential form choose Auth mode = GSS-TSIG and enter the Realm (AD domain, UPPERCASE), Username, Password.
3. On the Linux host running CertAutoPilot, provide a minimal /etc/krb5.conf (Kerberos is pure-Go here — no libgssapi/cgo needed):

   [libdefaults]
       default_realm = CORP.EXAMPLE.COM
       dns_lookup_kdc = true
   [realms]
       CORP.EXAMPLE.COM = { kdc = dc1.corp.example.com }

   Requirements: the host can reach a KDC (domain controller) on port 88, clock skew < 5 min with the DC, and the account can update the zone. No domain-join.

:::tip Prefer WinRM if Kerberos is inconvenient If setting up krb5.conf / KDC access on the Linux host is undesirable, the Windows DNS (WinRM) provider achieves the same result over your existing WinRM admin access — no Kerberos at all. :::

Enable dynamic updates on a Windows zone

DNS Manager → zone → Properties → General → Dynamic updates:

• Secure only — AD-integrated zones. Use GSS-TSIG.
• Nonsecure and secure — allows unsigned updates. Use Nonsecure mode, and only with the hardening below.
• None — disabled; RFC 2136 cannot work.

PowerShell: Set-DnsServerPrimaryZone -Name "example.com" -DynamicUpdate "Secure" (or "NonsecureAndSecure").

Add the credential

1. Settings → DNS Credentials → New → RFC 2136 (Dynamic DNS).
2. Nameserver — the DNS server as host:port, e.g. 10.0.0.5:53.
3. Auth mode — Nonsecure / TSIG / GSS-TSIG, then fill that mode's fields.
4. Test connectivity → Save.

Config fields

Field	Mode	Purpose
nameserver	all	DNS server accepting updates, as host:port.
tsig_key	TSIG	TSIG key name (e.g. acme-update.).
tsig_secret	TSIG	Base64 TSIG secret.
tsig_algorithm	TSIG	Pick to match your key (default hmac-sha256.).
tsig_gss_realm	GSS-TSIG	Kerberos realm, e.g. CORP.EXAMPLE.COM.
tsig_gss_username	GSS-TSIG	AD account allowed to update the zone.
tsig_gss_password	GSS-TSIG	That account's password.

Secrets (tsig_secret, tsig_gss_password) are encrypted at rest and never returned by the API.

Security hardening

• Prefer TSIG or GSS-TSIG over nonsecure. If you must use nonsecure, firewall port 53 to the worker IPs.
• Delegate a challenge-only sub-zone and grant update rights only there — never on your production zone.
• Least-privilege: the key / AD account should be able to write only TXT _acme-challenge.*.

Propagation

The record is written straight onto the authoritative server, so propagation is near-instant. If the zone is replicated across DCs/secondaries, set the propagation nameserver override to the server you update. See Propagation settings.

Troubleshooting

• "bad signature" / NOTAUTH — TSIG key name/secret/algorithm mismatch (must match the server's key exactly), or a plain-TSIG update sent to a Windows "Secure only" zone (use GSS-TSIG or WinRM).
• "REFUSED" — dynamic updates not enabled on the zone, or the mode doesn't match ("Secure only" needs GSS-TSIG), or the key/account lacks write permission.
• GSS-TSIG can't get a ticket — the host can't reach the KDC (port 88), krb5.conf realm wrong, or clock skew > 5 min.
• Timeout — firewall blocking UDP/TCP 53, or the wrong nameserver host:port.

See also

• Windows DNS (WinRM) — Windows secure zones without Kerberos
• DNS providers overview
• Manual DNS