From 8b9a3961ce549b565b25c774c713fb3e041b9a35 Mon Sep 17 00:00:00 2001 From: Alex Bukharov Date: Sat, 12 Oct 2024 14:10:31 +1100 Subject: [PATCH 1/4] 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/4] 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 From 1ab80ec274d21409d849a265877423cedeb21f94 Mon Sep 17 00:00:00 2001 From: Alex Bukharov Date: Wed, 27 Nov 2024 09:03:56 +1100 Subject: [PATCH 3/4] dhcp-server: ddns: T6773: DDNS config language changes --- docs/configuration/service/dhcp-server.rst | 48 +++++++++++----------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index 7bd0c0083b..ed70d73584 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -186,18 +186,18 @@ server with RFC-2136 DDNS support. 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 +.. cfgcmd:: set service dhcp-server dynamic-dns-update force-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. + scopes, where ``force-updates`` is explicity enabled. -.. cfgcmd:: set service dhcp-server dynamic-dns-update override-no-update +.. cfgcmd:: set service dhcp-server dynamic-dns-update force-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 +.. cfgcmd:: set service dhcp-server dynamic-dns-update force-client-update VyOS will override client DDNS request settings and always update both forward and reverse DNS records. @@ -258,13 +258,13 @@ level, i.e. for individual shared networks or subnets. See examples below. 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 +.. cfgcmd:: set service dhcp-server dynamic-dns-update tsig-key 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 +.. cfgcmd:: set service dhcp-server dynamic-dns-update tsig-key secret base64-encoded TSIG key secret value @@ -274,17 +274,17 @@ the name in the DNS domain definitions. 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 +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain key-name TSIG key used for the domain. -.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-ddns-domain-name +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain dns-server address IP address of the DNS server. -.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-ddns-domain-name +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain dns-server port UDP port of the DNS server. ``53`` is the default. @@ -295,7 +295,7 @@ 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 force-updates set service dhcp-server dynamic-dns-update use-conflict-resolution Override the above configuration for a shared network NET1: @@ -316,25 +316,25 @@ 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= + 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-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 + 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 From 4ed77ea02225ddd00f6920d94df4e18bf19254a3 Mon Sep 17 00:00:00 2001 From: Alex Bukharov Date: Sat, 30 Nov 2024 14:48:44 +1100 Subject: [PATCH 4/4] T6773: dhcp-server: ddns: Reflect recent configuration language changes --- docs/configuration/service/dhcp-server.rst | 32 ++++++++++++++-------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index ed70d73584..0748034373 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -186,28 +186,38 @@ server with RFC-2136 DDNS support. 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 force-updates +.. cfgcmd:: set service dhcp-server dynamic-dns-update send-updates [ enable + | disable ] - 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 ``force-updates`` is explicity enabled. + 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``. -.. cfgcmd:: set service dhcp-server dynamic-dns-update force-no-update + 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. - VyOS will ignore client request to not update DNS records and send DDNS +.. 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-client-update +.. 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 +.. 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 use-conflict-resolution +.. 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. @@ -295,8 +305,8 @@ Global configuration you will most likely want: .. code-block:: none - set service dhcp-server dynamic-dns-update force-updates - set service dhcp-server dynamic-dns-update use-conflict-resolution + 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: