vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
dhcp-server: ddns: T6773: DDNS configuration documentation
This commit is contained in:
Daniil Baturin 2025-04-29 13:13:09 +01:00 committed by GitHub
commit 0858fe7233
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 195 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

209
docs/configuration/service/dhcp-server.rst
View File

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