From 8b9a3961ce549b565b25c774c713fb3e041b9a35 Mon Sep 17 00:00:00 2001 From: Alex Bukharov Date: Sat, 12 Oct 2024 14:10:31 +1100 Subject: [PATCH 1/2] dhcp-server: ddns: T6773: DDNS configuration doco --- docs/configuration/service/dhcp-server.rst | 171 +++++++++++++++++++++ 1 file changed, 171 insertions(+) diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index eaa6a9f239..f89ffc3796 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -166,6 +166,177 @@ 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 + + If set on global level, updates for all scopes will be enabled, except if + explicitly disabled on the scope level. If unset, updates will only be sent for + scopes, where ``send-updates`` is explicity enabled. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update override-no-update + + VyOS will ignore client request to not update DNS records and send DDNS + update requests regardless. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update override-client-update + + 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 + + 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 use-conflict-resolution + + 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 used in client name generation. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update qualifying-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 + + + 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 + + + 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-name + 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-name + 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]-ddns-domain-name + key-name + + TSIG key used for the domain. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-ddns-domain-name + dns-server address + + IP address of the DNS server. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-ddns-domain-name + dns-server 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 + set service dhcp-server dynamic-dns-update use-conflict-resolution + +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-name mydomain-net algorithm hmac-sha256 + set service dhcp-server dynamic-dns-update tsig-key-name mydomain-net secret eWF5YW15bGl0dGxla2V5IQ== + set service dhcp-server dynamic-dns-update tsig-key-name reverse-172-18-201 algorithm hmac-sha256 + set service dhcp-server dynamic-dns-update tsig-key-name reverse-172-18-201 secret eWF5YW15YW5vdGhlcmxpdHRsZWtleSE= + +Configure DDNS domains: + +.. code-block:: none + + set service dhcp-server dynamic-dns-update forward-ddns-domain-name mydomain.net key-name mydomain-net + set service dhcp-server dynamic-dns-update forward-ddns-domain-name mydomain.net dns-server 1 address '172.18.0.254' + set service dhcp-server dynamic-dns-update forward-ddns-domain-name mydomain.net dns-server 1 port 1053 + set service dhcp-server dynamic-dns-update forward-ddns-domain-name mydomain.net dns-server 2 address '192.168.124.254' + set service dhcp-server dynamic-dns-update forward-ddns-domain-name mydomain.net dns-server 2 port 53 + set service dhcp-server dynamic-dns-update forward-ddns-domain-name 201.18.172.in-addr.arpa key-name reverse-172-18-201 + set service dhcp-server dynamic-dns-update reverse-ddns-domain-name 201.18.172.in-addr.arpa dns-server 1 address '172.18.0.254' + set service dhcp-server dynamic-dns-update reverse-ddns-domain-name 201.18.172.in-addr.arpa dns-server 1 port 1053 + set service dhcp-server dynamic-dns-update reverse-ddns-domain-name 201.18.172.in-addr.arpa dns-server 2 address '192.168.124.254' + set service dhcp-server dynamic-dns-update reverse-ddns-domain-name 201.18.172.in-addr.arpa dns-server 2 port 53 + + High Availability ----------------- From 786d200708c975a4b7b71cad7e26c85a8beee4a8 Mon Sep 17 00:00:00 2001 From: Alex Bukharov Date: Tue, 19 Nov 2024 19:25:26 +1100 Subject: [PATCH 2/2] Change rst lines to the correct length in docs/configuration/service/dhcp-server.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Göhler --- docs/configuration/service/dhcp-server.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index f89ffc3796..7bd0c0083b 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -167,7 +167,7 @@ Unifi controller at ``172.16.100.1`` to clients of that subnet. 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