1 Dynamic DNS Update (RFC2136)
2 ============================
4 Starting with the PowerDNS Authoritative Server 3.4.0, DNS update
5 support is available. There are a number of items NOT supported:
7 - There is no support for GSS\*TSIG and SIG (TSIG is supported);
8 - WKS records are specifically mentioned in the RFC, we don't
9 specifically care about WKS records;
10 - Anything we forgot....
12 The implementation requires the backend to support a number of new
13 operations. Currently, the following backends have been modified to
16 - :doc:`gmysql <backends/generic-mysql>`
17 - :doc:`gpgsql <backends/generic-postgresql>`
18 - :doc:`gsqlite3 <backends/generic-sqlite3>`
19 - :doc:`godbc <backends/generic-odbc>`
21 .. _dnsupdate-configuration-options:
26 There are two configuration parameters that can be used within the
27 powerdns configuration file.
32 A setting to enable/disable DNS update support completely. The default
33 is no, which means that DNS updates are ignored by PowerDNS (no message
34 is logged about this!). Change the setting to ``dnsupdate=yes`` to
35 enable DNS update support. Default is ``no``.
37 ``allow-dnsupdate-from``
38 ~~~~~~~~~~~~~~~~~~~~~~~~
40 A list of IP ranges that are allowed to perform updates on any domain.
41 The default is ``127.0.0.0/8``, which means that all loopback addresses are accepted.
42 Multiple entries can be used on this line
43 (``allow-dnsupdate-from=198.51.100.0/8 203.0.113.2/32``). The option can
44 be left empty to disallow everything, this then should be used in
45 combination with the ``ALLOW-DNSUPDATE-FROM`` :doc:`domain metadata <domainmetadata>` setting per
46 zone. Setting a range here and in ``ALLOW-DNSUPDATE-FROM`` enables updates
47 from either address range.
52 Tell PowerDNS to forward to the master server if the zone is configured
53 as slave. Masters are determined by the masters field in the domains
54 table. The default behaviour is enabled (yes), which means that it will
55 try to forward. In the processing of the update packet, the
56 ``allow-dnsupdate-from`` and ``TSIG-ALLOW-DNSUPDATE`` are processed
57 first, so those permissions apply before the ``forward-dnsupdate`` is
58 used. It will try all masters that you have configured until one is
61 .. _dnsupdate-lua-dnsupdate-policy-script:
63 ``lua-dnsupdate-policy-script``
64 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66 Use this Lua script containing function ``updatepolicy`` to validate
67 each update. This will ``TURN OFF`` all other
68 authorization methods, and you are expected to take care of everything
69 yourself. See :ref:`dnsupdate-update-policy` for details and
72 The semantics are that first a dynamic update has to be allowed either
73 by the global :ref:`setting-allow-dnsupdate-from` setting, or by a per-zone
74 ``ALLOW-DNSUPDATE-FROM`` metadata setting.
76 Secondly, if a zone has a ``TSIG-ALLOW-DNSUPDATE`` metadata setting, that
79 So to only allow dynamic DNS updates to a zone based on TSIG key, and
80 regardless of IP address, set :ref:`setting-allow-dnsupdate-from` to empty, set
81 ``ALLOW-DNSUPDATE-FROM`` to "0.0.0.0/0" and "::/0" and set the
82 ``TSIG-ALLOW-DNSUPDATE`` to the proper key name.
84 Further information can be found :ref:`below <dnsupdate-how-it-works>`.
86 .. _dnsupdate-metadata:
91 For permissions, a number of per zone settings are available via the
92 :doc:`domain metadata <domainmetadata>`.
94 .. _metadata-allow-dnsupdate-from:
99 This setting has the same function as described in the configuration
100 options (See :ref:`above <dnsupdate-configuration-options>`).
101 This will allow 198.51.100.0/8 and 203.0.113.2/32 to send DNS update
102 messages for the example.org domain::
104 pdnsutil set-meta example.org ALLOW-DNSUPDATE-FROM 198.51.100.0/8 203.0.113.2/32
106 .. _metadata-tsig-allow-dnsupdate:
111 This setting allows you to set the TSIG key required to do an DNS
112 update. If you have GSS-TSIG enabled, you can use Kerberos principals
113 here. An example, using :program:`pdnsutil` to create the key::
115 $ pdnsutil generate-tsig-key test hmac-md5
116 Create new TSIG key test hmac-md5 kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=
118 Then adding that key with the name `test` and add the metadata::
120 pdnsutil import-tsig-key test hmac-md5 'kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys='
121 pdnsutil set-meta example.org TSIG-ALLOW-DNSUPDATE test
123 An example of how to use a TSIG key with the :program:`nsupdate` command::
128 update add test1.example.org 3600 A 203.0.113.1
129 key test kp4/24gyYsEzbuTVJRUMoqGFmN3LYgVDzJ/3oRSP7ys=
133 If a TSIG key is set for the domain, it is required to be used for the
134 update. The TSIG is an alternative means of securing updates, instead of using the
135 ``ALLOW-DNSUPDATE-FROM`` setting. If a TSIG key is set, and if ``ALLOW-DNSUPDATE-FROM`` is set,
136 the IP(-range) of the updater still needs to be allowed via ``ALLOW-DNSUPDATE-FROM``.
138 .. _metadata-forward-dnsupdate:
143 See :ref:`Configuration options <dnsupdate-configuration-options>` for what it does,
146 pdnsutil set-meta example.org FORWARD-DNSUPDATE 'yes'
148 The existence of the entry (even with an empty value) enables the forwarding.
149 This domain-specific setting is only useful when the configuration
150 option :ref:`setting-forward-dnsupdate` is set to 'no', as that will disable it
151 globally. Using the domainmetadata setting than allows you to enable it
154 .. _metadata-notify-dnsupdate:
159 Send a notification to all slave servers after every update. This will
160 speed up the propagation of changes and is very useful for acme
163 pdnsutil set-meta example.org NOTIFY-DNSUPDATE 1
165 .. _metadata-soa-edit-dnsupdate:
170 This configures how the soa serial should be updated. See
171 :ref:`below <dnsupdate-soa-serial-updates>`.
173 .. _dnsupdate-soa-serial-updates:
178 After every update, the soa serial is updated as this is required by
179 section 3.7 of :rfc:`2136`. The behaviour is configurable via domainmetadata
180 with the ``SOA-EDIT-DNSUPDATE`` option. It has a number of options listed
181 below. If no behaviour is specified, DEFAULT is used.
183 :rfc:`2136, Section 3.6 <2136#section-3.6>` defines some specific behaviour for updates of SOA
184 records. Whenever the SOA record is updated via the update message, the
185 logic to change the SOA is not executed.
188 Powerdns will always use :ref:`metadata-soa-edit` when serving SOA
189 records, thus a query for the SOA record of the recently update domain,
190 might have an unexpected result due to a SOA-EDIT setting.
194 pdnsutil set-meta example.org SOA-EDIT-DNSUPDATE INCREASE
196 This will make the SOA Serial increase by one, for every successful
199 SOA-EDIT-DNSUPDATE settings
200 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
202 These are the settings available for **SOA-EDIT-DNSUPDATE**.
204 - DEFAULT: Generate a soa serial of YYYYMMDD01. If the current serial
205 is lower than the generated serial, use the generated serial. If the
206 current serial is higher or equal to the generated serial, increase
207 the current serial by 1.
208 - INCREASE: Increase the current serial by 1.
209 - EPOCH: Change the serial to the number of seconds since the EPOCH,
211 - SOA-EDIT: Change the serial to whatever SOA-EDIT would provide. See
212 :doc:`Domain metadata <domainmetadata>`
213 - SOA-EDIT-INCREASE: Change the serial to whatever SOA-EDIT would
214 provide. If what SOA-EDIT provides is lower than the current serial,
215 increase the current serial by 1.
216 Exception: with SOA-EDIT=INCEPTION-EPOCH, the serial is bumped to at
217 least the current EPOCH time.
219 DNS update How-to: Setup dyndns/rfc2136 with dhcpd
220 --------------------------------------------------
222 DNS update is often used with DHCP to automatically provide a hostname
223 whenever a new IP-address is assigned by the DHCP server. This section
224 describes how you can setup PowerDNS to receive DNS updates from ISC's
225 dhcpd (version 4.1.1-P1).
230 We're going to use a TSIG key for security. We're going to generate a
231 key using the following command:
233 .. code-block:: shell
235 dnssec-keygen -a hmac-md5 -b 128 -n USER dhcpdupdate
237 This generates two files (Kdhcpdupdate.*.key and
238 Kdhcpdupdate.*.private). You're interested in the .key file:
240 .. code-block:: shell
243 -rw------- 1 root root 53 Aug 26 19:29 Kdhcpdupdate.+157+20493.key
244 -rw------- 1 root root 165 Aug 26 19:29 Kdhcpdupdate.+157+20493.private
246 # cat Kdhcpdupdate.+157+20493.key
247 dhcpdupdate. IN KEY 0 3 157 FYhvwsW1ZtFZqWzsMpqhbg==
249 The important bits are the name of the key (**dhcpdupdate**) and the
250 hash of the key (**FYhvwsW1ZtFZqWzsMpqhbg==**
252 Using the details from the key you've just generated. Add the following
259 secret "FYhvwsW1ZtFZqWzsMpqhbg==";
262 You must also tell dhcpd that you want dynamic dns to work, add the
268 ddns-update-style interim;
269 update-static-leases on;
273 1. Enable Dynamic DNS
274 2. Which style it must use (interim)
275 3. Update static leases as well
277 For more information on this, consult the dhcpd.conf manual.
279 Per subnet, you also have to tell **dhcpd** which (reverse-)domain it
280 should update and on which master domain server it is running.
284 ddns-domainname "example.org";
285 ddns-rev-domainname "in-addr.arpa.";
292 zone 1.168.192.in-addr.arpa. {
297 This tells **dhcpd** a number of things:
299 1. Which domain to use (**ddns-domainname "example.org";**)
300 2. Which reverse-domain to use (**ddns-rev-domainname
302 3. For the zones, where the primary master is located (**primary
304 4. Which TSIG key to use (**key dhcpdupdate;**). We defined the key
307 This concludes the changes that are needed to the **dhcpd**
313 A number of small changes are needed to powerdns to make it accept
314 dynamic updates from **dhcpd**.
316 Enabled DNS update (:rfc:`2136`) support functionality in PowerDNS by adding
317 the following to the PowerDNS configuration file (pdns.conf).
322 allow-dnsupdate-from=
324 This tells PowerDNS to:
326 1. Enable DNS update support(:ref:`setting-dnsupdate`)
327 2. Allow updates from NO ip-address (":ref:`setting-allow-dnsupdate-from`\ =")
329 We just told powerdns (via the configuration file) that we accept
330 updates from nobody via the :ref:`setting-allow-dnsupdate-from`
331 parameter. That's not very useful, so we're going to give permissions
332 per zone (including the appropriate reverse zone), via the
333 domainmetadata table.
337 pdnsutil set-meta example.org ALLOW-DNSUPDATE-FROM 127.0.0.1
338 pdnsutil set-meta 1.168.192.in-addr.arpa ALLOW-DNSUPDATE-FROM 127.0.0.1
340 This gives the ip '127.0.0.1' access to send update messages. Make sure
341 you use the ip address of the machine that runs **dhcpd**.
343 Another thing we want to do, is add TSIG security. This can only be done
344 via the domainmetadata table:
348 pdnsutil import-tsig-key dhcpdupdate hmac-md5 FYhvwsW1ZtFZqWzsMpqhbg==
349 pdnsutil set-meta example.org TSIG-ALLOW-DNSUPDATE dhcpdupdate
350 pdnsutil set-meta 1.168.192.in-addr.arpa TSIG-ALLOW-DNSUPDATE dhcpdupdate
354 1. Add the 'dhcpdupdate' key to our PowerDNS installation
355 2. Associate the domains with the given TSIG key
357 Restart PowerDNS and you should be ready to go!
359 .. _dnsupdate-how-it-works:
364 This is a short description of how DNS update messages are processed by
367 1. The DNS update message is received. If it is TSIG signed, the TSIG
368 is validated against the tsigkeys table. If it is not valid, Refused
369 is returned to the requestor.
370 2. A check is performed on the zone to see if it is a valid zone.
371 ServFail is returned when not valid.
372 3. The **dnsupdate** setting is checked. Refused is returned when the
374 4. If update policy Lua script is provided then skip up to 7.
375 5. If the **ALLOW-DNSUPDATE-FROM** has a value (from both
376 domainmetadata and the configuration file), a check on the value is
377 performed. If the requestor (sender of the update message) does not
378 match the values in **ALLOW-DNSUPDATE-FROM**, Refused is returned.
379 6. If the message is TSIG signed, the TSIG keyname is compared with the
380 TSIG keyname in domainmetadata. If they do not match, a Refused is
381 send. The TSIG-ALLOW-DNSUPDATE domainmetadata setting is used to
382 find which key belongs to the domain.
383 7. The backends are queried to find the backend for the given domain.
384 8. If the domain is a slave domain, the **forward-dnsupdate** option
385 and domainmetadata settings are checked. If forwarding to a master
386 is enabled, the message is forward to the master. If that fails, the
387 next master is tried until all masters are tried. If all masters
388 fail, ServFail is returned. If a master succeeds, the result from
389 that master is returned.
390 9. A check is performed to make sure all updates/prerequisites are for
391 the given zone. NotZone is returned if this is not the case.
392 10. The transaction with the backend is started.
393 11. The prerequisite checks are performed (section 3.2 of :rfc:`2136 <2136#section-3.2>`). If a
394 check fails, the corresponding RCode is returned. No further
395 processing will happen.
396 12. Per record in the update message, a the prescan checks are
397 performed. If the prescan fails, the corresponding RCode is
398 returned. If the prescan for the record is correct, the actual
399 update/delete/modify of the record is performed. If the update fails
400 (for whatever reason), ServFail is returned. After changes to the
401 records have been applied, the ordername and auth flag are set to
402 make sure DNSSEC remains working. The cache for that record is
404 13. If there are records updated and the SOA record was not modified,
405 the SOA serial is updated. See :ref:`dnsupdate-soa-serial-updates`. The cache for this record is
407 14. The transaction with the backend is committed. If this fails,
408 ServFail is returned.
409 15. NoError is returned.
411 .. _dnsupdate-update-policy:
416 You can define a Lua script to handle DNS UPDATE message
417 authorization. The Lua script is to contain at least function called
418 ``updatepolicy`` which accepts one parameter. This parameter is an
419 object, containing all the information for the request. To permit
420 change, return true, otherwise return false. The script is called for
421 each record at a time and you can approve or reject any or all.
423 The object has following methods available:
425 - ``DNSName getQName()`` - name to update
426 - ``DNSName getZoneName()`` - zone name
427 - ``int getQType()`` - record type, it can be 255(ANY) for delete.
428 - ``ComboAddress getLocal()`` - local socket address
429 - ``ComboAddress getRemote()`` - remote socket address
430 - ``Netmask getRealRemote()`` - real remote address (or netmask if EDNS Subnet is used)
431 - ``DNSName getTsigName()`` - TSIG **key** name (you can assume it is validated here)
432 - ``string getPeerPrincipal()`` - Return peer principal name (``user@DOMAIN``,
433 ``service/machine.name@DOMAIN``, ``host/MACHINE$@DOMAIN``)
435 There are many same things available as in recursor Lua scripts, but
436 there is also ``resolve(qname, qtype)`` which returns array of records.
441 resolve("www.google.com", pdns.A)
443 You can use this to perform DNS lookups. If your resolver cannot find
444 your local records, then this will not find them either. In other words,
445 resolve does not perform local lookup.
447 Simple example script:
451 --- This script is not suitable for production use
453 function strpos (haystack, needle, offset)
454 local pattern = string.format("(%s)", needle)
455 local i = string.find (haystack, pattern, (offset or 0))
456 return (i ~= nil and i or false)
459 function updatepolicy(input)
460 princ = input:getPeerPrincipal()
467 if princ == "admin@DOMAIN" or input:getRemote():toString() == "192.168.1.1"
472 if (input:getQType() == pdns.A or input:getQType() == pdns.AAAA) and princ:sub(5,5) == '/' and strpos(princ, "@", 0) ~= false
474 i = strpos(princ, "@", 0)
475 if princ:sub(i) ~= "@DOMAIN"
479 hostname = princ:sub(6, i-1)
480 if input:getQName():toString() == hostname .. "." or input:getQName():toString() == hostname .. "." .. input:getZoneName():toString()
489 Additional updatepolicy example scripts can be found in our
490 `Wiki <https://github.com/PowerDNS/pdns/wiki/Lua-Examples-(Authoritative)>`__.