Below are some templates to assist in configuring the home network of a power user; they may also be
appropriate for a small office. These templates make the following assumptions:
-- the administrator wants to use a single /24 class of IPv4 addresses.
-- High Availability is desired, so there are two DHCP servers.
-- there are a handful of devices, and some of them (e.g. a printer or NAS) require
+- The administrator wants to use a single /24 class of IPv4 addresses.
+- High Availability (HA) is desired, so there are two DHCP servers.
+- There are a handful of devices, and some of them (e.g. a printer or NAS) require
static addresses or extra options.
-- the administrator does not want to be bothered with database management.
-- the setup is optimized for minimal-to-zero maintenance.
-- performance is not an issue; hundreds of queries per second are not expected.
+- The administrator does not want to be bothered with database management.
+- The setup is optimized for minimal to zero maintenance.
+- Performance is not an issue; hundreds of queries per second are not expected.
- IPv6 is not used.
- DNS updates will not be performed by Kea.
| | | |
+--------+ +--------+
-The CA on host-1 and CA on host-2 both listen on port 8000. The DHCP servers communicate
+The CAs on host-1 and host-2 both listen on port 8000. The DHCP servers communicate
with each other via the CAs, which forward control commands to the DHCP servers over the UNIX domain
sockets.
Deployment Considerations
~~~~~~~~~~~~~~~~~~~~~~~~~
-The setup is not expected to be very performant; most modest hardware will do. There are successful
-deployments on Raspberry Pi platforms. If it is running on a VM, 2GB of RAM with one CPU core should
-be enough. Ubuntu LTS is a choice that is easy to set up and is
+This setup is not expected to be very performant. Most modest hardware will do; Kea has been successfully
+deployed on Raspberry Pi platforms, for example. If it is running on a VM, 2GB of RAM with one CPU core should
+be sufficient. Ubuntu LTS is a choice that is easy to set up and is
low maintenance; however, any Linux or FreeBSD operating system is fine. Less popular systems, such as OpenBSD or
NetBSD, should also work in principle, but they are not regularly tested.
-The assumption is that there are two hosts that are running the Kea setup:
+In this example, there are two hosts running Kea:
- 192.168.1.2 - primary HA server (active, handles all the traffic)
- The reservations are done outside of this dynamic range (depending on the addressing preference,
either 192.168.1.1-192.168.1.99 or 192.168.1.200-192.168.1.254).
-To deploy this setup, conduct the following steps:
+To deploy this setup, perform the following steps:
-1. Install CA and DHCPv4 on host-1, and copy the configuration files to their typical locations.
+1. Install the CA and DHCPv4 daemon on host-1, and copy the configuration files to their typical locations.
They are usually in ``/etc/kea`` on Linux and ``/usr/local/etc/kea`` on FreeBSD, and the files are typically called
- ``kea-ctrl-agent.conf`` and ``kea-dhcp4.conf``. Please consult the start-up scripts for any specific system.
+ ``kea-ctrl-agent.conf`` and ``kea-dhcp4.conf``. Please consult the startup scripts for any specific system.
2. Alter the following to match the local setup:
- - the interface name that Kea should listen on (``interfaces`` in ``interfaces-config``).
+ - The interface name that Kea should listen on (``interfaces`` in ``interfaces-config``).
- - the interface name that is used to access the subnet (``interface`` in ``subnet4``).
+ - The interface name that is used to access the subnet (``interface`` in ``subnet4``).
- - the addressing, if using something other than 192.168.1.0/24. Make sure the CA port
+ - The addressing, if using something other than 192.168.1.0/24. Make sure the CA port
configuration (``http-host`` and ``http-port`` in ``kea-ca.conf``) matches the DHCPv4 server
configuration (``url`` in ``hook-libraries/parameters/high-availability/peers`` in ``kea-dhcp4.conf``).
- - the router option, to match the actual network.
+ - The router option, to match the actual network.
- - the DNS option, to match the actual network.
+ - The DNS option, to match the actual network.
- - the path to the hook libraries. This is a very OS-specific parameter; the library names are
+ - The path to the hook libraries. This is a very OS-specific parameter; the library names are
generally the same everywhere, but the path varies. See :ref:`hooks-libraries-introduction` for details.
3. If using a firewall, make sure host-1 can reach host-2. An easy way to ensure that is to
4. Verify that communication between the hosts works in the opposite direction as well
(host-2 can connect to host-1), by repeating step 3 from host-2 using host-1's IP address and port.
-5. Install the CA and DHCPv4 on host-2, as in steps 1 and 2. The config file for the
+5. Install the CA and DHCPv4 daemon on host-2, as in steps 1 and 2. The config file for the
standby server is very similar to the one on the primary server, other than the definition of
the ``this-server-name`` field (and possibly the interface names).
Possible Extensions
~~~~~~~~~~~~~~~~~~~
-The proposed configuration is somewhat basic, but functional. Once it is set up and running, administrators
+This sample configuration is basic but functional. Once it is set up and running, administrators
may wish to consider the following changes:
-- if there is a local DNS server, DNS updates can be configured via Kea. This requires running a DHCP-DDNS update server
+- If there is a local DNS server, DNS updates can be configured via Kea. This requires running a DHCP-DDNS update server
(``kea-dhcp-ddns``). See :ref:`dhcp-ddns-overview` for details.
-- to run Stateful DHCP for IPv6, a ``kea-dhcp6`` server is necessary. Its configuration
+- To run Stateful DHCP for IPv6, a ``kea-dhcp6`` server is necessary. Its configuration
is very similar to ``kea-dhcp4``, but there are some notable differences: the default gateway is not
configured via the DHCPv6 protocol, but via router advertisements sent by the local router. Also, the
DHCPv6 concept of prefix delegation does not exist in DHCPv4. See :ref:`dhcp6`
for details.
-- to expand the local network, adding a MySQL or PostgreSQL database is a popular solution.
+- To expand the local network, adding a MySQL or PostgreSQL database is a popular solution.
Users can choose to store leases, host reservations, and even most of the configuration
in a database. See :ref:`admin` and the ``lease-database``, ``hosts-database``, and
``config-control`` parameters in :ref:`dhcp4`.
-- to provide more insight into how the DHCP server operates, Kea's RESTful API can query
+- To provide more insight into how the DHCP server operates, Kea's RESTful API can query
for many runtime statistics or even change the configuration during runtime. Users may also
- consider deploying Stork, which is a new but quickly developing dashboard for Kea. See :ref:`stork`
+ consider deploying Stork, which is a rapidly developing dashboard for Kea. See :ref:`stork`
for more information.
-- all Kea users should read :ref:`security`: to learn about various trade-offs between
+- All Kea users should read :ref:`security`: to learn about various trade-offs between
convenience and security in Kea.
MySQL 5.7 vs MySQL 8 vs MariaDB 10 and 11
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In our Kea performance testing MySQL 8 shows 60-90% drop in speed
-in comparison with older MySQL 5.7.
+In our Kea performance testing, MySQL 8 shows a 60-90% drop in speed
+in comparison with MySQL 5.7.
Due to the upcoming MySQL 5.7 EOL, we recommend using MariaDB instead of MySQL 8.
-MySQL 5.7, MySQL 8, MariaDB 10, MariaDB 11 are fully compatible,
-interchangeble and tested with Kea.
+MySQL 5.7, MySQL 8, MariaDB 10, and MariaDB 11 are fully compatible,
+interchangeable, and tested with Kea.
.. _mysql-database-create:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Changing the PostgreSQL internal value ``synchronous_commit`` from the default value
-of ON to OFF can result in gain in Kea performance. On slow systems, the gain can be over 1000%.
-It can be set per-session for testing:
+of ON to OFF can result in significant gains in Kea performance; on slow systems, the gain
+can be over 1000%. It can be set per-session for testing:
.. code-block:: psql
postgres=# SET synchronous_commit = OFF;
-or permanently by command (preferred method):
+or permanently via command (preferred method):
.. code-block:: psql
synchronous_commit = off
-Be aware that changing this value can cause problems during data recovery
-after a crash, so we recommend checking the `PostgreSQL documentation
+Changing this value can cause problems during data recovery
+after a crash, so we recommend a careful read of the `PostgreSQL documentation
<https://www.postgresql.org/docs/current/wal-async-commit.html>`__.
With the default value of ON, PostgreSQL writes changes to disk after every INSERT or UPDATE query
(in Kea terms, every time a client gets a new lease or renews an existing lease). When
-``synchronous_commit`` is set to OFF, PostgreSQL writes the changes with some delay.
-Batching writes gives a substantial performance boost. The trade-off,
-however, is that in the worst-case scenario, all changes in the last moment before crash
-could be lost. Given the fact that Kea is stable software and crashes very rarely,
-most deployments find it a beneficial trade-off.
+``synchronous_commit`` is set to OFF, PostgreSQL adds some delay before writing the changes.
+Batching writes gives a substantial performance boost,
+but in the worst-case scenario, all changes in the last moment before a crash
+could be lost. Since Kea is stable software and crashes very rarely,
+most deployments find the performance benefits outweigh the potential risks.
Using Read-Only Databases With Host Reservations
------------------------------------------------
The ``pkt4_receive`` and ``pkt6_receive`` callouts are called here.
6. When the ``early-global-reservations-lookup`` global parameter is
- configured to ``true``, the process looks global reservations and
+ configured to ``true``, the process looks up global reservations and
partially performs steps 8, 9, and 10. The lookup is limited to
global reservations; if one is found the ``KNOWN`` class is set,
but if none is found the ``UNKNOWN`` class is **not** set.
(and/or prefixes), based on the assigned client classes. The details can
be found in :ref:`hooks-high-availability`.
-The ``SPAWN_`` prefix is used by template classes to generate spawn classes
+The ``SPAWN_`` prefix is used by template classes to generate spawned class
names at runtime. The spawned class name is constructed by prepending the
``SPAWN_`` prefix to the template class name and the evaluated value:
``SPAWN_<template-class-name>_<evaluated-value>``.
-The details can be found in :ref:`classification-configuring`.
+More details can be found in :ref:`classification-configuring`.
The ``BOOTP`` class is used by the BOOTP hook library to classify and
respond to inbound BOOTP queries.
.. note::
- To use a hard to escape character as a delimiter, you can use its ASCII hex value.
- For example you can split by ``single quote`` using ``0x27``:
+ To use a hard-to-escape character as a delimiter, use its ASCII hex value.
+ For example, split by ``single quote`` using ``0x27``:
``split(option[39].text, 0x27, 1)``
Ifelse
packets associated with this class. It is used in DHCPv4 only.
- The ``valid-lifetime``, ``min-valid-lifetime``, and ``max-valid-lifetime`` are
not mandatory and configure the valid lifetime fields for this client class.
- - The ``preferred-lifetime``, ``min-preferred-lifetime`` and
+ - The ``preferred-lifetime``, ``min-preferred-lifetime``, and
``max-preferred-lifetime`` are not mandatory and configure the preferred
lifetime fields for this client class. It is used in DHCPv6 only.
-A valid configuration contains at most one of ``test`` or ``template-test``
-parameters. The ``template-test`` parameter also indicates if the class is a
-template class. If both are provided, the configuration is rejected.
+A valid configuration contains either the ``test`` or ``template-test``
+parameters, or neither, but not both. The ``template-test`` parameter also indicates
+if the class is a template class. If both are provided, the configuration is rejected.
::
...
}
-If the received DHCPv4 packet contains option 61, then the first 3 bytes represent
-value ``foo`` in ASCII, then the spawned class will used the
+If the received DHCPv4 packet contains option 61, then the first three bytes represent
+the value ``foo`` in ASCII, and the spawned class uses the
``SPAWN_Client-ID_foo`` name.
-Both ``SPAWN_Client-ID_foo`` and ``Client-ID`` classes will be associated with
+Both the ``SPAWN_Client-ID_foo`` and ``Client-ID`` classes are associated with
the packet.
.. note ::
}
If the received DHCPv6 packet contains option 1 (client identifier) with hex
-value ``0x0002AABBCCDD``, then the ``SPAWN_Client-ID_foobar`` will be associated
-with the packet. Moreover, if the first 6 bytes represent value ``foobar`` in
-ASCII, then the spawned class will use the ``SPAWN_Client-ID_foobar`` name
+value ``0x0002AABBCCDD``, then the ``SPAWN_Client-ID_foobar`` is associated
+with the packet. Moreover, if the first six bytes represent value ``foobar`` in
+ASCII, then the spawned class uses the ``SPAWN_Client-ID_foobar`` name,
effectively associating the regular class to the packet. In this second case,
-both ``SPAWN_Client-ID_foobar`` and ``Client-ID`` classes will be associated
+both the ``SPAWN_Client-ID_foobar`` and ``Client-ID`` classes are associated
with the packet.
The ``test`` expression on the regular class ``SPAWN_Client-ID_foobar`` is not
mandatory and can be omitted, but it is used here with a different match
Usually the ``test`` and ``template-test`` expressions are evaluated before
subnet selection, but in some cases it is useful to evaluate it later when the
subnet, shared network, or pools are known but output-option processing has not
-yet been done. For this purpose, the ``only-if-required`` flag, which is
+yet been done. For this purpose, the ``only-if-required`` flag, which is
``false`` by default, allows the evaluation of the ``test`` expression or the
``template-test`` expression only when it is required, i.e. in a
``require-client-classes`` list of the selected subnet, shared network, or pool.
The ``require-client-classes`` list, which is valid for shared-network, subnet,
and pool scope, specifies the classes which are evaluated in the second pass
-before output-option processing. The list is built in the reversed precedence
-order of option data, i.e. an option data item in a subnet takes precedence over
-one in a shared network, but required class in a subnet is added after one in a
+before output-option processing. The list is built in reverse-precedence
+order of the option data, i.e. an option data item in a subnet takes precedence over
+one in a shared network, but a required class in a subnet is added after one in a
shared network. The mechanism is related to the ``only-if-required`` flag but it
is not mandatory that the flag be set to ``true``.
.. note ::
The template classes can be used to configure limits which, just like
- options, are associated with the spawned class. This permits configuring
- limits which apply for all packets associated with a class spawned at
+ options, are associated with the spawned class. This permits the configuration of
+ limits that apply to all packets associated with a class spawned at
runtime, according to the ``template-test`` expression in the parent template
- class. For a more detailed description on how to configure limits using the
- limits hooks library see the :ref:`hooks-limits-configuration`.
+ class. For a more detailed description of how to configure limits using the
+ limits hooks library, see :ref:`hooks-limits-configuration`.
For example, using the configuration below, ingress DHCPv6 packets that have
client ID values (in the format expressed by the Kea evaluator) ``foobar``
and ``foofoo`` both amount to the same limit of 60 packets per day, while
other packets that have the first three hextets different than ``foo`` are put
- in separate rate limiting buckets.
+ in separate rate-limiting buckets.
::
It is also possible to have both left and right operands of the evaluated
expression processed at runtime. Expressions related to packets can appear in
-the expression as many times as needed. There is no limit. However, each token
-has a small impact on performance and exceedingly complex expressions may be a
-major bottleneck.
+the expression as many times as needed; there is no limit. However, each token
+has a small impact on performance and excessively complex expressions may cause a
+bottleneck.
::
}
}
-``result`` value is a status code indicating a result of the command. The
+The ``result`` value is a status code indicating a result of the command. The
following general status codes are currently supported:
- ``0`` - the command has been processed successfully.
- ``1`` - a general error or failure has occurred during the command processing.
-- ``2`` - specified command is unsupported by the server receiving it.
+- ``2`` - the specified command is unsupported by the server receiving it.
- ``3`` - the requested operation has been completed but the requested
resource was not found. This status code is returned when a command
returns no resources or affects no resources.
- ``4`` - the well-formed command has been processed but the requested
- changes could not be applied because they were in conflict with the
+ changes could not be applied, because they were in conflict with the
server state or its notion of the configuration.
For example, a well-formed command that requests a subnet that exists
in a server's configuration returns the result 0. If the server encounters
-an error condition, it returns 1. If the command asks for the IPv6 subnet,
+an error condition, it returns 1. If the command asks for an IPv6 subnet,
but was sent to a DHCPv4 server, it returns 2. If the query asks for a
-subnet with ``subnet-id`` that matches no subnets, the result is 3.
+subnet with ``subnet-id`` that has matches, the result is 3.
If the command attempts to update a lease but the specified ``subnet-id``
does not match the identifier in the server's configuration, the result
is 4.
-Hook libraries can sometimes return some additional status codes specific
+Hook libraries can sometimes return additional status codes specific
to their use cases.
The ``text`` field typically appears when the result is non-zero and
server.
- ``-T file`` - specifies a configuration file to be tested. ``kea-dhcp4``
- loads it, checks it, and exits. It performs extra checks beside what ``-t``
- is doing, like establising database connections (lease backend,
- host reservations backend, configuration backend and forensic logging
- backend), hook libraries loading and configuration parsing, etc.
- It does not open unix or TCP/UDP sockets, neither does it open or rotate
- files, as all these actions could interfere with a running process on the
+ loads it, checks it, and exits. It performs extra checks beyond what ``-t``
+ offers, such as establishing database connections (for the lease backend,
+ host reservations backend, configuration backend, and forensic logging
+ backend), loading hook libraries, parsing configurations, etc.
+ It does not open UNIX or TCP/UDP sockets, nor does it open or rotate
+ files, as any of these actions could interfere with a running process on the
same machine.
- ``-v`` - displays the Kea version and exits.
if the new configuration is valid, uses the new configuration.
If the new configuration proves to be invalid, the server retains its
current configuration; however, in some cases a fatal error message is logged
-indicating that the server no longer provides any service: a working
+indicating that the server is no longer providing any service: a working
configuration must be loaded as soon as possible.
.. _dhcp4-configuration:
Tuning Database Timeouts
~~~~~~~~~~~~~~~~~~~~~~~~
-In rare cases, reading or writing to the database may hang. It can be
-caused by a temporary network issue or misconfiguration of the proxy
+In rare cases, reading or writing to the database may hang. This can be
+caused by a temporary network issue, or by misconfiguration of the proxy
server switching the connection between different database instances.
-These situations are rare, but we have received reports from the users
-that Kea can sometimes hang while performing the database IO operations.
+These situations are rare, but users have reported
+that Kea sometimes hangs while performing database IO operations.
Setting appropriate timeout values can mitigate such issues.
MySQL exposes two distinct connection options to configure the read and
"Dhcp4": { "lease-database": { "read-timeout" : 10, "write-timeout": 20, ... }, ... }
-Setting these parameters to 0 is equivalent to not specifying them and
+Setting these parameters to 0 is equivalent to not specifying them, and
causes the Kea server to establish a connection to the database with the
-MySQL defaults. In this case, Kea waits infinitely for the completion of
+MySQL defaults. In this case, Kea waits indefinitely for the completion of
the read and write operations.
-MySQL versions earlier than 5.6 do not support setting timeouts for the
+MySQL versions earlier than 5.6 do not support setting timeouts for
read and write operations. Moreover, the ``read-timeout`` and ``write-timeout``
-parameters can only be specified for the MySQL backend. Setting them for
-any other backend type causes a configuration error.
+parameters can only be specified for the MySQL backend; setting them for
+any other backend database type causes a configuration error.
-Use the ``tcp-user-timeout`` parameter to set a timeout for PostgreSQL
-in seconds. For example:
+To set a timeout in seconds for PostgreSQL, use the ``tcp-user-timeout``
+parameter. For example:
::
The timeouts described here are only effective for TCP connections.
Please note that the MySQL client library used by the Kea servers
typically connects to the database via a UNIX domain socket when the
- ``host`` parameter is ``localhost`` but establishes a TCP connection
+ ``host`` parameter is ``localhost``, but establishes a TCP connection
for ``127.0.0.1``.
assigned as well. This may be invalid in some network configurations. To
avoid this, use the ``min-max`` notation.
-In a subnet whose prefix length is less 24, users may wish to exclude all
-addresses ending in .0 and .255 from being dynamically allocated. For
-instance in the subnet 10.0.0.0/8, exclude 10.x.y.0 and 10.x.y.255 for all
-values of x and y even though only 10.0.0.0 and 10.255.255.255 must be
-excluded according to standards. The `exclude-first-last-24`` configuration
-compatibility flag (:ref:`dhcp4-compatibility`) was introduced in Kea version
-2.3.6 to do this
-automatically rather than having to explicitly configure many pools or
-reservations for fake hosts. When true it applies only to subnets
-prefix lengths less than 24 bits. It defaults to false.
-
-Note that here exclude means to skip them in the free address pickup
-routine of the allocation engine: if a client explicitly requests or
-has a host reservation for an address in .0 or .255 it will get it.
+In a subnet whose prefix length is less than 24, users may wish to exclude all
+addresses ending in .0 and .255 from being dynamically allocated. For
+instance, in the subnet 10.0.0.0/8, an administrator may wish to exclude 10.x.y.0
+and 10.x.y.255 for all
+values of x and y, even though only 10.0.0.0 and 10.255.255.255 must be
+excluded according to RFC standards. The ``exclude-first-last-24`` configuration
+compatibility flag (:ref:`dhcp4-compatibility`) does this
+automatically, rather than requiring explicit configuration of many pools or
+reservations for fake hosts. When ``true``, it applies only to subnets
+with prefix lengths less than 24 bits; the default is ``false``.
+
+In this case, "exclude" means to skip these addresses in the free address pickup
+routine of the allocation engine; if a client explicitly requests or
+has a host reservation for an address in .0 or .255, it will get it.
.. note::
Here are some liberties and limits to the values that subnets and pools can
- take in Kea configurations that are out of the ordinary:
+ take in unusual Kea configurations:
+-------------------------------------------------------------+---------+--------------------------------------------------------------------------------------+
| Kea configuration case | Allowed | Comment |
``192.0.3.0/24``, the value is taken from the subnet-level option data
specification.
-At the opposite of ``always-send`` if the ``never-send`` flag is set to
-``true`` for a particular option the server does not add it to the response.
+Contrary to ``always-send``, if the ``never-send`` flag is set to
+``true`` for a particular option, the server does not add it to the response.
The effect is the same as if the client removed the option code in the
Parameter Request List option (or its equivalent for vendor options):
...
}
-In the example above, ``domain-name-servers`` option is never added to
+In the example above, the ``domain-name-servers`` option is never added to
responses on subnet ``192.0.3.0/24``. ``never-send`` has precedence over
-``always-send`` so if both are true the option is not added.
+``always-send``, so if both are ``true`` the option is not added.
.. note::
The ``always-send`` and ``never-send`` flags are sticky, meaning
they do not follow the usual configuration inheritance rules.
Instead, if they are enabled at least once along the configuration
- inheritance chain, they get applied regardless of them being
- disabled in other places which would usually be more prioritized.
+ inheritance chain, they are applied - even if they are
+ disabled in other places which would normally receive a higher priority.
For instance, if one of the flags is enabled in the global scope,
- but disabled at the subnet level, it will act as enabled,
+ but disabled at the subnet level, it will be enabled,
disregarding the subnet-level setting.
.. note::
- The ``never-send`` is less powerful than the :ref:`hooks-flex-option`,
- for instance it has no effect on options managed by the server itself.
- Both ``always-send`` and ``never-send`` has no effect too on options
+ The ``never-send`` flag is less powerful than :ref:`hooks-flex-option`;
+ for instance, it has no effect on options managed by the server itself.
+ Both ``always-send`` and ``never-send`` have no effect on options
which cannot be requested, for instance from a custom space.
The ``name`` parameter specifies the option name. For a list of
+--------------------+------+----------------------------------------------------------------------+
| remote-id | 2 | Can be used with flex-id to identify hosts. |
+--------------------+------+----------------------------------------------------------------------+
- | link-selection | 5 | If present, is used to select the appropriate subnet. |
+ | link-selection | 5 | If present, used to select the appropriate subnet. |
+--------------------+------+----------------------------------------------------------------------+
| subscriber-id | 6 | Can be used with flex-id to identify hosts. |
+--------------------+------+----------------------------------------------------------------------+
+-------------+--------------+------------------------------------------------------------------------+
| option code | option name | option description |
+=============+==============+========================================================================+
-| 1 | oro | ORO (or Option Request Option) is used by clients to request a list of |
+| 1 | oro | ORO (or Option Request Option), used by clients to request a list of |
| | | options they are interested in. |
+-------------+--------------+------------------------------------------------------------------------+
| 2 | tftp-servers | a list of IPv4 addresses of TFTP servers to be used by the cable modem |
+-------------+--------------+------------------------------------------------------------------------+
-In Kea each vendor is represented by its own vendor space. Since there are
-hundreds of vendors and sometimes they use different option definitions for
+In Kea, each vendor is represented by its own vendor space. Since there are
+hundreds of vendors and they sometimes use different option definitions for
different hardware, it is impossible for Kea to support them all natively.
-Fortunately, it's easy to define support for new vendor options. Let's take an
-example of the Genexis home gateway. This device requires sending the vivso 125
-option with a sub-option 2 that contains a string with the TFTP server URL. To
-support such a device, three steps are needed: first, we need to define option
-definitions that will explain how the option is supposed to be formed. Second,
-we need to define option values. Third, we need to tell Kea when to send those
-specific options, which we can do via client classification.
+Fortunately, it is easy to define support for new vendor options. As an
+example, the Genexis home gateway device requires the vivso 125 option to be
+sent with a sub-option 2 that contains a string with the TFTP server URL. To
+support such a device, three steps are needed: first, establish option
+definitions that explain how the option is supposed to be formed; second,
+define option values; and third, tell Kea when to send those
+specific options, via client classification.
An example snippet of a configuration could look similar to the
following:
with vendor space 25167.
This is also how the Kea server can be configured to send multiple vendor
enterprise numbers and multiple options, specific for each vendor.
-If these options need to be sent by the server regardless if the client
-specified any enterprise number, the ``"always-send": true`` must be configured
+If these options need to be sent by the server regardless of whether the client
+specified any enterprise number, ``"always-send": true`` must be configured
for the option with code 125 (``vivso-suboptions``) for each enterprise number.
::
.. note::
- Multiple vendor enterprise numbers are supported by ``vivso-suboptions``
+ Multiple vendor enterprise numbers are supported by the ``vivso-suboptions``
(code 125) option. The option can contain multiple options for each vendor.
- Kea will honor DOCSIS sub-option 1 (ORO) and will add only requested options
+ Kea honors DOCSIS sub-option 1 (ORO) and adds only requested options
if this sub-option is present in the client request.
Currently only one vendor is supported for the ``vivco-suboptions``
.. note::
In the example above, the data has been wrapped into several lines for clarity,
- but Kea does not support it in the configuration file.
+ but Kea does not support wrapping in the configuration file.
This example illustrates configuring a custom long option (exceeding 255 octets)
-in a reservation. When sending a response, the server will split this option
+in a reservation. When sending a response, the server splits this option
into two options, each with the code 240.
.. note::
- Currently the server does not support storing long options in the databases,
- either host reservations or configuration backend.
+ Currently the server does not support storing long options in databases,
+ either host reservations or the configuration backend.
The server is also able to receive packets with split options (options using
the same option code) and to fuse the data chunks into one option. This is
.. note::
Vendor-Identifying Vendor Options are a special case: for all other
- options an option is identified by its code point, ``vivco-suboptions``
+ options an option is identified by its code point, but ``vivco-suboptions``
(124) and ``vivso-suboptions`` (125) are identified by the pair of
- code and vendor identifier. This has no visible effect for the
- ``vivso-suboptions`` which has for value the vendor identifier but it
- is different for ``vivco-suboptions`` which has for value a record
- with the vendor identifier and a binary value. For instance in:
+ code point and vendor identifier. This has no visible effect for
+ ``vivso-suboptions``, whose value is the vendor identifier, but it
+ is different for ``vivco-suboptions``, where the value is a record
+ with the vendor identifier and a binary value. For instance, in:
::
...
}
-The first ``option-data`` entry does not hide as usual the second one because
-vendor identifiers (1234 and 5678) are different: responses will carry
+The first ``option-data`` entry does not hide the second one, because
+vendor identifiers (1234 and 5678) are different: the responses will carry
two instances of the ``vivco-suboptions`` option, each for a different vendor.
.. _dhcp4-ddns-config:
reassigning either FQDNs or IP addresses. Doing so causes ``kea-dhcp4``
to generate DNS removal requests to D2.
-The DNS entries Kea creates contain a value for TTL (time to live). Since
-Kea 1.9.3, ``kea-dhcp4`` calculates that value based on
+The DNS entries Kea creates contain a value for TTL (time to live).
+``kea-dhcp4`` calculates that value based on
`RFC 4702, Section 5 <https://tools.ietf.org/html/rfc4702#section-5>`__,
which suggests that the TTL value be 1/3 of the lease's lifetime, with
-a minimum value of 10 minutes. In earlier versions, the server set the
-TTL value equal to the lease's valid lifetime.
+a minimum value of 10 minutes.
-Kea 2.3.6 adds a new parameter, ``ddns-ttl-percent``. When specified
-it causes the TTL to be calculated as a simple percentage of the lease's
-life time, using the parameter's value as the percentage. It is specified
+The parameter ``ddns-ttl-percent``, when specified,
+causes the TTL to be calculated as a simple percentage of the lease's
+lifetime, using the parameter's value as the percentage. It is specified
as a decimal percent (e.g. .25, .75, 1.00) and may be specified at the
-global, shared-network, and subnet levels. By default it is unspecified.
+global, shared-network, and subnet levels. By default it is unspecified.
.. _dhcpv4-d2-io-config:
When set to ``true``, information relevant to the DHCPREQUEST asking for the lease is
added into the lease's user-context as a map element labeled "ISC". Since
Kea version 2.3.2, when the DHCPREQUEST received contains the option
-(DHCP Option 82) the map contains the ``relay-agent-info`` map
-with the content option (DHCP Option 82) in the ``sub-options`` entry and
-when present the ``remote-id`` and ``relay-id`` options.
-Since DHCPREQUESTs sent as renewals will likely not contain this
+(DHCP Option 82), the map contains the ``relay-agent-info`` map
+with the content option (DHCP Option 82) in the ``sub-options`` entry and,
+when present, the ``remote-id`` and ``relay-id`` options.
+Since DHCPREQUESTs sent as renewals are not likely to contain this
information, the values taken from the last DHCPREQUEST that did contain it are
retained on the lease. The lease's user-context looks something like this:
- ``fix`` - fix some common inconsistencies and upgrade extended info
using the old format to the new one. It is the default level and is
- convenient when Lease Query hook library is not loaded.
+ convenient when the Leasequery hook library is not loaded.
- ``strict`` - fix all inconsistencies which have an impact on the (Bulk)
- Lease Query hook library.
+ Leasequery hook library.
- ``pedantic`` - enforce full conformance to the format produced by the
- Kea code, for instance no extra entries are allowed with the exception
+ Kea code; for instance, no extra entries are allowed with the exception
of ``comment``.
.. note::
- Currently this feature is implemented only for the memfile
+ This feature is currently implemented only for the memfile
backend. The sanity check applies to the lease database in memory,
- not to the lease file, i.e. inconsistent leases will stay in the lease
+ not to the lease file, i.e. inconsistent leases stay in the lease
file.
.. _dhcp4-multi-threading-settings:
parallel. The default is ``true``.
- ``thread-pool-size`` - specify the number of threads to process packets in
- parallel. It may be set to ``0`` (auto-detect), or any positive number which
+ parallel. It may be set to ``0`` (auto-detect), or any positive number that
explicitly sets the thread count. The default is ``0``.
- ``packet-queue-size`` - specify the size of the queue used by the thread
pool to process packets. It may be set to ``0`` (unlimited), or any positive
- number explicitly sets the queue size. The default is ``64``.
+ number that explicitly sets the queue size. The default is ``64``.
An example configuration that sets these parameters looks as follows:
Temporary Allocation on DHCPDISCOVER
------------------------------------
-By default, kea-dhcp4 does not allocate or store a lease when offering an address
-to a client in response to a DHCPDISCOVER. In general, kea-dhcp4, can fulfill client
+By default, ``kea-dhcp4`` does not allocate or store a lease when offering an address
+to a client in response to a DHCPDISCOVER. In general, ``kea-dhcp4`` can fulfill client
demands faster by deferring lease allocation and storage until it receives DHCPREQUESTs
-for them. Release 2.3.6 added a new parameter to kea-dhcp4, ``offer-lifetime``, which
+for them. Release 2.3.6 added a new parameter to ``kea-dhcp4``, ``offer-lifetime``, which
(when not zero) instructs the server to allocate and persist a lease when generating a
-DHCPOFFER and:
+DHCPOFFER. In addition:
- The persisted lease's lifetime is equal to ``offer-lifetime`` (in seconds).
-- The lifetime sent to the client in the DHCPOFFER via option 51 will still be based
- on ``valid-lifetime``. This avoids issues with clients that may reject offers whose
+- The lifetime sent to the client in the DHCPOFFER via option 51 is still based
+ on ``valid-lifetime``. This avoids issues with clients that may reject offers whose
lifetimes they perceive as too short.
-- DDNS updates are not performed. As with the default behavior, that occurs on DHCPREQUEST.
+- DDNS updates are not performed. As with the default behavior, those updates occur on DHCPREQUEST.
- Updates are not sent to HA peers.
- Lease caching, if enabled, is honored.
-- In sites running multiple instances of kea-dhcp4 against a single, shared lease store, races
+- In sites running multiple instances of ``kea-dhcp4`` against a single, shared lease store, races
for given address values are lost during DHCPDISCOVER processing rather than during DHCPREQUEST
- processing. Servers that lose the race for the address will simply not respond to the client
- rather than NAK them. The client in turn will simply retry DHCPDISCOVER. This should reduce
+ processing. Servers that lose the race for the address simply do not respond to the client,
+ rather than NAK them. The client in turn simply retries its DHCPDISCOVER. This should reduce
the amount of traffic such conflicts incur.
-- Clients repeating DHCPDISCOVERs will be offered the same address each time.
+- Clients repeating DHCPDISCOVERs are offered the same address each time.
An example subnet configuration is shown below:
}
],
-Here ``offer-lifetime`` has been configured to be 60 seconds with a ``valid-lifetime``
-of 2000 seconds. This instructs kea-dhcp4 to persist leases for 60 seconds when
-sending them back in DHCPOFFERs and then extending them to 2000 seconds when clients
+Here ``offer-lifetime`` has been configured to be 60 seconds, with a ``valid-lifetime``
+of 2000 seconds. This instructs ``kea-dhcp4`` to persist leases for 60 seconds when
+sending them back in DHCPOFFERs, and then extend them to 2000 seconds when clients
DHCPREQUEST them.
-The value, which defaults to zero, is supported at the global, shared-network, subnet,
-and class levels. Choosing an appropriate value for offer-lifetime is extremely
-site-dependent but a value between 60 and 120 seconds would be a reasonable starting
+The value, which defaults to 0, is supported at the global, shared-network, subnet,
+and class levels. Choosing an appropriate value for ``offer-lifetime`` is extremely
+site-dependent, but a value between 60 and 120 seconds is a reasonable starting
point.
.. _host-reservation-v4:
An address assigned via global host reservation must be feasible for the
subnet the server selects for the client. In other words, the address must
-lie within the subnet otherwise it will be ignored and the server will
-attempt to dynamically allocate an address. In the event the selected subnet
-belongs to a shared-network the server will check for feasibility against
-the subnet's siblings, selecting the first in-range subnet. If no such
-subnet exists, the server will fallback to dynamically allocating the address.
+lie within the subnet; otherwise, it is ignored and the server will
+attempt to dynamically allocate an address. If the selected subnet
+belongs to a shared network, the server checks for feasibility against
+the subnet's siblings, selecting the first in-range subnet. If no such
+subnet exists, the server falls back to dynamically allocating the address.
.. note::
Prior to release 2.3.5, the server did not perform feasibility checks on
- globally reserved addresses. This allowed the server to be configured to
- hand out nonsensical leases for arbitrary address values.
+ globally reserved addresses, which allowed the server to be configured to
+ hand out nonsensical leases for arbitrary address values. Later versions
+ of Kea perform these checks.
To use global host reservations, a configuration similar to the
following can be used:
-----------------------------------------
Starting with Kea 2.3.5, it is possible to define a host reservation that
-contains just an identifier, without any address, options or values. In some
-deployments this is useful, as the hosts that have a reservation will belong to
-KNOWN class, while others won't. This can be used as a basic access control.
+contains just an identifier, without any address, options, or values. In some
+deployments this is useful, as the hosts that have a reservation belong to
+the KNOWN class while others do not. This can be used as a basic access control
+mechanism.
-The following example demonstrates this concept. There is a single IPv4 subnet
-and all clients will get an address from it. However, only known (those that
+The following example demonstrates this concept. It indicates a single IPv4 subnet
+and all clients will get an address from it. However, only known clients (those that
have reservations) will get their default router configured.
::
]
}
-This concept can be extended further. A good real life scenario is a list of
-customers of an ISP. Some of them haven't paid their bills. A new class can be
-defined to use alternative default router, that instead of relaying traffic,
-redirects customers to a captive portal urging them to pay their bills.
+This concept can be extended further. A good real-life scenario might be a
+situation where some customers of an ISP have not paid their bills. A new class can be
+defined to use an alternative default router that, instead of relaying traffic,
+redirects those customers to a captive portal urging them to bring their accounts up to date.
::
-----------------------------
With ``"ignore-dhcp-server-identifier": true``, the server does not check the
-address in the DHCP Server Identifier option i.e. whether a query is sent
+address in the DHCP Server Identifier option, i.e. whether a query is sent
to this server or another one (and in the second case dropping the query).
.. code-block:: json
-------------------------
With ``"ignore-rai-link-selection": true``, Relay Agent Information Link
-Selection sub-option data will not be used for subnet selection. This will use
-normal subnet selection logic instead of attempting to use the subnet specified
-by the sub-option. This option is not RFC compliant and is set to ``false`` by
+Selection sub-option data is not used for subnet selection. In this case,
+normal logic drives the subnet selection, instead of attempting to use the subnet specified
+by the sub-option. This option is not RFC-compliant and is set to ``false`` by
default. Setting this option to ``true`` can help with subnet selection in
-certain scenarios, for example, when your DHCP relays do not allow you to
+certain scenarios; for example, when DHCP relays do not allow the administrator to
specify which sub-options are included in the Relay Agent Information option,
and include incorrect Link Selection information.
}
}
-Exclude First Last Addresses in Subnets bigger than /24
+Exclude First Last Addresses in Subnets Bigger Than /24
-------------------------------------------------------
The ``exclude-first-last-24`` compatibility flag is described in
A DHCP server follows a complicated algorithm to select an IPv4 address for a client.
It prefers assigning specific addresses requested by the client and the addresses for
-which the client has reservations. If the client requests no particular address,
-has no reservations, or other clients already use these addresses, the server must
+which the client has reservations. If the client requests no particular address and
+has no reservations, or other clients are already using any requested addresses, the server must
find another available address within the configured pools. A server function called
-"allocator" is responsible in Kea for finding an available address in such a case.
+an "allocator" is responsible in Kea for finding an available address in such a case.
-Kea DHCPv4 server provides configuration parameters to select different allocators
-(allocation strategies) at the global, shared network, and subnet levels.
+The Kea DHCPv4 server provides configuration parameters to select different allocators
+at the global, shared-network, and subnet levels.
Consider the following example:
.. code-block:: json
}
}
-It overrides the default iterative allocation strategy at the global level and
+This allocator overrides the default iterative allocation strategy at the global level and
selects the random allocation instead. The random allocation will be used
-for the subnet with id 2. The iterative allocation will be used for the subnet
-with id 1.
+for the subnet with ID 2, while the iterative allocation will be used for the subnet
+with ID 1.
-In the following sections, we describe the supported allocators and recommend
-when to use them.
+The following sections describe the supported allocators and
+their recommended uses.
.. note::
---------------------
In the table below, we briefly compare the supported allocators. The
-detailed allocators' descriptions are in further sections.
+detailed allocators' descriptions are in later sections.
.. table:: Comparison of the lease allocators supported by Kea DHCPv4
Iterative Allocator
-------------------
-It is the default allocator used by the Kea DHCPv4 server. It remembers the
-last offered address and offers this address increased by 1 to the next client.
+This is the default allocator used by the Kea DHCPv4 server. It remembers the
+last offered address and offers this address, increased by one, to the next client.
For example, it may offer addresses in this order: ``192.0.2.10``, ``192.0.2.11``,
``192.0.2.12``, and so on. The time to find and offer the next address is very
-short. Thus, it is the highly performant allocator when the pool utilization
+short; thus, this is the most performant allocator when pool utilization
is low and there is a high probability that the next address is available.
The iterative allocation underperforms when multiple DHCP servers share a lease
database or are connected to a cluster. The servers tend to offer and allocate
-the same blocks of addresses to different clients independently. It causes many
+the same blocks of addresses to different clients independently, which causes many
allocation conflicts between the servers and retransmissions by clients. A random
-allocation deals with it by dispersing the allocations order.
+allocation addresses this issue by dispersing the allocation order.
Random Allocator
----------------
The random allocator uses a uniform randomization function to select offered
-addresses from the subnet pools. It improves the server's resilience against
-attacks based on allocation predictability. In addition, the random allocation
-is suitable in deployments where multiple servers are connected to a shared
+addresses from subnet pools. It is suitable in deployments where multiple servers
+are connected to a shared
database or a database cluster. By dispersing the offered addresses, the servers
minimize the risk of allocating the same address to two different clients at
-the same or nearly the same time.
+the same or nearly the same time. In addition, it improves the server's resilience against
+attacks based on allocation predictability.
The random allocator is, however, slightly slower than the iterative allocator.
Moreover, it increases the server's memory consumption because it must remember
randomized addresses to avoid offering them repeatedly. Memory consumption grows
-with the number of offered addresses. In other words, larger pools and more
+with the number of offered addresses; in other words, larger pools and more
clients increase memory consumption by random allocation.
-The following configuration snipet shows how to select the random allocator
+The following configuration snippet shows how to select the random allocator
for a subnet:
.. code-block:: json
Free Lease Queue Allocator
--------------------------
-It is a sophisticated allocator whose use should be considered in subnets
+This is a sophisticated allocator whose use should be considered in subnets
with highly utilized address pools. In such cases, it can take a considerable
-amount of time for the iterative and random allocator to find an available
-address because they have to repeatedly check if there is a valid lease for
-the address they will offer. The number of checks can be as high as the number
-of addresses in the subnet when the subnet pools are exhausted. It has a
+amount of time for the iterative or random allocator to find an available
+address, because they must repeatedly check whether there is a valid lease for
+an address they will offer. The number of checks can be as high as the number
+of addresses in the subnet when the subnet pools are exhausted, which can have a
direct negative impact on the DHCP response time for each request.
The Free Lease Queue (FLQ) allocator tracks lease allocations and de-allocations
and maintains a running list of available addresses for each address pool.
-It allows for picking an available lease in a constant time, regardless of
+It allows an available lease to be selected within a constant time, regardless of
the subnet pools' utilization. The allocator continuously updates the list of
-free leases by removing the allocated leases and adding the released or
+free leases by removing any allocated leases and adding released or
reclaimed ones.
-The following configuration snipet shows how to select the FLQ allocator
+The following configuration snippet shows how to select the FLQ allocator
for a subnet:
.. code-block:: json
}
-There are several tradeoffs that the administrator should take into account
-before using this allocator. It can heavily impact the server's
-startup and reconfiguration time because the allocator has to populate the
-list of free leases for each subnet where it is used. The delays can be
+There are several considerations that the administrator should take into account
+before using this allocator. The FLQ allocator can heavily impact the server's
+startup and reconfiguration time, because the allocator has to populate the
+list of free leases for each subnet where it is used. These delays can be
observed both during the configuration reload and when the subnets are
created using the ``subnet_cmds`` hook. The allocator increases the
-memory consumption to hold the list of free leases, and it is proportional
+memory consumption to hold the list of free leases, proportional
to the total size of the address pools for which this allocator is used.
-Finally, the lease reclamation must be enabled with a low value of the
-``reclaim-timer-wait-time`` parameter to ensure that the server frequently
+Finally, lease reclamation must be enabled with a low value of the
+``reclaim-timer-wait-time`` parameter, to ensure that the server frequently
collects expired leases and makes them available for allocation via the
-allocator's free lease queue. Expired leases are not considered free by
+free lease queue. Expired leases are not considered free by
the allocator until they are reclaimed by the server. See
:ref:`lease-reclamation` for more details about the lease reclamation process.
-Due to the above tradeoffs, we recommend that the FLQ allocator is selected
-only after careful consideration. For example, using it for a subnet with
+We recommend that the FLQ allocator be selected
+only after careful consideration. For example, using it for a subnet with a
``/8`` pool may delay the server's startup by 15 seconds or more. On the
other hand, the startup delay and the memory consumption increase should
-be acceptable for subnets with the ``/16`` pool or smaller. We also recommend
-specifying some other allocator type in the global configuration settings
-and overriding this selection at the subnet or shared network level to use
-the FLQ allocator for selected subnets only. That way, when a new subnet is
-added without the allocator specification, the global setting is used, thus
+be acceptable for subnets with a ``/16`` pool or smaller. We also recommend
+specifying another allocator type in the global configuration settings
+and overriding this selection at the subnet or shared-network level, to use
+the FLQ allocator only for selected subnets. That way, when a new subnet is
+added without an allocator specification, the global setting is used, thus
avoiding unnecessary impact on the server's startup time.
-Similarly to the random allocator, the FLQ allocator offers leases in
+Like the random allocator, the FLQ allocator offers leases in
random order, which makes it suitable for use with a shared lease database.
server.
- ``-T file`` - specifies a configuration file to be tested. ``kea-dhcp6``
- loads it, checks it, and exits. It performs extra checks beside what ``-t``
- is doing, like establising database connections (lease backend,
- host reservations backend, configuration backend and forensic logging
- backend), hook libraries loading and configuration parsing, etc.
- It does not open unix or TCP/UDP sockets, neither does it open or rotate
- files, as all these actions could interfere with a running process on the
+ loads it, checks it, and exits. It performs extra checks beyond what ``-t``
+ offers, such as establising database connections (for the lease backend,
+ host reservations backend, configuration backend, and forensic logging
+ backend), loading hook libraries, parsing configurations, etc.
+ It does not open UNIX or TCP/UDP sockets, nor does it open or rotate
+ files, as any of these actions could interfere with a running process on the
same machine.
- ``-v`` - displays the Kea version and exits.
if the new configuration is valid, uses the new configuration.
If the new configuration proves to be invalid, the server retains its
current configuration; however, in some cases a fatal error message is logged
-indicating that the server no longer provides any service: a working
+indicating that the server is no longer providing any service: a working
configuration must be loaded as soon as possible.
.. _dhcp6-configuration:
Tuning Database Timeouts
~~~~~~~~~~~~~~~~~~~~~~~~
-In rare cases, reading or writing to the database may hang. It can be
-caused by a temporary network issue or misconfiguration of the proxy
+In rare cases, reading or writing to the database may hang. This can be
+caused by a temporary network issue, or by misconfiguration of the proxy
server switching the connection between different database instances.
-These situations are rare, but we have received reports from the users
-that Kea can sometimes hang while performing the database IO operations.
+These situations are rare, but users have reported
+that Kea sometimes hangs while performing database IO operations.
Setting appropriate timeout values can mitigate such issues.
MySQL exposes two distinct connection options to configure the read and
"Dhcp6": { "lease-database": { "read-timeout" : 10, "write-timeout": 20, ... }, ... }
-Setting these parameters to 0 is equivalent to not specifying them and
+Setting these parameters to 0 is equivalent to not specifying them, and
causes the Kea server to establish a connection to the database with the
-MySQL defaults. In this case, Kea waits infinitely for the completion of
+MySQL defaults. In this case, Kea waits indefinitely for the completion of
the read and write operations.
-MySQL versions earlier than 5.6 do not support setting timeouts for the
+MySQL versions earlier than 5.6 do not support setting timeouts for
read and write operations. Moreover, the ``read-timeout`` and ``write-timeout``
-parameters can only be specified for the MySQL backend. Setting them for
-any other backend type causes a configuration error.
+parameters can only be specified for the MySQL backend; setting them for
+any other backend database type causes a configuration error.
-Use the ``tcp-user-timeout`` parameter to set a timeout for PostgreSQL
-in seconds. For example:
+To set a timeout in seconds for PostgreSQL, use the ``tcp-user-timeout``
+parameter. For example:
::
The timeouts described here are only effective for TCP connections.
Please note that the MySQL client library used by the Kea servers
typically connects to the database via a UNIX domain socket when the
- ``host`` parameter is ``localhost`` but establishes a TCP connection
+ ``host`` parameter is ``localhost``, but establishes a TCP connection
for ``127.0.0.1``.
previous example, further assume that 2001:db8:1:0:5::/80 should also be
managed by the server. It could be written as 2001:db8:1:0:5:: to
2001:db8:1::5:ffff:ffff:ffff, but typing so many ``f`` characters is cumbersome.
-It can be expressed more simply as 2001:db8:1:0:5::/80. Both formats are
-supported by ``Dhcp6`` and can be mixed in the pool list. For example,
+The pool can be expressed more simply as 2001:db8:1:0:5::/80. Both formats are
+supported by ``Dhcp6`` and they can be mixed in the pool list. For example,
the following pools could be defined:
::
``2001:db8:1::/64``, the value is taken from the subnet-level option data
specification.
-At the opposite of ``always-send`` if the ``never-send`` flag is set to
-``true`` for a particular option the server does not add it to the response.
+Contrary to ``always-send``, if the ``never-send`` flag is set to
+``true`` for a particular option, the server does not add it to the response.
The effect is the same as if the client removed the option code in the
-Option Request Option (or its equivalent for vendor options), as in:
+Option Request Option (or its equivalent for vendor options):
::
In the example above, the ``dns-server`` option is never added to responses
on subnet ``2001:db8:1::/64``. ``never-send`` has precedence over
-``always-send`` so if both are true the option is not added.
+``always-send``, so if both are ``true`` the option is not added.
.. note::
The ``always-send`` and ``never-send`` flags are sticky, meaning
they do not follow the usual configuration inheritance rules.
Instead, if they are enabled at least once along the configuration
- inheritance chain, they get applied regardless of them being
- disabled in other places which would usually be more prioritized.
+ inheritance chain, they are applied - even if they are
+ disabled in other places which would normally receive a higher priority.
For instance, if one of the flags is enabled in the global scope,
- but disabled at the subnet level, it will act as enabled,
+ but disabled at the subnet level, it will be enabled,
disregarding the subnet-level setting.
.. note::
- The ``never-send`` is less powerful than the :ref:`hooks-flex-option`,
- for instance it has no effect on options managed by the server itself.
- Both ``always-send`` and ``never-send`` has no effect too on options
+ The ``never-send`` flag is less powerful than :ref:`hooks-flex-option`;
+ for instance, it has no effect on options managed by the server itself.
+ Both ``always-send`` and ``never-send`` have no effect on options
which cannot be requested, for instance from a custom space.
It is possible to override options on a per-subnet basis. If clients
.. note::
Multiple instances of the ``vendor-class`` (code 16) and
- instances of the ``vendor-opts`` (code 17) options can be
+ ``vendor-opts`` (code 17) options can be
specified. Specifying multiple options with different enterprise
- numbers is now supported by Kea.
+ numbers is supported by Kea.
.. _dhcp6-option-spaces:
reassigning either FQDNs or IP addresses. Doing so causes ``kea-dhcp6``
to generate DNS removal requests to D2.
-The DNS entries Kea creates contain a value for TTL (time to live). Since
-Kea 1.9.3, ``kea-dhcp6`` calculates that value based on
+The DNS entries Kea creates contain a value for TTL (time to live).
+``kea-dhcp6`` calculates that value based on
`RFC 4702, Section 5 <https://tools.ietf.org/html/rfc4702#section-5>`__,
which suggests that the TTL value be 1/3 of the lease's lifetime, with
-a minimum value of 10 minutes. In earlier versions, the server set the
-TTL value equal to the lease's valid lifetime.
+a minimum value of 10 minutes.
-Kea 2.3.6 adds a new parameter, ``ddns-ttl-percent``. When specified
-it causes the TTL to be calculated as a simple percentage of the lease's
-life time, using the parameter's value as the percentage. It is specified
+The parameter ``ddns-ttl-percent``, when specified,
+causes the TTL to be calculated as a simple percentage of the lease's
+lifetime, using the parameter's value as the percentage. It is specified
as a decimal percent (e.g. .25, .75, 1.00) and may be specified at the
global, shared-network, and subnet levels. By default it is unspecified.
.. note::
- Before Kea version 2.3.2 the entry was named ``relays``, remote and relay
+ Prior to Kea version 2.3.2, this entry was named ``relays``; remote and relay
identifier options were not decoded.
.. note::
- ``fix`` - fix some common inconsistencies and upgrade extended info
using the old format to the new one. It is the default level and is
- convenient when Lease Query hook library is not loaded.
+ convenient when the Leasequery hook library is not loaded.
- ``strict`` - fix all inconsistencies which have an impact on the (Bulk)
- Lease Query hook library.
+ Leasequery hook library.
- ``pedantic`` - enforce full conformance to the format produced by the
- Kea code, for instance no extra entries are allowed with the exception
+ Kea code; for instance, no extra entries are allowed with the exception
of ``comment``.
.. note::
- Currently this feature is implemented only for the memfile
+ This feature is currently implemented only for the memfile
backend. The sanity check applies to the lease database in memory,
- not to the lease file, i.e. inconsistent leases will stay in the lease
+ not to the lease file, i.e. inconsistent leases stay in the lease
file.
.. _dhcp6-multi-threading-settings:
parallel. The default is ``true``.
- ``thread-pool-size`` - specify the number of threads to process packets in
- parallel. It may be set to ``0`` (auto-detect), or any positive number which
+ parallel. It may be set to ``0`` (auto-detect), or any positive number that
explicitly sets the thread count. The default is ``0``.
- ``packet-queue-size`` - specify the size of the queue used by the thread
pool to process packets. It may be set to ``0`` (unlimited), or any positive
- number explicitly sets the queue size. The default is ``64``.
+ number that explicitly sets the queue size. The default is ``64``.
An example configuration that sets these parameters looks as follows:
An address assigned via global host reservation must be feasible for the
subnet the server selects for the client. In other words, the address must
-lie within the subnet otherwise it will be ignored and the server will
-attempt to dynamically allocate an address. In the event the selected subnet
-belongs to a shared-network the server will check for feasibility against
-the subnet's siblings, selecting the first in-range subnet. If no such
-subnet exists, the server will fallback to dynamically allocating the address.
+lie within the subnet; otherwise, it is ignored and the server will
+attempt to dynamically allocate an address. If the selected subnet
+belongs to a shared network, the server checks for feasibility against
+the subnet's siblings, selecting the first in-range subnet. If no such
+subnet exists, the server falls back to dynamically allocating the address.
This does not apply to globally reserved prefixes.
.. note::
Prior to release 2.3.5, the server did not perform feasibility checks on
- globally reserved addresses. This allowed the server to be configured to
- hand out nonsensical leases for arbitrary address values.
+ globally reserved addresses, which allowed the server to be configured to
+ hand out nonsensical leases for arbitrary address values. Later versions
+ of Kea perform these checks.
To use global host reservations, a configuration similar to the
following can be used:
-----------------------------------------
Starting with Kea 2.3.5, it is possible to define a host reservation that
-contains just an identifier, without any address, options or values. In some
-deployments this is useful, as the hosts that have a reservation will belong to
-KNOWN class, while others won't. This can be used as a basic access control.
+contains just an identifier, without any address, options, or values. In some
+deployments this is useful, as the hosts that have a reservation belong to
+the KNOWN class while others do not. This can be used as a basic access control
+mechanism.
-The following example demonstrates this concept. There is a single IPv6 subnet
-and all clients will get an address from it. However, only known (those that
+The following example demonstrates this concept. It indicates a single IPv6 subnet
+and all clients will get an address from it. However, only known clients (those that
have reservations) will get their default DNS server configured.
::
]
}
-This concept can be extended further. A good real life scenario is a list of
-customers of an ISP. Some of them haven't paid their bills. A new class can be
-defined to use alternative default DNS server, that instead of giving access
-to Internet, redirects customers to a captive portal urging them to pay
-their bills.
+This concept can be extended further. A good real-life scenario might be a
+situation where some customers of an ISP have not paid their bills. A new class can be
+defined to use an alternative default DNS server that, instead of giving access
+to the Internet, redirects those customers to a captive portal urging them to bring
+their accounts up to date.
::
A DHCP server follows a complicated algorithm to select a DHCPv6 lease for a client.
It prefers assigning specific addresses or delegated prefixes requested by the client
and the ones for which the client has reservations. If the client requests no particular
-lease, has no reservations, or other clients already use these leases, the server must
+lease and has no reservations, or other clients are already using any requested leases, the server must
find another available lease within the configured pools. A server function called
-"allocator" is responsible in Kea for finding an available leases in such a case.
+an "allocator" is responsible in Kea for finding an available lease in such a case.
-Kea DHCPv6 server provides configuration parameters to select different allocators
-(allocation strategies) at the global, shared network, and subnet levels. It also
+The Kea DHCPv6 server provides configuration parameters to select different allocators
+at the global, shared-network, and subnet levels. It also
allows for selecting different allocation strategies for address assignments and
prefix delegation.
-
Consider the following example:
.. code-block:: json
}
}
-The iterative allocator is globally selected for address assignments. The
+The iterative allocator is globally selected for address assignments, while the
random allocator is globally selected for prefix delegation. These settings
are selectively overridden at the subnet level.
-
-In the following sections, we describe the supported allocators and recommend
-when to use them.
+The following sections describe the supported allocators and their
+recommended uses.
.. note::
---------------------
In the table below, we briefly compare the supported allocators. The
-detailed allocators' descriptions are in further sections.
+detailed allocators' descriptions are in later sections.
.. table:: Comparison of the lease allocators supported by Kea DHCPv6
Iterative Allocator
-------------------
-It is the default allocator used by the Kea DHCPv6 server. It remembers the
-last offered lease and offers the following lease to the next client.
+This is the default allocator used by the Kea DHCPv6 server. It remembers the
+last offered lease and offers the following sequential lease to the next client.
For example, it may offer addresses in this order: ``2001:db8:1::10``,
``2001:db8:1::11``, ``2001:db8:1::12``, and so on. Similarly, it offers the
-delegated prefix following the previous one to the next client. The time to
-find and offer the next lease is very short. Thus, it is the highly performant
-allocator when the pool utilization is low and there is a high probability
+next sequential delegated prefix after the previous one to the next client. The time to
+find and offer the next lease is very short; thus, this is the most performant
+allocator when pool utilization is low and there is a high probability
that the next selected lease is available.
The iterative allocation underperforms when multiple DHCP servers share a lease
database or are connected to a cluster. The servers tend to offer and allocate
-the same blocks of addresses to different clients independently. It causes many
+the same blocks of addresses to different clients independently, which causes many
allocation conflicts between the servers and retransmissions by clients. A random
-allocation deals with it by dispersing the allocations order.
+allocation addresses this issue by dispersing the allocation order.
Random Allocator
----------------
The random allocator uses a uniform randomization function to select offered
-addresses and delegated prefixes from the subnet pools. It improves the server's
-resilience against attacks based on allocation predictability. In addition, the
-random allocation is suitable in deployments where multiple servers are connected
+addresses and delegated prefixes from subnet pools. It is suitable in deployments
+where multiple servers are connected
to a shared database or a database cluster. By dispersing the offered leases, the
servers minimize the risk of allocating the same lease to two different clients at
-the same or nearly the same time.
+the same or nearly the same time. In addition, it improves the server's
+resilience against attacks based on allocation predictability.
The random allocator is, however, slightly slower than the iterative allocator.
Moreover, it increases the server's memory consumption because it must remember
randomized leases to avoid offering them repeatedly. Memory consumption grows
-with the number of offered leases. In other words, larger pools and more
+with the number of offered leases; in other words, larger pools and more
clients increase memory consumption by random allocation.
Free Lease Queue Allocator (Prefix Delegation Only)
---------------------------------------------------
-It is a sophisticated allocator whose use should be considered in subnets
+This is a sophisticated allocator whose use should be considered in subnets
with highly utilized delegated prefix pools. In such cases, it can take a
-considerable amount of time for the iterative and random allocator to find
-an available prefix because they have to repeatedly check if there is a
-valid lease for the prefix they will offer. The number of checks can be as
+considerable amount of time for the iterative or random allocator to find
+an available prefix, because they must repeatedly check whether there is a
+valid lease for a prefix they will offer. The number of checks can be as
high as the number of delegated prefixes in the subnet when the subnet pools
-are exhausted. It has a direct negative impact on the DHCP response time for
+are exhausted, which can have a direct negative impact on the DHCP response time for
each request.
The Free Lease Queue (FLQ) allocator tracks lease allocations and de-allocations
and maintains a running list of available delegated prefixes for each pool.
-It allows for picking an available lease in a constant time, regardless of
+It allows an available lease to be selected within a constant time, regardless of
the subnet pools' utilization. The allocator continuously updates the list of
-free leases by removing the allocated leases and adding the released or
+free leases by removing any allocated leases and adding released or
reclaimed ones.
-The following configuration snipet shows how to select the FLQ allocator
+The following configuration snippet shows how to select the FLQ allocator
for prefix delegation in a subnet:
.. code-block:: json
The Free Lease Queue allocator can only be used for DHCPv6 prefix delegation.
An attempt to use this allocator for address assignment (with the ``allocator``
- parameter) will cause the configuration error. The DHCPv6 address pools are
- typically very large, and their utilization is low. In this case, the benefits
- of using the FLQ allocator diminish, and the amount of time required for the
+ parameter) will cause a configuration error. DHCPv6 address pools are
+ typically very large and their utilization is low; in these situation, the benefits
+ of using the FLQ allocator diminish. The amount of time required for the
allocator to populate the free lease queue would cause the server to freeze
upon startup.
-
-There are several tradeoffs that the administrator should take into account
-before using this allocator for prefix delegation. It can heavily
-impact the server's startup and reconfiguration time because the allocator
+There are several considerations that the administrator should take into account
+before using this allocator for prefix delegation. The FLQ allocator can heavily
+impact the server's startup and reconfiguration time, because the allocator
has to populate the list of free leases for each subnet where it is used.
-The delays can be observed both during the configuration reload and when
+These delays can be observed both during the configuration reload and when
the subnets are created using the ``subnet_cmds`` hook. The allocator
-increases the memory consumption to hold the list of free leases, and it
-is proportional to the total size of the pools for which this allocator is used.
-Finally, the lease reclamation must be enabled with a low value of the
-``reclaim-timer-wait-time`` parameter to ensure that the server frequently
+increases the memory consumption to hold the list of free leases,
+proportional to the total size of the pools for which this allocator is used.
+Finally, lease reclamation must be enabled with a low value of the
+``reclaim-timer-wait-time`` parameter, to ensure that the server frequently
collects expired leases and makes them available for allocation via the
allocator's free lease queue. Expired leases are not considered free by
the allocator until they are reclaimed by the server. See
:ref:`lease-reclamation` for more details about the lease reclamation process.
-Due to the above tradeoffs, we recommend that the FLQ allocator is selected
+We recommend that the FLQ allocator be selected
only after careful consideration. The server puts no restrictions on the
-delegated prefix pool sizes used with the FLQ allocator. We recommend testing
-how long it takes for the server to load the pools before deploying the
+delegated prefix pool sizes used with the FLQ allocator, so we advise users to
+test how long it takes for the server to load the pools before deploying the
configuration using the FLQ allocator in production. We also recommend
-specifying some other allocator type in the global configuration settings
-and overriding this selection at the subnet or shared network level to use
-the FLQ allocator for selected subnets only. That way, when a new subnet is
-added without the allocator specification, the global setting is used, thus
+specifying another allocator type in the global configuration settings
+and overriding this selection at the subnet or shared-network level, to use
+the FLQ allocator only for selected subnets. That way, when a new subnet is
+added without an allocator specification, the global setting is used, thus
avoiding unnecessary impact on the server's startup time.
-Similarly to the random allocator, the FLQ allocator offers leases in
+Like the random allocator, the FLQ allocator offers leases in
random order, which makes it suitable for use with a shared lease database.
--------
The Network Configuration Protocol, or NETCONF, is a network management protocol defined
-in `RFC 4741 <https://tools.ietf.org/html/rfc4741>`__. It uses YANG modeling language,
+in `RFC 4741 <https://tools.ietf.org/html/rfc4741>`__. It uses the YANG modeling language,
defined in `RFC 6020 <https://tools.ietf.org/html/rfc6020>`__, to provide a uniform way
-of handling the configuration syntax of varied networking devices. Kea provides optional
+of handling the configuration syntax of various networking devices. Kea provides optional
support for a YANG/NETCONF interface with the ``kea-netconf`` agent.
.. _netconf-install:
------------------
To get its NETCONF capabilities, Kea requires the v2 versions of libyang and
-sysrepo. The specific versions that were thoroughly tested with Kea are:
+Sysrepo. The specific versions that have been thoroughly tested with Kea are:
* libyang v2.1.4
* sysrepo v2.2.12
.. note::
- If, for whatever reason, an older version is desired, the versions below
- are the furthest back one can go. Backtracking even further has resulted
- either in compilation failure or in improper functioning in ISC internal
- testing, depending on which component is reverted.
+ For users who are unable to upgrade to one of the versions of libyang
+ and Sysrepo listed above, these are the oldest versions known to work
+ reliably with current Kea releases:
* libyang v2.0.256 (56d4e07ef1cdeab3eb2e6700247f83ec9148edcc)
* sysrepo v2.1.84
.. note::
- kea-netconf may be compatible with later versions, but if it is
- not hereby documented, it is not guaranteed.
+ ``kea-netconf`` may be compatible with later versions of libyang and
+ Sysrepo, but only the versions listed above have been thoroughly
+ tested by ISC.
-Use packages if they are provided by the system. If not, users can
-build from sources, which should work on all popular operating systems.
+Installing from packages is recommended, if they are provided by the system. If
+not, users can build from sources following the directions below, which
+should work on all popular operating systems.
.. _libyang-install-sources:
If any of the libraries are installed in a custom location, the
``--with`` flags accept the installations paths as values.
-3. Check ``config.report`` for NETCONF support.
+3. Check ``config.report`` to verify NETCONF support.
::
SYSREPOCPP_PREFIX : /usr/local
SYSREPOCPP_VERSION: 1.1.0
-4. Build as you normally would.
+4. Build as usual.
$ make
`Sysrepo homepage <https://www.sysrepo.org>`__.
In YANG, configurations and state data are described in YANG syntax
-in module files named: ``<module-name>[@<revision>].yang``
+in module files named ``<module-name>[@<revision>].yang``
-The revision part is optional and has ``YYYY-MM-DD`` format. An alternate
+The revision part is optional and follows the ``YYYY-MM-DD`` format. An alternate
XML syntax YIN is defined but less user-friendly. Top-level modules are
named in Kea models (a short version of schema models).
failed. Therefore, Kea uses its own dedicated models for DHCPv4 and DHCPv6 but
partially supports the IETF model for DHCPv6.
-All of the models have extra modules as dependencies. The dependency modules are also provided.
+All of the models have extra modules as dependencies, which are also provided.
All of the modules can be found in ``src/share/yang/modules`` in sources and in
-``share/kea/yang/modules`` in the installation directory. This directory will be
+``share/kea/yang/modules`` in the installation directory. This directory is
referred to as `${share_directory}` in the commands below.
-To install modules from sources, or upgrade them if you have older revisions
-installed, run the following command. In the case of a revision upgrade, YANG
+To install modules from sources or upgrade them from older revisions,
+run the following command. In the case of a revision upgrade, YANG
data will be migrated automatically to the new module schema.
.. code-block:: console
$ ${share_directory}/yang/modules/utils/reinstall.sh
-However, if there is resistance in the upgrade process, and data can be recreated from a NETCONF
-client or through other means, Kea modules can be easily uninstalled before installing again with:
+However, if there are any issues during the upgrade process, and data can be recreated from a NETCONF
+client or through other means, Kea modules can be easily uninstalled before installing again
+via this command:
.. code-block:: console
$ ${share_directory}/yang/modules/utils/reinstall.sh -u
-The script should be able to pick up on the Sysrepo installation.
-If not, there is a flag that was historically used to point to it:
+This script should be able to reinstall Sysrepo. However, the ``-s``
+flag can also be used to specify a path:
.. code-block:: console
[INF] File "kea-dhcp6-server@2022-11-30.yang" was installed.
[INF] No datastore changes to apply.
-It is possible to confirm whether the modules are imported correctly.
-The list of currently installed YANG modules should be similar to this:
+To confirm whether the modules have been imported correctly, check the list of
+currently installed YANG modules. It should be similar to this:
.. code-block:: console
If the module is used (i.e. imported) by other modules, it can be uninstalled
only after the dependent modules have first been uninstalled.
Installation and uninstallation must be done in dependency order and
-reverse-dependency order accordingly.
+reverse-dependency order, as appropriate.
.. _netconf-models:
Supported YANG Models
---------------------
-The only currently supported models are ``kea-dhcp4-server`` and
+The currently supported models are ``kea-dhcp4-server`` and
``kea-dhcp6-server``. There is partial support for
``ietf-dhcpv6-server``, but the primary focus of testing has been on Kea DHCP
servers. Other models (``kea-dhcp-ddns`` and ``kea-ctrl-agent``)
.. note::
- kea-netconf fetches the entire configuration from any Sysrepo datastore in a
- single get-config NETCONF operation. It underwent an extensive overhaul
- from the approach prior to Kea 2.3.2 where a get-config operation was done
- for each leaf and leaf-list node. Because of the broad changes, kea-netconf
- is considered experimental.
+ ``kea-netconf`` fetches the entire configuration from any Sysrepo datastore in a
+ single ``get-config`` NETCONF operation. Prior to Kea 2.3.2, a ``get-config`` operation
+ was done for each leaf and leaf-list node. Because of the significant changes,
+ ``kea-netconf`` is considered experimental.
.. _operation-example-errors:
-Error Handling in NETCONF Operation Example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Example of Error Handling in NETCONF Operation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are four classes of issues with configurations applied via
NETCONF:
.. _operation-example-logging:
-NETCONF Operation Example with Logging
+NETCONF Operation Example With Logging
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This example adds a logger entry to the initial (i.e. startup)
.. _migrating-yang-data:
-Migrating YANG Data from a prior Sysrepo version
+Migrating YANG Data From a Prior Sysrepo Version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-1. Shut down ``kea-netconf``. This makes sure that backups for both datastores
-are done at the same configuration state and no change happens between exporting them.
+1. Shut down ``kea-netconf``. This ensures that backups for both datastores
+are done at the same configuration state and that no change happens between exporting them.
-2. Make data backups for all YANG modules, one XML for each datastore.
+2. Make data backups for all YANG modules, with one XML for each datastore.
.. code-block:: console
.. note::
- Sysrepo v0 does not support import/export of all YANG modules. This capability was added in
+ Sysrepo v0 does not support import/export of all YANG modules; this capability was added in
Sysrepo v1. Users that are migrating from Sysrepo v0 will need to do per-module backups. This has
the added benefit of isolating potential failures and preventing them from affecting all
- modules. The command is the same except it has the module name added to it at the end.
+ modules. The command is the same, except it has the module name added to it at the end.
.. code-block:: console
$ sysrepocfg --datastore running --export=save.xml --format=xml kea-dhcp6-server
$ sysrepocfg --datastore startup --export=save.xml --format=xml kea-dhcp6-server
-3. Upgrade Sysrepo to the newer version and then:
+3. Upgrade Sysrepo to the newer version and then run:
.. code-block:: console
The ``ignore-iaid`` Flag
~~~~~~~~~~~~~~~~~~~~~~~~
-When ``ignore-iaid`` is set to ``true`` (default value is ``false``), the
-``flex-id`` hooks library will make the Kea DHCPv6 server ignore IAID value
+When ``ignore-iaid`` is set to ``true`` (the default value is ``false``), the
+``flex-id`` hook library causes the Kea DHCPv6 server to ignore the IAID value
from incoming IPv6 packets. This parameter is ignored by the Kea DHCPv4 server.
If the packet contains only one IA_NA, the IAID value will be changed to ``0``
-and stored as such in the lease storage. Similarly if the packet contains only
+and stored as such in the lease storage. Similarly, if the packet contains only
one IA_PD, the IAID value will be changed to ``0`` and stored as such in the
lease storage. The IAID is restored to its initial value in the response back
to the client. The change is visible in the identifier expression if the IAID is
.. note::
To avoid lease conflicts, if the incoming packet contains more than one
- IA_NA, the IAID value will not be changed on any of the IA_NAs. Similarly,
- if the incoming packet contains more than one IA_PD, the IAID value will not
- be changed on any of the IA_PDs.
+ IA_NA, the IAID value is not changed on any of the IA_NAs. Similarly,
+ if the incoming packet contains more than one IA_PD, the IAID value is not
+ changed on any of the IA_PDs.
.. warning::
is 10.
- ``max-rejected-lease-updates`` - specifies how many lease updates for distinct
- clients can fail due to a conflict between the lease and the partner configuration
- or state before the server transitions to the ``terminated`` state. Conflict
- can be a sign of a misconfiguration. Usually, a small number of conflicted
+ clients can fail, due to a conflict between the lease and the partner configuration
+ or state, before the server transitions to the ``terminated`` state. Conflict
+ can be a sign of a misconfiguration; usually, a small number of conflicted
leases are acceptable because they affect only a few devices. However, if
- the conflicts occur for many devices (e.g., entire subnet), the HA service
- becomes unreliable, should be terminated, and the problem should be manually
+ the conflicts occur for many devices (e.g., an entire subnet), the HA service
+ becomes unreliable and should be terminated, and the problem must be manually
corrected by an administrator. It is up to the administrator to select
the highest acceptable value of ``max-rejected-lease-updates``. The default
value is 10. The special value of 0 configures the server to never terminate
- the HA service due to the lease conflicts. If the value is 1, the server
+ the HA service due to lease conflicts. If the value is 1, the server
transitions to the ``terminated`` state when the first conflict occurs.
- This parameter does not pertain to the conflicting lease updates sent to
+ This parameter does not pertain to conflicting lease updates sent to
the backup servers.
- ``delayed-updates-limit`` - specifies the maximum number of lease updates
.. note::
- The ``max-rejected-lease-updates`` parameter has been introduced in Kea 2.3.1
- release. Earlier, the server did not differentiate between a lease update
- failure due to a dead partner and conflicts (e.g., configuration issues).
+ The ``max-rejected-lease-updates`` parameter was introduced in Kea 2.3.1.
+ Previously, the server did not differentiate between a lease update
+ failure due to a non-functioning partner and a failure due to a conflict
+ (e.g., configuration issues).
As a result, the server could sometimes transition to the ``partner-down``
- state even though the partner was operating normally, but only some leases
+ state even though the partner was operating normally, but only certain leases
had issues. Conflicts should no longer cause such a transition. However,
depending on the ``max-rejected-lease-updates`` setting, too many conflicts
- can lead to the High Availability service termination. In that case, both
+ can lead to termination of the High Availability service. In that case, both
servers continue to respond to DHCP queries but no longer send lease updates.
The values of ``max-ack-delay`` and ``max-unacked-clients`` must be selected
Many of the parameters present in the ``load-balancing`` and ``hot-standby``
configuration examples are not relevant in the ``passive-backup`` mode, thus
they are not specified here. For example: ``heartbeat-delay``,
-``max-unacked-clients``, ``max-rejected-lease-updates`` and others related to
+``max-unacked-clients``, ``max-rejected-lease-updates``, and others related to
the failover mechanism should not be specified in the ``passive-backup`` mode.
The ``wait-backup-ack`` is a boolean parameter not present in previous examples.
.. note::
The host cache and RADIUS hook libraries are two host backends that do not
- contribute to commands returning a collection of host reservations, such as
+ respond to commands that return a collection of host reservations, such as
``reservation-get-all``. Commands returning one host entry or dedicated host
cache commands should be used instead.
The ``lease4-write``, ``lease6-write`` Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-``lease4-write`` and ``lease6-write`` can be used to recover emergency
-situations where the memfile lease file is damage, e.g. removed by
-accident or truncated by a full file system but the in memory database
+``lease4-write`` and ``lease6-write`` can be used for recovery in emergency
+situations where the memfile lease file is damaged, e.g. removed by
+accident or truncated by a full file system, but the in-memory database
is still valid. These commands are supported only by the memfile database
backend and write the lease database into a CSV file. They take the path
of the file as the ``filename`` argument. If the specified output file
-is the same as the configured memfile one the backend close and reopen
-the file in an attempt to synchronize both file and in memory images
-of the lease database. The previous file is renamed by appending ``.bak``
-to its name.
+is the same as the configured memfile one, the backend closes and reopens
+the file in an attempt to synchronize both the files and the in-memory images
+of the lease database. The extension ``.bak`` is added to the previous filename.
.. note::
- These commands do not replace the LFC mechanism: they should be used
+ These commands do not replace the LFC mechanism; they should be used
only in exceptional circumstances, such as when recovering after
running out of disk space.
This library provides support for DHCPv4 Leasequery as described in
`RFC 4388 <https://tools.ietf.org/html/rfc4388>`__; and for DHCPv6
-Leasequery (`RFC 5007 <https://tools.ietf.org/html/rfc5007>`__).
+Leasequery as described in (`RFC 5007 <https://tools.ietf.org/html/rfc5007>`__).
.. note::
``kea-dhcp6`` process.
Kea version 2.3.4 added support for DHCPv6 Bulk Leasequery
-(`RFC 5460 <https://tools.ietf.org/html/rfc5460>`__) and
+(`RFC 5460 <https://tools.ietf.org/html/rfc5460>`__);
Kea version 2.3.5 added support for DHCPv4 Bulk Leasequery
(`RFC 6926 <https://tools.ietf.org/html/rfc6926>`__) using
the memfile lease backend.
When a query finds active leases in more than one subnet and the query's ``link-address``
is empty, then, in addition to the status-code, the ``DHCPV6_LEASEQUERY_REPLY``
-contains a ``lq-client-link`` option (48). The ``lq-client-link`` contains a list of
+contains an ``lq-client-link`` option (48). The ``lq-client-link`` contains a list of
IPv6 addresses, one for each subnet in which a lease was found (see
`RFC 5007, Section 4.1.2.5 <https://tools.ietf.org/html/rfc5007#section-4.1.2.5>`__)
If, however, the query's ``link-address`` is not empty, the list of queries is
DHCPv4 Bulk Leasequery gives a requester the ability to query for
active lease information over a TCP connection. This allows the server
-to return all leases matching a query.
+to return all leases matching a given query.
-Query types specified by RFC 6926 are query by hardware address and
-query by client identifier from Lease Query (RFC 4388, note the query
-by IP address is not available for Bulk Leasequery), and new query
-types are defined:
+Two of the query types identified by RFC 4388 - Query by MAC address and
+Query by Client-identifier - are Bulk Leasequery types specified by RFC
+6926. That RFC also defines these new Bulk Leasequery types:
-- Query by relay identifier
+- Query by Relay Identifier
- The query carries a RAI (dhcp-agent-options (82) option) with
+ The query carries an RAI (dhcp-agent-options (82)) option with
a relay-id (12) sub-option.
-- Query by remote identifier
+- Query by Remote ID
- The query carries a RAI (dhcp-agent-options (82) option) with
+ The query carries an RAI (dhcp-agent-options (82) option) with
a remote-id (2) sub-option.
-- Query for all configured IP addresses
+- Query for All Configured IP Addresses
This query type is selected when no other query type is specified.
-New options are defined for Bulk Leasequery:
+RFC 6926 also defines new options for Bulk Leasequery:
- status-code (151)
This reply option carries a status code such as MalformedQuery or
- NotAllowed with an optional text message.
+ NotAllowed, with an optional text message.
- base-time (152)
- This reply option carries the absolute current time the response
+ This reply option carries the absolute current time that the response
was created. All other time-based reply options are related to
this value.
- start-time-of-state (153)
- This reply option carries the time of the lease transition into its
+ This reply option carries the time of the lease's transition into its
current state.
- query-start-time (154)
- This query option specifies a start query time: replies will only
+ This query option specifies a start query time; replies will only
contain leases that are older than this value.
- query-end-time (155)
- This query option specifies an end query time: replies will only
- contain leases that are younger than this value.
+ This query option specifies an end query time; replies will only
+ contain leases that are newer than this value.
- dhcp-state (156)
.. note::
- Kea does not support the query for all configured IP addresses yet
- so do not use the dhcp-state option as only active leases can be
- returned in replies. It does not keep the start time of state,
- nor the local / remote information so does not emit corresponding
+ Kea does not yet support querying for all configured IP addresses,
+ so the dhcp-state option cannot be used, as only active leases can be
+ returned in replies. Kea does not keep the start time of the lease's state,
+ nor the local/remote information, so it cannot emit the corresponding
start-time-of-state and data-source options. Kea does not support VPNs
- so the presence of the option 221 in the query is considered as a
+ so the presence of option 221 in the query is considered a
(NotAllowed) error.
.. note::
- New query types are supported only with the memfile lease backend.
+ The new query types are only supported with the memfile lease backend.
.. _bulk-lease-query-dhcpv6:
to return all active leases matching a query.
New query types are available: ``query-by-relay-id`` (3),
-``query-by-link-address`` (4) and ``query-by-remote-id`` (5).
+``query-by-link-address`` (4), and ``query-by-remote-id`` (5).
-A new status code was defined: ``STATUS_QueryTerminated`` (11) but it is
+A new status code, ``STATUS_QueryTerminated`` (11), has been defined but it is
not yet used by the hook library.
.. note::
Kea attempts to map link address parameters to the prefixes of configured
- subnets. If a given address falls outside all configured subnet prefixes
- the query will fail with a status code of STATUS_NotConfigured. Also note if
+ subnets. If a given address falls outside all configured subnet prefixes,
+ the query fails with a status code of STATUS_NotConfigured. If
the link address parameter for ``query-by-relay-id`` or ``query-by-remote-id``
- is not :: (i.e. not empty) only delegated prefixes that lie within matching
- subnet prefixes will be returned. Currently ``query-by-address`` does not
+ is not ``::`` (i.e. not empty), only delegated prefixes that lie within matching
+ subnet prefixes are returned. Currently, ``query-by-address`` does not
support finding delegated prefixes by specifying an address that lies within
the prefix.
.. note::
- New query types are supported only with the memfile lease backend.
+ The new query types are only supported with the memfile lease backend.
.. _bulk-lease-query-dhcpv6-config:
Bulk Leasequery Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Bulk Leasequery configuration is done with a new map parameter ``advanced``
-with possible entries:
+Bulk Leasequery configuration is done via a new map parameter, ``advanced``,
+with these possible entries:
- ``bulk-query-enabled``
- When true, Kea will accept connections from IPs in the requesters
- list and process received Bulk Leasequeries. Default is false.
+ When ``true``, Kea accepts connections from IP addresses in the requesters
+ list and processes received Bulk Leasequeries. The default is ``false``.
- ``active-query-enabled``
- Anticipated parameter: if set must be false.
+ This is an anticipated parameter: if set, it must be ``false``.
- ``extended-info-tables-enabled``
- When true the lease backend manages DHCPv6 lease extended info
- (aka relay info) in tables to support by-relay-id and by-remote-id
- DHCPv6 Bulk Leasequery new query types. Default is to use the
+ When ``true``, the lease backend manages DHCPv6 lease extended info
+ (relay info) in tables to support the new DHCPv6 Bulk Leasequery
+ by-relay-id and by-remote-id types. The default is to use the
same value as ``bulk-query-enabled``.
- ``lease-query-ip``
- IP address upon which to listen for connections. The address must be
+ This is the IP address upon which to listen for connections. The address must be
of the same family as the server, e.g. IPv6 for DHCPv6 server.
- ``lease-query-port``
- Port upon which to listen. Default to 67 for IPv4 and 547 for IPv6,
+ This is the port upon which to listen. The default is 67 for IPv4 and 547 for IPv6,
i.e. the same value as for the UDP DHCP service but for TCP.
- ``max-bulk-query-threads``
- Indicates the maximum number of threads the Bulk Lease Query processing
+ This indicates the maximum number of threads that Bulk Leasequery processing
should use. A value of 0 instructs the server to use the same number of
threads that the Kea core is using for DHCP multi-threading.
The default is 0.
- ``max-requester-connections``
- Maximum number of concurrent requester connections (default 10, must be
- greater than 0).
+ This is the maximum number of concurrent requester connections. The default
+ is 10; the value must be greater than 0.
- ``max-concurrent-queries``
- Maximum number of concurrent queries per connection. A value 0
- leaves the number for Kea to determine and is the default.
+ This is the maximum number of concurrent queries per connection. The value 0
+ allows Kea to determine the number, and is the default.
- ``max-requester-idle-time``
- Amount time that may elapse between receiving data from a requester
- before its connection is closed as idle. In seconds with a default
- of 300 seconds.
+ This is the amount of time that may elapse after receiving data from a requester
+ before its connection is closed as idle, in seconds. The default
+ is 300.
- ``max-leases-per-fetch``
- Maximum number of leases to return in a single fetch (default 100).
+ This is the maximum number of leases to return in a single fetch. The default is 100.
-There should be common TLS parameters once TLS is supported.
+Once TLS is supported, we expect to implement common TLS parameters.
-For instance for DHCPv4:
+For instance, for DHCPv4:
::
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before the processing of commands in received HTTP requests, the ``rbac`` hook
-takes specific parameters, e.g. the common name part of the client
+takes specific parameters, e.g. the common-name part of the client
certificate subject name, to assign a role to the request.
The configuration associated with this role is used to accept or reject
the command. After processing, the response can be rewritten, e.g.
- The command is extracted from the request.
- A role is assigned using recorded information in the request.
- The role is used to accept (pass through) or reject (send
- a forbidden response) the command.
+ a forbidden response to) the command.
Here is a summary of the steps in processing a response:
- The information attached to the request is retrieved during the
+----------------------+---------------------------------------------------------+
| remote-address | remote/client IP address |
+----------------------+---------------------------------------------------------+
- | cert-subject | common name part of the client certificate subject name |
+ | cert-subject | common-name part of the client certificate subject name |
+----------------------+---------------------------------------------------------+
- | cert-issuer | common name part of the client certificate issuer name |
+ | cert-issuer | common-name part of the client certificate issuer name |
+----------------------+---------------------------------------------------------+
| basic-authentication | user ID of basic HTTP authentication |
+----------------------+---------------------------------------------------------+
+------------------+----------------------------------------------------+
| Name | Description |
+------------------+----------------------------------------------------+
- | name | the role name (at the exception of the default |
+ | name | the role name (with the exception of the default |
| | and unknown roles) |
+------------------+----------------------------------------------------+
| accept-commands | the accept access list |
| reject-commands | the reject access list |
+------------------+----------------------------------------------------+
| other-commands | specifies what to do for commands not matching |
- | | accept and reject lists (default reject) |
+ | | accept and reject lists (default: reject) |
+------------------+----------------------------------------------------+
| list-match-first | specifies what to do for commands matching both |
- | | accept and reject list by giving the list to check |
- | | and apply first (default accept) |
+ | | the accept and reject list by giving the list to |
+ | | check and apply first (default: accept) |
+------------------+----------------------------------------------------+
| response-filters | the filters to apply to responses |
+------------------+----------------------------------------------------+
.. note::
- The role assignment can fail, for instance with ``cert-subject`` when
- the client certificate was not required, or it has no subject common
- name and instead a DNS alternative subject name. In this case the role
+ The role assignment may fail, for instance with ``cert-subject`` when
+ the client certificate was not required, or it may have no subject common
+ name and instead have a DNS alternative subject name. In this case, the role
assignment returns the empty role and the ``default-role`` entry is used.
- The role assignment can return an unexpected value e.g. with an
+ The role assignment can return an unexpected value, e.g. with an
unregistered role name or a typing error. In this case the ``unknown-role``
entry is used.
- Both ``default-role`` and ``unknown-role`` default to reject all commands.
+ The default for both ``default-role`` and ``unknown-role`` is to reject all commands.
API Commands
------------
All commands of the REST API are described in files in the source directory
``src/share/api``, or in installed Kea
in ``.../share/kea/api``. The ``rbac`` hook reads these files to take the name,
-the access right (i.e. ``read`` or ``write``), and the hook name. Access right
-can be modified in the file but changes will be applied after Control Agent
-restart. Removing command definitions from ``.../share/kea/api`` has its
-consequences. If the access control list is based on ``read`` or ``write`` and
-the definition file is missing, the Control Agent will always reject such
-a command. If the access controls list is using ``commands`` to specify the
+the access right (i.e. ``read`` or ``write``), and the hook name. The access right
+can be modified in the file but changes are only applied after the Control Agent
+restarts. Removing command definitions from ``.../share/kea/api`` has
+consequences: if the access control list is based on ``read`` or ``write`` and
+the definition file is missing, the Control Agent always rejects such
+a command. If the access controls list is using ``commands`` to specify the
name of a command and the definition file from ``.../share/kea/api`` of this
-particular command is missing, the Control Agent will log an error on startup
+particular command is missing, the Control Agent logs an error on startup
and exit.
- ``access-control-lists``: the named access control list definitions
(each definition is a single entry map; the name of the entry is
the name of the access list, and the value is the specification).
- The name is used in other parts of configuration e.g. accept-commands.
+ The name is used in other parts of the configuration, such as "accept-commands".
- ``roles``: the role configurations.
}
}
-Custom hook commands, commands redefinition.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-It is possible to have a custom hook with new commands. In this case managing
-a new command via Role Based Access Control can be done in two ways.
+Custom Hook Commands and Command Redefinition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+It is possible to have a custom hook with new commands. In this case,
+Role Based Access Control can be used to manage a new command in two ways.
-Using the ``command`` global parameter:
+The ``command`` global parameter can be used to define its name, access type,
+and hook name:
.. code-block:: javascript
}
]
-to define its name, access type, and hook name. And in ``roles`` the new
-command can then be specified:
+The new command can then be specified in ``roles``:
.. code-block:: javascript
The second method is to create a custom file in ``.../share/kea/api`` and define
the access type of the custom command(s).
-It is also possible to redefine existing an command by removing its definition
+It is also possible to redefine an existing command by removing its definition
file from ``.../share/kea/api`` and defining it in the ``commands`` global parameter:
.. code-block:: javascript
}
]
-With this approach an administrator can put configurations of all existing
+With this approach, an administrator can put the configurations of all existing
commands inside the Control Agent's configuration file.
Extensive Example
],
...
-A common alternative is to not set the "reject-commands" list, i.e. leave
+A common alternative is not to set the "reject-commands" list, i.e. leave
it empty and rely on "other-commands" to reject anything else.
.. code-block:: javascript
and extra (accepted) commands.
``access-control-lists`` can be used for definitions of access control lists
-and later reused in roles:
+and later reused in ``roles``:
.. code-block:: javascript
Installation From Cloudsmith Packages
-------------------------------------
ISC provides Kea packages for Alpine, CentOS, Debian, Fedora, RHEL, and Ubuntu.
-The recommended method for installing Kea on any of these systems from the
-Cloudsmith repository for Kea release 2.3.1 is to install the ``isc-kea``
-metapackage. This metapackage is included on all supported distros and will
-install all of the services offered by the Kea software suite.
+The recommended method for installing Kea on any of these systems, from the
+Cloudsmith repository for Kea release 2.3.1 or later, is to install the ``isc-kea``
+metapackage. This metapackage is included on all supported distros and
+installs all of the services offered by the Kea software suite.
-If you would only like to install specific components offered by Kea, this
-can be accomplished by installing any of the following packages:
+Specific Kea components
+can be installed individually, with any of the following packages:
- ``isc-kea-dhcp4`` — Kea DHCPv4 server package
- ``isc-kea-ctrl-agent`` — Kea Control Agent for remote configuration
-- ``isc-kea-admin`` — Kea Database administration tools
+- ``isc-kea-admin`` — Kea database administration tools
-- ``isc-kea-hooks`` — Kea open-source DHCP hooks
+- ``isc-kea-hooks`` — Kea open source DHCP hooks
Kea Premium hook packages are not included in the ``isc-kea-hooks`` package.
-If you have access to the premium hooks, the packages will have the
+For ISC customers with access to the premium hooks, those packages have the
``isc-kea-premium-`` prefix.
-Once installed, the services can be managed through your distribution's
-service manager. The services will be named: ``kea-dhcp4``, ``kea-dhcp6``,
+Once installed, the services can be managed through the distribution's
+service manager. The services are named: ``kea-dhcp4``, ``kea-dhcp6``,
``kea-dhcp-ddns``, and ``kea-ctrl-agent``.
.. note::
The real service names on Debian and Ubuntu follow the names of the older
- packages in order to maintain compatibility in pre-existing scripts. A
+ packages, to maintain compatibility with pre-existing scripts. A
systemd service alias is used to allow users to refer to them with shorter
- names. In order to call ``systemctl enable`` on these services, you must
- use the real service names, which are: ``isc-kea-dhcp4-server``,
+ names. Calling ``systemctl enable`` on these services requires
+ the real service names, which are: ``isc-kea-dhcp4-server``,
``isc-kea-dhcp6-server``, ``isc-kea-dhcp-ddns-server``, and
``isc-kea-ctrl-agent``.
-Caveats for Upgrading Kea Packages
-----------------------------------
+Caveats When Upgrading Kea Packages
+-----------------------------------
-To upgrade to Kea 2.3.2 or later on Debian and Ubuntu systems, you need to
-run ``apt dist-upgrade``, instead of the usual ``apt upgrade``. This is only
-required to upgrade from an earlier version of Kea to a version greater than
-2.3.2. Once this upgrade has been done, you can upgrade to later versions
+To upgrade to Kea 2.3.2 or later from an earlier version of Kea on Debian
+and Ubuntu systems, run ``apt dist-upgrade`` instead of the usual ``apt upgrade``.
+Once this upgrade has been completed, it is possible to upgrade to later versions
normally using ``apt upgrade`` on Debian and Ubuntu systems.
-After upgrading to Kea 2.3.2 or later, it is possible that some Kea packages
-are removed from Debian and Ubuntu systems. This was an unavoidable side
-effect of overhauling our distribution packaging in 2.3.1 and 2.3.2. In order
-to ensure that the upgrade goes as smoothly as possible, pay attention to
+Users may notice differences in the packages distributed in Kea versions prior to
+2.3.2 and those distributed with 2.3.2 and later. As a result of an overhaul of our
+package design with that release, some packages were renamed or removed.
+To ensure that upgrades go as smoothly as possible, pay attention to
which packages are being removed and installed by the upgrade transaction,
-and ensure that all of the packages that your deployment requires get
-reinstalled.
+and ensure that all required packages are reinstalled.
Specifically, there is a possibility for the following packages to be removed
-during upgrade depending on which packages were originally installed:
+during the upgrade, depending on which packages were originally installed:
- ``isc-kea-dhcp4``
- ``isc-kea-hooks``
-If your goal is to have the entire Kea software suite installed, it is
-recommended that you simply ``apt install isc-kea`` after upgrading, which
+To install the entire Kea software suite, simply run
+``apt install isc-kea`` after upgrading, which
will install all of the relevant subpackages that make up Kea.
-This upgrade path hiccup is not present on RPM and Alpine systems, however
-if you experience issues with upgrading past 2.3.1, please inform us on the
-Kea Users mailing list, or contact customer support if you have a support
-contract with ISC.
+This upgrade path issue does not apply to RPM and Alpine systems; however,
+customers with ISC support contracts who experience difficulties with upgrading
+past 2.3.1 are invited to open a ticket in their support queue. Other users
+are encouraged to describe their situation on the kea-users mailing list for
+best-effort support from other list members.
.. _install-hierarchy:
Sysrepo 0.x or 1.x
------------------
-Kea versions 1.9.9 and earlier required Sysrepo 0.7.x to run, when optional
-support for NETCONF was enabled. Kea versions 1.9.10 and later required Sysrepo
-1.4.x and the related libyang 1.x library to run. The earlier Sysrepo versions
-are no longer supported. Kea 2.3.2 introduced support for Sysrepo 2.x. Sadly,
-the Sysrepo continues to undergo major changes that are backwards-incompatible.
-As such, Kea versions 2.3.2 and later dropped support for Sysrepo versions 1.x.
+Kea 2.3.2 introduced support for Sysrepo 2.x. Unfortunately,
+Sysrepo continues to undergo major changes that are backward-incompatible,
+and Kea versions 2.3.2 do not support Sysrepo earlier than versions 2.x.
-libreload command
------------------
+``libreload`` command
+---------------------
-The libreload was deprecated in Kea 2.3.4. The code to handle this command is
+The ``libreload`` command was deprecated in Kea 2.3.4. The code to handle this command is
still there, but there are reports of it being buggy and not really usable.
-Kea 2.3 and upcoming 2.4 versions will produce a warning when this command
-is used. It will be removed some time in 2.5 timeframe.
+Kea 2.3 and 2.4 versions will produce a warning when this command
+is used, and it will be removed entirely sometime in the 2.5 branch.
are held in the database for a specified amount of time rather than removed.
If both ``flush-reclaimed-timer-wait-time`` and ``hold-reclaimed-time`` are
greater than zero, the lease is expired immediately when the client sends a
-release message instead of being deleted from the lease storage. When the client
+release message, instead of being deleted from the lease storage. When the client
returns, the server first verifies whether there are any reclaimed leases
associated with this client and then reassigns them if possible. However, it is
important to note that any reclaimed lease may be assigned to another client if
root logger ``kea-dhcp4`` logging at the INFO level. In order to enable
DEBUG verbosity for DHCPv4 packet drops, we must create a configuration
entry for the logger with ``"name": "kea-dhcp4.bad-packets”``,
-``"severity": "DEBUG"`` and an explicit debug level. All other configuration
+``"severity": "DEBUG"``, and an explicit debug level. All other configuration
parameters may be omitted for this logger if it should use the default values
specified in the root logger's configuration.
``debuglevel`` is inherited only if ``severity`` is missing as well. For
predictable results, if ``severity`` is ``"DEBUG"``, these two attributes
should always be explicitly specified or omitted together. An entry with an
-explicit ``"DEBUG"`` severity will not inherit ``debuglevel`` from the root
-logger, and will default to ``0`` if missing, resulting in no debug messages
+explicit ``"DEBUG"`` severity does not inherit ``debuglevel`` from the root
+logger and defaults to ``0`` if missing, resulting in no debug messages
being logged. This is a consequence of relying on the log4cplus inheritance
mechanism.
For example, the Debian setup instructions for Kea 2.3 can be found here:
https://cloudsmith.io/~isc/repos/kea-2-3/setup/#formats-deb
- You can use the dropdown near the top of the page to get instructions for
- another OS.
+ The dropdown near the top of the page offers instructions for
+ other operating systems.
-3. Update system repositories. For example on Debian/Ubuntu:
+3. Update system repositories. For example, on Debian/Ubuntu:
.. code-block:: console
4. Kea is split into various packages. The entire list is available on
`cloudsmith.io <https://cloudsmith.io/~isc/repos/>`__ or using apt/yum/dnf.
- For example on Debian/Ubuntu:
+ For example, on Debian/Ubuntu:
.. code-block:: console
$ sudo apt install isc-kea-dhcp6
- or every single Kea related package, including development headers, debug
- symbols, and premium hooks (if they are available to you):
+ or every single Kea-related package, including development headers, debug
+ symbols, and premium hooks (if available):
.. code-block:: console
.. code-block:: console
- $ sudo apt install isc-kea*=1.8.1-isc0000920201106154401
+ $ sudo apt install isc-kea*=2.4.0-isc0000920201106154401
.. note::
Not all package managers support installing packages with a glob (``*``),
- please refer to your package managers manual before attempting to do so.
+ please refer to the specific package manager's manual before attempting this.
- - On CentOS/Fedora systems, replace ``apt install`` with ``yum install``
- - On Alpine systems, replace ``apt install`` with ``apk add``
+ - On CentOS/Fedora systems, replace ``apt install`` with ``yum install``.
+ - On Alpine systems, replace ``apt install`` with ``apk add``.
6. All installed packages should be now available directly; for example:
# service kea-dhcp6 restart
.. note::
- ``keactrl`` is not available in packages as similar functionality is provided
+ ``keactrl`` is not available in packages, as similar functionality is provided
by the native systemctl scripts.
-7. On CentOS, Fedora, and Alpine, you will need to enable the service at boot
- time if that is desirable. This is done automatically at package
+7. On CentOS, Fedora, and Alpine, the service must be enabled at boot
+ time if desired; this is done automatically at package
installation time on Debian and Ubuntu systems. For example, with systemd
on CentOS/Fedora:
OpenSSL Tuning
--------------
-OpenSSL can be tuned for Kea: from OpenSSL for Kea defaults from the OpenSSL
-configuration apply. Here we explain how for instance to limit the TLS version.
+Kea accepts the default OpenSSL configuration parameters, but administrators can
+also fine-tune the OpenSSL settings. For example, it may be desirable to limit
+the TLS version.
-The OpenSSL configuration file is named ``openssl.cnf`` and is in a system
-dependent ``etc`` directory. It can be overriden using the ``OPENSSL_CONF``
-environment variable. For OpenSSL versions greater than 1.0.2 the
-``MinProtocol`` variable can be set to the wanted minimal protocol.
+The default OpenSSL configuration file is named ``openssl.cnf``. It can
+be found in a system-dependent ``etc`` directory, and the location can be overridden
+using the ``OPENSSL_CONF`` environment variable. For OpenSSL versions greater than
+1.0.2, the minimum acceptable protocol can be set via the ``MinProtocol`` variable.
-Here we suppose that none of the variables are set or sections already exist.
-If it is not the case of course they should be reused.
+For these examples, we assume that no variables are already set and no sections already
+exist; it is, of course, possible to reuse existing variables and sections.
-The default application is ``openssl_conf`` and the corresponding variable
-must be set to the name of the section which handles defaults, for instance
-here ``default_conf``. So if the ``openssl_conf`` is not yet set please
-add at the beginning of the OpenSSL configuration file before the first
-section:
+In the default application, ``openssl_conf``, the corresponding variable
+must be set to the name of the section that handles defaults: in this example,
+``default_conf``. If ``openssl_conf`` is not yet set, add this command
+at the beginning of the OpenSSL configuration file (before the first
+section):
.. code-block:: ini
openssl_conf = default_conf
-In the ``default_conf`` section the ``ssl_conf`` variable must be set
-to the name of the section which handles SSL/TLS defaults, for
-instance here ``ssl_sect``.
+In the ``default_conf`` section, the ``ssl_conf`` variable must be set
+to the name of the section that handles SSL/TLS defaults: in this
+example, ``ssl_sect``.
.. code-block:: ini
[ default_conf ]
ssl_conf = ssl_sect
-In the ``ssl_sect`` section the ``system_default`` variable must be
-set to the name of the section which handles system defaults, for
-instance here ``system_default_sect``.
+In the ``ssl_sect`` section, the ``system_default`` variable must be
+set to the name of the section that handles system defaults: in
+this example, ``system_default_sect``.
.. code-block:: ini
[ ssl_sect ]
system_default = system_default_sect
-In the ``system_default_sect`` section the ``MinProtocol`` variable must be
-set to the wanted minimal SSL/TLS version, for instance here ``TLSv1.2``.
+In the ``system_default_sect`` section, the ``MinProtocol`` variable must be
+set to the desired minimal SSL/TLS version: in this example, ``TLSv1.2``.
.. code-block:: ini
[ system_default_sect ]
MinProtocol = TLSv1.2
-The same procedure can be used to enforce other crypto paramaters if
-wanted or needed.
-
-Anyway it is highly recommended to read the manual page about ``openssl.cnf``,
-its location can vary but its usual name is ``config.5ssl`` so can be
-displayed using ``man config``.
+The same steps can be used to enforce other crypto parameters if
+desired.
+It is highly recommended to read the ``openssl.cnf`` manual page,
+normally called ``config.5ssl`` and displayed using ``man config``.
Securing a Kea Deployment
=========================
``-T config-file``
Checks the configuration file and reports the first error, if any.
- It performs extra checks beside what ``-t`` is doing, like establising
- database connections (lease backend, host reservations backend, configuration
- backend and forensic logging backend), hook libraries
- loading and configuration parsing, etc. It does not open unix or TCP/UDP
- sockets, neither does it open or rotate files, as all these actions could
- interfere with a running process on the same machine.
+ It performs extra checks beyond what -t offers, such as establishing
+ database connections (for the lease backend, host reservations backend,
+ configuration backend, and forensic logging backend), loading hook libraries,
+ parsing configurations, etc. It does not open UNIX or TCP/UDP sockets,
+ nor does it open or rotate files, as any of these actions could interfere
+ with a running process on the same machine.
``-p server-port-number``
Specifies the server port number (1-65535) on which the server listens. This is
``-T config-file``
Checks the configuration file and reports the first error, if any.
- It performs extra checks beside what ``-t`` is doing, like establising
- database connections (lease backend, host reservations backend, configuration
- backend and forensic logging backend), hook libraries
- loading and configuration parsing, etc. It does not open unix or TCP/UDP
- sockets, neither does it open or rotate files, as all these actions could
- interfere with a running process on the same machine.
+ It performs extra checks beyond what -t offers, such as establishing
+ database connections (for the lease backend, host reservations backend,
+ configuration backend, and forensic logging backend), loading hook libraries,
+ parsing configurations, etc. It does not open UNIX or TCP/UDP sockets, nor
+ does it open or rotate files, as any of these actions could interfere with
+ a running process on the same machine.
``-p server-port-number``
Specifies the server port number (1-65535) on which the server listens. This is
projects / thirdparty / kea.git / commitdiff
