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

Wed May 31 16:24:54 UTC 2023

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

Releases in the Kea 2.3.x sequence are part of the Kea 2.3 development
branch, where new features are provided for testing and evaluation
before the branch is designated stable and recommended for production use.

The current stable branch of Kea is Kea 2.2 and its most recent release
is 2.2.0

Kea source tarball are available from cloudsmith.io:

https://dl.cloudsmith.io/public/isc/kea-2-2/raw/versions/2.2.0/kea-2.2.0.tar.gz

https://dl.cloudsmith.io/public/isc/kea-2-3/raw/versions/2.3.8/kea-2.3.8.tar.gz

And from the ISC download page:

           https://www.isc.org/download

---
# Kea 2.3.8 Release Notes, May 31st 2023

Welcome to Kea 2.3.8, the ninth monthly release of the 2.3 development
series. As with any other development release, use this with caution:
development releases are not recommended for production use.

Kea is a DHCP implementation developed by Internet Systems Consortium
(ISC) that features DHCPv4 and DHCPv6 servers with DNS updating and a
REST API; optional database support (MySQL and PostgreSQL); optional
RADIUS, Kerberos, and YANG/NETCONF support; and much more. Kea provides
extensive management capabilities, including but not limited to: TLS
support, run-time configuration monitoring and updates via a REST API,
host reservations, client classification, and more.

The text below references issue numbers. For more details, visit the Kea
GitLab page at https://gitlab.isc.org/isc-projects/kea/issues.

The following features and bug fixes have been implemented since the
previous release, version 2.3.7:

1. **Preferred lifetime for DHCPv6**: Earlier Kea versions had the
preferred lifetime timer set to a fixed value, if it was not explicitly
specified. This could lead, in some cases, to incorrect configuration if
the valid lifetime was configured to a lower value than the preferred
one. Starting with this release, the preferred lifetime is calculated as
0.625 * `valid-lifetime` unless explicitly specified, or if the
specified value is higher than the valid lifetime. This should avoid
situations where Kea sends configurations that are rejected by clients
[#2835].
2. **Statistics**: Several improvements made it into this release,
including the introduction of a new type of statistics that can be
observed on a per-pool basis. A plethora of new statistics were
introduced: `subnet[id].pool[id].assigned-addresses`,
`subnet[id].pool[id].cumulative-assigned-addresses`,
`subnet[id].pool[id].declined-addresses`,
`subnet[id].pool[id].reclaimed-declined-addresses`,
`subnet[id].pool[id].reclaimed-leases`, and
`subnet[id].pool[id].total-addresses` for DHCPv4 and even more for
DHCPv6: `subnet[id].pool[id].assigned-nas`,
`subnet[id].pd-pool[id].assigned-pds`,
`subnet[id].pool[id].cumulative-assigned-nas`,
`subnet[id].pd-pool[id].cumulative-assigned-pds`,
`subnet[id].pool[id].declined-addresses`,
`subnet[id].pool[id].reclaimed-declined-addresses`,
`subnet[id].pool[id].reclaimed-leases`,
`subnet[id].pd-pool[id].reclaimed-leases`,
`subnet[id].pool[id].total-nas`, and `subnet[id].pd-pool[id].total-pds`
[#145]. The statistics type for the total number of available addresses
and prefixes for DHCPv6 has been changed from 64 bits to 128, to account
for the enormous address space in IPv6 [#2658]. New statistics were
added to keep track of leases that have their CLTT increased in memory
and their expiration time left unchanged in persistent storage, as part
of the lease caching feature. Those new statistics are:
`v4-lease-reuse`, `subnet[id].v4-lease-reuse`, `v6-ia-na-lease-reuse`,
`subnet[id].v6-ia-na-lease-reuse`, `v6-ia-pd-lease-reuse`, and
`subnet[id].v6-ia-pd-lease-reuse` [#2797].
3. **DNR options**: The Discovery of Network-designated Resolvers (DNR)
options have been implemented for both DHCPv4 and DHCpv6. This is an
implementation of the draft-ietf-add-dnr-16 IETF Internet Draft, that is
expected to be published as an RFC soon. The options allow configuration
of DNS over various transports, such as TLS, HTTPS, and others. As this
implementation is based on a draft that has not yet reached RFC
publication, use it with caution [#2536].
4. **Forensic Logging hook traceability**: The High Availability (HA)
mechanism uses lease commands to add, update, and delete leases. The
same mechanism can now be used by an administrator to manage lease
state. Previously, the forensic logging hook logged both automated HA
and manual updates in the same manner. Starting with this release, the
forensic logging hook now records whether the lease change is an
administrative action or an automated HA update [#2629].
5. **Allocation strategies**: We fixed a bug that caused the random and
FLQ allocators to allocate PD leases in an unpredictable way [#2860]. We
also fixed a bug in the allocation engine that could cause an invalid
lease assignment in shared networks using subnets with different
allocator types [#2843].
6. **Bulk Leasequery**: The MySQL and PostgreSQL schemas were updated to
account for upcoming BLQ support [#2867]. The by-link address query has
been implemented [#2646, #2868]. A new command `extended-info4-upgrade`
was implemented: it upgrades old leases from an SQL DHCPV4 lease
database to be visible by Bulk Leasequery. This one-time operation is
useful for users who want to start using BLQ immediately and cannot wait
for the normal lease renewal process to gradually fill in the data
[#2757].
7. **YANG/NETCONF**: The YANG modules were updated with recent
configuration changes. The added parameters are: `allocator`,
`ddns-ttl-percent`, `exclude-first-last-24`,
`ignore-dhcp-server-identifier`, `offer-lifetime`, `pd-allocator`,
`read-timeout`, `tcp-user-timeout`, and `write-timeout`. We also removed
these now-obsolete parameters: `contact-points` and `keyspace` [#2832].
8. **Build improvements**: Kea code is now checked with CodeQL, yet
another code analyzer [#2760]; it now avoids warnings in files generated
by Bison [#2862]; and the getIface types have been corrected [#2817]. A
failure in the class_cmds unit test was fixed [#2848]. The CPL
controller now uses the right constants when reporting command status
[#2798].
9. **Bugfixes**: We improved `authoritative` flag handling. We fixed a
bug in the DHCPv4 server that sent DHCPNAK to a client in the
INIT-REBOOT state when the server had no matching subnet configuration
for that client [#2858]. Large (over 128 bytes) client-ids are now
appropriately handled [#2786]. We fixed another bug where the hooks DROP
flag could be ignored under certain circumstances [#2805].
10. **Documentation**: `lease4-write` and `lease6-write` documentation
now properly mentions process ID (PID) in the backup filename [#2859].
The flex-option examples were corrected [#2822]. We also corrected minor
mistakes in the `cb_cmds` [#2827] and `ddns_tuning` hooks documentation
[#2838].

## Incompatible Changes

1. **New preferred-lifetime calculation**. Kea now operates in a safer
manner and behaves in an RFC-conformant way in some corner cases where
it previously sent invalid configuration. Nevertheless, you should
review your configuration if you have unusual settings with scenarios
where `preferred-lifetime` was greater than `valid-lifetime`. This
affects DHCPv6 only. See [#2835] for details.

2. **MySQL and PostgreSQL schema update**. Both database schemas were
updated to accommodate upcoming Bulk Leasequery support in DHCPv6.

3. **YANG module updated**. The YANG modules were updated to incorporate
the latest changes.

## Supported Version

We expect this to be the last 2.3 development release, in anticipation
of the upcoming stable 2.4.0 release. One month after the release of
2.4.0, the next development cycle (2.5.x) will commence and the 2.3
branch will be effectively EOL.

When we release Kea 2.4.0, we will announce End-of-Life for our oldest
(2.0.x) branch on the [kea-users mailing
list](https://lists.isc.org/pipermail/kea-users/). For details regarding
ISC's Software Support Policy, see https://kb.isc.org/docs/aa-00896.

## License

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

https://www.mozilla.org/en-US/MPL/2.0

The premium and subscriber-only hook libraries are provided under the
terms of a Kea Hooks Basic Commercial End User License Agreement.

## Download

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

https://cloudsmith.io/\~isc/repos/

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

https://www.isc.org/download

as well as from the Cloudsmith repository.

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

https://www.isc.org/pgpkey

ISC provides detailed documentation, including installation instructions
and usage tutorials, in the Kea Administrator Reference Manual.
Documentation is included with the installation or at
https://kea.readthedocs.io/en/latest/index.html.

Limitations and known issues with this release can be found at
https://gitlab.isc.org/isc-projects/kea/wikis/known-issues-list.

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
(https://lists.isc.org/mailman/listinfo/kea-users. 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 maintenance is funded
with support subscriptions. For more information on ISC's Kea and DHCP
software support see https://www.isc.org/support/.

Free best-effort support is provided by our user community via a mailing
list. Information on all public email lists is available at
https://www.isc.org/community/mailing-list.

## Changes

The following summarizes changes and important upgrade notes for core
Kea since the previous release, version 2.3.7:

2144.	[build]		razvan
	The library version numbers have been bumped up for the Kea 2.3.8
	development release.
	(Gitlab #2885)

2143.	[func]		razvan
	Added v4 statistic counters per pool:
	subnet[id].pool[id].assigned-addresses
	subnet[id].pool[id].cumulative-assigned-addresses
	subnet[id].pool[id].declined-addresses
	subnet[id].pool[id].reclaimed-declined-addresses
	subnet[id].pool[id].reclaimed-leases
	subnet[id].pool[id].total-addresses
	Added v6 statistic counters per pool:
	subnet[id].pool[id].assigned-nas
	subnet[id].pd-pool[id].assigned-pds
	subnet[id].pool[id].cumulative-assigned-nas
	subnet[id].pd-pool[id].cumulative-assigned-pds
	subnet[id].pool[id].declined-addresses
	subnet[id].pool[id].reclaimed-declined-addresses
	subnet[id].pool[id].reclaimed-leases
	subnet[id].pd-pool[id].reclaimed-leases
	subnet[id].pool[id].total-nas
	subnet[id].pd-pool[id].total-pds
	Counters are stored in the lease storage and after schema
	upgrade all existing leases are considered to be part of pool
	ID 0. On lease update, the counters will be updated accordingly
	including pool IDs and statistics will converge to real values
	over time.
	(Gitlab #145)

2142.	[func]		piotrek
	New command option was added to perfdhcp: --or.
	It allows to insert extra option(s) to relayed DHCPv6 message
	at given level of encapsulation. For now only the first level of
	encapsulation is supported.
	(Gitlab #2834)

2141.	[bug]		razvan
	The High Availability hook library is sending the 'origin'
	parameter set to 'ha-partner' when sending lease update
	commands which enables the forensic log hook library to
	distinguish between administrator commands and HA partner
	commands.
	(Gitlab #2629)

2140.	[func]		slawek
	Implemented functions to delete the host reservations from the
	JSON configuration. Updated the host manager to fully support
	altering the primary source (JSON configuration). Its methods
	accept a new argument ("operation target") to specify the data
	source (JSON configuration and/or hosts database) to query or
	alter. Fixed a function that retrieves IPv6 host reservations
	from the configuration by address.
	(Gitlab #2815)

2139.	[bug]		marcin
	Fixed a bug in the delegated prefix permutations that caused
	allocating prefixes in the same order by the random and FLQ
	allocators.
	(Gitlab #2860)

2138.	[bug]		marcin
	Fixed a bug in the DHCPv4 server that sent DHCPNAK to a client
	in the INIT-REBOOT state when the server had no matching subnet
	configuration for that client.
	(Gitlab #2858)

2137.	[func]		fdupont
	A new command "extended-info4-upgrade" makes old leases
	from SQL DHCPV4 lease database visible to Bulk Lease Queries.
	(Gitlab #2757)

2136.	[func]		tmark
	The default value, in kea-dhcp6, for preferred-lifetime is
	now calculated as: 0.625 * valid-lifetime. This calculation
	is also used in the event that the specified value for
	preferred-lifetime is greater than valid-lifetime.  Prior to
	this, the default value was 3600 seconds, and there was no
	check against sending values greater than valid-lifetime.
	(Gitlab #2835)

2135.	[build]		tomek
	The CodeQL pipeline has been enabled on github. Developer's guide
	updated with details.
	(Gitlab #2760)

2134.	[func]		andrei
	Statistics total-nas and total-pds were increased from 64-bit
	values to 128-bit values to accurately represent large pools.
	(Gitlab #2658)

2133.	[func]		andrei
	Added missing YANG nodes: allocator, ddns-ttl-percent,
	exclude-first-last-24, ignore-dhcp-server-identifier,
	offer-lifetime, pd-allocator, read-timeout, tcp-user-timeout,
	write-timeout.
	Removed obsolete YANG nodes: contact-points, keyspace.
	(Gitlab #2832)

2132.	[bug]		marcin
	Fixed a bug in the allocation engine that could cause an invalid
	lease assignment in the shared networks using subnets with
	different allocator types.
	(Gitlab #2843)

2131.	[bug]		razvan
	Added support for 255 bytes long client-id and 130 bytes long
	duid (2 bytes for type and at most 128 bytes for value).
	(Gitlab #2786)

2130.	[func]		piotrek
	Added support of DHCP Options for the Discovery of
	Network-designated Resolvers (DNR) as per draft-ietf-add-dnr.
	Kea can now handle DHCPv4 Option code 162 and DHCPv6 Option
	code 144.
	(Gitlab #2536)

2129.	[func]		andrei
	New statistics were added to keep track of leases that have their
	CLTT increased in memory and their expiration time left unchanged
	in persistent storage as part of the lease caching feature. The
	statistics are: v4-lease-reuse, subnet[id].v4-lease-reuse,
	v6-ia-na-lease-reuse, subnet[id].v6-ia-na-lease-reuse,
	v6-ia-pd-lease-reuse, subnet[id].v6-ia-pd-lease-reuse.
	(Gitlab #2797)

2128.	[bug]*		razvan
	In addition to logging them, the server now sets the
	CalloutHandle status to DROP to indicate an error occurred when
	it catches unhandled exceptions thrown by a callout.
	(Gitlab #2805)

And for Kea premium:

171.	[bug]		razvan
	The High Availability hook library is sending the 'origin'
	parameter set to 'ha-partner' when sending lease update
	commands which enables the forensic log hook library to
	distinguish between administrator commands and HA partner
	commands.
	(Gitlab #2629)

170.	[func]		slawek
	The host_cmds has been updated to fully support altering (add,
	update, delete) host reservations in JSON configuration. The host
	commands accept a new argument ("operation-target") that defines
	the data source (JSON configuration and/or hosts database) to
	query or alter.
	(Gitlab #2815)

169.	[func]		fdupont
	A new command "extended-info4-upgrade" makes old leases
	from SQL DHCPV4 lease database visible to Bulk Lease Queries.
	(Gitlab #2757)

See https://gitlab.isc.org/isc-projects/kea/-/wikis/Release-Notes for a
complete list of release notes.

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

We look forward to receiving your feedback.

-- 
Everett B. Fulton
ISC Support