Version 9 (modified by wlodekwencel, 17 months ago) (diff)


Kea 1.4.0, June 15 2018, Release Notes

Welcome to the 1.4.0 release of Kea. Kea is a DHCP implementation developed by Internet Systems Consortium, Inc. that features fully functional DHCPv4 and DHCPv6 servers, a dynamic DNS update daemon, a Control Agent (CA) that provides a REST API to control the DHCP servers, an example shell client to connect to the CA and a DHCP performance measurement tool. Both DHCP servers fully support server discovery, address assignment, renewal, rebinding, release, decline, information request, DNS updates, client classification and host reservations. The DHCPv6 server also supports prefix delegation. Lease information can be stored in a MySQL, PostgreSQL or Cassandra database; it can also be stored in a CSV file. Host reservations can be stored in a configuration file; they can also be stored in a MySQL, PostgreSQL, Cassandra databases and to some degree also retrieved from a RADIUS server.

Version 1.4.0 adds the following features to Kea:

  • High Availability - To provide a highly available service, despite server failure, two Kea instances can now be configured to run as a pair. Two modes are supported. In hot standby mode there is a primary instance handling all traffic and sending updates to its secondary partner. The secondary monitors the health of the primary and is able to take over automatically in case the primary fails. In load balancing mode both partners are active and are handling approximately half of the traffic traffic. In case of a failure of either server, the partner is able to take over responding to all traffic directed to both servers. Support for additional backup servers is implemented. The backup server's database is updated as soon as possible after changes are made to the primary server's database, so that it can be used as an almost drop-in replacement in case of catastrophic failures that take out both primary and secondary servers. The solution supports both IPv4 and IPv6 and can work with any backend, including memfile. Note that this is NOT an implementation of the IETF standard DHCPv4 failover (which does not support DHCPv6).

The HA feature was planned to be a Premium feature, and so it was not included in the Kea 1.4 open source beta package. During the beta period we decided to instead offer it as part of the free open source to enable more users who rely on DHCP failover to migrate to Kea.

  • Database improvements - Many Kea users report using multiple Kea instances sharing a single database backend, or cluster of databases. One of the frequently requested features was the ability to report accurate statistics in this case. This surprisingly tricky problem was solved for MySQL and PostgreSQL by a new stat_cmds hook library and schema updates. Users also requested the ability to reconnect after the database connection is lost for whatever reason. NOTE You will need to upgrade any existing MySQL and PostgreSQL Kea databases to the new schema versions. This is readily done using kea-admin:
$ kea-admin lease-upgrade {mysql|pgsql} -u database-user -p database-password -n database-name
  • Cassandra - Kea has had experimental support for a Apache Cassandra database backend for a while, but the feature hadn't been finished or fully tested. This has changed: the code now supports host reservations and has a great number of new smaller fixes and improvements. Its is now both easier to install and much better documented. Thank you to Deutsche Telekom AG for sponsoring this work.
  • Classification - It is now possible to specify client classes on a pool level, so you can control who is able to use specific pools, group similar clients together or even reject clients that don't meet certain class requirements. Class expressions have expanded capabilities. The most popular seems to be a member operator, which determines whether packet is a member of a given class. Complex boolean logic is available. Ever wanted to do member(foo) and not member(bar)? Now you can.
  • Bug fixes and quality of life improvements - With 134 tickets closed, 1.4.0 is by far the biggest release we ever did.

We have also added a new premium hook library:

  • RADIUS - Kea can now be integrated with an existing RADIUS server. Both access and accounting roles are supported. Kea is able to send Access-Request messages and alter its behavior depending on the responses. Specific IP addresses may be assigned (if Framed-IP-Address or Framed-IPv6-Address is received), client can be assigned to specific pool (if Framed-Pool or Framed-IPv6-Pool is received) or denied service altogether (if Access-Reject is received). Kea can also send accounting messages to RADIUS accounting servers. As with other features, this supports both IPv4 and IPv6.

We have introduced the following backward incompatible changes since Kea 1.4.0 beta release:

  • Logger names - Several Kea loggers have been renamed to adhere to the common naming convention, i.e. hyphens are used instead of underscores and loggers used by the hook libraries use include "-hooks" postfix. For example: rather than kea-dhcp4-lease_cmds). This change affects loggers used both in the core Kea code and in the hooks libraries. See Kea ticket #5622 for details.
  • Host reservations API changes - Removed deprecated API functions which had been used for retrieving host reservations by HW address and/or DUID. This change does not affect Kea users. It merely affects hooks library developers who use the removed functions for retrieving host reservations. See Kea ticket #5563 for details.
  • Hook installation - We have changed the installation method for hooks packages. Hooks released with earlier versions of Kea will need to be updated to the Kea 1.4 versions.
  • Client Classification change planned for Kea 1.5 - In a future version of Kea, probably in Kea 1.5, we would like to adjust the option precedence order for Kea so that it matches the order for ISC DHCP (to simplify configuration for users migrating to Kea). Currently, Kea uses (host, pool, subnet, shared network, class, global), while ISC DHCP uses (host, class, pool, subnet, shared network, global). Because this is a potentially disruptive change to existing Kea users, we want to give advance notice that we are planning this. To express your feedback about this pending change, please send your comments to Kea-users at


Kea 1.4.0 is released under the Mozilla Public License, version 2.0.

The premium hook libraries are provided in source code form, under the terms of an End User License Agreement (you are not permitted to redistribute).


The Kea 1.4.0 source may be downloaded from:

A PGP signature of the distribution is at

The signature was generated with the ISC code signing key which is available at

ISC provides detailed documentation, including installation instructions and usage tutorials in the Kea Administrator Reference Manual. Documentation is included with the installation or via in HTML, plain text, or PDF formats. ISC maintains a public open source code tree at and wiki pages with roadmap and issue tracking at

Limitations and known issues with this release can be found at

We'd like users of this software to please let us know how it worked for you and what operating system you tested on. Feel free to share your configuration or use case. Also we would like to hear whether the documentation is adequate and accurate (please open tickets for documentation omissions and errors). We want to hear from you even if everything worked.


Professional support for Kea is available from ISC. We encourage all professional users to consider this option: Kea maintenance is funded with support subscriptions. For more information on ISC's DHCP software support see Free best-effort support is provided by our user community via a mailing list. Information on all public email lists is available at

If you have any comments or questions about working with Kea, please share them to the Kea Users List Bugs and feature requests may be submitted via the ticket tracking system at


The following summarizes changes and important upgrade notes since the previous release (1.4.0-beta).

  1. [bug] marcin

Resolved multiple problems causing slow synchronization of leases in the HA hooks library, including adjusting timeouts in control channel and improving performance of responses sent by the Command Manager to Control Agent. Also, introduced 'sync-timeout' configuration parameter into HA hooks library to control lease database synchronization timeout. (Trac #5649, git cbc29128863916a13364749bf681586aea2aa51e)

  1. [func] fdupont

Added KNOWN and UNKNOWN built-in client classes: after host lookup if a matching host entry is found the incoming packet is added to the KNOWN class, if none is found to the UNKNOWN class. Then expressions depending directly or indirectly on these classes are evaluated. Note these classes may be used to select a pool but they may not to select a subnet. (Trac #5549, git 6a856ed9722b918a65dca15ff44314e28897784e)

  1. [bug] marcin

Improved performance of the DHCP server running in High Availability configuration by optimizing the management of CalloutHandle? objects passed to the callouts. (Trac #5647, git eea88d5c8f4d8efb6c5bfdfbf4e070a90069db5d)

  1. [doc] marcin

List of hooks libraries provided by ISC includes an information which Kea servers the libraries can be attached to. The detailed description of each supported hooks library also contains this information. (Trac #5613, git 9d6f8de3d988c42c413a7d628e31854e9c80d8c9)

  1. [bug] tmark

kea-dhcp4 and kea-dhcp6 now retain and emit global, scalar parameters specified in their configuration. (Trac #5378, git 4d05122f03d00b10a888c768fe1725cae9d6aea6)

  1. [build] fdupont

Commented out BOOST_ASIO_DISABLE_THREADS in configure to reflect the current use of threads by boost ASIO in Kea. (Trac #5615, git f3fc8b1a4257a42a97aaf88a36287bbe33d1f65b)

  1. [build] marcin

Moved libdhcp_ha (High Availability) hooks library from premium to main Kea repository and changed its license to MPLv2.0. Future ChangeLog? entries for this library will be tracked in the Kea ChangeLog? file. (Trac #5645, git 19b2553d4869bdd52b63b6f7969052d8a724f78d)

  1. [doc] marcin

Updated list of loggers in the Kea Administrator's Manual. The updated list contains all loggers, including those from supported hooks libraries. (Trac #5622, git bd94afc0af7183452c94f3b5768c6138f79d3b60)

  1. [doc] marcin

Documented "sync-leases" configuration parameter of the HA hooks library in the Kea Administrator's Manual. (Trac #5621, git 4ebac3a411aa02d1cc3d74e7eaf3212ad208159a)

  1. [bug] marcin

Corrected bug in the allocation engine which caused occasional lease allocation failures when a loaded hooks library set the callout status to non default value, e.g. "skip" rather than "continue". In such cases, the server reported that it failed to allocate a lease "after 0 attempts". (Trac #5638, git f2e9b686ae52e1b06f660e1b522588b1440e2620)

  1. [bug] marcin

Improved logging in the HTTP library both for the server and the client. (Trac #5205, git fd0bec610c89084d5a5d43ef032c9875c3e6ad46)

  1. [bug] fdupont

Added support of recent Botan 2.x crypto backend. Note that Botan 1.[9-11] is still supported but not recommended. (Trac #5382, git 22651b1935a2397edfbddb9b8873c353c090f18e)

  1. [bug] tmark

kea-dhcp4 and kea-dhcp6 now validate the schema version of lease and host back ends after establishing a connection. If a schema version does not match the version the server expects, the server will emit an error log and close the connection. This applies to MySQL, PostgreSQL, and Cassandra. (Trac #5629, git 15c34afdba45be609e35284a209ad18ed66605f8)

  1. [bug] tmark

kea-dhcp4 parsing now treats renew-timer and rebind-timer as optional with no defaults. The logic for sending them to the client was changed to: send rebind-timer only when it is less than the lease lifetime; and send renew-timer only when it less than either the rebind-timer if specified, or lease lifetime in the absence of rebind-timer. (Trac #5596, git 38426e16ec04a786e35a65d27cbcb7dbabfe79b5)

  1. [func] fdupont

Removed getAll, get4 and get6 methods using both hardware address and DUID from host backend (aka host data source) APIs. This is an *incompatible* change. (Trac #5563, git db4c34b069f114f93d9f29cdeb02b536a0fbc982)

  1. [func]* marcin

The client classes used by the High Availability hook library use upper case "HA_" prefix and they are now built-in classes. This means that those classes do not need to be declared in the server configuration. (Trac #5632, git 2d590bfd7d1b0eca377eb99eef83a3083a1d7399)

  1. [bug] fdupont

Fixed warnings about lambda's not using captured variables. (Trac #5591, git f88a505823d39faec7dc5f647f40e6454e5dfc74)

  1. [bug] marcin

Fixed multiple hanging Control Agent unittests. (Trac #5576, git 310af68101cba74220652ec2b403520fc5666dc0)

  1. [doc] marcin

Documented in the User's Guide how Kea HA service behaves when the clock skew between active servers becomes too high. (Trac #5603, git ffaff4d2a03600bb4f81d335b49a840e31d03c8c)

  1. [func] tomek

perfdhcp now supports -o option that adds DHCP options. This may be used to simulate various clients. (github #77, git b81dedb7f0a2516130e7bd799d9084c63f0e844c)

  1. [bug] tmark

Corrected an issue where the destruction of loggers prior to the destruction of the TimerMgr? singleton caused unit tests to segfault. (Trac #5626, git 9f4e3f9cd8acf8e7d1d3e714d8f904754377c00f)

  1. [func] fdupont

Added pkg-config alternative to configure --with-cql path so now you can use either pkg-config or cql_config. (Trac #5488, git 55498ca3455517132533a39002ebfc05d26c7e38)

  1. [bug] tmark

Corrected missing "override" warning in cql_lease_mgr.h (Trac #5625, git df3068ba0e520df4d96dd38e2de679beb99f2e23)

Thank you again to everyone who assisted us in making this release possible. If you would like to contribute to ISC to assist us in continuing to make quality open source software, please visit our donations page at

We look forward to receiving your feedback.