# Kea 1.5.0-beta1, Nov 9 2018, Release Notes Welcome to the first beta release of Kea 1.5.0. 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 servers, an example shell client to connect to the CA, a NETCONF daemon that is able to retrieve YANG configuration and updates from Sysrepo, and a DHCP performance measurement tool. Both DHCP servers fully 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 can be stored in a MySQL, PostgreSQL or Cassandra database; it can also be stored in a CSV file. Host reservations can be stored in a configuration file; they can also be stored in a MySQL, PostgreSQL, Cassandra databases and to some degree also retrieved from a RADIUS server. Kea DHCPv4 and DHCPv6 daemons provide support for YANG models, which can be configured over NETCONF protocol. Version 1.5.0-beta1 adds the following features to Kea: * YANG models and NETCONF support - [YANG](https://tools.ietf.org/html/rfc6020) is very popular configuration language that allows to define a model, which is a configuration syntax (think of this as database schema) for various networking devices. You can then store actual configuration in that model (think of this as data stored in your database). This configuration then can be modified using either local command line tools (such as sysrepocfg) or remotely using [NETCONF](https://tools.ietf.org/html/rfc6241) protocol. Kea 1.5.0-beta1 introduces support for [Sysrepo](http://www.sysrepo.org/), which provides YANG data models and YANG configuration storage. It currently supports both startup and running datastores. This may become very useful if you want to experiment with your Kea configuration, but don't want want to commit it permanently. A new daemon kea-netconf has been introduced in this release. It provides three services. First, it can load the initial configuration from Sysrepo startup datastore and then apply it to Kea DHCPv4 and/or DHCPv6 servers. Second, it can monitor running datastore and pick up any changes that may appear. Third, before you commit any changes to sysrepo, it may retrieve the proposed configuration from Sysrepo, send it to Kea DHCP servers using config-test and then report back to Sysrepo whether the new configuration is valid or should be rejected. YANG and NETCONF is a complex environment. This is the first release and we are hoping to expand Kea capabilities. We currently have four models defined (kea-dhcp4-server, kea-dhcp6-server, kea-dhcp-ddns, kea-ctrl-agent), but only the first two are supported. Beta testers using CentOS may find [these installation notes for Netconf on CentOS](https://kb.isc.org/docs/kea-build-on-centos) helpful. * Global host reservations - Kea 1.5 introduces support for global host reservations. Previously reservations were always subnet specific, so if you had a mobile client visiting 10 networks and you wanted to reserve something, such as special options or parameter values, you would have to create 10 reservations. Right now it is possible to specify that certain subnets (or even all of them) should use global reservations. Caution is advised when assigning addresses this way. Kea does not check correctness of the addresses being reserved, so this feature is mostly intended to be used for options and other configuration parameters, but not addresses. * Congestion control - In order to help mitigate congestion during heavy DHCP traffic conditions we have added an experimental feature, "dhcp-queue-control". When enabled, kea-dhcpX servers will read in-bound packets from the interface sockets in a separate thread and place them in queue. The primary application thread will process packets from this queue. The packet queue implementation is both configurable and dynamically replaceable with a plug-in loaded via hook library. For details, see [congestion control wiki page](https://gitlab.isc.org/isc-projects/kea/wikis/congestion-control). BETA DISCLAIMER: This feature will be enabled in 1.5.0beta. For 1.5.0 final there may be an option to disable it. Initial testing has shown that this new feature reduces throughput at very high congestion levels, although at lower congestion levels it ensures Kea is focused on processing current, rather than stale, requests. * High Availability improvements - High Availability has been introduced in 1.4. Release 1.5 brings in a number of performance, resiliency and overall robustness improvements. A new mechanism was introduced that synchronizes leases in chunks rather than all of them at once. This approach makes possible to synchronize large subnets without risking timeouts. Some timeouts are now configurable. A sanity mechanism has been implemented that checks leases being loaded from file or received from HA partner. Depending on its configuration it can be forgiving (accepts leases and prints warnings if they're not matching current configuration), merciless (reject anything that doesn't match current configuration) or helpful (will try to fix certain lease aspects, so they match current configuration). * Configuration Backend design - The Configuration Backend feature is now planned to be implemented in Kea 1.6.0. It will provide the ability to use a database as a source of configuration information for the Kea DHCP servers. Even though the Configuration Backend is not functional in the Kea 1.5.0 release, the design for this feature was created and some basic elements implementing this design are included in the current release. The most prominent change is the update of the MySQL schema to include new tables, constraints and indexes to be used by the Configuration Backend feature once it is implemented. These elements are currently unused, but they will be created in the existing database instances once the MySQL database is upgraded to the version supported by Kea 1.5.0 release. The design of the Configuration Backend is available at https://gitlab.isc.org/isc-projects/kea/wikis/designs/configuration-in-db-design . * Authoritative flag for DHCPv4 - This popular feature of ISC DHCP now comes to Kea. Kea DHCPv4 server now provide a flag that determines whether the server is authoritative or not. This lets two servers coexist on the same link without NAKing each others clients. Thanks to Sebastian Schrader for submitting a high-quality patch implementing this feature. * User contexts in leases - Lease objects and lease backends can now store additional 'user context'. User context can be any arbitrary data as long as it is in JSON format. Database schemas updated. * New REST API documentation - By popular demand, Kea team spent some time documenting existing RESTFul and control channel API. Kea now supports 71 commands and each of them has its own section that covers overview, daemons that support it, hook library name if provided by a hook, first Kea version where it appeared, syntax of the command itself and syntax of the response, although the responses are not fully documented for some commands yet. Lists ordered alphabetically, by server, by hook are provided. * Client classification commands - A new Kea Premium extension library, Class_cmds, enables listing, adding, updating, and deleting client classes configured for a given DHCPv4 or DHCPv6 server. ## Gitlab migration - Since the last Kea release we have migrated the Kea project to a new development system, at https://gitlab.isc.org/isc-projects/kea. We are now tracking issues, archiving design documentation and providing the source repo at this new site. Our old Trac site is still available at https://oldkea.isc.org for reference. ## License Kea 1.5.0-beta1 is released under the Mozilla Public License, version 2.0. https://www.mozilla.org/en-US/MPL/2.0 The premium hook libraries are provided in source code form, under the terms of an End User License Agreement (you are not permitted to redistribute). ## Testing premium hooks ISC Kea support customers will receive tickets inviting them to beta test the premium hooks, which are included with the support subscription. If you are interested in testing premium hooks and do not have a Kea support contract, please contact info at isc dot org to apply to beta test. We will give you a 100% discount coupon in exchange for your help in improving the software. Please let us know when you email which premium hook package(s) you want to test. ## Download The Kea 1.5.0-beta1 source may be downloaded from: https://ftp.isc.org/isc/kea/1.5.0-beta1/kea-1.5.0-beta1.tar.gz A PGP signature of the distribution is at https://ftp.isc.org/isc/kea/1.5.0-beta1/kea-1.5.0-beta1.tar.gz.sha512.asc The signature was generated with the ISC code signing key which is available at https://www.isc.org/about/openpgp ISC provides detailed documentation, including installation instructions and usage tutorials in the Kea Administrator Reference Manual. Documentation is included with the installation or via https://kb.isc.org/docs in HTML, plain text, or PDF formats. ISC maintains a public open source code tree, wiki, 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'd like 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 configuration or use case. Also we would like to hear whether the documentation is adequate and accurate (please open tickets for documentation omissions and errors). 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 maintenance is funded with support subscriptions. For more information on ISC's DHCP software support see https://www.isc.org/dhcp-subscription/. 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 the ticket tracking system at https://kea.isc.org. ## Changes The following summarizes changes and important upgrade notes since the previous release (1.4.0-P1). 1477. [build] marcin Bumped up libraries version numbers for Kea 1.5.0 beta release. (Gitlab #261,!119, git 54d63139048e7fe2dd0384b547ed6f8b96ff0e8f) 1476. [func] tmark Added initial implementation of congestion handling to kea-dhcp4 and kea-dhcpt6. This adds a new top level element to the server configurations, "dhcp-queue-control". Both servers will now read client packets from interface sockets in a separate thread queueing them for server level processing. For Kea 1.5-Beta this feature is always on. (Gitlab #42, !103, git 09d5ffebc8f9bfab2ab99c384eec9c3a3c915f39) 1475. [func] sebschrader Add authoritative feature for DHCPv4 from ISC DHCP: requests from unknown clients are dropped (default/previous behavior) or answered with DHCPNAK (new behevior with new authoritative flag set to true for the subnet). Patch proposed by Sebastian Schrader. (Gitlab #66, !115, git 0fc1b767826f214475025d8631227970de368de5) 1474. [doc] godfryd Updated list of supported operating systems. (Gitlab #205, !109, git 73253af554cf48434798282f8440a99b1494fd04) 1473. [doc] tomek Outdated FAQ section removed from the User's Guide. (Gitlab #118, !113, git 7d079384bd5f49e0e36a571ee964bfd7d6ebd25d) 1472. [bug] marcin Timeout is now reported by the HTTP client when connecting to the server takes too long. This eliminates HTTP client hangs when firewall is misconfigured and causes connection to never be established. This issue was found during Kea High Availability testing. (Gitlab #26,!106, git 9724823f160af0ef5e8ccdf779087ff08a04457a) 1471. [bug] lmasarati Fixed a bug in kea-admin that ignored specified remote hostname. Thank you to lmasarati and Thorsten Krohn for reporting it and proposing a patch! (Gitlab #61, #138, !114, git 901cac7dc85ad8dacf631bf3a5c266eefeb3e6a1) 1470. [func] marcin Improved lease database synchronization mechanisms in High Availability hooks library. The new implementation uses lease4-get-page and lease6-get-page commands to fetch leases from the partner server. This prevents timeouts occurring during long synchronizations as well as decreases CPU and memory consumption on the HA enabled servers during lease database synchronization. (Gitlab #78,!85, git c54ea216463dcc6df693c96c4a5f82c0fbec2ff6) 1469. [doc] marcin, fdupont Documented new class_cmds premium library which is used to modify client class configuration of the DHCP servers. (Gitlab #64,!41, git c1c1d0b71496d81b330a8c1eb95996bbf634ada0) 1468. [build] wlodek make distcheck fix. (Gitlab #202, !111, git 5d8fb5f7af5fa36f4cb2b89f10631683b2e230d5) 1467. [doc] fdupont, tomek Doxygen errors fixed. (Gitlab #180,!93, git d12fb04d71c3b2d0e84ebb2c957334454b5705c4) 1466. [func] fdupont Added random number generation in services provided by the crypto library (and ultimately by the crypto backend, i.e. Botan or OpenSSL). (Gitlab #29,!9, git 609ddc69613dc828b3d93673d61a2c259c3944aa) 1465. [build] marcin Removed libkea-process dependency on MySQL, Postgres and Cassandra libraries. (Gitlab #194,!104, git bcce7d3c2226c10218d537c4688344c3b7f8c84a) 1464. [build] marcin Exclude mysql_cb hooks library from the Kea 1.5.0 release. This library will be added back in Kea 1.6.0 release. (Gitlab #93,!105, git 49572aa300ea2b25712d7e8cea0dd0df34faf7ee) 1463. [bug] tmark Added missing parsing logic for the reservation-mode value, "global", to kea-dhcp6. The parsing logic was somehow omitted and caused kea-dhcp6 configuration parsing to fail on values of "global". (Gitlab #129,!55, git 00352d701f61274f0993b468a413af6c5623af3d) 1462. [build,doc] tomek,sgoldlust,vicky Kea REST API is now documented. Thanks to Suzanne Goldlust for providing descriptions for great majority of commands and to Vicky Risk for review and corrections. Also, docgen, a new tool for documentation generation has been written. (Gitlab #10,!3, git 5d2e4d6fcc182a19eafa895abc35b1aee599fd23) 1461. [doc] marcin, fdupont Added new sample configurations providing all parameters at the exception of host reservations for DHCPv4 and DHCPv6 servers for testing of configuration managers. (Gitlab #130,!89, git 4bc7e0dbe4804f63c51d100a8f724327e3d3a936) 1460. [func] tmark While kea-dhcp4 and kea-dhcp6 configuration parsing supports configuration backend elements "server-tag" and "config-control", use of these parameters has been disabled. Developement of this feature will resume after Kea 1.5 release. (Gitlab #101,!87, git 4292a7ef7ab268826f846812e7320e1fe1fc46ef) 1459. [func] marcin Implemented libdhcp_mysql_cb hooks library which provides Configuration Backend functionality for MySQL. (Gitlab #93, git 98456608056b3361352b3127767138845eeb5d00) 1458. [func] fdupont Control sockets for kea-netconf has been implemented. The code is not functional yet, but the capability of the kea-netconf daemon to communicate with CA, D2, DHCPv4 and DHCPv6 daemons is there. (Gitlab #153,!60, git 11486e255aef704114645f8e7c5fee9c3abf9e76) 1457. [func] tmark Both kea-dhcp4 and kea-dhcp6 configuration parsing support new, server-level configuration elements "server-tag" and "config-control". While these elements will parse, they are not yet used by the servers. (Gitlab #32,!23, git c0727407da8d749d9fb51d873a725369800c967b) 1456. [build] tomek Extended Kea version is now stored in a separate file for build performance reasons. (Gitlab #137,!42, git 87479e979ca3d3025cb4129ace991a59e32e0f62) 1455. [func] fdupont Implemented hexstring(value, separator) operator that can be used in any expression, such as client classification, flex-id or RADIUS attribute. (Gitlab #67,!34, git 004d9a29db09b1c203c52e23585bd275c52095fa) 1454. [func] fdupont Unused interface-id and rapid-commit parameters removed from DHCPv4 parser. (Gitlab #116,!24, git 7e47292f10acb9179241c991d3591e9bfa47c37d) 1453. [func] marcin Updated MySQL schema to facilitate Kea Configuration Backend feature. (Gitlab #89,!22, git e28c0c7b3e7a7729167cdad993f634ed1f0ac53b) 1452. [func] marcin Implemented libkea-cb library which includes basic class hierarchy for the Kea Configuration Backend. (Gitlab #28,!20, git fb5c031ecaf4182e56f62874e9a6bd4c1d755a77) 1451. [build] tmark Resolved a namespace issue with std::distance() in libdhcp++.cc when building with Boost 1.68. Thanks to Huy Vu and Khem Raj for reporting and suggesting a fix. (Gitlab #109,!21, git 1fd301f998129e9926ffa35eac27768ae150633d) 1450. [build] tomek Dependencies improved. libkea-process no longer requires libkea-dhcpsrv. As a result, D2 and CA are no longer linked with libkea-dhcpsrv. (Gitlab #25,!14, git cdb3a6f2d98a303b80433df7e0d5698c77897b7f) 1449. [func] tmark Modified Kea 1.5.0 database upgrade scripts to convert subnet ID values of 0, to either null (MySQL and Postgres) or 0xFFFFFFFF (CQL), in existing host reservations. This is done to accomodate support for global host reservations. (Gitlab #15,!11, git 25b54fd9ced4c6d3a2c8ceff9cc7c866b56da2c1) 1448. [build]* marcin Created new Kea libraries: libkea-database, libkea-mysql, libkea-pgsql and libkea-cql. Some database specific code was moved from libkea-dhcpsrv to those new libraries. (Gitlab #92,!13, git 5feb6b8a53675c27715e9e8fbeb312bd6eb17547) 1447. [doc] tmark Updated Kea Administrators's Guide with discussions of the use of subnet ID parameters in hook library commands. (Gitlab #14,!15 git# 4a7da8069feab1e21132689a9368f8ccb4174683) 1446. [func] tmark kea-dhcp6 now supports global host reservations and a new global reservations-mode . Prior to this reservations could only be specified per subnet. This is supported by by Memfile, MySQL, PostgreSQL, and Cassandra host data sources. (Gitlab #13,!6, git# a5484c4d8852662be7da1e6e8b1d4c1a19e6502f) 1445. [func] tomek Implemented initial skeleton version of the kea-netconf tool. Currently it can't do anything, but the build system is now capable of detecting sysrepo (use --with-sysrepo in configure), there's a very basic documentation and unit-tests. (gitlab !1, git 89ff2093811d65220d99dc2a6516375c4ec953dc) 1444. [bug] tomek keactrl version tests now work properly on macOS. (Gitlab !5, git a8c385e1507ffd101f65b445783b0355b01decce) 1443. [func] tmark kea-dhcp4 now supports global host reservations and a new global reservations-mode . Prior to this reservations could only be specified per subnet. This is supported by by Memfile, MySQL,PostgreSQL,and Cassandra host data sources. (Trac #5705, git f991cffd06add941f8bf2937232f51d597623e21) 1442. [func] MayyaSunil Implemented new queries for IPv6 leases by DUID. (Github #99, git c20b5248da1283e596e35ad057ae242f4d613965) 1441. [func] marcin Added log message indicating that the control socket has been opened by a server. (Gitlab #8, git 3dbaf4917bea112466f1ee5726870c545950e114) 1440. [func] tmark The internal represenation of an "unused" subnet-id has been changed from zero to 0xFFFFFFFF. The largest, valid value for a subnet's ID is now 0xFFFFFFFE. Three new constants have been added so subnet_id.h: isc::dhcp::SUBNET_ID_GLOBAL isc::dhcp::SUBNET_ID_UNUSED isc::dhcp::SUBNET_ID_MAX which should be used in code/hooks in place of hard-coded values. (Trac #5704, git 90fe9ca2cd6f63bcc7168bdc3786677db57b65ec) 1439. [func] tomek keactrl and kea-admin tools can now report version. (Gitlab #9, git 4a00ab5d4b9ac9193fc5f924149aeaca7a88e2ef) 1438. [func] tomek subnet-id parameter is now optional in lease4-add, lease6-add, lease4-update and lease6-update commands. If not specified or its value is zero, Kea will attempt to figure out the correct value of subnet-id. If there is no matching subnet configured, the lease will be rejected. (Trac #5683, git a8ce7a78b5b294e6bce02de887552a1e4593db4e) 1437. [func] tomek DHCPv4 and DHCPv6 servers are now able to sanity check and possibly correct some inconsistencies in leases when loaded from disk (memfile). A new parameter to govern this behavior has been added. (Trac #5682, git 609bfa0a67caa91fac6834eb39260acfd19e3be4) 1436. [func] tmark Added two new configuration paramters to kea-dhcp4 and kea-dhcp6 DhcpDdns sections: 'hostname-char-set' and 'hostname-char-replacment'. These values (when not empty) are used by the server to sanitize host name and FQDN domain names sent by clients prior to using them to construct DNS names. (Trac #5680, git 32466ab3d4688e66c8c2f9fd24d4a98fcc871ff6) 1435. [func] marcin Implemented ha-continue command in HA hooks library and updated the Kea User's Guide with the information how to pause and resume the HA state machine. (Trac #5675, git 98a9bd4f6766ff2f53681d84d55c56988be4d501) 1434. [func] MayyaSunil Code added to support storage of Authentication key host reservation. There is no way to use the code yet. (Github #88, git 66602af46b1a7d9f4197b1f285c928bd9f80ba2b) 1433. [func] marcin Implemented state HA state machine pausing in the high availability hooks library. (Trac #5674, git b9f3f082c7a88fe98fa4545b9649193ceb5e3ef5) 1432. [func] MayyaSunil Code added to handle Authentication option in DHCPv6. There is no way to use this code yet. (Github #93, git 022dae4393da9e714678d52886d4f478ba308ba9) 1431. [func] marcin Implemented lease4-get-page and lease6-get-page commands in lease_cmds hooks library. (Trac #5651, git b056828212f7b206ff8bd07c097fd6f427d22d71) 1430. [func] fdupont Lease objects and lease backends are now able to store user context. User context can store an arbitrary data as long as it is in JSON format. Database schemas updated. (Trac #5584, git b0b7a198b99fd417466708c80cb7cc2162ae480c) 1429. [bug] marcin Removed memory leak in the DHCPv4 and DHCPv6 servers which occurred when hooks libraries where loaded. (Trac #5664, git 2584b902d2617089bfa7238133490ddd855aa77a) 1428. [bug] marcin Corrected behavior of the standby server in the HA hot-standby mode, which failed to monitor delays in responses to the DHCP queries sent to the primary server after the primary server became unavailable. This resulted in transition of the standby server to the partner-down state immediately after detecting interruption in communication with the primary over the control channel. (Trac #5654, git 7a83f05fe40fb1b6812b055e2d6d633d9e00160c) Thank you again to everyone who assisted us in making this release possible. If you would like to contribute to ISC to assist us in continuing to make quality open source software, please visit our donations page at https://www.isc.org/donate-to-isc/. We look forward to receiving your feedback.