Using the Kea DHCP Server 2

Posted by Henry Du on Monday, October 5, 2020


This is the study notes from KEA DHCP Webinar Part 2. Some of contents are from ISC KEA document listed in Reference section.


KEA is modern DHCPv4 and DHCPv6 server. It is under open source MPL License. It provides JSON/REST API and modular design. It also provides high performance, which is able to have 1000 leases/seconds.

KEA supports for DHCPv6 prefix delegation, dynamic reconfiguration, dynamic DNS updates, SQL database backend and PXE Boot support.

KEA Platforms

The following OS are able to run KEA

  • CentOS, Fedora,
  • MacOS X
  • Alpine Linux
  • OpenBSD Unix But not for Windows

KEA hooks

The base KEA software implements the basic DHCPv4 and DHCPv6 functions. The hooks are libraries that contain extra functions that will be called when a DHCP request is processed.

Hooks allow the core Kea system to stay lean, installations only load the functions used and needed. This reduces the complexity and the attack surface of an installation. Hooks that are part of the KEA open source code (source and binary packages)

KEA configuration

Configuration files for the DHCPv4, DHCPv6, DDNS control agent and netconf modules are defined in an extended JSON format. JSON was defined in RFC 7159 and ECMA 404. JSON Editor understands the JSON format. It can check the syntax and can highlight and reformat JSON data.

Extended JSON: Kea components use an extended JSON with addition features.

  • Shell comments:
  • C comments:
  • Multiline comments:
  • File inclusion:

KEA configuration files include kea-dhcp4.conf, kea-dhcp6.conf, kea-dhcp-ddns.conf, kea-ctrl-agent.conf and keactrl.conf.

The following sections are examples of configuration section inside the config file.

network interface configuration

  "interfaces-config": {
            "interfaces": [
            "re-detect": true,
            "dhcp-socket-type": "raw",
            "outbound-interface": "same-as-inbound"

The DHCPv4 server must be configured to listen on specific network interfaces. The simplest network interface configuration tells the server to listen on all available interfaces. The asterisk plays the role of a wildcard and means “listen on all interfaces.”

The dhcp-socket-type specifies that the IP/UDP sockets will be opened on all interfaces on which the server listens, i.e. “eth1” and “eth3” in our case. If dhcp-socket-type is set to raw, it configures the server to use raw sockets instead. If the dhcp-socket-type value is not specified, the default value raw is used.[1]

Interfaces are re-detected at each reconfiguration.

lease database definition

 "lease-database": {
            "type": "memfile",
            "persist": true,
            "name": "/var/leases/dhcp4.leases",
            "lfc-interval": 3600

The lease database is the place where the server stores its lease information. This particular example tells the server to use memfile, which is the simplest (and fastest) database backend. It uses an in-memory database and stores leases on disk in a CSV (comma-separated values) file. This is a very simple configuration; usually the lease database configuration is more extensive and contains additional parameters. Note that lease-database is an object and opens up a new scope, using an opening brace. Its parameters (just one in this example: type) follow. If there were more than one, they would be separated by commas. This scope is closed with a closing brace. As more parameters for the DHCPv4 definition follow, a trailing comma is present.

subnet and pool definition

 "subnet4": [
                "valid-lifetime": 3600,
                "subnet": "",
                "match-client-id": true,
                "pools": [
                        "pool": " -"

We need to define a list of IPv4 subnets. This is the most important DHCPv4 configuration structure, as the server uses that information to process clients’ requests. It defines all subnets from which the server is expected to receive DHCP requests. The subnets are specified with the subnet4 parameter. It is a list, so it starts and ends with square brackets. Each subnet definition in the list has several attributes associated with it, so it is a structure and is opened and closed with braces. At a minimum, a subnet definition has to have at least two parameters: subnet (which defines the whole subnet) and pools (which is a list of dynamically allocated pools that are governed by the DHCP server).

logging definition

KEA DHCP has comes with a flexible and powerful logging framework. The configuration snippet below configures a log-file for the DHCPv4 service.

 "Logging": {
        "loggers": [
                "name": "kea-dhcp4",
                "output_options": [
                        "output": "syslog:user"
                "severity": "INFO",
                "debuglevel": 0
                "name": "kea-dhcp4.leases",
                "output_options": [
                        "output": "syslog:user"
                "severity": "INFO",
                "debuglevel": 0

kea configuration check

kea-dhcp4 -t /etc/kea/kea-dhcp4.conf


keactrl is a shell script that can be used to control the KEA services. The care must be taken not to conflict with process supervision services such as systemd, runit or s6.

keactrl has a configuration, which lists the location of the configuration files and the kea binaries.

To check Kea DHCP service status

keactrl status

keactrl reload when change the configuration file

keactrl reload -c keactrl.conf

Testing DHCPv4 with the ISC dhcpclient

Most Linux distributions provide the ISC DHCP client tool dhclient. This tool can be used as an simple DHCP debugging tool.

dhclient as a debugging tool

Create a new shell script in /usr/local/sbin/ with the lines below


Then, make it executable

chmod 755 /usr/local/sbin/

Execute the dhclient tool with this script

dhclient -sf /usr/local/sbind/

The script will print out all the information received from the DHCP server (via environment variables). It will not reconfigure the client machines network stack.

performance benchmarking

Kea comes with a DHCP benchmarking tool: perfdhcp. This tool can be used to benchmark Kea, but also other DHCP server systems. For details, see the perfdhcp document.

Kea DHCPv6 configuration

The Kea DHCPv6 server is independent from the Kea DHCPv4 server. Both can be started together on the same machine, or separated machines. The configuration file for the Kea DHCPv6 server is kea-dhcp6.conf. The Kea DHCPv6 server can be controlled from the keactrl script or through systemd (on Linux).


Each DHCPv6 server has a unique DHCP-Unique-ID (DUID). When re-installing a DHCPv6 server, it might be useful to backup and restore the DUID of the system. The Kea DHCPv6 DUID is stored in the file kea-dhcp6-serverid in the /var/lib/kea directory.


  1. ISC KEA configuration