# 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.