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. Please see the Kea ARM for further information.

The Network

For this article, an example network is configured in Kea for DHCPv4 and also 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 does not make use of client classes, which are covered in detail in Understanding Client Classification as well as 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). Domain name servers of 192.0.2.252 and 192.0.2.253 will be provided to the DHCP clients. 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 that they can directly copy the above configuration, modify the IP information, file locations, and interface and serve their network. Others may need to add additional details. The intention here is to provide a simple starting point for a simple network. This covers the DHCPv4 part of the network. Next DHCPv6 will be covered.

DHCPv6 Configuration

Below is a DHCPv6 Kea configuration for this example network followed by a brief explanation of the configuration comparing it 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 than the previous DHCPv4 configuration. Refer to the Kea ARM for details. The interface configuration is the same between DHCPv4 and DHCPv6. The lease database is the same except the file destination is different as they cannot be stored together. The DHCPv6 leases will be stored in /tmp/dhcp6.leases. The valid lifetime configured is the same between the two versions.

Note the difference when assigning DNS servers. First, the servers are IPv6 addresses; 2001:db8:192:0::252 and 2001:db8:192:0::253. Second, the option itself is named differently (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 appearing 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 duid of 01:02:03:04:05:1a:1b:1c:1d:1e:1f. This is the same client that received 192.0.2.200 due to MAC address of 1a:1b:1c:1d:1e:1f. DUID is the identifier used most of the time in DHCPv6. The other difference is that the logging destination is /tmp/kea-dhcp6.log.

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

Start DHCP servers

How to start the DHCP servers will be a matter of choice, how Kea came to exist on the system (compile from source or install from package) and the capabilities of the system Kea is installed upon. It is possible to start the servers using operating system mechanisms such as systemd. They can also be started with keactrl or directly by 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 dependant 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.