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