RFC 2136 dynamic DNS (AXFR + DDNS)
AXFR/DDNS TSIG key setup: authorize one dedicated TSIG key to transfer each listed zone with AXFR and update it with RFC 2136 over TCP 53.
On this page
AXFR/DDNS TSIG key permissions
- Credential type
- TSIG key
- Preview access
- TSIG-authenticated AXFR for every listed zone
- Apply access
- TSIG-authenticated RFC 2136 updates for every listed zone
- API endpoint
- You provide a public API endpoint.
Additional access
DNSControl id
{
"TYPE": "AXFRDDNS"
}Create credentials
Authorize one dedicated TSIG key to transfer each listed zone with AXFR and update it with RFC 2136 over TCP 53.
Access you'll grant
TSIG-authenticated AXFR for every listed zone
TSIG-authenticated RFC 2136 updates for every listed zone
Before you start
- Each zone already exists as a primary zone on a DNS server that supports TSIG, AXFR, and RFC 2136 dynamic update.
- Configuration access to the primary and permission to allow our egress IP through its firewall on TCP port 53.
Setup steps
0 of 7 done
Generate a dedicated TSIG key
Run
tsig-keygenon the BIND primary and save its completekeyblock in a root-readable file. The default adapter algorithm ishmac-sha256.Generate keytsig-keygen -a hmac-sha256 dnsmigratorLoad the key securely
Put the generated block in
/etc/bind/keys/dnsmigrator.key, restrict the file to the BIND service, and include it fromnamed.conf. Copy the exactsecretvalue later without the surrounding quotes.Include the keyinclude "/etc/bind/keys/dnsmigrator.key";Protect the filechown root:bind /etc/bind/keys/dnsmigrator.key && chmod 0640 /etc/bind/keys/dnsmigrator.keyGrant zone transfers
Add allow-transfer to every managed primary-zone block. The quoted identity must exactly match the generated key name, including its trailing dot when present.
BIND zone optionallow-transfer { key "dnsmigrator."; };Grant dynamic updates
Add update-policy to every managed primary-zone block.
zonesub ANYpermits records at the zone apex and below it; narrowANYif your migration excludes record types. update-policy and allow-update cannot coexist in the same zone.BIND update policyupdate-policy { grant "dnsmigrator." zonesub ANY; };Validate and reload BIND
Validate the full configuration before reloading it. Resolve any
named-checkconferror instead of restarting with an untested policy.Validatenamed-checkconfReloadrndc reconfigAllow TCP 53 from DNSMigrator
Allow
our egress IPto reach the update primary and, when different, the transfer server on TCP port 53. DNSMigrator connects from its servers over the public Internet and uses TCP for both AXFR and RFC 2136. Its guard rejects private, loopback, link-local, CGNAT, metadata, documentation/reserved, and other non-public addresses, validates every DNS answer, and pins one validated IP.Required flowour egress IP → primary:53/tcpEnter the servers, zones, and key
Set Primary server to the RFC 2136 target. Set Transfer server only when AXFR comes from another host. List every zone, then paste the key identity and Base64 secret. Checking access performs a real AXFR and a no-change update against the first zone.
Zone listexample.com example.net
Troubleshooting
AXFR returns REFUSED or the connection closes
Confirm the first zone is primary on the transfer server, allow-transfer names the exact key, and our egress IP can reach TCP 53. BIND denies transfers by default when allow-transfer is omitted.
The empty update returns NOTAUTH or REFUSED
Send updates to the actual primary and add the TSIG identity to that zone's update-policy. A secondary can serve AXFR but cannot accept primary updates.
BADSIG, BADKEY, or BADTIME
Match key name, algorithm, and Base64 secret byte-for-byte on both sides. For BADTIME, synchronize both clocks with NTP.
One zone works but another fails
The connection check exercises only the first listed zone. Verify allow-transfer and update-policy in every zone block with dig AXFR and nsupdate before applying.
Official documentation
Guide checked against the official documentation on .
Credential fields
| Field | Requirement | Where to find it |
|---|---|---|
| Primary serverserver | Required | Public hostname or IP of the RFC 2136 update primary. DNSMigrator connects over TCP port 53. |
| Transfer servertransferServer | Optional | Optional public AXFR source. Leave empty to transfer from the Primary server; it still uses TCP port 53. |
| Zoneszones | Required | One pre-existing primary zone per line (commas and whitespace are also accepted). Put a safe test zone first. |
| TSIG key namekeyName | Required | Exact TSIG identity from the key declaration, commonly dnsmigrator. Preserve the trailing dot. |
| TSIG algorithmkeyAlgorithm | Optional | The algorithm in the server's key declaration. Leave empty for hmac-sha256; legacy SHA-1 and MD5 choices should be avoided. |
| TSIG secretkeySecret | Required | Base64 TSIG secret without quotes. The same key is used for both AXFR and RFC 2136 updates. |
| Nameserversnameservers | Optional | Optional comma-separated authoritative nameservers for registrar guidance. If empty, DNSMigrator uses the zone's NS records. |
Capabilities
- Create zones
- No
- List zones
- No
- DNSSEC
- Not available through this connection
- Minimum TTL
- 0 seconds
- Apex CNAME
- No
- Read only
- No
Record types
- A
- AAAA
- CNAME
- MX
- TXT
- NS
- SRV
- CAA
- PTR
- DS
- TLSA
- SSHFP
- NAPTR
- SPF
- URI
- DNAME
- OPENPGPKEY
- SMIMEA
- DHCID
- RP
- HTTPS
- SVCB
Caveats
- We reach the primary only over TCP port 53 at a public address; servers on private networks must expose port 53 publicly and allow our egress IPs.
- Zones can't be listed or created over DNS: list them in the connection and create them on the server first.
- Records of types we can't encode (e.g. LOC, CERT) and DNSSEC records are skipped when reading; signing stays with the server.
Troubleshooting
- AXFR returns REFUSED or the connection closes
- Confirm the first zone is primary on the transfer server, allow-transfer names the exact key, and {egressIp} can reach TCP 53. BIND denies transfers by default when allow-transfer is omitted.
- The empty update returns NOTAUTH or REFUSED
- Send updates to the actual primary and add the TSIG identity to that zone's update-policy. A secondary can serve AXFR but cannot accept primary updates.
- BADSIG, BADKEY, or BADTIME
- Match key name, algorithm, and Base64 secret byte-for-byte on both sides. For BADTIME, synchronize both clocks with NTP.
- One zone works but another fails
- The connection check exercises only the first listed zone. Verify allow-transfer and update-policy in every zone block with dig AXFR and nsupdate before applying.