Kea Configuration for Small Office or Home Use

This article provides a basic Kea configuration for small office or home users. The idea here is to present a simple configuration that will get you most of the way there. More complicated configurations or specific items might be required in your network, depending on your needs and setup. Please see the Kea ARM for further information.

The Network

For this article, an example network is configured in Kea for DHCPv4 and DHCPv6. This is a very simple network consisting of only one IPv4 subnet (192.0.2.0/24) and one IPv6 subnet (2001:db8:192:0::/64). There is a single host reservation for a printer (192.0.2.200 and 2001:db8:192:0::200, respectively). For simplicity, the configurations do not make use of client classes, which are covered in detail in Understanding Client Classification and in the Kea ARM.

DHCPv4 Configuration

Here is the complete DHCPv4 configuration. This is explained below.

{
  "Dhcp4": {
    "interfaces-config": {
      "interfaces": [
        "ens256"
      ]
    },
    "lease-database": {
      "type": "memfile",
      "persist": true,
      "name": "/tmp/dhcp4.leases"
    },
    "valid-lifetime": 28800,
    "option-data": [
      {
        "name": "domain-name-servers",
        "data": "192.0.2.252, 192.0.2.253"
      }
    ],
    "subnet4": [
      {
        "subnet": "192.0.2.0/24",
        "pools": [
          {
            "pool": "192.0.2.1 - 192.0.2.199"
          }
        ],
        "option-data": [
          {
            "name": "routers",
            "data": "192.0.2.254"
          }
        ],
        "reservations": [
          {
            "hw-address": "1a:1b:1c:1d:1e:1f",
            "ip-address": "192.0.2.200" 
          }
        ]
      }
    ],
    "loggers": [
      {
        "name": "kea-dhcp4",
        "output_options": [
          {
            "output": "/tmp/kea-dhcp4.log",
            "maxver": 10
          }
        ],
        "severity": "INFO"
      }
    ]
  }
}

The configuration above contains several parts for different purposes. These are all explained in detail in the Kea ARM, so they will be covered here briefly. The above configuration has Kea listening on interface ens256 for DHCPv4 traffic. Leases are stored in /tmp/dhcp4.leases. The default lease time is 28800 seconds (8 hours). DHCP clients will be offered domain name servers192.0.2.252 and 192.0.2.253 . An address in the range 192.0.2.1 through 192.10.2.199 will be allocated to the clients unless the client has a MAC address of 1a:1b:1c:1d:1e:1f in which case it will be allocated the address 192.0.2.200. Clients will receive a router gateway address of 192.0.2.254. Log messages about this process will be available in /tmp/kea-dhcp4.log.

Some will find they can directly copy the above configuration; modify the IP information, file locations, and interface; and serve their network. Others may need to add extra details. The intention here is to provide a simple starting point for a simple network.

This covers the DHCPv4 part of the network.

DHCPv6 Configuration

Below is a DHCPv6 Kea configuration for this example network, followed by a brief explanation and comparison of the configuration with the DHCPv4 version.

{
  "Dhcp6": {
    "interfaces-config": {
      "interfaces": [
        "ens256"
      ]
    },
    "lease-database": {
      "type": "memfile",
      "persist": true,
      "name": "/tmp/dhcp6.leases"
    },
    "valid-lifetime": 28800,
    "option-data": [
      {
        "name": "dns-servers",
        "data": "2001:db8:192:0::252, 2001:db8:192:0::253"
      }
    ],
    "subnet6": [
      {
        "subnet": "2001:db8:192:0::/64",
        "pools": [
          {
            "pool": "2001:db8:192:0::1 - 2001:db8:192:0::199"
          }
        ],
        "reservations": [
          {
            "duid": "01:02:03:04:05:1a:1b:1c:1d:1e:1f",
            "ip-addresses": [ "2001:db8:192:0::200" ]
          }
        ]
      }
    ],
    "loggers": [
      {
        "name": "kea-dhcp6",
        "output_options": [
          {
            "output": "/tmp/kea-dhcp6.log",
            "maxver": 10
          }
        ],
        "severity": "INFO"
      }
    ]
  }
}

The above configuration is only slightly different from the previous DHCPv4 configuration. Refer to the Kea ARM for details. The interface configuration is the same for DHCPv4 and DHCPv6. The lease database type is the same, though the file destination is different, as they cannot be stored in the same file. DHCPv6 leases will be stored in /tmp/dhcp6.leases. The valid lifetime configured is the same for both versions.

Note the difference when assigning DNS servers. Firstly, the servers are IPv6 addresses: 2001:db8:192:0::252 and 2001:db8:192:0::253. Secondly, the option name itself differs (domain-name-servers for DHCPv4 vs. dns-servers for DHCPv6). The subnet configurations are very similar aside from the opening stanza being subnet6 vs. subnet4 for DHCPv4, and IPv6 addresses appear instead of IPv4 addresses.

Two more differences are present. In the host reservation, the address 2001:db8:192:0::200 is allocated to the client identified by a duid of 01:02:03:04:05:1a:1b:1c:1d:1e:1f. This is the same client that receives 192.0.2.200 based on the MAC address of 1a:1b:1c:1d:1e:1f. A DUID is the preferred identifier in DHCPv6. Lastly, the logging destination for DHCP6 is /tmp/kea-dhcp6.log.

In a dual-stack environment, keeping your DHCPv4 and DHCPv6 configurations as similar as possible makes sense. This makes transitioning away from DHCPv4 as painless as possible. Again, the above configuration can probably be copied and used with only minimal changes (such as IP addresses and interfaces) in small networks.

Start the DHCP Servers

How to start the DHCP servers is a matter of choice, depending on how Kea was installed (compiled from source or installed from a package) and the capabilities of the system. It is possible to start the servers using operating system mechanisms such as systemd; they can also be started with keactrl, or by directly running the associated kea servers, kea-dhcp4 and kea-dhcp6.

It may be that systemd already has service files for starting the servers. If that is the case, consult these files for the expected location of the configuration files. Describing exactly how to start the servers using systemd is beyond the scope of this article, as it is largely dependent on the particular implementation. Consult the Kea ARM for details about starting DHCPv4 and DHCPv6 servers without systemd by calling the servers directly or by using keactrl.