- ``code`` - the server requires either an option name or an option code to
identify an option. This parameter may be left unspecified if the
``name`` parameter is specified. However, this also requires that the
- particular option has a definition (either as a standard option
- or an administrator-created definition for the option using an
+ particular option has a definition (either as a standard option or
+ an administrator-created definition for the option using an
'option-def' structure), as the option definition associates an
option with a particular name. It is possible to configure an option
for which there is no definition (unspecified option format).
Configuration of such options requires the use of the option code.
- ``space`` - if the option space is unspecified it will default to
- 'dhcp4', which is an option space holding standard DHCPv4
- options.
+ 'dhcp4', which is an option space holding standard DHCPv4 options.
- ``data`` - if the option data is unspecified it defaults to an empty
value. The empty value is mostly used for the options which have no
payload (boolean options), but it is legal to specify empty values
for some options which carry variable-length data and for which the
- specification allows a length of 0. For such options, the
- data parameter may be omitted in the configuration.
+ specification allows a length of 0. For such options, the data
+ parameter may be omitted in the configuration.
- ``csv-format`` - if this value is not specified, the server will
assume that the option data is specified as a list of comma-separated
...
}
-Required evaluation can be used to express complex dependencies like subnet membership. It can also be used to reverse the
+Required evaluation can be used to express complex dependencies like
+subnet membership. It can also be used to reverse the
precedence; if an option-data is set in a subnet, it takes precedence
over an option-data in a class. If the option-data is moved to a
required class and required in the subnet, a class evaluated earlier
what has occurred. Specifying these values within ``dhcp-ddns`` is
deprecated and support for it will be removed at some future date.
-The default configuration would appear as follows:
+The default configuration and values would appear as follows:
::
...
}
-As of Kea 1.7.1, there are two parameters which determine whether kea-dhcp4
+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
FQDN while new entries for Client-B will still be added.
Disabling conflict resolution should be done only after careful review of
- specific use cases. The best way to avoid unwanted DNS entries is to
+ specific use cases. The best way to avoid unwanted DNS entries is to
always ensure lease changes are processed through Kea, whether they are
released, expire, or are deleted via the lease-del4 command, prior to
reassigning either FQDNs or IP addresses. Doing so will cause kea-dhcp4
.. note::
-
The DNS entries Kea creates contain a value for TTL (time to live). As of
Kea 1.9.3, kea-dhcp4 calculates that value based on
`RFC 4702, Section 5 <https://tools.ietf.org/html/rfc4702#section-5>`__
::
- "Dhcp4": {
- ...
- "ddns-override-no-update": true,
- ...
- }
+ "Dhcp4": {
+ ...
+ "ddns-override-no-update": true,
+ ...
+ }
kea-dhcp4 will always generate DDNS update requests if the client
request only contains the Host Name option. In addition, it will include
::
- "Dhcp4": {
+ "Dhcp4": {
...
"ddns-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
::
- "Dhcp4": {
- ...
+ "Dhcp4": {
+ ...
"ddns-generated-prefix": "another.host",
- ...
- }
+ ...
+ }
The suffix used when generating an FQDN, or when qualifying a partial
name, is specified by the ``ddns-qualifying-suffix`` parameter. It is
Starting with Kea 1.7.5, the default values are as follows:
- - "hostname-char-set": "[^A-Za-z0-9.-]",
- - "hostname-char-replacement": ""
+ - "hostname-char-set": "[^A-Za-z0-9.-]",
+ - "hostname-char-replacement": ""
This enables sanitizing and omits any character that is not
a letter, digit, hyphen, dot, or null.
digit, hyphen, or dot with the letter 'x':
::
- "Dhcp4": {
+ "Dhcp4": {
...
"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
# DHCPv4 conf
"Dhcp4": {
+
"interfaces-config": {
"interfaces": [ "eno33554984" ]
},
options. Yet another possible use case is to define unique names for
hosts.
-Note that there may be
-cases when a new reservation has been made for a client for an address
-currently in use by another client. We call this situation a "conflict."
+Note that there may be cases when a new reservation has been made for a
+client for an address currently in use by another client. We call this
+situation a "conflict."
These conflicts get resolved automatically over time as described in
subsequent sections. Once the conflict is resolved, the correct client will
receive the reserved configuration when it renews.
.. note::
Global reservations, while useful in certain circumstances, have aspects
- that must be given due consideration when using them, please see
+ that must be given due consideration when using them. Please see
:ref:`reservation4-conflict` for more details.
.. note::
}
]
} ]
- }
+ }
In some cases the host reservations can be used in conjunction with client
classes specified within the Kea configuration. In particular, when a
:ref:`subnet-selection-with-class-reservations4`
for the specific use cases.
-
.. _reservations4-mysql-pgsql-cql:
Storing Host Reservations in MySQL, PostgreSQL, or Cassandra
allocating or renewing a lease for the client. Allowed values are:
- ``all`` - enables both in-pool and out-of-pool host reservation
- types. This setting is the default value, and is the safest and
- most flexible. However, as all checks are conducted, it is also the slowest.
+ types. This setting is the default value, and is the safest and most
+ flexible. However, as all checks are conducted, it is also the slowest.
It does not check against global reservations.
-- ``out-of-pool`` - allows only out-of- pool host reservations. With
+- ``out-of-pool`` - allows only out-of-pool host reservations. With
this setting in place, the server may assume that all host
reservations are for addresses that do not belong to the dynamic
pool. Therefore, it can skip the reservation checks when dealing with
}
}
-
``out-of-pool``:
.. code-block:: json
}
}
-
To activate both ``global`` and ``out-of-pool``, the following combination can
be used:
}
}
-
An example configuration using global reservations is shown below:
.. code-block:: json
::
"Dhcp4:" {
- # This specifies global reservations. They will apply to all subnets that
+ # This specifies global reservations.
+ # They will apply to all subnets that
# have global reservations enabled.
"reservations": [
"hw-address": "01:02:03:04:05:06",
"hostname": "hw-host-fixed",
- # Use of IP addresses in global reservations is risky. If used outside
- # of a matching subnet, such as 192.0.1.0/24, it will result in a broken
- # configuration being handed to the client.
+ # Use of IP addresses in global reservations is risky.
+ # If used outside of a matching subnet, such as 192.0.1.0/24,
+ # it will result in a broken configuration being handed
+ # to the client.
"ip-address": "192.0.1.77"
},
{
{
"name": "kakapo",
"relay": {
- # This relay address is inherited by both subnets.
+ # This relay address is inherited by both subnets.
"ip-addresses": [ "192.1.1.1" ]
},
"subnet4": [
"relay": {
"ip-addresses": [ "10.0.0.1" ]
},
- ...
}
],
- ...
}
If "relay" is specified, the "ip-addresses" parameter within it is
The parameter is expressed in seconds, so the example above will
instruct the server to recycle declined leases after one hour.
-There are several statistics and hook points associated with the Decline
+There are several statistics and hook points associated with the decline
handling procedure. The lease4_decline hook is triggered after the
incoming DHCPDECLINE message has been sanitized and the server is about
to decline the lease. The declined-addresses statistic is increased
after the hook returns (both global and subnet-specific variants). (See
-:ref:`dhcp4-stats` and :ref:`hooks-libraries` for more details on DHCPv4 statistics and Kea
-hook points.)
+:ref:`dhcp4-stats` and :ref:`hooks-libraries`
+for more details on DHCPv4 statistics and Kea hook points.)
Once the probation time elapses, the declined lease is recovered using
the standard expired-lease reclamation procedure, with several
reclaimed-declined-addresses statistics (again in two variants, global
and subnet-specific) are increased.
-A note about statistics: the server does not decrease the
+A note about statistics: The server does not decrease the
assigned-addresses statistics when a DHCPDECLINE is received and
processed successfully. While technically a declined address is no
longer assigned, the primary usage of the assigned-addresses statistic
:class: longtable
:widths: 20 10 70
+
+-------------------------------------------+----------------+------------------------------------+
| Statistic | Data Type | Description |
+===========================================+================+====================================+
Statistics can be retrieved periodically to gain more insight into Kea operations. One tool that
leverages that capability is ISC Stork. See :ref:`stork` for details.
+
.. _dhcp4-ctrl-channel:
Management API for the DHCPv4 Server
"pool": "192.0.2.10 - 192.0.2.20",
# This is pool specific user context
"user-context": { "color": "red" }
- }],
+ } ],
# This is a subnet-specific user context. Any type
# of information can be entered here as long as it is valid JSON.
"devices-registered": 42,
"billing": false
}
- }],
+ } ]
}
Kea does not interpret or use the user-context information; it simply stores it and makes it
}
}
+
Lenient Option Parsing
----------------------
behavior of the server when a particular parameter is not explicitly
specified:
-- ``name`` - the server requires an option name or an option code to
+- ``name`` - the server requires either an option name or an option code to
identify an option. If this parameter is unspecified, the option code
must be specified.
Required evaluation can be used to express complex dependencies like
subnet membership. It can also be used to reverse the
-precedence; if an option-data is set in a subnet it takes precedence
-over an option-data in a class. When option-data is moved to a
+precedence; if an option-data is set in a subnet, it takes precedence
+over an option-data in a class. If the option-data is moved to a
required class and required in the subnet, a class evaluated earlier
may take precedence.
| | | false for ddns-enable-updates |
+-----------------+--------------------+-------------------------------+
-
-Kea 1.9.1 adds two new parameters. The first new parameter is ``ddns-update-on-renew``.
-Normally, when leases are renewed the server will only update DNS if the DNS
+Kea 1.9.1 adds two new parameters. The first new parameter is ``ddns-update-on-renew``.
+Normally, when leases are renewed the server only updates DNS if the DNS
information for the lease (e.g. FQDN, DNS update direction flags) has changed.
Setting ``ddns-update-on-renew`` to true instructs the server to always update
the DNS information when a lease is renewed even if its DNS information has not
-changed. This allows Kea to "self-heal" if it was previously unable
+changed. This allows Kea to "self-heal" if it was previously unable
to add DNS entries or they were somehow lost by the DNS server.
.. note::
considered an invalid character to be replaced (or omitted).
- ``hostname-char-replacement`` - a string of zero or more characters
- with which to replace each invalid character in the host name. An empty
+ with which to replace each invalid character in the host name. An empty
string causes invalid characters to be OMITTED rather than replaced.
.. note::
.. note::
Global reservations, while useful in certain circumstances, have aspects
- that must be given due consideration. Please see
+ that must be given due consideration when using them. Please see
:ref:`reservation6-conflict` for more details.
.. note::
Beginning with Kea 1.9.1 reservation mode was replaced by three
boolean flags ``"reservations-global"``, ``"reservations-in-subnet"``
- and ``"reservations-out-of-pool"`` which allow to configure host
- reservations both global and in a subnet. In such a case a subnet
- host reservation has the preference on a global reservation
+ and ``"reservations-out-of-pool"`` which allows the configuration of
+ host reservations both globally and in a subnet. In such cases a subnet
+ host reservation has preference over a global reservation
when both exist for the same client.
.. _reservation6-conflict:
"data": "2001:db8:1::50"
}
]
- },
- {
+ },
+ {
"name": "reserved-class2",
"option-data": [
{
"client-classes": [ "reserved-class1", "reserved-class2" ]
- } ]
- } ]
+ }
+ ]
+ } ]
}
In some cases the host reservations can be used in conjunction with client
- ``all`` - enables both in-pool and out-of-pool host reservation
types. This setting is the default value, and is the safest and most
- flexible. However, as all checks are conducted, it is also the
- slowest. It does not check against global reservations.
+ flexible. However, as all checks are conducted, it is also the slowest.
+ It does not check against global reservations.
- ``out-of-pool`` - allows only out-of-pool host reservations. With
this setting in place, the server may assume that all host
- ``global`` - allows only global host reservations. With this setting
in place, the server searches for reservations for a client only
among the defined global reservations. If an address is specified,
- the server skips the reservation checks carried out when dealing
- in other modes, thus improving performance. Caution is advised when
+ the server skips the reservation checks carried out when dealing in
+ other modes, thus improving performance. Caution is advised when
using this setting; Kea does not sanity-check the reservations when
``global`` and misconfiguration may cause problems.
- ``reservations-global``: fetch global reservations.
- ``reservations-in-subnet``: fetch subnet reservations. For a shared network
- this includes all subnets member of the shared network.
+ this includes all subnet members of the shared network.
-- ``reservations-out-of-pool``: the makes sense only when the
+- ``reservations-out-of-pool``: this makes sense only when the
``reservations-in-subnet`` flag is true. When ``reservations-out-of-pool``
is true the server may assume that all host reservations are for addresses
that do not belong to the dynamic pool. Therefore, it can skip the reservation
.. _multiple-reservations-same-ip6:
-Multiple Reservations for the same IP
+Multiple Reservations for the Same IP
-------------------------------------
Host Reservations were designed to preclude creation of multiple
When ``ip-reservations-unique`` is set to ``true`` (the default value)
the server ensures that IP reservations are unique for a subnet within
- a single host backend and/or Kea configuration file. It does not guarantee
- that the reservations are unique across multiple backends.
+ a single host backend and/or Kea configuration file. It does not
+ guarantee that the reservations are unique across multiple backends.
The following is the example configuration with two reservations for
"pools": [ { "pool": "2001:db8::1 - 2001:db8::ffff" } ]
},
{
- "subnet": "3ffe:abcd::/64",
- "pools": [ { "pool": "3ffe:abcd::1 - 3ffe:abcd::ffff" } ],
- "relay": {
+ "subnet": "3ffe:abcd::/64",
+ "pools": [ { "pool": "3ffe:abcd::1 - 3ffe:abcd::ffff" } ],
+ "relay": {
# Specifying a different relay address for this
# subnet is a configuration error. In this case
# it should be 2001:db8::1234 or the relay address
# in the previous subnet should be 3ffe:abcd::cafe.
"ip-addresses": [ "3ffe:abcd::cafe" ]
- }
+ }
}
]
}
{
"pool": "2001:db8:1::1-2001:db8:1::ffff"
}
- ],
- "relay": {
- "ip-addresses": [ "3000::1" ]
- }
+ ],
+ "relay": {
+ "ip-addresses": [ "3000::1" ]
+ }
}
]
}
"ip-addresses": [ "3000::1" ]
}
},
-
{
"subnet": "2001:db8:1::/64",
"pools": [
{
"pool": "2001:db8:1::1-2001:db8:1::ffff"
}
- ],
- "relay": {
- "ip-addresses": [ "3000::1" ]
- }
+ ],
+ "relay": {
+ "ip-addresses": [ "3000::1" ]
+ }
}
]
}
"billing-department": 42,
"contact-points": [ "Alice", "Bob" ]
}
- } ],
- ...
+ } ]
}
Kea does not interpret or use the user context information; it simply
projects / thirdparty / kea.git / commitdiff
