# Kea 1.9.1, October 28th 2020, Release Notes Welcome to Kea 1.9.1, the second monthly release of the new 1.9 development branch. As with any other development release, use this with caution. Development releases are not recommended for production use. This first development release tackles an assortment of improvements and bug features that didn't make it into 1.8, but also prepares for larger features coming in the 1.9 branch. The most significant changes introduced in this version are: 1. **Multiple MAC reservations for the same IP**. Having more than one reservation for the same IP may cause conflicts, thus Kea considers it a configuration error and doesn't allow it. However, if the client has two interfaces, but at any given time only one of them will be connected, it is useful to have two reservations. To enable this mode of operation, a new parameter ``ip-reservations-unique`` has been added. The default behavior remains unchanged. Multiple reservations are forbidden unless explicitly allowed. Care should be taken to never allow a situation where two or more devices are active with reservations for the same IP. Kea has no way to meaningfully resolve such a conflict. When in doubt, don't use this feature! #1428 2. **DDNS improvements**. It is now possible to configure Kea to perform DNS updates when the client renews a lease. Typically this is redundant, as the DNS update done during initial client configuration is sufficient. However, if there were problems with the DNS (e.g., misconfigured TSIG keys or perhaps the server was down), it may be useful to turn on the new ``ddns-update-on-renew`` parameter. This forces all DNS records to be updated for active clients. After some time (roughly equal to the value of the ``renewal-timer``), this ensures that all records for current clients are properly updated. #1385 By default, Kea generates DHCID DNS records to keep a record in the DNS of the current owner of an address. When attempting to do updates, Kea (per the Conflict Resolution protocol as defined in RFC4703), checks for the presence and content of the DHCID records. Kea can now be optionally told to ignore the records, using a new ``ddns-use-conflict-resolution`` parameter. The DHCID records are still created, but their presence does not prevent Kea from overwriting older records. Implemented this way, Kea does not have a history gap if conflict resolution is disabled and later enabled. #1386 3. **Fix for High Availability (HA) hook with MySQL**. With the introduction of multi-threading support, the MySQL lease update mechanism has been updated slightly to protect against two or more threads updating the same lease. Sadly, under some circumstances this caused the HA hook to reject lease updates sent by its partner. This problem has now been fixed. #1434 4. **Authorization improvements**. The Control Agent logs every authentication attempt, showing which user authorized the command to be executed. That information was previously available at the verbose ``DEBUG`` logging level; now the information is logged at the ``INFO`` level. #1450 Logging entries have been updated to redact HTTP basic authentication passwords. #1459 5. **Performance statistics**. A new statistic has been added that reports packet queue utilization. It reports an average for the last 10, 100, and 1000 packets. This uses an approach similar to the Unix ``top`` tool, which returns CPU utilization for the last 1, 5, and 15 minutes. This may be useful for fine-tuning Kea performance and its queue length. #1306 6. **Better error messages for broken JSON**. The JSON parser has been improved to provide more meaningful error messages when receiving malformed JSON. This may be useful for finding syntax issues such as missing quote marks and incorrectly escaped characters. #151 7. **Doc updates**. We have made numerous improvements in the Kea documentation. There are new ``all-options.json`` example configurations for DHCPv4 and DHCPv6 that demonstrate how to configure all options currently defined in Kea, including defining custom and vendor options. They are available in the ``doc/examples/kea4`` and ``doc/examples/kea6`` directories. #1298 Database communication can sometimes fail for various reasons and Kea has a mechanism to reconnect. However, the parameters for controlling this were hard to find. Several configuration examples have been updated, illustrating the use of the ``max-reconnect-tries`` and ``reconnect-wait-time`` parameters. #827 The DHCPv6 documentation has been extended to clearly list the options that are set by Kea itself, that are not supposed to be manually configured by the administrator. Such a list is useful to answer the question of whether a given option is supported by Kea. #1436 Two options (the link selection sub-option and the subnet selection option) have been supported by Kea for a long time, but their support was not clearly documented. This has been corrected. #1460 Introductory text about host reservations and how to use them has been added in the ARM. #1299 Several ``pd-exclude`` examples have been corrected. #1454 A section about configuring RADIUS to use non-standard formatting for MAC addresses has been added. The particular example uses Cisco's preferred format of MAC addresses as ``0123.4567.89ab``, but other syntaxes can be used as well. #1441 8. **Build improvements**. Our internal build farm has been extended with Alpine 3.12, and our build tool ``hammer`` has been extended to support this OS. #1429 ## Known Issues See https://gitlab.isc.org/isc-projects/kea/-/wikis/known-issues-list for details. ## 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 major version number. The current stable releases are 1.8.0, with an old stable version of 1.6.3. 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 major version number: for example, 1.9.0 is a development release. We will continue our development work with 1.9.1, then 1.9.2, and so on. 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 https://kb.isc.org/docs/aa-00896. ## 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 https://gitlab.isc.org/isc-projects/kea/issues. ## 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 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: 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, 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 https://gitlab.isc.org/isc-projects/kea. 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). Also we would 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 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. If you have any comments or questions about working with Kea, please share them to the Kea Users List (https://lists.isc.org/mailman/listinfo/kea-users). Bugs and feature requests may be submitted via GitLab at https://gitlab.isc.org/isc-projects/kea/issues. ## Changes The following summarizes changes and important upgrade notes since the previous release (1.9.0). ``` 1826. [build] razvan Library version numbers bumped for Kea 1.9.1 development version. (Gitlab #1481) 1825. [doc] andrei Examples for option definitions, option data, standardized option spaces other than "dhcp[46]", custom option spaces, option embedding under doc/examples/kea[46]/all-options.json. (Gitlab #1298) 1824. [func] tmark Added a new parameter, ddns-use-conflict-resolution, to kea-dhcp4 and kea-dhcp6. This parameter is passed per request to kea-dhcp-ddns which uses it to determine whether or not conflict resolution rules (see RFC 4703) are followed for that request. The default value is true. Disabling conflict resolution should only be used after careful consideration. (Gitlab #1386) 1823. [doc] tomek Updated options documentation for DHCPv4 and DHCPv6. (Gitlab #1436, #1460) 1822. [func] fdupont When multi-threading is enabled the status-get command displays the average lenght of the multi-threading packet queue for last 10, 100 and 1000 packets. (Gitlab #1306) 1821. [func] anonymous, fdupont The forensic log hook library now logs release and decline events. (Gitlab #1445) 1820. [bug] razvan Fixed lease update when using HA and lease_cmds hooks with database backend. Previously, HA updates were rejected because the database backend rejects operations on the lease if the old expiration time is different than what it is already stored, to act as a protection mechanism for parallel updates from several threads or processes. (Gitlab #1434) 1819. [func] fdupont Improved error messages for bad escapes in JSON strings. (Gitlab #151) 1818. [doc] andrei Add to the reservation documentation: * instructions on how to choose "reservation-mode" * priority of "reservation-mode" specified at all levels * priority of file reservations vs database reservations (Gitlab #1299) 1817. [func] fdupont Redact control agent logs to hide basic HTTP authentication passwords from the configuration files. Note that when HTTP headers are logged credentials are present in clear text. (Gitlab #1459) 1816. [func] fdupont The message logged when basic HTTP authentication succeed is now informative (was DEBUG, is INFO now). (Gitlab #1450) 1815. [bug] marcin Fixed libdhcpsrv build failures when building without database backends. (Gitlab #1468) 1814. [func] marcin Added ip-reservations-unique global parameter which controls whether or not it is allowed to create multiple host reservations for the same IP address or delegated prefix. By default, it is not allowed to create multiple reservations for the same lease within the same subnet. This change facilitates the use case in which a single host can communicate with the DHCP server over multiple network interfaces but should be assigned the same reserved lease regardless of which interface is used. (Gitlab #1428) 1813. [func] tmark A new parameter, ddns-update-on-renew, has been added to kea-dhcp4 and kea-dhcp6 configuration. When true, the server will always update DNS when a lease is renewed even if the DNS information for the lease has not changed. The prior, and now default, behavior is for the server to only update DNS for a renewing lease if its DNS information has changed. (Gitlab #1385) 1812. [doc] andrei Document how MAC addresses can be formatted for use as attributes in RADIUS authentication (Gitlab #1441) 1811. [func] fdupont Two new parameters were added: cache-threshold and cache-max-age to the DHCPv4 and DHCPv6 global scopes. They will govern the upcoming cache thresfold feature. The parameters can be set and retrieved, but they're not used yet. (Gitlab #1418) ``` Thank you again to everyone who assisted us in making this release possible. We look forward to receiving your feedback.