Using the Kea Configuration Backend

  • Updated on Sep 22, 2026
  • Published on Sep 9, 2019
  • 3 minute(s) read
  • Darren Ankney
  • Vicky Risk
  • Suzanne Goldlust
  • Peter Davies
    Peter Davies
 Prev Next

What is the configuration backend?

The configuration backend (also known as the config backend or CB) provides scalable DHCP configuration management using a MySQL or PostgreSQL database.

Config backend takes advantage of three major features of Kea:

  1. Its ability to use a configuration database backend;
  2. Its implementation as a series of hooks; and
  3. Its management through the REST API.

Why do I need it?

DHCPv4 and DHCPv6 servers need to store leases (addresses and prefixes), host reservations (per-host details), and configuration information (options, pools, subnets, shared networks, option definitions, and global parameters). All of those parameters need to be managed, but different servers often have very similar configurations. Duplicating those configurations among multiple servers can be time-consuming.

The config backend allows administrators to easily manage and deploy configuration information across multiple Kea servers by storing it in a database rather than locally on each server, reducing complexity and saving administrative time.

Some config backend features

  • The database server can be colocated with the DHCP server or remote.
  • Multiple Kea servers can share a single remote database.
  • Changes can be made to the configuration database without needing to restart the servers; the servers update automatically using a pull model, with a configurable delay.

What are the benefits of CB?

  1. Configurations can be shared between HA partners; there's no need to worry about missing anything while making changes among different servers.
  2. Rapidly changing configurations are easily maintained.
  3. It offers basic error checking and verification of IP address structure.
  4. Large deployments are easily managed, and updates are propagated nearly simultaneously across your entire network.
  5. CB lets you scale up and down easily with the "server tags" feature.
  6. The configuration backend gives you the ability to monitor the database, run reports, deploy backups, and maintain redundancy.

Are there any limitations to the configuration backend?

  • CB is only available on DHCPv4 and DHCPv6 servers; it does not currently work for DDNS or Control Agent, or other Kea hooks (like RADIUS, NETCONF, etc.).
  • Some parameters (like server-tag) must be configured manually via the JSON file.
  • At the moment, the CB is not fully supported by the ISC Stork server. However, work is in progress to address this.

How do I use CB?

Using the configuration backend, you can create minimal local configuration for new servers, and then have the servers pull all the rest of the information from the database backend. The basic info that needs to be configured is:

  • server-tag – the name of the server with respect to the configuration backend
  • interfaces-config – the information on how to communicate with the network
  • control-socket – the ability for the DHCP server to talk to its Kea configuration
  • config-control – a new feature: the database in which the config backend is stored
  • hooks-libraries – the hooks enable the configuration backend
  • lease-database – the name of the database where the lease data is to be stored
  • expired-leases-processing – the information on when to process expired leases

Many other server parameters can be retrieved via the configuration backend: global parameters, option definitions, client classes, subnets and shared networks, pools, and options. Every time the local server reaches the end of its specified refresh interval, it contacts the config backend to fetch any changes and update its configuration.

How do I administer Kea servers with CB?

Kea distributions contain the kea-shell too, which may be used to talk to a Kea process over a unix socket or via HTTP. The socat or curl tools can also be used. Prior to Kea 3.0, the kea-ctrl-agent (CA) process forwarded API commands to other Kea processes. The CA is now deprecated, and Kea processes must be configured to accept API commands directly. See Management API for the DHCPv4 Server

How do I specify which servers get which configurations?

Server tags allow you to create groups that can be used to specify which configuration options are applied to the Kea servers. Each server has exactly one tag; each object in the database can have one or more server tags associated with it. There is also a global all tag that is associated with all servers. Server tags allow you to set configuration parameters for specific server locations and for all servers.

image.png

How do I migrate from my previous, non-database configuration to the config backend setup in Kea?

You need to review your existing configuration files and identify common elements that can be extracted and grouped. These elements must then be created in the CB using the CB API commands

For a complete description of the configuration backend, please see the Kea Administrator Reference Manual (ARM). You can see the complete list of commands available with the cb_cmds hooks library here.