Creating the Initial Configuration

Among other things, the /usr/local/etc/kea directory contains the configuration files of the modules for DHCPv4 and DHCPv6, the dynamic DNS registry, and the parameterization of the keactrl script.

To customize the configuration, use either the configuration files or the RESTful API. The associated daemon is named Kea Control Agent, which also lets you connect to your own management systems. However, it does not provide encrypted access natively. You would have to connect a reverse proxy such as Apache or Nginx to enable encrypted management access – which is of course recommended.

After the initial configuration, start the DHCPv4 service with

keactrl start -s dhcp4

and verify the status by typing keactrl status.

Static Config vs. Database

To begin, start with the static DHCPv4 configuration in a configuration file (Listing 3). Note that these sample configurations are not intended for production and partly include IP addresses from reserved address ranges specifically for documenting the process.

{
"Dhcp4": {
  "renew-timer": 900,
  "rebind-timer": 1800,
  "valid-lifetime": 3600,
  "interfaces-config": {
    "interfaces": ["ens33"],
    "dhcp-socket-type": "raw"
  },
  "lease-database": {
    "type": "memfile",
    "persist": true,
    "lfc-interval": 3600
  },
  "option-data": [
  {
    "name": "domain-name-servers",
    "data": "192.0.2.1"
  },
  {
    "code": 15,
    "data": "lab.pfisterit.de"
  },
  {
    "name": "domain-search",
    "data": "lab.pfisterit.de"
  }
  ],
  "subnet4": [
  {
    "subnet": "192.0.2.0/24",
    "pools": [
      {
        "pool": "192.0.2.20 -- 192.0.2.199"
      }
    ],
  "option-data":[
  {
    "name": "routers",
    "data": "192.0.2.1"
  }],
  "reservations": [
  {
    "hw-address":
    "1a:1b:1c:1d:1e:1f",
    "ip-address": "192.0.2.201"
  }
  ]
  }
  ],
  "loggers": [ {
    "name": "kea-dhcp4",
    "output_options": [ {
      "output": "/tmp/kea-dhcp4.log"
    } ],
    "severity": "WARNINGS",
    "debuglevel": 0
  } ]
}
}

A DHCPv4 configuration file initially starts and ends with the outer element "Dhcp4": { }. The individual parameters must be comma-separated cleanly to create a valid JSON file. This example first defines some timers, including timers for the maximum validity of a DHCP lease and for the extension of a lease with the previous DHCP server or with other DHCP servers. After that, it defines the interface on which a service binding will be made and determines that it accepts raw requests with dhcp-socket-type.

Alternatively, to accept DHCP requests by a DHCP relay on the DHCP server, you could parameterize the socket type as udp. Next, the file configures the leases database to be a memfile type and stores it persistently in the /var/lib/kea/dhcp4.leases directory. Next are the global DHCP options. The example defines the DNS server of the organization, the domain name, and the search domain.

Additionally, it creates a DHCP scope with the option to assign the default gateway; that is, it has set up a DHCP reservation for the MAC address 1a:1b:1c:1d:1e:1f and the IP address 192.0.2.201. The path /usr/local/var/log/kea-dhcp4.log is used as the logging destination. The corresponding log level is set to WARNINGS.

Figure 1 shows a DHCPv4 process in Wireshark as an example. The global DHCP option for the lab.pfisterit.de DNS domain was passed to the client in the offer from the DHCP server residing on the IPv4 address 192.168.178.194.

Figure 1: Example of a packet capture of a DHCP offer. The global option of the domain name was adopted.

In contrast to the example in Listing 3, with a memfile lease database, the next example connects to a MySQL database by storing the corresponding connection parameters such as the TCP port, database name, and corresponding credentials in the configuration snippet (Listing 4).

{
"Dhcp4": {
  "renew-timer": 900,
  "rebind-timer": 1800,
  "valid-lifetime": 3600,
  "interfaces-config": {
    "interfaces": ["ens33"],
    "dhcp-socket-type": "raw"
  },
  "lease-database": {
    "type": "mysql",
    "name": "dhcp",
    "host": "",
    "connect-timeout" : 5,
    "max-reconnect-tries": 5,
    "reconnect-wait-time": 3000,
    "user": "dhcpsvc",
    "password": "t0ps3cr3t",
    "port": 3306,
    "persist": true,
    "lfc-interval": 3600
  },
  "option-data": [
  {
    "name": "domain-name-servers",
    "data": "192.0.2.1"
  },
  {
    "code": 15,
    "data": "lab.pfisterit.de"
  },
  {
    "name": "domain-search",
    "data": "lab.pfisterit.de"
  }
  ] ,
  "subnet4": [
  {
    "subnet": "192.168.178.0/24",
    "pools": [
    {
      "pool": "192.168.178.20 -- 192.168.178.199"
    }
    ],
  "option-data":[
  {
    "name": "routers",
    "data": "192.168.178.1"
  }],
  "reservations": [
  {
    "hw-address":
    "1a:1b:1c:1d:1e:1f",
    "ip-address": "192.168.178.201"
  }
  ]
  }
  ],
  "loggers": [ {
    "name": "kea-dhcp4",
    "output_options": [ {
      "output": "/tmp/kea-dhcp4.log"
    } ],
    "severity": "WARNINGS",
    "debuglevel": 0
  } ]
}
}

DHCPv6 and Data Models

The example in Listing 5 uses a dedicated configuration file for IPv6. The matching timers and interface bindings are already known from the IPv4 configuration. The central differences are recognizable in this very simple JSON example in the form of specifications for Dhcp6 instead of Dhcp4, as well as subnet6 instead of subnet4 for the corresponding scopes.

{
"Dhcp6": {
  "renew-timer": 900,
  "rebind-timer": 1800,
  "valid-lifetime": 3600,
  "interfaces-config": {
    "interfaces": ["ens33"],
  },
  "lease-database": {
    "type": "memfile",
    "persist": true,
    "name": "/var/lib/kea/dhcp6.leases"
  },
  "subnet6": [
  {
    "subnet": "2001:db8:1::/64",
    "pools": [
    {
      "pool": "2001:db8:1::5 - 2001:db8:1::ffff"
    }
    ]
  }
  ]
}
}

As the level of automation in the network environment increases, the YANG (Yet Another Next Generation) data model has become increasingly popular. A unified data model is particularly recommended on heterogeneous networks. Kea also offers YANG support based on the open source Sysrepo engine. To work with this data model, the NETOPEER2 NETCONF server, which is under BSD license, offers an interface for configuration adjustments.