Things to be aware of when upgrading to Kea 3.0.0

The release of the Kea 3.0 branch brings with it many changes users need to know about.

Hooks libraries re-licensed and re-packaged

Most Kea hook libraries have become open source and are freely available; the only exceptions are the Role-Based Access Control hook (RBAC) and the Configuration Backend hook (CB), which remain commercially licensed. The open source hook libraries will be available in the Kea source tarball and for package installation from the official ISC repositories on Cloudsmith.io. The isc-kea-hooks packages in the open-source repository will contain many more hooks than in previous versions.

The separate -prv private repository will no longer include copies of the open source software. Users who need the RBAC or CB hooks must set up both the open source and the -prv repositories, and must use their Cloudsmith token to access the private repositories for the two commercial hooks.

For details on package installation, see the Using Official ISC Packages for Kea knowledge base article.

Recent security improvements

Security improvements introduced before Kea 3.0.0

Several security enhancements were made to Kea, as outlined in the following Common Vulnerabilities and Exposures: CVE-2025-32801, CVE-2025-32802, and CVE-2025-32803.

Hooks libraries can only be loaded from the hooks directory. The environment variable KEA_HOOKS_PATH may be set to override the default path at startup.
The config-write command has been altered, so it will only create files in the directory containing the Kea startup configuration file.
The Kea Control Agent (CA) configuration has API authentication enabled by default. A password must be stored in the kea-api-password file before the CA can start. See Securing a Kea Deployment for additional details.
It is no longer possible to create sockets in any available directory; sockets must be created in a specific directory, which must have 0750 access rights. The default directory is [kea-installation-dir]/var/run/kea. This path may be overridden at startup by setting the environment variable KEA_CONTROL_SOCKET_DIR to the desired path. See Configuration in the ARM for further details.
Lease files and the duid file (DHCPv6 only) may only be loaded from a specific directory; the default is [kea-install-dir]/var/lib/kea. This path may be overridden at startup by setting the environment variable KEA_DHCP_DATA_DIR to the desired path. This restriction also applies to writing lease files using the lease4-write and lease6-write commands.
Logger log files may only be written to a specific directory; the default is [kea-install-dir]/var/log/kea. This path may be overridden at startup by setting the environment variable KEA_LOG_FILE_DIR to the desired path.
Forensic (legal) log files may only be written to a specific directory; the default is [kea-install-dir]/var/log/kea. This path may be overridden at startup by setting the environment variable KEA_LEGAL_LOG_DIR to the desired path.
Before upgrading, check that your configuration file is acceptable. The -T command line parameter may be used to verify a configuration. For packaged installations, the kea-dhcp4/kea-dhcp6 parameter -W will list the default installation and hooks directories.
When compiling Kea from the source, the default installation directory may be changed with the --prefix build time parameter.
In many cases, when specifying files, the path component may now be omitted. Kea will attempt to find the file in its default location.

Security improvements introduced in Kea 3.0.0

The default configuration for the Kea Control Agent (CA) has been updated to enable basic HTTP authentication. Thus, access to the Kea API requires a password. The ARM also contains additional examples of stronger TLS certificate-based authentication, which only allows access to clients presenting a valid TLS certificate. It is still possible to avoid the use of a password or TLS certificate-based authentication but it is not recommended.
A new command-line flag has been included to enable a relaxed security policy. The -X flag disables path and permissions restrictions. If -X is used, the server will emit a warning at startup that security restrictions have been disabled.
Changes to the security of the Run Script and Forensic Logging hook libraries have been made. The run_scripts hooks is now restricted to run scripts located in the [kea-install-dir]/share/kea/scripts/ directory only. The forensic logging hook may only write files to the [kea-install-dir]/var/log/kea directory. This path may be overridden at startup by setting the environment variable KEA_LEGAL_LOG_DIR to the desired path. If a path other than this is used, Kea will emit an error and refuse to start, or if it is already running, it will log an unrecoverable error. As with other changes to paths, it is now possible to omit the path entirely from the configuration directive. The default path will be used. Please see: #3849 for further information.

Upgrading from Kea 2.4

When upgrading from Kea 2.4.x, be aware of the following changes:

Kea no longer autogenerates a subnet-id if one is not given. Subnets defined without a subnet-id will yield a syntax error.
Packages for EL7 distributions, e.g. CentOS 7 and RHEL 7, are no longer maintained.
The relay/ip-address list parameter has been replaced with the relay/ip-addresses map parameter.
The following behavioural parameters have been removed from the dhcp-ddns map: ddns-generated-prefix, ddns-qualifying-suffix, ddns-replace-client-name, ddns-override-client-update, ddns-override-no-update, hostname-char-replacement, and hostname-char-set. They must now be defined in the global scope.
A new RADIUS hook library implementation makes it unnecessary to install the FreeRADIUS client and compile it with Kea.
The deprecated libreload API command has been removed.
The deprecated reservation-mode parameter has been removed.
The Cloudsmith repo for development releases is now named kea-dev.

For more details, see the release notes document.

Upgrading from Kea 2.6

When upgrading from Kea 2.6.x, be aware of the following changes:

Starting with Kea 2.7.0, the High Availability (HA) implementation is incompatible with older Kea versions. All Kea HA partners must run Kea 2.7.0 or later.
It is no longer possible to send API commands, that are unrelated to HA, via the HA listener. The flag that controls this is restrict-commands which now defaults to true.
Lease caching (see: https://kea.readthedocs.io/en/latest/arm/dhcp4-srv.html#lease-caching for DHCPv4 or https://kea.readthedocs.io/en/latest/arm/dhcp6-srv.html#lease-caching for DHCPv6) is now enabled by default.
The control-socket.socket-name and control-socket.socket-type parameters have been removed from the CB.
Kea now rejects certain default passwords. If you copied your Kea configuration from the examples in our documentation using our sample password, change your password to a unique value.

Please continue reading below for more incompatible changes that apply to migrations from Kea 2.4 and 2.6.

The Kea Control Agent is deprecated

The kea-control-agent is now deprecated. As of 2.7.2, the individual Kea services support HTTP/HTTPS control channels, so the Control Agent (CA) is no longer needed. API commands may now be sent directly to the kea-dhcp4, kea-dhcp6, and kea-dhcp-ddns processes. The CA is still available but will be removed from the Kea distribution in a future release. To configure a Kea process to accept incoming API commands, a new control-sockets map is available, which may be configured as follows:

    "control-sockets": [
        {
            "socket-type": "http",
            "socket-address": "10.20.30.40",
            "socket-port": 8004
        }
    ],

Available socket types are unix, http, and https. Multiple sockets may be defined within the control-sockets map. The new control-sockets map precludes the use of the control-socket list.

See Migration from the Control Agent for further information.

Changes to database hooks

Support for MySQL and Postgres database backends have been moved from the core binaries to hooks libraries. These hooks libraries include support for the Lease Backend, the Host Backend, and the Configuration Backend (CB). isc-kea-mysql and isc-kea-pgsql are the package names of these hooks. If you use the Lease or Host database backends, you must now load the appropriate database hooks library. See libdhcp_mysql.so:Database Backend for MySQL or libdhcp_pgsql.so:Database Backend for PostgreSQL for further information.

Lease file format

There have been no incompatible changes to the lease file format.

Connection with Stork Agent

As of Stork 2.2.0, Stork does not support management of Kea via direct API to the service daemons. People wishing to use Stork for management of Kea 3.0 will need to keep the Kea Control Agent configured for now.

Changes to client classification

There have been several changes to client classification:

The precedence of options specified in a template class and its spawned classes has been reversed. An option specified in a spawned class now takes precedence over the same option specified in the template class.
The only-if-required and require-client-classes were renamed to only-in-additional-list and evaluate-additional-classes.
Classes included in require-client-classes (now called evaluate-additional-classes) that do not have test expressions will now be unconditionally added to a client's list of matching classes; previously, they were ignored.
Additional classes are now evaluated in the same order as option-data, i.e. pools, subnets, and shared networks. In earlier versions, the order was reversed.
It is now possible to define multiple client classes when limiting access to networks, subnets, and pools. The parameter client-class (a single class name) has been replaced with client-classes (a list of one or more class names). The older syntax is still accepted but is now deprecated and will be removed in the future. You cannot specify both client-class and client-classes within the same scope.
Options name value pairs specified in option-data have a new parameter available: client-classes. This allows the administrator to place a guard on the option requiring membership in a class or classes before that particular option data will be added to the packet. This is intended as a powerful mechanism to bring back some of the functionality from the conditional (if) statements that were widely used in ISC DHCP. See Option Class-Tagging in the ARM for further information.

Meson a new build system

Kea now features a Meson-based build system introducing Meson addresses several older Autotools issue If you're switching to Meson, the How To Meson in the Kea Gitlab Wiki may prove helpful. The ARM, of course, has detailed build instructions. See Build Requirements and Installation from Source sections for more information. It may be easiest to install Meson for the local user so that the latest version may be used. Some OS packaged versions of Meson are too old to build Kea.