Using Kea Config File Includes

Updated
  • Updated on Jan 23, 2026
  • Published on Jan 22, 2026
  • 3 minute(s) read
  • Ben Scott
 Prev Next

Introduction

Kea features an extension to JSON that allows one to include the contents of one file into another file: The <?include?> directive. This feature can be used to simplify management of Kea configurations. This article provides practical examples of such usage.

How Include Works

As explained in the Kea ARM, at any point in a Kea config file where a JSON element is expected, one can place a <?include?> directive. When Kea loads the config file, Kea effectively replaces the <?include?> tag with the contents of the named file.

The path to the included file is given in double-quotes inside the tag. For example:

<?include "/etc/kea/interfaces4.json"?>

Contraindications

Since <?include?> is processed during config file load, the included file structure is not represented in memory, and will not be preserved by Kea API commands like config-get or config-write. The entire config (including anything that was included from a separate file) will be presented together as one object. Any subsequent config-write will replace the main config file with the combined config, causing the formerly-included files to be ignored from that moment on.

Management tools that make use of the Kea API to modify the Kea config are thus generally incompatible with the <?include?> feature. This includes ISC's own Stork management tool. Read-only API usage (which never makes changes) is generally compatible. In theory Stork can be used this way, but any accidental change will clobber the includes.

WARNING

Using the <?include?> directive with Stork or anything else that invokes config-write will generally result in undesirable behavior.

Example: Database

When using SQL database storage with Kea, it is common for the same database configuration parameters to appear multiple times in the config files. For example, one might need to specify the same database in both kea-dhcp4.conf and kea-dhcp6.conf, and/or, for both lease-database and host-databases sections. Rather than repeating the same information (and manually updating each when something changes), the database configuration can be put in a separate file, and included as needed.

A simplified example configuration that demonstrates this is provided below (click the file names to see the example file content):

In the above example, note how the lease-database and hosts-database sections both include the same database config file. Note also that the DHCPv4 and DHCPv6 daemons both use the same include file. Thus, all database configuration is kept in a single file. One update to database.conf will change the database config throughout.

Example: High Availability

When using Kea in an HA (High Availability) scenario, it is common for most of the configuration to be the same across the two HA servers (the member servers, or peers). Ideally, the only differences are the thishost directive identifying which server it is, and perhaps the interfaces directive (especially for DHCPv6). Accidental differences between the config files on each server can be a source of problems.

To help manage this, one can construct kea-dhcp4.conf and kea-dhcp6.conf files which will literally be identical on both servers. Keep the server-specific information in separate files, and have the main files include it. Keep everything else in the main file — subnets, pools, host reservations, and so on. When making changes, one updates the main file, and copies the same file to both servers.

A simplified example configuration that demonstrates this is provided below (click the file names to see the example file content):

  • These files will be identical on both servers:
  • These files will be different on each server:

In the above example, note how the vast majority of the configuration is kept in the main files. If those main files are copied from server to server as described, this keeps the configuration properly in sync. Also note that the server-specific information is kept in separate, small files. These files will typically be configured once and then never change again.

The above example assumes the kea-dhcp4 daemon will have an identical interface configuration on both servers. If different interfaces need to be defined for DHCPv4 as well, the interfaces6.conf concept can be extended to interfaces4.conf in the same fashion.