Kea API and Control Sockets

  • Updated on Mar 26, 2026
  • Published on Mar 26, 2026
  • 8 minute(s) read
  • Ben Scott
 Prev Next

Introduction

This article introduces the Kea Application Programming Interface (API). It briefly discusses the architecture of how the Kea API is presented, through control sockets, the direct API, and the Kea Control Agent (KCA).

Use of API commands is beyond the scope of this article. Consult the Kea ARM for information on API commands and their usage.

Kea API Overview

The Kea DHCP server consists of up to four daemons (service processes). These daemons communicate with each other, and with external programs, through an Application Programming Interface (API). The Kea API provides a way for other programs to send commands to Kea. These commands can be used to interrogate and manipulate the Kea server while it is running.

The Kea API is used by the ISC Stork management suite, and by some third-party software. They use it to retrieve Kea configuration, submit configuration changes, and/or retrieve status and statistics information.

The kea-shell tool included with Kea provides a basic command-line interface to the API. The API can also be used with generic command-line tools like curl and jq. Administrators of Kea servers can assemble such tools together in scripts to automate tasks.

To API clients, the Kea API appears as an HTTP server that accepts HTTP POST requests with a JSON body, each of which returns an HTTP response with a JSON body. The JSON body of the request presents the API command, along with any arguments. The JSON body of the response includes an API result code, and any data that was requested by the command.

Important operational aspects

The API is optional

Use of the Kea API is optional. If you do not have a need to manipulate a running Kea server, you can simply keep the Kea API disabled. Simpler deployments of Kea — such as a residential gateway appliance — may find restarting the daemons for every configuration change to be viable. More complicated deployments will likely find the impact of a complete restart to be unacceptable, and find the API necessary for changes and monitoring.

The API is powerful

The power of the Kea API makes it an attractive target for attackers. The API can be used to replace the entire Kea configuration, or manipulate any part of it. By changing file paths, an attacker may be able to use Kea to corrupt or replace critical system files. By manipulating DHCP responses, an attacker may be able to mislead or take control of DHCP clients. By impersonating a Kea server, an attacker may be able to steal administrator credentials like passwords.

The API should be secured

Due to the power of the API, operators are very strongly encouraged to take steps to protect the API from abuse. These steps might include:

Control Sockets

The various Kea daemons provide control sockets to access the API. Control sockets are also called API access points, or sometimes a control channel.

In terms of structure, control sockets are one of two types:

  • Unix domain sockets (also called named sockets), which are created in the filesystem, appearing similar to regular files
  • HTTP listeners, which listen on numbered TCP ports

Generally, the API clients are expected to connect to an HTTP listener. The Unix domain sockets are intended more for Kea's internal communications. By their nature, Unix domain sockets are restricted to the local host. Anything needing to access the Kea API over the network must use HTTP.

HTTP listeners can be grouped by their intended purpose:

  • General API listeners, providing the full compliment of API commands for any API client
  • HA dedicated listeners, used exclusively for communication between members of a High Availability group

HTTP listeners can also be grouped by how Kea provides them:

Direct API

Kea 3.0 introduced direct API access. In this mode of operation, all Kea daemons provide their own HTTP listeners. API clients then connect directly to the individual daemons. This eliminates the need for the Kea Control Agent. This is now the preferred mechanism for accessing the Kea API.

Defining a direct API listener

One can define a direct API listener in kea-dhcp4.conf, kea-dhcp6.conf, and kea-dhcp-ddns.conf. The general form is:

"control-sockets":
  [
    {
      "socket-type": "http",
      "socket-address": "127.0.0.1",
      "socket-port": 8004
    }
  ]

More than one listener can be defined in the list. The socket-type can be http for unencrypted HTTP, or https for HTTP over encrypted TLS. See also advice on selecting port numbers.

Control socket becomes plural

Prior to Kea 3.0, each daemon (other than the Kea Control Agent) allowed one to define a single control-socket. This specified a Unix domain socket which the Kea Control Agent would connect to.

With Kea 3.0, the control-socket (singular) declaration in the various Kea config files has become control-sockets (plural). The value is no longer a single object, but instead, a list of object. Each object defines an individual control socket that the daemon will provide.

If Kea 3.0 encounters control-socket (singular) while loading a config file, it treats it as a list containing the one object. Thus, if you have an older config file that uses control-socket, and load it using Kea 3.0, and then issue a config-write API command, the new file will be written using the new control-sockets syntax.

Kea Control Agent

Prior to Kea 3.0, the only supported method to access the Kea API was via the Kea Control Agent (KCA). The KCA is a separate daemon, kea-ctrl-agent, which acts as an API front-end to the other Kea daemons. The other daemons provide only a Unix domain socket in the filesystem. The KCA listened on a TCP port as an HTTP server, and forwarded commands to the others daemons using those control sockets. The KCA managed the HTTP protocol encapsulation.

As of Kea 3.0, the Kea Control Agent (KCA) was deprecated, with the new direct API mechanism becoming the preferred approach. The KCA is still fully supported for reasons of backwards compatibility, but administrators are encouraged to plan to move to the direct API.

Kea Control Agent removal

The KCA is scheduled for removal in Kea 3.2. Operators should plan to migrate away from the Kea Control Agent before they need to upgrade to Kea 3.2 or later.

Control Agent sockets

In the kea-ctrl-agent.conf file, one defines two types of sockets: The Unix domain sockets the KCA will use to talk to the other Kea daemons, and the HTTP(S) listener the KCA will provide to API clients.

HTTP listener parameters are defined at the top level. http-host defines the IP address the KCA will listen on. http-port defines the TCP port number the KCA will listen on. API clients will connect to the IP address and port specified here.

The Unix domain sockets are defined in the control-sockets list. The only supported socket-type is unix. The socket-name is the path to the node in the filesystem. The definitions given in the KCA config file must match the definitions given in the config files of the other Kea daemons. Inconsistencies between config files is a common source of Kea API trouble.

Click to see kea-ctrl-agent.conf example 
{
  "Control-agent": {

    "http-host": "127.0.0.1",
    "http-port": 8000,

    "control-sockets": {
      "dhcp4": {
        "socket-type": "unix",
        "socket-name": "/var/run/kea/kea4-ctrl-socket"
      },
      "dhcp6": {
        "socket-type": "unix",
        "socket-name": "/var/run/kea/kea6-ctrl-socket"
      },
      "d2": {
        "socket-type": "unix",
        "socket-name": "kea-ddns-ctrl-socket"
      }
    }

  }
}

HA dedicated listeners

Using the Kea High Availability hook (plugin) involves configuring two or more Kea servers into a High Availability group (HA group). Each member of the HA group communicates with the other members to exchange information on status and leases. This communication is done using API commands dedicated to the HA hook.

The HA hook can use the same API listener as all other API commands, but it is easy for this to become a performance bottleneck. Thus, the HA hook can also provided a dedicated HTTP listener to be used exclusively for HA communication. This is the recommended configuration when using HA, for performance and stability reasons.

Consult the Kea ARM for more information on configuring an HA dedicated listener.

Restricting HA listener commands

In terms of the underlying API command mechanism, an HA dedicated listener is no different than the direct API or the Kea Control Agent. As such, it has the same potential for abuse, and warrants similar protections.

One option unique to the HA listener is the restrict-commands parameter. When enabled, this limits the API commands accepted by the HA listener to those relevant to HA coordination.

The restrict-commands parameter was introduced in Kea 2.2, but defaulted to false. With Kea 3.0, the default became true. Enabled is recommended for all versions.

This parameter is set within the high-availability section of the parameters section of the HA hook. For example:

Click to see kea-dhcp4.conf example 
{
  "Dhcp4": {
    "hooks-libraries": [
      {
        "library": "libdhcp_ha.so",
        "parameters": {
          "high-availability": [
            {
              "this-server-name": "dhcp1",
	      "restrict-commands": "true",
              "mode": "hot-standby",
              "peers": [
                {
                  "name": "dhcp1",
                  "url": "http://192.0.2.11:8005/",
                  "role": "primary"
                },
                {
                  "name": "dhcp2",
                  "url": "http://192.0.2.12:8005/",
                  "role": "standby"
                }
              ]
            }
          ]
        }
      }
      # ... more hook libraries, if needed ...
    ]
    # ... remainder of configuration ...

See also