RESTful Interface for Kea DHCP Server

Kea is a flexible open source DHCP server that is becoming popular among system administrators. One of the most frequent feature requests was for an API for administrative tasks such as retrieving statistics, managing configuration, and certain run time aspects, like leases. Some of the functionality was there, but there was no way to communicate with Kea. At the same time, Kea was suffering from the old Unix paradigm of a daemon reading its configuration from a local text file. It’s a good approach, but in 2017 people expect something more from software that claims to be modern.

ISC engineers came up with a proposal for a RESTful API. Mozilla graciously decided to fund development through their Mozilla Open Source Support (MOSS) fund. Almost a year later, we are ready to show the results. The task at hand was not a trivial one, so we split the work into milestones.

Milestone 1: Update Parser

The first step was to update the parser. It was designed to read the configuration from a file on local disk. This is an approach that works well for smaller installations, but it was problematic for larger, modern deployments where there are many servers and the configuration is being pushed to those servers remotely. Kea had multiple, complex parsers spread in many files in multiple directories. This was difficult to maintain and extend. Also, the handling of defaults was confusing - the default values were spread out in many places and it required detailed code inspection to find out what the actual default was.

We significantly re-wrote Kea’s parsers. The new parsers are much simpler to understand, use, and extend. They print out more meaningful errors, so users have a better clue about what is wrong in their configuration and how to fix it. In the process a couple of new useful features were added: multi-line comments, bash (#) and C++ (//) style comments, and file inclusions. For details, see here.

Milestone 2: Add a REST API

Kea already used JSON commands over its control channel (which is a Unix domain socket), so we decided to extend this capability to a REST interface. A basic REST interface was implemented as an optional control agent (people who don’t need the management interface simply don’t run the daemon). As a result, Kea 1.2 now supports many more commands that can be used over REST/http: you can set configuration remotely, retrieve configuration, tell Kea to write configuration to disk, and do many other things the API offers.

Milestone 3: Make it robust and secure

The API was functional, but we still needed to secure it. The obvious way to protect http communication is to use TLS. We had a dilemma: we could implement TLS support on our own or use existing tools available for it. Getting cryptography right is a challenging task, so we opted to use the best methods that were already available. As a result, there are two Kea configurations that expose secure https (with TLS) interface, using Apache or Nginx. Example configurations are available in the doc/examples/https directory.

Another significantly improved aspect is a move towards asynchronous handling of the socket operations. This opened up the possibility to handle commands and responses larger than 64K and paved the way for future extensions that may be large (e.g. returning thousands of leases from a subnet or configuring hundreds of subnets at once). These changes will be included in Kea 1.3.

Milestone 4: Make good use of the capabilities

Finally, the last step was to embrace the new interface with an application. We wanted a feature that would showcase the API, but also a useful feature at the same time. We picked leases, which are “contracts” between the DHCP server and the devices it serves. We wanted to provide as much flexibility as possible. We designed 10 new commands that help with creating new leases, querying and inspecting existing leases using various search criteria, retrieving them, updating them, and even removing them when necessary. All the code for handling those commands is now written. The code is already available in the Kea github repository (commits for lease4-add, lease6-add, lease4-get, lease6-get, and for lease4-del, lease6-del, lease4-update, lease6-update, lease4-wipe, lease6-wipe). All of these changes will be included in the upcoming Kea 1.3.

Going forward

The first two milestones are already released as Kea 1.2. The remaining code is available on github and is scheduled to be released in the upcoming Kea 1.3 update later this autumn. The work will not stop there. We already have plans to extend the API. We have requests for new commands, new parameters for existing commands, and management interfaces for existing and upcoming features. Kea users definitely do not suffer from a shortage of ideas! Over time we will make the best possible usage of the code that was created with Mozilla’s help.

Let me take the opportunity to personally thank Mozilla and the Mozilla Open Source Support (MOSS) fund for their generous support of this work. We did our best to make the best use of the funds to listen to the open source community and deliver high-quality open source code for the benefit of all users. We also made sure the result is something that will continue to yield benefits for the community in the future. Thank you.

Tomek Mrugalski

Kea Lead Engineer, ISC