Installing Kea DHCP Server

Quite a number of my hosts are zeroconf devices, that is, you plug them in and they just work. They expect to get their IP addresses by DHCP. While I do provide a pool of aleatory (randomly assigned) addresses, both IPv4+6, I prefer that the devices get consistent addresses for easier troubleshooting. Devices involved are toucan (the VoIP ATA), roku1 (video performance), ringc[123] (security cameras), petra (development VM), thermo-{up,down}, etc. Petra is hosted on my laptop Xena, which roams. Petra is supposed to have as nearly normal a networking environment as possible including DHCP service, so that server has to be on Xena. The others get DHCP service from Jacinth, the master site which is running 24/7.

Formerly I used dnsmasq-2.80 on both servers. As part of my big infrastructure renovation, I suppressed DNS service from dnsmasq, replacing it with unbound, and leaving only DHCP. dnsmasq has a nice feature where it reads /etc/ethers and /etc/hosts, and creates static assignments for all hosts found in both files, both IPv4+6. But unfortunately this feature has become broken, and I was not able to resurrect it. And I need the static leases for the zeroconf hosts. So I'm looking for a new DHCP server.

ISC sponsored a DHCP server called dhcpd by James Lemon, which I used before dnsmasq. It needed some modernization, and they did a complete rewrite called Kea. Its features look pretty good, so I installed it on Jacinth and Xena. This is OpenSuSE package kea-1.6.0. There are 24 total packages to be installed, mostly kea-specific libraries.

Configuring Kea

Kea has multiple semi-autonomous components. These are the relevant configuration files:

keactrl.conf

Handles starting and stopping the various daemons. I left the configuration at the default, starting DHCPv4, DHCPv6, and Control Agent, but omitting the Dynamic DNS and Netconf components.

kea-ctrl-agent.conf

Handles inter-process communication, and runtime reconfiguration (e.g. adding or killing leases). I left this at the default.

kea-dhcp4.conf

The DHCPv4 server daemon. In my setup the static leases have to be inserted in this file (by a script I wrote), equivalent to dnsmasq's read-ether command. Important configuration items:

• "interfaces": [ "br0" ] — The interfaces it should listen on for requests from clients.
• "valid-lifetime": 3600 — I let the other timer parameters be derived from this per RFC 2131.
• "subnet": "192.9.200.192/26" — The subnet being served; there could be several.
• "pool": "192.9.200.240 - 192.9.200.253" — The range or subnet for aleatory addresses; there could be several.
• { "hw-address": "52:54:0:9:c8:a9", "ip-address": "192.9.200.177", "hostname": "xena" } etc. etc. — Example of a static lease.
• "lease-database": { "type": "memfile", "lfc-interval": 3600 } — This type is the simplest, just a flat file. For an enterprise or an ISP, several real databases can be used.
• Expired lease cleanup is done insanely often, every 25 sec. I lengthened this to 10 min, hakuna matata.
• One major deficiency of Kea is that it lacks programmatic support for DHCP option 121, "classless-static-route". But you can use their feature to create custom options. As it happens, I never got this working, but also because of the infrastructure renovation I no longer needed static routes.
• DHCPv4 options. The ones I used were:
  • "routers"— Your default route(s).
  • "domain-name-servers"
  • "ntp-servers"
  • "domain-search" "routers" — Rarely supported by clients.
• "loggers": [ … ] — I left this at the default.

kea-dhcp6.conf

The DHCPv6 server daemon. Its configuration is very similar to kea-dhcp4.conf, but besides replacing IPv4 with IPv6 addresses, it has only one real difference: the only DHCP option that it serves is "dns-servers", note the different option name. In IPv6, routes have to come from Router Advertisements (for which I use radvd, not dnsmasq).

kea-dhcp-ddns.conf

Since I don't run the Dynamic DNS daemon, I didn't touch its configuration. It could call a user-provided script that sends a set of local-data to Unbound when an aleatory lease is granted, and removes it on expiration.

Additional Setup Steps

I have a script called mkstatic.sh that copies a template file and expands a template line into static leases for all the known hosts. The result becomes kea-dhcp{4,6}.conf.

The systemd unit needs an improvement, to create /run/kea at startup. I just copied /usr/lib/systemd/system/kea.service into /etc/systemd/system/kea.service and inserted this line before ExecStart:
ExecStartPre=mkdir -p ${KEA_PIDFILE_DIR}

Another gotcha: you need to mkdir /var/lib/kea (mode 755 root:root). Kea will not do it for you and will be unable to open its lease files.

With this configuration, Kea is performing well and is passing out both aleatory and static leases.

The Netconf daemon looks intriguing. According to this Wikipedia article about NETCONF , it is a IETF protocol for network management, per RFC 4741 as amended, see RFC 6241 among others. Its main purpose is to inspect and edit the configuration of network devices. I would hope that includes routes. But the easily available documentation is at a higher level, i.e. message syntax, and I suspect without proof that the names and organization of relevant objects like the routing table are not standard among router vendors (Cisco, Juniper, etc.) And there may or may not be a client for generic Linux. Further investigation of NETCONF is kind of out of scope for this document.

Appendix: JSON Syntax

Kea configuration files are in JSON format, and so are a lot of inter-process messages. For a normative definition of JSON see these web resources:

• RFC 8259 The JavaScript Object Notation (JSON) Data Interchange Format (obsoletes RFC 7159) (2017-12-xx)
• ECMA 404, The JSON Daa Interchange Syntax (PDF, 2017)
• Also see this syntax definition for JSON from www.json.org; author, date and backers are not clear, but it's clearer than the formal specifications.

Jimc's summary:

• Comments may begin with # or // (and /* ... */ is possible but unseen). The comment rules are not part of JSON.
• Comments and empty lines are ignored; the example does not show #comments following non-comment text.
• "Words" are separated by 0 or more whitespaces including newlines. It looks like whitespace is always optional, but mandatory punctuation always separates otherwise fusible values.
• A parameter setting statement (PSET) has the form "identifier":value . The identifier is alphanumeric but may include hyphens; it must be in double quotes. Case sensitive. There are various values possible. The acronym PSET is an unofficial Jimc-ism.
• An object has the form { "id":value, ... } i.e. a comma separated list of PSETs, in squiggles. (Ending comma is illegal.)
• The whole config file is one object. (JSON requirement?) Recent Kea convention: this object contains only one PSET identifying the element (e.g. "Dhcp4") being configured, and its configuration as a big object.
• A null value is represented by the keyword null, no quotes.
• A boolean value is true or false, lower case only, no quotes.
• A string value is in double quotes and probably can have internal whitespace, but the sample doesn't have any such examples. Characters can be arbitrary unicode (except double quote and backslash). Backslash escapes are available: \" = double quote, \\ = one backslash, \/ = (not sure), \b = backspace, \f = formfeed, \n = linefeed, \r = carriage return, \t = horizontal tab, \xxxx = numerical unicode (4 hex digits).
• A numeric value is a string of digits, no quotes. Decimal or E-format are legal. Radix 10 only, no octal or hex.
• A list value is [ value, ... ] i.e. comma separated values in brackets. The values can be composite, i.e. lists or objects. (Ending comma is illegal.) Subscripts start at 0.
• A nested object can be (and usually is) a value.
• Naturally the expected identifiers and the types of their values are extremely application specific.
• I think this is a documentation convention for referring to composite parameters: list the identifiers of nested objects slash separated, and for a list value append to its identifier the subscript in brackets. Example: Dhcp4/subnet4[0]/pool means in the "Dhcp4" toplevel object, in the 0'th member of the "subnet4" list value, the "pool" parameter.