# Kea 1.9.0, September 30th 2020, Release Notes

Welcome to Kea 1.9.0, the first 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 was used to tackle an assortment
of improvements and bug features that didn't make it into 1.8, but
also to perform some preparatory work for the larger features coming
up in in the 1.9 branch.

The most significant changes introduced in this version are:

1. **Local access control**. This version introduces basic
authentication. It is now possible to configure a list of credentials
(pairs of user identifiers and passwords) that the user or script
must provide to use Kea's API. It uses the HTTP protocol feature,
defined in RFC7617. Right now, the capabilities are simple (a list of
credentials stored as plain text in a configuration file) and have
some serious limitations, but we expect to expand them soon. A new
hook point is expected, with a hook library that will take advantage
of access control and provide more flexible credentials management.
For details, see #1304.

2. **Role based access control**. The ultimate goal here is
full-scale role-based access control (RBAC). As a preparatory step
towards RBAC, the JSON files that describe API commands have gotten a
new `access` field that specifies what kind of access right is
required to use a given command. That capability is not used yet, but
it will be in future releases. #1240

3. **Preallocation**. All existing Kea versions use an iterative
algorithm to pick the next lease. This works very quickly if there
are plenty of addresses, but it gets increasingly slow when running
with high pool utilization (i.e., when the pool of addresses is
almost depleted). Another problem is that the iterative approach
makes predictions regarding the next address to be assigned much
easier, which may be used to perform certain attacks, such as network
scanning. We are working on a solution that will address both issues.
The overall idea is that Kea will "shuffle" the available leases and
order them randomly at start-up or reconfiguration. This will solve
the two aforementioned problems: Kea should both maintain its
performance even when running low on available addresses and provide
better distribution throughout the address space. In this release, we
made the first two steps towards that goal: we came up with a design
(#1126) and implemented the storage for preallocated leases. The
feature is not usable yet. #1415

4. **IPv6-only preferred networks**. In modern dual-stack networks,
dual-stack devices are capable of obtaining both IPv4 and IPv6
connectivity. A new mechanism has been defined in the IETF and will
soon be published as RFC8925. The idea here is that compatible client
devices will ask for IPv6-only as the preferred option in their
DHCPv4 requests. If the network prefers devices to run in IPv6-only
mode, the DHCPv4 server will send back an option that says so. The
compatible clients' devices will then shut down their IPv4 stack for
the period specified by this option's value. Kea now supports this
capability. #1351

5. **Flex-option improvements**. It is now possible to specify the
`csv-format` parameter for flex-option. The option value can now be
interpreted as plain text, the same way as for options in the
configuration file. #1373, #1374, #1430

6. **API: fetching host reservations without subnet-id**. Two
existing API commands, `reservation-get-by-id` and
`reservaton-get-page`, have now been extended. The subnet-id
parameter is now optional. The related improvements are available in
the premium `hook_cmds` library. #1163

7. **Vendor option improvements**. A bug has been fixed regarding
sending vendor options defined in host reservations. Several errors
in the configuration examples in the ARM have been corrected. #1025

8. **DDNS improvements**. The DNS update code behaves better when
there is a shared network
and the code initially selected one subnet, but then later determined
that a different subnet would be used
#1389. The DHCPv4 daemon now correctly updates DNS when a client
returns for a lease after the lease has expired.  Previously, the
server removed the entries but then failed to add them unless the
host name changed.
This change also eliminates redundant DNS removes when expired leases
are reclaimed and given to different clients #1409. The
`qualifying-suffix` parameter is now deprecated and will be removed
in future releases. #1197

9. **Cassandra**. The Cassandra code has been updated to no longer
use the deprecated `cass_cluster_set_reconnect_wait_time` function.
This fixes the compatibility with the latest Cassandra cpp-driver.
#802, #1399

10. **kea-admin**. The kea-admin tool now handles error reporting
better, in particular for MySQL and PostgreSQL. Previously, with
certain errors, the exit code used to be 0 (all ok). It now returns 1
(error) when encountering problems. #828

11. **Multi-threading**. An outdated log message claiming that
multi-threading support is experimental was accidentally left in the
code. It has now been removed. #1431

12. **Documentation updates** A new table with DHCPv4 options that
Kea supports and provides on its own has been added. This is mostly
useful for cases when the reader wants to find out if a given option
is supported by Kea, but the option itself should not be specified
directly. A good example is a message-type option 53. #1323 Several
examples for DHPv6 configurations have been updated #1397, and
several `lease4-get-*` and `lease6-get-*` commands have improved
documentation. #1392

13. **Build improvements**. Our build automation tool, `hammer`, has
been improved to better handle building on CentOS 8, especially in
case of network failures. #1432 Obsolete copies of man pages were
removed. #1271

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

```
1810.	[build]		fdupont, razvan
	Bump up libs version for Kea 1.9.0 release.
	(Gitlab #1400)

1809.	[func]		razvan
	Added csv-format option to flex_option hook to be able to
        insert option data in csv format. The implicit value
        is false, maintaining compatibility with the previous default
        raw format.
	(Gitlab #1373)

1808.	[func]		razvan
	Support for new IPv6-only-preferred option for DHCPv4 has been
	added. It lets Kea to signal to compatible devices that the
	IPv6 connectivity is available and they can disable their
	IPv4 stack. This implements support for
        draft-ietf-dhc-v6only-08, which is expected to be soon
        published by IETF as an RFC.
	(Gitlab #1351)

1807.	[doc]		tomek
	Added separate table with DHCPv4 options that are governed by
Kea
	itself, rather than configured by administrator.
	(Gitlab #1323, #1398)

1806.	[bug]		tmark
	The DNS update code behaving better when there is a shared
        network and the code initially selected one subnet,
        but then later determined that a different subnet will be used.
        There is still a corner-case in DHCPv6 if the client requests
        multiple addresses or multiple prefixes and some of them
        is serviced from one subnet and some from another.
	(Gitlab #1389)

1805.	[doc]		tomek
	API documentation for lease4-get-* and lease6-get-* commands
	has been updated.
	(Gitlab #1392)

1804.	[func]		fdupont
	Added a new reservation-get-by-id command to retrieve all host
	reservations with an identifier value and type. Made the
	subnet-id optional in the reservation-get-page command.
	(Gitlab #1163)

1803.	[doc]		fdupont
	Corrected Kea ARM sections describing how to send DHCPv6
	Vendor-specific Information Option (code 17) with sub-options.
	(Gitlab #1025)

1802.	[bug]		fdupont
	Removed the bug which allowed for repeating the same
        configuration parameter multiple times in the same scope.
        The second occurrence of the parameter overwrote the first
        occurrence causing server misconfiguration. Starting from
        this change an error is raised when the same parameter
        occurs multiple times in a given scope the location of
        the first value.
	(Gitlab #1102)

1801.	[doc]		fdupont
	Moved JSON files describing commands to the share directory
	and adding a new access entry taking read or write values.
	(Gitlab #1240)

1800.	[func]		fdupont
	Added support of basic HTTP authentication in HTTP library,
	control agent, kea shell and high availability hook.
	(Gitlab #1304)

1799.	[bug]		fdupont
	Checked execution of queries to get schema versions of MySQL
	and PostgreSQL database in kea-admin.
	(Gitlab #828)

1798.	[bug]		tmark
	kea-dhcp4 now correctly updates DNS when a client
	returns for lease after the lease has expired.  Prior
	to this, the server would remove the entries but then
	fail to add them unless the hostname (or FQDN) changed.
	This change also eliminates redundant DNS removes when
	expired leases are reclaimed and given to different clients.
	(Gitlab #1409)
```

Thank you again to everyone who assisted us in making this release
possible.

We look forward to receiving your feedback.