DNS update

CLI reference:/tool/dns-update

The /tool/dns-update command sends one dynamic update (RFC 2136) to the authoritative DNS server of a zone and points a name in that zone at an IPv4 address. The update is signed with a TSIG key (RFC 8945), so the server can check that it comes from you, as in a secure dynamic update (RFC 3007). Use it for a zone that you run yourself, for example on a BIND server.

You do not need this command in two common cases:

• For a name that follows the router's own public address without running a DNS server, use the DDNS service of IP Cloud.
• Dynamic DNS services that take updates over HTTP, such as DynDNS, are updated with Fetch instead.

Prerequisites

• A DNS server that is authoritative for the zone and accepts dynamic updates over TCP port 53.
• A TSIG key that the server accepts for updates of the zone, with the algorithm hmac-md5. RouterOS signs with hmac-md5 only; the command has no algorithm setting.
• The name of the key and its secret in base64, as configured on the server. For example on BIND, create the key with tsig-keygen -a hmac-md5 dns-update-key, because BIND creates keys with another algorithm by default, and allow this key to update only the name it needs (update-policy).
• A router clock that differs from the server's clock by less than 5 minutes. The signature allows 300 seconds of difference, so keep the clock synchronized with NTP.
• A firewall on the server side that accepts TCP port 53 from the router.

Point a name at an address

Point office.example.com at 198.51.100.20 on the DNS server 192.0.2.53, with the key dns-update-key. Replace the key with the base64 secret of your key, and keep the quotes, because a base64 value can end in =:

/tool/dns-update dns-server=192.0.2.53 zone=example.com \
    name=office address=198.51.100.20 ttl=300 \
    key-name=dns-update-key key="c2VjcmV0LWtleS1mb3ItZXhhbXBsZQ=="

ttl=300 keeps the record for 5 minutes in the caches of other DNS servers, so they pick up a changed address soon. Without ttl, the record gets one day.

When the server accepts the update, the command prints nothing. When it does not, the command stops with a failure: message; the Troubleshoot section lists what each one means.

How the parameters work:

• name is relative to zone: name=office with zone=example.com updates office.example.com. A full name is doubled: name=office.example.com updates office.example.com.example.com. A name with a trailing dot is refused with failure: bad name.
• The update first deletes all A records of the name and then adds the new one, so it replaces the address instead of adding a second one.
• ttl sets the time to live of the record in seconds. Without ttl, the record gets 86400 seconds (one day), which is long for an address that changes.
• address takes one IPv4 address. Two addresses fail with failure: only one address allowed, and an IPv6 address is refused. The command updates A records only.

Keep the name current

The command sends one update each time it runs. To keep a name pointing at an address that changes, run it from a script when the address changes, for example from the lease script of the DHCP client on the WAN interface, or regularly from a scheduler entry. The script reads the current address, removes the prefix length (see Strip netmask), and passes the address to /tool/dns-update.

Things to keep in mind for such a script:

• Each update changes the zone on the server. Compare the address with the address the name has now (:resolve), and send the update only when it differs.
• At startup, wait until NTP has synchronized the clock, so that the server accepts the signature.
• Behind NAT or carrier-grade NAT, the address on the WAN interface is not the public one. The router's public address is in public-address of IP Cloud.
• The key is part of the command, so every user who can read the script can read the key.

Troubleshoot

Message	Meaning
failure: update send failed	The router could not open a TCP connection to port 53 of the server: the server is down, does not listen on TCP, or a firewall blocks it.
failure: reply not signed	The server rejected the signature, for example because the key name or the key is wrong.
failure: refused	The server refuses the update, for example because the key has no permission to update this zone, or because the update was sent without a key.
failure: name not within zone	The name is not in the zone. Check zone and name.
failure: bad name	name is not valid, for example because it ends with a dot.

Technical details

Protocol

The update goes to TCP port 53 of dns-server. The message is a DNS UPDATE for the zone (zone section example.com. IN SOA). Its update section deletes the A records of the name (office.example.com. ANY A) and adds the new record (office.example.com. 86400 IN A 198.51.100.20).

Signature

With key-name and key, the message carries a TSIG record with the algorithm hmac-md5.sig-alg.reg.int and a fudge of 300 seconds, the allowed clock difference. key is the base64 secret of the key. Without key-name and key, the update is sent unsigned, and most servers refuse it.

For all parameters, see the /tool/dns-update CLI reference.