diff options
| -rw-r--r-- | docs/configuration/service/dhcp-server.rst | 209 |
1 files changed, 195 insertions, 14 deletions
diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index 00f0b21c..502d1e1b 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/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>`. |