From: Razvan Becheriu Date: Mon, 2 Oct 2023 15:00:38 +0000 (+0300) Subject: [#3046] updated ARM references to DDNS tunin hook library X-Git-Tag: Kea-2.5.3~52 X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=1e5a757a0e14cf7349a73fb95bbc06d989a3840b;p=thirdparty%2Fkea.git [#3046] updated ARM references to DDNS tunin hook library --- diff --git a/doc/sphinx/arm/ddns.rst b/doc/sphinx/arm/ddns.rst index b559255070..2d94d45c31 100644 --- a/doc/sphinx/arm/ddns.rst +++ b/doc/sphinx/arm/ddns.rst @@ -12,13 +12,20 @@ Overview The DHCP-DDNS Server (:iscman:`kea-dhcp-ddns`, known informally as D2) conducts the client side of the Dynamic DNS protocol (DDNS, defined in `RFC 2136 `__) on behalf of the DHCPv4 -and DHCPv6 servers (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` respectively). The DHCP -servers construct DDNS update requests, known as NameChangeRequests +and DHCPv6 servers (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` respectively). +The DHCP servers construct DDNS update requests, known as NameChangeRequests (NCRs), based on DHCP lease change events and then post them to D2. D2 attempts to match each request to the appropriate DNS server(s) and carries out the necessary conversation with those servers to update the DNS data. +For the ability to generate host names procedurally, based on an expression, and +for the ability to skip DDNS updates on a per-client basis, or fine-tuning +various DNS update aspects, the :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` can +load the premium hook library `libdhcp_ddns_tuning.so` which is available from +ISC. Please refer to :ref:`hooks-ddns-tuning` documentation for the +configuration options. + .. _dhcp-ddns-dns-server-selection: DNS Server Selection diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index 2eda450b16..1c0b890883 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -3652,9 +3652,9 @@ control this communication: By default, :iscman:`kea-dhcp-ddns` is assumed to be running on the same machine as :iscman:`kea-dhcp4`, and all of the default values mentioned above should be sufficient. If, however, D2 has been configured to listen on a different -address or port, these values must be altered accordingly. For example, -if D2 has been configured to listen on 192.168.1.10 port 900, the -following configuration is required: +address or port, these values must be altered accordingly. For example, if +D2 has been configured to listen on 192.168.1.10 port 900, the following +configuration is required: :: @@ -3702,32 +3702,32 @@ As for the first case, the decisions involved when granting a new lease are more complex. When a new lease is granted, :iscman:`kea-dhcp4` generates a DDNS update request if the DHCPREQUEST contains either the FQDN option (code 81) or the Host Name option (code 12). If both are present, the -server uses the FQDN option. By default, :iscman:`kea-dhcp4` respects the -FQDN N and S flags specified by the client as shown in the following -table: +server uses the FQDN option. +By default, :iscman:`kea-dhcp4` respects the FQDN N and S flags +specified by the client as shown in the following table: .. table:: Default FQDN flag behavior - +------------+---------------------+-----------------+-------------+ - | Client | Client Intent | Server Response | Server | - | Flags:N-S | | | Flags:N-S-O | - +============+=====================+=================+=============+ - | 0-0 | Client wants to | Server | 1-0-0 | - | | do forward | generates | | - | | updates, server | reverse-only | | - | | should do | request | | - | | reverse updates | | | - +------------+---------------------+-----------------+-------------+ - | 0-1 | Server should | Server | 0-1-0 | - | | do both forward | generates | | - | | and reverse | request to | | - | | updates | update both | | - | | | directions | | - +------------+---------------------+-----------------+-------------+ - | 1-0 | Client wants no | Server does not | 1-0-0 | - | | updates done | generate a | | - | | | request | | - +------------+---------------------+-----------------+-------------+ + +------------+-----------------+-----------------+-------------+ + | Client | Client Intent | Server Response | Server | + | Flags:N-S | | | Flags:N-S-O | + +============+=================+=================+=============+ + | 0-0 | Client wants to | Server | 1-0-0 | + | | do forward | generates | | + | | updates, server | reverse-only | | + | | should do | request | | + | | reverse updates | | | + +------------+-----------------+-----------------+-------------+ + | 0-1 | Server should | Server | 0-1-0 | + | | do both forward | generates | | + | | and reverse | request to | | + | | updates | update both | | + | | | directions | | + +------------+-----------------+-----------------+-------------+ + | 1-0 | Client wants no | Server does not | 1-0-0 | + | | updates done | generate a | | + | | | request | | + +------------+-----------------+-----------------+-------------+ The first row in the table above represents "client delegation." Here the DHCP client states that it intends to do the forward DNS updates and @@ -3760,8 +3760,8 @@ requests that no DNS updates be done. The parameter ``ddns-override-no-update`` can be used to instruct the server to disregard the client's wishes. When this parameter is ``true``, :iscman:`kea-dhcp4` generates DDNS update requests to :iscman:`kea-dhcp-ddns` even if the client -requests that no updates be done. The N-S-O flags in the server's -response to the client will be 0-1-1. +requests that no updates be done. The N-S-O flags in the server's response to +the client will be 0-1-1. To override client delegation, issue the following commands: @@ -3861,7 +3861,19 @@ meaningful default. ... } -When generating a name, :iscman:`kea-dhcp4` constructs the name in the format: +When qualifying a partial name, :iscman:`kea-dhcp4` constructs the name in the +format: + +``[candidate-name].[ddns-qualifying-suffix].`` + +where ``candidate-name`` is the partial name supplied in the DHCPREQUEST. +For example, if the FQDN domain name value is "some-computer" and the +``ddns-qualifying-suffix`` is "example.com", the generated FQDN is: + +``some-computer.example.com.`` + +When generating the entire name, :iscman:`kea-dhcp4` constructs the name in +the format: ``[ddns-generated-prefix]-[address-text].[ddns-qualifying-suffix].`` @@ -3878,11 +3890,11 @@ Sanitizing Client Host Name and FQDN Names ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Some DHCP clients may provide values in the Host Name -option (option code 12) or FQDN option (option code 81) that contain -undesirable characters. It is possible to configure :iscman:`kea-dhcp4` to -sanitize these values. The most typical use case is ensuring that only -characters that are permitted by RFC 1035 be included: A-Z, a-z, 0-9, -and "-". This may be accomplished with the following two parameters: +option (option code 12) or FQDN option (option code 81) that contain undesirable +characters. It is possible to configure :iscman:`kea-dhcp4` to sanitize these +values. The most typical use case is ensuring that only characters that +are permitted by RFC 1035 be included: A-Z, a-z, 0-9, and "-". This may be +accomplished with the following two parameters: - ``hostname-char-set`` - a regular expression describing the invalid character set. This can be any valid, regular expression using POSIX @@ -3916,19 +3928,20 @@ qualifying suffix (if one is defined and needed). Name sanitizing is meant to catch the more common cases of invalid characters through a relatively simple character-replacement scheme. It is difficult to devise a scheme that works well in all cases, for - both Host Name and FQDN options. Administrators who find they have clients - with odd corner cases of character combinations that cannot be - readily handled with this mechanism should consider writing a - hook that can carry out sufficiently complex logic to address their - needs. + both Host Name and FQDN options. + Administrators who find they have clients with odd corner cases of + character combinations that cannot be readily handled with this + mechanism should consider writing a hook that can carry out + sufficiently complex logic to address their needs. If clients include domain names in the Host Name option and the administrator wants these preserved, they need to make sure that the dot, ".", is considered a valid character by the ``hostname-char-set`` expression, such as this: ``"[^A-Za-z0-9.-]"``. This does not affect dots in FQDN - Option values. When scrubbing FQDNs, dots are treated as delimiters - and used to separate the option value into individual domain labels - that are scrubbed and then re-assembled. + Option values. + When scrubbing FQDNs, dots are treated as delimiters and used to separate + the option value into individual domain labels that are scrubbed and + then re-assembled. If clients are sending values that differ only by characters considered as invalid by the ``hostname-char-set``, be aware that @@ -3950,6 +3963,12 @@ qualifying suffix (if one is defined and needed). a ``hostname-char`` parameter is defined at both the global scope and in a ``dhcp-ddns`` entry, the second (local) value is used. + For the ability to generate host names procedurally, based on an expression, and + for the ability to skip DDNS updates on a per-client basis, or fine-tuning various + DNS update aspects, the :iscman:`kea-dhcp4` can load the premium hook library + `libdhcp_ddns_tuning.so` which is available from ISC. Please refer to + :ref:`hooks-ddns-tuning` documentation for the configuration options. + .. _dhcp4-next-server: Next Server (``siaddr``) diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index fda0015757..9d35fff1ba 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/doc/sphinx/arm/dhcp6-srv.rst @@ -2993,8 +2993,8 @@ NCRs. Each NCR contains the following information: 1. Whether it is a request to add (update) or remove DNS entries. -2. Whether the change requests forward DNS updates (AAAA records), - reverse DNS updates (PTR records), or both. +2. Whether the change requests forward DNS updates (AAAA records) reverse + DNS updates (PTR records), or both. 3. The Fully Qualified Domain Name (FQDN), lease address, and DHCID (information identifying the client associated with the FQDN). @@ -3163,7 +3163,7 @@ offers four modes of conflict resolution-related behavior: prevent. This means that existing entries for an FQDN or an IP address made for Client-A can be deleted or replaced by entries for Client-B. Furthermore, there are two scenarios by which entries - for multiple clients for the same key (e.g. FQDN or IP) can be created + for multiple clients for the same key (e.g. FQDN or IP) can be created. 1. Client-B uses the same FQDN as Client-A but a different IP address. In this case, the forward DNS entries (AAAA and DHCID RRs) for @@ -3187,7 +3187,7 @@ offers four modes of conflict resolution-related behavior: to generate DNS removal requests to D2. The DNS entries Kea creates contain a value for TTL (time to live). -:iscman:`kea-dhcp6` calculates that value based on +The :iscman:`kea-dhcp6` server calculates that value based on `RFC 4702, Section 5 `__, which suggests that the TTL value be 1/3 of the lease's lifetime, with a minimum value of 10 minutes. @@ -3273,8 +3273,9 @@ out the actual DNS updates and dealing with such things as conflict resolution are within the purview of D2 itself (see :ref:`dhcp-ddns-server`). This section describes when :iscman:`kea-dhcp6` generates NCRs and the configuration parameters that can be used to -influence this decision. It assumes that the ``enable-updates`` -parameter is ``true``. +influence this decision. It assumes that both the connectivity parameter +``enable-updates`` and the behavioral parameter ``ddns-send-updates``, +are ``true``. .. note:: @@ -3300,42 +3301,44 @@ single DDNS request - to remove its entries will be made. As for the first case, the decisions involved when granting a new lease are more complex. When a new lease is granted, :iscman:`kea-dhcp6` generates a DDNS update request only if the DHCPREQUEST contains the FQDN option -(code 39). By default, :iscman:`kea-dhcp6` respects the FQDN N and S flags +(code 39). +By default, :iscman:`kea-dhcp6` respects the FQDN N and S flags specified by the client as shown in the following table: .. table:: Default FQDN flag behavior - +-----------------+-----------------+-----------------+-----------------+ - | Client | Client Intent | Server Response | Server | - | Flags:N-S | | | Flags:N-S-O | - +=================+=================+=================+=================+ - | 0-0 | Client wants to | Server | 1-0-0 | - | | do forward | generates | | - | | updates, server | reverse-only | | - | | should do | request | | - | | reverse updates | | | - +-----------------+-----------------+-----------------+-----------------+ - | 0-1 | Server should | Server | 0-1-0 | - | | do both forward | generates | | - | | and reverse | request to | | - | | updates | update both | | - | | | directions | | - +-----------------+-----------------+-----------------+-----------------+ - | 1-0 | Client wants no | Server does not | 1-0-0 | - | | updates done | generate a | | - | | | request | | - +-----------------+-----------------+-----------------+-----------------+ + +------------+-----------------+-----------------+-------------+ + | Client | Client Intent | Server Response | Server | + | Flags:N-S | | | Flags:N-S-O | + +============+=================+=================+=============+ + | 0-0 | Client wants to | Server | 1-0-0 | + | | do forward | generates | | + | | updates, server | reverse-only | | + | | should do | request | | + | | reverse updates | | | + +------------+-----------------+-----------------+-------------+ + | 0-1 | Server should | Server | 0-1-0 | + | | do both forward | generates | | + | | and reverse | request to | | + | | updates | update both | | + | | | directions | | + +------------+-----------------+-----------------+-------------+ + | 1-0 | Client wants no | Server does not | 1-0-0 | + | | updates done | generate a | | + | | | request | | + +------------+-----------------+-----------------+-------------+ The first row in the table above represents "client delegation." Here the DHCP client states that it intends to do the forward DNS updates and the server should do the reverse updates. By default, :iscman:`kea-dhcp6` -honors the client's wishes and generates a DDNS request to D2 to update -only reverse DNS data. The parameter ``ddns-override-client-update`` can be -used to instruct the server to override client delegation requests. When -this parameter is ``true``, :iscman:`kea-dhcp6` disregards requests for client -delegation and generates a DDNS request to update both forward and -reverse DNS data. In this case, the N-S-O flags in the server's response -to the client will be 0-1-1 respectively. +honors the client's wishes and generates a DDNS request to the D2 server +to update only reverse DNS data. The parameter +``ddns-override-client-update`` can be used to instruct the server to +override client delegation requests. When this parameter is ``true``, +:iscman:`kea-dhcp6` disregards requests for client delegation and generates a +DDNS request to update both forward and reverse DNS data. In this case, +the N-S-O flags in the server's response to the client will be 0-1-1 +respectively. (Note that the flag combination N=1, S=1 is prohibited according to `RFC 4702 `__. If such a combination is @@ -3379,10 +3382,10 @@ is the name submitted to D2 in the DDNS update request. :iscman:`kea-dhcp6` Name Generation for DDNS Update Requests ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Each NameChangeRequest must of course include the fully qualified -domain name whose DNS entries are to be affected. :iscman:`kea-dhcp6` can be -configured to supply a portion or all of that name, based upon what it -receives from the client in the DHCPREQUEST. +Each NameChangeRequest must of course include the fully qualified domain +name whose DNS entries are to be affected. :iscman:`kea-dhcp6` can be configured +to supply a portion or all of that name, based on what it receives +from the client in the DHCPREQUEST. The default rules for constructing the FQDN that will be used for DNS entries are: @@ -3415,12 +3418,11 @@ parameter, which provides the following modes of behavior: .. note:: - In early versions of Kea, this parameter was a boolean and - permitted only values of ``true`` and ``false``. - Boolean values have been deprecated and are no longer accepted. - Administrators currently using booleans must replace them with the - desired mode name. A value of ``true`` maps to ``when-present``, while - ``false`` maps to ``never``. + In early versions of Kea, this parameter was a boolean and permitted only + values of ``true`` and ``false``. Boolean values have been deprecated + and are no longer accepted. Administrators currently using booleans + must replace them with the desired mode name. A value of ``true`` + maps to ``when-present``, while ``false`` maps to ``never``. For example, to instruct :iscman:`kea-dhcp6` to always generate the FQDN for a client, set the parameter ``ddns-replace-client-name`` to ``always`` as @@ -3445,9 +3447,10 @@ its value, simply set it to the desired string: } The suffix used when generating an FQDN, or when qualifying a partial -name, is specified by the ``ddns-qualifying-suffix`` parameter. This -parameter has no default value; thus, it is mandatory when DDNS updates -are enabled. To set its value simply set it to the desired string: +name, is specified by the ``ddns-qualifying-suffix`` parameter. It is +strongly recommended that the user supply a value for the qualifying prefix when +DDNS updates are enabled. For obvious reasons, we cannot supply a +meaningful default. :: @@ -3484,8 +3487,8 @@ qualifying suffix is "example.com", and the default value is used for Sanitizing Client FQDN Names ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Some DHCP clients may provide values in the name -component of the FQDN option (option code 39) that contain undesirable +Some DHCP clients may provide values in the name component of the FQDN +option (option code 39) that contain undesirable characters. It is possible to configure :iscman:`kea-dhcp6` to sanitize these values. The most typical use case is ensuring that only characters that are permitted by RFC 1035 be included: A-Z, a-z, 0-9, and "-". This may be @@ -3528,8 +3531,9 @@ qualifying suffix (if one is defined and needed). mechanism should consider writing a hook that can carry out sufficiently complex logic to address their needs. - Do not include dots in the ``hostname-char-set`` expression. When - scrubbing FQDNs, dots are treated as delimiters and used to separate + Make sure that the dot, "." is considered a valid character by the + ``hostname-char-set`` expression, such as this: ``"[^A-Za-z0-9.-]"``. + When scrubbing FQDNs, dots are treated as delimiters and used to separate the option value into individual domain labels that are scrubbed and then re-assembled. @@ -3553,6 +3557,12 @@ qualifying suffix (if one is defined and needed). a ``hostname-char`` parameter is defined at both the global scope and in a ``dhcp-ddns`` entry, the second (local) value is used. + For the ability to generate host names procedurally, based on an expression, and + for the ability to skip DDNS updates on a per-client basis, or fine-tuning various + DNS update aspects, the :iscman:`kea-dhcp6` can load the premium hook library + `libdhcp_ddns_tuning.so` which is available from ISC. Please refer to + :ref:`hooks-ddns-tuning` documentation for the configuration options. + .. _dhcp6-dhcp4o6-config: DHCPv4-over-DHCPv6: DHCPv6 Side diff --git a/src/bin/dhcp6/tests/fqdn_unittest.cc b/src/bin/dhcp6/tests/fqdn_unittest.cc index bc26f19a28..2b2d7819fb 100644 --- a/src/bin/dhcp6/tests/fqdn_unittest.cc +++ b/src/bin/dhcp6/tests/fqdn_unittest.cc @@ -125,11 +125,11 @@ public: subnet_->setDdnsOverrideNoUpdate(mask & OVERRIDE_NO_UPDATE); subnet_->setDdnsOverrideClientUpdate(mask & OVERRIDE_CLIENT_UPDATE); subnet_->setDdnsReplaceClientNameMode((mask & REPLACE_CLIENT_NAME) ? - D2ClientConfig::RCM_WHEN_PRESENT - : D2ClientConfig::RCM_NEVER); + D2ClientConfig::RCM_WHEN_PRESENT : + D2ClientConfig::RCM_NEVER); subnet_->setDdnsGeneratedPrefix("myhost"); subnet_->setDdnsQualifyingSuffix("example.com"); - subnet_->setHostnameCharSet("[^A-Za-z0-9-]"); + subnet_->setHostnameCharSet("[^A-Za-z0-9.-]"); subnet_->setHostnameCharReplacement("x"); subnet_->setDdnsConflictResolutionMode("check-with-dhcid"); diff --git a/src/lib/dhcpsrv/tests/d2_client_unittest.cc b/src/lib/dhcpsrv/tests/d2_client_unittest.cc index c15afc59fd..bbfad172f1 100644 --- a/src/lib/dhcpsrv/tests/d2_client_unittest.cc +++ b/src/lib/dhcpsrv/tests/d2_client_unittest.cc @@ -1086,7 +1086,7 @@ TEST_F(D2ClientMgrParamsTest, sanitizeFqdnV4) { subnet_->setDdnsReplaceClientNameMode(D2ClientConfig::RCM_NEVER); subnet_->setDdnsGeneratedPrefix("prefix"); subnet_->setDdnsQualifyingSuffix("suffix.com"); - subnet_->setHostnameCharSet("[^A-Za-z0-9-]"); + subnet_->setHostnameCharSet("[^A-Za-z0-9.-]"); subnet_->setHostnameCharReplacement("x"); // Get the sanitizer. @@ -1169,7 +1169,7 @@ TEST_F(D2ClientMgrParamsTest, sanitizeFqdnV6) { subnet_->setDdnsReplaceClientNameMode(D2ClientConfig::RCM_NEVER); subnet_->setDdnsGeneratedPrefix("prefix"); subnet_->setDdnsQualifyingSuffix("suffix.com"); - subnet_->setHostnameCharSet("[^A-Za-z0-9-]"); + subnet_->setHostnameCharSet("[^A-Za-z0-9.-]"); subnet_->setHostnameCharReplacement("x"); // Get the sanitizer.