Documentation Index

Fetch the complete documentation index at: https://kb.isc.org/llms.txt

Use this file to discover all available pages before exploring further.

Kea 3.2: Things to be aware of when upgrading

Updated
  • Updated on Jun 24, 2026
  • Published on Jun 24, 2026
  • 3 minute(s) read
  • Suzanne Goldlust
  • Peter Davies
  • Ben Scott
 Prev Next

The release of the Kea 3.2 branch includes a few changes users should know about when upgrading from Kea 3.0. If you are upgrading from a pre-3.0 version, please review the "Things to be aware of when upgrading to Kea 3.0.0" article first.

The Kea Control Agent (CA)

The Kea Control Agent, which was deprecated in Kea 3.0, is no longer included in the Kea distribution.

If you have an installation that sends API commands to the CA for forwarding to other Kea daemons, you will need to update both your Kea configuration and your API client(s) to use the direct API mechanism instead.

If you previously sent API commands directly to Unix domain sockets in the filesystem, there will be no change.

For the kea-dhcp4, kea-dhcp6, and kea-dhcp-ddns processes, the control-sockets structure may be used to define access methods. The default configs now contain control-sockets examples. See Migrating away from Kea Control Agent for further information.

Note that, prior to Kea 3.0, the HA restrict-commands parameter defaulted to false, which allowed users to send commands to the HA dedicated listener. The default is now true; Kea HA will now only process HA-related commands.

The REST API

When using the direct API, the service parameter is no longer silently ignored, as it was in Kea 3.0.x. If service is a non-empty list, it must contain exactly one element matching the name of the server to which the command was sent. It is recommended not to add a service parameter.

Databases require JSON

Kea now assumes any SQL database used with Kea supports JSON. Kea no longer checks whether JSON is supported. Since all currently supported PostgreSQL, MySQL, and MariaDB versions support JSON, this change should not affect anyone. Users of outdated databases may see an error; in that case, please upgrade to a recent database server version.

Stricter Kea Config File

Various changes were made to tighten rules around Kea's parsing of its own config files.

  • Leading zeros in numeric values (prohibited per the JSON specification) now log warnings.
  • Leading plus signs in numeric values were already being rejected, but one corner case was slipping through. Fixed.
  • Invalid socket parameters are detected and rejected.

Network Interfaces

Kea's code for managing network interface devices was overhauled. This enhances support for VLANs and external interfaces, performs better when handling heavy loads, and adds new API commands.

Previously, Kea could struggle to handle significant traffic across multiple interfaces, favoring the first interface specified in the configuration. Processing of incoming traffic is now distributed more evenly.

The following API commands have been added:

  • interface-list
    • Retrieve the currently configured list of interfaces. That list is also part of config-get, but this is more specific and has less overhead.
  • ìnterface-add
    • Manually adds specific interfaces to a running Kea, without automatic interface re-detection.
  • interface-redetect
    • Allows Kea discover changes in network interfaces (adds and removes), without the overhead of a full configuration reload.

Packages

Permissions

ISC packages for Kea now install Kea executables as owned by the Kea user and group (kea or _kea), with permission mode 750 (rwx/r-x/---). Installations desiring the ability for unprivileged or other users to run the Kea software will need to add those users to the Kea group.

Restarts

Kea daemons will now be restarted by systemd if the service exits with failure status.

During a package upgrade, any running Kea services will now automatically be restarted.

Lease Queue Allocators

Adaptive Lease Times

An adaptive-lease-time-threshold parameter has been added, which currently applies only to the FLQ allocation strategy. This allows Kea to offer low lease times in oversubscribed address pools.

Shared Free Lease Queue Allocator

Experimental Feature

Shared Free Lease Queue Allocator is considered experimental and is not supported for production use.

A new IP allocation strategy, Shared Free Lease Queue Allocator (sFLQ), has been added, enabling the use of FLQ on installations that use shared-lease database backends. sFLQ does not support adaptive-lease-time-threshold.

For details, see Shared Free Lease Queue Allocator

Statistics

Many new statistics counters have been added: statistic-global-get-all, pkt{4,6}-service-disabled, global assigned-addresses, global assigned-nas, global assigned-pds, pkt{4,6}-limit-exceeded, pkt{4,6}-queue-full, pkt{4,6}-rfc-violation, pkt{4,6}-admin-filtered, pkt{4,6}-processing-failed, pkt{4,6}-not-for-us, and pkt{4,6}-duplicate.

For more details, see: Statistics.

RADIUS

Among other improvements, RADIUS over TLS (radsec) is now supported and a status-server mechanism has been added.
When configuring RADIUS to use TLS, the idle-timer-interval parameters are no longer allowed in either the access or the accounting scopes. Support for the realm parameter has also been removed.

For more details, see the RADIUS/TLS Configuration section in the Kea ARM.

See also