Supported Platforms

In general, this version of Kea builds and runs on any POSIX-compliant system with a C++ compiler (with C++14 support), the Botan cryptographic library, the log4cplus logging library and the Boost system library.

ISC regularly tests Kea on many operating systems and architectures, but lacks the resources to test all of them. Consequently, ISC is only able to offer support on a "best-effort" basis for some.

Regularly Tested Platforms

Kea is officially supported on Alpine, Debian, Fedora, FreeBSD, RHEL, and Ubuntu systems. Kea-3.0.0 builds have been tested on:

There are currently no plans to port Kea to Windows systems.

Best-Effort

The following are platforms on which Kea is known to build and run. ISC makes every effort to fix bugs on these platforms, but may be unable to do so quickly due to lack of hardware, less familiarity on the part of engineering staff, and other constraints.

Community-Maintained

These systems have once been regularly tested, but official support for it has been abandoned, usually due to discontinued support on their own part. Older versions may not have the required dependencies for building Kea easily available, although it is possible in many cases to compile on those directly from source. The community and interested parties may wish to help with maintenance, and we welcome patch contributions, although we cannot guarantee that we will accept them. All contributions are assessed against the risk of adverse effect on officially supported platforms.

These include platforms past their respective EOL dates, such as:

Unsupported Platforms

These are platforms on which versions of Kea since 1.7 are known not to build or run:

Required Software at Runtime

Kea uses various extra software packages which may not be provided in the default installation of some operating systems, nor in the standard package collections. This required software may need to be installed separately. (For the build requirements, also see Build Requirements.)

Some optional features of Kea have additional dependencies.

Kea Software

Kea is a modular DHCP server solution. This modularity is accomplished using multiple cooperating processes which, together, provide the server functionality. The following software is included with Kea:

The tools and modules are covered in full detail in this guide. In addition, manual pages are also provided in the default installation.

Kea also provides C++ libraries and programmer interfaces for DHCP. These include detailed developer documentation and code examples.

Quick Start Guide Using tarball

$ tar -Jxvf kea-3.0.0.tar.xz

$ cd kea-3.0.0
$ meson setup build [your extra parameters]

$ meson compile -C build

$ meson install -C build

Quick Start Guide Using Native Packages

ISC provides native Alpine, deb, and RPM packages, which make Kea installation much easier than building from source. Unless specific compilation options are desired, it is usually easier to install Kea using native packages.

NOTE:

NOTE:

or specific packages:

or ALL Kea-related packages, including development headers, debug symbols, and subscriber hooks (if available):

or all packages with a specified version number:

# kea-dhcp6 -c /etc/kea/kea-dhcp6.conf

# systemctl restart kea-dhcp6

# service kea-dhcp6 restart

NOTE:

# systemctl enable kea-dhcp6

# rc-update add kea-dhcp6

Quick Start Guide Using Docker Containers

$ docker network create --driver ipvlan --ipv6 --subnet 2001:db8::/64 --opt parent=eth0 ipvlan0

$ docker pull docker.cloudsmith.io/isc/docker/kea-dhcp6

$ docker create \
    --name kea-dhcp6 \
    --network ipvlan0 \
    --volume /local/kea/config:/etc/kea \
    --volume /local/kea/data:/var/lib/kea \
    docker.cloudsmith.io/isc/docker/kea-dhcp6

$ docker start kea-dhcp6

$ docker stop kea-dhcp6

NOTE:

Quick Start Guide for DHCPv4 and DHCPv6 Services

# keactrl start -s dhcp4

# keactrl start -s dhcp6

# keactrl start

# keactrl status

# keactrl stop

For system-specific instructions, please read the system-specific notes, available in the Kea section of ISC's Knowledgebase.

The details of keactrl script usage can be found in Managing Kea with keactrl.

Once Kea services are up and running, consider deploying a dashboard solution to monitor running services. For more details, see Monitoring Kea With Stork.

Running the Kea Servers Directly

The Kea servers can be started directly, without the need to use keactrl or systemctl. To start the DHCPv4 server run the following command:

# kea-dhcp4 -c /path/to/your/kea4/config/file.json

Similarly, to start the DHCPv6 server, run the following command:

# kea-dhcp6 -c /path/to/your/kea6/config/file.json

Packages

ISC publishes native RPM, deb, and APK packages, as well as tarballs with the source code. The packages are available in ISC's Cloudsmith repositories. The native packages can be downloaded and installed using the system available in a specific distribution (such as dpkg or rpm). The Kea repository can also be added to the system, making it easier to install updates. For details, please go to https://cloudsmith.io/~isc/repos, choose the desired Kea version, and then click the "Set Me Up" button. For detailed instructions, please refer to this Knowledgebase article.

ISC maintains two types of repositories: stable and development. The stable repositories contain a single stable release (e.g., kea-2-6 or kea-3-0) along with all its maintenance updates. Separate repositories were introduced to minimize the risk of unintentionally upgrading from one stable release to another.

The development repository, kea-dev, includes current and future development releases, which ISC does not recommend for production use. Packages in the kea-dev repository are subject to cleanup, and older versions may be removed.

Installation From Cloudsmith Packages

ISC provides Kea packages for Alpine, Debian, Fedora, RHEL, and Ubuntu. The recommended method for installing Kea on any of these systems is to install the isc-kea metapackage from the Cloudsmith repository. This metapackage is included on all supported distros and installs all of the services offered by the Kea software suite.

Specific Kea components can be installed individually, with any of the following packages:

The Kea subscriber hook packages are not included in the isc-kea-hooks package. For ISC customers with access to the subscriber hooks, those packages have the isc-kea-subscriber- prefix. For users interested in purchasing professional support services from ISC and getting access to the subscriber hooks, please fill out our contact form at https://www.isc.org/contact.

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:

Caveats When Upgrading Kea Packages

To upgrade to a current version of Kea from version 2.3.2 or earlier 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.

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 required packages are reinstalled.

Specifically, there is a possibility for the following packages to be removed during the upgrade, depending on which packages were originally installed:

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 issue does not apply to RPM and Alpine systems.

Customers with ISC support contracts who experience difficulties with upgrading 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.

Installation Hierarchy

The following is the directory layout of the complete Kea installation. (All directory paths are relative to the installation directory.)

Build Requirements

In addition to the runtime requirements (listed in Required Software at Runtime), building Kea from source code requires various development include headers and program development tools.

NOTE:

Building from source code requires the following software installed on the system:

Visit ISC's Knowledgebase at https://kb.isc.org/docs/installing-kea for system-specific installation tips.

Installation From Source

Although Kea may be available in pre-compiled, ready-to-use packages from operating system vendors, it is open source software written in C++. As such, it is freely available in source code form from ISC as a downloadable tar file. The source code can also be obtained from the Kea GitLab repository at https://gitlab.isc.org/isc-projects/kea. This section describes how to build Kea from the source code.

Download Tar File

The Kea release tarballs may be downloaded from: https://downloads.isc.org/isc/kea/.

Verify The Tar File Signature

The tar file with the source code is distributed together with its GPG signature. The signature is a file with the same name as the tar file appended by the .asc extension. You can find the signature file on our download page, FTP, or CloudSmith.

The signature is created using the ISC code-signing key. The current set of ISC code-signing keys is available from the ISC website at https://www.isc.org/pgpkey (the Current Set of ISC Code-Signing Keys link).

The signature can be verified using the GnuPGP gpg tool. The following commands import the code-signing keys (isc-keyblock.asc) and verify the signature:

$ gpg --import isc-keyblock.asc
$ gpg --verify kea-X.Y.Z.tar.xz.asc kea-X.Y.Z.tar.xz

The verification allows users to confirm that the tar file has not been tampered with and that it was created by ISC.

Retrieve From Git

The latest development code is available on GitLab (see https://gitlab.isc.org/isc-projects/kea). The Kea source is public and development is done in the “master” branch.

Downloading this "bleeding edge" code is recommended only for developers or advanced users. Using development code in a production environment is not recommended.

NOTE:

The code can be checked out from https://gitlab.isc.org/isc-projects/kea.git:

$ git clone https://gitlab.isc.org/isc-projects/kea.git

The code checked out from the git repository does not include the build files. They can be created by running meson setup build.

Write access to the Kea repository is only granted to ISC staff. Developers planning to contribute to Kea should check our Contributor's Guide. The Kea Developer's Guide contains more information about the process, and describes the requirements for contributed code to be accepted by ISC.

Set Up the Build

Kea uses Meson to discover build environment details. To generate the ninja file using the defaults, simply run:

$ meson setup build

Run meson configure to view the different build options. Some commonly used options are:

NOTE:

If meson setup build fails, it may be due to missing or old dependencies.

When meson setup build succeeds, it displays a report with the parameters used to build the code. This report is saved into the file build/config.report and is also embedded into the executable binaries, e.g. kea-dhcp6.

Build

After the setup step is complete, build the executables from the C++ code and prepare the Python scripts by running the command:

$ meson compile -C build

Install

To install the Kea executables, support files, and documentation, issue the command:

$ meson install -C build

NOTE:

It should not be required, but if shared libraries are not found at runtime, you can run ldconfig as root with /usr/local/lib (or with ${prefix}/lib if set up with --prefix) in /etc/ld.so.conf (or the relevant linker cache configuration file for the OS):

$ ldconfig

If ldconfig is not run where required, users may see errors like the following:

program: error while loading shared libraries: libkea-something.so.1:
cannot open shared object file: No such file or directory

Cross-Building

It is possible to cross-build Kea, i.e. to create binaries in a separate system (the build system) from the one where Kea runs (the host system).

It is outside of the scope of common administrator operations and requires some developer skills, but the Developer Guide explains how to do that using an x86_64 Linux system to build Kea for a Raspberry Pi box running Raspbian: see this Kea Cross-Compiling Example.

DHCP Database Installation and Configuration

Kea stores its leases in a lease database. The software has been written in a way that makes it possible to choose which database product should be used to store the lease information. Kea supports three database backends: MySQL, PostgreSQL, and memfile. To limit external dependencies, MySQL and PostgreSQL support are disabled by default and only memfile is available. Support for the optional external database backend must be explicitly included when Kea is built. This section covers the building of Kea with one of the optional backends and the creation of the lease database.

NOTE:

Building with MySQL Support

Install MySQL according to the instructions for the system. The client development libraries must be installed.

Build and install Kea as described in Installation, with the following modification. To enable the MySQL database code, at the setup step (see Set Up the Build), the -D mysql=enabled switch should be specified:

$ meson setup build -D mysql=enabled

If MySQL was not installed in the default location, the location can be selected by setting PKG_CONFIG_PATH=/path/to/mariadb.pc:${PKG_CONFIG_PATH} or PATH=/path/to/mariadb-config:${PATH} prior to meson setup.

$ PKG_CONFIG_PATH=/opt/mariadb/lib/pkgconfig PATH=/opt/mariadb/bin meson setup build -D mysql=enabled

See First-Time Creation of the MySQL Database for details regarding MySQL database configuration.

Building with PostgreSQL Support

Install PostgreSQL according to the instructions for the system. The client development libraries must be installed. Client development libraries are often packaged as libpq.

Build and install Kea as described in Installation, with the following modification. To enable the PostgreSQL database code, at the setup step (see Set Up the Build), the -D postgresql=enabled switch should be specified.

If PostgreSQL was not installed in the default location, the location can be selected by setting PKG_CONFIG_PATH=/path/to/libpq.pc:${PKG_CONFIG_PATH} or PATH=/path/to/pg_config:${PATH} prior to meson setup.

$ PKG_CONFIG_PATH=/opt/postgresql/lib/pkgconfig PATH=/opt/postgresql/bin meson setup build -D postgresql=enabled

See First-Time Creation of the PostgreSQL Database for details regarding PostgreSQL database configuration.

Hammer Building Tool

Hammer is a Python 3 script that lets users automate tasks related to building Kea, such as setting up virtual machines, installing Kea dependencies, compiling Kea with various options, running unit-tests and more. This tool was created primarily for internal QA purposes at ISC and it is not included in the Kea distribution; however, it is available in the Kea git repository. This tool was developed primarily for internal purposes and ISC cannot guarantee its proper operation. Administrators who decide to use it should do so with care.

NOTE:

The first-time user is strongly encouraged to look at Hammer's built-in help:

$ ./hammer.py --help

It will list available parameters.

Hammer is able to set up various operating systems running either in LXC or in VirtualBox. For a list of supported systems, use the supported-systems command:

$ ./hammer.py supported-systems
fedora:
  - 37: lxc
  - 38:
centos:
  - 8: lxc, virtualbox
  - 9:
rhel:
  - 8: virtualbox
  - 9:
ubuntu:
  - 18.04: lxc, virtualbox
  - 20.04: lxc
  - 22.04: lxc
debian:
  - 10: lxc, virtualbox
  - 11: lxc
  - 12: lxc
freebsd:
  - 12.0: virtualbox
  - 12.1:
  - 13.0: virtualbox
alpine:
  - 3.15: lxc
  - 3.16: lxc
  - 3.17: lxc

It is also possible to run the build locally, in the current system (if the OS is supported).

First, the Hammer dependencies must be installed: Vagrant and either VirtualBox or LXC. Hammer can install Vagrant and the required Vagrant plugins using the command:

$ ./hammer.py ensure-hammer-deps

VirtualBox and LXC must be installed manually.

The basic functions provided by Hammer are to prepare the build environment and perform the actual build, and to run the unit tests locally in the current system. This can be achieved by running the command:

$ ./hammer.py build -p local

The scope of the process can be defined using the --with (-w) and --without (-x) options. By default, the build command builds Kea with documentation, installs it locally, and runs unit tests.

To exclude the installation and generation of docs, type:

$ ./hammer.py build -p local -x install docs

The basic scope can be extended by mysql, pgsql, native-pkg, shell, and forge. Please refer to ./hammer.py build --help for more details.

NOTE:

Hammer can be told to set up a new virtual machine with a specified operating system, without the build:

$ ./hammer.py prepare-system -p virtualbox -s freebsd -r 12.0

This way, a system can be prepared for our own use.

To prepare such a system using SSH, invoke:

$ ./hammer.py ssh -p virtualbox -s freebsd -r 12.0

It is possible to speed up subsequent Hammer builds via ccache. During compilation, ccache stores objects in a shared folder. In subsequent runs, instead of doing an actual compilation, ccache returns the stored earlier objects. The cache with these objects for reuse must be stored outside of VM or LXC. To indicate the folder, the --ccache-dir parameter for Hammer must be included. In the indicated folder, there are separate stored objects for each target operating system.

$ ./hammer.py build -p lxc -s ubuntu -r 18.04 --ccache-dir ~/kea-ccache

NOTE:

For more information check:

$ ./hammer.py --help

Running Kea From a Non-root Account on Linux

Both Kea DHCPv4 and DHCPv6 servers perform operations that in general require root access privileges. In particular, DHCPv4 opens raw sockets and both DHCPv4 and DHCPv6 open UDP sockets on privileged ports. However, with some extra system configuration, it is possible to run Kea from non-root accounts.

First, a regular user account must be created:

useradd admin

Then, change the binaries' ownership and group to the new user. Note that the specific path may be different. Please refer to the --prefix parameter passed to meson setup:

chown -R admin /opt/kea
chgrp -R admin /opt/kea
chown -R admin /var/log/kea/kea-dhcp4.log
chgrp -R admin /var/log/kea/kea-dhcp4.log
chown -R admin /var/log/kea/kea-dhcp6.log
chgrp -R admin /var/log/kea/kea-dhcp6.log

If using systemd, modify its service file (e.g. /etc/systemd/system/kea-dhcp6.service):

User=admin
Group=admin

The most important step is to set the capabilities of the binaries. Refer to the operating system man page for capabilities for more information.

setcap 'cap_net_bind_service,cap_net_raw=+ep' /opt/kea/sbin/kea-dhcp4
setcap 'cap_net_bind_service=+ep' /opt/kea/sbin/kea-dhcp6

If using systemd, also add this to the service file (e.g. /etc/systemd/system/kea-dhcp6.service):

ExecStartPre=setcap 'cap_net_bind_service=+ep' /opt/kea/sbin/kea-dhcp6

After this step is complete, the admin user should be able to run Kea. Note that the DHCPv4 server by default opens raw sockets. If the network is only using relayed traffic, Kea can be instructed to use regular UDP sockets (refer to dhcp-socket-type parameter in the Interface Configuration section) and the cap_net_raw capability can be skipped.

NOTE:

ExecStart=/opt/kea/sbin/kea-dhcp4 -d -c /etc/kea/kea-dhcp4.conf -p 2067

and /etc/systemd/system/kea-dhcp4.service:

ExecStart=/opt/kea/sbin/kea-dhcp6 -d -c /etc/kea/kea-dhcp6.conf -p 1547

Then configure port redirection with iptables and ip6tables for new ports (e.g. 1547 and 1548). Be sure to replace ens4 with the specific interface name.

iptables -t nat -A PREROUTING -i ens4 -p udp --dport 67 -j REDIRECT --to-port 2067
iptables -t nat -A PREROUTING -i ens4 -p udp --dport 2068 -j REDIRECT --to-port 68
ip6tables -t nat -A PREROUTING -i ens4 -p udp --dport 547 -j REDIRECT --to-port 1547
ip6tables -t nat -A PREROUTING -i ens4 -p udp --dport 1548 -j REDIRECT --to-port 548

Deprecated Features

This section lists significant features that have been or will be removed. We try to deprecate features before removing them, to signal to current users to plan a migration. New users should not rely on deprecated features.

Sysrepo 0.x or 1.x

Kea 2.3.2 introduced support for Sysrepo 2.x. Unfortunately, Sysrepo continues to undergo major changes that are backward-incompatible, and current Kea versions do not support Sysrepo earlier than versions 2.x.

Databases and Schema Versions

Kea may be configured to use a database as storage for leases or as a source of servers' configurations and host reservations (i.e. static assignments of addresses, prefixes, options, etc.). As Kea is updated, new database schemas are introduced to facilitate new features and correct discovered issues with the existing schemas.

Each version of Kea expects a particular schema structure and checks for this by examining the version of the database it is using. Separate version numbers are maintained for the schemas, independent of the version of Kea itself. It is possible that the schema version will stay the same through several Kea revisions; similarly, it is possible that the version of the schema may go up several revisions during a single Kea version upgrade. Versions for each backend type are also independent, so an increment in the MySQL backend version does not imply an increment in that of PostgreSQL.

Schema versions are specified in a major.minor format. For the most recent versions, the minor version is always zero and only the major version is incremented.

Historically, the minor version used to be incremented when backward-compatible changes were introduced to the schema: for example - when a new index is added. This was opposed to incrementing the major version which implied an incompatible schema change: for example - changing the type of an existing column. If Kea attempts to run on a schema that is too old, as indicated by a mismatched schema version, it will fail; administrative action is required to upgrade the schema.

The kea-admin Tool

To manage the databases, Kea provides the kea-admin tool. It can initialize a new backend, check its version number, perform a backend upgrade, and dump lease data to a text file.

kea-admin takes two mandatory parameters: command and backend. Additional, non-mandatory options may be specified. The currently supported commands are:

backend specifies the type of backend database. The currently supported types are:

Additional parameters may be needed, depending on the setup and specific operation: username, password, and database name or the directory where specific files are located. See the appropriate manual page for details (man 8 kea-admin).

Supported Backends

The following table presents the capabilities of available backends. Please refer to the specific sections dedicated to each backend to better understand their capabilities and limitations. Choosing the right backend is essential for the success of the deployment.

List of available backends

Memfile

The memfile backend is able to store lease information, but cannot store host reservation details; these must be stored in the configuration file. (There are no plans to add a host reservations storage capability to this backend.)

No special initialization steps are necessary for the memfile backend. During the first run, both kea-dhcp4 and kea-dhcp6 create an empty lease file if one is not present. Necessary disk-write permission is required.

Upgrading Memfile Lease Files From an Earlier Version of Kea

There are no special steps required to upgrade memfile lease files between versions of Kea. During startup, the servers check the schema version of the lease files against their own. If there is a mismatch, the servers automatically launch the LFC process to convert the files to the server's schema version. While this mechanism is primarily meant to ease the process of upgrading to newer versions of Kea, it can also be used for downgrading should the need arise. When upgrading, any values not present in the original lease files are assigned appropriate default values. When downgrading, any data present in the files but not in the server's schema are dropped. To convert the files manually prior to starting the servers, run the lease file cleanup (LFC) process. See The LFC Process for more information.

MySQL

MySQL is able to store leases, host reservations, options defined on a per-host basis, and a subset of the server configuration parameters (serving as a configuration backend).

MySQL 5.7 vs MySQL 8 vs MariaDB 10 and 11

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, and MariaDB 11 are fully compatible, interchangeable, and tested with Kea.

First-Time Creation of the MySQL Database

Before preparing any Kea-specific database and tables, the MySQL database must be configured to use the system timezone. It is recommended to use UTC as the timezone for both the system and the MySQL database.

To check the system timezone:

date +%Z

To check the MySQL timezone:

mysql> SELECT @@system_time_zone;
mysql> SELECT @@global.time_zone;
mysql> SELECT @@session.time_zone;

To configure the MySQL timezone for a specific server, please refer to the installed version documentation.

Usually the setting is configured in the [mysqld] section in /etc/mysql/my.cnf, /etc/mysql/mysql.cnf, /etc/mysql/mysqld.cnf, or /etc/mysql/mysql.conf.d/mysqld.cnf.

[mysqld]
# using default-time-zone
default-time-zone='+00:00'
# or using timezone
timezone='UTC'

When setting up the MySQL database for the first time, the database area must be created within MySQL, and the MySQL user ID under which Kea will access the database must be set up. This needs to be done manually, rather than via kea-admin.

To create the database:

$ mysql -u root -p
Enter password:
mysql>

mysql> CREATE DATABASE database_name;

mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY '1234';
mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost';

mysql> quit
Bye

$ kea-admin db-init mysql -u database-user -p database-password -n database-name

ERROR 1419 (HY000) at line 1: You do not have the SUPER privilege and binary logging is
enabled (you *might* want to use the less safe log_bin_trust_function_creators variable)
ERROR/kea-admin: mysql_can_create cannot trigger, check user permissions, mysql status = 1
mysql: [Warning] Using a password on the command line interface can be insecure.
ERROR/kea-admin: Create failed, the user, keatest, has insufficient privileges.

mysql> set @@global.log_bin_trust_function_creators = 1;
Query OK, 0 rows affected (0.00 sec)

mysql> CONNECT database-name;
mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql

mysql> CONNECT database-name;
mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_drop.mysql

WARNING:

mysql> quit
Bye

If the tables were not created in Step 4, run the kea-admin tool to create them now:

$ kea-admin db-init mysql -u database-user -p database-password -n database-name

Do not do this if the tables were created in Step 4. kea-admin implements rudimentary checks; it will refuse to initialize a database that contains any existing tables. To start from scratch, all data must be removed manually. (This process is a manual operation on purpose, to avoid accidentally irretrievable mistakes by kea-admin.)

Upgrading a MySQL Database From an Earlier Version of Kea

Sometimes a new Kea version uses a newer database schema, so the existing database needs to be upgraded. This can be done using the kea-admin db-upgrade command.

To check the current version of the database, use the following command:

$ kea-admin db-version mysql -u database-user -p database-password -n database-name

(See Databases and Schema Versions for a discussion about versioning.) If the version does not match the minimum required for the new version of Kea (as described in the release notes), the database needs to be upgraded.

Before upgrading, please make sure that the database is backed up. The upgrade process does not discard any data, but depending on the nature of the changes, it may be impossible to subsequently downgrade to an earlier version.

To perform an upgrade, issue the following command:

$ kea-admin db-upgrade mysql -u database-user -p database-password -n database-name

NOTE:

mysql> SELECT COLLATION('');
+-----------------+
| COLLATION('')   |
+-----------------+
| utf8_general_ci |
+-----------------+

Improved Performance With MySQL

Changing the MySQL internal value innodb_flush_log_at_trx_commit from the default value of 1 to 2 can result in a huge gain in Kea performance. In some deployments, the gain was over 1000% (10 times faster when set to 2, compared to the default value of 1). It can be set per-session for testing:

mysql> SET GLOBAL innodb_flush_log_at_trx_commit=2;
mysql> SHOW SESSION VARIABLES LIKE 'innodb_flush_log%';

or permanently in /etc/mysql/my.cnf:

[mysqld]
innodb_flush_log_at_trx_commit=2

Be aware that changing this value can cause problems during data recovery after a crash, so we recommend checking the MySQL documentation. With the default value of 1, MySQL 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 innodb_flush_log_at_trx_commit is set to 2, MySQL writes the changes at intervals no longer than 1 second. Batching writes gives a substantial performance boost. The trade-off, however, is that in the worst-case scenario, all changes in the last second 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.

PostgreSQL

PostgreSQL can store leases, host reservations, and options defined on a per-host basis.

First-Time Creation of the PostgreSQL Database

Before preparing any Kea-specific database and tables, the PostgreSQL database must be configured to use the system timezone. It is recommended to use UTC as the timezone for both the system and the PostgreSQL database.

To check the system timezone:

date +%Z

To check the PostgreSQL timezone:

postgres=# show timezone;
postgres=# SELECT * FROM pg_timezone_names WHERE name = current_setting('TIMEZONE');

To configure the PostgreSQL timezone for a specific server, please refer to the installed version documentation.

Usually the setting is configured in the postgresql.conf with the varying version path /etc/postgresql/<version>/main/postgresql.conf, but on some systems the files may be located in /var/lib/pgsql/data.

timezone = 'UTC'

The first task is to create both the database and the user under which the servers will access it. A number of steps are required:

$ sudo -u postgres psql postgres
Enter password:
postgres=#

postgres=# CREATE DATABASE database-name;
CREATE DATABASE
postgres=#

postgres=# CREATE USER user-name WITH PASSWORD '1234';
CREATE ROLE
postgres=# GRANT ALL PRIVILEGES ON DATABASE database-name TO user-name;
GRANT
postgres=# \c database-name
You are now connected to database "database-name" as user "postgres".
postgres=# GRANT ALL PRIVILEGES ON SCHEMA public TO user-name;
GRANT
postgres=#

postgres=# \q
Bye
$

$ psql -d database-name -U user-name -f path-to-kea/share/kea/scripts/pgsql/dhcpdb_create.pgsql
Password for user user-name:
CREATE TABLE
CREATE INDEX
CREATE INDEX
CREATE TABLE
CREATE INDEX
CREATE TABLE
START TRANSACTION
INSERT 0 1
INSERT 0 1
INSERT 0 1
COMMIT
CREATE TABLE
START TRANSACTION
INSERT 0 1
COMMIT
$

psql: FATAL:  no pg_hba.conf entry for host "[local]", user "user-name", database "database-name", SSL off

local   database-name    user-name                                 password
host    database-name    user-name          127.0.0.1/32           password
host    database-name    user-name          ::1/128                password

Initialize the PostgreSQL Database Using kea-admin

If the tables were not created manually, do so now by running the kea-admin tool:

$ kea-admin db-init pgsql -u database-user -p database-password -n database-name

Do not do this if the tables were already created manually. kea-admin implements rudimentary checks; it will refuse to initialize a database that contains any existing tables. To start from scratch, all data must be removed manually. (This process is a manual operation on purpose, to avoid accidentally irretrievable mistakes by kea-admin.)

Upgrading a PostgreSQL Engine From an Earlier Version

If you upgraded your PostgreSQL from a version prior to 15.0, you need to grant additional privileges to the user:

First, log into PostgreSQL as "postgres":

$ sudo -u postgres psql -d database-name -U postgres
Enter password:
postgres=#

Next, grant the access to the public schema.

postgres=# GRANT ALL PRIVILEGES ON SCHEMA public TO user-name;
GRANT
postgres=#

Now, quit the PostgreSQL client:

postgres=# \q
Bye
$

Upgrading a PostgreSQL Database From an Earlier Version of Kea

The PostgreSQL database schema can be upgraded using the same tool and commands as described in Upgrading a MySQL Database From an Earlier Version of Kea, with the exception that the "pgsql" database backend type must be used in the commands.

Use the following command to check the current schema version:

$ kea-admin db-version pgsql -u database-user -p database-password -n database-name

Use the following command to perform an upgrade:

$ kea-admin db-upgrade pgsql -u database-user -p database-password -n database-name

Improved Performance With PostgreSQL

Changing the PostgreSQL internal value synchronous_commit from the default value 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:

postgres=# SET synchronous_commit = OFF;

or permanently via command (preferred method):

postgres=# ALTER SYSTEM SET synchronous_commit=OFF;

or permanently in /etc/postgresql/[version]/main/postgresql.conf:

synchronous_commit = off

Changing this value can cause problems during data recovery after a crash, so we recommend a careful read of the PostgreSQL documentation. 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 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

If a read-only database is used for storing host reservations, Kea must be explicitly configured to operate on the database in read-only mode. Sections Using Read-Only Databases for Host Reservations With DHCPv4 and Using Read-Only Databases for Host Reservations with DHCPv6 describe when such a configuration may be required, and how to configure Kea to operate in this way for both DHCPv4 and DHCPv6.

Limitations Related to the Use of SQL Databases

Year 2038 Issue

The lease expiration time in Kea is stored in the SQL database for each lease as a timestamp value. Kea developers have observed that the MySQL database does not accept timestamps beyond 2147483647 seconds (the maximum signed 32-bit number) from the beginning of the UNIX epoch (00:00:00 on 1 January 1970). Some versions of PostgreSQL do accept greater values, but the value is altered when it is read back. For this reason, the lease database backends put a restriction on the maximum timestamp to be stored in the database, which is equal to the maximum signed 32-bit number. This effectively means that the current Kea version cannot store leases whose expiration time is later than 2147483647 seconds since the beginning of the epoch (around the year 2038). This will be fixed when database support for longer timestamps is available.

TLS/HTTPS Support

Since Kea 1.9.6, TLS can be used to secure HTTP communication. There are three levels of protection possible:

NOTE:

NOTE:

NOTE:

Building Kea with TLS/HTTPS Support

TLS/HTTPS support is available with either the OpenSSL or the Botan cryptographic library. There are some constraints on the Boost library that must be used:

TLS/HTTPS Configuration

The TLS configuration parameters are:

The three string parameters must be either all unspecified (TLS disabled) or all specified (TLS enabled).

TLS is asymmetric: the authentication of the server by the client is mandatory but the authentication of the client by the server is optional. In TLS terms, this means the server may require the client certificate, or may not; there is a server-specific TLS parameter.

Objects in files must be in the PEM format. Files can contain more than one certificate, but this has not been tested and is not supported.

Botan requires CA certificates to have the standard CA certificate attributes, verifies that end-entity certificates are version 3 certificates (as required by the TLS standard), and supports only PKCS 8 files for the private key.

NOTE:

A sample set of certificates and associated objects is available at src/lib/asiolink/testutils/ca in the Kea sources, with a doc.txt file explaining how they were generated using the openssl command. These files are for testing purposes only. Do not use them in production.

TLS handshake, the phase where the cryptographic parameters are exchanged and authentication is verified, can fail in multiple ways. Error messages often do not help to pinpoint the source of the problem. Both OpenSSL and Botan provide a command-line tool with a verify command which can be used to understand and fix handshake issues.

OpenSSL Tuning

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 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.

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.

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):

openssl_conf = default_conf

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.

[ default_conf ]
ssl_conf = ssl_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.

[ ssl_sect ]
system_default = system_default_sect

In the system_default_sect section, the MinProtocol variable must be set to the desired minimal SSL/TLS version: in this example, TLSv1.2.

[ system_default_sect ]
MinProtocol = TLSv1.2

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.

Secure Kea Control Agent

The Kea Control Agent natively supports secure HTTP connections using TLS. This allows protection against users from the node where the agent runs, something that a reverse proxy cannot provide. More about TLS/HTTPS support in Kea can be found in TLS/HTTPS Support.

TLS is configured using three string parameters with file names, and a boolean parameter:

The file format is PEM. Either all the string parameters are specified and HTTP over TLS (HTTPS) is used, or none is specified and plain HTTP is used. Configuring only one or two string parameters results in an error.

NOTE:

NOTE:

The kea-shell tool also supports TLS.

Securing a Kea Deployment

Below is a list of considerations for administrators wishing to improve Kea's security. In many cases, there are trade-offs between convenience and security.

Component-Based Design

The Kea architecture is modular, with separate daemons for separate tasks. A Kea deployment may include DHCPv4, DHCPv6, and Dynamic DNS daemons; a Control Agent daemon run on each application server; the kea-lfc utility for doing periodic lease file cleanup; MySQL and or PostgreSQL databases, run either locally on the application servers or accessed over the internal network; a Netconf daemon to perform config and stats monitoring of Kea servers; and a Stork monitoring system. This modular architecture allows the administrator to minimize the attack surface by minimizing the code that is loaded and running. For example, kea-dhcp-ddns should not be run unless DNS updates are required. Similarly, kea-lfc is never triggered (and can be safely removed or never installed) if memfile is not used. Potential Kea security issues can be minimized by running only those processes required in the local environment.

NOTE:

Limiting Application Permissions

The DHCPv4 and DHCPv6 protocols assume the server opens privileged UDP port 67 (DHCPv4) or 547 (DHCPv6), which requires root access under normal circumstances. However, via the capabilities mechanism on Linux systems, Kea can run from an unprivileged account. See Running Kea From a Non-root Account on Linux for details on how to run Kea without root access.

The Control Agent (CA) can accept incoming HTTP or HTTPS connections. The default port is 8000, which does not require privileged access.

Securing Kea Administrative Access

The three primary Kea daemons (kea-dhcp4, kea-dhcp6 and kea-dhcp-ddns) all support a control channel, which is implemented as a UNIX socket. The control channel, which opens a UNIX socket, is disabled by default; however, many configuration examples have it enabled, as it is a very popular feature. To read from or write to this socket, root access is generally required, although if Kea is configured to run as non-root, the owner of the process can write to it. Access can be controlled using normal file-access control on POSIX systems (owner, group, others, read/write).

NOTE:

Since Kea version 2.7.2 DHCP servers support HTTP/HTTPS control channels so the Control Agent (CA) is no longer needed.

Since Kea-2.7.6 Kea supports multiple HTTP/HTTPS connections. Both IPv4 and IPv6 addresses can be used. Security can be enhanced if configuring HTTPS connections for all daemons.

Kea configuration is controlled by a JSON file on the Kea server. This file can be viewed or edited by anyone with file permissions (which are controlled by the operating system). Note that passwords are stored in clear text in the configuration file, so anyone with access to read the configuration file can find this information. As a practical matter, anyone with permission to edit the configuration file has control over Kea. Limiting user permission to read or write the Kea configuration file is an important security step.

NOTE:

Securing Database Connections

Kea can use an external MySQL or PostgreSQL database to store configuration, host reservations, or/and leases, or/and for forensic logging. The use of databases is a popular feature, but it is optional; it is also possible to store data in a flat file on disk.

When using a database, Kea stores and uses the following credentials to authenticate with the database: username, password, host, port, and database name. These are stored in clear text in the configuration file.

Depending on the database configuration, it is also possible to verify whether the system user matches the database username. Consult the MySQL or PostgreSQL manual for details.

Kea supports client TLS settings for MySQL database and it must be configured explicitly for all used connections (configuration, reservations, leases, forensic logging).

Information Leakage Through Logging

It is possible for Kea to log an entire configuration file, including passwords and secrets. Since Kea 1.9.7, this issue has been resolved by replacing the value of all entries ending in password or secret with asterisks, as was already done for database logs.

Logs are sent to stdout, stderr, files, or syslog; system file permissions system apply to stdout/stderr and files. Syslog may export the logs over the network, exposing them further to possible snooping.

NOTE:

NOTE:

Summary of Path Restrictions

Path restrictions mentioned through this section can be summarized according to the following table:

Cryptography Components

Kea supports the use of either of two cryptographic libraries: Botan or OpenSSL. The choice is made at compile time, and creates both compile and runtime dependencies between the Kea and the selected library. While OpenSSL is the most popular choice for deployments, Botan remains a fully supported alternative.

The primary use cases for the cryptographic libraries are:

For OpenSSL and Botan, only the low-level crypto interface is used (e.g. libcrypto). Kea does not link with libssl. Some dependent software systems, such as database client libraries, can also depend on a crypto library.

One way to limit exposure for potential OpenSSL or Botan vulnerabilities is not to use DDNS. The libraries would still be needed to build and run Kea, but the code would never be used, so any potential bugs in the libraries would not be exploitable.

TSIG Signatures

Kea supports the following algorithms when signing DNS updates with TSIG signatures:

See TSIG Key List for an up-to-date list.

Kea uses SHA256 to calculate DHCID records. This is irrelevant from the cryptography perspective, as the DHCID record is only used to generate unique identifiers for two devices that may have been assigned the same IP address at different times.

Raw Socket Support

In principle, Kea DHCPv4 uses raw sockets to receive traffic from clients. The difficulty is with receiving packets from devices that do not yet have an IPv4 address. When dealing with direct traffic (where both client and server are connected to the same link, not separated by relays), the kernel normally drops the packet as the source IP address is 0.0.0.0. Therefore, Kea needs to open raw sockets to be able to receive this traffic.

However, this is not necessary if all the traffic is coming via relays, which is often the case in many networks. In that case normal UDP sockets can be used instead. There is a dhcp-socket-type parameter that controls this behavior.

The default is to permit raw socket usage, as it is more versatile.

When using raw sockets, Kea is able to receive raw layer 2 packets, bypassing most firewalls (including iptables). This effectively means that when raw sockets are used, the iptables cannot be used to block DHCP traffic. This is a design choice of the Linux kernel.

Kea can be switched to use UDP sockets. This is an option when all traffic is relayed. However, it does not work for directly connected devices. If Kea is limited to UDP sockets, iptables should work properly.

If raw sockets are not required, disabling this access can improve security.

Remote Administrative Access

Kea's Control Agent (CA) exposes a RESTful API over HTTP or HTTPS (HTTP over TLS). The CA is an optional feature that is disabled by default, but it is very popular. When enabled, it listens on the loopback address (127.0.0.1 or ::1) by default, unless configured otherwise. See TLS/HTTPS Support for information about protecting the TLS traffic. Limiting the incoming connections with a firewall, such as iptables, is generally a good idea.

Note that in High Availability (HA) deployments, DHCP partners connect to each other using a CA connection.

Since Kea version 2.7.2 DHCP and DDNS servers support HTTP/HTTPS control channels so the Control Agent (CA) is no longer needed.

Since Kea-2.7.6 Kea supports multiple HTTP/HTTPS connections. Both IPv4 and IPv6 addresses can be used. Security can be enhanced if configuring HTTPS connections for all daemons.

Authentication for Kea's RESTful API

Kea 1.9.0 added support for basic HTTP authentication (RFC 7617), to control access for incoming REST commands over HTTP. The credentials (username, password) are stored in a local Kea configuration file on disk. The username is logged with the API command, so it is possible to determine which authenticated user performed each command. The access control details are logged using a dedicated auth logger. Basic HTTP authentication is weak on its own as there are known dictionary attacks, but those attacks require a "man in the middle" to get access to the HTTP traffic. That can be eliminated by using basic HTTP authentication exclusively over TLS. In fact, if possible, using client certificates for TLS is better than using basic HTTP authentication.

Kea 1.9.2 introduced a new auth hook point. With this new hook point, it is possible to develop an external hook library to extend the access controls, integrate with another authentication authority, or add role-based access control to the Control Agent. This hookpoint was renamed as http_auth and is also supported by the DHCP and DDNS servers since Kea version 2.7.2.

Kea Security Processes

The following sections discuss how the Kea DHCP development team ensures code quality and handles vulnerabilities.

Vulnerability Handling

ISC is an experienced and active participant in the industry-standard vulnerability disclosure process and maintains accurate documentation on our process and vulnerabilities in ISC software. See https://kb.isc.org/docs/aa-00861 for ISC's Software Defect and Security Vulnerability Disclosure Policy.

In case of a security vulnerability in Kea, ISC notifies support customers ahead of any public disclosure, and provides a patch and/or updated installer package to remediate the vulnerability.

When a security update is published, both the source tarballs and the ISC-maintained packages are published on the same day. This enables users of the native Linux update mechanisms (such as Debian's and Ubuntu's apt or RedHat's dnf) to update their systems promptly.

Code Quality and Testing

Kea undergoes extensive tests during its development. The following are some of the processes that are used to ensure adequate code quality:

Fuzz Testing

The Kea team has a process for running fuzz testing. Fuzzing is a software-testing technique whereby a program is presented with a variety of generated data as input and is monitored for abnormal conditions such as crashes or hangs.

There are two ways to fuzz Kea.

Option 1. With the libfuzzer harness function LLVMFuzzerTestOneInput.

Option 2. With the AFL (American Fuzzy Lop https://github.com/google/AFL) compiler.

Using the LLVMFuzzerTestOneInput Harness Function:

This mode of fuzzing works with virtually any compiler.

There are four types of fuzzers implemented with this mode:

There are two binaries under test:

Release Integrity

All ISC software releases are signed with PGP and distributed via the ISC website, which is itself DNSSEC-signed, so users can be confident the software has not been tampered with.

Bus Factor

According to the Core Infrastructure project, a "bus factor" or "truck factor" is the minimum number of project members that have to suddenly disappear from a project ("be hit by a bus") before the project stalls due to lack of knowledgeable or competent personnel. It is hard to estimate precisely, but the bus factor for Kea is somewhere around five. As of 2021, there are six core developers and two quality assurance engineers, with many additional casual contributors (product manager, support team, IT, etc.). The team is geographically dispersed.

JSON Configuration

JSON is the notation used throughout the Kea project. The most obvious usage is for the configuration file, but JSON is also used for sending commands over the Management API (see Management API) and for communicating between DHCP servers and the DDNS update daemon.

Typical usage assumes that the servers are started from the command line, either directly or using a script, e.g. keactrl. The configuration file is specified upon startup using the -c parameter.

JSON Syntax

Configuration files for the DHCPv4, DHCPv6, DDNS, Control Agent, and NETCONF modules are defined in an extended JSON format. Basic JSON is defined in RFC 7159 and ECMA 404. In particular, the only boolean values allowed are true or false (all lowercase). The capitalized versions (True or False) are not accepted.

Even though the JSON standard (ECMA 404) does not require JSON objects (i.e. name/value maps) to have unique entries, Kea implements them using a C++ STL map with unique entries. Therefore, if there are multiple values for the same name in an object/map, the last value overwrites previous values. Since Kea 1.9.0, configuration file parsers raise a syntax error in such cases.

Kea components use extended JSON with additional features allowed:

WARNING:

The configuration file consists of a single object (often colloquially called a map) started with a curly bracket. It comprises only one of the "Dhcp4", "Dhcp6", "DhcpDdns", "Control-agent", or "Netconf" objects. It is possible to define additional elements but they will be ignored.

A very simple configuration for DHCPv4 could look like this:

# The whole configuration starts here.
{
    # DHCPv4 specific configuration starts here.
    "Dhcp4": {
        "interfaces-config": {
            "interfaces": [ "eth0" ],
            "dhcp-socket-type": "raw"
        },
        "valid-lifetime": 4000,
        "renew-timer": 1000,
        "rebind-timer": 2000,
        "subnet4": [{
           "pools": [ { "pool": "192.0.2.1-192.0.2.200" } ],
           "subnet": "192.0.2.0/24",
           "id": 1
        }],
       # Now loggers are inside the DHCPv4 object.
       "loggers": [{
            "name": "*",
            "severity": "DEBUG"
        }]
    }
# The whole configuration structure ends here.
}

More examples are available in the installed share/doc/kea/examples directory.

To avoid repetition of mostly similar structures, examples in the rest of this guide will showcase only the subset of parameters appropriate for a given context. For example, when discussing the IPv6 subnets configuration in DHCPv6, only subnet6 parameters will be mentioned. It is implied that the remaining elements (the global map that holds Dhcp6) are present, but they are omitted for clarity. Usually, locations where extra parameters may appear are denoted by an ellipsis (...).

Comments and User Context

Shell, C, or C++ style comments are all permitted in the JSON configuration file if the file is used locally. This is convenient and works in simple cases where the configuration is kept statically using a local file. However, since comments are not part of JSON syntax, most JSON tools detect them as errors. Another problem with them is that once Kea loads its configuration, the shell, C, and C++ style comments are ignored. If commands such as config-get or config-write are used, those comments are lost. An example of such comments was presented in the previous section.

Historically, to address the problem, Kea code allowed the use of comment strings as valid JSON entities. This had the benefit of being retained through various operations (such as config-get), or allowing processing by JSON tools. An example JSON comment looks like this:

"Dhcp4": {
    "subnet4": [{
        "id": 1,
        "subnet": "192.0.2.0/24",
        "pools": [{ "pool": "192.0.2.10 - 192.0.2.20" }],
        "comment": "second floor"
    }]
}

However, the facts that the comment could only be a single line, and that it was not possible to add any other information in a more structured form, were frustrating. One specific example was a request to add floor levels and building numbers to subnets. This was one of the reasons why the concept of user context was introduced. It allows adding an arbitrary JSON structure to most Kea configuration structures.

This has a number of benefits compared to earlier approaches. First, it is fully compatible with JSON tools and Kea commands. Second, it allows storing simple comment strings, but it can also store much more complex data, such as multiple lines (as a string array), extra typed data (such as floor numbers being actual numbers), and more. Third, the data is exposed to hooks, so it is possible to develop third-party hooks that take advantage of that extra information. An example user context looks like this:

"Dhcp4": {
    "subnet4": [{
        "id": 1,
        "subnet": "192.0.2.0/24",
        "pools": [{ "pool": "192.0.2.10 - 192.0.2.20" }],
        "user-context": {
            "comment": "second floor",
            "floor": 2
        }
    }]
}

User contexts can store an arbitrary data file as long as it has valid JSON syntax and its top-level element is a map (i.e. the data must be enclosed in curly brackets). However, some hook libraries may expect specific formatting; please consult the specific hook library documentation for details.

The user-context mechanism has superseded the JSON comment capabilities; ISC encourages administrators to use user context instead of the older mechanisms. To promote this way of storing comments, Kea converts JSON comments to user context on the fly.

However, if the configuration uses the old JSON comment method, the config-get command returns a slightly modified configuration. It is not uncommon for a call for config-set followed by config-get to receive a slightly different structure. The best way to avoid this problem is simply to abandon JSON comments and use user context.

Kea supports user contexts at the following levels: global scope, interfaces configuration, multi-threading, shared networks, subnets, client classes, option data and definitions, pools, prefix delegation pools, host reservations, control socket, HTTP header, authentication, clients, queue control, DHCP-DDNS, loggers, leases, and server ID. These are supported in both DHCPv4 and DHCPv6, with the exception of prefix delegation pools and server ID, which are DHCPv6 only.

User context can be added and edited in structures supported by commands.

We encourage Kea users to utilize these functions to store information used by other systems and custom hooks.

For example, the subnet4-update command can be used to add user context data to an existing subnet.

{
"subnet4": [ {
   "id": 1,
   "subnet": "10.20.30.0/24",
   "user-context": {
      "building": "Main",
      "floor": 1
      }
 } ]
 }

The same can be done with many other commands, like lease6-add, etc.

Kea also uses user context to store non-standard data. Currently, only Storing Extended Lease Information uses this feature.

When enabled, it adds the ISC key in user-context to differentiate automatically added content.

Example of relay information stored in a lease:

{
"arguments": {
   "client-id": "42:42:42:42:42:42:42:42",
   "cltt": 12345678,
   "fqdn-fwd": false,
   "fqdn-rev": true,
   "hostname": "myhost.example.com.",
   "hw-address": "08:08:08:08:08:08",
   "ip-address": "192.0.2.1",
   "state": 0,
   "subnet-id": 44,
   "valid-lft": 3600,
   "user-context": {
      "ISC": {
      "relays": [
      {
            "hop": 2,
            "link": "2001:db8::1",
            "peer": "2001:db8::2"
      },
      {
            "hop": 1,
            "link": "2001:db8::3",
            "options": "0x00C800080102030405060708",
            "peer": "2001:db8::4"
      }]
      }
   }
}
}

User context can store configuration for multiple hooks and comments at once.

For a discussion about user context used in hooks, see User Contexts in Hooks.

Simplified Notation

It is sometimes convenient to refer to a specific element in the configuration hierarchy. Each hierarchy level is separated by a slash. If there is an array, a specific instance within that array is referenced by a number in square brackets (with numbering starting at zero). For example, in the above configuration the valid-lifetime in the Dhcp4 component can be referred to as Dhcp4/valid-lifetime, and the pool in the first subnet defined in the DHCPv4 configuration as Dhcp4/subnet4[0]/pool.

Configuration Files Inclusion

The parser provides the ability to include files. The syntax was chosen to look similar to how Apache includes PHP scripts in HTML code. This particular syntax was chosen to emphasize that the include directive is an additional feature and not a part of JSON syntax.

The inclusion is implemented as a stack of files. You can use the include directive in nested includes. Up to ten nesting levels are supported. This arbitrarily chosen limit is protection against recursive inclusions.

The include directive has the form:

<?include "[PATH]"?>

The [PATH] pattern should be replaced with an absolute path or a path relative to the current working directory at the time the Kea process was launched.

To include one file from another, use the following syntax:

{
   "Dhcp6": {
      "interfaces-config": {
         "interfaces": [ "*" ]},
      "preferred-lifetime": 3000,
      "rebind-timer": 2000,
      "renew-timer": 1000,
      <?include "subnets.json"?>
      "valid-lifetime": 4000
   }
}

where the content of "subnets.json" may be:

{
"subnet4": [
   {
      "id": 123,
      "subnet": "192.0.2.0/24"
   },
   {
      "id": 234,
      "subnet": "192.0.3.0/24"
   },
   {
      "id": 345,
      "subnet": "10.0.0.0/8"
   }
],
...
}

Kea Configuration Backend

Applicability

The Kea Configuration Backend (CB or config backend) gives Kea servers the ability to store almost all of their configuration in one or more databases.

Potential features and benefits include:

Potential drawbacks include:

NOTE:

Example Scenario

Consider a large organization with many sites, each with a pair of Kea servers deployed in a high availability (HA) configuration. Typically such deployments use standardized configurations, leading to similar config parameters for every site. The members of each HA pair are often almost exactly the same, differing only by name. Often installations of this size will feature a high level of automation, including provisioning and management systems.

The CB is ideal for such deployments. While some effort is required to integrate with the provisioning automation, once accomplished, deployment of new Kea servers can be nearly automatic. A small "stub" JSON config, identical for every server, can be used, and all remaining configuration (shared networks, subnets, pools, etc.) loaded from the central CB database. Any updates to the central CB database are automatically propagated to all Kea instances. The CB becomes the "single source of truth" for DHCP throughout the organization.

Limitations and Warnings

Availability

libdhcp_cb_cmds.so is available only to ISC customers with a paid support contract. For more information on subscription options, please complete the form at https://www.isc.org/contact. While it is theoretically possible to use the CB without this hook, this is neither supported nor recommended.

Preparation is Required

The Configuration Backend is not a "plug-and-play" solution. Supported scenarios require use of the CB API commands. Configuration information must be loaded into the CB database using the API for the CB to have any effect. The general intent is for the CB to be integrated as part of a larger provisioning solution. Please do not define config-databases unless you have done the necessary preparation work.

Database Management

The only supported method for managing the contents of the CB database is through the libdhcp_cb_cmds.so hook, which provides API commands for config backends. As a practical matter, to use the CB, you must do almost all Kea configuration through the CB API.

While it is theoretically possible to use the CB without the API (using tools such as MySQL Workbench or the command-line MySQL client), these avenues are neither recommended nor supported.

Config Conflicts

We strongly recommend against mixing configuration information from the CB and JSON config file. In other words, do not use both JSON config declarations and CB to configure the same types of objects. Ideally, when using the CB, the Kea config files should contain the absolute bare minimum necessary, with everything else coming from the CB.

Using both CB and JSON as a source of configuration risks conflicting definitions. Such conflicts are confusing at best, and usually lead to undesired behavior or errors from Kea.

In the event of a conflict, configuration instructions from the CB database generally take precedence over instructions from a JSON file.

In certain carefully-controlled scenarios, it may be technically possible to use both. For example, defining one subnet in a JSON file and a second (different) subnet in the CB database would not conflict. However, other structures are replaced entirely. For example, if client classes are defined in the CB database, the DHCP server disregards any client classes defined in the JSON file.

In short, if you are using the CB, you should use only the CB.

Incompatible Software

API commands which modify Kea's configuration (other than the CB API) are contraindicated. This includes the libdhcp_subnet_cmds.so hook. Its APIs modify Kea's in-memory configuration, and the modifications can only be made persistent by using config-write to write a new JSON config file.

The Stork management suite does not currently support the CB. Stork makes all configuration changes through API avenues which expect to write changes into JSON config file. Support for the CB is planned for a future release of Stork.

In certain carefully-controlled scenarios, it may be possible to use these tools with the CB. Namely, if they are used in strictly "read-only" fashion, to retrieve Kea information, but never to modify it. However, no protection against accidental modification is provided, so this is not recommended.

Limitations

Currently, the Kea CB has the following limitations:

Custom Options

Using custom option formats requires creating definitions for these options. Suppose a user wishes to set option data in the configuration backend. In that case, we recommend specifying the definition for that option in the configuration backend as well. It is essential when multiple servers are managed via the configuration backend, and may differ in their configurations. The option data parser can search for an option definition appropriate for the server for which the option data is specified.

In a single-server deployment, or when all servers share the same configuration file information, it is possible to specify option definitions in the configuration files and option data in the configuration backend. The server receiving a command to set option data must have a valid definition in its configuration file, even when it sets option data for another server.

It is not supported to specify option definitions in the configuration backend and the corresponding option data in the server configuration files.

Components

The Kea Configuration Backend solution consists of the CB modules (hook libraries), the CB commands API (its own hook library), the external database software (MySQL or PostgreSQL), the database schema, and the Kea configuration information stored in the database.

In this documentation, the term "Configuration Backend" may also refer to the particular Kea module providing support for that database type. For example, the MySQL Configuration Backend, libdhcp_mysql.so, provides a complete set of functions to manage and fetch the configuration information from a MySQL database. The PostgreSQL Configuration Backend, libdhcp_pgsql.so, is the corresponding module for PostgreSQL. Similarly, the term "database" is used to refer to either a MySQL or PostgreSQL database.

The CB commands API provides a complete set of commands to manage Kea configuration information, as stored within the database. This API is implemented in its own hook library, libdhcp_cb_cmds.so. This library can be attached to both DHCPv4 and DHCPv6 server instances. It simplifies many typical operations, such as listing, adding, retrieving, and deleting global parameters, shared networks, subnets, pools, options, option definitions, and client classes. In addition, it provides essential business logic that ensures the logical integrity of the data. All CB API commands start with remote-. See libdhcp_cb_cmds.so: Configuration Backend Commands for more information.

Installation and maintenance of external database software is beyond the scope of this manual.

The database schema is typically installed via the kea-admin tool. See Installation for more information. The raw schema creation scripts are dhcpdb_create.mysql and dhcpdb_create.pgsql.

Use the CB commands API to populate the database with Kea configuration information.

Related design documents are available in our GitLab:

Installation

To use either Configuration Backend, the appropriate module library (libdhcp_mysql.so or libdhcp_pgsql.so) must be compiled during the Kea build. The -D switch specifies which database module to build, if any: -D mysql=enabled or -D postgresql=enabled. The appropriate database client libraries and header files must be installed prior to build. See DHCP Database Installation and Configuration for more information on building Kea with database support. ISC's Kea packaging, as well as some third-party distributions, provide separate packages for each database type.

The database server hosting the CB tables must be prepared with the Kea schema. When upgrading an existing Kea installation, the database schema may also need to be upgraded. The kea-admin tool can be used to more easily apply the schema, as described in The kea-admin Tool.

At runtime, the DHCP servers must be configured to load the module, in the hooks-libraries section. A config-databases directive must then be used to instruct Kea to load configuration using the database backend. The DHCPv4 and DHCPv6 server-specific configurations of the CB, as well as the list of supported configuration parameters, can be found in Configuration Backend in DHCPv4 and Configuration Backend in DHCPv6, respectively.

Once installation is completed, the CB commands API can be used to populate the database with Kea configuration information.

Configuration Sharing and Server Tags

The configuration database is designed to store configuration information for multiple Kea servers. Depending on the use case, the entire configuration may be shared by all servers; parts of the configuration may be shared by multiple servers and the rest of the configuration may be different for these servers; or each server may have its own non-shared configuration.

The configuration elements in the database are associated with the servers by "server tags." The server tag is an arbitrary string holding the name of the Kea server instance. The tags of the DHCPv4 and DHCPv6 servers are independent in the database, i.e. the same server tag can be created for both the DHCPv4 and the DHCPv6 server. The value is configured using the server-tag parameter in the Dhcp4 or Dhcp6 scope. The current server tag can be checked with the server-tag-get command.

The server definition, which consists of the server tag and the server description, must be stored in the configuration database prior to creating the dedicated configuration for that server. In cases when all servers use the same configuration, e.g. a pair of servers running as High Availability peers, there is no need to configure the server tags for these servers in the database.

Commands which contain the logical server all are applied to all servers connecting to the database. The all server cannot be deleted or modified, and it is not returned among other servers as a result of the remote-server4-get-all and remote-server6-get-all commands.

In most cases, there are no server tags defined in the configuration database; all connecting servers get the same configuration regardless of the server tag they use. The server tag that a particular Kea instance presents to the database to fetch its configuration is specified in the Kea configuration file, using the config-control map (please refer to the Enabling the Configuration Backend and Enabling the Configuration Backend for details). All Kea instances presenting the same server tag to the configuration database are given the same configuration.

It is the administrator's choice whether multiple Kea instances use the same server tag or each Kea instance uses a different server tag. There is no requirement that the instances running on the same physical or virtual machine use the same server tag. It is even possible to configure the Kea server without assigning it a server tag. In such a case the server will be given the configuration specified for all servers.

To differentiate between different Kea server configurations, a list of the server tags used by the servers must be stored in the database. For the DHCPv4 and DHCPv6 servers, this can be done using the remote-server4-set and remote-server6-set commands. The server tags can then be used to associate the configuration information with the servers. However, it is important to note that some DHCP configuration elements may be associated with multiple server tags (known as "shareable" elements), while other configuration elements may be associated with only one server tag ("non-shareable" elements). The Configuration Backend in DHCPv4 and Configuration Backend in DHCPv6 sections list the DHCP-specific shareable and non-shareable configuration elements; however, in this section we briefly explain the differences between them.

A shareable configuration element is one which has some unique property identifying it, and which may appear only once in the database. An example of a shareable DHCP element is a subnet instance: the subnet is a part of the network topology and we assume that any particular subnet may have only one definition within this network. Each subnet has two unique identifiers: the subnet identifier and the subnet prefix. The subnet identifier is used in Kea to uniquely identify the subnet within the network and to connect it with other configuration elements, e.g. in host reservations. Some commands provided by libdhcp_cb_cmds.so allow the subnet information to be accessed by either subnet identifier or prefix, and explicitly prohibit using the server tag to access the subnet. This is because, in general, the subnet definition is associated with multiple servers rather than a single server. In fact, it may even be associated with no servers (unassigned). Still, the unassigned subnet has an identifier and prefix which can be used to access the subnet.

A shareable configuration element may be associated with multiple servers, one server, or no servers. Deletion of the server which is associated with the shareable element does not cause the deletion of the shareable element. It merely deletes the association of the deleted server with the element.

Unlike a shareable element, a non-shareable element must not be explicitly associated with more than one server and must not exist after the server is deleted (must not remain unassigned). A non-shareable element only exists within the context of the server. An example of a non-shareable element in DHCP is a global parameter, e.g. renew-timer. The renew timer is the value to be used by a particular server and only this server. Other servers may have their respective renew timers set to the same or different values. The renew timer parameter has no unique identifier by which it could be accessed, modified, or otherwise used. Global parameters like the renew timer can be accessed by the parameter name and the tag of the server for which they are configured. For example, the remote-global-parameter4-get and remote-global-parameter6-get commands allow the value of the global parameter to be fetched by the parameter name and the server name. Getting the global parameter only by its name (without specifying the server tag) is not possible, because there may be many global parameters with a given name in the database.

When the server associated with a non-shareable configuration element is deleted, the configuration element is automatically deleted from the database along with the server because the non-shareable element must be always assigned to a server (or the logical server all).

The terms "shareable" and "non-shareable" only apply to associations with user-defined servers; all configuration elements associated with the logical server all are by definition shareable. For example: the renew-timer associated with all servers is used by all servers connecting to the database which do not have their specific renew timers defined. In a special case, when none of the configuration elements are associated with user-defined servers, the entire configuration in the database is shareable because all its pieces belong to all servers.

NOTE:

Overview

keactrl is a shell script which controls the startup, shutdown, and reconfiguration of the Kea servers (kea-dhcp4, kea-dhcp6, kea-dhcp-ddns, kea-ctrl-agent, and kea-netconf). It also provides the means for checking the current status of the servers and determining the configuration files in use.

keactrl is available only when Kea is built from sources. When installing Kea using native packages, the native systemd scripts are provided. See Native Packages and systemd Section for details.

Command Line Options

keactrl is run as follows:

# keactrl <command> [-c keactrl-config-file] [-s server[,server,...]]

<command> is one of the commands described in Commands.

The optional -c keactrl-config-file switch allows specification of an alternate keactrl configuration file. (--ctrl-config is a synonym for -c.) In the absence of -c, keactrl uses the default configuration file [kea-install-dir]/etc/kea/keactrl.conf.

The optional -s server[,server,...] switch selects the servers to which the command is issued. (--server is a synonym for -s.) If absent, the command is sent to all servers enabled in the keactrl configuration file. If multiple servers are specified, they should be separated by commas with no intervening spaces.

The keactrl Configuration File

Depending on the administrator's requirements, it may not be necessary to run all of the available servers. The keactrl configuration file sets which servers are enabled and which are disabled. The default configuration file is [kea-install-dir]/etc/kea/keactrl.conf, but this can be overridden on a per-command basis using the -c switch.

The contents of keactrl.conf are:

# This is a configuration file for keactrl script which controls
# the startup, shutdown, reconfiguration and gathering the status
# of the Kea processes.
# prefix holds the location where the Kea is installed.
prefix=@prefix@
# Location of Kea configuration file.
kea_dhcp4_config_file=@sysconfdir@/@PACKAGE@/kea-dhcp4.conf
kea_dhcp6_config_file=@sysconfdir@/@PACKAGE@/kea-dhcp6.conf
kea_dhcp_ddns_config_file=@sysconfdir@/@PACKAGE@/kea-dhcp-ddns.conf
kea_ctrl_agent_config_file=@sysconfdir@/@PACKAGE@/kea-ctrl-agent.conf
kea_netconf_config_file=@sysconfdir@/@PACKAGE@/kea-netconf.conf
# Location of Kea binaries.
exec_prefix=@exec_prefix@
dhcp4_srv=@sbindir@/kea-dhcp4
dhcp6_srv=@sbindir@/kea-dhcp6
dhcp_ddns_srv=@sbindir@/kea-dhcp-ddns
ctrl_agent_srv=@sbindir@/kea-ctrl-agent
netconf_srv=@sbindir@/kea-netconf
# Start DHCPv4 server?
dhcp4=yes
# Start DHCPv6 server?
dhcp6=yes
# Start DHCP DDNS server?
dhcp_ddns=no
# Start Control Agent?
ctrl_agent=yes
# Start Netconf?
netconf=no
# Be verbose?
kea_verbose=no

NOTE:

Setting the dhcp4, dhcp6, dhcp_ddns, ctrl_agent, and netconf parameters set to "yes" configures keactrl to manage (start, reconfigure) all servers, i.e. kea-dhcp4, kea-dhcp6, kea-dhcp-ddns, kea-ctrl-agent, and kea-netconf. When any of these parameters is set to "no", keactrl ignores the corresponding server when starting or reconfiguring Kea. Some daemons (dhcp_ddns and netconf) are disabled by default.

By default, Kea servers managed by keactrl are located in [kea-install-dir]/sbin. This should work for most installations. If the default location needs to be altered, the paths specified with the dhcp4_srv, dhcp6_srv, dhcp_ddns_srv, ctrl_agent_srv, and netconf_srv parameters should be modified.

The kea_verbose parameter specifies the verbosity of the servers being started. When kea_verbose is set to yes, the logging level of the server is set to DEBUG. Modification of the logging severity in a configuration file, as described in Logging, will have no effect as long as kea_verbose is set to "yes." Setting it to "no" causes the server to use the logging levels specified in the Kea configuration file. If no logging configuration is specified, the default settings are used.

NOTE:

Commands

The following commands are supported by keactrl:

Typical output from keactrl when starting the servers looks similar to the following:

$ keactrl start
INFO/keactrl: Starting kea-dhcp4 -c /usr/local/etc/kea/kea-dhcp4.conf -d
INFO/keactrl: Starting kea-dhcp6 -c /usr/local/etc/kea/kea-dhcp6.conf -d
INFO/keactrl: Starting kea-dhcp-ddns -c /usr/local/etc/kea/kea-dhcp-ddns.conf -d
INFO/keactrl: Starting kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf -d
INFO/keactrl: Starting kea-netconf -c /usr/local/etc/kea/kea-netconf.conf -d

Kea's servers create PID files upon startup. These files are used by keactrl to determine whether a given server is running. If one or more servers are running when the start command is issued, the output looks similar to the following:

$ keactrl start
INFO/keactrl: kea-dhcp4 appears to be running, see: PID 10918, PID file: /usr/local/var/run/kea/kea.kea-dhcp4.pid.
INFO/keactrl: kea-dhcp6 appears to be running, see: PID 10924, PID file: /usr/local/var/run/kea/kea.kea-dhcp6.pid.
INFO/keactrl: kea-dhcp-ddns appears to be running, see: PID 10930, PID file: /usr/local/var/run/kea/kea.kea-dhcp-ddns.pid.
INFO/keactrl: kea-ctrl-agent appears to be running, see: PID 10931, PID file: /usr/local/var/run/kea/kea.kea-ctrl-agent.pid.
INFO/keactrl: kea-netconf appears to be running, see: PID 10123, PID file: /usr/local/var/run/kea/kea.kea-netconf.pid.

During normal shutdowns, these PID files are deleted; they may, however, be left over as remnants following a system crash. It is possible, though highly unlikely, that upon system restart the PIDs they contain may actually refer to processes unrelated to Kea. This condition will cause keactrl to decide that the servers are running, when in fact they are not. In such a case the PID files listed in the keactrl output must be manually deleted.

The following command stops all servers:

$ keactrl stop
INFO/keactrl: Stopping kea-dhcp4...
INFO/keactrl: Stopping kea-dhcp6...
INFO/keactrl: Stopping kea-dhcp-ddns...
INFO/keactrl: Stopping kea-ctrl-agent...
INFO/keactrl: Stopping kea-netconf...

Note that the stop command attempts to stop all servers regardless of whether they are "enabled" in keactrl.conf. If any of the servers are not running, an informational message is displayed as in the stop command output below.

$ keactrl stop
INFO/keactrl: kea-dhcp4 isn't running.
INFO/keactrl: kea-dhcp6 isn't running.
INFO/keactrl: kea-dhcp-ddns isn't running.
INFO/keactrl: kea-ctrl-agent isn't running.
INFO/keactrl: kea-netconf isn't running.

As already mentioned, the reconfiguration of each Kea server is triggered by the SIGHUP signal. The reload command sends the SIGHUP signal to any servers that are enabled in the keactrl configuration file and that are currently running. When a server receives the SIGHUP signal it rereads its configuration file and, 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 is no longer providing any service: a working configuration must be loaded as soon as possible.

A reload is executed as follows:

$ keactrl reload
INFO/keactrl: Reloading kea-dhcp4...
INFO/keactrl: Reloading kea-dhcp6...
INFO/keactrl: Reloading kea-dhcp-ddns...
INFO/keactrl: Reloading kea-ctrl-agent...

If any of the servers are not running, an informational message is displayed as in the reload command output below. kea-netconf does not support the SIGHUP signal. If its configuration has changed, please stop and restart it for the change to take effect.

$ keactrl stop
INFO/keactrl: kea-dhcp4 isn't running.
INFO/keactrl: kea-dhcp6 isn't running.
INFO/keactrl: kea-dhcp-ddns isn't running.
INFO/keactrl: kea-ctrl-agent isn't running.
INFO/keactrl: kea-netconf isn't running.

NOTE:

NOTE:

Sometimes it is useful to check which servers are running. The status command reports this, with typical output that looks like:

$ keactrl status
DHCPv4 server: active
DHCPv6 server: inactive
DHCP DDNS: active
Control Agent: active
Netconf agent: inactive
Kea configuration file: /usr/local/etc/kea/kea.conf
Kea DHCPv4 configuration file: /usr/local/etc/kea/kea-dhcp4.conf
Kea DHCPv6 configuration file: /usr/local/etc/kea/kea-dhcp6.conf
Kea DHCP DDNS configuration file: /usr/local/etc/kea/kea-dhcp-ddns.conf
Kea Control Agent configuration file: /usr/local/etc/kea/kea-ctrl-agent.conf
Kea Netconf configuration file: /usr/local/etc/kea/kea-netconf.conf
keactrl configuration file: /usr/local/etc/kea/keactrl.conf

keactrl status offers basic reporting capabilities. For more extensive insight into Kea's health and status, consider deploying Stork. For details, see Monitoring Kea With Stork.

Overriding the Server Selection

The optional -s switch allows the selection of the server(s) to which the keactrl command is issued. For example, the following instructs keactrl to stop the kea-dhcp4 and kea-dhcp6 servers and leave the kea-dhcp-ddns and kea-ctrl-agent running:

$ keactrl stop -s dhcp4,dhcp6

Similarly, the following starts only the kea-dhcp4 and kea-dhcp-ddns servers, but not kea-dhcp6 or kea-ctrl-agent.

$ keactrl start -s dhcp4,dhcp_ddns

Note that the behavior of the -s switch with the start and reload commands is different from its behavior with the stop command. On start and reload, keactrl checks whether the servers given as parameters to the -s switch are enabled in the keactrl configuration file; if not, the server is ignored. For stop, however, this check is not made; the command is applied to all listed servers, regardless of whether they have been enabled in the file.

The following keywords can be used with the -s command-line option:

Native Packages and systemd

keactrl is a script that was developed to assist in managing Kea processes. However, all modern operating systems have their own process-management scripts, such as systemd. In general, these native scripts should be used, as they have several advantages. systemd scripts handle processes in a uniform way, so Kea is handled in a similar fashion to HTTP or a mail server. Second and more importantly, systemd allows dependencies to be defined between services. For example, it is easy to specify that the Kea server should not start until the network interfaces are operational. Using native scripts also has other benefits, such as the ability to enable or disable services using commands, and the ability to temporarily start a disabled service.

Thus, it is recommended to use systemctl commands if they are available. Native Kea packages do not provide keactrl; systemctl service definitions are provided instead. Consult the system documentation for details.

Briefly, here are example commands to check status, start, stop, and restart various Kea daemons:

# systemctl status kea-ctrl-agent
# systemctl start kea-dhcp4
# systemctl stop kea-dhcp6
# systemctl restart kea-dhcp-ddns

Note that the service names may be slightly different between Linux distributions; in general, we have followed the naming conventions in third-party packages. In particular, some systems may not have the isc- prefix.

Overview of the Kea Control Agent

The Kea Control Agent (CA) is a daemon which exposes a RESTful control interface for managing Kea servers. The daemon can receive control commands over HTTP and either forward these commands to the respective Kea servers or handle these commands on its own. The determination whether the command should be handled by the CA or forwarded is made by checking the value of the service parameter, which may be included in the command from the controlling client. The details of the supported commands, as well as their structures, are provided in Management API.

The CA can use hook libraries to provide support for additional commands or to program custom behavior of existing commands. Such hook libraries must implement callouts for the control_command_receive hook point. Details about creating new hook libraries and supported hook points can be found in the Kea Developer's Guide.

The CA processes received commands according to the following algorithm:

NOTE:

Configuration

The following example demonstrates the basic CA configuration.

{
    "Control-agent": {
        "http-host": "10.20.30.40",
        "http-port": 8000,
        "http-headers": [
            {
                "name": "Strict-Transport-Security",
                "value": "max-age=31536000"
             }
        ],
        "trust-anchor": "/path/to/the/ca-cert.pem",
        "cert-file": "/path/to/the/agent-cert.pem",
        "key-file": "/path/to/the/agent-key.pem",
        "cert-required": true,
        "authentication": {
            "type": "basic",
            "realm": "kea-control-agent",
            "clients": [
            {
                "user": "admin",
                "password": "1234"
            } ]
        },
        "control-sockets": {
            "dhcp4": {
                "comment": "main server",
                "socket-type": "unix",
                "socket-name": "/path/to/the/unix/socket-v4"
            },
            "dhcp6": {
                "socket-type": "unix",
                "socket-name": "/path/to/the/unix/socket-v6",
                "user-context": { "version": 3 }
            },
            "d2": {
                "socket-type": "unix",
                "socket-name": "/path/to/the/unix/socket-d2"
            }
        },
        "hooks-libraries": [
        {
            "library": "/opt/local/custom_hooks_example.so",
            "parameters": {
                "param1": "foo"
            }
        } ],
        "loggers": [ {
            "name": "kea-ctrl-agent",
            "severity": "INFO"
        } ]
    }
}

The http-host and http-port parameters specify an IP address and port to which HTTP service will be bound. In the example configuration provided above, the RESTful service will be available at the URL https://10.20.30.40:8000/. If these parameters are not specified, the default URL is http://127.0.0.1:8000/.

When using Kea's HA hook library with multi-threading, the address:port combination used for CA must be different from the HA peer URLs, which are strictly for internal HA traffic between the peers. User commands should still be sent via the CA.

Since Kea 2.7.5 the http-headers parameter specifies a list of extra HTTP headers to add to HTTP responses.

The trust-anchor, cert-file, key-file, and cert-required parameters specify the TLS setup for HTTP, i.e. HTTPS. If these parameters are not specified, HTTP is used. The TLS/HTTPS support in Kea is described in TLS/HTTPS Support.

As mentioned in Overview of the Kea Control Agent, the CA can forward received commands to the Kea servers for processing. For example, config-get is sent to retrieve the configuration of one of the Kea services. When the CA receives this command, including a service parameter indicating that the client wishes to retrieve the configuration of the DHCPv4 server, the CA forwards the command to that server and passes the received response back to the client. More about the service parameter and the general structure of commands can be found in Management API.

The CA uses UNIX domain sockets to forward control commands and receive responses from other Kea services. The dhcp4, dhcp6, and d2 maps specify the files to which UNIX domain sockets are bound. In the configuration above, the CA connects to the DHCPv4 server via /path/to/the/unix/socket-v4 to forward the commands to it. Obviously, the DHCPv4 server must be configured to listen to connections via this same socket. In other words, the command-socket configuration for the DHCPv4 server and the CA (for that server) must match. Consult UNIX Control Socket, UNIX Control Socket, and UNIX Control Socket to learn how the UNIX socket configuration is specified for the DHCPv4, DHCPv6, and D2 services.

NOTE:

User contexts can store arbitrary data as long as they are in valid JSON syntax and their top-level element is a map (i.e. the data must be enclosed in curly brackets). Some hook libraries may expect specific formatting; please consult the relevant hook library documentation for details.

User contexts can be specified on either global scope, control socket, basic authentication, or loggers. One other useful feature is the ability to store comments or descriptions; the parser translates a "comment" entry into a user context with the entry, which allows a comment to be attached within the configuration itself.

Basic HTTP authentication protects against unauthorized uses of the control agent by local users. For protection against remote attackers, HTTPS and reverse proxy of Secure Connections provide stronger security.

The authentication is described in the authentication block with the mandatory type parameter, which selects the authentication. Currently only the basic HTTP authentication (type basic) is supported.

The realm authentication parameter is used for error messages when the basic HTTP authentication is required but the client is not authorized.

When the clients authentication list is configured and not empty, basic HTTP authentication is required. Each element of the list specifies a user ID and a password. The user ID is mandatory, must not be empty, and must not contain the colon (:) character. The password is optional; when it is not specified an empty password is used.

NOTE:

To avoid exposing the user ID and/or the associated password, these values can be read from files. The syntax is extended by:

When files are used, they are read when the configuration is loaded, to detect configuration errors as soon as possible.

Hook libraries can be loaded by kea-ctrl-agent in the same way as they are loaded by kea-dhcp4 and kea-dhcp6. The CA currently supports one hook point - control_command_receive - which makes it possible to delegate the processing of some commands to the hook library. The hooks-libraries list contains the list of hook libraries that should be loaded by kea-ctrl-agent, along with their configuration information specified with parameters.

Please consult Logging for the details on how to configure logging. The CA's root logger's name is kea-ctrl-agent, as given in the example above.

Secure Connections

Configuration options related to Kea Control Agent security can be found in the Secure Kea Control Agent section.

Starting and Stopping the Control Agent

kea-ctrl-agent accepts the following command-line switches:

# from installation using libkea-process.so
$ strings ${prefix}/lib/libkea-process.so | sed -n 's/;;;; //p'
# from sources using libkea-process.so
$ strings src/lib/process/.libs/libkea-process.so | sed -n 's/;;;; //p'
# from sources using libkea-process.a
$ strings src/lib/process/.libs/libkea-process.a | sed -n 's/;;;; //p'
# from sources using libcfgrpt.a
$ strings src/lib/process/cfgrpt/.libs/libcfgrpt.a | sed -n 's/;;;; //p'

The CA is started by running its binary and specifying the configuration file it should use. For example:

$ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf

It can be started by keactrl as well (see Managing Kea with keactrl).

Connecting to the Control Agent

For an example of a tool that can take advantage of the RESTful API, see The Kea Shell.

Starting and Stopping the DHCPv4 Server

It is recommended that the Kea DHCPv4 server be started and stopped using keactrl (described in Managing Kea with keactrl); however, it is also possible to run the server directly via the kea-dhcp4 command, which accepts the following command-line switches:

# from installation using libkea-process.so
$ strings ${prefix}/lib/libkea-process.so | sed -n 's/;;;; //p'
# from sources using libkea-process.so
$ strings src/lib/process/.libs/libkea-process.so | sed -n 's/;;;; //p'
# from sources using libkea-process.a
$ strings src/lib/process/.libs/libkea-process.a | sed -n 's/;;;; //p'
# from sources using libcfgrpt.a
$ strings src/lib/process/cfgrpt/.libs/libcfgrpt.a | sed -n 's/;;;; //p'

On startup, the server detects available network interfaces and attempts to open UDP sockets on all interfaces listed in the configuration file. Since the DHCPv4 server opens privileged ports, it requires root access; this daemon must be run as root.

During startup, the server attempts to create a PID file of the form: [pidfile_dir]/[conf name].kea-dhcp4.pid where:

If the file already exists and contains the PID of a live process, the server issues a DHCP4_ALREADY_RUNNING log message and exits. It is possible, though unlikely, that the file is a remnant of a system crash and the process to which the PID belongs is unrelated to Kea. In such a case, it would be necessary to manually delete the PID file.

The server can be stopped using the kill command. When running in a console, the server can also be shut down by pressing Ctrl-c. Kea detects the key combination and shuts down gracefully.

The reconfiguration of each Kea server is triggered by the SIGHUP signal. When a server receives the SIGHUP signal it rereads its configuration file and, 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 is no longer providing any service: a working configuration must be loaded as soon as possible.

DHCPv4 Server Configuration

Introduction

This section explains how to configure the Kea DHCPv4 server using a configuration file.

Before DHCPv4 is started, its configuration file must be created. The basic configuration is as follows:

{
# DHCPv4 configuration starts on the next line
"Dhcp4": {
# First we set up global values
    "valid-lifetime": 4000,
    "renew-timer": 1000,
    "rebind-timer": 2000,
# Next we set up the interfaces to be used by the server.
    "interfaces-config": {
        "interfaces": [ "eth0" ]
    },
# And we specify the type of lease database
    "lease-database": {
        "type": "memfile",
        "persist": true,
        "name": "/var/lib/kea/dhcp4.leases"
    },
# Finally, we list the subnets from which we will be leasing addresses.
    "subnet4": [
        {
            "id": 1,
            "subnet": "192.0.2.0/24",
            "pools": [
                {
                    "pool": "192.0.2.1 - 192.0.2.200"
                }
            ]
        }
    ]
# DHCPv4 configuration ends with the next line
}
}

The following paragraphs provide a brief overview of the parameters in the above example, along with their format. Subsequent sections of this chapter go into much greater detail for these and other parameters.

The lines starting with a hash (#) are comments and are ignored by the server; they do not impact its operation in any way.

The configuration starts in the first line with the initial opening curly bracket (or brace). Each configuration must contain an object specifying the configuration of the Kea module using it. In the example above, this object is called Dhcp4.

The Dhcp4 configuration starts with the "Dhcp4": { line and ends with the corresponding closing brace (in the above example, the brace after the last comment). Everything defined between those lines is considered to be the Dhcp4 configuration.

In general, the order in which those parameters appear does not matter, but there are two caveats. The first one is that the configuration file must be well-formed JSON, meaning that the parameters for any given scope must be separated by a comma, and there must not be a comma after the last parameter. When reordering a configuration file, moving a parameter to or from the last position in a given scope may also require moving the comma. The second caveat is that it is uncommon — although legal JSON — to repeat the same parameter multiple times. If that happens, the last occurrence of a given parameter in a given scope is used, while all previous instances are ignored. This is unlikely to cause any confusion as there are no real-life reasons to keep multiple copies of the same parameter in the configuration file.

The first few DHCPv4 configuration elements define some global parameters. valid-lifetime defines how long the addresses (leases) given out by the server are valid; the default is for a client to be allowed to use a given address for 4000 seconds. (Note that integer numbers are specified as is, without any quotes around them.) renew-timer and rebind-timer are values (also in seconds) that define the T1 and T2 timers that govern when the client begins the renewal and rebind processes.

NOTE:

NOTE:

The interfaces-config map specifies the network interfaces on which the server should listen to DHCP messages. The interfaces parameter specifies a list of network interfaces on which the server should listen. Lists are opened and closed with square brackets, with elements separated by commas. To listen on two interfaces, the interfaces-config element should look like this:

{
"interfaces-config": {
    "interfaces": [ "eth0", "eth1" ]
},
...
}

The next lines define the lease database, the place where the server stores its lease information. This particular example tells the server to use memfile, which is the simplest and fastest database backend. It uses an in-memory database and stores leases on disk in a CSV (comma-separated values) file. This is a very simple configuration example; usually the lease database configuration is more extensive and contains additional parameters. Note that lease-database is an object and opens up a new scope, using an opening brace. Its parameters (just one in this example: type) follow. If there were more than one, they would be separated by commas. This scope is closed with a closing brace. As more parameters for the Dhcp4 definition follow, a trailing comma is present.

Finally, we need to define a list of IPv4 subnets. This is the most important DHCPv4 configuration structure, as the server uses that information to process clients' requests. It defines all subnets from which the server is expected to receive DHCP requests. The subnets are specified with the subnet4 parameter. It is a list, so it starts and ends with square brackets. Each subnet definition in the list has several attributes associated with it, so it is a structure and is opened and closed with braces. At a minimum, a subnet definition must have at least two parameters: subnet, which defines the whole subnet; and pools, which is a list of dynamically allocated pools that are governed by the DHCP server.

The example contains a single subnet. If more than one were defined, additional elements in the subnet4 parameter would be specified and separated by commas. For example, to define three subnets, the following syntax would be used:

{
"subnet4": [
    {
        "id": 1,
        "pools": [ { "pool":  "192.0.2.1 - 192.0.2.200" } ],
        "subnet": "192.0.2.0/24"
    },
    {
        "id": 2,
        "pools": [ { "pool": "192.0.3.100 - 192.0.3.200" } ],
        "subnet": "192.0.3.0/24"
    },
    {
        "id": 3,
        "pools": [ { "pool": "192.0.4.1 - 192.0.4.254" } ],
        "subnet": "192.0.4.0/24"
    }
],
...
}

Note that indentation is optional and is used for aesthetic purposes only. In some cases it may be preferable to use more compact notation.

After all the parameters have been specified, there are two contexts open: global and Dhcp4; thus, two closing curly brackets must be used to close them.

Lease Storage

All leases issued by the server are stored in the lease database. There are three database backends available: memfile (the default), MySQL, PostgreSQL.

Memfile - Basic Storage for Leases

The server is able to store lease data in different repositories. Larger deployments may elect to store leases in a database; Lease Database Configuration describes this option. In typical smaller deployments, though, the server stores lease information in a CSV file rather than a database. As well as requiring less administration, an advantage of using a file for storage is that it eliminates a dependency on third-party database software.

The configuration of the memfile backend is controlled through the Dhcp4/lease-database parameters. The type parameter is mandatory and specifies which storage for leases the server should use, through the "memfile" value. The following list gives additional optional parameters that can be used to configure the memfile backend.

NOTE:

An example configuration of the memfile backend is presented below:

"Dhcp4": {
    "lease-database": {
        "type": "memfile",
        "persist": true,
        "name": "kea-leases4.csv",
        "lfc-interval": 1800,
        "max-row-errors": 100
    }
}

This configuration selects kea-leases4.csv as the storage for lease information and enables persistence (writing lease updates to this file). It also configures the backend to perform a periodic cleanup of the lease file every 1800 seconds (30 minutes) and sets the maximum number of row errors to 100.

Why Is Lease File Cleanup Necessary?

It is important to know how the lease file contents are organized to understand why the periodic lease file cleanup is needed. Every time the server updates a lease or creates a new lease for a client, the new lease information must be recorded in the lease file. For performance reasons, the server does not update the existing client's lease in the file, as this would potentially require rewriting the entire file. Instead, it simply appends the new lease information to the end of the file; the previous lease entries for the client are not removed. When the server loads leases from the lease file, e.g. at server startup, it assumes that the latest lease entry for the client is the valid one. Previous entries are discarded, meaning that the server can reconstruct accurate information about the leases even though there may be many lease entries for each client. However, storing many entries for each client results in a bloated lease file and impairs the performance of the server's startup and reconfiguration, as it needs to process a larger number of lease entries.

Lease file cleanup (LFC) removes all previous entries for each client and leaves only the latest ones. The interval at which the cleanup is performed is configurable, and it should be selected according to the frequency of lease renewals initiated by the clients. The more frequent the renewals, the smaller the value of lfc-interval should be. Note, however, that the LFC takes time and thus it is possible (although unlikely) that, if the lfc-interval is too short, a new cleanup may be started while the previous one is still running. The server would recover from this by skipping the new cleanup when it detected that the previous cleanup was still in progress, but it implies that the actual cleanups will be triggered more rarely than the configured interval. Moreover, triggering a new cleanup adds overhead to the server, which is not able to respond to new requests for a short period of time when the new cleanup process is spawned. Therefore, it is recommended that the lfc-interval value be selected in a way that allows the LFC to complete the cleanup before a new cleanup is triggered.

Lease file cleanup is performed by a separate process (in the background) to avoid a performance impact on the server process. To avoid conflicts between two processes using the same lease files, the LFC process starts with Kea opening a new lease file; the actual LFC process operates on the lease file that is no longer used by the server. There are also other files created as a side effect of the lease file cleanup. The detailed description of the LFC process is located later in this Kea Administrator's Reference Manual: The LFC Process.

Lease Database Configuration

NOTE:

NOTE:

Lease database configuration is controlled through the Dhcp4/lease-database parameters. The database type must be set to memfile, mysql or postgresql, e.g.:

"Dhcp4": { "lease-database": { "type": "mysql", ... }, ... }

Next, the name of the database to hold the leases must be set; this is the name used when the database was created (see First-Time Creation of the MySQL Database or First-Time Creation of the PostgreSQL Database).

For MySQL or PostgreSQL:

"Dhcp4": { "lease-database": { "name": "database-name" , ... }, ... }

If the database is located on a different system from the DHCPv4 server, the database host name must also be specified:

"Dhcp4": { "lease-database": { "host": "remote-host-name", ... }, ... }

Normally, the database is on the same machine as the DHCPv4 server. In this case, set the value to the empty string:

"Dhcp4": { "lease-database": { "host" : "", ... }, ... }

Should the database use a port other than the default, it may be specified as well:

"Dhcp4": { "lease-database": { "port" : 12345, ... }, ... }

Should the database be located on a different system, the administrator may need to specify a longer interval for the connection timeout:

"Dhcp4": { "lease-database": { "connect-timeout" : timeout-in-seconds, ... }, ... }

The default value of five seconds should be more than adequate for local connections. If a timeout is given, though, it should be an integer greater than zero.

The maximum number of times the server automatically attempts to reconnect to the lease database after connectivity has been lost may be specified:

"Dhcp4": { "lease-database": { "max-reconnect-tries" : number-of-tries, ... }, ... }

If the server is unable to reconnect to the database after making the maximum number of attempts, the server will exit. A value of 0 (the default) disables automatic recovery and the server will exit immediately upon detecting a loss of connectivity (MySQL and PostgreSQL only).

The number of milliseconds the server waits between attempts to reconnect to the lease database after connectivity has been lost may also be specified:

"Dhcp4": { "lease-database": { "reconnect-wait-time" : number-of-milliseconds, ... }, ... }

The default value for MySQL and PostgreSQL is 0, which disables automatic recovery and causes the server to exit immediately upon detecting the loss of connectivity.

"Dhcp4": { "lease-database": { "on-fail" : "stop-retry-exit", ... }, ... }

The possible values are:

NOTE:

"Dhcp4": { "lease-database": { "retry-on-startup" : true, ... }, ... }

During server startup, the inability to connect to any of the configured backends is considered fatal only if retry-on-startup is set to false (the default). A fatal error is logged and the server exits, based on the idea that the configuration should be valid at startup. Exiting to the operating system allows nanny scripts to detect the problem. If retry-on-startup is set to true, the server starts reconnection attempts even at server startup or on reconfigure events, and honors the action specified in the on-fail parameter.

The host parameter is used by the MySQL and PostgreSQL backends.

Finally, the credentials of the account under which the server will access the database should be set:

"Dhcp4": {
    "lease-database": {
        "user": "user-name",
        "password": "1234",
        ...
    },
    ...
}

If there is no password to the account, set the password to the empty string "". (This is the default.)

Tuning Database Timeouts

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 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 write timeouts. Kea's corresponding read-timeout and write-timeout configuration parameters specify the timeouts in seconds. For example:

"Dhcp4": { "lease-database": { "read-timeout" : 10, "write-timeout": 20, ... }, ... }

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 indefinitely for the completion of the read and write operations.

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 database type causes a configuration error.

To set a timeout in seconds for PostgreSQL, use the tcp-user-timeout parameter. For example:

"Dhcp4": { "lease-database": { "tcp-user-timeout" : 10, ... }, ... }

Specifying this parameter for other backend types causes a configuration error.

NOTE:

Since Kea.2.7.4, the libdhcp_mysql.so hook library must be loaded in order to store leases in the MySQL Lease Database Backend. Specify the lease backend hook library location:

"Dhcp4": { "hooks-libraries": [
    {
        // the MySQL lease backend hook library required for lease storage.
        "library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
    }, ... ], ... }

Since Kea.2.7.4, the libdhcp_pgsql.so hook library must be loaded in order to store leases in the PostgreSQL Lease Database Backend. Specify the lease backend hook library location.

"Dhcp4": { "hooks-libraries": [
    {
        // the PostgreSQL lease backend hook library required for lease storage.
        "library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
    }, ... ], ... }

Hosts Storage

Kea is also able to store information about host reservations in the database. The hosts database configuration uses the same syntax as the lease database. In fact, the Kea server opens independent connections for each purpose, be it lease or hosts information, which gives the most flexibility. Kea can keep leases and host reservations separately, but can also point to the same database. Currently the supported hosts database types are MySQL and PostgreSQL.

The following configuration can be used to configure a connection to MySQL:

"Dhcp4": {
    "hosts-database": {
        "type": "mysql",
        "name": "kea",
        "user": "kea",
        "password": "1234",
        "host": "localhost",
        "port": 3306
    }
}

Depending on the database configuration, many of the parameters may be optional.

Please note that usage of hosts storage is optional. A user can define all host reservations in the configuration file, and that is the recommended way if the number of reservations is small. However, when the number of reservations grows, it is more convenient to use host storage. Please note that both storage methods (the configuration file and one of the supported databases) can be used together. If hosts are defined in both places, the definitions from the configuration file are checked first and external storage is checked later, if necessary.

Host information can be placed in multiple stores. Operations are performed on the stores in the order they are defined in the configuration file, although this leads to a restriction in ordering in the case of a host reservation addition; read-only stores must be configured after a (required) read-write store, or the addition will fail.

NOTE:

DHCPv4 Hosts Database Configuration

Hosts database configuration is controlled through the Dhcp4/hosts-database parameters. If enabled, the type of database must be set to mysql or postgresql.

"Dhcp4": { "hosts-database": { "type": "mysql", ... }, ... }

Next, the name of the database to hold the reservations must be set; this is the name used when the lease database was created (see Supported Backends for instructions on how to set up the desired database type):

"Dhcp4": { "hosts-database": { "name": "database-name" , ... }, ... }

If the database is located on a different system than the DHCPv4 server, the database host name must also be specified:

"Dhcp4": { "hosts-database": { "host": remote-host-name, ... }, ... }

Normally, the database is on the same machine as the DHCPv4 server. In this case, set the value to the empty string:

"Dhcp4": { "hosts-database": { "host" : "", ... }, ... }

Should the database use a port different than the default, it may be specified as well:

"Dhcp4": { "hosts-database": { "port" : 12345, ... }, ... }

The maximum number of times the server automatically attempts to reconnect to the host database after connectivity has been lost may be specified:

"Dhcp4": { "hosts-database": { "max-reconnect-tries" : number-of-tries, ... }, ... }

If the server is unable to reconnect to the database after making the maximum number of attempts, the server will exit. A value of 0 (the default) disables automatic recovery and the server will exit immediately upon detecting a loss of connectivity (MySQL and PostgreSQL only).

The number of milliseconds the server waits between attempts to reconnect to the host database after connectivity has been lost may also be specified:

"Dhcp4": { "hosts-database": { "reconnect-wait-time" : number-of-milliseconds, ... }, ... }

The default value for MySQL and PostgreSQL is 0, which disables automatic recovery and causes the server to exit immediately upon detecting the loss of connectivity.

"Dhcp4": { "hosts-database": { "on-fail" : "stop-retry-exit", ... }, ... }

The possible values are:

NOTE:

"Dhcp4": { "hosts-database": { "retry-on-startup" : true, ... }, ... }

During server startup, the inability to connect to any of the configured backends is considered fatal only if retry-on-startup is set to false (the default). A fatal error is logged and the server exits, based on the idea that the configuration should be valid at startup. Exiting to the operating system allows nanny scripts to detect the problem. If retry-on-startup is set to true, the server starts reconnection attempts even at server startup or on reconfigure events, and honors the action specified in the on-fail parameter.

Finally, the credentials of the account under which the server will access the database should be set:

"Dhcp4": {
    "hosts-database": {
        "user": "user-name",
        "password": "1234",
        ...
    },
    ...
}

If there is no password to the account, set the password to the empty string "". (This is the default.)

The multiple-storage extension uses a similar syntax; a configuration is placed into a hosts-databases list instead of into a hosts-database entry, as in:

"Dhcp4": { "hosts-databases": [ { "type": "mysql", ... }, ... ], ... }

If the same host is configured both in-file and in-database, Kea does not issue a warning, as it would if both were specified in the same data source. Instead, the host configured in-file has priority over the one configured in-database.

Using Read-Only Databases for Host Reservations With DHCPv4

In some deployments, the user whose name is specified in the database backend configuration may not have write privileges to the database. This is often required by the policy within a given network to secure the data from being unintentionally modified. In many cases administrators have deployed inventory databases, which contain substantially more information about the hosts than just the static reservations assigned to them. The inventory database can be used to create a view of a Kea hosts database and such a view is often read-only.

Kea host-database backends operate with an implicit configuration to both read from and write to the database. If the user does not have write access to the host database, the backend will fail to start and the server will refuse to start (or reconfigure). However, if access to a read-only host database is required for retrieving reservations for clients and/or assigning specific addresses and options, it is possible to explicitly configure Kea to start in "read-only" mode. This is controlled by the readonly boolean parameter as follows:

"Dhcp4": { "hosts-database": { "readonly": true, ... }, ... }

Setting this parameter to false configures the database backend to operate in "read-write" mode, which is also the default configuration if the parameter is not specified.

NOTE:

Since Kea.2.7.4, the libdhcp_mysql.so hook library must be loaded in order to store host reservations in the MySQL Host Database Backend. Specify the lease backend hook library location:

"Dhcp4": { "hooks-libraries": [
    {
        // the MySQL host backend hook library required for host storage.
        "library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
    }, ... ], ... }

Since Kea.2.7.4, the libdhcp_pgsql.so hook library must be loaded in order to store host reservations in the PostgreSQL Host Database Backend. Specify the lease backend hook library location.

"Dhcp4": { "hooks-libraries": [
    {
        // the PostgreSQL host backend hook library required for host storage.
        "library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
    }, ... ], ... }

Tuning Database Timeouts for Hosts Storage

See Tuning Database Timeouts.

Interface Configuration

The DHCPv4 server must be configured to listen on specific network interfaces. The simplest network interface configuration tells the server to listen on all available interfaces:

"Dhcp4": {
    "interfaces-config": {
        "interfaces": [ "*" ]
    },
    ...
}

The asterisk plays the role of a wildcard and means "listen on all interfaces." However, it is usually a good idea to explicitly specify interface names:

"Dhcp4": {
    "interfaces-config": {
        "interfaces": [ "eth1", "eth3" ]
    },
    ...
}

It is possible to use an interface wildcard (*) concurrently with explicit interface names:

"Dhcp4": {
    "interfaces-config": {
        "interfaces": [ "eth1", "eth3", "*" ]
    },
    ...
}

This format should only be used when it is desired to temporarily override a list of interface names and listen on all interfaces.

Some deployments of DHCP servers require that the servers listen on interfaces with multiple IPv4 addresses configured. In these situations, the address to use can be selected by appending an IPv4 address to the interface name in the following manner:

"Dhcp4": {
    "interfaces-config": {
        "interfaces": [ "eth1/10.0.0.1", "eth3/192.0.2.3" ]
    },
    ...
}

Should the server be required to listen on multiple IPv4 addresses assigned to the same interface, multiple addresses can be specified for an interface as in the example below:

"Dhcp4": {
    "interfaces-config": {
        "interfaces": [ "eth1/10.0.0.1", "eth1/10.0.0.2" ]
    },
    ...
}

Alternatively, if the server should listen on all addresses for the particular interface, an interface name without any address should be specified.

Kea supports responding to directly connected clients which do not have an address configured. This requires the server to inject the hardware address of the destination into the data-link layer of the packet being sent to the client. The DHCPv4 server uses raw sockets to achieve this, and builds the entire IP/UDP stack for the outgoing packets. The downside of raw socket use, however, is that incoming and outgoing packets bypass the firewalls (e.g. iptables).

Handling traffic on multiple IPv4 addresses assigned to the same interface can be a challenge, as raw sockets are bound to the interface. When the DHCP server is configured to use the raw socket on an interface to receive DHCP traffic, advanced packet filtering techniques (e.g. the BPF) must be used to receive unicast traffic on the desired addresses assigned to the interface. Whether clients use the raw socket or the UDP socket depends on whether they are directly connected (raw socket) or relayed (either raw or UDP socket).

Therefore, in deployments where the server does not need to provision the directly connected clients and only receives the unicast packets from the relay agents, the Kea server should be configured to use UDP sockets instead of raw sockets. The following configuration demonstrates how this can be achieved:

"Dhcp4": {
    "interfaces-config": {
        "interfaces": [ "eth1", "eth3" ],
        "dhcp-socket-type": "udp"
    },
    ...
}

The dhcp-socket-type parameter specifies that the IP/UDP sockets will be opened on all interfaces on which the server listens, i.e. "eth1" and "eth3" in this example. If dhcp-socket-type is set to raw, it configures the server to use raw sockets instead. If the dhcp-socket-type value is not specified, the default value raw is used.

Using UDP sockets automatically disables the reception of broadcast packets from directly connected clients. This effectively means that UDP sockets can be used for relayed traffic only. When using raw sockets, both the traffic from the directly connected clients and the relayed traffic are handled.

Caution should be taken when configuring the server to open multiple raw sockets on the interface with several IPv4 addresses assigned. If the directly connected client sends the message to the broadcast address, all sockets on this link will receive this message and multiple responses will be sent to the client. Therefore, the configuration with multiple IPv4 addresses assigned to the interface should not be used when the directly connected clients are operating on that link. To use a single address on such an interface, the "interface-name/address" notation should be used.

NOTE:

In a typical environment, the DHCP server is expected to send back a response on the same network interface on which the query was received. This is the default behavior. However, in some deployments it is desired that the outbound (response) packets be sent as regular traffic and the outbound interface be determined by the routing tables. This kind of asymmetric traffic is uncommon, but valid. Kea supports a parameter called outbound-interface that controls this behavior. It supports two values: the first one, same-as-inbound, tells Kea to send back the response on the same interface where the query packet was received. This is the default behavior. The second parameter, use-routing, tells Kea to send regular UDP packets and let the kernel's routing table determine the most appropriate interface. This only works when dhcp-socket-type is set to udp. An example configuration looks as follows:

"Dhcp4": {
    "interfaces-config": {
        "interfaces": [ "eth1", "eth3" ],
        "dhcp-socket-type": "udp",
        "outbound-interface": "use-routing"
    },
    ...
}

Interfaces are re-detected at each reconfiguration. This behavior can be disabled by setting the re-detect value to false, for instance:

"Dhcp4": {
    "interfaces-config": {
        "interfaces": [ "eth1", "eth3" ],
        "re-detect": false
    },
    ...
}

Note that interfaces are not re-detected during config-test.

Usually loopback interfaces (e.g. the lo or lo0 interface) are not configured, but if a loopback interface is explicitly configured and IP/UDP sockets are specified, the loopback interface is accepted.

For example, this setup can be used to run Kea in a FreeBSD jail having only a loopback interface, to service a relayed DHCP request:

"Dhcp4": {
    "interfaces-config": {
        "interfaces": [ "lo0" ],
        "dhcp-socket-type": "udp"
    },
    ...
}

Kea binds the service sockets for each interface on startup. If another process is already using a port, then Kea logs the message and suppresses an error. DHCP service runs, but it is unavailable on some interfaces.

The "service-sockets-require-all" option makes Kea require all sockets to be successfully bound. If any opening fails, Kea interrupts the initialization and exits with a non-zero status. (Default is false).

"Dhcp4": {
    "interfaces-config": {
        "interfaces": [ "eth1", "eth3" ],
        "service-sockets-require-all": true
    },
    ...
}

Sometimes, immediate interruption isn't a good choice. The port can be unavailable only temporary. In this case, retrying the opening may resolve the problem. Kea provides two options to specify the retrying: service-sockets-max-retries and service-sockets-retry-wait-time.

The first defines a maximal number of retries that Kea makes to open a socket. The zero value (default) means that the Kea doesn't retry the process.

The second defines a wait time (in milliseconds) between attempts. The default value is 5000 (5 seconds).

"Dhcp4": {
    "interfaces-config": {
        "interfaces": [ "eth1", "eth3" ],
        "service-sockets-max-retries": 5,
        "service-sockets-retry-wait-time": 5000
    },
    ...
}

If "service-sockets-max-retries" is non-zero and "service-sockets-require-all" is false, then Kea retries the opening (if needed) but does not fail if any socket is still not opened.

Issues With Unicast Responses to DHCPINFORM

The use of UDP sockets has certain benefits in deployments where the server receives only relayed traffic; these benefits are mentioned in Interface Configuration. From the administrator's perspective it is often desirable to configure the system's firewall to filter out unwanted traffic, and the use of UDP sockets facilitates this. However, the administrator must also be aware of the implications related to filtering certain types of traffic, as it may impair the DHCP server's operation.

In this section we focus on the case when the server receives the DHCPINFORM message from the client via a relay. According to RFC 2131, the server should unicast the DHCPACK response to the address carried in the ciaddr field. When the UDP socket is in use, the DHCP server relies on the low-level functions of an operating system to build the data link, IP, and UDP layers of the outgoing message. Typically, the OS first uses ARP to obtain the client's link-layer address to be inserted into the frame's header, if the address is not cached from a previous transaction that the client had with the server. When the ARP exchange is successful, the DHCP message can be unicast to the client, using the obtained address.

Some system administrators block ARP messages in their network, which causes issues for the server when it responds to the DHCPINFORM messages because the server is unable to send the DHCPACK if the preceding ARP communication fails. Since the OS is entirely responsible for the ARP communication and then sending the DHCP packet over the wire, the DHCP server has no means to determine that the ARP exchange failed and the DHCP response message was dropped. Thus, the server does not log any error messages when the outgoing DHCP response is dropped. At the same time, all hooks pertaining to the packet-sending operation will be called, even though the message never reaches its destination.

Note that the issue described in this section is not observed when raw sockets are in use, because, in this case, the DHCP server builds all the layers of the outgoing message on its own and does not use ARP. Instead, it inserts the value carried in the chaddr field of the DHCPINFORM message into the link layer.

Server administrators willing to support DHCPINFORM messages via relays should not block ARP traffic in their networks, or should use raw sockets instead of UDP sockets.

IPv4 Subnet Identifier

The subnet identifier (subnet ID) is a unique number associated with a particular subnet. In principle, it is used to associate clients' leases with their respective subnets. The server configuration must contain unique and stable identifiers for all subnets.

NOTE:

The following configuration assigns the specified subnet identifier to a newly configured subnet:

"Dhcp4": {
    "subnet4": [
        {
            "subnet": "192.0.2.0/24",
            "id": 1024,
            ...
        }
    ]
}

IPv4 Subnet Prefix

The subnet prefix is the second way to identify a subnet. Kea can accept non-canonical subnet addresses; for instance, this configuration is accepted:

"Dhcp4": {
    "subnet4": [
        {
           "subnet": "192.0.2.1/24",
            ...
        }
    ]
}

This works even if there is another subnet with the "192.0.2.0/24" prefix; only the textual form of subnets are compared to avoid duplicates.

NOTE:

Configuration of IPv4 Address Pools

The main role of a DHCPv4 server is address assignment. For this, the server must be configured with at least one subnet and one pool of dynamic addresses to be managed. For example, assume that the server is connected to a network segment that uses the 192.0.2.0/24 prefix. The administrator of that network decides that addresses from the range 192.0.2.10 to 192.0.2.20 are going to be managed by the DHCPv4 server. Such a configuration can be achieved in the following way:

"Dhcp4": {
    "subnet4": [
        {
            "subnet": "192.0.2.0/24",
            "pools": [
                { "pool": "192.0.2.10 - 192.0.2.20" }
            ],
            ...
        }
    ]
}

Note that subnet is defined as a simple string, but the pools parameter is actually a list of pools; for this reason, the pool definition is enclosed in square brackets, even though only one range of addresses is specified.

Each pool is a structure that contains the parameters that describe a single pool. Currently there is only one parameter, pool, which gives the range of addresses in the pool.

It is possible to define more than one pool in a subnet; continuing the previous example, further assume that 192.0.2.64/26 should also be managed by the server. It could be written as 192.0.2.64 to 192.0.2.127, or it can be expressed more simply as 192.0.2.64/26. Both formats are supported by Dhcp4 and can be mixed in the pool list. For example, the following pools could be defined:

"Dhcp4": {
    "subnet4": [
        {
            "subnet": "192.0.2.0/24",
            "pools": [
                { "pool": "192.0.2.10-192.0.2.20" },
                { "pool": "192.0.2.64/26" }
            ],
            ...
        }
    ],
    ...
}

White space in pool definitions is ignored, so spaces before and after the hyphen are optional. They can be used to improve readability.

The number of pools is not limited, but for performance reasons it is recommended to use as few as possible.

The server may be configured to serve more than one subnet. To add a second subnet, use a command similar to the following:

"Dhcp4": {
    "subnet4": [
        {
            "subnet": "192.0.2.0/24",
            "pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ],
            ...
        },
        {
            "subnet": "192.0.3.0/24",
            "pools": [ { "pool": "192.0.3.100 - 192.0.3.200" } ],
            ...
        },
        {
            "subnet": "192.0.4.0/24",
            "pools": [ { "pool": "192.0.4.1 - 192.0.4.254" } ],
            ...
        }
    ]
}

When configuring a DHCPv4 server using prefix/length notation, please pay attention to the boundary values. When specifying that the server can use a given pool, it is also able to allocate the first (typically a network address) and the last (typically a broadcast address) address from that pool. In the aforementioned example of pool 192.0.3.0/24, both the 192.0.3.0 and 192.0.3.255 addresses may be 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 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 (Kea DHCPv4 Compatibility Configuration Parameters) does this automatically, rather than requiring explicit configuration of many pools or reservations for fake hosts. When true, it applies only to subnets of prefix length 24 or smaller, i.e. larger address space; 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:

Sending T1 (Option 58) and T2 (Option 59)

According to RFC 2131, servers should send values for T1 and T2 that are 50% and 87.5% of the lease lifetime, respectively. By default, kea-dhcp4 does not send either value; it can be configured to send values that are either specified explicitly or that are calculated as percentages of the lease time. The server's behavior is governed by a combination of configuration parameters, two of which have already been mentioned. To send specific, fixed values use the following two parameters:

The server only sends T2 if it is less than the valid lease time. T1 is only sent if T2 is being sent and T1 is less than T2; or T2 is not being sent and T1 is less than the valid lease time.

Calculating the values is controlled by the following three parameters.

NOTE:

Standard DHCPv4 Options

One of the major features of the DHCPv4 server is the ability to provide configuration options to clients. Most of the options are sent by the server only if the client explicitly requests them using the Parameter Request List option. Those that do not require inclusion in the Parameter Request List option are commonly used options, e.g. "Domain Server", and options which require special behavior, e.g. "Client FQDN", which is returned to the client if the client has included this option in its message to the server.

List of standard DHCPv4 options configurable by an administrator comprises the list of the standard DHCPv4 options whose values can be configured using the configuration structures described in this section. This table excludes the options which require special processing and thus cannot be configured with fixed values. The last column of the table indicates which options can be sent by the server even when they are not requested in the Parameter Request List option, and those which are sent only when explicitly requested.

The following example shows how to configure the addresses of DNS servers, which is one of the most frequently used options. Options specified in this way are considered global and apply to all configured subnets.

"Dhcp4": {
    "option-data": [
        {
           "name": "domain-name-servers",
           "code": 6,
           "space": "dhcp4",
           "csv-format": true,
           "data": "192.0.2.1, 192.0.2.2"
        },
        ...
    ]
}

Note that either name or code is required; there is no need to specify both. space has a default value of dhcp4, so this can be skipped as well if a regular (not encapsulated) DHCPv4 option is defined. Finally, csv-format defaults to true, so it too can be skipped, unless the option value is specified as a hexadecimal string. Therefore, the above example can be simplified to:

"Dhcp4": {
    "option-data": [
        {
           "name": "domain-name-servers",
           "data": "192.0.2.1, 192.0.2.2"
        },
        ...
    ]
}

Defined options are added to the response when the client requests them, with a few exceptions which are always added. To enforce the addition of a particular option, set the always-send flag to true as in:

"Dhcp4": {
    "option-data": [
        {
           "name": "domain-name-servers",
           "data": "192.0.2.1, 192.0.2.2",
           "always-send": true
        },
        ...
    ]
}

The effect is the same as if the client added the option code in the Parameter Request List option (or its equivalent for vendor options):

"Dhcp4": {
    "option-data": [
        {
           "name": "domain-name-servers",
           "data": "192.0.2.1, 192.0.2.2",
           "always-send": true
        },
        ...
    ],
    "subnet4": [
        {
           "subnet": "192.0.3.0/24",
           "option-data": [
               {
                   "name": "domain-name-servers",
                   "data": "192.0.3.1, 192.0.3.2"
               },
               ...
           ],
           ...
        },
        ...
    ],
    ...
}

In the example above, the domain-name-servers option respects the global always-send flag and is always added to responses, but for subnet 192.0.3.0/24, the value is taken from the subnet-level option data specification.

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):

"Dhcp4": {
    "option-data": [
        {
           "name": "domain-name-servers",
           "data": "192.0.2.1, 192.0.2.2"
        },
        ...
    ],
    "subnet4": [
        {
           "subnet": "192.0.3.0/24",
           "option-data": [
               {
                   "name": "domain-name-servers",
                   "never-send": true
               },
               ...
           ],
           ...
        },
        ...
    ],
    ...
}

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.

NOTE:

NOTE:

NOTE:

The name parameter specifies the option name. For a list of currently supported names, see List of standard DHCPv4 options configurable by an administrator below. The code parameter specifies the option code, which must match one of the values from that list. The next line specifies the option space, which must always be set to dhcp4 as these are standard DHCPv4 options. For other option spaces, including custom option spaces, see Nested DHCPv4 Options (Custom Option Spaces). The next line specifies the format in which the data will be entered; use of CSV (comma-separated values) is recommended. The sixth line gives the actual value to be sent to clients. The data parameter is specified as normal text, with values separated by commas if more than one value is allowed.

Options can also be configured as hexadecimal values. If csv-format is set to false, option data must be specified as a hexadecimal string. The following commands configure the domain-name-servers option for all subnets with the following addresses: 192.0.3.1 and 192.0.3.2. Note that csv-format is set to false.

"Dhcp4": {
    "option-data": [
        {
            "name": "domain-name-servers",
            "code": 6,
            "space": "dhcp4",
            "csv-format": false,
            "data": "C0 00 03 01 C0 00 03 02"
        },
        ...
    ],
    ...
}

Kea supports the following formats when specifying hexadecimal data:

Care should be taken to use proper encoding when using hexadecimal format; Kea's ability to validate data correctness in hexadecimal is limited.

It is also possible to specify data for binary options as a single-quoted text string within double quotes as shown (note that csv-format must be set to false):

"Dhcp4": {
    "option-data": [
        {
            "name": "user-class",
            "code": 77,
            "space": "dhcp4",
            "csv-format": false,
            "data": "'convert this text to binary'"
        },
        ...
    ],
    ...
}

Most of the parameters in the option-data structure are optional and can be omitted in some circumstances, as discussed in Unspecified Parameters for DHCPv4 Option Configuration.

It is possible to specify or override options on a per-subnet basis. If clients connected to most subnets are expected to get the same values of a given option, administrators should use global options. On the other hand, if different values are used in each subnet, it does not make sense to specify global option values; rather, only subnet-specific ones should be set.

The following commands override the global DNS servers option for a particular subnet, setting a single DNS server with address 192.0.2.3:

"Dhcp4": {
    "subnet4": [
        {
            "option-data": [
                {
                    "name": "domain-name-servers",
                    "code": 6,
                    "space": "dhcp4",
                    "csv-format": true,
                    "data": "192.0.2.3"
                },
                ...
            ],
            ...
        },
        ...
    ],
    ...
}

In some cases it is useful to associate some options with an address pool from which a client is assigned a lease. Pool-specific option values override subnet-specific and global option values; it is not possible to prioritize assignment of pool-specific options via the order of pool declarations in the server configuration.

The following configuration snippet demonstrates how to specify the DNS servers option, which is assigned to a client only if the client obtains an address from the given pool:

"Dhcp4": {
    "subnet4": [
        {
            "pools": [
                {
                    "pool": "192.0.2.1 - 192.0.2.200",
                    "option-data": [
                        {
                            "name": "domain-name-servers",
                            "data": "192.0.2.3"
                         },
                         ...
                    ],
                    ...
                },
                ...
            ],
            ...
        },
        ...
    ],
    ...
}

Options can also be specified in class or host-reservation scope. The current Kea options precedence order is (from most important to least): host reservation, pool, subnet, shared network, class, global.

When a data field is a string and that string contains the comma (,; U+002C) character, the comma must be escaped with two backslashes (\\,; U+005C). This double escape is required because both the routine splitting of CSV data into fields and JSON use the same escape character; a single escape (\,) would make the JSON invalid. For example, the string "foo,bar" must be represented as:

"Dhcp4": {
    "subnet4": [
        {
            "pools": [
                {
                    "option-data": [
                        {
                            "name": "boot-file-name",
                            "data": "foo\\,bar"
                        }
                    ]
                },
                ...
            ],
            ...
        },
        ...
    ],
    ...
}

Some options are designated as arrays, which means that more than one value is allowed. For example, the option time-servers allows the specification of more than one IPv4 address, enabling clients to obtain the addresses of multiple NTP servers.

Custom DHCPv4 Options describes the configuration syntax to create custom option definitions (formats). Creation of custom definitions for standard options is generally not permitted, even if the definition being created matches the actual option format defined in the RFCs. However, there is an exception to this rule for standard options for which Kea currently does not provide a definition. To use such options, a server administrator must create a definition as described in Custom DHCPv4 Options in the dhcp4 option space. This definition should match the option format described in the relevant RFC, but the configuration mechanism allows any option format as there is currently no way to validate it.

The currently supported standard DHCPv4 options are listed in the table below. "Name" and "Code" are the values that should be used as a name/code in the option-data structures. "Type" designates the format of the data; the meanings of the various types are given in List of standard DHCP option types.

List of standard DHCPv4 options configurable by an administrator

NOTE:

Kea also supports other options than those listed above; the following options are returned by the Kea engine itself and in general should not be configured manually.

List of standard DHCPv4 options managed by Kea on its own and not directly configurable by an administrator

The following table lists all option types used in the previous two tables with a description of what values are accepted for them.

List of standard DHCP option types

Kea also supports the Relay Agent Information (RAI, defined in RFC 3046) option, sometimes referred to as the relay option, agent option, or simply option 82. The option itself is just a container and does not convey any information on its own. The following table contains a list of RAI sub-options that Kea can understand. The RAI and its sub-options are inserted by the relay agent and received by Kea; there is no need for Kea to be configured with those options. Kea's classification and flexible ID features in host reservations can be used to process those and other options not listed in the table below.

List of RAI sub-options that Kea can understand

All other RAI sub-options (including those not listed here) can be used in client classification to classify incoming packets to specific classes, and/or by libdhcp_flex_id.so to construct a unique device identifier. For more information about expressions used in client classification and flexible identifiers, see Client Classification. The RAI sub-options can be referenced using relay4[option-code].hex; for example, to classify packets based on the remote-id (sub-option code 2), one would use relay4[2].hex. An example client class that includes all packets with a specific remote-id value would look as follows:

"Dhcp4": {
    "client-classes": [
        {
            "name": "remote-id-1020304",
            "test": "relay4[2].hex == 0x01020304",
            ...
        }
    ],
    ...
}

Classes may be used to segregate traffic into a relatively small number of groups, which then can be used to select specific subnets, pools and extra options, and more. If per-host behavior is necessary, using host reservations with flexible identifiers is strongly recommended.

CableLabs Client Conf Suboptions

CableLabs client conf option ("cablelabs-client-conf" code 122) is a container of suboptions in the "cablelabs-client-conf" space listed in the table below.

List of CableLabs Client Conf sub-options that Kea can understand

These suboptions are defined in RFC 3495 including its errata which clarifies the realm format, RFC 3594 and RFC 3634.

NOTE:

Custom DHCPv4 Options

Kea supports custom (non-standard) DHCPv4 options. Let's say that we want to define a new DHCPv4 option called foo, which will have code 222 and will convey a single, unsigned, 32-bit integer value. Such an option can be defined by putting the following entry in the configuration file:

"Dhcp4": {
    "option-def": [
        {
            "name": "foo",
            "code": 222,
            "type": "uint32",
            "array": false,
            "record-types": "",
            "space": "dhcp4",
            "encapsulate": ""
        },
        ...
    ],
    ...
}

The false value of the array parameter determines that the option does NOT comprise an array of uint32 values but is, instead, a single value. Two other parameters have been left blank: record-types and encapsulate. The former specifies the comma-separated list of option data fields, if the option comprises a record of data fields. The record-types value should be non-empty if type is set to "record"; otherwise it must be left blank. The latter parameter specifies the name of the option space being encapsulated by the particular option. If the particular option does not encapsulate any option space, the parameter should be left blank. Note that the option-def configuration statement only defines the format of an option and does not set its value(s).

The name, code, and type parameters are required; all others are optional. The array parameter's default value is false. The record-types and encapsulate parameters' default values are blank (""). The default space is dhcp4.

Once the new option format is defined, its value is set in the same way as for a standard option. For example, the following commands set a global value that applies to all subnets.

"Dhcp4": {
    "option-data": [
        {
            "name": "foo",
            "code": 222,
            "space": "dhcp4",
            "csv-format": true,
            "data": "12345"
        },
        ...
    ],
    ...
}

New options can take more complex forms than the simple use of primitives (uint8, string, ipv4-address, etc.); it is possible to define an option comprising a number of existing primitives.

For example, say we want to define a new option that will consist of an IPv4 address, followed by an unsigned 16-bit integer, followed by a boolean value, followed by a text string. Such an option could be defined in the following way:

"Dhcp4": {
    "option-def": [
        {
            "name": "bar",
            "code": 223,
            "space": "dhcp4",
            "type": "record",
            "array": false,
            "record-types": "ipv4-address, uint16, boolean, string",
            "encapsulate": ""
        },
        ...
    ],
    ...
}

The type parameter is set to "record" to indicate that the option contains multiple values of different types. These types are given as a comma-separated list in the record-types field and should be ones from those listed in List of standard DHCP option types.

The option's values are set in an option-data statement as follows:

"Dhcp4": {
    "option-data": [
        {
            "name": "bar",
            "space": "dhcp4",
            "code": 223,
            "csv-format": true,
            "data": "192.0.2.100, 123, true, Hello World"
        }
    ],
    ...
}

The csv-format parameter is set to true to indicate that the data field comprises a comma-separated list of values. The values in data must correspond to the types set in the record-types field of the option definition.

When array is set to true and type is set to "record", the last field is an array, i.e. it can contain more than one value, as in:

"Dhcp4": {
    "option-def": [
        {
            "name": "bar",
            "code": 223,
            "space": "dhcp4",
            "type": "record",
            "array": true,
            "record-types": "ipv4-address, uint16",
            "encapsulate": ""
        },
        ...
    ],
    ...
}

The new option content is one IPv4 address followed by one or more 16-bit unsigned integers.

NOTE:

NOTE:

DHCPv4 Private Options

Options with a code between 224 and 254 are reserved for private use. They can be defined at the global scope or at the client-class local scope; this allows option definitions to be used depending on context, and option data to be set accordingly. For instance, to configure an old PXEClient vendor:

"Dhcp4": {
    "client-classes": [
        {
            "name": "pxeclient",
            "test": "option[vendor-class-identifier].text == 'PXEClient'",
            "option-def": [
                {
                    "name": "configfile",
                    "code": 209,
                    "type": "string"
                }
            ],
            ...
        },
        ...
    ],
    ...
}

As the Vendor-Specific Information (VSI) option (code 43) has a vendor-specific format, i.e. can carry either raw binary value or sub-options, this mechanism is also available for this option.

In the following example taken from a real configuration, two vendor classes use option 43 for different and incompatible purposes:

"Dhcp4": {
    "option-def": [
        {
            "name": "cookie",
            "code": 1,
            "type": "string",
            "space": "APC"
        },
        {
            "name": "mtftp-ip",
            "code": 1,
            "type": "ipv4-address",
            "space": "PXE"
        },
        ...
    ],
    "client-classes": [
        {
            "name": "APC",
            "test": "option[vendor-class-identifier].text == 'APC'",
            "option-def": [
                {
                    "name": "vendor-encapsulated-options",
                    "type": "empty",
                    "encapsulate": "APC"
                }
            ],
            "option-data": [
                {
                    "name": "cookie",
                    "space": "APC",
                    "data": "1APC"
                },
                {
                    "name": "vendor-encapsulated-options"
                },
                ...
            ],
            ...
        },
        {
            "name": "PXE",
            "test": "option[vendor-class-identifier].text == 'PXE'",
            "option-def": [
                {
                    "name": "vendor-encapsulated-options",
                    "type": "empty",
                    "encapsulate": "PXE"
                }
            ],
            "option-data": [
                {
                    "name": "mtftp-ip",
                    "space": "PXE",
                    "data": "0.0.0.0"
                },
                {
                    "name": "vendor-encapsulated-options"
                },
                ...
            ],
            ...
        },
        ...
    ],
    ...
}

The definition used to decode a VSI option is:

NOTE:

NOTE:

NOTE:

DHCPv4 Vendor-Specific Options

Currently there are two option spaces defined for kea-dhcp4: dhcp4 (for the top-level DHCPv4 options) and "vendor-encapsulated-options-space", which is empty by default but in which options can be defined. Those options are carried in the Vendor-Specific Information option (code 43). The following examples show how to define an option foo with code 1 that comprises an IPv4 address, an unsigned 16-bit integer, and a string. The foo option is conveyed in a Vendor-Specific Information option.

The first step is to define the format of the option:

"Dhcp4": {
    "option-def": [
        {
            "name": "foo",
            "code": 1,
            "space": "vendor-encapsulated-options-space",
            "type": "record",
            "array": false,
            "record-types": "ipv4-address, uint16, string",
            "encapsulate": ""
        }
    ],
    ...
}

Note that the option space is set to "vendor-encapsulated-options-space". Once the option format is defined, the next step is to define actual values for that option:

"Dhcp4": {
    "option-data": [
        {
            "name": "foo",
            "space": "vendor-encapsulated-options-space",
            "code": 1,
            "csv-format": true,
            "data": "192.0.2.3, 123, Hello World"
        }
    ],
    ...
}

In this example, we also include the Vendor-Specific Information option, which conveys our sub-option foo. This is required; otherwise, the option will not be included in messages sent to the client.

"Dhcp4": {
    "option-data": [
        {
            "name": "vendor-encapsulated-options"
        }
    ],
    ...
}

Alternatively, the option can be specified using its code.

"Dhcp4": {
    "option-data": [
        {
            "code": 43
        }
    ],
    ...
}

Another popular option that is often somewhat imprecisely called the "vendor option" is option 125. Its proper name is the "vendor-independent vendor-specific information option" or "vivso". The idea behind vivso options is that each vendor has its own unique set of options with their own custom formats. The vendor is identified by a 32-bit unsigned integer called enterprise-number or vendor-id.

The standard spaces defined in Kea and their options are:

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 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:

"Dhcp4": {
    // First, we need to define that the sub-option 2 in vivso option for
    // vendor-id 25167 has a specific format (it's a plain string in this example).
    // After this definition, we can specify values for option tftp.
    "option-def": [
        {
            // We define a short name, so the option can be referenced by name.
            // The option has code 2 and resides within vendor space 25167.
            // Its data is a plain string.
            "name": "tftp",
            "code": 2,
            "space": "vendor-25167",
            "type": "string"
        }
    ],
    "client-classes": [
        {
            // We now need to tell Kea how to recognize when to use vendor space 25167.
            // Usually we can use a simple expression, such as checking if the device
            // sent a vivso option with specific vendor-id, e.g. "vendor[4491].exists".
            // Unfortunately, Genexis is a bit unusual in this aspect, because it
            // doesn't send vivso. In this case we need to look into the vendor class
            // (option code 60) and see if there's a specific string that identifies
            // the device. Alternatively, one can make use of the automated `VENDOR_CLASS_`
            // client class and replace "name" and "test" with `"name": "VENDOR_CLASS_HMC1000"`
            // and no test expression.
            "name": "cpe_genexis",
            "test": "substring(option[60].hex,0,7) == 'HMC1000'",
            // Once the device is recognized, we want to send two options:
            // the vivso option with vendor-id set to 25167, and a sub-option 2.
            "option-data": [
                {
                    "name": "vivso-suboptions",
                    "data": "25167"
                },
                // The sub-option 2 value is defined as any other option. However,
                // we want to send this sub-option 2, even when the client didn't
                // explicitly request it (often there is no way to do that for
                // vendor options). Therefore we use always-send to force Kea
                // to always send this option when 25167 vendor space is involved.
                {
                    "name": "tftp",
                    "space": "vendor-25167",
                    "data": "tftp://192.0.2.1/genexis/HMC1000.v1.3.0-R.img",
                    "always-send": true
                }
            ]
        }
    ]
}

By default, Kea sends back only those options that are requested by a client, unless there are protocol rules that tell the DHCP server to always send an option. This approach works nicely in most cases and avoids problems with clients refusing responses with options they do not understand. However, the situation with vendor options is more complex, as they are not requested the same way as other options, are not well-documented in official RFCs, or vary by vendor.

Some vendors (such as DOCSIS, identified by vendor option 4491) have a mechanism to request specific vendor options and Kea is able to honor those (sub-option 1). Unfortunately, for many other vendors, such as Genexis (25167, discussed above), Kea does not have such a mechanism, so it cannot send any sub-options on its own. To solve this issue, we devised the concept of persistent options. Kea can be told to always send options, even if the client did not request them. This can be achieved by adding "always-send": true to the option data entry. Note that in this particular case an option is defined in vendor space 25167. With always-send enabled, the option is sent every time there is a need to deal with vendor space 25167.

This is also how kea-dhcp4 can be configured to send multiple vendor options from different vendors, along with each of their specific vendor IDs. 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 suboptions that will be included in the vivso-suboptions option (code 125).

"Dhcp4": {
    "option-data": [
        # Typically DHCPv4 clients will send a Parameter Request List option (code 55) for
        # vivso-suboptions (code 125), and that is enough for Kea to understand that it needs to
        # send the option. These options still need to be defined in the configuration, one per
        # each vendor, but they don't need "always-send" enabled in that case. For misbehaving
        # clients that do not explicitly request it, one may alternatively set "always-send"
        # to true for them as well. This is referring to the following two entries in option-data.
        {
            "name": "vivso-suboptions",
            "space": "dhcp4",
            "data": "2234"
        },
        {
            "name": "vivso-suboptions",
            "space": "dhcp4",
            "data": "3561"
        },
        {
            "always-send": true,
            "data": "tagged",
            "name": "tag",
            "space": "vendor-2234"
        },
        {
            "always-send": true,
            "data": "https://example.com:1234/path",
            "name": "url",
            "space": "vendor-3561"
        }
    ],
    "option-def": [
        {
            "code": 22,
            "name": "tag",
            "space": "vendor-2234",
            "type": "string"
        },
        {
            "code": 11,
            "name": "url",
            "space": "vendor-3561",
            "type": "string"
        }
    ]
}

Another possibility is to redefine the option; see DHCPv4 Private Options.

Kea comes with several example configuration files. Some of them showcase how to configure options 60 and 43. See doc/examples/kea4/vendor-specific.json and doc/examples/kea4/vivso.json in the Kea sources.

NOTE:

Nested DHCPv4 Options (Custom Option Spaces)

It is sometimes useful to define a completely new option space, such as when a user creates a new option in the standard option space (dhcp4) and wants this option to convey sub-options. Since they are in a separate space, sub-option codes have a separate numbering scheme and may overlap with the codes of standard options.

Note that the creation of a new option space is not required when defining sub-options for a standard option, because one is created by default if the standard option is meant to convey any sub-options (see DHCPv4 Vendor-Specific Options).

If we want a DHCPv4 option called container with code 222, that conveys two sub-options with codes 1 and 2, we first need to define the new sub-options:

"Dhcp4": {
    "option-def": [
        {
            "name": "subopt1",
            "code": 1,
            "space": "isc",
            "type": "ipv4-address",
            "record-types": "",
            "array": false,
            "encapsulate": ""
        },
        {
            "name": "subopt2",
            "code": 2,
            "space": "isc",
            "type": "string",
            "record-types": "",
            "array": false,
            "encapsulate": ""
        }
    ],
    ...
}

Note that we have defined the options to belong to a new option space (in this case, "isc").

The next step is to define a regular DHCPv4 option with the desired code and specify that it should include options from the new option space:

"Dhcp4": {
    "option-def": [
        {
            "name": "container",
            "code": 222,
            "space": "dhcp4",
            "type": "empty",
            "array": false,
            "record-types": "",
            "encapsulate": "isc"
        },
        ...
    ],
    ...
}

The name of the option space in which the sub-options are defined is set in the encapsulate field. The type field is set to "empty", to indicate that this option does not carry any data other than sub-options.

Finally, we can set values for the new options:

{
  "Dhcp4": {
    "option-data": [
        {
            "name": "subopt1",
            "code": 1,
            "space": "isc",
            "data": "192.0.2.3"
        },
        {
            "name": "subopt2",
            "code": 2,
            "space": "isc",
            "data": "Hello world"
        },
        {
            "name": "container",
            "code": 222,
            "space": "dhcp4"
        }
    ]
  }
}

It is possible to create an option which carries some data in addition to the sub-options defined in the encapsulated option space. For example, if the container option from the previous example were required to carry a uint16 value as well as the sub-options, the type value would have to be set to "uint16" in the option definition. (Such an option would then have the following data structure: DHCP header, uint16 value, sub-options.) The value specified with the data parameter — which should be a valid integer enclosed in quotes, e.g. "123" — would then be assigned to the uint16 field in the container option.

Unspecified Parameters for DHCPv4 Option Configuration

In many cases it is not required to specify all parameters for an option configuration, and the default values can be used. However, it is important to understand the implications of not specifying some of them, as it may result in configuration errors. The list below explains the behavior of the server when a particular parameter is not explicitly specified:

Support for Long Options

The kea-dhcp4 server partially supports long options (RFC 3396). Since Kea 2.1.6, the server accepts configuring long options and sub-options (longer than 255 bytes). The options and sub-options are stored internally in their unwrapped form and they can be processed as usual using the parser language. On send, the server splits long options and sub-options into multiple options and sub-options, using the respective option code.

{
"option-def": [
    {
        "array": false,
        "code": 240,
        "encapsulate": "",
        "name": "my-option",
        "space": "dhcp4",
        "type": "string"
    }
],
"subnet4": [
    {
        "id": 1,
        "subnet": "192.0.2.0/24",
        "reservations": [
            {
                "hw-address": "aa:bb:cc:dd:ee:ff",
                "option-data": [
                    {
                        "always-send": false,
                        "code": 240,
                        "name": "my-option",
                        "csv-format": true,
                        "data": "data \
                                 -00010203040506070809-00010203040506070809-00010203040506070809-00010203040506070809 \
                                 -00010203040506070809-00010203040506070809-00010203040506070809-00010203040506070809 \
                                 -00010203040506070809-00010203040506070809-00010203040506070809-00010203040506070809 \
                                 -data",
                        "space": "dhcp4"
                    }
                ]
            }
        ]
    }
],
...
}

NOTE:

This example illustrates configuring a custom long option (exceeding 255 octets) in a reservation. When sending a response, the server splits this option into two options, each with the code 240.

NOTE:

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 also supported for sub-options if each sub-option data chunk also contains the sub-option code and sub-option length.

Support for IPv6-Only Preferred Option

The v6-only-preferred (code 108) option is handled in a specific way described in RFC 8925 by kea-dhcp4 when it is configured in a subnet or a shared network: when the client requests the option (i.e. puts the 108 code in the DHCP parameter request list option) and the subnet or shared network is selected the 0.0.0.0 address is offered and the option returned in the response.

Stateless Configuration of DHCPv4 Clients

The DHCPv4 server supports stateless client configuration, whereby the client has an IP address configured (e.g. using manual configuration) and only contacts the server to obtain other configuration parameters, such as addresses of DNS servers. To obtain the stateless configuration parameters, the client sends the DHCPINFORM message to the server with the ciaddr set to the address that the client is currently using. The server unicasts the DHCPACK message to the client that includes the stateless configuration ("yiaddr" not set).

The server responds to the DHCPINFORM when the client is associated with a subnet defined in the server's configuration. An example subnet configuration looks like this:

"Dhcp4": {
    "subnet4": [
        {
            "id": 1,
            "subnet": "192.0.2.0/24",
            "option-data": [
            {
                "name": "domain-name-servers",
                "code": 6,
                "data": "192.0.2.200,192.0.2.201",
                "csv-format": true,
                "space": "dhcp4"
            }
            ]
        }
    ]
}

This subnet specifies the single option which will be included in the DHCPACK message to the client in response to DHCPINFORM. The subnet definition does not require the address pool configuration if it will be used solely for stateless configuration.

This server will associate the subnet with the client if one of the following conditions is met:

Client Classification in DHCPv4

The DHCPv4 server includes support for client classification. For a deeper discussion of the classification process, see Client Classification.

In certain cases it is useful to configure the server to differentiate between DHCP client types and treat them accordingly. Client classification can be used to modify the behavior of almost any part of DHCP message processing. Kea currently offers client classification via private options and option 43 deferred unpacking; subnet selection; pool selection; assignment of different options; and, for cable modems, specific options for use with the TFTP server address and the boot file field.

Kea can be instructed to limit access to given subnets based on class information. This is particularly useful for cases where two types of devices share the same link and are expected to be served from two different subnets. The primary use case for such a scenario is cable networks, where there are two classes of devices: the cable modem itself, which should be handed a lease from subnet A; and all other devices behind the modem, which should get leases from subnet B. That segregation is essential to prevent overly curious end-users from playing with their cable modems. For details on how to set up class restrictions on subnets, see Configuring Subnets With Class Information.

When subnets belong to a shared network, the classification applies to subnet selection but not to pools; that is, a pool in a subnet limited to a particular class can still be used by clients which do not belong to the class, if the pool they are expected to use is exhausted. The limit on access based on class information is also available at the pool level within a subnet: see Configuring Pools With Class Information. This is useful when segregating clients belonging to the same subnet into different address ranges.

In a similar way, a pool can be constrained to serve only known clients, i.e. clients which have a reservation, using the built-in KNOWN or UNKNOWN classes. Addresses can be assigned to registered clients without giving a different address per reservation: for instance, when there are not enough available addresses. The determination whether there is a reservation for a given client is made after a subnet is selected, so it is not possible to use KNOWN/UNKNOWN classes to select a shared network or a subnet.

The process of classification is conducted in five steps. The first step is to assess an incoming packet and assign it to zero or more classes. The second step is to choose a subnet, possibly based on the class information. When the incoming packet is in the special class DROP, it is dropped and a debug message logged. The next step is to evaluate class expressions depending on the built-in KNOWN/UNKNOWN classes after host reservation lookup, using them for pool selection and assigning classes from host reservations. The list of required classes is then built and each class of the list has its expression evaluated; when it returns true, the packet is added as a member of the class. The last step is to assign options, again possibly based on the class information. More complete and detailed information is available in Client Classification.

There are two main methods of classification. The first is automatic and relies on examining the values in the vendor class options or the existence of a host reservation. Information from these options is extracted, and a class name is constructed from it and added to the class list for the packet. The second method specifies an expression that is evaluated for each packet. If the result is true, the packet is a member of the class.

NOTE:

NOTE:

Setting Fixed Fields in Classification

It is possible to specify that clients belonging to a particular class should receive packets with specific values in certain fixed fields. In particular, three fixed fields are supported: next-server (conveys an IPv4 address, which is set in the siaddr field), server-hostname (conveys a server hostname, can be up to 64 bytes long, and is sent in the sname field) and boot-file-name (conveys the configuration file, can be up to 128 bytes long, and is sent using the file field).

Obviously, there are many ways to assign clients to specific classes, but for PXE clients the client architecture type option (code 93) seems to be particularly suited to make the distinction. The following example checks whether the client identifies itself as a PXE device with architecture EFI x86-64, and sets several fields if it does. See Section 2.1 of RFC 4578) or the client documentation for specific values.

"Dhcp4": {
    "client-classes": [
        {
            "name": "ipxe_efi_x64",
            "test": "option[93].hex == 0x0009",
            "next-server": "192.0.2.254",
            "server-hostname": "hal9000",
            "boot-file-name": "/dev/null"
        },
        ...
    ],
    ...
}

If an incoming packet is matched to multiple classes, then the value used for each field will come from the first class that specifies the field, in the order the classes are assigned to the packet.

NOTE:

Using Vendor Class Information in Classification

The server checks whether an incoming packet includes the vendor class identifier option (60). If it does, the content of that option is prepended with VENDOR_CLASS_, and it is interpreted as a class. For example, modern cable modems send this option with value docsis3.0, so the packet belongs to the class VENDOR_CLASS_docsis3.0.

NOTE:

This example shows a configuration using an automatically generated VENDOR_CLASS_ class. The administrator of the network has decided that addresses from the range 192.0.2.10 to 192.0.2.20 are going to be managed by the Dhcp4 server and only clients belonging to the DOCSIS 3.0 client class are allowed to use that pool.

"Dhcp4": {
    "subnet4": [
        {
            "id": 1,
            "subnet": "192.0.2.0/24",
            "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
            "client-classes": [ "VENDOR_CLASS_docsis3.0" ]
        }
    ],
    ...
}

Defining and Using Custom Classes

The following example shows how to configure a class using an expression and a subnet using that class. This configuration defines the class named Client_foo. It is comprised of all clients whose client IDs (option 61) start with the string foo. Members of this class will be given addresses from 192.0.2.10 to 192.0.2.20 and the addresses of their DNS servers set to 192.0.2.1 and 192.0.2.2.

"Dhcp4": {
    "client-classes": [
        {
            "name": "Client_foo",
            "test": "substring(option[61].hex,0,3) == 'foo'",
            "option-data": [
                {
                    "name": "domain-name-servers",
                    "code": 6,
                    "space": "dhcp4",
                    "csv-format": true,
                    "data": "192.0.2.1, 192.0.2.2"
                }
            ]
        },
        ...
    ],
    "subnet4": [
        {
            "id": 1,
            "subnet": "192.0.2.0/24",
            "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
            "client-classes": [ "Client_foo" ]
        },
        ...
    ],
    ...
}

Additional Classification

In some cases it is useful to limit the scope of a class to a pool, subnet, or shared network. There are two parameters which are used to limit the scope of the class by instructing the server to evaluate test expressions when required.

The evaluate-additional-classes, which takes a list of class names and is valid in pool, subnet, and shared network scope. Classes in these lists are marked as additional and evaluated after selection of this specific pool/subnet/shared network and before output-option processing.

The second one is the per-class only-in-additional-list flag, which is false by default. When it is set to true, the test expression of the class is not evaluated at the reception of the incoming packet but later, and only if the class is present in an evaluate-additional-classes list.

In this example, a class is assigned to the incoming packet when the specified subnet is used:

"Dhcp4": {
    "client-classes": [
       {
           "name": "Client_foo",
           "test": "member('ALL')",
           "only-in-additional-list": true
       },
       ...
    ],
    "subnet4": [
        {
            "subnet": "192.0.2.0/24",
            "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
            "evaluate-additional-classes": [ "Client_foo" ],
            ...
        },
        ...
    ],
    ...
}

Additional evaluation can be used to express complex dependencies like subnet membership. It can also be used to reverse the precedence; if option-data is set in a subnet, it takes precedence over option-data in a class. If option-data is moved to a required class and required in the subnet, a class evaluated earlier may take precedence.

Additional evaluation is also available at shared network and pool levels. The order in which additional classes are considered is: pool, subnet, and shared network, i.e. in the same order from the way in which option-data is processed.

Since Kea version 2.7.4 additional classes configured without a test expression are unconditionally added, i.e. they are considered to always be evaluated to true.

NOTE:

NOTE:

NOTE:

"Dhcp4": {
    "option-data": [
       {
           "name": "vivco-suboptions",
           "always-send": true,
           "data": "1234, 03666f6f"
       },
       {
           "name": "vivco-suboptions",
           "always-send": true,
           "data": "5678, 03626172"
       },
       ...
     ],
     ...
 }

The first option-data entry does not hide the second one, because the vendor identifiers (1234 and 5678) are different: the responses will carry two instances of the vivco-suboptions option, each for a different vendor.

DDNS for DHCPv4

As mentioned earlier, kea-dhcp4 can be configured to generate requests to the DHCP-DDNS server, kea-dhcp-ddns, (referred to herein as "D2") to update DNS entries. These requests are known as NameChangeRequests or NCRs. Each NCR contains the following information:

DDNS-related parameters are split into two groups:

NOTE:

NOTE:

The default configuration and values would appear as follows:

"Dhcp4": {
     "dhcp-ddns": {
         // Connectivity parameters
         "enable-updates": false,
         "server-ip": "127.0.0.1",
         "server-port":53001,
         "sender-ip":"",
         "sender-port":0,
         "max-queue-size":1024,
         "ncr-protocol":"UDP",
         "ncr-format":"JSON"
     },
     // Behavioral parameters (global)
     "ddns-send-updates": true,
     "ddns-override-no-update": false,
     "ddns-override-client-update": false,
     "ddns-replace-client-name": "never",
     "ddns-generated-prefix": "myhost",
     "ddns-qualifying-suffix": "",
     "ddns-update-on-renew": false,
     "ddns-conflict-resolution-mode": "check-with-dhcid",
     "hostname-char-set": "",
     "hostname-char-replacement": "",
     ...
}

There are two parameters which determine whether kea-dhcp4 can generate DDNS requests to D2: the existing dhcp-ddns:enable-updates parameter, which now only controls whether kea-dhcp4 connects to D2; and the new behavioral parameter, ddns-send-updates, which determines whether DDNS updates are enabled at a given level (i.e. global, shared-network, or subnet). The following table shows how the two parameters function together:

Enabling and disabling DDNS updates

Kea 1.9.1 added two new parameters; the first is ddns-update-on-renew. Normally, when leases are renewed, the server only updates DNS if the DNS information for the lease (e.g. FQDN, DNS update direction flags) has changed. Setting ddns-update-on-renew to true instructs the server to always update the DNS information when a lease is renewed, even if its DNS information has not changed. This allows Kea to "self-heal" if it was previously unable to add DNS entries or they were somehow lost by the DNS server.

NOTE:

The second parameter added in Kea 1.9.1 is ddns-use-conflict-resolution. This boolean parameter was passed through to D2 and enabled or disabled conflict resolution as described in RFC 4703. Beginning with Kea 2.5.0, it is deprecated and replaced by ddns-conflict-resolution-mode, which offers four modes of conflict resolution-related behavior:

NOTE:

NOTE:

The DNS entries Kea creates contain a value for TTL (time to live). By default, the kea-dhcp4 server calculates that value based on RFC 4702, Section 5, which suggests that the TTL value be 1/3 of the lease's lifetime, with a minimum value of 10 minutes. There are four optional parameters which may be used to influence the TTL calculation:

NOTE:

DHCP-DDNS Server Connectivity

For NCRs to reach the D2 server, kea-dhcp4 must be able to communicate with it. kea-dhcp4 uses the following configuration parameters to control this communication:

By default, kea-dhcp-ddns is assumed to be running on the same machine as kea-dhcp4, and all of the default values mentioned above should be sufficient. If, however, D2 has been configured to listen on a different address or port, these values must be altered accordingly. For example, if D2 has been configured to listen on 192.168.1.10 port 900, the following configuration is required:

"Dhcp4": {
    "dhcp-ddns": {
        "server-ip": "192.168.1.10",
        "server-port": 900,
        ...
    },
    ...
}

When Does the kea-dhcp4 Server Generate a DDNS Request?

The kea-dhcp4 server follows the behavior prescribed for DHCP servers in RFC 4702. It is important to keep in mind that kea-dhcp4 makes the initial decision of when and what to update and forwards that information to D2 in the form of NCRs. Carrying out the actual DNS updates and dealing with such things as conflict resolution are within the purview of D2 itself (see The DHCP-DDNS Server). This section describes when kea-dhcp4 generates NCRs and the configuration parameters that can be used to influence this decision. It assumes that both the connectivity parameter enable-updates and the behavioral parameter ddns-send-updates, are true.

In general, kea-dhcp4 generates DDNS update requests when:

In the second case, lease renewal, two DDNS requests are issued: one request to remove entries for the previous FQDN, and a second request to add entries for the new FQDN. In the third case, a lease release - a single DDNS request - to remove its entries is made.

As for the first case, the decisions involved when granting a new lease are more complex. When a new lease is granted, kea-dhcp4 generates a DDNS update request if the DHCPREQUEST contains either the FQDN option (code 81) or the Host Name option (code 12). If both are present, the server uses the FQDN option. By default, kea-dhcp4 respects the FQDN N and S flags specified by the client as shown in the following table:

Default FQDN flag behavior

The first row in the table above represents "client delegation." Here the DHCP client states that it intends to do the forward DNS updates and the server should do the reverse updates. By default, kea-dhcp4 honors the client's wishes and generates a DDNS request to the D2 server to update only reverse DNS data. The parameter ddns-override-client-update can be used to instruct the server to override client delegation requests. When this parameter is true, kea-dhcp4 disregards requests for client delegation and generates a DDNS request to update both forward and reverse DNS data. In this case, the N-S-O flags in the server's response to the client will be 0-1-1 respectively.

(Note that the flag combination N=1, S=1 is prohibited according to RFC 4702. If such a combination is received from the client, the packet is dropped by kea-dhcp4.)

To override client delegation, set the following values in the configuration file:

"Dhcp4": {
    "ddns-override-client-update": true,
    ...
}

The third row in the table above describes the case in which the client requests that no DNS updates be done. The parameter ddns-override-no-update can be used to instruct the server to disregard the client's wishes. When this parameter is true, kea-dhcp4 generates DDNS update requests to kea-dhcp-ddns even if the client requests that no updates be done. The N-S-O flags in the server's response to the client will be 0-1-1.

To override client delegation, issue the following commands:

"Dhcp4": {
    "ddns-override-no-update": true,
    ...
}

The kea-dhcp4 server always generates DDNS update requests if the client request only contains the Host Name option. In addition, it includes an FQDN option in the response to the client with the FQDN N-S-O flags set to 0-1-0, respectively. The domain name portion of the FQDN option is the name submitted to D2 in the DDNS update request.

kea-dhcp4 Name Generation for DDNS Update Requests

Each NameChangeRequest must of course include the fully qualified domain name whose DNS entries are to be affected. kea-dhcp4 can be configured to supply a portion or all of that name, based on what it receives from the client in the DHCPREQUEST.

The default rules for constructing the FQDN that will be used for DNS entries are:

These rules can be amended by setting the ddns-replace-client-name parameter, which provides the following modes of behavior:

NOTE:

For example, to instruct kea-dhcp4 to always generate the FQDN for a client, set the parameter ddns-replace-client-name to always as follows:

"Dhcp4": {
    "ddns-replace-client-name": "always",
    ...
}

The prefix used in the generation of an FQDN is specified by the ddns-generated-prefix parameter. The default value is "myhost". To alter its value, simply set it to the desired string:

"Dhcp4": {
    "ddns-generated-prefix": "another.host",
    ...
}

The suffix used when generating an FQDN, or when qualifying a partial name, is specified by the ddns-qualifying-suffix parameter. It is strongly recommended that the user supply a value for the qualifying suffix when DDNS updates are enabled. For obvious reasons, we cannot supply a meaningful default.

"Dhcp4": {
    "ddns-qualifying-suffix": "foo.example.org",
    ...
}

When qualifying a partial name, kea-dhcp4 constructs the name in the format:

[candidate-name].[ddns-qualifying-suffix].

where candidate-name is the partial name supplied in the DHCPREQUEST. For example, if the FQDN domain name value is "some-computer" and the ddns-qualifying-suffix is "example.com", the generated FQDN is:

some-computer.example.com.

When generating the entire name, kea-dhcp4 constructs the name in the format:

[ddns-generated-prefix]-[address-text].[ddns-qualifying-suffix].

where address-text is simply the lease IP address converted to a hyphenated string. For example, if the lease address is 172.16.1.10, the qualifying suffix is "example.com", and the default value is used for ddns-generated-prefix, the generated FQDN is:

myhost-172-16-1-10.example.com.

NOTE:

Sanitizing Client Host Name and FQDN Names

Some DHCP clients may provide values in the Host Name option (option code 12) or FQDN option (option code 81) that contain undesirable characters. It is possible to configure kea-dhcp4 to sanitize these values. The most typical use case is ensuring that only characters that are permitted by RFC 1035 be included: A-Z, a-z, 0-9, and "-". This may be accomplished with the following two parameters:

The following configuration replaces anything other than a letter, digit, dot, or hyphen with the letter "x":

"Dhcp4": {
    "hostname-char-set": "[^A-Za-z0-9.-]",
    "hostname-char-replacement": "x",
    ...
}

Thus, a client-supplied value of "myhost-$[123.org" would become "myhost-xx123.org". Sanitizing is performed only on the portion of the name supplied by the client, and it is performed before applying a qualifying suffix (if one is defined and needed).

NOTE:

NOTE:

Next Server (siaddr)

In some cases, clients want to obtain configuration from a TFTP server. Although there is a dedicated option for it, some devices may use the siaddr field in the DHCPv4 packet for that purpose. That specific field can be configured using the next-server directive. It is possible to define it in the global scope or for a given subnet only. If both are defined, the subnet value takes precedence. The value in the subnet can be set to "0.0.0.0", which means that next-server should not be sent. It can also be set to an empty string, which is equivalent to it not being defined at all; that is, it uses the global value.

The server-hostname (which conveys a server hostname, can be up to 64 bytes long, and is in the sname field) and boot-file-name (which conveys the configuration file, can be up to 128 bytes long, and is sent using the file field) directives are handled the same way as next-server.

"Dhcp4": {
    "next-server": "192.0.2.123",
    "boot-file-name": "/dev/null",
    "subnet4": [
        {
            "next-server": "192.0.2.234",
            "server-hostname": "some-name.example.org",
            "boot-file-name": "bootfile.efi",
            ...
        }
    ],
    ...
}

Echoing Client-ID (RFC 6842)

The original DHCPv4 specification (RFC 2131) states that the DHCPv4 server must not send back client-id options when responding to clients. However, in some cases that results in confused clients that do not have a MAC address or client-id; see RFC 6842 for details. That behavior changed with the publication of RFC 6842, which updated RFC 2131. That update states that the server must send the client-id if the client sent it, and that is Kea's default behavior. However, in some cases older devices that do not support RFC 6842 may refuse to accept responses that include the client-id option. To enable backward compatibility, an optional configuration parameter has been introduced. To configure it, use the following configuration statement:

"Dhcp4": {
    "echo-client-id": false,
    ...
}

Using Client Identifier and Hardware Address

The DHCP server must be able to identify the client from which it receives the message and distinguish it from other clients. There are many reasons why this identification is required; the most important ones are:

DHCPv4 uses two distinct identifiers which are placed by the client in the queries sent to the server and copied by the server to its responses to the client: chaddr and client-identifier. The former was introduced as a part of the BOOTP specification and it is also used by DHCP to carry the hardware address of the interface used to send the query to the server (MAC address for the Ethernet). The latter is carried in the client-identifier option, introduced in RFC 2132.

RFC 2131 indicates that the server may use both of these identifiers to identify the client but the client identifier, if present, takes precedence over chaddr. One of the reasons for this is that the client identifier is independent from the hardware used by the client to communicate with the server. For example, if the client obtained the lease using one network card and then the network card is moved to another host, the server will wrongly identify this host as the one which obtained the lease. Moreover, RFC 4361 gives the recommendation to use a DUID (see RFC 8415, the DHCPv6 specification) carried as a client identifier when dual-stack networks are in use to provide consistent identification information for the client, regardless of the type of protocol it is using. Kea adheres to these specifications, and the client identifier by default takes precedence over the value carried in the chaddr field when the server searches, creates, updates, or removes the client's lease.

When the server receives a DHCPDISCOVER or DHCPREQUEST message from the client, it tries to find out if the client already has a lease in the database; if it does, the server hands out that lease rather than allocates a new one. Each lease in the lease database is associated with the client identifier and/or chaddr. The server first uses the client identifier (if present) to search for the lease; if one is found, the server treats this lease as belonging to the client, even if the current chaddr and the chaddr associated with the lease do not match. This facilitates the scenario when the network card on the client system has been replaced and thus the new MAC address appears in the messages sent by the DHCP client. If the server fails to find the lease using the client identifier, it performs another lookup using the chaddr. If this lookup returns no result, the client is considered to not have a lease and a new lease is created.

A common problem reported by network operators is that poor client implementations do not use stable client identifiers, instead generating a new client identifier each time the client connects to the network. Another well-known case is when the client changes its client identifier during the multi-stage boot process (PXE). In such cases, the MAC address of the client's interface remains stable, and using the chaddr field to identify the client guarantees that the particular system is considered to be the same client, even though its client identifier changes.

To address this problem, Kea includes a configuration option which enables client identification using chaddr only. This instructs the server to ignore the client identifier during lease lookups and allocations for a particular subnet. Consider the following simplified server configuration:

{
  "Dhcp4": {
    "match-client-id": true,
    "subnet4": [
    {
        "id": 1,
        "subnet": "192.0.10.0/24",
        "pools": [ { "pool": "192.0.2.23-192.0.2.87" } ],
        "match-client-id": false
    },
    {
        "id": 1,
        "subnet": "10.0.0.0/8",
        "pools": [ { "pool": "10.0.0.23-10.0.2.99" } ]
    }
    ]
  }
}

The match-client-id parameter is a boolean value which controls this behavior. The default value of true indicates that the server will use the client identifier for lease lookups and chaddr if the first lookup returns no results. false means that the server will only use the chaddr to search for the client's lease. Whether the DHCID for DNS updates is generated from the client identifier or chaddr is controlled through the same parameter.

The match-client-id parameter may appear both in the global configuration scope and/or under any subnet declaration. In the example shown above, the effective value of the match-client-id will be false for the subnet 192.0.10.0/24, because the subnet-specific setting of the parameter overrides the global value of the parameter. The effective value of the match-client-id for the subnet 10.0.0.0/8 will be set to true, because the subnet declaration lacks this parameter and the global setting is by default used for this subnet. In fact, the global entry for this parameter could be omitted in this case, because true is the default value.

It is important to understand what happens when the client obtains its lease for one setting of the match-client-id and then renews it when the setting has been changed. First, consider the case when the client obtains the lease and the match-client-id is set to true. The server stores the lease information, including the client identifier (if supplied) and chaddr, in the lease database. When the setting is changed and the client renews the lease, the server will determine that it should use the chaddr to search for the existing lease. If the client has not changed its MAC address, the server should successfully find the existing lease. The client identifier associated with the returned lease will be ignored and the client will be allowed to use this lease. When the lease is renewed only the chaddr will be recorded for this lease, according to the new server setting.

In the second case, the client has the lease with only a chaddr value recorded. When the match-client-id setting is changed to true, the server will first try to use the client identifier to find the existing client's lease. This will return no results because the client identifier was not recorded for this lease. The server will then use the chaddr and the lease will be found. If the lease appears to have no client identifier recorded, the server will assume that this lease belongs to the client and that it was created with the previous setting of the match-client-id. However, if the lease contains a client identifier which is different from the client identifier used by the client, the lease will be assumed to belong to another client and a new lease will be allocated.

For a more visual representation of how Kea recognizes the same client, please refer to How Kea Recognizes the Same Client In Different DHCP Messages.

Authoritative DHCPv4 Server Behavior

The original DHCPv4 specification (RFC 2131) states that if a client requests an address in the INIT-REBOOT state of which the server has no knowledge, the server must remain silent, except if the server knows that the client has requested an IP address from the wrong network. By default, Kea follows the behavior of the ISC dhcpd daemon instead of the specification and also remains silent if the client requests an IP address from the wrong network, because configuration information about a given network segment is not known to be correct. Kea only rejects a client's DHCPREQUEST with a DHCPNAK message if it already has a lease for the client with a different IP address. Administrators can override this behavior through the boolean authoritative (false by default) setting.

In authoritative mode, authoritative set to true, Kea always rejects INIT-REBOOT requests from unknown clients with DHCPNAK messages. The authoritative setting can be specified in global, shared-network, and subnet configuration scope and is automatically inherited from the parent scope, if not specified. All subnets in a shared-network must have the same authoritative setting.

DHCPv4-over-DHCPv6: DHCPv4 Side

The support of DHCPv4-over-DHCPv6 transport is described in RFC 7341 and is implemented using cooperating DHCPv4 and DHCPv6 servers. This section is about the configuration of the DHCPv4 side (the DHCPv6 side is described in DHCPv4-over-DHCPv6: DHCPv6 Side).

NOTE:

The dhcp4o6-port global parameter specifies the first of the two consecutive ports of the UDP sockets used for the communication between the DHCPv6 and DHCPv4 servers. The DHCPv4 server is bound to ::1 on port + 1 and connected to ::1 on port.

With DHCPv4-over-DHCPv6, the DHCPv4 server does not have access to several of the identifiers it would normally use to select a subnet. To address this issue, three new configuration entries are available; the presence of any of these allows the subnet to be used with DHCPv4-over-DHCPv6. These entries are:

ISC tested the following configuration:

{
# DHCPv4 conf
"Dhcp4": {
    "interfaces-config": {
        "interfaces": [ "eno33554984" ]
    },
    "lease-database": {
        "type": "memfile",
        "name": "leases4"
    },
    "valid-lifetime": 4000,
    "subnet4": [
    {
        "id": 1,
        "subnet": "10.10.10.0/24",
        "4o6-interface": "eno33554984",
        "4o6-subnet": "2001:db8:1:1::/64",
        "pools": [ { "pool": "10.10.10.100 - 10.10.10.199" } ]
    }
    ],
    "dhcp4o6-port": 786,
    "loggers": [
    {
        "name": "kea-dhcp4",
        "output-options": [
        {
            "output": "kea-dhcp4.log"
        }
        ],
        "severity": "DEBUG",
        "debuglevel": 0
    }
    ]
}
}

Sanity Checks in DHCPv4

An important aspect of a well-running DHCP system is an assurance that the data remains consistent; however, in some cases it may be convenient to tolerate certain inconsistent data. For example, a network administrator who temporarily removes a subnet from a configuration would not want all the leases associated with it to disappear from the lease database. Kea has a mechanism to implement sanity checks for situations like this.

Kea supports a configuration scope called sanity-checks. A parameter, called lease-checks, governs the verification carried out when a new lease is loaded from a lease file. This mechanism permits Kea to attempt to correct inconsistent data.

Every subnet has a subnet-id value; this is how Kea internally identifies subnets. Each lease has a subnet-id parameter as well, which identifies the subnet it belongs to. However, if the configuration has changed, it is possible that a lease could exist with a subnet-id but without any subnet that matches it. Also, it is possible that the subnet's configuration has changed and the subnet-id now belongs to a subnet that does not match the lease.

Kea's corrective algorithm first checks to see if there is a subnet with the subnet-id specified by the lease. If there is, it verifies whether the lease belongs to that subnet. If not, depending on the lease-checks setting, the lease is discarded, a warning is displayed, or a new subnet is selected for the lease that matches it topologically.

There are five levels which are supported:

This feature is currently implemented for the memfile backend. The sanity check applies to the lease database in memory, not to the lease file, i.e. inconsistent leases stay in the lease file.

An example configuration that sets this parameter looks as follows:

"Dhcp4": {
    "sanity-checks": {
        "lease-checks": "fix-del"
    },
    ...
}

Storing Extended Lease Information

To support such features as DHCP Leasequery (RFC 4388) and stash agent options (Stash Agent Options), additional information must be stored with each lease. Because the amount of information for each lease has ramifications in terms of performance and system resource consumption, storage of this additional information is configurable through the store-extended-info parameter. It defaults to false and may be set at the global, shared-network, and subnet levels.

"Dhcp4": {
    "store-extended-info": true,
    ...
}

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". 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 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:

{ "ISC": { "relay-agent-info": { "sub-options": "0x0104AABBCCDD" } } }

Or with remote and relay sub-options:

{
    "ISC": {
        "relay-agent-info": {
            "sub-options": "0x02030102030C03AABBCC",
            "remote-id": "03010203",
            "relay-id": "AABBCC"
        }
    }
}

NOTE:

Extended lease information is also subject to configurable sanity checking. The parameter in the sanity-checks scope is named extended-info-checks and supports these levels:

NOTE:

Stash Agent Options

This global parameter was added in version 2.5.8 to mirror a feature that was previously available in ISC DHCP. When the stash-agent-options parameter is true, the server records the relay agent information options sent during the client's initial DHCPREQUEST message (when the client was in the SELECTING state) and behaves as if those options are included in all subsequent DHCPREQUEST messages sent in the RENEWING state. This works around a problem with relay agent information options, which do not usually appear in DHCPREQUEST messages sent by the client in the RENEWING state; such messages are unicast directly to the server and are not sent through a relay agent.

The default is false.

Multi-Threading Settings

The Kea server can be configured to process packets in parallel using multiple threads. These settings can be found under the multi-threading structure and are represented by:

An example configuration that sets these parameters looks as follows:

"Dhcp4": {
    "multi-threading": {
       "enable-multi-threading": true,
       "thread-pool-size": 4,
       "packet-queue-size": 16
    },
    ...
}

Multi-Threading Settings With Different Database Backends

The Kea DHCPv4 server is benchmarked by ISC to determine which settings give the best performance. Although this section describes our results, they are merely recommendations and are very dependent on the particular hardware used for benchmarking. We strongly advise that administrators run their own performance benchmarks.

A full report of performance results for the latest stable Kea version can be found here. This includes hardware and benchmark scenario descriptions, as well as current results.

After enabling multi-threading, the number of threads is set by the thread-pool-size parameter. Results from our experiments show that the best settings for kea-dhcp4 are:

Another very important parameter is packet-queue-size; in our benchmarks we used it as a multiplier of thread-pool-size. The actual setting strongly depends on thread-pool-size.

We saw the best results in our benchmarks with the following settings:

IPv6-Only Preferred Networks

RFC 8925, recently published by the IETF, specifies a DHCPv4 option to indicate that a host supports an IPv6-only mode and is willing to forgo obtaining an IPv4 address if the network provides IPv6 connectivity. The general idea is that a network administrator can enable this option to signal to compatible dual-stack devices that IPv6 connectivity is available and they can shut down their IPv4 stack. The new option v6-only-preferred content is a 32-bit unsigned integer and specifies for how long the device should disable its stack. The value is expressed in seconds.

The RFC mentions the V6ONLY_WAIT timer. This is implemented in Kea by setting the value of the v6-only-preferred option. This follows the usual practice of setting options; the option value can be specified on the pool, subnet, shared network, or global levels, or even via host reservations.

There is no special processing involved; it follows the standard Kea option processing regime. The option is not sent back unless the client explicitly requests it. For example, to enable the option for the whole subnet, the following configuration can be used:

{
"subnet4": [
    {
        "id": 1,
        "pools": [ { "pool":  "192.0.2.1 - 192.0.2.200" } ],
        "subnet": "192.0.2.0/24",
        "option-data": [
            {
                // This will make the v6-only capable devices to disable their
                // v4 stack for half an hour and then try again
                "name": "v6-only-preferred",
                "data": "1800"
            }
        ]
    }
],
...
}

Lease Caching

Clients that attempt multiple renewals in a short period can cause the server to update and write to the database frequently, resulting in a performance impact on the server. The cache parameters instruct the DHCP server to avoid updating leases too frequently, thus avoiding this behavior. Instead, the server assigns the same lease (i.e. reuses it) with no modifications except for CLTT (Client Last Transmission Time), which does not require disk operations.

The two parameters are the cache-threshold double and the cache-max-age integer. These parameters can be configured at the global, shared-network, and subnet levels. The subnet level has precedence over the shared-network level, while the global level is used as a last resort. For example:

{
"subnet4": [
    {
        "pools": [ { "pool":  "192.0.2.1 - 192.0.2.200" } ],
        "subnet": "192.0.2.0/24",
        "cache-threshold": .25,
        "cache-max-age": 600,
        "valid-lifetime": 2000,
        ...
    }
],
...
}

NOTE:

When an already-assigned lease can fulfill a client query:

In our example, a lease with a valid lifetime of 2000 seconds can be reused if it was committed less than 500 seconds ago. With a lifetime of 3000 seconds, a maximum age of 600 seconds applies.

In outbound client responses (e.g. DHCPACK messages), the dhcp-lease-time option is set to the reusable valid lifetime, i.e. the expiration date does not change. Other options based on the valid lifetime e.g. dhcp-renewal-time and dhcp-rebinding-time, also depend on the reusable lifetime.

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 demands faster by deferring lease allocation and storage until it receives DHCPREQUESTs for them. The offer-lifetime parameter in kea-dhcp4 (when not zero) instructs the server to allocate and persist a lease when generating a DHCPOFFER. In addition:

An example subnet configuration is shown below:

{
"subnet4": [
    {
        "pools": [ { "pool":  "192.0.2.1 - 192.0.2.200" } ],
        "subnet": "192.0.2.0/24",
        "offer-lifetime": 60,
        "valid-lifetime": 2000,
        ...
    }
],
...
}

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 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.

DNR (Discovery of Network-designated Resolvers) Options for DHCPv4

The Discovery of Network-designated Resolvers, or DNR option, was introduced in RFC 9463 as a way to communicate location of DNS resolvers available over means other than the classic DNS over UDP over port 53. As of spring 2024, the supported technologies are DoT (DNS-over-TLS), DoH (DNS-over-HTTPS), and DoQ (DNS-over-QUIC), but the option was designed to be extensible to accommodate other protocols in the future.

The DHCPv4 option and its corresponding DHCPv6 options are almost exactly the same, with the exception of cardinality: only one DHCPv4 option is allowed, while multiple options are allowed for DHCPv6. To be able to convey multiple entries, the DHCPv4 DNR is an array that allows multiple DNS instances. Each instance is logically equal to one DHCPv6 option; the only difference is that it uses IPv4 rather than IPv6 addresses. DNR DHCPv4 options allow more than one DNR instance to be configured, and the DNR instances are separated with the "pipe" (0x7C) character.

For a detailed example of how to configure the DNR option, see DNR (Discovery of Network-designated Resolvers) Options for DHCPv6.

For each DNR instance, comma-delimited fields must be provided in the following order:

Example usage:

{
  "name": "v4-dnr",
  // 2 DNR Instances:
  // - Service priority 2, ADN, resolver IPv4 address and Service Parameters
  // - Service priority 3, ADN - this is ADN-only mode as per RFC 9463 3.1.6
  "data": "2, resolver.example., 10.0.5.6, alpn=dot\\,doq port=8530 | 3, fooexp.resolver.example."
}

NOTE:

Examples for DNR DHCPv4 options are provided in the Kea sources, in all-options.json in the doc/examples/kea4 directory.

Host Reservations in DHCPv4

There are many cases where it is useful to provide a configuration on a per-host basis. The most obvious one is to reserve a specific, static address for exclusive use by a given client (host); the returning client receives the same address from the server every time, and other clients generally do not receive that address. Host reservations are also convenient when a host has specific requirements, e.g. a printer that needs additional DHCP options. Yet another possible use case is to define unique names for hosts.

There may be cases when a new reservation has been made for a client for an address currently in use by another client. We call this situation a "conflict." These conflicts get resolved automatically over time, as described in subsequent sections. Once a conflict is resolved, the correct client will receive the reserved configuration when it renews.

Host reservations are defined as parameters for each subnet. Each host must have its own unique identifier, such as the hardware/MAC address. There is an optional reservations array in the subnet4 structure; each element in that array is a structure that holds information about reservations for a single host. In particular, the structure has an identifier that uniquely identifies a host. In the DHCPv4 context, the identifier is usually a hardware or MAC address. In most cases an IP address will be specified. It is also possible to specify a hostname, host-specific options, or fields carried within the DHCPv4 message such as siaddr, sname, or file.

NOTE:

The following example shows how to reserve addresses for specific hosts in a subnet:

{
"subnet4": [
    {
        "id": 1,
        "pools": [ { "pool":  "192.0.2.1 - 192.0.2.200" } ],
        "subnet": "192.0.2.0/24",
        "interface": "eth0",
        "reservations": [
            {
                "hw-address": "1a:1b:1c:1d:1e:1f",
                "ip-address": "192.0.2.202"
            },
            {
                "duid": "0a:0b:0c:0d:0e:0f",
                "ip-address": "192.0.2.100",
                "hostname": "alice-laptop"
            },
            {
                "circuit-id": "'charter950'",
                "ip-address": "192.0.2.203"
            },
            {
                "client-id": "01:11:22:33:44:55:66",
                "ip-address": "192.0.2.204"
            }
        ]
    }
],
...
}

The first entry reserves the 192.0.2.202 address for the client that uses a MAC address of 1a:1b:1c:1d:1e:1f. The second entry reserves the address 192.0.2.100 and the hostname of "alice-laptop" for the client using a DUID 0a:0b:0c:0d:0e:0f. (If DNS updates are planned, it is strongly recommended that the hostnames be unique.) The third example reserves address 192.0.3.203 for a client whose request would be relayed by a relay agent that inserts a circuit-id option with the value "charter950". The fourth entry reserves address 192.0.2.204 for a client that uses a client identifier with value 01:11:22:33:44:55:66.

The above example is used for illustrational purposes only; in actual deployments it is recommended to use as few types as possible (preferably just one). See Fine-Tuning DHCPv4 Host Reservation for a detailed discussion of this point.

Making a reservation for a mobile host that may visit multiple subnets requires a separate host definition in each subnet that host is expected to visit. It is not possible to define multiple host definitions with the same hardware address in a single subnet. Multiple host definitions with the same hardware address are valid if each is in a different subnet.

Adding host reservations incurs a performance penalty. In principle, when a server that does not support host reservation responds to a query, it needs to check whether there is a lease for a given address being considered for allocation or renewal. The server that does support host reservation has to perform additional checks: not only whether the address is currently used (i.e., if there is a lease for it), but also whether the address could be used by someone else (i.e., if there is a reservation for it). That additional check incurs extra overhead.

Address Reservation Types

In a typical Kea scenario there is an IPv4 subnet defined, e.g. 192.0.2.0/24, with a certain part of it dedicated for dynamic allocation by the DHCPv4 server. That dynamic part is referred to as a dynamic pool or simply a pool. In principle, a host reservation can reserve any address that belongs to the subnet. The reservations that specify addresses that belong to configured pools are called "in-pool reservations." In contrast, those that do not belong to dynamic pools are called "out-of-pool reservations." There is no formal difference in the reservation syntax and both reservation types are handled uniformly.

Kea supports global host reservations. These are reservations that are specified at the global level within the configuration and that do not belong to any specific subnet. Kea still matches inbound client packets to a subnet as before, but when the subnet's reservation mode is set to "global", Kea looks for host reservations only among the global reservations defined. Typically, such reservations would be used to reserve hostnames for clients which may move from one subnet to another.

NOTE:

NOTE:

Conflicts in DHCPv4 Reservations

As reservations and lease information are stored separately, conflicts may arise. Consider the following series of events: the server has configured the dynamic pool of addresses from the range of 192.0.2.10 to 192.0.2.20. Host A requests an address and gets 192.0.2.10. Now the system administrator decides to reserve address 192.0.2.10 for Host B. In general, reserving an address that is currently assigned to someone else is not recommended, but there are valid use cases where such an operation is warranted.

The server now has a conflict to resolve. If Host B boots up and requests an address, the server cannot immediately assign the reserved address 192.0.2.10. A naive approach would to be immediately remove the existing lease for Host A and create a new one for Host B. That would not solve the problem, though, because as soon as Host B gets the address, it will detect that the address is already in use (by Host A) and will send a DHCPDECLINE message. Therefore, in this situation, the server has to temporarily assign a different address from the dynamic pool (not matching what has been reserved) to Host B.

When Host A renews its address, the server will discover that the address being renewed is now reserved for another host - Host B. The server will inform Host A that it is no longer allowed to use it by sending a DHCPNAK message. The server will not remove the lease, though, as there's a small chance that the DHCPNAK will not be delivered if the network is lossy. If that happens, the client will not receive any responses, so it will retransmit its DHCPREQUEST packet. Once the DHCPNAK is received by Host A, it will revert to server discovery and will eventually get a different address. Besides allocating a new lease, the server will also remove the old one. As a result, address 192.0.2.10 will become free.

When Host B tries to renew its temporarily assigned address, the server will detect that it has a valid lease, but will note that there is a reservation for a different address. The server will send DHCPNAK to inform Host B that its address is no longer usable, but will keep its lease (again, the DHCPNAK may be lost, so the server will keep it until the client returns for a new address). Host B will revert to the server discovery phase and will eventually send a DHCPREQUEST message. This time the server will find that there is a reservation for that host and that the reserved address 192.0.2.10 is not used, so it will be granted. It will also remove the lease for the temporarily assigned address that Host B previously obtained.

This recovery will succeed, even if other hosts attempt to get the reserved address. If Host C requests the address 192.0.2.10 after the reservation is made, the server will either offer a different address (when responding to DHCPDISCOVER) or send DHCPNAK (when responding to DHCPREQUEST).

This mechanism allows the server to fully recover from a case where reservations conflict with existing leases; however, this procedure takes roughly as long as the value set for renew-timer. The best way to avoid such a recovery is not to define new reservations that conflict with existing leases. Another recommendation is to use out-of-pool reservations; if the reserved address does not belong to a pool, there is no way that other clients can get it.

NOTE:

Reserving a Hostname

When the reservation for a client includes the hostname, the server returns this hostname to the client in the Client FQDN or Hostname option. The server responds with the Client FQDN option only if the client has included the Client FQDN option in its message to the server. The server responds with the Hostname option if the client included the Hostname option in its message to the server, or if the client requested the Hostname option using the Parameter Request List option. The server returns the Hostname option even if it is not configured to perform DNS updates. The reserved hostname always takes precedence over the hostname supplied by the client or the autogenerated (from the IPv4 address) hostname.

The server qualifies the reserved hostname with the value of the ddns-qualifying-suffix parameter. For example, the following subnet configuration:

{
    "subnet4": [
    {
        "id": 1,
        "subnet": "10.0.0.0/24",
        "pools": [ { "pool": "10.0.0.10-10.0.0.100" } ],
        "ddns-qualifying-suffix": "example.isc.org.",
        "reservations": [
           {
             "hw-address": "aa:bb:cc:dd:ee:ff",
             "hostname": "alice-laptop"
           }
        ]
    }
    ],
    "dhcp-ddns": {
        "enable-updates": true
    }
}

will result in the "alice-laptop.example.isc.org." hostname being assigned to the client using the MAC address "aa:bb:cc:dd:ee:ff". If the ddns-qualifying-suffix is not specified, the default (empty) value will be used, and in this case the value specified as a hostname will be treated as a fully qualified name. Thus, by leaving the ddns-qualifying-suffix empty it is possible to qualify hostnames for different clients with different domain names:

{
    "subnet4": [
    {
        "id": 1,
        "subnet": "10.0.0.0/24",
        "pools": [ { "pool": "10.0.0.10-10.0.0.100" } ],
        "reservations": [
           {
             "hw-address": "aa:bb:cc:dd:ee:ff",
             "hostname": "alice-laptop.isc.org."
           },
           {
             "hw-address": "12:34:56:78:99:AA",
             "hostname": "mark-desktop.example.org."
           }
        ]
    }
    ],
    "dhcp-ddns": {
        "enable-updates": true
    }
}

The above example results in the assignment of the "alice-laptop.isc.org." hostname to the client using the MAC address "aa:bb:cc:dd:ee:ff", and the hostname "mark-desktop.example.org." to the client using the MAC address "12:34:56:78:99:AA".

Including Specific DHCPv4 Options in Reservations

Kea offers the ability to specify options on a per-host basis. These options follow the same rules as any other options. These can be standard options (see Standard DHCPv4 Options), custom options (see Custom DHCPv4 Options), or vendor-specific options (see DHCPv4 Vendor-Specific Options). The following example demonstrates how standard options can be defined:

{
    "subnet4": [
    {
        "reservations": [
        {
            "hw-address": "aa:bb:cc:dd:ee:ff",
            "ip-address": "192.0.2.1",
            "option-data": [
            {
                "name": "cookie-servers",
                "data": "10.1.1.202,10.1.1.203"
            },
            {
                "name": "log-servers",
                "data": "10.1.1.200,10.1.1.201"
            }
            ]
        }
        ],
        ...
    }
    ],
    ...
}

Vendor-specific options can be reserved in a similar manner:

{
    "subnet4": [
    {
        "reservations": [
        {
            "hw-address": "aa:bb:cc:dd:ee:ff",
            "ip-address": "10.0.0.7",
            "option-data": [
            {
                "name": "vivso-suboptions",
                "data": "4491"
            },
            {
                "name": "tftp-servers",
                "space": "vendor-4491",
                "data": "10.1.1.202,10.1.1.203"
            }
            ]
        }
        ],
        ...
    }
    ],
    ...
}

Options defined at the host level have the highest priority. In other words, if there are options defined with the same type on the global, subnet, class, and host levels, the host-specific values are used.

Reserving Next Server, Server Hostname, and Boot File Name

BOOTP/DHCPv4 messages include "siaddr", "sname", and "file" fields. Even though DHCPv4 includes corresponding options, such as option 66 and option 67, some clients may not support these options. For this reason, server administrators often use the "siaddr", "sname", and "file" fields instead.

With Kea, it is possible to make static reservations for these DHCPv4 message fields:

{
    "subnet4": [
    {
        "reservations": [
        {
            "hw-address": "aa:bb:cc:dd:ee:ff",
            "next-server": "10.1.1.2",
            "server-hostname": "server-hostname.example.org",
            "boot-file-name": "/usr/local/share/kea/bootfile.efi"
        }
        ],
        ...
    }
    ],
    ...
}

Note that those parameters can be specified in combination with other parameters for a reservation, such as a reserved IPv4 address. These parameters are optional; a subset of them can be specified, or all of them can be omitted.

Reserving Client Classes in DHCPv4

Using Expressions in Classification explains how to configure the server to assign classes to a client, based on the content of the options that this client sends to the server. Host reservation mechanisms also allow for the static assignment of classes to clients. The definitions of these classes are placed in the Kea configuration file or a database. The following configuration snippet shows how to specify that a client belongs to the classes reserved-class1 and reserved-class2. Those classes are associated with specific options sent to the clients which belong to them.

{
    "client-classes": [
    {
       "name": "reserved-class1",
       "option-data": [
       {
           "name": "routers",
           "data": "10.0.0.200"
       }
       ]
    },
    {
       "name": "reserved-class2",
       "option-data": [
       {
           "name": "domain-name-servers",
           "data": "10.0.0.201"
       }
       ]
    }
    ],
    "subnet4": [
    {
        "id": 1,
        "subnet": "10.0.0.0/24",
        "pools": [ { "pool": "10.0.0.10-10.0.0.100" } ],
        "reservations": [
        {
            "hw-address": "aa:bb:cc:dd:ee:ff",
            "client-classes": [ "reserved-class1", "reserved-class2" ]
        }
        ]
    }
    ]
 }

In some cases the host reservations can be used in conjunction with client classes specified within the Kea configuration. In particular, when a host reservation exists for a client within a given subnet, the "KNOWN" built-in class is assigned to the client. Conversely, when there is no static assignment for the client, the "UNKNOWN" class is assigned to the client. Class expressions within the Kea configuration file can refer to "KNOWN" or "UNKNOWN" classes using the "member" operator. For example:

{
    "client-classes": [
        {
            "name": "dependent-class",
            "test": "member('KNOWN')",
            "only-in-additional-list": true
        }
    ]
}

The only-in-additional-list parameter is needed here to force evaluation of the class after the lease has been allocated, and thus the reserved class has been also assigned.

NOTE:

NOTE:

Storing Host Reservations in MySQL or PostgreSQL

Kea can store host reservations in MySQL or PostgreSQL. See Hosts Storage for information on how to configure Kea to use reservations stored in MySQL or PostgreSQL. Kea provides a dedicated hook for managing reservations in a database; section libdhcp_host_cmds.so: Host Commands provides detailed information. The Kea wiki provides some examples of how to conduct common host reservation operations.

NOTE:

Fine-Tuning DHCPv4 Host Reservation

The host reservation capability introduces additional restrictions for the allocation engine (the component of Kea that selects an address for a client) during lease selection and renewal. In particular, three major checks are necessary. First, when selecting a new lease, it is not sufficient for a candidate lease to simply not be in use by another DHCP client; it also must not be reserved for another client. Similarly, when renewing a lease, an additional check must be performed to see whether the address being renewed is reserved for another client. Finally, when a host renews an address, the server must check whether there is a reservation for this host, which would mean the existing (dynamically allocated) address should be revoked and the reserved one be used instead.

Some of those checks may be unnecessary in certain deployments, and not performing them may improve performance. The Kea server provides the reservations-global, reservations-in-subnet and reservations-out-of-pool configuration parameters to select the types of reservations allowed for a particular subnet. Each reservation type has different constraints for the checks to be performed by the server when allocating or renewing a lease for the client.

Configuration flags are:

Since Kea 1.9.1 the reservations-global, reservations-in-subnet and reservations-out-of-pool flags are suported.

The reservations-global, reservations-in-subnet and reservations-out-of-pool parameters can be specified at:

To decide which flags to use, the following decision diagram may be useful:

                              O
                              |
                              v
+-----------------------------+------------------------------+
|         Is per-host configuration needed, such as          |
|                reserving specific addresses,               |
|               assigning specific options or                |
| assigning packets to specific classes on per-device basis? |
+-+-----------------+----------------------------------------+
  |                 |
no|              yes|
  |                 |   +--------------------------------------+
  |                 |   |         For all given hosts,         |
  +--> "disabled"   +-->+      can the reserved resources      |
                        |  be used in all configured subnets?  |
                        +--------+---------------------------+-+
                                 |                           |
+----------------------------+   |no                         |yes
|             Is             |   |                           |
|  at least one reservation  +<--+               "global" <--+
| used to reserve addresses? |
+-+------------------------+-+
  |                        |
no|                     yes|   +---------------------------+
  |                        |   | Is high leases-per-second |
  +--> "out-of-pool"       +-->+ performance or efficient  |
        ^                      |      resource usage       |
        |                      |  (CPU ticks, RAM usage,   |
        |                      |   database roundtrips)    |
        |                      | important to your setup?  |
        |                      +-+----------------+--------+
        |                        |                |
        |                     yes|              no|
        |                        |                |
        |          +-------------+                |
        |          |                              |
        |          |   +----------------------+   |
        |          |   | Can it be guaranteed |   |
        |          +-->+  that the reserved   |   |
        |              |      addresses       |   |
        |              |  aren't part of the  |   |
        |              |   pools configured   |   |
        |              |  in the respective   |   |
        |              |       subnet?        |   |
        |              +-+------------------+-+   |
        |                |                  |     |
        |             yes|                no|     |
        |                |                  |     V
        +----------------+                  +--> "in-subnet"

An example configuration that disables reservations looks as follows:

{
  "Dhcp4": {
    "subnet4": [
      {
        "id": 1,
        "pools": [
          {
            "pool": "192.0.2.10-192.0.2.100"
          }
        ],
        "reservations-global": false,
        "reservations-in-subnet": false,
        "subnet": "192.0.2.0/24"
      }
    ]
  }
}

An example configuration using global reservations is shown below:

{
  "Dhcp4": {
    "reservations-global": true,
    "reservations": [
      {
        "hostname": "host-one",
        "hw-address": "01:bb:cc:dd:ee:ff"
      },
      {
        "hostname": "host-two",
        "hw-address": "02:bb:cc:dd:ee:ff"
      }
    ],
    "subnet4": [
      {
        "id": 1,
        "pools": [
          {
            "pool": "192.0.2.10-192.0.2.100"
          }
        ],
        "subnet": "192.0.2.0/24"
      }
    ]
  }
}

The meaning of the reservation flags are:

The disabled configuration corresponds to:

{
  "Dhcp4": {
    "reservations-global": false,
    "reservations-in-subnet": false
  }
}

The global``configuration using ``reservations-global corresponds to:

{
  "Dhcp4": {
    "reservations-global": true,
    "reservations-in-subnet": false
  }
}

The out-of-pool configuration using reservations-out-of-pool corresponds to:

{
  "Dhcp4": {
    "reservations-global": false,
    "reservations-in-subnet": true,
    "reservations-out-of-pool": true
  }
}

And the in-subnet configuration using reservations-in-subnet corresponds to:

{
  "Dhcp4": {
    "reservations-global": false,
    "reservations-in-subnet": true,
    "reservations-out-of-pool": false
  }
}

To activate both global and in-subnet, the following combination can be used:

{
  "Dhcp4": {
    "reservations-global": true,
    "reservations-in-subnet": true,
    "reservations-out-of-pool": false
  }
}

To activate both global and out-of-pool, the following combination can be used:

{
  "Dhcp4": {
    "reservations-global": true,
    "reservations-in-subnet": true,
    "reservations-out-of-pool": true
  }
}

Enabling out-of-pool and disabling in-subnet at the same time is not recommended because out-of-pool applies to host reservations in a subnet, which are fetched only when the in-subnet flag is true.

The parameter can be specified at the global, subnet, and shared-network levels.

An example configuration that disables reservations looks as follows:

{
  "Dhcp4": {
    "subnet4": [
      {
        "reservations-global": false,
        "reservations-in-subnet": false,
        "subnet": "192.0.2.0/24",
        "id": 1
      }
    ]
  }
}

An example configuration using global reservations is shown below:

{
  "Dhcp4": {
    "reservations": [
      {
        "hostname": "host-one",
        "hw-address": "01:bb:cc:dd:ee:ff"
      },
      {
        "hostname": "host-two",
        "hw-address": "02:bb:cc:dd:ee:ff"
      }
    ],
    "reservations-global": true,
    "reservations-in-subnet": false,
    "subnet4": [
      {
        "pools": [
          {
            "pool": "192.0.2.10-192.0.2.100"
          }
        ],
        "subnet": "192.0.2.0/24",
        "id": 1
      }
    ]
  }
}

For more details regarding global reservations, see Global Reservations in DHCPv4.

Another aspect of host reservations is the different types of identifiers. Kea currently supports four types of identifiers: hw-address, duid, client-id, and circuit-id. This is beneficial from a usability perspective; however, there is one drawback. For each incoming packet, Kea has to extract each identifier type and then query the database to see if there is a reservation by this particular identifier. If nothing is found, the next identifier is extracted and the next query is issued. This process continues until either a reservation is found or all identifier types have been checked. Over time, with an increasing number of supported identifier types, Kea would become slower and slower.

To address this problem, a parameter called host-reservation-identifiers is available. It takes a list of identifier types as a parameter. Kea checks only those identifier types enumerated in host-reservation-identifiers. From a performance perspective, the number of identifier types should be kept to a minimum, ideally one. If the deployment uses several reservation types, please enumerate them from most- to least-frequently used, as this increases the chances of Kea finding the reservation using the fewest queries. An example of a host-reservation-identifiers configuration looks as follows:

{
"host-reservation-identifiers": [ "circuit-id", "hw-address", "duid", "client-id" ],
"subnet4": [
    {
        "subnet": "192.0.2.0/24",
        ...
    }
],
...
}

If not specified, the default value is:

"host-reservation-identifiers": [ "hw-address", "duid", "circuit-id", "client-id" ]

NOTE:

Global Reservations in DHCPv4

In some deployments, such as mobile networks, clients can roam within the network and certain parameters must be specified regardless of the client's current location. To meet such a need, Kea offers a global reservation mechanism. The idea behind it is that regular host reservations are tied to specific subnets, by using a specific subnet ID. Kea can specify a global reservation that can be used in every subnet that has global reservations enabled.

This feature can be used to assign certain parameters, such as hostname or other dedicated, host-specific options. It can also be used to assign addresses.

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 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:

To use global host reservations, a configuration similar to the following can be used:

"Dhcp4": {
    # This specifies global reservations.
    # They will apply to all subnets that
    # have global reservations enabled.
    "reservations": [
    {
       "hw-address": "aa:bb:cc:dd:ee:ff",
       "hostname": "hw-host-dynamic"
    },
    {
       "hw-address": "01:02:03:04:05:06",
       "hostname": "hw-host-fixed",
       # Use of IP addresses in global reservations is risky.
       # If used outside of a matching subnet, such as 192.0.1.0/24,
       # it will result in a broken configuration being handed
       # to the client.
       "ip-address": "192.0.1.77"
    },
    {
       "duid": "01:02:03:04:05",
       "hostname": "duid-host"
    },
    {
       "circuit-id": "'charter950'",
       "hostname": "circuit-id-host"
    },
    {
       "client-id": "01:11:22:33:44:55:66",
       "hostname": "client-id-host"
    }
    ],
    "valid-lifetime": 600,
    "subnet4": [
    {
        "id": 1,
        "subnet": "10.0.0.0/24",
        # Specify if the server should look up global reservations.
        "reservations-global": true,
        # Specify if the server should look up in-subnet reservations.
        "reservations-in-subnet": false,
        # Specify if the server can assume that all reserved addresses
        # are out-of-pool. It can be ignored because "reservations-in-subnet"
        # is false.
        # "reservations-out-of-pool": false,
        "pools": [ { "pool": "10.0.0.10-10.0.0.100" } ]
    }
    ]
}

When using database backends, the global host reservations are distinguished from regular reservations by using a subnet-id value of 0.

Pool Selection with Client Class Reservations

Client classes can be specified in the Kea configuration file and/or via host reservations. The classes specified in the Kea configuration file are evaluated immediately after receiving the DHCP packet and therefore can be used to influence subnet selection using the client-classes parameter specified in the subnet scope. The classes specified within the host reservations are fetched and assigned to the packet after the server has already selected a subnet for the client. This means that the client class specified within a host reservation cannot be used to influence subnet assignment for this client, unless the subnet belongs to a shared network. If the subnet belongs to a shared network, the server may dynamically change the subnet assignment while trying to allocate a lease. If the subnet does not belong to a shared network, the subnet is not changed once selected.

If the subnet does not belong to a shared network, it is possible to use host reservation-based client classification to select a pool within the subnet as follows:

{
    "Dhcp4": {
        "client-classes": [
            {
                "name": "reserved_class"
            },
            {
                "name": "unreserved_class",
                "test": "not member('reserved_class')"
            }
        ],
        "subnet4": [
            {
                "id": 1,
                "subnet": "192.0.2.0/24",
                "reservations": [
                    {
                        "hw-address": "aa:bb:cc:dd:ee:fe",
                        "client-classes": [ "unreserved_class" ]
                    }
                ],
                "pools": [
                    {
                        "pool": "192.0.2.10 - 192.0.2.20",
                        "client-classes": [ "unreserved_class" ]
                    },
                    {
                        "pool": "192.0.2.30 - 192.0.2.40",
                        "client-classes": [ "reserved_class" ]
                    },
                    {
                        "pool": "192.0.2.50 - 192.0.2.60"
                    }
                ]
            }
        ]
    }
}

reserved_class is declared without the test parameter because it may only be assigned to a client via the host reservation mechanism. The second class, unreserved_class, is assigned to clients which do not belong to reserved_class.

The first pool in the subnet is used for clients not having such a reservation. The second pool is only used for clients having a reservation for reserved_class. The third pool is an unrestricted pool for any clients, comprising of both reserved_class clients and unreserved_class.

The configuration snippet includes one host reservation which causes the client with the MAC address aa:bb:cc:dd:ee:fe to be assigned to reserved_class. Thus, this client will be given an IP address from the second address pool.

Reservations defined on a subnet that belongs to a shared network are not visible to an otherwise matching client, so they cannot be used to select pools, nor subnets for that matter.

Subnet Selection with Client Class Reservations

There is one specific use case when subnet selection may be influenced by client classes specified within host reservations: when the client belongs to a shared network. In such a case it is possible to use classification to select a subnet within this shared network. Consider the following example:

{
    "Dhcp4": {
        "client-classes": [
            {
                "name": "reserved_class"
            },
            {
                "name": "unreserved_class",
                "test": "not member('reserved_class')"
            }
        ],
        "reservations": [
            {
                "hw-address": "aa:bb:cc:dd:ee:fe",
                "client-classes": [ "reserved_class" ]
            }
        ],
        "reservations-global": true,
        "reservations-in-subnet": false,
        "shared-networks": [
            {
                "name": "net",
                "subnet4": [
                    {
                        "id": 1,
                        "subnet": "192.0.2.0/24",
                        "pools": [
                            {
                                "pool": "192.0.2.10-192.0.2.20",
                                "client-classes": [ "unreserved_class" ]
                            },
                            {
                                "pool": "192.0.2.30-192.0.2.40",
                                "client-classes": [ "unreserved_class" ]
                            }
                        ]
                    },
                    {
                        "id": 2,
                        "subnet": "192.0.3.0/24",
                        "pools": [
                            {
                                "pool": "192.0.3.10-192.0.3.20",
                                "client-classes": [ "reserved_class" ]
                            },
                            {
                                "pool": "192.0.3.30-192.0.3.40",
                                "client-classes": [ "reserved_class" ]
                            }
                        ]
                    },
                    {
                        "id": 3,
                        "subnet": "192.0.4.0/24",
                        "pools": [
                            {
                                "pool": "192.0.4.10-192.0.4.20"
                            },
                            {
                                "pool": "192.0.4.30-192.0.4.40"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

This is similar to the example described in Pool Selection with Client Class Reservations. This time, however, there are three subnets, of which the first two have a pool associated with a different class each.

The clients that do not have a reservation for reserved_class are assigned an address from the first subnet and when that is filled from the third subnet. Clients with a reservation for reserved_class are assigned an address from the second subnet and when that is filled from the third subnet.

The subnets must belong to the same shared network.

For a subnet to be restricted to a certain class, or skipped, all of the pools inside that subnet must be guarded by reserved_class or unreserved_class respectively.

In addition, the reservation for the client class must be specified at the global scope (global reservation) and reservations-global must be set to true.

In the example above, the client-classes configuration parameter could also be specified at the subnet level rather than the pool level, and would yield the same effect.

If the subnets were defined outside shared networks, and client-classes were specified at the subnet level, then early-global-reservations-lookup would also need to be enabled in order for subnet selection to work.

Multiple Reservations for the Same IP

Host reservations were designed to preclude the creation of multiple reservations for the same IP address within a particular subnet, to avoid having two different clients compete for the same address. When using the default settings, the server returns a configuration error when it finds two or more reservations for the same IP address within a subnet in the Kea configuration file. libdhcp_host_cmds.so returns an error in response to the reservation-add command when it detects that the reservation exists in the database for the IP address for which the new reservation is being added.

In some deployments a single host can select one of several network interfaces to communicate with the DHCP server, and the server must assign the same IP address to the host regardless of the interface used. Since each interface is assigned a different MAC address, it implies that several host reservations must be created to associate all of the MAC addresses present on this host with IP addresses. Using different IP addresses for each interface is impractical and is considered a waste of the IPv4 address space, especially since the host typically uses only one interface for communication with the server, hence only one IP address is in use.

This causes a need to create multiple host reservations for a single IP address within a subnet; this is supported since the Kea 1.9.1 release as an optional mode of operation, enabled with the ip-reservations-unique global parameter.

ip-reservations-unique is a boolean parameter that defaults to true, which forbids the specification of more than one reservation for the same IP address within a given subnet. Setting this parameter to false allows such reservations to be created both in the Kea configuration file and in the host database backend, via libdhcp_host_cmds.so.

Setting ip-reservations-unique to false when using memfile, MySQL, or PostgreSQL is supported. This setting is not supported when using Host Cache (see libdhcp_host_cache.so: Host Cache Reservations for Improved Performance) or the RADIUS backend (see libdhcp_radius.so: RADIUS Server Support). These reservation backends do not support multiple reservations for the same IP; if either of these hooks is loaded and ip-reservations-unique is set to false, then a configuration error is emitted and the server fails to start.

NOTE:

The following is an example configuration with two reservations for the same IP address but different MAC addresses:

"Dhcp4": {
    "ip-reservations-unique": false,
    "subnet4": [
        {
            "id": 1,
            "subnet": "192.0.2.0/24",
            "reservations": [
                {
                    "hw-address": "1a:1b:1c:1d:1e:1f",
                    "ip-address": "192.0.2.11"
                },
                {
                    "hw-address": "2a:2b:2c:2d:2e:2f",
                    "ip-address": "192.0.2.11"
                }
            ]
        }
    ]
}

It is possible to control the ip-reservations-unique parameter via the Configuration Backend in DHCPv4. If the new setting of this parameter conflicts with the currently used backends (i.e. backends do not support the new setting), the new setting is ignored and a warning log message is generated. The backends continue to use the default setting, expecting that IP reservations are unique within each subnet. To allow the creation of non-unique IP reservations, the administrator must remove the backends which lack support for them from the configuration file.

Administrators must be careful when they have been using multiple reservations for the same IP address and later decide to return to the default mode in which this is no longer allowed. They must make sure that at most one reservation for a given IP address exists within a subnet, prior to switching back to the default mode. If such duplicates are left in the configuration file, the server reports a configuration error. Leaving such reservations in the host databases does not cause configuration errors but may lead to lease allocation errors during the server's operation, when it unexpectedly finds multiple reservations for the same IP address.

NOTE:

The reservations-lookup-first is a boolean parameter which controls whether host reservations lookup should be performed before lease lookup. This parameter has effect only when multi-threading is disabled. When multi-threading is enabled, host reservations lookup is always performed first to avoid lease-lookup resource locking. The reservations-lookup-first parameter defaults to false when multi-threading is disabled.

Host Reservations as Basic Access Control

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 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. 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. Empty reservations, i.e. reservations that only have the identification criterion, can be useful as a way of making the clients known.

"Dhcp4": {
    "client-classes": [
        {
            "name": "KNOWN",
            "option-data": [
                {
                    "name": "routers",
                    "data": "192.0.2.250"
                }
            ]
        }
    ],
    "reservations": [
        // Clients on this list will be added to the KNOWN class.
        { "hw-address": "aa:bb:cc:dd:ee:fe" },
        { "hw-address": "11:22:33:44:55:66" }
    ],
    "reservations-in-subnet": true,
    "subnet4": [
        {
            "id": 1,
            "subnet": "192.0.2.0/24",
            "pools": [
                {
                    "pool": "192.0.2.1-192.0.2.200"
                }
            ]
        }
    ]
}

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.

"Dhcp4": {
    "client-classes": [
        {
            "name": "blocked",
            "option-data": [
                {
                    "name": "routers",
                    "data": "192.0.2.251"
                }
            ]
        }
    ],
    "reservations": [
        // Clients on this list will be added to the KNOWN class. Some
        // will also be added to the blocked class.
        { "hw-address": "aa:bb:cc:dd:ee:fe",
          "client-classes": [ "blocked" ] },
        { "hw-address": "11:22:33:44:55:66" }
    ],
    "reservations-in-subnet": true,
    "subnet4": [
        {
            "id": 1,
            "subnet": "192.0.2.0/24",
            "pools": [
                {
                    "pool": "192.0.2.1-192.0.2.200"
                }
            ],
            "option-data": [
                {
                    "name": "routers",
                    "data": "192.0.2.250"
                }
            ]
        }
    ]
}

Shared Networks in DHCPv4

DHCP servers use subnet information in two ways. It is used to both determine the point of attachment, i.e. where the client is connected to the network, and to group information pertaining to a specific location in the network. Sometimes it is useful to have more than one logical IP subnet deployed on the same physical link. Understanding that two or more subnets are used on the same link requires additional logic in the DHCP server. This capability is called "shared networks" in Kea, and sometimes also "shared subnets"; in Microsoft's nomenclature it is called "multinet."

There are many cases where the shared networks feature is useful; here we explain just a handful of the most common ones. The first and by far most common use case is an existing IPv4 network that has grown and is running out of available address space. Rather than migrating all devices to a new, larger subnet, it is easier to simply configure additional subnets on top of the existing one. Sometimes, due to address space fragmentation (e.g. only many disjointed /24s are available), this is the only choice. Also, configuring additional subnets has the advantage of not disrupting the operation of existing devices.

Another very frequent use case comes from cable networks. There are two types of devices in cable networks: cable modems and the end-user devices behind them. It is a common practice to use different subnets for cable modems to prevent users from tinkering with them. In this case, the distinction is based on the type of device, rather than on address-space exhaustion.

A client connected to a shared network may be assigned an address from any of the pools defined within the subnets belonging to the shared network. Internally, the server selects one of the subnets belonging to a shared network and tries to allocate an address from this subnet. If the server is unable to allocate an address from the selected subnet (e.g., due to address-pool exhaustion), it uses another subnet from the same shared network and tries to allocate an address from this subnet. The server typically allocates all addresses available in a given subnet before it starts allocating addresses from other subnets belonging to the same shared network. However, in certain situations the client can be allocated an address from another subnet before the address pools in the first subnet get exhausted; this sometimes occurs when the client provides a hint that belongs to another subnet, or the client has reservations in a subnet other than the default.

NOTE:

To define a shared network, an additional configuration scope is introduced:

{
"Dhcp4": {
    "shared-networks": [
        {
            # Name of the shared network. It may be an arbitrary string
            # and it must be unique among all shared networks.
            "name": "my-secret-lair-level-1",
            # The subnet selector can be specified at the shared-network level.
            # Subnets from this shared network will be selected for directly
            # connected clients sending requests to the server's "eth0" interface.
            "interface": "eth0",
            # This starts a list of subnets in this shared network.
            # There are two subnets in this example.
            "subnet4": [
                {
                    "id": 1,
                    "subnet": "10.0.0.0/8",
                    "pools": [ { "pool":  "10.0.0.1 - 10.0.0.99" } ]
                },
                {
                    "id": 2,
                    "subnet": "192.0.2.0/24",
                    "pools": [ { "pool":  "192.0.2.100 - 192.0.2.199" } ]
                }
            ]
        }
    ],
    # end of shared-networks
    # It is likely that in the network there will be a mix of regular,
    # "plain" subnets and shared networks. It is perfectly valid to mix
    # them in the same configuration file.
    #
    # This is a regular subnet. It is not part of any shared network.
    "subnet4": [
        {
            "id": 3,
            "subnet": "192.0.3.0/24",
            "pools": [ { "pool":  "192.0.3.1 - 192.0.3.200" } ],
            "interface": "eth1"
        }
    ]
}
}

As demonstrated in the example, it is possible to mix shared and regular ("plain") subnets. Each shared network must have a unique name. This is similar to the ID for subnets, but gives administrators more flexibility. It is used for logging, but also internally for identifying shared networks.

In principle it makes sense to define only shared networks that consist of two or more subnets. However, for testing purposes, an empty subnet or a network with just a single subnet is allowed. This is not a recommended practice in production networks, as the shared network logic requires additional processing and thus lowers the server's performance. To avoid unnecessary performance degradation, shared subnets should only be defined when required by the deployment.

Shared networks provide the ability to specify many parameters in the shared network scope that apply to all subnets within it. If necessary, it is possible to specify a parameter in the shared-network scope and then override its value in the subnet scope. For example:

{
"shared-networks": [
    {
        "name": "lab-network3",
        "interface": "eth0",
        # This applies to all subnets in this shared network, unless
        # values are overridden on subnet scope.
        "valid-lifetime": 600,
        # This option is made available to all subnets in this shared
        # network.
        "option-data": [
        {
            "name": "log-servers",
            "data": "1.2.3.4"
        }
        ],
        "subnet4": [
            {
                "id": 1,
                "subnet": "10.0.0.0/8",
                "pools": [ { "pool":  "10.0.0.1 - 10.0.0.99" } ],
                # This particular subnet uses different values.
                "valid-lifetime": 1200,
                "option-data": [
                {
                    "name": "log-servers",
                    "data": "10.0.0.254"
                },
                {
                    "name": "routers",
                    "data": "10.0.0.254"
                } ]
            },
            {
                 "id": 2,
                 "subnet": "192.0.2.0/24",
                 "pools": [ { "pool":  "192.0.2.100 - 192.0.2.199" } ],
                 # This subnet does not specify its own valid-lifetime value,
                 # so it is inherited from shared network scope.
                 "option-data": [
                 {
                     "name": "routers",
                     "data": "192.0.2.1"
                 } ]
            }
        ]
    }
    ],
    ...
}

In this example, there is a log-servers option defined that is available to clients in both subnets in this shared network. Also, the valid lifetime is set to 10 minutes (600s). However, the first subnet overrides some of the values (the valid lifetime is 20 minutes, there is a different IP address for log-servers), but also adds its own option (the router address). Assuming a client asking for router and log-servers options is assigned a lease from this subnet, it will get a lease for 20 minutes and a log-servers and routers value of 10.0.0.254. If the same client is assigned to the second subnet, it will get a 10-minute lease, a log-servers value of 1.2.3.4, and routers set to 192.0.2.1.

Local and Relayed Traffic in Shared Networks

It is possible to specify an interface name at the shared-network level, to tell the server that this specific shared network is reachable directly (not via relays) using the local network interface. As all subnets in a shared network are expected to be used on the same physical link, it is a configuration error to attempt to define a shared network using subnets that are reachable over different interfaces. In other words, all subnets within the shared network must have the same value for the interface parameter. The following configuration is an example of what NOT to do:

{
"shared-networks": [
    {
        "name": "office-floor-2",
        "subnet4": [
            {
                "id": 1,
                "subnet": "10.0.0.0/8",
                "pools": [ { "pool":  "10.0.0.1 - 10.0.0.99" } ],
                "interface": "eth0"
            },
            {
                 "id": 2,
                 "subnet": "192.0.2.0/24",
                 "pools": [ { "pool":  "192.0.2.100 - 192.0.2.199" } ],
                 # Specifying the different interface name is a configuration
                 # error. This value should rather be "eth0" or the interface
                 # name in the other subnet should be "eth1".
                 "interface": "eth1"
            }
        ]
    }
],
...
}

To minimize the chance of configuration errors, it is often more convenient to simply specify the interface name once, at the shared-network level, as shown in the example below.

{
"shared-networks": [
    {
        "name": "office-floor-2",
        # This tells Kea that the whole shared network is reachable over a
        # local interface. This applies to all subnets in this network.
        "interface": "eth0",
        "subnet4": [
            {
                "id": 1,
                "subnet": "10.0.0.0/8",
                "pools": [ { "pool":  "10.0.0.1 - 10.0.0.99" } ]
            },
            {
                 "id": 2,
                 "subnet": "192.0.2.0/24",
                 "pools": [ { "pool":  "192.0.2.100 - 192.0.2.199" } ]
            }
        ]
    }
],
...
}

With relayed traffic, subnets are typically selected using the relay agents' addresses. If the subnets are used independently (not grouped within a shared network), a different relay address can be specified for each of these subnets. When multiple subnets belong to a shared network they must be selected via the same relay address and, similarly to the case of the local traffic described above, it is a configuration error to specify different relay addresses for the respective subnets in the shared network. The following configuration is another example of what NOT to do:

{
"shared-networks": [
    {
        "name": "kakapo",
        "subnet4": [
            {
                "id": 1,
                "subnet": "192.0.2.0/26",
                "relay": {
                    "ip-addresses": [ "192.1.1.1" ]
                },
                "pools": [ { "pool": "192.0.2.63 - 192.0.2.63" } ]
            },
            {
                "id": 2,
                "subnet": "10.0.0.0/24",
                "relay": {
                    # Specifying a different relay address for this
                    # subnet is a configuration error. In this case
                    # it should be 192.1.1.1 or the relay address
                    # in the previous subnet should be 192.2.2.2.
                    "ip-addresses": [ "192.2.2.2" ]
                },
                "pools": [ { "pool": "10.0.0.16 - 10.0.0.16" } ]
            }
        ]
    }
],
...
}

Again, it is better to specify the relay address at the shared-network level; this value will be inherited by all subnets belonging to the shared network.

{
"shared-networks": [
    {
        "name": "kakapo",
        "relay": {
            # This relay address is inherited by both subnets.
            "ip-addresses": [ "192.1.1.1" ]
        },
        "subnet4": [
            {
                "id": 1,
                "subnet": "192.0.2.0/26",
                "pools": [ { "pool": "192.0.2.63 - 192.0.2.63" } ]
            },
            {
                "id": 2,
                "subnet": "10.0.0.0/24",
                "pools": [ { "pool": "10.0.0.16 - 10.0.0.16" } ]
            }
        ]
    }
],
...
}

Even though it is technically possible to configure two (or more) subnets within the shared network to use different relay addresses, this will almost always lead to a different behavior than what the user expects. In this case, the Kea server will initially select one of the subnets by matching the relay address in the client's packet with the subnet's configuration. However, it MAY end up using the other subnet (even though it does not match the relay address) if the client already has a lease in this subnet or has a host reservation in this subnet, or simply if the initially selected subnet has no more addresses available. Therefore, it is strongly recommended to always specify subnet selectors (interface or relay address) at the shared-network level if the subnets belong to a shared network, as it is rarely useful to specify them at the subnet level and may lead to the configuration errors described above.

Client Classification in Shared Networks

Sometimes it is desirable to segregate clients into specific subnets based on certain properties. This mechanism is called client classification and is described in Client Classification.

Client classification can be applied to subnets belonging to shared networks in the same way as it is used for subnets specified outside of shared networks. It is important to understand how the server selects subnets for clients when client classification is in use, to ensure that the appropriate subnet is selected for a given client type.

If a subnet is associated with one or more classes, only the clients belonging to at least one of these classes may use this subnet. If there are no classes specified for a subnet, any client connected to a given shared network can use this subnet. A common mistake is to assume that a subnet that includes a client class is preferred over subnets without client classes.

The client-classes parameter may be specified at the shared network, subnet, and/or pool scopes. If specified for a shared network, clients must belong to at least one of the classes specified for that network to be considered for subnets within that network. If specified for a subnet, clients must belong to at least one of the classes specified for that subnet to be considered for any of that subnet's pools or host reservations. If specified for a pool, clients must belong to at least one of the classes specified for that pool to be given a lease from that pool.

Consider the following example:

{
    "client-classes": [
        {
            "name": "b-devices",
            "test": "option[93].hex == 0x0002"
        }
    ],
    "shared-networks": [
        {
            "name": "galah",
            "interface": "eth0",
            "subnet4": [
                {
                    "id": 1,
                    "subnet": "192.0.2.0/26",
                    "pools": [ { "pool": "192.0.2.1 - 192.0.2.63" } ]
                },
                {
                    "id": 2,
                    "subnet": "10.0.0.0/24",
                    "pools": [ { "pool": "10.0.0.2 - 10.0.0.250" } ],
                    "client-classes": [ "b-devices" ]
                }
            ]
        }
    ]
}

If the client belongs to the "b-devices" class (because it includes option 93 with a value of 0x0002), that does not guarantee that the subnet 10.0.0.0/24 will be used (or preferred) for this client. The server can use either of the two subnets, because the subnet 192.0.2.0/26 is also allowed for this client. The client classification used in this case should be perceived as a way to restrict access to certain subnets, rather than as a way to express subnet preference. For example, if the client does not belong to the "b-devices" class, it may only use the subnet 192.0.2.0/26 and will never use the subnet 10.0.0.0/24.

A typical use case for client classification is in a cable network, where cable modems should use one subnet and other devices should use another subnet within the same shared network. In this case it is necessary to apply classification on all subnets. The following example defines two classes of devices, and the subnet selection is made based on option 93 values.

{
    "client-classes": [
        {
            "name": "a-devices",
            "test": "option[93].hex == 0x0001"
        },
        {
            "name": "b-devices",
            "test": "option[93].hex == 0x0002"
        }
    ],
    "shared-networks": [
        {
            "name": "galah",
            "interface": "eth0",
            "subnet4": [
                {
                    "id": 1,
                    "subnet": "192.0.2.0/26",
                    "pools": [ { "pool": "192.0.2.1 - 192.0.2.63" } ],
                    "client-classes": [ "a-devices" ]
                },
                {
                    "id": 2,
                    "subnet": "10.0.0.0/24",
                    "pools": [ { "pool": "10.0.0.2 - 10.0.0.250" } ],
                    "client-classes": [ "b-devices" ]
                }
            ]
        }
    ]
}

In this example each class has its own restriction. Only clients that belong to class "a-devices" are able to use subnet 192.0.2.0/26 and only clients belonging to "b-devices" are able to use subnet 10.0.0.0/24. Care should be taken not to define too-restrictive classification rules, as clients that are unable to use any subnets will be refused service. However, this may be a desired outcome if one wishes to provide service only to clients with known properties (e.g. only VoIP phones allowed on a given link).

It is possible to achieve an effect similar to the one presented in this section without the use of shared networks. If the subnets are placed in the global subnets scope, rather than in the shared network, the server will still use classification rules to pick the right subnet for a given class of devices. The major benefit of placing subnets within the shared network is that common parameters for the logically grouped subnets can be specified once in the shared-network scope, e.g. the interface or relay parameter. All subnets belonging to this shared network will inherit those parameters.

Host Reservations in Shared Networks

Subnets that are part of a shared network allow host reservations, similar to regular subnets:

{
    "shared-networks": [
    {
        "name": "frog",
        "interface": "eth0",
        "subnet4": [
            {
                "subnet": "192.0.2.0/26",
                "id": 100,
                "pools": [ { "pool": "192.0.2.1 - 192.0.2.63" } ],
                "reservations": [
                    {
                        "hw-address": "aa:bb:cc:dd:ee:ff",
                        "ip-address": "192.0.2.28"
                    }
                ]
            },
            {
                "subnet": "10.0.0.0/24",
                "id": 101,
                "pools": [ { "pool": "10.0.0.1 - 10.0.0.254" } ],
                "reservations": [
                    {
                        "hw-address": "11:22:33:44:55:66",
                        "ip-address": "10.0.0.29"
                    }
                ]
            }
        ]
    }
    ]
}

It is worth noting that Kea conducts additional checks when processing a packet if shared networks are defined. First, instead of simply checking whether there is a reservation for a given client in its initially selected subnet, Kea looks through all subnets in a shared network for a reservation. This is one of the reasons why defining a shared network may impact performance. If there is a reservation for a client in any subnet, that particular subnet is selected for the client. Although it is technically not an error, it is considered bad practice to define reservations for the same host in multiple subnets belonging to the same shared network.

While not strictly mandatory, it is strongly recommended to use explicit "id" values for subnets if database storage will be used for host reservations. If an ID is not specified, the values for it are auto-generated, i.e. Kea assigns increasing integer values starting from 1. Thus, the auto-generated IDs are not stable across configuration changes.

Server Identifier in DHCPv4

The DHCPv4 protocol uses a "server identifier" to allow clients to discriminate between several servers present on the same link; this value is an IPv4 address of the server. The server chooses the IPv4 address of the interface on which the message from the client (or relay) has been received. A single server instance uses multiple server identifiers if it is receiving queries on multiple interfaces.

It is possible to override the default server identifier values by specifying the dhcp-server-identifier option. This option configuration is only supported at the subnet, shared network, client class, and global levels. It must not be specified at the host-reservation level. When configuring the dhcp-server-identifier option at client-class level, the class must not set the only-in-additional-list flag, because this class would not be evaluated before the server determines if the received DHCP message should be accepted for processing. Such classes are evaluated after subnet selection. See Additional Classification for details.

The following example demonstrates how to override the server identifier for a subnet:

{
"subnet4": [
    {
        "subnet": "192.0.2.0/24",
        "option-data": [
            {
                "name": "dhcp-server-identifier",
                "data": "10.2.5.76"
            }
        ],
        ...
    }
],
...
}

How the DHCPv4 Server Selects a Subnet for the Client

The DHCPv4 server differentiates among directly connected clients, clients trying to renew leases, and clients sending their messages through relays. For directly connected clients, the server checks the configuration for the interface on which the message has been received and, if the server configuration does not match any configured subnet, the message is discarded.

An optional interface parameter is available within a subnet definition to designate that a given subnet is local, i.e. reachable directly over the specified interface. For example, a server that is intended to serve a local subnet over eth0 may be configured as follows:

"Dhcp4": {
    "subnet4": [
        {
            "id": 1,
            "subnet": "192.0.2.0/24",
            "pools": [
                 {
                     "pool": "192.0.2.100 - 192.0.2.199"
                 }
             ],
            "interface": "eth0"
        }
    ],
    ...
}

Assuming that the server's interface is configured with the IPv4 address 192.0.2.3, the server only processes messages received through this interface from a directly connected client if there is a subnet configured to which this IPv4 address belongs, such as 192.0.2.0/24. The server uses this subnet to assign an IPv4 address for the client.

The rule above does not apply when the client unicasts its message, i.e. is trying to renew its lease; such a message is accepted through any interface. The renewing client sets ciaddr to the currently used IPv4 address, and the server uses this address to select the subnet for the client (in particular, to extend the lease using this address).

If the message is relayed it is accepted through any interface. The giaddr set by the relay agent is used to select the subnet for the client.

It is also possible to specify a relay IPv4 address for a given subnet. It can be used to match incoming packets into a subnet in uncommon configurations, e.g. shared networks. See Using a Specific Relay Agent for a Subnet for details.

NOTE:

NOTE:

Using a Specific Relay Agent for a Subnet

A relay must have an interface connected to the link on which the clients are being configured. Typically the relay has an IPv4 address configured on that interface, which belongs to the subnet from which the server assigns addresses. Normally, the server is able to use the IPv4 address inserted by the relay (in the giaddr field of the DHCPv4 packet) to select the appropriate subnet.

However, that is not always the case. In certain uncommon — but valid — deployments, the relay address may not match the subnet. This usually means that there is more than one subnet allocated for a given link. The two most common examples of this are long-lasting network renumbering (where both old and new address spaces are still being used) and a cable network. In a cable network, both cable modems and the devices behind them are physically connected to the same link, yet they use distinct addressing. In such a case, the DHCPv4 server needs additional information (the IPv4 address of the relay) to properly select an appropriate subnet.

The following example assumes that there is a subnet 192.0.2.0/24 that is accessible via a relay that uses 10.0.0.1 as its IPv4 address. The server is able to select this subnet for any incoming packets that come from a relay that has an address in the 192.0.2.0/24 subnet. It also selects that subnet for a relay with address 10.0.0.1.

{
  "Dhcp4": {
    "subnet4": [
        {
            "id": 1,
            "subnet": "192.0.2.0/24",
            "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
            "relay": {
                "ip-addresses": [ "10.0.0.1" ]
            }
        }
    ]
  }
}

If relay is specified, the ip-addresses parameter within it is mandatory. The ip-addresses parameter supports specifying a list of addresses.

Segregating IPv4 Clients in a Cable Network

In certain cases, it is useful to mix relay address information (introduced in Using a Specific Relay Agent for a Subnet) with client classification (explained in Client Classification). One specific example is in a cable network, where modems typically get addresses from a different subnet than all the devices connected behind them.

Let us assume that there is one Cable Modem Termination System (CMTS) with one CM MAC (a physical link that modems are connected to). We want the modems to get addresses from the 10.1.1.0/24 subnet, while everything connected behind the modems should get addresses from the 192.0.2.0/24 subnet. The CMTS that acts as a relay uses address 10.1.1.1. The following configuration can serve that situation:

"Dhcp4": {
    "subnet4": [
        {
            "id": 1,
            "subnet": "10.1.1.0/24",
            "pools": [ { "pool": "10.1.1.2 - 10.1.1.20" } ],
            "client-classes": [ "docsis3.0" ],
            "relay": {
                "ip-addresses": [ "10.1.1.1" ]
            }
        },
        {
            "id": 2,
            "subnet": "192.0.2.0/24",
            "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
            "relay": {
                "ip-addresses": [ "10.1.1.1" ]
            }
        }
    ],
    ...
}

Duplicate Addresses (DHCPDECLINE Support)

The DHCPv4 server is configured with a certain pool of addresses that it is expected to hand out to DHCPv4 clients. It is assumed that the server is authoritative and has complete jurisdiction over those addresses. However, for various reasons such as misconfiguration or a faulty client implementation that retains its address beyond the valid lifetime, there may be devices connected that use those addresses without the server's approval or knowledge.

Such an unwelcome event can be detected by legitimate clients (using ARP or ICMP Echo Request mechanisms) and reported to the DHCPv4 server using a DHCPDECLINE message. The server does a sanity check (to see whether the client declining an address really was supposed to use it) and then conducts a clean-up operation. Any DNS entries related to that address are removed, the event is logged, and hooks are triggered. After that is complete, the address is marked as declined (which indicates that it is used by an unknown entity and thus not available for assignment) and a probation time is set on it. Unless otherwise configured, the probation period lasts 24 hours; after that time, the server will recover the lease (i.e. put it back into the available state) and the address will be available for assignment again. It should be noted that if the underlying issue of a misconfigured device is not resolved, the duplicate-address scenario will repeat. If reconfigured correctly, this mechanism provides an opportunity to recover from such an event automatically, without any system administrator intervention.

To configure the decline probation period to a value other than the default, the following syntax can be used:

"Dhcp4": {
    "decline-probation-period": 3600,
    "subnet4": [
        {
            ...
        },
        ...
    ],
    ...
}

The parameter is expressed in seconds, so the example above instructs the server to recycle declined leases after one hour.

There are several statistics and hook points associated with the decline handling procedure. The lease4_decline hook point is triggered after the incoming DHCPDECLINE message has been sanitized and the server is about to decline the lease. The declined-addresses statistic is increased after the hook returns (both the global and subnet-specific variants). (See Statistics in the DHCPv4 Server and Hook Libraries for more details on DHCPv4 statistics and Kea hook points.)

Once the probation time elapses, the declined lease is recovered using the standard expired-lease reclamation procedure, with several additional steps. In particular, both declined-addresses statistics (global and subnet-specific) are decreased. At the same time, reclaimed-declined-addresses statistics (again in two variants, global and subnet-specific) are increased.

A note about statistics: The Kea server does not decrease the assigned-addresses statistics when a DHCPDECLINE is received and processed successfully. While technically a declined address is no longer assigned, the primary usage of the assigned-addresses statistic is to monitor pool utilization. Most people would forget to include declined-addresses in the calculation, and would simply use assigned-addresses/total-addresses. This would cause a bias towards under-representing pool utilization. As this has a potential to cause serious confusion, ISC decided not to decrease assigned-addresses immediately after receiving DHCPDECLINE, but to do it later when Kea recovers the address back to the available pool.

Statistics in the DHCPv4 Server

The DHCPv4 server supports the following statistics:

DHCPv4 statistics

NOTE:

NOTE:

The DHCPv4 server provides two global parameters to control the default sample limits of statistics:

For instance, to reduce the statistic-keeping overhead, set the default maximum sample count to 1 so only one sample is kept:

"Dhcp4": {
    "statistic-default-sample-count": 1,
    "subnet4": [
        {
            ...
        },
        ...
    ],
    ...
}

Statistics can be retrieved periodically to gain more insight into Kea operations. One tool that leverages that capability is ISC Stork. See Monitoring Kea With Stork for details.

Management API for the DHCPv4 Server

The management API allows the issuing of specific management commands, such as statistics retrieval, reconfiguration, or shutdown. For more details, see Management API. By default there are no sockets open; to instruct Kea to open a socket, the following entry in the configuration file can be used:

"Dhcp4": {
    "control-sockets": [
        {
            "socket-type": "unix",
            "socket-name": "/path/to/the/unix/socket"
        }
    ],
    "subnet4": [
        {
            ...
        },
        ...
    ],
    ...
}

UNIX Control Socket

Until Kea server 2.7.2 the only supported communication channel type was the UNIX stream socket with socket-type set to unix and socket-name to the file path of the UNIX/LOCAL socket.

The length of the path specified by the socket-name parameter is restricted by the maximum length for the UNIX socket name on the administrator's operating system, i.e. the size of the sun_path field in the sockaddr_un structure, decreased by 1. This value varies on different operating systems, between 91 and 107 characters. Typical values are 107 on Linux and 103 on FreeBSD.

Kea supports only one unix control socket in the "control-sockets" list.

NOTE:

Communication over the control channel is conducted using JSON structures. See the Control Channel section in the Kea Developer's Guide for more details.

The DHCPv4 server supports the following operational commands:

as described in Commands Supported by Both the DHCPv4 and DHCPv6 Servers. In addition, it supports the following statistics-related commands:

as described in Commands for Manipulating Statistics.

HTTP/HTTPS Control Socket

The socket-type must be http or https (when the type is https TLS is required). The socket-address (default 127.0.0.1) and socket-port (default 8000) specify an IP address and port to which the HTTP service will be bound.

Since Kea 2.7.5 the http-headers parameter specifies a list of extra HTTP headers to add to HTTP responses.

The trust-anchor, cert-file, key-file, and cert-required parameters specify the TLS setup for HTTP, i.e. HTTPS. If these parameters are not specified, HTTP is used. The TLS/HTTPS support in Kea is described in TLS/HTTPS Support.

Basic HTTP authentication protects against unauthorized uses of the control agent by local users. For protection against remote attackers, HTTPS and reverse proxy of Secure Connections provide stronger security.

The authentication is described in the authentication block with the mandatory type parameter, which selects the authentication. Currently only the basic HTTP authentication (type basic) is supported.

The realm authentication parameter (default kea-dhcpv4-server is used for error messages when the basic HTTP authentication is required but the client is not authorized.

When the clients authentication list is configured and not empty, basic HTTP authentication is required. Each element of the list specifies a user ID and a password. The user ID is mandatory, must not be empty, and must not contain the colon (:) character. The password is optional; when it is not specified an empty password is used.

NOTE:

To avoid exposing the user ID and/or the associated password, these values can be read from files. The syntax is extended by:

Since Kea-2.7.6 Kea supports multiple HTTP/HTTPS connections. Both IPv4 and IPv6 addresses can be used. The server will issue an error when changing the socket type from HTTP to HTTPS or from HTTPS to HTTP using the same address and port. This action is not allowed as it might introduce a security issue accidentally caused by a user mistake. A different address or port must be specified when using the "config-set" command to switch from HTTP to HTTPS or from HTTPS to HTTP. The same applies when modyfying the configuration file and then running "config-reload" command.

When files are used, they are read when the configuration is loaded, to detect configuration errors as soon as possible.

"Dhcp4": {
    "control-sockets": [
        {
            "socket-type": "https",
            "socket-address": "10.20.30.40",
            "socket-port": 8004,
            "http-headers": [
                {
                    "name": "Strict-Transport-Security",
                    "value": "max-age=31536000"
                 }
            ],
            "trust-anchor": "/path/to/the/ca-cert.pem",
            "cert-file": "/path/to/the/agent-cert.pem",
            "key-file": "/path/to/the/agent-key.pem",
            "cert-required": true,
            "authentication": {
                "type": "basic",
                "realm": "kea-dhcpv4-server",
                "clients": [
                {
                    "user": "admin",
                    "password": "1234"
                } ]
            }
        },
        {
            "socket-type": "http",
            "socket-address": "2010:30:40::50",
            "socket-port": 8004
        }
    ],
    "subnet4": [
        {
            ...
        },
        ...
    ],
    ...
}

User Contexts in IPv4

Kea allows the loading of hook libraries that can sometimes benefit from additional parameters. If such a parameter is specific to the whole library, it is typically defined as a parameter for the hook library. However, sometimes there is a need to specify parameters that are different for each pool.

See Comments and User Context for additional background regarding the user-context idea. See User Contexts in Hooks for a discussion from the hooks perspective.

User contexts can be specified at global scope; at the shared-network, subnet, pool, client-class, option-data, or definition level; and via host reservation. One other useful feature is the ability to store comments or descriptions.

Let's consider an imaginary case of devices that have colored LED lights. Depending on their location, they should glow red, blue, or green. It would be easy to write a hook library that would send specific values, maybe as a vendor option. However, the server has to have some way to specify that value for each pool. This need is addressed by user contexts. In essence, any user data can be specified in the user context as long as it is a valid JSON map. For example, the aforementioned case of LED devices could be configured in the following way:

"Dhcp4": {
    "subnet4": [
        {
        "id": 1,
        "subnet": "192.0.2.0/24",
        "pools": [
        {
            "pool": "192.0.2.10 - 192.0.2.20",
            # This is pool specific user context
            "user-context": { "color": "red" }
        }
        ],
        # This is a subnet-specific user context. Any type
        # of information can be entered here as long as it is valid JSON.
        "user-context": {
            "comment": "network on the second floor",
            "last-modified": "2017-09-04 13:32",
            "description": "you can put anything you like here",
            "phones": [ "x1234", "x2345" ],
            "devices-registered": 42,
            "billing": false
        }
    }
    ]
}

Kea does not interpret or use the user-context information; it simply stores it and makes it available to the hook libraries. It is up to each hook library to extract that information and use it. The parser translates a comment entry into a user context with the entry, which allows a comment to be attached inside the configuration itself.

Supported DHCP Standards

The following standards are currently supported in Kea:

Known RFC Violations

In principle, Kea aspires to be a reference implementation and aims to implement 100% of the RFC standards. However, in some cases there are practical aspects that prevent Kea from completely adhering to the text of all RFC documents.

DHCPv4 Server Limitations

These are the current known limitations of the Kea DHCPv4 server software. Most of them are reflections of the current stage of development and should be treated as “not yet implemented,” rather than as actual limitations. However, some of them are implications of the design choices made. Those are clearly marked as such.

Kea DHCPv4 Server Examples

A collection of simple-to-use examples for the DHCPv4 component of Kea is available with the source files, located in the doc/examples/kea4 directory.

Configuration Backend in DHCPv4

In the Kea Configuration Backend section we have described the Configuration Backend (CB) feature, its applicability, and its limitations. This section focuses on the usage of the CB with the Kea DHCPv4 server. It lists the supported parameters, describes limitations, and gives examples of DHCPv4 server configurations to take advantage of the CB. Please also refer to the corresponding section Configuration Backend in DHCPv6 for DHCPv6-specific usage of the CB.

Supported Parameters

The ultimate goal for the CB is to serve as a central configuration repository for one or multiple Kea servers connected to a database. In currently supported Kea versions, only a subset of the DHCPv4 server parameters can be configured in the database. All other parameters must be specified in the JSON configuration file, if required.

All supported parameters can be configured via libdhcp_cb_cmds.so. The general rule is that scalar global parameters are set using remote-global-parameter4-set; shared-network-specific parameters are set using remote-network4-set; and subnet-level and pool-level parameters are set using remote-subnet4-set. Whenever there is an exception to this general rule, it is highlighted in the table. Non-scalar global parameters have dedicated commands; for example, the global DHCPv4 options (option-data) are modified using remote-option4-global-set. Client classes, together with class-specific option definitions and DHCPv4 options, are configured using the remote-class4-set command.

The Configuration Sharing and Server Tags section explains the concept of shareable and non-shareable configuration elements and the limitations for sharing them between multiple servers. In the DHCP configuration (both DHCPv4 and DHCPv6), the shareable configuration elements are subnets and shared networks. Thus, they can be explicitly associated with multiple server tags. The global parameters, option definitions, and global options are non-shareable and can be associated with only one server tag. This rule does not apply to the configuration elements associated with all servers. Any configuration element associated with all servers (using the all keyword as a server tag) is used by all servers connecting to the configuration database.

The following table lists DHCPv4-specific parameters supported by the configuration backend, with an indication of the level of the hierarchy at which it is currently supported.

List of DHCPv4 parameters supported by the configuration backend

Some scalar parameters contained by top-level global maps are supported by the configuration backend.

List of DHCPv4 map parameters supported by the configuration backend

Enabling the Configuration Backend

Consider the following configuration snippet, which uses a MySQL configuration database:

{
    "Dhcp4": {
        "server-tag": "my DHCPv4 server",
        "config-control": {
            "config-databases": [
                {
                    "type": "mysql",
                    "name": "kea",
                    "user": "kea",
                    "password": "1234",
                    "host": "192.0.2.1",
                    "port": 3302
                }
            ],
            "config-fetch-wait-time": 20
        },
        "hooks-libraries": [
            {
                "library": "/usr/local/lib/kea/hooks/libdhcp_mysql.so"
            },
            {
                "library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so"
            }
        ]
    }
}

The following snippet illustrates the use of a PostgreSQL database:

{
    "Dhcp4": {
        "server-tag": "my DHCPv4 server",
        "config-control": {
            "config-databases": [
                {
                    "type": "postgresql",
                    "name": "kea",
                    "user": "kea",
                    "password": "1234",
                    "host": "192.0.2.1",
                    "port": 3302
                }
            ],
            "config-fetch-wait-time": 20
        },
        "hooks-libraries": [
            {
                "library": "/usr/local/lib/kea/hooks/libdhcp_pgsql.so"
            },
            {
                "library": "/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so"
            }
        ]
    }
}

The config-control map contains two parameters. config-databases is a list that contains one element, which includes the database type, its location, and the credentials to be used to connect to this database. (Note that the parameters specified here correspond to the database specification for the lease database backend and hosts database backend.) Currently only one database connection can be specified on the config-databases list. The server connects to this database during startup or reconfiguration, and fetches the configuration available for this server from the database. This configuration is merged into the configuration read from the configuration file.

NOTE:

Once the Kea server is configured, it starts periodically polling the database for configuration changes. The polling frequency is controlled by the config-fetch-wait-time parameter, expressed in seconds; it is the period between the time when the server completed its last poll (and possibly the local configuration update) and the time when it will begin polling again. In the example above, this period is set to 20 seconds. This means that after adding a new configuration into the database (e.g. adding a new subnet), it will take up to 20 seconds (plus the time needed to fetch and apply the new configuration) before the server starts using this subnet. The lower the config-fetch-wait-time value, the shorter the time for the server to react to incremental configuration updates in the database. On the other hand, polling the database too frequently may impact the DHCP server's performance, because the server needs to make at least one query to the database to discover any pending configuration updates. The default value of config-fetch-wait-time is 30 seconds.

The config-backend-pull command can be used to force the server to immediately poll any configuration changes from the database and avoid waiting for the next fetch cycle.

In the configuration examples above, two hook libraries are loaded. The first is a library which implements the configuration backend for a specific database type: libdhcp_mysql.so provides support for MySQL and libdhcp_pgsql.so provides support for PostgreSQL. The library loaded must match the database type specified within the config-control parameter; otherwise an error is logged when the server attempts to load its configuration, and the load fails.

The second hook library, libdhcp_cb_cmds.so, is optional. It should be loaded when the Kea server instance is to be used to manage the configuration in the database. See the libdhcp_cb_cmds.so: Configuration Backend Commands section for details.

Kea DHCPv4 Compatibility Configuration Parameters

ISC's intention is for Kea to follow the RFC documents to promote better standards compliance. However, many buggy DHCP implementations already exist that cannot be easily fixed or upgraded. Therefore, Kea provides an easy-to-use compatibility mode for broken or non-compliant clients. For that purpose, the compatibility option must be enabled to permit uncommon practices:

{
  "Dhcp4": {
    "compatibility": {
    }
  }
}

Lenient Option Parsing

By default, tuple fields defined in custom options are parsed as a set of length-value pairs.

With "lenient-option-parsing": true, if a length ever exceeded the rest of the option's buffer, previous versions of Kea returned a log message unable to parse the opaque data tuple, the buffer length is x, but the tuple length is y with x < y; this no longer occurs. Instead, the value is considered to be the rest of the buffer, or in terms of the log message above, the tuple length y becomes x.

{
  "Dhcp4": {
    "compatibility": {
      "lenient-option-parsing": true
    }
  }
}

Starting with Kea version 2.5.8, this parsing is extended to silently ignore FQDN (81) options with some invalid domain names.

Ignore DHCP Server Identifier

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 to this server or another one (and in the second case dropping the query).

{
  "Dhcp4": {
    "compatibility": {
      "ignore-dhcp-server-identifier": true
    }
  }
}

Ignore RAI Link Selection

With "ignore-rai-link-selection": true, Relay Agent Information Link 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 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.

{
  "Dhcp4": {
    "compatibility": {
      "ignore-rai-link-selection": true
    }
  }
}

Exclude First Last Addresses in /24 Subnets or Larger

The exclude-first-last-24 compatibility flag is described in Configuration of IPv4 Address Pools (when true .0 and .255 addresses are excluded from subnets with prefix length less than or equal to 24).

Address Allocation Strategies in DHCPv4

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 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 an "allocator" is responsible in Kea for finding an available address in such a case.

The Kea DHCPv4 server provides configuration parameters to select different allocators at the global, shared-network, and subnet levels. Consider the following example:

{
    "Dhcp4": {
        "allocator": "random",
        "subnet4": [
            {
                "id": 1,
                "subnet": "10.0.0.0/8",
                "allocator": "iterative"
            },
            {
                "id": 2,
                "subnet": "192.0.2.0/24"
            }
        ]
    }
}

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, while the iterative allocation will be used for the subnet with ID 1.

The following sections describe the supported allocators and their recommended uses.

Allocators Comparison

In the table below, we briefly compare the supported allocators, all of which are described in detail in later sections.

Comparison of the lease allocators supported by Kea DHCPv4

Iterative Allocator

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, 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, which causes many allocation conflicts between the servers and retransmissions by clients. A random allocation addresses this issue by dispersing the allocation order.

Random Allocator

The random allocator uses a uniform randomization function to select offered 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. 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 clients increase memory consumption by random allocation.

The following configuration snippet shows how to select the random allocator for a subnet:

{
    "Dhcp4": {
        "allocator": "random",
        "subnet4": [
            {
                "id": 1,
                "subnet": "10.0.0.0/8",
                "allocator": "random"
            }
        ]
    }
}

Free Lease Queue Allocator

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 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 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 any allocated leases and adding released or reclaimed ones.

The following configuration snippet shows how to select the FLQ allocator for a subnet:

{
    "Dhcp4": {
        "subnet4": [
            {
                "id": 1,
                "subnet": "192.0.2.0/24",
                "allocator": "flq"
            }
        ]
    }
}

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 libdhcp_subnet_cmds.so. This allocator increases memory consumption to hold the list of free leases, proportional to the total size of the address pools for which the FLQ 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 free lease queue; expired leases are not considered free by the allocator until they are reclaimed by the server. See Lease Reclamation for more details about the lease reclamation process.

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 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.

WARNING:

Starting and Stopping the DHCPv6 Server

It is recommended that the Kea DHCPv6 server be started and stopped using keactrl (described in Managing Kea with keactrl); however, it is also possible to run the server directly via the kea-dhcp6 command, which accepts the following command-line switches:

# from installation using libkea-process.so
$ strings ${prefix}/lib/libkea-process.so | sed -n 's/;;;; //p'
# from sources using libkea-process.so
$ strings src/lib/process/.libs/libkea-process.so | sed -n 's/;;;; //p'
# from sources using libkea-process.a
$ strings src/lib/process/.libs/libkea-process.a | sed -n 's/;;;; //p'
# from sources using libcfgrpt.a
$ strings src/lib/process/cfgrpt/.libs/libcfgrpt.a | sed -n 's/;;;; //p'

On startup, the server detects available network interfaces and attempts to open UDP sockets on all interfaces listed in the configuration file. Since the DHCPv6 server opens privileged ports, it requires root access; this daemon must be run as root.

During startup, the server attempts to create a PID file of the form: [pidfile_dir]/[conf name].kea-dhcp6.pid, where:

If the file already exists and contains the PID of a live process, the server issues a DHCP6_ALREADY_RUNNING log message and exits. It is possible, though unlikely, that the file is a remnant of a system crash and the process to which the PID belongs is unrelated to Kea. In such a case, it would be necessary to manually delete the PID file.

The server can be stopped using the kill command. When running in a console, the server can also be shut down by pressing Ctrl-c. Kea detects the key combination and shuts down gracefully.

The reconfiguration of each Kea server is triggered by the SIGHUP signal. When a server receives the SIGHUP signal it rereads its configuration file and, 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 is no longer providing any service: a working configuration must be loaded as soon as possible.

DHCPv6 Server Configuration

Introduction

This section explains how to configure the Kea DHCPv6 server using a configuration file.

Before DHCPv6 is started, its configuration file must be created. The basic configuration is as follows:

{
# DHCPv6 configuration starts on the next line
"Dhcp6": {
# First we set up global values
    "valid-lifetime": 4000,
    "renew-timer": 1000,
    "rebind-timer": 2000,
    "preferred-lifetime": 3000,
# Next we set up the interfaces to be used by the server.
    "interfaces-config": {
        "interfaces": [ "eth0" ]
    },
# And we specify the type of lease database
    "lease-database": {
        "type": "memfile",
        "persist": true,
        "name": "/var/lib/kea/dhcp6.leases"
    },
# Finally, we list the subnets from which we will be leasing addresses.
    "subnet6": [
        {
            "id": 1,
            "subnet": "2001:db8:1::/64",
            "pools": [
                {
                    "pool": "2001:db8:1::1-2001:db8:1::ffff"
                }
             ]
        }
    ]
# DHCPv6 configuration ends with the next line
}
}

The following paragraphs provide a brief overview of the parameters in the above example, along with their format. Subsequent sections of this chapter go into much greater detail for these and other parameters.

The lines starting with a hash (#) are comments and are ignored by the server; they do not impact its operation in any way.

The configuration starts in the first line with the initial opening curly bracket (or brace). Each configuration must contain an object specifying the configuration of the Kea module using it. In the example above, this object is called Dhcp6.

The Dhcp6 configuration starts with the "Dhcp6": { line and ends with the corresponding closing brace (in the above example, the brace after the last comment). Everything defined between those lines is considered to be the Dhcp6 configuration.

In general, the order in which those parameters appear does not matter, but there are two caveats. The first one is that the configuration file must be well-formed JSON, meaning that the parameters for any given scope must be separated by a comma, and there must not be a comma after the last parameter. When reordering a configuration file, moving a parameter to or from the last position in a given scope may also require moving the comma. The second caveat is that it is uncommon — although legal JSON — to repeat the same parameter multiple times. If that happens, the last occurrence of a given parameter in a given scope is used, while all previous instances are ignored. This is unlikely to cause any confusion as there are no real-life reasons to keep multiple copies of the same parameter in the configuration file.

The first few DHCPv6 configuration elements define some global parameters. valid-lifetime defines how long the addresses (leases) given out by the server are valid; the default is for a client to be allowed to use a given address for 4000 seconds. (Note that integer numbers are specified as is, without any quotes around them.) The address will become deprecated in 3000 seconds, i.e. clients are allowed to keep old connections, but cannot use this address to create new connections. renew-timer and rebind-timer are values (also in seconds) that define T1 and T2 timers, which govern when the client begins the renewal and rebind procedures.

The interfaces-config map specifies the network interfaces on which the server should listen to DHCP messages. The interfaces parameter specifies a list of network interfaces on which the server should listen. Lists are opened and closed with square brackets, with elements separated by commas. To listen on two interfaces, the interfaces-config element should look like this:

{
"interfaces-config": {
    "interfaces": [ "eth0", "eth1" ]
},
...
}

The next lines define the lease database, the place where the server stores its lease information. This particular example tells the server to use memfile, which is the simplest and fastest database backend. It uses an in-memory database and stores leases on disk in a CSV (comma-separated values) file. This is a very simple configuration example; usually the lease database configuration is more extensive and contains additional parameters. Note that lease-database is an object and opens up a new scope, using an opening brace. Its parameters (just one in this example: type) follow. If there were more than one, they would be separated by commas. This scope is closed with a closing brace. As more parameters for the Dhcp6 definition follow, a trailing comma is present.

Finally, we need to define a list of IPv6 subnets. This is the most important DHCPv6 configuration structure, as the server uses that information to process clients' requests. It defines all subnets from which the server is expected to receive DHCP requests. The subnets are specified with the subnet6 parameter. It is a list, so it starts and ends with square brackets. Each subnet definition in the list has several attributes associated with it, so it is a structure and is opened and closed with braces. At a minimum, a subnet definition must have at least two parameters: subnet, which defines the whole subnet; and pools, which is a list of dynamically allocated pools that are governed by the DHCP server.

The example contains a single subnet. If more than one were defined, additional elements in the subnet6 parameter would be specified and separated by commas. For example, to define two subnets, the following syntax would be used:

{
"subnet6": [
    {
        "id": 1,
        "pools": [ { "pool": "2001:db8:1::/112" } ],
        "subnet": "2001:db8:1::/64"
    },
    {
        "id": 2,
        "pools": [ { "pool": "2001:db8:2::1-2001:db8:2::ffff" } ],
        "subnet": "2001:db8:2::/64"
    }
],
...
}

Note that indentation is optional and is used for aesthetic purposes only. In some cases it may be preferable to use more compact notation.

After all the parameters have been specified, there are two contexts open: global and Dhcp6; thus, two closing curly brackets must be used to close them.

Lease Storage

All leases issued by the server are stored in the lease database. There are three database backends available: memfile (the default), MySQL, PostgreSQL.

Memfile - Basic Storage for Leases

The server is able to store lease data in different repositories. Larger deployments may elect to store leases in a database; Lease Database Configuration describes this option. In typical smaller deployments, though, the server stores lease information in a CSV file rather than a database. As well as requiring less administration, an advantage of using a file for storage is that it eliminates a dependency on third-party database software.

The configuration of the memfile backend is controlled through the Dhcp6/lease-database parameters. The type parameter is mandatory and specifies which storage for leases the server should use, through the "memfile" value. The following list gives additional optional parameters that can be used to configure the memfile backend.

NOTE:

An example configuration of the memfile backend is presented below:

"Dhcp6": {
    "lease-database": {
        "type": "memfile",
        "persist": true,
        "name": "kea-leases6.csv",
        "lfc-interval": 1800,
        "max-row-errors": 100
    }
}

This configuration selects kea-leases6.csv as the storage file for lease information and enables persistence (writing lease updates to this file). It also configures the backend to perform a periodic cleanup of the lease file every 1800 seconds (30 minutes) and sets the maximum number of row errors to 100.

Why Is Lease File Cleanup Necessary?

It is important to know how the lease file contents are organized to understand why the periodic lease file cleanup is needed. Every time the server updates a lease or creates a new lease for a client, the new lease information must be recorded in the lease file. For performance reasons, the server does not update the existing client's lease in the file, as this would potentially require rewriting the entire file. Instead, it simply appends the new lease information to the end of the file; the previous lease entries for the client are not removed. When the server loads leases from the lease file, e.g. at server startup, it assumes that the latest lease entry for the client is the valid one. Previous entries are discarded, meaning that the server can reconstruct accurate information about the leases even though there may be many lease entries for each client. However, storing many entries for each client results in a bloated lease file and impairs the performance of the server's startup and reconfiguration, as it needs to process a larger number of lease entries.

Lease file cleanup (LFC) removes all previous entries for each client and leaves only the latest ones. The interval at which the cleanup is performed is configurable, and it should be selected according to the frequency of lease renewals initiated by the clients. The more frequent the renewals, the smaller the value of lfc-interval should be. Note, however, that the LFC takes time and thus it is possible (although unlikely) that, if the lfc-interval is too short, a new cleanup may be started while the previous one is still running. The server would recover from this by skipping the new cleanup when it detected that the previous cleanup was still in progress, but it implies that the actual cleanups will be triggered more rarely than the configured interval. Moreover, triggering a new cleanup adds overhead to the server, which is not able to respond to new requests for a short period of time when the new cleanup process is spawned. Therefore, it is recommended that the lfc-interval value be selected in a way that allows the LFC to complete the cleanup before a new cleanup is triggered.

Lease file cleanup is performed by a separate process (in the background) to avoid a performance impact on the server process. To avoid conflicts between two processes using the same lease files, the LFC process starts with Kea opening a new lease file; the actual LFC process operates on the lease file that is no longer used by the server. There are also other files created as a side effect of the lease file cleanup. The detailed description of the LFC process is located later in this Kea Administrator's Reference Manual: The LFC Process.

Lease Database Configuration

NOTE:

NOTE:

Lease database configuration is controlled through the Dhcp6/lease-database parameters. The database type must be set to memfile, mysql or postgresql, e.g.:

"Dhcp6": { "lease-database": { "type": "mysql", ... }, ... }

Next, the name of the database to hold the leases must be set; this is the name used when the database was created (see First-Time Creation of the MySQL Database or First-Time Creation of the PostgreSQL Database).

For MySQL or PostgreSQL:

"Dhcp6": { "lease-database": { "name": "database-name" , ... }, ... }

If the database is located on a different system from the DHCPv6 server, the database host name must also be specified:

"Dhcp6": { "lease-database": { "host": "remote-host-name", ... }, ... }

Normally, the database is on the same machine as the DHCPv6 server. In this case, set the value to the empty string:

"Dhcp6": { "lease-database": { "host" : "", ... }, ... }

Should the database use a port other than the default, it may be specified as well:

"Dhcp6": { "lease-database": { "port" : 12345, ... }, ... }

Should the database be located on a different system, the administrator may need to specify a longer interval for the connection timeout:

"Dhcp6": { "lease-database": { "connect-timeout" : timeout-in-seconds, ... }, ... }

The default value of five seconds should be more than adequate for local connections. If a timeout is given, though, it should be an integer greater than zero.

The maximum number of times the server automatically attempts to reconnect to the lease database after connectivity has been lost may be specified:

"Dhcp6": { "lease-database": { "max-reconnect-tries" : number-of-tries, ... }, ... }

If the server is unable to reconnect to the database after making the maximum number of attempts, the server will exit. A value of 0 (the default) disables automatic recovery and the server will exit immediately upon detecting a loss of connectivity (MySQL and PostgreSQL only).

The number of milliseconds the server waits between attempts to reconnect to the lease database after connectivity has been lost may also be specified:

"Dhcp6": { "lease-database": { "reconnect-wait-time" : number-of-milliseconds, ... }, ... }

The default value for MySQL and PostgreSQL is 0, which disables automatic recovery and causes the server to exit immediately upon detecting the loss of connectivity.

"Dhcp6": { "lease-database": { "on-fail" : "stop-retry-exit", ... }, ... }

The possible values are:

NOTE:

"Dhcp6": { "lease-database": { "retry-on-startup" : true, ... }, ... }

During server startup, the inability to connect to any of the configured backends is considered fatal only if retry-on-startup is set to false (the default). A fatal error is logged and the server exits, based on the idea that the configuration should be valid at startup. Exiting to the operating system allows nanny scripts to detect the problem. If retry-on-startup is set to true, the server starts reconnection attempts even at server startup or on reconfigure events, and honors the action specified in the on-fail parameter.

The host parameter is used by the MySQL and PostgreSQL backends.

Finally, the credentials of the account under which the server will access the database should be set:

"Dhcp6": {
    "lease-database": {
        "user": "user-name",
        "password": "1234",
        ...
    },
    ...
}

If there is no password to the account, set the password to the empty string "". (This is the default.)

Tuning Database Timeouts

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 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 write timeouts. Kea's corresponding read-timeout and write-timeout configuration parameters specify the timeouts in seconds. For example:

"Dhcp6": { "lease-database": { "read-timeout" : 10, "write-timeout": 20, ... }, ... }

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 indefinitely for the completion of the read and write operations.

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 database type causes a configuration error.

To set a timeout in seconds for PostgreSQL, use the tcp-user-timeout parameter. For example:

"Dhcp6": { "lease-database": { "tcp-user-timeout" : 10, ... }, ... }

Specifying this parameter for other backend types causes a configuration error.

NOTE:

Since Kea.2.7.4, the libdhcp_mysql.so hook library must be loaded in order to store leases in the MySQL Lease Database Backend. Specify the lease backend hook library location:

"Dhcp6": { "hooks-libraries": [
    {
        // the MySQL lease backend hook library required for lease storage.
        "library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
    }, ... ], ... }

Since Kea.2.7.4, the libdhcp_pgsql.so hook library must be loaded in order to store leases in the PostgreSQL Lease Database Backend. Specify the lease backend hook library location.

"Dhcp6": { "hooks-libraries": [
    {
        // the PostgreSQL lease backend hook library required for lease storage.
        "library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
    }, ... ], ... }

Hosts Storage

Kea is also able to store information about host reservations in the database. The hosts database configuration uses the same syntax as the lease database. In fact, the Kea server opens independent connections for each purpose, be it lease or hosts information, which gives the most flexibility. Kea can keep leases and host reservations separately, but can also point to the same database. Currently the supported hosts database types are MySQL and PostgreSQL.

The following configuration can be used to configure a connection to MySQL:

"Dhcp6": {
    "hosts-database": {
        "type": "mysql",
        "name": "kea",
        "user": "kea",
        "password": "1234",
        "host": "localhost",
        "port": 3306
    }
}

Depending on the database configuration, many of the parameters may be optional.

Please note that usage of hosts storage is optional. A user can define all host reservations in the configuration file, and that is the recommended way if the number of reservations is small. However, when the number of reservations grows, it is more convenient to use host storage. Please note that both storage methods (the configuration file and one of the supported databases) can be used together. If hosts are defined in both places, the definitions from the configuration file are checked first and external storage is checked later, if necessary.

Host information can be placed in multiple stores. Operations are performed on the stores in the order they are defined in the configuration file, although this leads to a restriction in ordering in the case of a host reservation addition; read-only stores must be configured after a (required) read-write store, or the addition will fail.

NOTE:

DHCPv6 Hosts Database Configuration

Hosts database configuration is controlled through the Dhcp6/hosts-database parameters. If enabled, the type of database must be set to mysql or postgresql.

"Dhcp6": { "hosts-database": { "type": "mysql", ... }, ... }

Next, the name of the database to hold the reservations must be set; this is the name used when the lease database was created (see Supported Backends for instructions on how to set up the desired database type):

"Dhcp6": { "hosts-database": { "name": "database-name" , ... }, ... }

If the database is located on a different system than the DHCPv6 server, the database host name must also be specified:

"Dhcp6": { "hosts-database": { "host": remote-host-name, ... }, ... }

Normally, the database is on the same machine as the DHCPv6 server. In this case, set the value to the empty string:

"Dhcp6": { "hosts-database": { "host" : "", ... }, ... }

Should the database use a port different than the default, it may be specified as well:

"Dhcp6": { "hosts-database": { "port" : 12345, ... }, ... }

The maximum number of times the server automatically attempts to reconnect to the host database after connectivity has been lost may be specified:

"Dhcp6": { "hosts-database": { "max-reconnect-tries" : number-of-tries, ... }, ... }

If the server is unable to reconnect to the database after making the maximum number of attempts, the server will exit. A value of 0 (the default) disables automatic recovery and the server will exit immediately upon detecting a loss of connectivity (MySQL and PostgreSQL only).

The number of milliseconds the server waits between attempts to reconnect to the host database after connectivity has been lost may also be specified:

"Dhcp6": { "hosts-database": { "reconnect-wait-time" : number-of-milliseconds, ... }, ... }

The default value for MySQL and PostgreSQL is 0, which disables automatic recovery and causes the server to exit immediately upon detecting the loss of connectivity.

"Dhcp6": { "hosts-database": { "on-fail" : "stop-retry-exit", ... }, ... }

The possible values are:

NOTE:

"Dhcp6": { "hosts-database": { "retry-on-startup" : true, ... }, ... }

During server startup, the inability to connect to any of the configured backends is considered fatal only if retry-on-startup is set to false (the default). A fatal error is logged and the server exits, based on the idea that the configuration should be valid at startup. Exiting to the operating system allows nanny scripts to detect the problem. If retry-on-startup is set to true, the server starts reconnection attempts even at server startup or on reconfigure events, and honors the action specified in the on-fail parameter.

Finally, the credentials of the account under which the server will access the database should be set:

"Dhcp6": {
    "hosts-database": {
        "user": "user-name",
        "password": "1234",
        ...
    },
    ...
}

If there is no password to the account, set the password to the empty string "". (This is the default.)

The multiple-storage extension uses a similar syntax; a configuration is placed into a hosts-databases list instead of into a hosts-database entry, as in:

"Dhcp6": { "hosts-databases": [ { "type": "mysql", ... }, ... ], ... }

If the same host is configured both in-file and in-database, Kea does not issue a warning, as it would if both were specified in the same data source. Instead, the host configured in-file has priority over the one configured in-database.

Using Read-Only Databases for Host Reservations with DHCPv6

In some deployments, the user whose name is specified in the database backend configuration may not have write privileges to the database. This is often required by the policy within a given network to secure the data from being unintentionally modified. In many cases administrators have deployed inventory databases, which contain substantially more information about the hosts than just the static reservations assigned to them. The inventory database can be used to create a view of a Kea hosts database and such a view is often read-only.

Kea host-database backends operate with an implicit configuration to both read from and write to the database. If the user does not have write access to the host database, the backend will fail to start and the server will refuse to start (or reconfigure). However, if access to a read-only host database is required for retrieving reservations for clients and/or assigning specific addresses and options, it is possible to explicitly configure Kea to start in "read-only" mode. This is controlled by the readonly boolean parameter as follows:

"Dhcp6": { "hosts-database": { "readonly": true, ... }, ... }

Setting this parameter to false configures the database backend to operate in "read-write" mode, which is also the default configuration if the parameter is not specified.

NOTE:

Since Kea.2.7.4, the libdhcp_mysql.so hook library must be loaded in order to store host reservations in the MySQL Host Database Backend. Specify the lease backend hook library location:

"Dhcp6": { "hooks-libraries": [
    {
        // the MySQL host backend hook library required for host storage.
        "library": "/opt/lib/kea/hooks/libdhcp_mysql.so"
    }, ... ], ... }

Since Kea.2.7.4, the libdhcp_pgsql.so hook library must be loaded in order to store host reservations in the PostgreSQL Host Database Backend. Specify the lease backend hook library location.

"Dhcp6": { "hooks-libraries": [
    {
        // the PostgreSQL host backend hook library required for host storage.
        "library": "/opt/lib/kea/hooks/libdhcp_pgsql.so"
    }, ... ], ... }

Tuning Database Timeouts for Hosts Storage

See Tuning Database Timeouts.

Interface Configuration

The DHCPv6 server must be configured to listen on specific network interfaces. The simplest network interface configuration tells the server to listen on all available interfaces:

"Dhcp6": {
    "interfaces-config": {
        "interfaces": [ "*" ]
    },
    ...
}

The asterisk plays the role of a wildcard and means "listen on all interfaces." However, it is usually a good idea to explicitly specify interface names:

"Dhcp6": {
    "interfaces-config": {
        "interfaces": [ "eth1", "eth3" ]
    },
    ...
}

It is possible to use an interface wildcard (*) concurrently with explicit interface names:

"Dhcp6": {
    "interfaces-config": {
        "interfaces": [ "eth1", "eth3", "*" ]
    },
    ...
}

This format should only be used when it is desired to temporarily override a list of interface names and listen on all interfaces.

As with the DHCPv4 server, binding to specific addresses and disabling re-detection of interfaces are supported. But dhcp-socket-type is not supported, because DHCPv6 uses only UDP/IPv6 sockets. The following example shows how to disable interface detection:

"Dhcp6": {
    "interfaces-config": {
        "interfaces": [ "eth1", "eth3" ],
        "re-detect": false
    },
    ...
}

The loopback interfaces (i.e. the lo or lo0 interface) are not configured by default, unless explicitly mentioned in the configuration. Note that Kea requires a link-local address (which does not exist on all systems) or a specified unicast address, as in:

"Dhcp6": {
    "interfaces-config": {
        "interfaces": [ "enp0s2/2001:db8::1234:abcd" ]
    },
    ...
}

Kea binds the service sockets for each interface on startup. If another process is already using a port, then Kea logs the message and suppresses an error. DHCP service runs, but it is unavailable on some interfaces.

The "service-sockets-require-all" option makes Kea require all sockets to be successfully bound. If any opening fails, Kea interrupts the initialization and exits with a non-zero status. (Default is false).

"Dhcp6": {
    "interfaces-config": {
        "interfaces": [ "eth1", "eth3" ],
        "service-sockets-require-all": true
    },
    ...
}

Sometimes, immediate interruption isn't a good choice. The port can be unavailable only temporary. In this case, retrying the opening may resolve the problem. Kea provides two options to specify the retrying: service-sockets-max-retries and service-sockets-retry-wait-time.

The first defines a maximal number of retries that Kea makes to open a socket. The zero value (default) means that the Kea doesn't retry the process.

The second defines a wait time (in milliseconds) between attempts. The default value is 5000 (5 seconds).

"Dhcp6": {
    "interfaces-config": {
        "interfaces": [ "eth1", "eth3" ],
        "service-sockets-max-retries": 5,
        "service-sockets-retry-wait-time": 5000
    },
    ...
}

If "service-sockets-max-retries" is non-zero and "service-sockets-require-all" is false, then Kea retries the opening (if needed) but does not fail if any socket is still not opened.

IPv6 Subnet Identifier

The subnet identifier (subnet ID) is a unique number associated with a particular subnet. In principle, it is used to associate clients' leases with their respective subnets. The server configuration must contain unique and stable identifiers for all subnets.

NOTE:

The following configuration assigns the specified subnet identifier to a newly configured subnet:

"Dhcp6": {
    "subnet6": [
        {
            "subnet": "2001:db8:1::/64",
            "id": 1024,
            ...
        }
    ]
}

IPv6 Subnet Prefix

The subnet prefix is the second way to identify a subnet. Kea can accept non-canonical subnet addresses; for instance, this configuration is accepted:

"Dhcp6": {
   "subnet6": [
       {
            "subnet": "2001:db8:1::1/64",
            ...
       }
    ]
}

This works even if there is another subnet with the "2001:db8:1::/64" prefix; only the textual form of subnets are compared to avoid duplicates.

NOTE:

Unicast Traffic Support

When the DHCPv6 server starts, by default it listens to the DHCP traffic sent to multicast address ff02::1:2 on each interface that it is configured to listen on (see Interface Configuration). In some cases it is useful to configure a server to handle incoming traffic sent to global unicast addresses as well; the most common reason for this is to have relays send their traffic to the server directly. To configure the server to listen on a specific unicast address, add a slash (/) after the interface name, followed by the global unicast address on which the server should listen. The server will listen to this address in addition to normal link-local binding and listening on the ff02::1:2 address. The sample configuration below shows how to listen on 2001:db8::1 (a global address) configured on the eth1 interface.

"Dhcp6": {
    "interfaces-config": {
        "interfaces": [ "eth1/2001:db8::1" ]
    },
    "option-data": [
        {
            "name": "unicast",
            "data": "2001:db8::1"
        } ],
    ...
}

This configuration will cause the server to listen on eth1 on the link-local address, the multicast group (ff02::1:2), and 2001:db8::1.

Usually, unicast support is associated with a server unicast option which allows clients to send unicast messages to the server. The example above includes a server unicast option specification which causes the client to send messages to the specified unicast address.

It is possible to mix interface names, wildcards, and interface names/addresses in the list of interfaces. It is not possible, however, to specify more than one unicast address on a given interface.

Care should be taken to specify proper unicast addresses, as the server will attempt to bind to the addresses specified without any additional checks. This approach was selected intentionally, to allow the software to communicate over uncommon addresses if so desired.

Configuration of IPv6 Address Pools

The main role of a DHCPv6 server is address assignment. For this, the server must be configured with at least one subnet and one pool of dynamic addresses to be managed. For example, assume that the server is connected to a network segment that uses the 2001:db8:1::/64 prefix. The administrator of that network decides that addresses from the range 2001:db8:1::1 to 2001:db8:1::ffff are going to be managed by the DHCPv6 server. Such a configuration can be achieved in the following way:

"Dhcp6": {
    "subnet6": [
       {
           "subnet": "2001:db8:1::/64",
           "pools": [
               {
                   "pool": "2001:db8:1::1-2001:db8:1::ffff"
               }
           ],
           ...
       }
    ]
}

Note that subnet is defined as a simple string, but the pools parameter is actually a list of pools; for this reason, the pool definition is enclosed in square brackets, even though only one range of addresses is specified.

Each pool is a structure that contains the parameters that describe a single pool. Currently there is only one parameter, pool, which gives the range of addresses in the pool.

It is possible to define more than one pool in a subnet; continuing the 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. 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:

"Dhcp6": {
    "subnet6": [
    {
        "subnet": "2001:db8:1::/64",
        "pools": [
            { "pool": "2001:db8:1::1-2001:db8:1::ffff" },
            { "pool": "2001:db8:1:05::/80" }
        ],
        ...
    }
    ]
}

White space in pool definitions is ignored, so spaces before and after the hyphen are optional. They can be used to improve readability.

The number of pools is not limited, but for performance reasons it is recommended to use as few as possible.

The server may be configured to serve more than one subnet. To add a second subnet, use a command similar to the following:

"Dhcp6": {
    "subnet6": [
    {
        "id": 1,
        "subnet": "2001:db8:1::/64",
        "pools": [
            { "pool": "2001:db8:1::1-2001:db8:1::ffff" }
        ]
    },
    {
        "id": 2,
        "subnet": "2001:db8:2::/64",
        "pools": [
            { "pool": "2001:db8:2::/64" }
        ]
    },
    ...
    ]
}

In this example, we allow the server to dynamically assign all addresses available in the whole subnet. Although rather wasteful, it is certainly a valid configuration to dedicate the whole /64 subnet for that purpose. Note that the Kea server does not preallocate the leases, so there is no danger in using gigantic address pools.

When configuring a DHCPv6 server using prefix/length notation, please pay attention to the boundary values. When specifying that the server can use a given pool, it is also able to allocate the first (typically a network address) address from that pool. For example, for pool 2001:db8:2::/64, the 2001:db8:2:: address may be assigned as well. To avoid this, use the min-max notation.

Subnet and Prefix Delegation Pools

Subnets may also be configured to delegate prefixes, as defined in RFC 8415, section 6.3. A subnet may have one or more prefix delegation pools. Each pool has a prefixed address, which is specified as a prefix (prefix) and a prefix length (prefix-len), as well as a delegated prefix length (delegated-len). The delegated length must not be shorter than (i.e. it must be numerically greater than or equal to) the prefix length. If both the delegated and prefix lengths are equal, the server will be able to delegate only one prefix. The delegated prefix does not have to match the subnet prefix.

Below is a sample subnet configuration which enables prefix delegation for the subnet:

"Dhcp6": {
    "subnet6": [
        {
            "id": 1,
            "subnet": "2001:d8b:1::/64",
            "pd-pools": [
                {
                    "prefix": "3000:1::",
                    "prefix-len": 64,
                    "delegated-len": 96
                }
            ]
        }
    ],
    ...
}

Prefix Exclude Option

For each delegated prefix, the delegating router may choose to exclude a single prefix out of the delegated prefix as specified in RFC 6603. The requesting router must not assign the excluded prefix to any of its downstream interfaces. The excluded prefix is intended to be used on a link through which the delegating router exchanges DHCPv6 messages with the requesting router. The configuration example below demonstrates how to specify an excluded prefix within a prefix pool definition. The excluded prefix 2001:db8:1:8000:cafe:80::/72 will be sent to a requesting router which includes the Prefix Exclude option in the Option Request option (ORO), and which is delegated a prefix from this pool.

"Dhcp6": {
    "subnet6": [
        {
            "id": 1,
            "subnet": "2001:db8:1::/48",
            "pd-pools": [
                {
                    "prefix": "2001:db8:1:8000::",
                    "prefix-len": 56,
                    "delegated-len": 64,
                    "excluded-prefix": "2001:db8:1:8000:cafe:80::",
                    "excluded-prefix-len": 72
                }
            ]
        }
    ]
}

NOTE:

Standard DHCPv6 Options

One of the major features of the DHCPv6 server is the ability to provide configuration options to clients. Although there are several options that require special behavior, most options are sent by the server only if the client explicitly requests them. The following example shows how to configure the addresses of DNS servers, one of the most frequently used options. Options specified in this way are considered global and apply to all configured subnets.

"Dhcp6": {
    "option-data": [
        {
           "name": "dns-servers",
           "code": 23,
           "space": "dhcp6",
           "csv-format": true,
           "data": "2001:db8::cafe, 2001:db8::babe"
        },
        ...
    ]
}

The option-data line creates a new entry in the option-data table. This table contains information on all global options that the server is supposed to configure in all subnets. The name line specifies the option name. (For a complete list of currently supported names, see List of standard DHCPv6 options configurable by an administrator.) The next line specifies the option code, which must match one of the values from that list. The line beginning with space specifies the option space, which must always be set to dhcp6 as these are standard DHCPv6 options. For other name spaces, including custom option spaces, see Nested DHCPv6 Options (Custom Option Spaces). The following line specifies the format in which the data will be entered; use of CSV (comma-separated values) is recommended. Finally, the data line gives the actual value to be sent to clients. The data parameter is specified as normal text, with values separated by commas if more than one value is allowed.

Options can also be configured as hexadecimal values. If csv-format is set to false, the option data must be specified as a hexadecimal string. The following commands configure the dns-servers option for all subnets with the addresses 2001:db8:1::cafe and 2001:db8:1::babe.

"Dhcp6": {
    "option-data": [
        {
           "name": "dns-servers",
           "code": 23,
           "space": "dhcp6",
           "csv-format": false,
           "data": "20 01 0D B8 00 01 00 00 00 00 00 00 00 00 CA FE \
                    20 01 0D B8 00 01 00 00 00 00 00 00 00 00 BA BE"
        },
        ...
    ]
}

NOTE:

Kea supports the following formats when specifying hexadecimal data:

Care should be taken to use proper encoding when using hexadecimal format; Kea's ability to validate data correctness in hexadecimal is limited.

It is also possible to specify data for binary options as a single-quoted text string within double quotes, as shown (note that csv-format must be set to false):

"Dhcp6": {
    "option-data": [
        {
            "name": "subscriber-id",
            "code": 38,
            "space": "dhcp6",
            "csv-format": false,
            "data": "'convert this text to binary'"
        },
        ...
    ],
    ...
}

Most of the parameters in the option-data structure are optional and can be omitted in some circumstances, as discussed in Unspecified Parameters for DHCPv6 Option Configuration. Only one of name or code is required; it is not necessary to specify both. Space has a default value of dhcp6, so this can be skipped as well if a regular (not encapsulated) DHCPv6 option is defined. Finally, csv-format defaults to true, so it too can be skipped, unless the option value is specified as hexstring. Therefore, the above example can be simplified to:

"Dhcp6": {
    "option-data": [
        {
           "name": "dns-servers",
           "data": "2001:db8::cafe, 2001:db8::babe"
        },
        ...
    ]
}

Defined options are added to the response when the client requests them, as well as any options required by a protocol. An administrator can also specify that an option is always sent, even if a client did not specifically request it. To enforce the addition of a particular option, set the always-send flag to true, as in:

"Dhcp6": {
    "option-data": [
        {
           "name": "dns-servers",
           "data": "2001:db8::cafe, 2001:db8::babe",
           "always-send": true
        },
        ...
    ]
}

The effect is the same as if the client added the option code in the Option Request Option (or its equivalent for vendor options), as in:

"Dhcp6": {
    "option-data": [
        {
           "name": "dns-servers",
           "data": "2001:db8::cafe, 2001:db8::babe",
           "always-send": true
        },
        ...
    ],
    "subnet6": [
        {
           "subnet": "2001:db8:1::/64",
           "option-data": [
               {
                   "name": "dns-servers",
                   "data": "2001:db8:1::cafe, 2001:db8:1::babe"
               },
               ...
           ],
           ...
        },
        ...
    ],
    ...
}

In the example above, the dns-servers option respects the global always-send flag and is always added to responses, but for subnet 2001:db8:1::/64, the value is taken from the subnet-level option data specification.

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):

"Dhcp6": {
    "option-data": [
        {
           "name": "dns-servers",
           "data": "2001:db8::cafe, 2001:db8::babe"
        },
        ...
    ],
    "subnet6": [
        {
           "subnet": "2001:db8:1::/64",
           "option-data": [
               {
                   "name": "dns-servers",
                   "never-send": true
               },
               ...
           ],
           ...
        },
        ...
    ],
    ...
}

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.

NOTE:

NOTE:

It is possible to override options on a per-subnet basis. If clients connected to most subnets are expected to get the same values of a given option, administrators should use global options; it is possible to override specific values for a small number of subnets. On the other hand, if different values are used in each subnet, it does not make sense to specify global option values; rather, only subnet-specific ones should be set.

The following commands override the global dns-servers option for a particular subnet, setting a single DNS server with address 2001:db8:1::3.

"Dhcp6": {
    "subnet6": [
        {
            "option-data": [
                {
                    "name": "dns-servers",
                    "code": 23,
                    "space": "dhcp6",
                    "csv-format": true,
                    "data": "2001:db8:1::3"
                },
                ...
            ],
            ...
        },
        ...
    ],
    ...
}

In some cases it is useful to associate some options with an address or prefix pool from which a client is assigned a lease. Pool-specific option values override subnet-specific and global option values. If the client is assigned multiple leases from different pools, the server assigns options from all pools from which the leases have been obtained. However, if the particular option is specified in multiple pools from which the client obtains the leases, only one instance of this option is handed out to the client. The server's administrator must not try to prioritize assignment of pool-specific options by trying to order pool declarations in the server configuration.

The following configuration snippet demonstrates how to specify the dns-servers option, which will be assigned to a client only if the client obtains an address from the given pool:

"Dhcp6": {
    "subnet6": [
        {
            "pools": [
                {
                    "pool": "2001:db8:1::100-2001:db8:1::300",
                    "option-data": [
                        {
                            "name": "dns-servers",
                            "data": "2001:db8:1::10"
                        }
                    ]
                }
            ]
        },
        ...
    ],
    ...
}

Options can also be specified in class or host-reservation scope. The current Kea options precedence order is (from most important to least): host reservation, pool, subnet, shared network, class, global.

NOTE:

When a data field is a string and that string contains the comma (,; U+002C) character, the comma must be escaped with two backslashes (\\,; U+005C). This double escape is required because both the routine splitting of CSV data into fields and JSON use the same escape character; a single escape (\,) would make the JSON invalid. For example, the string "EST5EDT4,M3.2.0/02:00,M11.1.0/02:00" must be represented as:

"Dhcp6": {
    "subnet6": [
        {
            "pools": [
                {
                    "option-data": [
                        {
                            "name": "new-posix-timezone",
                            "data": "EST5EDT4\\,M3.2.0/02:00\\,M11.1.0/02:00"
                        }
                    ]
                },
                ...
            ],
            ...
        },
        ...
    ],
    ...
}

Some options are designated as arrays, which means that more than one value is allowed. For example, the option dns-servers allows the specification of more than one IPv6 address, enabling clients to obtain the addresses of multiple DNS servers.

Custom DHCPv6 Options describes the configuration syntax to create custom option definitions (formats). Creation of custom definitions for standard options is generally not permitted, even if the definition being created matches the actual option format defined in the RFCs. However, there is an exception to this rule for standard options for which Kea currently does not provide a definition. To use such options, a server administrator must create a definition as described in Custom DHCPv6 Options in the dhcp6 option space. This definition should match the option format described in the relevant RFC, but the configuration mechanism allows any option format as there is currently no way to validate it.

The currently supported standard DHCPv6 options are listed in the table below. "Name" and "Code" are the values that should be used as a name/code in the option-data structures. "Type" designates the format of the data; the meanings of the various types are given in List of standard DHCP option types.

List of standard DHCPv6 options configurable by an administrator