dhcp-server: ddns: T6773: DDNS configuration documentation

docs/configuration/service/dhcp-server.rst

@@ -166,6 +166,187 @@ Unifi controller at ``172.16.100.1`` to clients of that subnet.
   '172.18.201.0/24' option vendor-option ubiquiti '172.16.100.1'
 
 
+Dynamic DNS Update (RFC 2136)
+-----------------------------
+
+VyOS DHCP service supports RFC-2136 DDNS protocol. Based on DHCP lease change
+events, DHCP server generates DDNS update requests (defines as NameChangeRequests
+or NCRs) and posts them to a compliant DNS server, that will update its name
+database accordingly.
+
+VyOS built-in DNS Forwarder does not support DDNS, you will need an external DNS
+server with RFC-2136 DDNS support.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update
+
+   Enables DDNS globally. 
+
+**Behavioral settings**
+
+These settings can be configured on the global level and overridden on the scope
+level, i.e. for individual shared networks or subnets. See examples below.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update send-updates [ enable
+   | disable ]
+
+   If set to ``enable`` on global level, updates for all scopes will be enabled,
+   except if explicitly set to ``disable`` on the scope level. If set to ``disable``,
+   updates will only be sent for scopes, where ``send-updates`` is explicity 
+   set to ``enable``.
+
+   This model is followed for a few behavioral settings below: if the option is 
+   not set, the setting is inherited from the parent scope. You can override the
+   parent scope setting by setting the option explicitly.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update force-update [ enable
+   | disable ]
+
+   VyOS will ignore client request not to update DNS records and send DDNS
+   update requests regardless.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update force-update-both [ enable
+   | disable ]
+
+   VyOS will override client DDNS request settings and always update both
+   forward and reverse DNS records.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update update-on-renew [ enable
+   | disable ]
+
+   Issue DDNS update requests on DHCP lease renew. In busy networks this may
+   generate a lot of traffic.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update conflict-resolution [ enable
+   | disable ]
+
+   Use RFC-4703 conflict resolution. This algorithm helps in situation when
+   multiple clients reserve same IP addresses or advertise identical hostnames.
+   Should be used in most situations.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update replace-client-name [ never
+   | always | when-present | when-not-present ]
+
+   * **never**: use the name sent by the client. If the client didn't provide any,
+     do not generate one. This is the default behavior
+
+   * **always**: always generate a name for the client
+
+   * **when-present**: replace the name the client sent with a generated one, if
+     the client didn't send any, do not generate one
+
+   * **when-not-present**: use the name sent by the client. If the client didn't
+     send any, generate one for the client
+
+   The names are generated using ``generated-prefix``, ``qualifying-suffix`` and the
+   client's IP address string.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update generated-prefix <prefix>
+
+   Prefix used in client name generation.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update qualifying-suffix <suffix>
+
+   DNS suffix used in client name generation.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update ttl-percent <0-100>
+
+   TTL of the DNS record as a percentage of the DHCP lease time.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update hostname-char-set
+   <character string>
+
+   Characters, that are considered invalid in the client name. They will be replaced
+   with ``hostname-char-replacement`` string.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update hostname-char-replacement
+   <character string>
+
+   Replacement string for the invalid characters defined by ``hostname-char-set``.
+
+**TSIG keys definition**
+
+This is the global list of TSIG keys for DDNS updates. They need to be specified by
+the name in the DNS domain definitions.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update tsig-key <key-name>
+   algorithm <algorithm>
+
+   Sets the algorithm for the TSIG key. Supported algorithms are ``hmac-md5``,
+   ``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, ``hmac-sha512``
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update tsig-key <key-name>
+   secret <key-secret>
+
+   base64-encoded TSIG key secret value
+
+**DNS domains definition**
+
+This is global configuration of DNS servers for the updatable forward and reverse 
+DNS domains. For every domain multiple DNS servers can be specified.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain
+   <domain-name> key-name <tsig-key-name>
+
+   TSIG key used for the domain.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain
+   <domain-name> dns-server <number> address <ip-address>
+
+   IP address of the DNS server.
+
+.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain
+   <domain-name> dns-server <number> port <port>
+
+   UDP port of the DNS server. ``53`` is the default.
+
+**Example:**
+
+Global configuration you will most likely want:
+
+.. code-block:: none
+
+  set service dhcp-server dynamic-dns-update send-updates enable
+  set service dhcp-server dynamic-dns-update conflict-resolution enable
+
+Override the above configuration for a shared network NET1:
+
+.. code-block:: none
+
+  set service dhcp-server shared-network-name 'NET1' dynamic-dns-update replace-client-name when-not-present
+  set service dhcp-server shared-network-name 'NET1' dynamic-dns-update generated-prefix ip
+  set service dhcp-server shared-network-name 'NET1' dynamic-dns-update qualifying-suffix mybigdomain.net
+
+And in a subnet within the same shared network:
+
+.. code-block:: none
+
+  set service dhcp-server shared-network-name 'NET1' subnet '172.18.201.0/24' dynamic-dns-update qualifying-suffix mydomain.net
+
+Configure TSIG keys:
+
+.. code-block:: none
+
+  set service dhcp-server dynamic-dns-update tsig-key mydomain-net algorithm hmac-sha256
+  set service dhcp-server dynamic-dns-update tsig-key mydomain-net secret eWF5YW15bGl0dGxla2V5IQ==
+  set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 algorithm hmac-sha256
+  set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 secret eWF5YW15YW5vdGhlcmxpdHRsZWtleSE=
+
+Configure DDNS domains:
+
+.. code-block:: none
+
+  set service dhcp-server dynamic-dns-update forward-domain mydomain.net key-name mydomain-net
+  set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 address '172.18.0.254'
+  set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 port 1053
+  set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 address '192.168.124.254'
+  set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 port 53
+  set service dhcp-server dynamic-dns-update forward-domain 201.18.172.in-addr.arpa key-name reverse-172-18-201
+  set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 address '172.18.0.254'
+  set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 port 1053
+  set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 address '192.168.124.254'
+  set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 port 53
+
+
 High Availability
 -----------------