Migrating away from Kea Control Agent

Summary

The Kea Control Agent (KCA) is deprecated in Kea 3.0, and has been removed as of Kea 3.2. The functions of the KCA are now fulfilled by the direct API access features of Kea 3.0 or later. This article provides guidance on migrating from the KCA to the direct API.

What is changing?

Prior to Kea 3.0, the only supported method to access the Kea API was via the Kea Control Agent (KCA). All API clients connected to the KCA, and the KCA forwarded API commands to the other Kea daemons. Kea 3.0 introduced direct API access, where all Kea daemons provide their own HTTP listeners. API clients then connect directly to the individual daemons. This eliminates the need for the KCA. As such, the KCA is optional in Kea 3.0, and deprecated.

In Kea 3.2, the KCA has been removed entirely. As such, anyone wishing to upgrade to Kea 3.2 or later, who is still using the KCA, will need to migrate to the direct API as part of that upgrade.

Impact

If your API clients only use Unix domain sockets in the local file system, nothing else needs to change for you. The KCA and its HTTP listener go away, and everything else stays the same.

In the case of HTTP(S), things are more complicated.

One consequence of moving from the single KCA to a direct API listener for each daemon is that each daemon will need its own TCP port for API access. Ports used by Kea — Management Ports provides further explanation and some suggestions.

API clients will likewise need to select the appropriate destination TCP port based on the desired service (DHCPv4, DHCPv6, or DHCP-DDNS). If your API clients currently send API commands to multiple services using the KCA, logic will need to be added to select the appropriate destination port.

If you have clients using a mix of HTTP(S) and Unix domain sockets, you can define both in the control-sockets directive, which is plural for all service daemons as of Kea 3.0.

Security considerations

The Kea API is very powerful. An attacker for hijacks the API can use it for all manner of evil, such as changing the Kea configuration, corrupting the host system, influencing DHCP clients, and/or stealing administrator passwords. For this reason, securing the API is important.

Please see Securing the Kea API for more on this subject.

Configuration examples

The most common case

Below are two config file fragments from two hypothetical kea-dhcp4.conf files, illustrating what might need to change when moving from the old KCA scenario to the new direct API approach.

Note how the section name changes from control-socket (singular) to control-sockets (plural). Note also how the new form defines a list of control sockets, with [ ] square brackets.

Before

Click to see old kea-dhcp4.conf

{
  "Dhcp4":
    {
      "control-socket":
        {
          "socket-type": "unix",
          "socket-name": "/var/run/kea/kea4-ctrl-socket"
        },
      # (The rest of the file follows...)

After

Click to see new kea-dhcp4.conf

{
  "Dhcp4":
    {
      "control-sockets":
        [
          {
            "socket-type": "unix",
            "socket-name": "/var/run/kea/kea4-ctrl-socket"
          },
          {
            "socket-type": "http",
            "socket-address": "127.0.0.1",
            "socket-port": 8004
          }
        ],
      # (The rest of the file follows...)

Without filesystem sockets

Looking at the previous example, the new configuration still provides a Unix domain socket in the filesystem, for compatibility with the KCA or anything else that expects one. If this is not needed, it may be omitted: