[Kea-announce] Kea 1.9.1, a new development release of Kea, is now available

[Michael McNally]

Internet Systems Consortium is pleased to announce the release of Kea 1.9.1.

                                 -  -  -

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