Merge pull request #1561 from abukharov/feature/dhcp-ddns

dhcp-server: ddns: T6773: DDNS configuration documentation

Author: dmbaturin

docs/configuration/service/dhcp-server.rst

@@ -49,15 +49,15 @@ Configuration
    Inform client that the DNS server can be found at `<address>`.
 
    This is the configuration parameter for the entire shared network definition.
-   All subnets will inherit this configuration item if not specified locally. 
+   All subnets will inherit this configuration item if not specified locally.
    Multiple DNS servers can be defined.
 
-.. cfgcmd:: set service dhcp-server shared-network-name <name> option 
+.. cfgcmd:: set service dhcp-server shared-network-name <name> option
    vendor-option <option-name>
 
-   This configuration parameter lets you specify a vendor-option for the 
-   entire shared network definition. All subnets will inherit this 
-   configuration item if not specified locally. An example for Ubiquiti is 
+   This configuration parameter lets you specify a vendor-option for the
+   entire shared network definition. All subnets will inherit this
+   configuration item if not specified locally. An example for Ubiquiti is
    shown below:
 
 **Example:**
@@ -66,14 +66,14 @@ Pass address of Unifi controller at ``172.16.100.1`` to all clients of ``NET1``
 
 .. code-block:: none
 
-  set service dhcp-server shared-network-name 'NET1' option vendor-option  
+  set service dhcp-server shared-network-name 'NET1' option vendor-option
   ubiquiti '172.16.100.1'
 
 .. cfgcmd:: set service dhcp-server listen-address <address>
 
-   This configuration parameter lets the DHCP server to listen for DHCP 
-   requests sent to the specified address, it is only realistically useful for 
-   a server whose only clients are reached via unicasts, such as via DHCP relay 
+   This configuration parameter lets the DHCP server to listen for DHCP
+   requests sent to the specified address, it is only realistically useful for
+   a server whose only clients are reached via unicasts, such as via DHCP relay
    agents.
 
 Individual Client Subnet
@@ -148,24 +148,205 @@ Individual Client Subnet
    request where no full FQDN is passed. This option can be given multiple times
    if you need multiple search domains (DHCP Option 119).
 
-.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> 
+.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet>
    option vendor-option <option-name>
 
    This configuration parameter lets you specify a vendor-option for the
-   subnet specified within the shared network definition. An example for  
+   subnet specified within the shared network definition. An example for
    Ubiquiti is shown below:
 
 **Example:**
 
-Create ``172.18.201.0/24`` as a subnet within ``NET1`` and pass address of  
+Create ``172.18.201.0/24`` as a subnet within ``NET1`` and pass address of
 Unifi controller at ``172.16.100.1`` to clients of that subnet.
 
 .. code-block:: none
 
-  set service dhcp-server shared-network-name 'NET1' subnet 
+  set service dhcp-server shared-network-name 'NET1' 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 override-no-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 override-client-update [ 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
 -----------------
 
@@ -645,7 +826,7 @@ used:
 
 
 .. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet
-   <prefix> prefix-delegation prefix <pd-prefix> excluded-prefix-length <length> 
+   <prefix> prefix-delegation prefix <pd-prefix> excluded-prefix-length <length>
 
    Define lenght of exclude prefix in `<pd-prefix>`.