Finally upgrading from isc-dhcp-server to isc-kea for my homelab

A few months back, I put together a big fat guide on how to configure DNS and DHCP on your LAN the old-school way, with bind and dhcpd working together to seamlessly hand out addresses to hosts on your network and also register those hosts in your LAN's forward and reverse DNS lookup zones. The article did really well—thanks for reading it!—but one thing commenters pointed out was that my preferred dhcpd implementation, the venerable isc-dhcp-server, reached end-of-life in 2022. To replace it, ISC has for many years been working on the development of a new DHCP server named Kea.

Kea (which for this piece will refer mainly to the isc-kea-dhcp4 and isc-kea-dhcp-ddns applications) doesn't alter the end-user experience of receiving DHCP addresses—your devices won't much care if you're using isc-dhcp-server or isc-kea-dhcp4. Instead, what Kea brings to the table is a new codebase that jettisons the older dhcpd's multi-decade pile of often crufty code for a new pile of much less crufty code that will (hopefully) be easier to maintain and extend.

Many Ars readers are aware of the classic Joel on Software blog post about how rewriting your application from scratch is almost never a good idea, but something like isc-dhcp-server—whose redesign is being handled planfully by the Internet Systems Consortium—is the exception to the rule.

According to ISC, the older isc-dhcp-server application's codebase was becoming increasingly difficult to maintain, and at a certain point, it hit what we sometimes refer to as the "Old Yeller" threshold, where it finally became smarter to start over than to continue to complicate an already over-complicated mess of old code. In isc-dhcp-server's place, Kea is properly multithreaded, supports high availability, can extend its functionality through optional hooks and a full-featured API, and even has an optional graphical interface for reporting and admin tasks.

Unfortunately for admins, Kea being a ground-up rewrite means that you can't just take your existing isc-dhcp-server configuration file and drop it in /etc/kea—and while there are automated tools to translate that existing config file to Kea-speak, those tools provide more of a starting point than a destination. Diving into the documentation to determine what options are necessary for the functionality your specific setup needs is a mandatory part of the process.

We'll short-circuit that just a teeny bit as I step through my own upgrade process and share the config I'm using on my LAN. But first, the inevitable caveats!

Who the heck is this guide even for?

If you're a network engineer looking for tips on upgrading your enterprise's core DHCP functionality over to Kea, this is not the guide for you. We'll be re-creating my homelab-specific isc-dhcp-server configuration in Kea JSON and talking about the (mostly very basic) options I've picked. We are not going to be doing anything crazy advanced. Besides, if you're doing this at work, shouldn't you have a VAR or MSP doing this for you? Don't rely on my advice for an environment that actually matters!

On the other hand, if you're an Ars reader with a homelab (or if you're like me and your entire home network is your homelab because no one who knows any better is around to stop you) and you've got isc-dhcpd providing DHCP services, this guide is exactly for you! Provided you have a reasonably simple setup with one or two subnets and nothing wild going on, this guide should get you pointed in the right direction.

Wait, this “upgrade” sounds hard and unrewarding!

Yeah, replacing a program that works fine with another program that works fine but requires a new configuration doesn't exactly feel like the most useful thing one could do with their time, but look at it this way: The old isc-dhcp-server application was released 26 years ago, and if Kea is similarly supported and nurtured by its dev community, the expectation is that it will be around for at least as long. With a bit of luck, this pain will be a one-time-only deal.

And to be perfectly clear, you do not need to change over from isc-dhcp-server to Kea for your homelab. (At least not yet.) The isc-dhcp-server packages are still available on every big Linux distro, and will likely remain so for quite some time. ISC states that Kea is fully production-ready, but if you'd prefer to watch Kea cook a little longer and let folks like me continue to flail around with it, you definitely still have plenty of time to do so.

I guess we’re doing this

The very first thing to do for folks transitioning from isc-dhcp-server to Kea is to run your existing isc-dhcp-server configuration file through the ISC's Kea Migration Assistant tool. This will give you some idea of how your existing dhcpd setup will need to be altered when hammering it into Kea's JSON-style config files.

(Folks who are uncomfortable pasting their configuration files into a web-based tool can probably take advantage of local versions of the Kea Migration Assistant. For example, if you're using Ubuntu Server, you can install the isc-dhcp-keama package from the default repos.)

If you have my level of luck, the Migration Assistant will spit back a config file mostly made of comments about how everything you want to do uses deprecated options. And that's OK! Set aside the output file for a few minutes—we'll come back to it.

Actually installing Kea

Now it's time to install Kea, and there are several options for getting that done. If you're on Ubuntu and you'd prefer to go the bare metal route, there are Kea packages available in the repositories; for Ubuntu Server 24.04 LTS, which is what I'm using, the packages are for Kea version 2.4.1 (Kea's "stable" branch).

This is a perfectly cromulent version to simply install and run, but if you'd like something more current, ISC maintains a set of repos for most major Linux distros. This is the option I chose, utilizing these instructions right here, because Kea is under active development, and the current (as of October 2024) 2.6.1 version from the ISC repo offers features absent from 2.4.1 stable (and some of the configuration options are slightly different, too).

Finally, there's also a set of official Docker images for Kea if you'd prefer an installation that is a bit more ephemeral—or if Docker is your preferred method of running infrastructure tools like Kea.

(A quick note for folks who choose to go the Docker route: I'll be proceeding in this guide with instructions for bare-metal installs. If you're going ahead with Docker, you'll need to adapt this stuff into Docker-speak yourself. At the very least, you'll need a directory set aside on your host to store your Kea configuration files and DHCP lease database outside of the Docker image.)

There are three specific Kea packages we want: isc-kea-dhcp4, isc-kea-dhcp-ddns, and isc-kea-doc (or kea-dhcp4-server, kea-dhcp-ddns-server, and kea-doc if you're installing from the older Canonical repos rather than the ISC ones). There are multiple other Kea packages you could install if you'd prefer to tinker further, including the isc-kea meta-package if you want all of the Kea components, but for this guide, we'll stick just with the three listed.

The reason there are multiple things to install here—at least compared to the old isc-dhcp-server all-in-one package—is that Kea splits out its DDNS functionality into separate components. We need isc-kea-dhcp4 to provide IPv4 DHCP services, and then we need isc-kea-dhcp-ddns to hook Kea up to our DNS server (bind, in this instance) to do the actual dynamic updates to your zone files as hosts come and go. Finally, the isc-kea-doc package contains a whole mess of useful example configuration files to crib from—more on that in a bit.

Both the DHCP server and the DDNS server components have their own configuration files, and the next step is to edit those files. If you used the Kea Migration Assistant earlier, keep that output file handy for the end of the next section.

Assessing our configuration needs

Just to re-emphasize something from the beginning of this article: I can't tell you how you should configure your instance of Kea. Instead, I'll tell you how I configured my instance of Kea. (If you want some more configurations to examine, consult the examples supplied by the isc-kea-doc package in /usr/share/doc/isc-kea-doc/examples—there's a tremendous amount of useful information stored there!)

I have a simple setup: I need to provide DHCP services to a single subnet, and most of the hosts on that subnet have DHCP reservations, so I don't need a gigantic pool. I don't need anything fancy or complex (beyond DDNS, which isn't terribly fancy or complex).

With that being said, the main component of the migration to Kea for me was assessing the important stuff in my old isc-dhcp-server config file and seeing either how the Migration Assistant turned it into Kea-speak, or, if the Migration Assistant didn't know what to do with a given setting, trying to manually find the equivalent setting for Kea.

A quick walk-through of my old config showed that I had the following requirements to carry forward from the old setup to the new:

• I needed to establish one DHCP-enabled subnet
• I needed DDNS enabled and forward- and reverse-lookup zones specified
• I needed to account for a signing key for DDNS updates
• I probably wanted longer DHCP lease times than the default (since it's a homelab without a lot of host turnover)
• I needed some host reservations.

Broken down that way, the migration didn't look terribly scary—and it's made easier by the fact that the Kea default config files come filled with descriptive comments and configuration examples to crib from. (And, again, ISC has done an outstanding job with the docs for Kea. All versions, from deprecated to bleeding-edge, have thorough and extensive online documentation if you're curious about what a given option does or where to apply it—and, as noted above, there are also the supplied sample config files to tear apart if you want more detailed examples.)

Configuration time for DHCP

We have two Kea applications to configure, so we'll do DHCP first and then get to the DDNS side. (Though the DHCP config file also contains a bunch of DDNS stuff, so I guess if we're being pedantic, we're setting both up at once.)

The first file to edit, if you installed Kea via package manager, is /etc/kea/kea-dhcp4.conf. The file should already have some reasonably sane defaults in it, and it's worth taking a moment to look through the comments and see what those defaults are and what they mean.

Here's a lightly sanitized version of my working kea-dhcp4.conf file:

{
  "Dhcp4": {
    "control-socket": {
      "socket-type": "unix",
      "socket-name": "/tmp/kea4-ctrl-socket"
    },
    "interfaces-config": {
      "interfaces": ["eth0"],
      "dhcp-socket-type": "raw"
    },
    "dhcp-ddns": {
      "enable-updates": true
    },
    "ddns-conflict-resolution-mode": "no-check-with-dhcid",
    "ddns-override-client-update": true,
    "ddns-override-no-update": true,
    "ddns-qualifying-suffix": "bigdinosaur.lan",
    "authoritative": true,
    "valid-lifetime": 86400,
    "renew-timer": 43200,
    "expired-leases-processing": {
      "reclaim-timer-wait-time": 3600,
      "hold-reclaimed-time": 3600,
      "max-reclaim-leases": 0,
      "max-reclaim-time": 0
    },
    "loggers": [
    {
      "name": "kea-dhcp4",
      "output_options": [
        {
          "output": "syslog",
          "pattern": "%-5p %m\n",
          "maxsize": 1048576,
          "maxver": 8
        }
      ],
      "severity": "INFO",
      "debuglevel": 0
      }
    ],
    "reservations-global": false,
    "reservations-in-subnet": true,
    "reservations-out-of-pool": true,
    "host-reservation-identifiers": [
      "hw-address"
    ],
    "subnet4": [
      {
        "id": 1,
        "subnet": "10.10.10.0/24",
        "pools": [
          {
            "pool": "10.10.10.170 - 10.10.10.254"
          }
        ],
        "option-data": [
          {
            "name": "subnet-mask",
            "data": "255.255.255.0"
          },
          {
            "name": "routers",
            "data": "10.10.10.1"
          },
          {
            "name": "broadcast-address",
            "data": "10.10.10.255"
          },
          {
            "name": "domain-name-servers",
            "data": "10.10.10.53"
          },
          {
            "name": "domain-name",
            "data": "bigdinosaur.lan"
          }
        ],
        "reservations": [
          {
            "hostname": "host1.bigdinosaur.lan",
            "hw-address": "aa:bb:cc:dd:ee:ff",
            "ip-address": "10.10.10.100"
          },
          {
            "hostname": "host2.bigdinosaur.lan",
            "hw-address": "ff:ee:dd:cc:bb:aa",
            "ip-address": "10.10.10.101"
          }
        ]
      }
    ]
  }
}

The first stanzas set up the control socket on which the DHCP process listens for management API commands (we're not going to set up the management tool, which is overkill for a homelab, but this will ensure the socket exists if you ever decide to go in that direction). They also set up the interface on which Kea listens for DHCP requests, and they tell Kea to listen for those requests in raw socket mode. You almost certainly want raw as your DHCP socket type (see here for why), but this can also be set to udp if needed.

Next, we're enabling DDNS so that hosts on the network will register themselves with DNS as they're assigned DHCP addresses. We'll be providing a few options to make DDNS work the way I want—specifically, I want DHCP clients to always register themselves with DDNS, and I want them to do it with my domain suffix. We also want our host to be authoritative so that it properly responds to all types of DHCP requests.

Pay particular attention to the ddns-conflict-resolution-mode parameter. This setting dictates whether or not Kea modifies forward- and reverse-lookup records for DHCP hosts as they register. The default value is check-with-dhcid, which makes Kea act in accordance with RFC 4703 and not remove or alter any DNS records it doesn't recognize as its own, with that recognition keying off of the Dynamic Host Configuration Identifier, or DHCID, which Kea records when it creates a new DNS host file entry.

(If you're using a version of Kea prior to 2.5.0, you'll have to use the ddns-use-conflict-resolution option instead, which was replaced in 2.5.0 with ddns-conflict-resolution-mode. All of this is laid out, with detailed explanations, in the official docs.)

The reason I'm using no-check-with-dhcid instead of the default is that in this case, I'm slotting Kea into an existing environment with existing zone files populated with existing entries from existing hosts, and I want Kea to be unconstrained with removing and replacing those existing entries as hosts de- and re-register themselves. I figure I'll change it back to the default option after a few weeks, once Kea has been in charge for a while. If you're in a similar situation, you might consider a similar solution; otherwise, it's fine to leave that option at its default.

Next, we have some lines that deal with DHCP lease lifetime and how Kea reclaims expired leases. As noted earlier, I prefer a longer lease time since my homelab doesn't have a lot of hosts and isn't constrained for address space, so I've bumped the default values up considerably. You should set these values to taste or leave them at defaults.

The logging stanzas are all from the defaults in the config file, so there's nothing much to talk about there.

After this, we get to the meaty bit where we tell Kea what subnet to listen to for incoming DHCP requests and how to respond to them. I have my main LAN segment listed, and the pools stanza identifies the actual address pool inside of that subnet from which client addresses will be handed out. I'm using 10.10.10.170-10.10.10.254 for my pool.

(Without getting too far into the weeds, I like to use 10.10.10.2-99 for static addressing, 10.10.10.100-169 for DHCP host reservations, and higher addresses for general DHCP hosts. The old sysadmin in me prefers being able to discern a host's role by looking at its IP address.)

Below the subnet and pool definitions are the specific DHCP options we want our clients to pick up. There are many things you can define here, but I'm sticking with the basics: Clients get a netmask, a gateway address, a broadcast address, a DNS server, and a domain name.

Finally, if you'd like, you can add some host reservations. If you prefer certain clients to always grab the same IP address whenever they join the LAN, this is how you do it.

What other options exist that we didn’t get to?

There are many different ways to put your own configuration together, with one of the primary considerations being the scope of how widely our options apply. Most of the configuration options here can be set to apply globally, apply per subnet, or apply to specific groups of hosts.

The best way to dig into this, if you feel like there's something you want to do that I haven't covered, is to spend some time dissecting the Kea example configuration files, which should be located in /usr/share/doc/isc-kea-doc/examples. Multiple use cases are outlined there, and no matter how weird your homelab is, you should be able to find something that at least resembles what you're looking to do.

Configuration time for DDNS

The DDNS configuration is a bit simpler than the DHCP configuration and doesn't really need that many stanzas. Configuration for the Kea DDNS component is stored in kea-dhcp-ddns.conf. Here's mine:

{
"DhcpDdns":
{
  "control-socket": {
      "socket-type": "unix",
      "socket-name": "/tmp/kea-ddns-ctrl-socket"
  },
  "tsig-keys": [
    {
      "name": "dhcpupdate",
      "algorithm": "hmac-md5",
      "secret-file": "/etc/kea/dhcpupdate.key"
    }
  ],
  "forward-ddns" : {
    "ddns-domains": [
      {
        "name": "bigdinosaur.lan.",
        "key-name": "dhcpupdate",
        "dns-servers": [
          {
            "ip-address": "10.10.10.20",
            "port": 53
          }
        ]
      }
    ]
  },
  "reverse-ddns" : {
    "ddns-domains": [
      {
        "name": "10.10.10.in-addr.arpa.",
        "key-name": "dhcpupdate",
        "dns-servers": [
          {
            "ip-address": "10.10.10.20",
            "port": 53
          }
        ]
      }
    ]
  },
  "loggers": [
  {
    "name": "kea-ddns",
    "output_options": [
      {
        "output": "syslog",
        "pattern": "%-5p %m\n",
        "maxsize": 1048576,
        "maxver": 8
      }
    ],
    "severity": "INFO",
    "debuglevel": 0
    }
  ]
}
}

Much like with the DHCP side of the house, we start by configuring a control socket. After that, we specify a cryptographic key (stored in a file) that will be supplied to the DNS server when creating, updating, or removing entries in the forward and reverse DNS zone files. This can be the same key you're already using if you have an existing isc-dhcp instance already running.

(Note that if you're using the 2.4.1 stable version of Kea from the Canonical repos, you'll have to inline your TSIG key—external key storage wasn't introduced until version 2.5.8. Some examples of how to do this can be found in the official docs.)

Continuing in the config file, below the key declaration, are two very important sections: the ones that define the names of the forward and reverse DNS zones, the DNS server or servers with authoritative control over those zones, and the name of the key which will be used for DNS updates.

Finally, we set up our logging, which I'm configuring the same as with the DHCP server so that everything dumps into syslog. If you'd prefer your DHCP and DDNS logging data to show up in its own file, this can be configured here.

Start ’em up

And that's… kind of it. If you're transitioning off of the older isc-dhcpd-server application, now's the time to stop isc-dhcpd-server and start up (or restart) the Kea services. Before starting the new stuff up, it's not a bad idea to give your Kea configuration files a syntax check using the -t options for the DHCP and DDNS servers, like so: