mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-22 18:08:16 +00:00
Code Issues Releases Wiki Activity

[#1548] Improved documentation in the ARM

Browse Source 
modified:   arm/hooks-ddns-tuning.rst
This commit is contained in:
Thomas Markwalder 2022-04-06 13:53:34 -04:00
parent 06c8e06c19
commit be0cd24054
1 changed files with 84 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
doc/sphinx/arm/hooks-ddns-tuning.rst
View File

@ -4,35 +4,59 @@
=================================== ===================================
This hook library adds support for fine tuning various DNS update aspects. This hook library adds support for fine tuning various DNS update aspects.
Currently is supports procedural hostname generation and an ability to fine Currently it supports procedural host name generation. The DDNS Tuning hook
tune which devices should do the DNS update. The DDNS Tuning hook is a premium is a premium feature.
feature.
The library, which was added in Kea 2.1.4, can be loaded in a The library, which was added in Kea 2.1.4, is loaded in a
similar way to other hook libraries by the ``kea-dhcp4`` and can be loaded by ``kea--dhcp4`` and ``kea-dhcp6`` by adding it
``kea-dhcp6`` processes. to ``hooks-libraries`` element of the server's configuration:
.. code-block:: javascript .. code-block:: javascript
{ {
"hooks-libraries": [ "hooks-libraries": [
:
,
{ {
"library": "/usr/local/lib/libdhcp_ddns_tuning.so", "library": "/usr/local/lib/libdhcp_ddns_tuning.so",
"parameters": { "parameters": {
"hostname-expr": "'host-'+hexstring(pkt4.mac,'-')" :
} }
} },
:
] ]
} }
This hook allows generating the hostname procedurally, based on an expression. Procedural Host name generation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The expression can be defined globally in the hook parameters, using `hostname-expr`. This hook library provides the ability to generate host names, procedurally, based on
If defined globally, it will apply to all hosts in all subnets. The expressions can use an expression. The expression can be defined globally in the hook parameters, using
all tokens defined in :ref:`classify`. `hostname-expr`. If defined globally, it will apply to all hosts in all subnets. The
expressions can use all tokens defined in :ref:`classify`. An example of a global
expression is shown below:
It is also possible to define this parameter in a subnet, using user context mechanism. .. code-block:: javascript
If defined at the subnet level, the expression applies to specific subnet only.
{
"hooks-libraries": [
:
,
{
"library": "/usr/local/lib/libdhcp_ddns_tuning.so",
"parameters": {
:
"hostname-expr": "'host-'+hexstring(pkt4.mac,'-')"
}
},
:
]
}
It is also possible to define this parameter in a subnet, using user-context mechanism.
If defined at the subnet level, the expression applies to specific subnet only. If the
subnet expression is defined as empty, "", it will suppresses (or disables) the use of
a global expression for that subnet. An example subnet expression is shown below:
.. code-block:: javascript .. code-block:: javascript
@ -65,7 +89,52 @@ If defined at the subnet level, the expression applies to specific subnet only.
.. note:: .. note::
Privacy should be taken into consideration when generating a hostname. The hostname is Privacy should be taken into consideration when generating a host name. The host name is
usually inserted into the DNS, which is a public system. Exposing identifiers that usually inserted into the DNS, which is a public system. Exposing identifiers that
can be used to track devices, such as MAC address, are usually a very bad idea. can be used to track devices, such as MAC address, are usually a very bad idea.
The global expression example used MAC address for simplicity. The global expression example used MAC address for simplicity.
DHCPv4 host name generation
---------------------------
With this library installed the behavior for ``kea-dhcp4`` when forming host names in
response to a client query (e.g. DISCOVER, REQUEST) is as follows:
1. If a host name is supplied via a host reservation use it along with the DDNS
behavioral parameters to form the final host name. Goto step 4.
2. If the client supplied an FQDN option (option 81) use the domain name value
specified within it along with the DDNS behavioral parameters to form the final
host name. Goto step 4.
3. If the client supplied a host name option (option 12) use the host name specified
within it along with the DDNS behavioral parameters to form the final host name.
4. If there is an ddns-tuning in-scope host name expression (either global or subnet),
calculate the host name using the expression. If the calculated value is not a fully
qualified name and there is an in-scope ddns-qualifying-suffix, append the suffix.
5. If value calculated by the hook is not an empty string and is different than the
the host name formed in the prior steps (1 or 2), the calculated value becomes the
final host name.
DHCPv6 host name generation
---------------------------
With this library installed the behavior for ``kea-dhcp6`` when forming host names in
response to a client query (e.g. SOLICIT, REQUEST, RENEW, REBIND) is as follows:
1. If a host name is supplied via a host reservation use it along with the DDNS
behavioral parameters to form the final host name. Goto step 3.
2. If the client supplied an FQDN option (option 39) use the domain name value
specified within it along with the DDNS behavioral parameters to form the final
host name. Goto step 3.
3. If there is an ddns-tuning in-scope host name expression (either global or subnet),
calculate the host name using the expression. If the calculated value is not a fully
qualified name and there is an in-scope ddns-qualifying-suffix, append the suffix.
4. If value calculated by the hook is not an empty string and is different than the
the host name formed in the prior steps (1 or 2), the calculated value becomes the
final host name.