mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-28 12:37:55 +00:00
Code Issues Releases Wiki Activity

[#35,!517] Updated ARM and example confings

Browse Source 
Updated:
    doc/examples/kea4/all-keys.json
    doc/examples/kea4/with-ddns.json
    doc/examples/kea6/all-keys.json
    doc/sphinx/arm/dhcp4-srv.rst
    doc/sphinx/arm/dhcp6-srv.rst

Added ChangeLogEntry
This commit is contained in:
Thomas Markwalder 2019-10-08 09:21:03 -04:00
parent 1f60cb9dd7
commit 4ac6e5b9ee
6 changed files with 588 additions and 314 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
ChangeLog
View File

@ -1,3 +1,10 @@
1669. [func] tmark
Rather than within the 'dhcp-ddns' section, DDNS behavioral
parameters may now be specifed at global, shared-network,
and subnet scopes. Implemented for both kea-dhcp4 and
kea-dhcp6. Not yet supported by Config Backend or Netconf.
(Gitlab #35,!517, git TBD)
1668. [build] fdupont
The Kea util thread library was removed.
(Gitlab #907,!519, git 1b27dc52aae23753643461086f0950b125bf9c93)

186
doc/examples/kea4/all-keys.json
View File

@ -98,6 +98,46 @@
"socket-type": "unix"
},
// Specifies a prefix to be prepended to the generated Client FQDN.
"ddns-generated-prefix": "myhost",
// Boolean flag indicating that server should ignore DHCP client
// wishes to update DNS on its own. With that flag set to true
// the server will send DNS updates for both forward and
// reverse DNS data. The default value is false, which indicates
// that the server will delegate DNS update to the client when
// requested.
"ddns-override-client-update": false,
// Boolean flag indicating that the server should override DHCP
// client's wish to not update the DNS. With this parameter
// set to true the server will send DNS update even when
// the client requested no update.
"ddns-override-no-update": false,
// Suffix appended to the partial name sent to the DNS. The
// default value is an empty string which indicates that no
// suffix is appended.
"ddns-qualifying-suffix": "",
// Enumeration specifying whether the server should honor
// hostname or Client FQDN sent by the client or replace
// this name. The acceptable values are: "never" (use the
// name the client sent), "always" (replace the name the
// client sent), "when-present" (replace the name the client
// sent, but do not generate one when the client didn't sent
// the name), "when-not-present" (generate the name when
// client didn't send one, otherwise leave the name the
// client sent). The default value is "never".
"ddns-replace-client-name": "never",
// Boolean flag which enables or disables the DDNS updating. It
// defaults to true. It may be specified at the global, shared-
// network and subnet levels. It works in conjunction with
// dhcp-ddns:enable-updates which must be true enable connectivity
// kea-dhcp-ddns..
"ddns-send-updates": true,
// Time in seconds specifying how long a declined lease should be
// excluded from DHCP assignments. The default value is 24 hours.
"decline-probation-period": 86400,
@ -106,23 +146,11 @@
// NCRs are sent to Kea D2 module to update DNS upon allocation of the
// DHCP leases.
"dhcp-ddns": {
// Boolean flag indicating if Kea DHCPv4 server must generate NCRs.
// By default NCRs are not generated.
// Boolean flag indicating if Kea DHCPv4 server should connect to
// kea-dhcp-ddns. This must be true for NCRs to be created and
// sent to kea-dhcp-ddns. By default NCRs are not generated.
"enable-updates": false,
// Specifies a prefix to be prepended to the generated Client FQDN.
"generated-prefix": "myhost",
// String of zero or more characters with which to replace each
// invalid character in the hostname or Client FQDN. The default
// value is an empty string which will cause invalid characters
// to be omitted rather than replaced.
"hostname-char-replacement": "x",
// Regular expression describing the invalid character set in
// the hostname or Client FQDN.
"hostname-char-set": "[^A-Za-z0-9.-]",
// Specifies maximum number of NCRs to queue waiting to be sent
// to Kea D2 server.
"max-queue-size": 1024,
@ -135,36 +163,6 @@
// only UDP is supported.
"ncr-protocol": "UDP",
// Boolean flag indicating that server should ignore DHCP client
// wishes to update DNS on its own. With that flag set to true
// the server will send DNS updates for both forward and
// reverse DNS data. The default value is false, which indicates
// that the server will delegate DNS update to the client when
// requested.
"override-client-update": false,
// Boolean flag indicating that the server should override DHCP
// client's wish to not update the DNS. With this parameter
// set to true the server will send DNS update even when
// the client requested no update.
"override-no-update": false,
// Suffix appended to the partial name sent to the DNS. The
// default value is an empty string which indicates that no
// suffix is appended.
"qualifying-suffix": "",
// Enumeration specifying whether the server should honor
// hostname or Client FQDN sent by the client or replace
// this name. The acceptable values are: "never" (use the
// name the client sent), "always" (replace the name the
// client sent), "when-present" (replace the name the client
// sent, but do not generate one when the client didn't sent
// the name), "when-not-present" (generate the name when
// client didn't send one, otherwise leave the name the
// client sent). The default value is "never".
"replace-client-name": "never",
// IP address that Kea DHCPv4 server should use to send
// NCRs to D2. Default value of zero indicates that Kea
// should pick suitable address.
@ -522,6 +520,55 @@
// empty string is provided, no restriction is applied.
"client-class": "",
// Specifies a prefix to be prepended to the generated Client FQDN.
"ddns-generated-prefix": "myhost",
// Boolean flag indicating that server should ignore DHCP client
// wishes to update DNS on its own. With that flag set to true
// the server will send DNS updates for both forward and
// reverse DNS data. The default value is false, which indicates
// that the server will delegate DNS update to the client when
// requested.
"ddns-override-client-update": false,
// Boolean flag indicating that the server should override DHCP
// client's wish to not update the DNS. With this parameter
// set to true the server will send DNS update even when
// the client requested no update.
"ddns-override-no-update": false,
// Suffix appended to the partial name sent to the DNS. The
// default value is an empty string which indicates that no
// suffix is appended.
"ddns-qualifying-suffix": "",
// Enumeration specifying whether the server should honor
// hostname or Client FQDN sent by the client or replace
// this name. The acceptable values are: "never" (use the
// name the client sent), "always" (replace the name the
// client sent), "when-present" (replace the name the client
// sent, but do not generate one when the client didn't sent
// the name), "when-not-present" (generate the name when
// client didn't send one, otherwise leave the name the
// client sent). The default value is "never".
"ddns-replace-client-name": "never",
// Boolean flag which enables or disables DDNS updating for
// subnets in this network. It works in conjunction with
// dhcp-ddns:enable-updates which must be true enable connectivity
// kea-dhcp-ddns. The default value is "true".
"ddns-send-updates": true,
// String of zero or more characters with which to replace each
// invalid character in the hostname or Client FQDN. The default
// value is an empty string which will cause invalid characters
// to be omitted rather than replaced.
"hostname-char-replacement": "x",
// Regular expression describing the invalid character set in
// the hostname or Client FQDN.
"hostname-char-set": "[^A-Za-z0-9.-]",
// Specifies that this shared network is selected for the
// requests received on the particular interface.
"interface": "ethX",
@ -593,6 +640,55 @@
// provided, no restriction is applied.
"client-class": "",
// Specifies a prefix to be prepended to the generated Client FQDN.
"ddns-generated-prefix": "myhost",
// Boolean flag indicating that server should ignore DHCP client
// wishes to update DNS on its own. With that flag set to true
// the server will send DNS updates for both forward and
// reverse DNS data. The default value is false, which indicates
// that the server will delegate DNS update to the client when
// requested.
"ddns-override-client-update": false,
// Boolean flag indicating that the server should override DHCP
// client's wish to not update the DNS. With this parameter
// set to true the server will send DNS update even when
// the client requested no update.
"ddns-override-no-update": false,
// Suffix appended to the partial name sent to the DNS. The
// default value is an empty string which indicates that no
// suffix is appended.
"ddns-qualifying-suffix": "",
// Enumeration specifying whether the server should honor
// hostname or Client FQDN sent by the client or replace
// this name. The acceptable values are: "never" (use the
// name the client sent), "always" (replace the name the
// client sent), "when-present" (replace the name the client
// sent, but do not generate one when the client didn't sent
// the name), "when-not-present" (generate the name when
// client didn't send one, otherwise leave the name the
// client sent). The default value is "never".
"ddns-replace-client-name": "never",
// Boolean flag which enables or disables DDNS updating for
// subnets in this network. It works in conjunction with
// dhcp-ddns:enable-updates which must be true enable connectivity
// kea-dhcp-ddns. The default value is "true".
"ddns-send-updates": true,
// String of zero or more characters with which to replace each
// invalid character in the hostname or Client FQDN. The default
// value is an empty string which will cause invalid characters
// to be omitted rather than replaced.
"hostname-char-replacement": "x",
// Regular expression describing the invalid character set in
// the hostname or Client FQDN.
"hostname-char-set": "[^A-Za-z0-9.-]",
// Subnet unique identifier.
"id": 1,

26
doc/examples/kea4/with-ddns.json
View File

@ -1,5 +1,5 @@
// This is an example configuration file for the DHCPv4 server in Kea.
// It is a basic scenario with one IPv4 subnet configured but with DDNS
// It is a basic scenario with one IPv4 subnet configured and with DDNS
// enabled.
{ "Dhcp4":
@ -39,7 +39,8 @@
}
],
// Enable dynamic DNS updates
// Enable connectivity with kea-dhcp-ddns
// (Required for dynamic DNS updates)
"dhcp-ddns" : {
"enable-updates" : true,
"server-ip" : "192.0.2.0",
@ -48,15 +49,18 @@
"sender-port" : 3433,
"max-queue-size" : 2048,
"ncr-protocol" : "UDP",
"ncr-format" : "JSON",
"override-no-update" : true,
"override-client-update" : true,
"replace-client-name" : "when-present",
"generated-prefix" : "test.prefix",
"qualifying-suffix" : "test.suffix.",
"hostname-char-set": "[^A-Za-z0-9.-]",
"hostname-char-replacement": "x"
},
"ncr-format" : "JSON"
},
// Enable DDNS updates and configure DDNS update behavior
"ddns-send-updates" : true,
"ddns-override-no-update" : true,
"ddns-override-client-update" : true,
"ddns-replace-client-name" : "when-present",
"ddns-generated-prefix" : "test.prefix",
"ddns-qualifying-suffix" : "test.suffix.",
"hostname-char-set": "[^A-Za-z0-9.-]",
"hostname-char-replacement": "x",
// The following configures logging. It assumes that messages with at
// least informational level (info, warn, error and fatal) should be

185
doc/examples/kea6/all-keys.json
View File

@ -63,6 +63,46 @@
"socket-type": "unix"
},
// Specifies a prefix to be prepended to the generated Client FQDN.
"ddns-generated-prefix": "myhost",
// Boolean flag indicating that server should ignore DHCP client
// wishes to update DNS on its own. With that flag set to true
// the server will send DNS updates for both forward and
// reverse DNS data. The default value is false, which indicates
// that the server will delegate DNS update to the client when
// requested.
"ddns-override-client-update": false,
// Boolean flag indicating that the server should override DHCP
// client's wish to not update the DNS. With this parameter
// set to true the server will send DNS update even when
// the client requested no update.
"ddns-override-no-update": false,
// Suffix appended to the partial name sent to the DNS. The
// default value is an empty string which indicates that no
// suffix is appended.
"ddns-qualifying-suffix": "",
// Enumeration specifying whether the server should honor
// hostname or Client FQDN sent by the client or replace
// this name. The acceptable values are: "never" (use the
// name the client sent), "always" (replace the name the
// client sent), "when-present" (replace the name the client
// sent, but do not generate one when the client didn't sent
// the name), "when-not-present" (generate the name when
// client didn't send one, otherwise leave the name the
// client sent). The default value is "never".
"ddns-replace-client-name": "never",
// Boolean flag which enables or disables the DDNS updating. It
// defaults to true. It may be specified at the global, shared-
// network and subnet levels. It works in conjunction with
// dhcp-ddns:enable-updates which must be true enable connectivity
// kea-dhcp-ddns..
"ddns-send-updates": true,
// Time in seconds specifying how long a declined lease should be
// excluded from DHCP assignments. The default value is 24 hours.
"decline-probation-period": 86400,
@ -75,19 +115,6 @@
// By default NCRs are not generated.
"enable-updates": false,
// Specifies a prefix to be prepended to the generated Client FQDN.
"generated-prefix": "myhost",
// String of zero or more characters with which to replace each
// invalid character in the hostname or Client FQDN. The default
// value is an empty string which will cause invalid characters
// to be omitted rather than replaced.
"hostname-char-replacement": "x",
// Regular expression describing the invalid character set in
// the hostname or Client FQDN.
"hostname-char-set": "[^A-Za-z0-9.-]",
// Specifies maximum number of NCRs to queue waiting to be sent
// to Kea D2 server.
"max-queue-size": 1024,
@ -100,36 +127,6 @@
// only UDP is supported.
"ncr-protocol": "UDP",
// Boolean flag indicating that server should ignore DHCP client
// wishes to update DNS on its own. With that flag set to true
// the server will send DNS updates for both forward and
// reverse DNS data. The default value is false, which indicates
// that the server will delegate DNS update to the client when
// requested.
"override-client-update": false,
// Boolean flag indicating that the server should override DHCP
// client's wish to not update the DNS. With this parameter
// set to true the server will send DNS update even when
// the client requested no update.
"override-no-update": false,
// Suffix appended to the partial name sent to the DNS. The
// default value is an empty string which indicates that no
// suffix is appended.
"qualifying-suffix": "",
// Enumeration specifying whether the server should honor
// hostname or Client FQDN sent by the client or replace
// this name. The acceptable values are: "never" (use the
// name the client sent), "always" (replace the name the
// client sent), "when-present" (replace the name the client
// sent, but do not generate one when the client didn't sent
// the name), "when-not-present" (generate the name when
// client didn't send one, otherwise leave the name the
// client sent). The default value is "never".
"replace-client-name": "never",
// IP address that Kea DHCPv6 server should use to send
// NCRs to D2. Default value of zero indicates that Kea
// should pick suitable address.
@ -476,6 +473,55 @@
// empty string is provided, no restriction is applied.
"client-class": "",
// Specifies a prefix to be prepended to the generated Client FQDN.
"ddns-generated-prefix": "myhost",
// Boolean flag indicating that server should ignore DHCP client
// wishes to update DNS on its own. With that flag set to true
// the server will send DNS updates for both forward and
// reverse DNS data. The default value is false, which indicates
// that the server will delegate DNS update to the client when
// requested.
"ddns-override-client-update": false,
// Boolean flag indicating that the server should override DHCP
// client's wish to not update the DNS. With this parameter
// set to true the server will send DNS update even when
// the client requested no update.
"ddns-override-no-update": false,
// Suffix appended to the partial name sent to the DNS. The
// default value is an empty string which indicates that no
// suffix is appended.
"ddns-qualifying-suffix": "",
// Enumeration specifying whether the server should honor
// hostname or Client FQDN sent by the client or replace
// this name. The acceptable values are: "never" (use the
// name the client sent), "always" (replace the name the
// client sent), "when-present" (replace the name the client
// sent, but do not generate one when the client didn't sent
// the name), "when-not-present" (generate the name when
// client didn't send one, otherwise leave the name the
// client sent). The default value is "never".
"ddns-replace-client-name": "never",
// Boolean flag which enables or disables DDNS updating for
// subnets in this network. It works in conjunction with
// dhcp-ddns:enable-updates which must be true enable connectivity
// kea-dhcp-ddns. The default value is "true".
"ddns-send-updates": true,
// String of zero or more characters with which to replace each
// invalid character in the Client FQDN. The default
// value is an empty string which will cause invalid characters
// to be omitted rather than replaced.
"hostname-char-replacement": "x",
// Regular expression describing the invalid character set in
// the Client FQDN.
"hostname-char-set": "[^A-Za-z0-9.-]",
// Specifies that this shared network is selected for the
// requests received on the particular interface.
"interface": "ethX",
@ -542,6 +588,55 @@
// provided, no restriction is applied.
"client-class": "",
// Specifies a prefix to be prepended to the generated Client FQDN.
"ddns-generated-prefix": "myhost",
// Boolean flag indicating that server should ignore DHCP client
// wishes to update DNS on its own. With that flag set to true
// the server will send DNS updates for both forward and
// reverse DNS data. The default value is false, which indicates
// that the server will delegate DNS update to the client when
// requested.
"ddns-override-client-update": false,
// Boolean flag indicating that the server should override DHCP
// client's wish to not update the DNS. With this parameter
// set to true the server will send DNS update even when
// the client requested no update.
"ddns-override-no-update": false,
// Suffix appended to the partial name sent to the DNS. The
// default value is an empty string which indicates that no
// suffix is appended.
"ddns-qualifying-suffix": "",
// Enumeration specifying whether the server should honor
// hostname or Client FQDN sent by the client or replace
// this name. The acceptable values are: "never" (use the
// name the client sent), "always" (replace the name the
// client sent), "when-present" (replace the name the client
// sent, but do not generate one when the client didn't sent
// the name), "when-not-present" (generate the name when
// client didn't send one, otherwise leave the name the
// client sent). The default value is "never".
"ddns-replace-client-name": "never",
// Boolean flag which enables or disables DDNS updating for
// subnets in this network. It works in conjunction with
// dhcp-ddns:enable-updates which must be true enable connectivity
// kea-dhcp-ddns. The default value is "true".
"ddns-send-updates": true,
// String of zero or more characters with which to replace each
// invalid character in the Client FQDN. The default
// value is an empty string which will cause invalid characters
// to be omitted rather than replaced.
"hostname-char-replacement": "x",
// Regular expression describing the invalid character set in
// the or Client FQDN.
"hostname-char-set": "[^A-Za-z0-9.-]",
// Subnet unique identifier.
"id": 1,
@ -809,13 +904,13 @@
"t2-percent": .75,
// String of zero or more characters with which to replace each
// invalid character in the hostname or Client FQDN. The default
// invalid character in the Client FQDN. The default
// value is an empty string which will cause invalid characters
// to be omitted rather than replaced.
"hostname-char-replacement": "x",
// Regular expression describing the invalid character set in
// the hostname or Client FQDN.
// the Client FQDN.
"hostname-char-set": "[^A-Za-z0-9.-]",
// List of loggers used by the servers using this configuration file.

243
doc/sphinx/arm/dhcp4-srv.rst
View File

@ -2799,9 +2799,9 @@ DDNS for DHCPv4
---------------
As mentioned earlier, kea-dhcp4 can be configured to generate requests
to the DHCP-DDNS server (referred to here as "D2") to update DNS
entries. These requests are known as Name Change Requests or NCRs. Each
NCR contains the following information:
to the DHCP-DDNS server, kea-dhcp-ddns, (referred to herein as "D2") to
update DNS entries. These requests are known as Name Change Requests or
NCRs. Each NCR contains the following information:
1. Whether it is a request to add (update) or remove DNS entries
@ -2811,62 +2811,108 @@ NCR contains the following information:
3. The Fully Qualified Domain Name (FQDN), lease address, and DHCID
(information identifying the client associated with the FQDN)
The parameters for controlling the generation of NCRs for submission to
D2 are contained in the ``dhcp-ddns`` section of the kea-dhcp4 server
configuration. The mandatory parameters for the DHCP DDNS configuration
are ``enable-updates``, which is unconditionally required, and
``qualifying-suffix``, which has no default value and is required when
``enable-updates`` is set to ``true``. The two (disabled and enabled)
minimal DHCP DDNS configurations are:
Prior to Kea 1.7.1, all parameters for controlling DDNS were within the
global, ``dhcp-ddns`` section of the kea-dhcp4. Beginning with Kea 1.7.1
DDNS related parameters were split into two groups:
1. Connectivity Parameters
These are parameters which specify where and how kea-dhcp4 connects to
and communicates with D2. These parameters can only be specified
within the top-level ``dhcp-ddns`` section in the kea-dhcp4
configuration. The connectivity parameters are listed below:
- ``enable-updates``
- ``server-ip``
- ``server-port``
- ``sender-ip``
- ``sender-port``
- ``max-queue-size``
- ``ncr-protocol``
- ``ncr-format"``
2. Behavioral Parameters
These parameters influence behavior such as how client host names and
FQDN options are handled. They have been moved out of the ``dhcp-ddns``
section so that they may be specified at the global, shared-network,
and/or subnet levels. Furthermore, they are inherited downward from global to
shared-network to subnet. In other words, if a parameter is not specified at
a given level, the value for that level comes from the level above it.
The behavioral parameter as follows:
- ``ddns-send-updates``
- ``ddns-override-no-update``
- ``ddns-override-client-update``
- ``ddns-replace-client-name"``
- ``ddns-generated-prefix``
- ``ddns-qualifying-suffix``
- ``hostname-char-set``
- ``hostname-char-replacement``
.. note::
For backward compatibility, configuration parsing will still recognize
the original behavioral parameters specified in ``dhcp-ddns``. It will
do so by translating the parameter into its global equivalent. If a
parameter is specified both globally and in ``dhcp-ddns``, the latter
value will be ignored. In either case, a log will be emitted explaining
what has occurred. Specifying these values within ``dhcp-ddns`` is
deprecated and support for it may be removed at some future date.
The default configuration would appear as follows:
::
"Dhcp4": {
"dhcp-ddns": {
"enable-updates": false
},
...
"dhcp-ddns": {
// Connectivity parameters
"enable-updates": false,
"server-ip": "127.0.0.1",
"server-port":53001,
"sender-ip":"",
"sender-port":0,
"max-queue-size":1024,
"ncr-protocol":"UDP",
"ncr-format":"JSON"
},
// Behavioral parameters (global)
"ddns-send-updates": true,
"ddns-override-no-update": false,
"ddns-override-client-update": false,
"ddns-replace-client-name": "never",
"ddns-generated-prefix": "myhost",
"ddns-qualifying-suffix": "",
"hostname-char-set": "",
"hostname-char-replacement": ""
...
}
and for example:
As of Kea 1.7.1, there are two parameters which determine if kea-dhcp4
can generate DDNS requests to D2. The existing, ``dhcp-ddns:enable-updates``
parameter which now only controls whether kea-dhcp4 connects to D2.
And the new behavioral parameter, ``ddns-send-updates``, which determines
if DDNS updates are enabled at a given level (i.e global, shared-network,
or subnet). The following table shows how the two parameters function
together:
::
.. table:: Enabling and Disabling DDNS Updates
"Dhcp4": {
"dhcp-ddns": {
"enable-updates": true,
"qualifying-suffix": "example."
},
...
}
The default values for the "dhcp-ddns" section are as follows:
- ``"server-ip": "127.0.0.1"``
- ``"server-port": 53001``
- ``"sender-ip": ""``
- ``"sender-port": 0``
- ``"max-queue-size": 1024``
- ``"ncr-protocol": "UDP"``
- ``"ncr-format": "JSON"``
- ``"override-no-update": false``
- ``"override-client-update": false``
- ``"replace-client-name": "never"``
- ``"generated-prefix": "myhost"``
- ``"hostname-char-set": ""``
- ``"hostname-char-replacement": ""``
+-----------------+--------------------+------------------------------+
| dhcp-ddns: | Global | Outcome |
| enable-updates | ddns-send-udpates | |
+=================+====================+==============================+
| false (default) | false | no updates at any scope |
+-----------------+--------------------+------------------------------+
| false | true (default) | no updates at any scope |
+-----------------+--------------------+------------------------------+
| true | false | updates only at scopes with |
| | | a local value of true for |
| | | ddns-enable-updates |
+-----------------+--------------------+------------------------------+
| true | true | updates at all scopes except |
| | | those with a local value of |
| | | false for ddns-enble-updates |
+-----------------+--------------------+------------------------------+
.. _dhcpv4-d2-io-config:
@ -2877,9 +2923,10 @@ For NCRs to reach the D2 server, kea-dhcp4 must be able to communicate
with it. kea-dhcp4 uses the following configuration parameters to
control this communication:
- ``enable-updates`` - this determines whether kea-dhcp4 will generate NCRs.
By default, this value is false, so DDNS updates are disabled. To
enable DDNS updates set this value to true.
- ``enable-updates`` - As of Kea 1.7.1, this parameter only enables
connectivity to kea-dhcp-ddns such that DDNS updates can be constructed
and sent. It must be true for NCRs to be generated and sent to D2.
It defaults to false.
- ``server-ip`` - the IP address on which D2 listens for requests. The
default is the local loopback interface at address 127.0.0.1.
@ -2942,8 +2989,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 kea-dhcp4
will generate 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.
In general, kea-dhcp4 will generate DDNS update requests when:
@ -2995,7 +3043,7 @@ the DHCP client states that it intends to do the forward DNS updates and
the server should do the reverse updates. By default, kea-dhcp4 will
honor the client's wishes and generate a DDNS request to the D2 server
to update only reverse DNS data. The parameter
``override-client-update`` can be used to instruct the server to
``ddns-override-client-update`` can be used to instruct the server to
override client delegation requests. When this parameter is "true",
kea-dhcp4 will disregard requests for client delegation and generate a
DDNS request to update both forward and reverse DNS data. In this case,
@ -3011,17 +3059,15 @@ configuration file:
::
"Dhcp4": {
"dhcp-ddns": {
"override-client-update": true,
...
},
...
}
"Dhcp4": {
...
"ddns-override-client-update": true,
...
}
The third row in the table above describes the case in which the client
requests that no DNS updates be done. The parameter,
``override-no-update``, can be used to instruct the server to disregard
``ddns-override-no-update``, can be used to instruct the server to disregard
the client's wishes. When this parameter is true, kea-dhcp4 will
generate DDNS update requests to kea-dhcp-ddns even if the client
requests that no updates be done. The N-S-O flags in the server's
@ -3032,10 +3078,8 @@ To override client delegation, issue the following commands:
::
"Dhcp4": {
"dhcp-ddns": {
"override-no-update": true,
...
},
...
"ddns-override-no-update": true,
...
}
@ -3070,7 +3114,7 @@ entries are:
4. If the client provides neither option, then take no DNS action.
These rules can be amended by setting the ``replace-client-name``
These rules can be amended by setting the ``ddns-replace-client-name``
parameter, which provides the following modes of behavior:
- ``never`` - use the name the client sent. If the client sent no name,
@ -3096,17 +3140,15 @@ parameter, which provides the following modes of behavior:
maps to ``"when-present"``, while ``false`` maps to ``"never"``.
For example, to instruct kea-dhcp4 to always generate the FQDN for a
client, set the parameter ``replace-client-name`` to ``always`` as
client, set the parameter ``ddns-replace-client-name`` to ``always`` as
follows:
::
"Dhcp4": {
"dhcp-ddns": {
"replace-client-name": "always",
...
},
...
...
"ddns-replace-client-name": "always",
...
}
The prefix used in the generation of an FQDN is specified by the
@ -3116,36 +3158,33 @@ its value, simply set it to the desired string:
::
"Dhcp4": {
"dhcp-ddns": {
"generated-prefix": "another.host",
...
},
...
"ddns-generated-prefix": "another.host",
...
}
The suffix used when generating an FQDN, or when qualifying a partial
name, is specified by the ``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 you supply a value for qualifying prefix when
DDNS updates are enabled. For obvious reasons, we cannot supply a
meaningful default.
::
"Dhcp4": {
"dhcp-ddns": {
"qualifying-suffix": "foo.example.org",
...
},
...
}
"Dhcp4": {
...
"ddns-qualifying-suffix": "foo.example.org",
...
}
When generating a name, kea-dhcp4 will construct the name in the format:
[**generated-prefix**]-[**address-text**].[**qualifying-suffix**].
[**ddns-generated-prefix**]-[**address-text**].[**ddns-qualifying-suffix**].
where **address-text** is simply the lease IP address converted to a
hyphenated string. For example, if the lease address is 172.16.1.10, the
qualifying suffix "example.com", and the default value is used for
``generated-prefix``, the generated FQDN is:
``ddns-generated-prefix``, the generated FQDN is:
**myhost-172-16-1-10.example.com.**
@ -3178,12 +3217,10 @@ digit, hyphen, or dot with the letter 'x':
::
"Dhcp4": {
"dhcp-ddns": {
"hostname-char-set": "[^A-Za-z0-9.-]",
"hostname-char-replacement": "x",
...
},
...
...
"hostname-char-set": "[^A-Za-z0-9.-]",
"hostname-char-replacement": "x",
...
}
Thus, a client-supplied value of "myhost-$[123.org" would become
@ -3828,7 +3865,7 @@ over the hostname supplied by the client or the autogenerated (from the
IPv4 address) hostname.
The server qualifies the reserved hostname with the value of the
``qualifying-suffix`` parameter. For example, the following subnet
``ddns-qualifying-suffix`` parameter. For example, the following subnet
configuration:
::
@ -3837,6 +3874,7 @@ configuration:
"subnet4": [ {
"subnet": "10.0.0.0/24",
"pools": [ { "pool": "10.0.0.10-10.0.0.100" } ],
"ddns-qualifying-suffix": "example.isc.org.",
"reservations": [
{
"hw-address": "aa:bb:cc:dd:ee:ff",
@ -3846,16 +3884,15 @@ configuration:
}],
"dhcp-ddns": {
"enable-updates": true,
"qualifying-suffix": "example.isc.org."
}
}
will result in assigning the "alice-laptop.example.isc.org." hostname to
the client using the MAC address "aa:bb:cc:dd:ee:ff". If the
``qualifying-suffix`` is not specified, the default (empty) value will
``ddns-qualifying-suffix`` is not specified, the default (empty) value will
be used, and in this case the value specified as a ``hostname`` will be
treated as a fully qualified name. Thus, by leaving the
``qualifying-suffix`` empty it is possible to qualify hostnames for
``ddns-qualifying-suffix`` empty it is possible to qualify hostnames for
different clients with different domain names:
::
@ -5612,7 +5649,7 @@ The following standards are currently supported:
Qualified Domain Name (FQDN) Option*, `RFC 4702
<https://tools.ietf.org/html/rfc4702>`__: The Kea server is able to
handle the Client FQDN option. Also, it is able to use
kea-dhcp-ddns compontent do initiate appropriate DNS Update
kea-dhcp-ddns component do initiate appropriate DNS Update
operations.
- *Resolution of Fully Qualified Domain Name (FQDN) Conflicts among Dynamic Host

255
doc/sphinx/arm/dhcp6-srv.rst
View File

@ -2565,62 +2565,108 @@ NCR contains the following information:
3. The Fully Qualified Domain Name (FQDN), lease address, and DHCID
(information identifying the client associated with the FQDN)
The parameters for controlling the generation of NCRs for submission to D2
are contained in the ``dhcp-ddns`` section of the kea-dhcp6 server
configuration. The mandatory parameters for the DHCP DDNS configuration
are ``enable-updates``, which is unconditionally required, and
``qualifying-suffix``, which has no default value and is required when
``enable-updates`` is set to ``true``. The two (disabled and enabled)
minimal DHCP DDNS configurations are:
Prior to Kea 1.7.1, all parameters for controlling DDNS were within the
global, ``dhcp-ddns`` section of the kea-dhcp6. Beginning with Kea 1.7.1
DDNS related parameters were split into two groups:
1. Connectivity Parameters
These are parameters which specify where and how kea-dhcp4 connects to
and communicates with D2. These parameters can only be specified
within the top-level ``dhcp-ddns`` section in the kea-dhcp4
configuration. The connectivity parameters are listed below:
- ``enable-updates``
- ``server-ip``
- ``server-port``
- ``sender-ip``
- ``sender-port``
- ``max-queue-size``
- ``ncr-protocol``
- ``ncr-format"``
2. Behavioral Parameters
These parameters influence behavior such as how client host names and
FQDN options are handled. They have been moved out of the ``dhcp-ddns``
section so that they may be specified at the global, shared-network,
and/or subnet levels. Furthermore, they are inherited downward from global to
shared-network to subnet. In other words, if a parameter is not specified at
a given level, the value for that level comes from the level above it.
The behavioral parameter as follows:
- ``ddns-send-updates``
- ``ddns-override-no-update``
- ``ddns-override-client-update``
- ``ddns-replace-client-name"``
- ``ddns-generated-prefix``
- ``ddns-qualifying-suffix``
- ``hostname-char-set``
- ``hostname-char-replacement``
.. note::
For backward compatibility, configuration parsing will still recognize
the original behavioral parameters specified in ``dhcp-ddns``. It will
do so by translating the parameter into its global equivalent. If a
parameter is specified both globally and in ``dhcp-ddns``, the latter
value will be ignored. In either case, a log will be emitted explaining what
has occurred. Specifying these values within ``dhcp-ddns`` is deprecated
and support for it may be removed at some future date.
The default configuration and values would appear as follows:
::
"Dhcp6": {
"dhcp-ddns": {
"enable-updates": false
},
...
"dhcp-ddns": {
// Connectivity parameters
"enable-updates": false,
"server-ip": "127.0.0.1",
"server-port":53001,
"sender-ip":"",
"sender-port":0,
"max-queue-size":1024,
"ncr-protocol":"UDP",
"ncr-format":"JSON"
},
// Behavioral parameters (global)
"ddns-send-updates": true,
"ddns-override-no-update": false,
"ddns-override-client-update": false,
"ddns-replace-client-name": "never",
"ddns-generated-prefix": "myhost",
"ddns-qualifying-suffix": "",
"hostname-char-set": "",
"hostname-char-replacement": ""
...
}
and for example:
As of Kea 1.7.1, there are two parameters which determine if kea-dhcp6
can generate DDNS requests to D2. The existing, ``dhcp-ddns:enable-updates``
parameter which now only controls whether kea-dhcp6 connects to D2.
And the new behavioral parameter, ``ddns-send-updates``, which determines
if DDNS updates are enabled at a given level (i.e global, shared-network,
or subnet). The following table shows how the two parameters function
together:
::
.. table:: Enabling and Disabling DDNS Updates
"Dhcp6": {
"dhcp-ddns": {
"enable-updates": true,
"qualifying-suffix": "example."
},
...
}
The default values for the "dhcp-ddns" section are as follows:
- ``"server-ip": "127.0.0.1"``
- ``"server-port": 53001``
- ``"sender-ip": ""``
- ``"sender-port": 0``
- ``"max-queue-size": 1024``
- ``"ncr-protocol": "UDP"``
- ``"ncr-format": "JSON"``
- ``"override-no-update": false``
- ``"override-client-update": false``
- ``"replace-client-name": "never"``
- ``"generated-prefix": "myhost"``
- ``"hostname-char-set": ""``
- ``"hostname-char-replacement": ""``
+-----------------+--------------------+------------------------------+
| dhcp-ddns: | Global | Outcome |
| enable-updates | ddns-send-udpates | |
+=================+====================+==============================+
| false (default) | false | no updates at any scope |
+-----------------+--------------------+------------------------------+
| false | true (default) | no updates at any scope |
+-----------------+--------------------+------------------------------+
| true | false | updates only at scopes with |
| | | a local value of true for |
| | | ddns-enable-updates |
+-----------------+--------------------+------------------------------+
| true | true | updates at all scopes except |
| | | those with a local value of |
| | | false for ddns-enble-updates |
+-----------------+--------------------+------------------------------+
.. _dhcpv6-d2-io-config:
@ -2628,12 +2674,13 @@ DHCP-DDNS Server Connectivity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For NCRs to reach the D2 server, kea-dhcp6 must be able to communicate
with it. kea-dhcp6 uses the following configuration parameters to
with it. kea-dhcp4 uses the following configuration parameters to
control this communication:
- ``enable-updates`` - this determines whether kea-dhcp6 will generate NCRs.
If missing, this value is assumed to be false, so DDNS updates are
disabled. To enable DDNS updates set this value to true.
- ``enable-updates`` - As of Kea 1.7.1, this parameter only enables
connectivity to kea-dhcp-ddns such that DDNS updates can be constructed
and sent. It must be true for NCRs to be generated and sent to D2.
It defaults to false.
- ``server-ip`` - IP address on which D2 listens for requests. The
default is the local loopback interface at address 127.0.0.1.
@ -2753,7 +2800,7 @@ 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, kea-dhcp6 will
honor the client's wishes and generate a DDNS request to D2 to update
only reverse DNS data. The parameter ``override-client-update`` can be
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", kea-dhcp6 will disregard requests for client
delegation and generate a DDNS request to update both forward and
@ -2769,17 +2816,15 @@ configuration file:
::
"Dhcp6": {
"dhcp-ddns": {
"override-client-update": true,
...
},
...
}
"Dhcp6": {
...
"ddns-override-client-update": true,
...
}
The third row in the table above describes the case in which the client
requests that no DNS updates be done. The parameter,
``override-no-update``, can be used to instruct the server to disregard
``ddns-override-no-update``, can be used to instruct the server to disregard
the client's wishes. When this parameter is true, kea-dhcp6 will
generate DDNS update requests to kea-dhcp-ddns even if the client
requests that no updates be done. The N-S-O flags in the server's response to
@ -2789,13 +2834,11 @@ To override client delegation, issue the following commands:
::
"Dhcp6": {
"dhcp-ddns": {
"override-no-update": true,
...
},
...
}
"Dhcp6": {
...
"ddns-override-no-update": true,
...
}
.. _dhcpv6-fqdn-name-generation:
@ -2821,7 +2864,7 @@ entries are:
4. If the client provides neither option, then take no DNS action.
These rules can be amended by setting the ``replace-client-name``
These rules can be amended by setting the ``ddns-replace-client-name``
parameter, which provides the following modes of behavior:
- ``never`` - use the name the client sent. If the client sent no name,
@ -2848,68 +2891,62 @@ parameter, which provides the following modes of behavior:
``false`` maps to ``"never"``.
For example, to instruct kea-dhcp6 to always generate the FQDN for a
client, set the parameter ``replace-client-name`` to ``always`` as
client, set the parameter ``ddns-replace-client-name`` to ``always`` as
follows:
::
"Dhcp6": {
"dhcp-ddns": {
"replace-client-name": "always",
...
},
...
}
"Dhcp6": {
...
"ddsn-replace-client-name": "always",
...
}
The prefix used in the generation of an FQDN is specified by the
``generated-prefix`` parameter. The default value is "myhost". To alter
``ddns-generated-prefix`` parameter. The default value is "myhost". To alter
its value, simply set it to the desired string:
::
"Dhcp6": {
"dhcp-ddns": {
"generated-prefix": "another.host",
...
},
...
}
"Dhcp6": {
...
"ddns-generated-prefix": "another.host",
...
}
The suffix used when generating an FQDN, or when qualifying a partial
name, is specified by the ``qualifying-suffix`` parameter. This
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:
::
"Dhcp6": {
"dhcp-ddns": {
"qualifying-suffix": "foo.example.org",
...
},
...
}
"Dhcp6": {
...
"ddns-qualifying-suffix": "foo.example.org",
...
}
When qualifying a partial name, kea-dhcp6 will construct the name in the
format:
[**candidate-name**].[**qualifying-suffix**].
[**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
qualifying-suffix "example.com", the generated FQDN is:
``ddsn-qualifying-suffix`` "example.com", the generated FQDN is:
**some-computer.example.com.**
When generating the entire name, kea-dhcp6 will construct the name in
the format:
[**generated-prefix**]-[**address-text**].[**qualifying-suffix**].
[**ddns-generated-prefix**]-[**address-text**].[**ddns-qualifying-suffix**].
where **address-text** is simply the lease IP address converted to a
hyphenated string. For example, if the lease address is 3001:1::70E, the
qualifying suffix "example.com", and the default value is used for
``generated-prefix``, the generated FQDN is:
``ddns-generated-prefix``, the generated FQDN is:
**myhost-3001-1--70E.example.com.**
@ -2941,14 +2978,12 @@ The following configuration will replace anything other than a letter,
digit, hyphen, or dot with the letter 'x':
::
"Dhcp4": {
"dhcp-ddns": {
"hostname-char-set": "[^A-Za-z0-9.-]",
"hostname-char-replacement": "x",
...
},
...
}
"Dhcp6": {
...
"hostname-char-set": "[^A-Za-z0-9.-]",
"hostname-char-replacement": "x",
...
}
Thus, a client-supplied value of "myhost-$[123.org" would become
"myhost-xx123.org". Sanitizing is performed only on the portion of the
@ -3365,7 +3400,7 @@ client (via the FQDN option) or the autogenerated (from the IPv6
address) hostname.
The server qualifies the reserved hostname with the value of the
``qualifying-suffix`` parameter. For example, the following subnet
``ddns-qualifying-suffix`` parameter. For example, the following subnet
configuration:
::
@ -3374,6 +3409,7 @@ configuration:
{
"subnet": "2001:db8:1::/48",
"pools": [ { "pool": "2001:db8:1::/80" } ],
"ddns-qualifying-suffix": "example.isc.org.",
"reservations": [
{
"duid": "01:02:03:04:05:0A:0B:0C:0D:0E",
@ -3384,16 +3420,15 @@ configuration:
}
],
"dhcp-ddns": {
"enable-updates": true,
"qualifying-suffix": "example.isc.org."
"enable-updates": true
}
will result in assigning the "alice-laptop.example.isc.org." hostname to
the client using the DUID "01:02:03:04:05:0A:0B:0C:0D:0E". If the
``qualifying-suffix`` is not specified, the default (empty) value will
``ddns-qualifying-suffix`` is not specified, the default (empty) value will
be used, and in this case the value specified as a ``hostname`` will be
treated as a fully qualified name. Thus, by leaving the
``qualifying-suffix`` empty it is possible to qualify hostnames for
``ddns-qualifying-suffix`` empty it is possible to qualify hostnames for
different clients with different domain names:
::