Skip to content
Hayami Docs

Dynamic DNS registration

DTM accepts standard RFC 2136 dynamic updates, so hosts, DHCP servers, and any tooling that speaks nsupdate can register and refresh their own records in a DTM zone, authenticated with TSIG. This page is the generic workflow; the AKS ExternalDNS recipe and Active Directory coexistence build on the same mechanics for their specific audiences. The setup steps send a bearer token as $DTM_TOKEN; the API overview shows how to capture one.

Updates can create and modify A, AAAA, CNAME, MX, SRV, CAA, TXT, PTR, and NS records. The target zone must already exist and be Active, and every name in an update must sit inside that zone; standard RFC 2136 prerequisites (“name exists”, “record does not exist”, and so on) are honoured with the usual response codes.

1. Enable dynamic updates, requiring TSIG

Section titled “1. Enable dynamic updates, requiring TSIG”

Dynamic updates are off by default, and the setting is per node: enable it on every node that will receive RFC 2136 updates, either by repeating the API call below against each node’s endpoint or with one dtm_dynamic_dns_config Terraform resource per provider endpoint. A node where updates were not enabled answers UPDATE with REFUSED. (The UI’s Settings page manages the TSIG keys the updates authenticate with, not the enablement itself.)

Terminal window
curl -sk -X PUT https://dtm.internal:8443/api/v1/config/dynamic-dns \
  -H "Authorization: Bearer $DTM_TOKEN" \
  -H "X-DTM-CSRF: 1" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "require_tsig": true }'

2. Create a TSIG key and bind it to the zone

Section titled “2. Create a TSIG key and bind it to the zone”

Generate a strong secret and bind the key to the zone(s) it may update:

Terminal window
SECRET=$(openssl rand -base64 32)


curl -sk -X POST https://dtm.internal:8443/api/v1/tsig-keys \
  -H "Authorization: Bearer $DTM_TOKEN" \
  -H "X-DTM-CSRF: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "host-reg",
    "algorithm": "hmac-sha256",
    "secret": "'"$SECRET"'",
    "zone_ids": ["<zone-id>"]
  }'
  • Accepted algorithms are hmac-sha256, hmac-sha384, and hmac-sha512 (hmac-md5 and hmac-sha1 are refused). Minimum secret length is per-algorithm: 128 bits for hmac-sha256, 192 for hmac-sha384, and 256 for hmac-sha512; the openssl rand -base64 32 example (256 bits) satisfies all three.
  • A key is only authorized for the zones in its zone_ids; an update signed with the right key against the wrong zone is refused.
  • Key names match with or without a trailing dot, so keys created by standard tooling interoperate.
  • To rotate later, PUT /api/v1/tsig-keys/host-reg with a new secret; omitting zone_ids keeps the existing bindings.

3. Register from a host

Section titled “3. Register from a host”

Any RFC 2136 client works. With nsupdate (from bind9-dnsutils):

Terminal window
nsupdate -y "hmac-sha256:host-reg:$SECRET" <<'EOF'
server 10.0.0.4
zone corp.internal.
update delete web01.corp.internal. A
update add web01.corp.internal. 300 A 10.1.2.34
send
EOF

The delete-then-add pair is the conventional “set this name to exactly this address” idiom; a plain update add appends a value alongside existing ones.

4. Point a DHCP server at DTM

Section titled “4. Point a DHCP server at DTM”

DHCP servers register leases through the same standard mechanism (DDNS). Give the DHCP server the TSIG key and, as the zone’s server, a DTM node where dynamic updates were enabled in step 1 (the setting is per node), exactly as you would against any RFC 2136-capable DNS server; ISC Kea and dhcpd both support DDNS with TSIG out of the box. Two DTM-side notes:

  • Bind the DHCP server’s key to both the forward zone and the matching reverse zone if it registers PTR records.
  • Every renewal-driven re-registration counts as a refresh, even when the address has not changed, which is what keeps records alive under scavenging below.

5. Verify

Section titled “5. Verify”
Terminal window
dig @10.0.0.4 web01.corp.internal +short

Signed updates also land in the audit log attributed to the TSIG key, so the Audit Log page shows who registered what.

Scavenging stale records

Section titled “Scavenging stale records”

Hosts that disappear without deregistering leave stale records behind. DTM’s scavenger removes dynamic records only (records created via RFC 2136; records you created through the API, UI, or Terraform are never scavenged) once they have gone unrefreshed for longer than a configured age. Any dynamic update to a record, including an identical-value DHCP renewal, resets its age.

Scavenging is off by default and is configured in the server configuration file (it is deliberately not settable through the API or Terraform):

dynamic_dns:
  enabled: true
  require_tsig: true
  scavenge_max_age: 172800 # seconds; 0 (default) disables scavenging
  scavenge_interval: 3600 # seconds between sweeps; default 3600

Choose scavenge_max_age relative to your DHCP lease time: it must be comfortably longer than the renewal interval, or the scavenger will delete records for hosts that are still alive. A common starting point is at least twice the DHCP lease duration (for example two days for a one-day lease). Edit the file on each node and restart the service one node at a time; the keys and apply procedure are in the configuration reference.

Next steps

Section titled “Next steps”
Privacy policyTerms of use