[Kea-announce] Kea 1.9.4, a new development release of Kea, is now available

Michael McNally mcnally at isc.org
Wed Jan 27 20:44:55 UTC 2021

Internet Systems Consortium is pleased to announce the release of Kea 1.9.4.


                       Please Note:  New Signing Key

If you are among the users who use the detached signatures provided with each
release download to verify its authenticity, please note that this release is
double-signed -- the provided detached signature files can demonstrate the validity
of its contents using either:

  -  the 2019-2020 code signing key (AE3F AC79 6711 EC59 FC00  7AA4 74BB 6B9A 4CBB 3D38)
     which expires on January 31st of this year, or

  -  the 2021-2022 code signing key (7E1C 91AC 8030 A5A5 9D1E  FAB9 750F 3C87 723E 4012)
     which is newly available from https://www.isc.org/pgpkey (specifically you want the
     item labeled "Current ISC Code Signing Key 2021 - 2022 (codesign at isc.org)"

For those who are unfamiliar with PGP / GPG, the page with the ISC public keys
(https://www.isc.org/pgpkey) also contains instructions on how to use the public key
portion of the codesign key and the signature files to verify the contents of your download.

After 31 January, 2021, the old key will be expired and will no longer be used,
so please take care to update your public key ring before next month's releases.


# Kea 1.9.4, January 27th 2021, Release Notes

Welcome to Kea 1.9.4, the fifth monthly release of the 1.9 development
branch. As with any other development release, use this with caution:
development releases are not recommended for production use.

This release adds new features, improves existing features, clarifies
documentation and fixes a few bugs. The most notable changes introduced
in this version are:

**Experiments with TLS support.** Kea has never supported TLS, so we
have always recommended that more security-conscious deployments set up
a reverse HTTPS proxy to secure access. This is inconvenient and can
introduce additional problems. We finally got the necessary resources
(and courage) to tackle the problem of implementing native TLS support
in Kea. We did several experiments with the Boost.SSL library, which
provides a nice C++/ASIO abstraction over the OpenSSL layer. We now have
a working proof of concept (PoC). The code for the PoC is not included
in this release as it is not yet production quality, but you can find it
in our open GitLab repo. Adding native TLS support is a fairly big
project and will take more than one monthly development cycle to
complete. The plan is to turn this PoC into production-quality code in
the coming releases. Stay tuned! #1619.

**Cache threshold.** The renew-timer governs when the devices are
supposed to renew their leases. Clients sometimes renew earlier than
specified, either because they are ignoring the timer or because they
are broken. Frequent early renewals put an extra burden on the server,
which has to write updated leases, even though they may have been
already renewed seconds earlier. The ``cache-threshold`` (expressed as a
percentage) and ``cache-max-age`` (expressed in seconds) parameters help
reduce that extra burden on Kea. Kea still responds to the client but
merely resends the existing lease lifetime, thus eliminating the need to
update the lease database. Cache threshold is a popular feature of ISC
DHCP that so far was missing in Kea. The implementation is considered
experimental, as we were unable to test it properly by release time. If
you're willing to test it, please do report your findings. #1418

**HA improvement: responsive when recovering from communication
failure.** The failover procedure in the Kea High Availability library
has been improved by introducing a new communication-recovery state. In
this state, the load balancing servers remain responsive to DHCP queries
when the communication between them is interrupted. The new feature is
controlled using the ``delayed-updates-limit`` configuration parameter.

**HA improvement: dhcp-enable/dhcp-disable upgrades.** The DHCP service
can be independently enabled or disabled by a user command, by the
database connection mechanics, or by the HA library. The DHCP service is
disabled when any of those originators disable the service, and it is
enabled when all those that previously disabled the service enable it.
The ``dhcp-enable`` and ``dhcp-disable`` commands accept an "origin"
parameter with valid values of "user," which is the default and
indicates a user-generated command, and "ha-partner," which is used
internally by the HA library. #1601

**Small performance improvement in host backend.** The host retrieval
algorithm has been optimized slightly when retrieving host data from a
database: in certain situations, a single query can retrieve multiple
reservations. This should improve performance a bit, especially in cases
with shared networks and many reservations. #1458

**Documentation updates.** Vendor option examples (options 43 and 125)
were added. We also detected several oddities in the option handling, so
we plan to add more code fixes and examples in the near future. #1546
The Administrator Reference Manual (ARM) has been updated to clarify
that the lease sanitizer fixes lease records in memory only. Kea only
reads stored lease files when starting. #1618 The section about running
Kea as a non-root user has been corrected. #1629 The example in Section
8.2.12 has been corrected by removing unbalanced parentheses. #1589 In
some cases, Kea does not adhere to RFC standards. The new ARM section
dedicated to RFC conformance exceptions mentions two such cases and
explains why they exist. Usually, the practical aspects of supporting
real-life non-conformant devices outweigh the compliance benefits. The
two documented exceptions are: 1) a DECLINE packet with a missing
mandatory "server id" option is handled #1615, and 2) on REQUEST, for a
packet with no ``requested IP address`` Kea should respond with NAK.

**Build improvements.** Hammer, our build automation tool, has been
extended with support for recently released Fedora 33 and Ubuntu 20.10
systems. This is the first step towards building packages. #1527, #1528
The Perfdhcp build system was overly strict. #1637 Hammer exception
handling was improved. It now handles the scenario in which required
tools are missing in a gentler way. #1512

**Bug fixes.** A handful of bugs were fixed in this release. When using
the configuration backend, the server converts the old
``reservation-mode`` global parameter internally to new reservation
flags. The new flags are listed when issuing the ``config-get`` command.
#1598 Kea previously did not handle sub-options with option code 125
well, incorrectly assuming that 125 was always a vendor option. That is
now fixed. If you previously experienced problems with Kea
misinterpreting sub-options, your problem may have been fixed as well.
#1585 The Kea-LFC (lease file cleanup) tool now processes all lines,
even if the last trailing blank line is missing. #1603

**Test improvements.** We continue our efforts to improve testing
capabilities. Investments in testing infrastructure make the code more
stable and more maintainable in the long term. Unit tests for HA running
with thread sanitizer (#1627), lfc timer, and shell tests were improved.
#1630 A tricky off-by-one error was fixed in HA failover tests. #1578
The shell tests now report their results in an XML file, similar to
Google tests. #437 A unit test failure on FreeBSD 12.0 is now fixed.
#673 One Cassandra test (cql_update_hosts) has been fixed. #1616
Jenkins, our testing and build farm, did not report crashes under some
circumstances. This is now fixed. #1519

**Developer tools.** Our team also spent some time improving our
processes. Code formatting is now automated using ``uncrustify`` and
``clang-format``. #1455 The kea-msg-compiler tool no longer adds dates
to generated files, which will reduce commits in Kea's git history.
#1511 We added a script to check for duplicate includes, which are
mostly harmless but which slow down the compilation a bit. #1602 A new
section about best practices for maintaining and developing shell
scripts was added to the Developer's Guide. #1610

## Incompatible Changes

This release introduces one incompatible change:

1. The ``config-get`` command now returns the reservation mode using the
new syntax. This affects only people who implemented specific code that
relies on the now obsolete ``reservation-mode`` as returned by Kea. The
parameter is deprecated, but is still supported when setting the config
or reading the configuration from a file.

## Known Issues

For details on known issues, visit:


And the list of issues marked as bug:


## Release Model

The Kea project has a significant production deployment base with users
who are looking for stability, rather than a constant stream of new
"bleeding-edge" features. At the same time, we want to continue
developing the software and add some new powerful, but
difficult-to-implement, features. To meet both of these requirements we
have both Stable and Development branches.

Stable releases are what you would expect: stable, released
infrequently, without new features or significant changes, very
well-tested. These can be identified by an even-numbered minor version
number. The current stable releases are 1.8.2. The older stable version
of 1.6.3 is also available. If we discover important bugs that require
fixing, we may release additional maintenance versions on the 1.8
branch, but that will be determined on a case-by-case basis. The next
major stable version will be 2.0.0.

Development releases can be easily identified by an odd minor version
number: for example, 1.9.0 is a development release. Subsequent releases
on the same minor release branch get numbered with 1.9.1, 1.9.2, and so

Our goal is to make the development release available on the last
Wednesday of each month. There may be exceptions (such as during
holidays), but that's the general plan.

We encourage users to test the development releases and report back
their findings.

For more details on the plan, see ISC's Software Support Policy at:


## Kea Overview

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 and DNS update servers, an example shell client to
connect to the CA, a daemon that is able to retrieve YANG configuration
and updates from Sysrepo, and a DHCP performance-measurement tool. Both
DHCP servers 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 is stored in a CSV file by default;
it can optionally be stored in a MySQL, PostgreSQL, or Cassandra
database instead. Host reservations can be stored in a configuration
file, or in a MySQL, PostgreSQL, or Cassandra database. They can also be
retrieved from a RADIUS server, although this functionality is somewhat
limited. Kea DHCPv4 and DHCPv6 daemons provide support for YANG models,
which are stored in a Sysrepo datastore and can be configured via the
NETCONF protocol.

This text references issue numbers. For more details, visit the Kea
GitLab page at:


## License

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


The premium and subscriber-only hooks libraries are provided in source
code form, under the terms of an End User License Agreement (you will
get the source code that you can modify freely, but you are not
permitted to redistribute it).

## Download

Pre-built ISC packages for current versions of the most popular Linux
operating systems are available at:


The Kea source and PGP signature for this release may be downloaded from:


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

* https://kea.readthedocs.io/en/latest/
* or via https://kb.isc.org/docs/kea-administrator-reference-manual in
HTML, plain text, or PDF formats

ISC maintains a public open source code tree, a wiki, an issue tracking
system, milestone planning, and a roadmap at:


We ask 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
feedback on the Kea Users mailing list at:


We would also like to hear whether the documentation is adequate and
accurate. Please open tickets in the Kea GitLab project for bugs,
documentation omissions and errors, and enhancement requests. We want to
hear from you even if everything worked.

## Support

Professional support for Kea is available from ISC. We encourage all
professional users to consider this option; Kea development and
maintenance are funded with support subscriptions. For more information
on ISC's Kea and 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 GitLab at:


## Changes

The following summarizes changes since the previous release of 1.9.3:

1860.	[build]		razvan
	Library version numbers bumped for Kea 1.9.4 development
	(Gitlab #1666)

1859.	[doc]		wlodek
	Added example files with configured Vendor Specific Information
	option (code 43) and Vendor-Identifying Vendor-specific
	Information option (code 125) with several suboptions each.
	(Gitlab #1546)

1858.	[bug]		razvan
	The DHCP service can be independently enabled or disabled by
	the user command, by the database connection mechanics or
	by the HA library. The DHCP service is disabled when any
	of those originators disables the service, and it is enabled
	when all those who previously disabled the service enable it.
	The 'dhcp-enable' and 'dhcp-disable' commands accept 'origin'
	parameter with valid values of 'user' (which is the default)
	indicating a user generated command and 'ha-partner' which is
	used internally by the HA library.
	(Gitlab #1601)

1857.	[build]		andrei
	Code format styles meant to be as close as possible to the
	recommended coding guidelines are now included with the Kea
	source repository in the form of .clang-format and
	.uncrustify.cfg. The clang-format.sh and uncrustify.sh scripts in
	the tools directory can be used to apply these styles to chosen
	files. See coding guidelines in CONTRIBUTING.md for more details.
	(Gitlab #1455)

1856.	[bug]		razvan
	When using the config backend, the server converts the old
	'reservation-mode' global parameter internally to new
	reservation flags. The new flags are listed when issuing the
	config-get command.
	(Gitlab #1598)

1855.	[func]		marcin
	Improved failover procedure in Kea High Availability library
	by introducing new communication-recovery state. In this
	state the load balancing servers remain responsive to DHCP
	queries when the communication between them is interrupted.
	The new feature is controlled using the delayed-updates-limit
	configuration parameter.
	(Gitlab #1402)

1854.	[func, perf]	fdupont
	Implemented "lease caching", a feature similar to ISC
	DHCP's dhcp-cache-threshold. Lease caching is configured
	through two new parameters: cache-max-age and cache-threshold,
	and is supported by both kea-dhcp4 and kea-dhcp6. When enabled,
	lease-caching allows the server to skip updating lease storage,
	when a client is requesting it's own pre-existing lease whose
	age falls under the cache threshold and for which there are no
	substantive changes to lease values such as the hostname.
	(Gitlab #1418)

1853.	[func]		fdupont
	Populated the space field of option definitions. This solved
	reported bugs where a specific standard option processing
	was applied to an option from another space but sharing the
	same code. In particular, this fixes the problem reported
	with vendor suboption 125.
	(Gitlab #1585)

1852.	[bug]		razvan
	Corrected the value of unacked-clients-left returned in response
	to the status-get command and the corresponding log messages.
	The previously returned value was too low by 1.
	(Gitlab #1578)

1851.	[func]		fdupont
	Removed methods fetching leases by both client identifier
	and hardware addresses from the API.
	(Gitlab #1540)

1850.	[build]		andrei
	Add two scripts to help with code aesthetics, insight on how Kea
	is built or minor build optimizations:
	* ./tools/check-for-duplicate-includes.sh: warns you if
	there is a source file that includes the same header twice.
	While this wouldn't normally result in any errors, it is an
	unusual practice. If you feel that a header should be included
	twice in a file, add the file under "# Exceptions:" in the
	* ./tools/print-generated-files.sh: prints all the files
	that are generated which may or may not be part of the
	repository. These consist of messages, parser files, and "built
	sources" (as called in Makefile.am files).
	(Gitlab #1602)

1849.	[doc]		tomek
	Two known DHCPv4 RFC violations are now documented in the ARM.
	They are both cases where Kea deliberately deviates from the
	RFC to accommodate some common broken-client behaviors.
	(Gitlab #1608, #1615)

1848.	[bug]		razvan
	The cql upgrade script from schema v3.0 to v4.0 was broken in
	Kea-1.9.3 and has been fixed also enabling the unittest.
	(Gitlab #1616)

Thank you again to everyone who assisted us in making this release

We look forward to receiving your feedback.

More information about the Kea-announce mailing list