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