# Kea 1.9.6, March 31st 2021, Release Notes Welcome to Kea 1.9.6, the seventh monthly release of the 1.9 development branch. As with any other development release, use this with caution: development releases are not recommended for production use. This release adds new features, improves existing features, clarifies documentation, and fixes a few bugs. The most notable changes introduced in this version are: **Experimental TLS support**. This release introduces support for Transport Layer Security (TLS) in the Control Agent (CA). The CA can now be configured to accept incoming HTTPS connections. Three modes of operation are available. The first is plain HTTP with TLS completely disabled (this was the only mode available previously). The second mode is encryption, where the CA accepts TLS connections. This is the typical mode when securing a website, where clients and servers are not under the control of the same organization. The third mode (and the default when TLS support is enabled) is mutual authentication between connecting clients and the CA server. In this mode, clients are required to identify themselves using TLS certificates: the clients verify the server's certificate and the server verifies the client's. This work was done in #1661, #1662, #1663, #1664, #1726, #1748, and #1758. The TLS support is considered experimental and currently has a number of limitations: - It is reasonably well tested with some versions of OpenSSL and Boost. Kea uses the Boost ASIO SSL wrapper around OpenSSL. If your Boost or OpenSSL is too old, you may encounter problems and/or get a lower security level. Please refer to the new section 23 (Kea Security) in the Kea ARM for details. - Kea supports two cryptographic libraries: OpenSSL and Botan. This release does not yet support using the Botan library for TLS. The Kea code configured with Botan compiles and unit tests pass, but the TLS support may not be enabled. - The kea-shell tool is written in Python. The primary implementation uses Python 3, but we do have legacy code for Python 2. However, since Python 2 is now EOL, we are not going to update that legacy code with TLS support. This may affect CentOS 7 users. The recommendation is to install Python 3 on your system or use any alternative clients, such as curl, to connect to CA. - TLS support for the High Availability (HA) hook will be available in a future version. - The documentation is incomplete, especially in the new Kea ARM section about security. There's a good tutorial available [in src/lib/asiolink/testutils/ca](https://gitlab.isc.org/isc-projects/kea/-/ blob/master/src/lib/asiolink/testutils/ca/doc.txt) about how to create your own certificates and associated files. The TLS work will continue in the upcoming releases. We do encourage people to test this and report their experience. We're particularly interested in which operating system, OpenSSL or Botan, and Boost versions were used. **Database connection recovery rework**. A new parameter `on-fail` now controls what to do on database connection loss. It has three possible values which govern whether the DHCP service should be disabled and whether Kea should shutdown or continue DHCP service after all the configured tries were exhausted: `stop-retry-exit`, which indicates that DHCP service should stop, attempt to reconnect, and terminate if unable to reconnect; `serve-retry-exit`, which instructs Kea to continue serving DHCP traffic, attempt to reconnect, and terminate if unable to reconnect); and `serve-retry-continue`, which tells Kea to continue serving DHCP traffic, try to reconnect, and continue serving even if reconnection fails. This is particularly useful for forensic logging and configuration backend services. Depending on your specific deployment, you may prefer one strategy over another. #1621 **Multi-threaded HA work**. Kea 1.8 introduced multi-threaded support for DHCP packet processing, which offers substantial performance gains. Unfortunately, if used with HA, the current implementation makes the lease updates sequential, effectively eliminating the benefits of multi-threading. Mitigating this limitation requires substantial rework of how HA connections are established, and in this milestone we made substantial progress towards solving this bottleneck. The MT-HA design has been proposed and reviewed. #1315 Also, the first major element of the solution (a multi-threaded HTTP listener) has been reviewed and merged. #1748 The HA-MT solution is not yet functional, but the experiments and planning phase are complete and we have moved onto the implementation phase. This work will continue in the next releases. **Test farm migration**. While this is not something users are normally concerned with, this project took a substantial amount of our team's time. Our Jenkins test farm was running on ISC-hosted hardware that was aging and was not very powerful. We often struggled with test execution times and were limited in the number of systems we could test on. Our QA team has now set up a new Jenkins instance using Amazon Web Services (AWS). The Kea test environment is exceedingly complicated, with MySQL, PostgreSQL, and Cassandra backends; RADIUS, NETCONF, and DNS servers; multiple Kea instances running in a variety of stand-alone, HA, and load-balancing modes; and various API and traffic generators. We have migrated the great majority of our environment, and while the bulk of the migration is done, not everything is running smoothly yet on the new platform. As such, our testing of this release is more lightweight than usual. This does not mean that the release is broken or has lower quality than usual; it simply means that we were not able to confirm its stability. Use with caution! #1774, #1761, #1773, #1770, #1751, #1757, #1752 **Design for incremental lease updates**. The Stork project would like to be able to provide more insight into leases being assigned, but the current API is not well-prepared for it. It can enumerate all leases, but using existing calls periodically would incur a substantial burden on a Kea server. As such, a design for cached mode and incremental lease updates has been written. #1230 **kea-admin can now use a non-standard port** kea-admin commands can now be run on databases exposed through custom ports using `-P` or `--port`. #1674 **Bug fixes**. We fixed a problem where DHCP service would remain disabled after the HA hook was unloaded. #1697 Distcheck was failing due to a missing kea_conn Python module. #1775 There was a faulty locking system in DB_LOG logger, used in forensic logging. #1719 **Documentation updates**. A variety of documentation updates has been completed. #1717, #1726, #1696 ## Incompatible Changes There are no backward-incompatible changes in this release. ## Known Issues For details on known issues, visit: https://gitlab.isc.org/isc-projects/kea/-/wikis/known-issues-list And for the list of issues marked as bugs: https://gitlab.isc.org/isc-projects/kea/issues?label_name%5B%5D=bug ## 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 minor version number. The current stable release is 1.8.2. The older stable version of 1.6.3 is also available. 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 minor version number: for example, 1.9.0 is a development release. Subsequent releases on the same minor release branch get numbered with 1.9.1, 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 (ARM). 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 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 at: 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 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 on 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 since the previous release of 1.9.5: ``` 1883. [build] andrei Bump library versions for Kea 1.9.6 release. (Gitlab #1772) 1882. [func] razvan Implemented database connection recovery for forensic logging. To achieve this, the "on-fail" connection parameter has been added to control the action performed on connection loss. The supported values are "stop-retry-exit", "serve-retry-exit" and "serve-retry-continue". They indicate if the server should disable the service on connection loss ("stop-retry-exit") or if on recovery failure the server should shut down ("stop-retry-exit" and "serve-retry-exit") or continue ("serve-retry-continue"). The default value used (if not configured) is "stop-retry-exit" for lease, host and config backends, and "serve-retry-continue" for forensic log. (Gitlab #1621) 1881. [func] fdupont Moved errors about URLs using names (vs addresses) or https (vs http) scheme in High Availability hook configuration from connection opening time to configuration time. (Gitlab #1758) 1880. [build] fdupont TLS support is now reported by configure in the cryptographic backend section. (Gitlab #1774) 1879. [func] fdupont The Control Agent now supports TLS/HTTPS. This works with OpenSSL and there are known problems with Botan, which will be addressed in the future. (Gitlab #1662) 1878. [bug] razvan Request enabling DHCP service when the HA hooks library is unloaded. It may remain disabled if it had been disabled outside of the HA hooks library. Prior to this change, if the HA hooks library disabled the DHCP service it would always remain disabled after the hooks library was unloaded. (Gitlab #1697) 1877. [func] fdupont kea-shell supports TLS/HTTPS. This is limited to the python 3 version i.e. if kea-shell is configured with python 2 it still works in 1.9.6 but raises an error if a new TLS/HTTPS argument is specified. (Gitlab #1663) 1876. [doc] fdupont Added documentation for TLS/HTTPS support. (Gitlab #1664) 1875. [func] fdupont TLS/HTTPS support was added to asiolink and http libraries. (Gitlab #1661) 1874. [doc] marcin Added notes in the ARM highlighting that the address and delegated prefix pools must be split when HA load-balancing mode is used. (Gitlab #1726) 1873. [func] andrei kea-admin now accepts the -P|--port parameter with a custom port used to connect to the database. (Gitlab #1674) ``` Thank you again to everyone who assisted us in making this release possible. We look forward to receiving your feedback.