# Kea 2.1.2, Jan 26th 2022, Release Notes Welcome to Kea 2.1.2, the third monthly release of the 2.1 development branch. 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 bugfixes and features have been implemented since the Kea 2.1.1 release: 1. **TLS Support for MySQL and PostgreSQL**. MySQL and PostgreSQL backends now can be configured to use SSL/TLS support to protect connections between the database and the Kea server [#34]. The `kea-admin` tool now accepts extra arguments which are passed to the database command tool with `-x`, e.g. `--ssl` to `mysql` with `kea-admin ... -x --ssl`. While the primary goal of this capability is to pass TLS-related parameters, it is generic and can be used to tune other parameters as well [#2225]. 2. **Credentials in files**. Support for using files to configure basic HTTP credentials has been added. Instead of configuring a value directly in the configuration, it can be taken from the content of a file. The new parameters are `user-file`, `password-file`, and `basic-auth-password-file` [#2006]. 3. **Lease migration between backends**. Kea supports several backends for lease storage: memfile, MySQL, and PostgreSQL (also Cassandra, but it is deprecated and will be removed soon). A new capability has been implemented to export and import leases between the backends. This can be used for both backup and for migration between backends. This opens up new possibilities, such as migrating to memfile if extra performance is necessary or migrating to SQL if more powerful statistics and monitoring are desired. The `kea-admin` `lease-dump` command now outputs a CSV file that is compatible with the memfile backend [#2038]. The `lease-upload` command, which can upload leases from a memfile CSV file to a database backend, was added to `kea-admin` [#2039]. `hwtype` and `hwaddr_source` columns were added to memfile for DHCPv6 [#2236]. 4. **PostgreSQL Configuration Backend**. The work on enabling the PostgreSQL-based Config Backend continues. While it is not functional yet, the initial groundwork phase is coming to an end. The PG CB hook now has many of the queries necessary to manage subnets, shared networks, options, option definitions, global parameters, client classes, audit entries, and servers. However, they are not yet hooked to the REST API and thus are non-functional [#95 (partial)]. Additional changes and corrections relating to Config Backend were made to the PostgreSQL database schema. In addition, the upgrade scripts were renamed to ensure proper filename ordering [#2183, #2244]. 5. **Commas in configurations**. Kea servers are now more lenient towards trailing commas in file configurations. While parsing, a warning is printed with the location of the comma to give the user the ability to correct a potential mistake [#2084]. 6. **Forensic logging**. A new parameter, `timestamp-format`, was added in the forensic logging hook library to permit configuration of the timestamp format for the log file. The `%Q` extra format, which adds microseconds subunits, was also implemented. Thanks to Peter Tirsek for contributing the patch [#2208]. 7. **Captive portal**. The `default-url` DHCPv4 option has been replaced with `v4-captive-portal`, as defined in RFC 8910 [#1684]. 8. **Dual-Stack DDNS**. Support for embedded DHCPv6 DUIDs was added within DHCPv4 Client Identifier options, per RFC 4361. This allows Kea to support DDNS in dual-stack environments per RFC 4703 (Sec 5.2). Thanks to John Dickinson for contributing the patch [#1934]. 9. **Performance**. The global parameter lookup has been refactored to provide better performance [#1082]. Several steps have been taken towards making the subnet selection process more performant. While the whole optimization is too large to fit in a single release, this release has the subnet storage structures simplified [#2254]. 10. **Client class options in Config Backend**. Kea core logic now ensures that options belonging to client classes are properly created when classes are read from configuration backends [#2246]. 11. **Infinite valid lifetime**. Update and delete operations on leases no longer raise an error with infinite valid lifetime (used by BOOTP) and MySQL or PostgreSQL backends where timestamps can be limited to 32 bits. [#897] 12. **IPv6 address as URL**. The configuration for an HA peer now accepts an IPv6 address as a valid value for the `url` entry. [#2264] 13. **Flexible Identifiers premium hook**. A race condition in the `flex-id` premium hook library has been fixed [#2251]. The code now uses only MAX_HWADDR_LEN (20) bytes from `remote-id` when extracting the MAC address from relay options [#2201]. 14. **Bugfixes**. For a brief time, the `config-get` command did not return logger information. This has been fixed [#2279]. URLs that have literal IPv6 addresses are now parsed properly, when square brackets are placed around the IPv6 address [#2264]. An issue with custom options [#2283] and PostgreSQL array binding was fixed [#2284]. Minimum and maximum values of lifetimes are no longer skipped when the configuration is retrieved, even when they are the same as the default value [#2222]. Improved handling was implemented for leases with infinite lifetimes. This fixes a problem with BOOTP devices returning after a reboot [#897]. 15. **Documentation**. Several ARM sections were reviewed and updated [#2238]. The Kea ARM now correctly states that DHCPv6 authentication option has code 11, not 10 [#2207]. The examples now correctly show `option-data-list` in the `reservation-add` example [#2233]. The PDF version of the Kea ARM is now available on the Read the Docs platform [#2274]. Small errors in the `status-get` description have been fixed in the Kea ARM [#2216]. A small mistake in built-in help for the configure script has been corrected [#2218]. The developer's guide for D2 and the d2srv library have been updated [#2122]. The d2srv developer's documentation is now included in the release tarballs [#2241]. Several references to EOL versions of Kea have been removed from the Kea ARM [#2142]. The Hooks section of the Kea ARM has been reviewed and updated [#2202]. 16. **Testing and QA**. A CI job that cross-checks database upgrade scripts was added [#2205]. ## Incompatible Changes 1. The output of `kea-admin`'s `lease-dump` command has changed. The generated output is backwards incompatible; any tools that depend on it must be updated. ## 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 hooks libraries are provided under the terms of an 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 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 since the 2.1.1 release for Kea core: 1989. [build] razvan Library version numbers bumped for Kea 2.1.2 development version. (Gitlab #2281) 1988. [bug] tmark Kea core logic now ensures options belonging to client classes are properly created when classes are read from configuration backends. (Gitlab #2246) 1987. [bug] tmark Fixed an issue in PostgreSQL support code that caused asserts when compiled with: -Wp,-D_GLIBCXX_ASSERTIONS. (Gitlab #2284) 1986. [func] fdupont The kea-admin command now accepts extra arguments which are passed to the database command tool, e.g. '--ssl' to 'mysql' with `kea-admin ... -x --ssl'. Quotes are not preserved but multiple arguments can be given. (Gitlab #2225) 1985. [func] fdupont Added support for using files to configure basic HTTP credentials. Instead of configuring a value, it is taken from the content of a file. The new parameters of the Control Agent configuration are: - 'user-file' pointing to a file vs 'user' - 'password-file' pointing to a file vs 'password' - 'password-file' pointing to a file with the secret (which is :) vs 'user' and 'password'. For the High Availability hook library the new parameter is 'basic-auth-password-file' which can be used as an alternative to 'basic-auth-password'. (Gitlab #2006) 1984. [func] andrei Introduced the lease-upload command to kea-admin which can upload leases from a memfile CSV file to a database backend. (Gitlab #2039) 1983. [bug] fdupont Minimum and maximum values of lifetimes are no longer skipped when the configuration is retrieved even when they are the same as the default value. (Gitlab #2222) 1982. [bug] andrei The config for an HA peer now accepts an IPv6 address as a valid value for the "url" entry. (Gitlab #2264) 1981. [func] tomek The default-url DHCPv4 option has been replaced with v4-captive-portal, as defined in RFC8910. (Gitlab #1684) 1980. [func]* andrei The kea-admin lease-dump command now outputs a CSV file that is compatible with the memfile backend. This is useful when migrating from database to memfile. The generated output is backwards incompatible. Any tools that depend on it would need to adapt. (Gitlab #2038) 1979. [bug] fdupont Update and delete operations on leases no longer raise an error with infinite valid lifetime (used by BOOTP) and MySQL or PostgreSQL backends where timestamps can be limited to 32 bits. (Gitlab 897) 1978. [doc] tomek The Kea Administrator Reference Manual now correctly states that DHCPv6 authentication option has code 11, not 10. (Gitlab #2207) 1977. [bug] razvan Use only MAX_HWADDR_LEN (20) bytes from remote-id when extracting the MAC from relay options. (Gitlab #2201) 1976. [func] andrei Added hwtype and hwaddr_source columns to v6 memfile. (Gitlab #2236) 1975. [func] tmark Additional changes and corrections relating to Config Backend were made to the PostgreSQL database schema. In addition, the upgrade scripts were renamed to ensure proper file name ordering. Note that PostgreSQL CB is not yet functional. (Gitlab #2183, #2244, #2245) 1974. [func] fdupont The global parameter lookup has been refactored to provide better performance. Proper return error code (CONTROL_RESULT_ERROR) has been fixed in some cases when trying to apply the new configuration. Old code was using wrong hardcoded '2' value (CONTROL_RESULT_COMMAND_UNSUPPORTED). (Gitlab #1082) 1973. [func] fdupont MySQL backends now can be configured to use the SSL/TLS support to protect connections to the server. New database parameters are "cert-file", "key-file", "trust-anchor" and "cipher-list". The negotiated cipher name is logged so the MySQL service configuration can be checked. PostgreSQL accepts the same parameters but they only trigger the call to the OpenSSL generic initialization in the Pq C-API. (Gitlab #34) 1972. [func] andrei Kea servers now can accept trailing commas in file configurations. While parsing, a warning is printed with the location of the comma to give the user the ability to correct a mistake. (Gitlab #2084) 1971. [func] tmark, jad Added support for embedded DHCPv6 DUIDs within DHCPv4 Client Identifier options per RFC 4361. This allows Kea to support DDNS in dual stack environments per RFC 4703(Sec 5.2). Thanks to John Dickinson for contributing the patch! (Gitlab #1934) And for Kea premium: 137. [func] tirsek, razvan Added new parameter "timestamp-format" in forensic log hook library to be able to configure the timestamp format for log file. Also adds the '%Q' extra format which adds the microseconds subunits. (Gitlab #2208) 136. [bug] razvan Fixed race condition on initialization of flex_id_expr member when using multi-threading in flex id hook library. (Gitlab #2251) 135. [func] fdupont Added SSL/TLS support to the MySQL backend for the forensic logs. New parameters are "cert-file", "key-file", "trust-anchor" and "cipher-list". The negotiated cipher name is logged. (Gitlab #34) 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.