Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

dhcp-server: ddns: T6773: DDNS configuration documentation #1561

Open
wants to merge 2 commits into
base: current
Choose a base branch
from
Open

dhcp-server: ddns: T6773: DDNS configuration documentation #1561

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8b9a396
dhcp-server: ddns: T6773: DDNS configuration doco
abukharov Oct 12, 2024
786d200
Change rst lines to the correct length in docs/configuration/service/…
abukharov Nov 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
171 changes: 171 additions & 0 deletions docs/configuration/service/dhcp-server.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>

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-name <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-name <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]-ddns-domain-name
<domain-name> key-name <tsig-key-name>

TSIG key used for the domain.

.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-ddns-domain-name
<domain-name> dns-server <number> address <ip-address>

IP address of the DNS server.

.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-ddns-domain-name
<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
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
-----------------

Expand Down