How to: Getting started with Kea DHCP for IPv4 / IPv6

By on 6 Mar 2020

Category: Tech matters

Tags: , , , ,

Blog home

Dynamic Host Configuration Protocol (DHCP) is a network management protocol used to automate the process of configuring devices on IP networks.

DHCP servers enable computers to request IP addresses and networking parameters automatically from Internet Service Providers (ISPs), reducing the need for network administrators or users to manually assign IP addresses to all network devices.

Kea is an open-source DHCP server developed by the authors of ISC DHCP (DHCPd) and the Internet Systems Consortium (ISC). It includes DHCPv4 and DHCPv6 servers; a dynamic DNS daemon; a REST API interface; MySQL, PostgreSQL and Cassandra databases; RADIUS and NETCONF interfaces; and related utilities.

Watch a recording of Tomek Mrugalski’s Intro to Kea DHCP for IPv4/IPv6 webinar on APNIC Academy.

Migrating from ISC DHCP to Kea DHCP

ISC DHCP is a proven and reliable software that has been in development since 1995. Even though the initial design assumptions made in the mid-1990s are no longer valid (back then there was no concept of mobility, IPv6 was a novel concept being researched at the IETF, Wi-Fi was a novelty with limited availability, and 16MB was considered a significant amount of RAM) the software has stood well against the test of time. However, there is only so much ISC can do to extend its lifetime without rewriting significant parts of the code. That’s why we decided to write a new DHCP server, which is how Kea came to be.

Kea was designed on modern principles: a modern API, flexible database support, robust extensibility, detailed documentation, and design prepared to take advantage of modern hardware and tackle modern scale networks. As such, Kea is not a 1-to-1 replacement for ISC DHCP.

Those who wish to migrate from ISC DHCP to Kea will notice many differences, particularly in the structure of the configuration file. It is, of course, possible to rewrite the configuration file manually; however, ISC has developed the Kea Migration Assistant (or ’KeaMA’) tool to make it easier for users to translate their configuration files from one format to the other.

KeaMA takes an existing ISC DHCP configuration file and outputs it as a Kea JSON configuration file. Administrators need to run it once each for IPv6 and IPv4 configurations; KeaMA produces separate output files for each. KeaMA provides diagnostic messages when a direct translation is not available or possible and provides a link to the related Kea GitLab issue. For example, in the image below, the error message (indicated here in red) refers the user to GitLab issue #245 for additional information.

Figure 1 — A result of the KeaMA operation.

In May 2019, Alan Clegg presented a webinar on migrating from ISC DHCP to Kea DHCP using KeaMA. This article recaps the highlights of the webinar for those who may be interested in the migration steps. You can also watch a recording of the webinar here. Also, see our KB article about migration.

Installing Kea

Users have at least two options to get Kea working.

The most convenient is to install Kea using native (DEB, RPM, APK) packages hosted on

The other installation method requires source code compiling — see the Kea Administrative Reference Manual (ARM), Section 3.

If you’re looking for production deployment, you want stable releases; with Kea, it’s very easy to differentiate between stable and development releases. After 1.6.0 was released, ISC moved to a release model where the second version number denotes a branch; even numbers are stable and odds are development. For example, the latest stable version as of the time of writing this blog post was 1.6.2. If significant bugs are discovered, we may publish another stable version, which will be designated 1.6.3. Sometime in the future (estimated summer 2020), we will release a new stable series, designated 1.8.0.

However, if you’re impatient or want to check out the latest bells and whistles, you may be interested in monthly development releases. ISC recently published 1.7.5, and 1.7.6 is expected in late March 2020. However, please be careful with using development code. In general, it’s not tested well enough to deploy it in production networks. Use with care!

Once Kea is installed, you should tweak the configuration file next to suit your specific configuration. Kea has a separate configuration file for each daemon, so depending on what you want to do exactly, you’ll need to edit one or several files. But don’t worry, you can take it step-by-step and enable more advanced features once your basic service is working.

You should edit at least one of these two files: kea-dhcp4.conf or kea-dhcp6.conf, both located in /etc/kea. These are JSON files and they have a basic structure in place. At the very minimum, you need to modify at least the name of the network interfaces Kea should listen on, and your subnets and pools. This is a very simple example of what a Kea DHCPv4 configuration file looks like:

"Dhcp4": {
// First we set up global values
    "valid-lifetime": 4000,
    "renew-timer": 1000,
    "rebind-timer": 2000,
 // Next we set up the interfaces to be used by the server.
    "interfaces-config": {
        "interfaces": [ "eth0" ]
 // And we specify the type of lease database
    "lease-database": {
        "type": "memfile",
        "persist": true,
        "name": "/var/lib/kea/dhcp4.leases"
 // Finally, we list the subnets from which we will be leasing addresses.
    "subnet4": [
            "subnet": "",
            "pools": [
                     "pool": " -"
            // If you want to serve direct traffic (i.e. not via relays),
            // uncomment this line. It tells Kea that any DHCP packets
            // incoming through interface eth0 should be handled by this
            // subnet.
            // "interface": "eth0"

DHCPv6 configuration is very similar, although you can also configure PD (Prefix Delegation) pools.

Once you get the configuration up and running, you’ll probably want to experiment and start tweaking it to meet your specific needs. You may want to look at adding extra options — router configuration and DNS are two most common in DHCPv4 — and defining more subnets to reflect your actual topology.

Client classification allows you to segregate your devices into different classes — Kea can then treat them differently, depending on your needs. One example is service tiers for offering customers different levels of service. Another popular application is to send different options to different device types; for example, many cable modems require different options, depending on the vendor or firmware version.

You can look at host reservations — a convenient way to alter your configuration on a per device basis — which enables you to reserve IPv4 addresses, IPv6 addresses, and IPv6 prefixes, but also to assign specific options or add devices to certain classes. Does your printer require some extra options? Do you want to have a MAC-based (or any other property for that matter; see flex-id) list of devices that get your latest cool service? Not a problem!

There are many more features, including High Availability, databases, the hooks mechanism, and the API that you can tweak, all of which I’ll touch on in my next post and the webinar.

Tomek Mrugalski is the Director of DHCP Engineering at the Internet Systems Consortium (ISC) and one of the original authors and engineers of Kea DHCP.

Rate this article

The views expressed by the authors of this blog are their own and do not necessarily reflect the views of APNIC. Please note a Code of Conduct applies to this blog.

Leave a Reply

Your email address will not be published. Required fields are marked *

Please answer the math question * Time limit is exhausted. Please click the refresh button next to the equation below to reload the CAPTCHA (Note: your comment will not be deleted).