---
title: "Migrating away from Kea Control Agent"
slug: "kea-control-agent-migration"
description: "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 handled by the direct API."
status: "new"
updated: 2026-06-24T04:30:51Z
published: 2026-06-24T04:30:51Z
canonical: "kb.isc.org/kea-control-agent-migration"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://kb.isc.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)](/docs/kea-api-sockets#kea-control-agent). All API clients connected to the KCA, and the KCA forwarded API commands to the other Kea daemons. Kea 3.0 introduced [*direct API*](/docs/kea-api-sockets#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](/docs/kea-ports#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](/docs/kea-api-sockets#control-socket-becomes-plural) 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](/docs/kea-security#securing-the-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:

**Click to see new kea-dhcp4.conf**

```
{
  "Dhcp4":
    {
      "control-sockets":
        [
          {
            "socket-type": "http",
            "socket-address": "127.0.0.1",
            "socket-port": 8004
          }
        ],
      # (The rest of the file follows...)
```

Note how `control-sockets` is still defined as a list, but now contains only a single object.

## See also

- Knowledgebase
  - [Kea 3.2: Things to be aware of when upgrading](/docs/things-to-be-aware-of-when-upgrading-to-kea-3-2)
  - [Kea API and Control Sockets](/docs/kea-api-sockets)
  - [Kea Security](/docs/kea-security)
- Kea ARM
  - [Migration from the obsolete (removed) Control Agent](https://kea.readthedocs.io/en/latest/arm/ctrl-channel.html#migration-from-the-obsolete-removed-control-agent)