Why switch to Kea DHCP in OPNsense?#
By default, OPNsense uses the ISC DHCP server, which is reliable, but not only is it morally outdated - the ISC DHCP project itself has reached end of life (EOL) and is no longer being developed. It has been succeeded by Kea DHCP - a modular, high-performance, and flexible solution from the same developers.
If you enjoyed this article, you can support the author by becoming a sponsor on Boosty (link in the contacts section).
Kea DHCP is a powerful alternative to the outdated ISC DHCP, offering a modern approach to IP address distribution and centralized management. If you use OPNsense in production or in a home lab, now is a good time to switch to a more flexible and actively developed solution.
Advantages of Kea DHCP#
- Hot-reload of the lease list - configuration can be changed without restarting.
- Modular architecture - only the components you need.
- Support for storing the IP lease list in a database (MySQL/PostgreSQL).
- REST API - automation and external management.
- Support for extended logic via hooks and scripts.
- Active development and support from the community and ISC.
Disadvantages of Kea DHCP#
Higher load when used in containers on weak hardware. Kea is modern, modular software, but when used with a REST API or a database it can consume more resources. On low-power single-board computers (such as a Raspberry Pi) or LXC containers, performance can be lower than that of the lightweight ISC DHCP.
Limited failover support (compared to ISC). ISC DHCP implements a classic failover peer protocol. Kea doesn’t yet have a full HA mechanism out of the box - or rather, there are certain nuances when configuring it.
Links#
Kea DHCP has shipped out of the box in Opnsense for quite a while now. The approach I’ll describe in this article works both for setting things up from scratch and if you already have a working Opnsense with an ISC DHCP server.
I put off, or more accurately, I didn’t want to start the migration from ISC DHCP to Kea DHCP for a long time, because I was afraid that something would break during the move. What’s more, by the standards of how fast networking technologies develop (get adopted), Kea is still a young project. Opnsense users do have some complaints about Kea DHCP - it’s still not as stable as one might like, and some may find the feature set lacking. Given all of this, the OPNsense developers began introducing Dnsmasq DHCP & DNS as a lightweight alternative to Kea DHCP. As a result, Opnsense users now have a choice of DHCP server. The developers themselves suggest the following split on their site: Dnsmasq for home and small office use, and Kea DHCP only for business needs. Unfortunately, Dnsmasq DHCP is also still too new a product for Opnsense at this point. There’s constantly something that needs fixing. That said, this is to be expected for a new solution. Here’s the bottom line. In January 2026, in version 26.1, ISC DHCP was removed from the default installed packages (on fresh installations) and is now available only as a plugin for fans of ancient lore - on existing systems it’s pulled in automatically during upgrades. Users are free to decide for themselves which DHCP server option to choose. BUT the default is now DNSMasq. That said, migrating from Kea DHCP to Dnsmasq DHCP and vice versa can be very fast, because both service options support the .csv format. That is, all you need to do is activate the server, do the minimal initial configuration, and feed it a csv file with the static lease data. Unfortunately, the ISC server, being an old technology, doesn’t support this format, so migrating from an ISC server on systems with a large number of static leases can take a lot of time. But looking at it from a glass-half-full perspective, this is something you only have to do once.
Configuring the KEA DHCP server#
So. Let’s imagine you have an existing setup with ISC. If you have a fresh installation, then for the most part you’ll be doing the same thing, except you won’t need to migrate any existing leases. My sequence of actions was as follows. First, with Kea DHCP not yet running (and, accordingly, ISC still running), I made all the necessary configuration changes, entered the interface data and static addresses, then enabled Kea DHCP and immediately disabled ISC DHCP. As a result, the static leases were picked up right away, and the dynamic leases appeared in the Kea DHCP lease lists once the lease term tracked by the ISC server expired, even though it had already been disabled. Everything went off without a hitch. I was actually surprised how smoothly it all went.
Go to Services, select Kea DHCP
We’re not interested in the Control Agent, since it’s needed for enterprise use. In a home setup you’re hardly going to be setting up HA for routers, are you? You’re not, right? I’m assuming you have a regular IPv4 setup, so I’ll show everything using an example for ordinary people. Go to Kea DHCPv4. We won’t activate the service just yet, but in the interfaces section, in the drop-down menu, you need to select all the interfaces on which you want your new DHCP server to operate. If you only have two: WAN and LAN, then select only LAN. If you’re as abnormal as I am, you’ll have more than three interfaces, at minimum: WAN, LAN, and some VLAN. Select anything except WAN. After selecting all the interfaces you need, be sure to check the box next to firewall rules. In the valid lifetime field you can specify the DHCP lease time you want, but the default values should work for most use cases. Naturally, we don’t touch HA mode. Here’s what I ended up with.
Now go to the subnets section, click the red plus icon, and manually enter your subnet data. In the subnet field, enter your subnet data. For example, for the default LAN network this looks like 192.168.1.1/24. Set a description in the description field, though that’s optional. If you have few subnets, or a good memory, there’s no real need for it. In the pool field, you need to manually enter the pool of IP addresses that the DHCP server will hand out automatically. Let’s set the address pool the same way it was with ISC, in the format 192.168.1.100 - 192.168.1.199. Uncheck the box next to match client-id. I won’t insist that this must be done, but if you want to be able to register IP leases by MAC address in the future - and that’s really what you want - the box needs to be unchecked. In the DHCP option data section, check the box next to Auto collect option data. Don’t touch anything else.
So, here’s where we’re at. We need to migrate our existing static leases from ISC DHCPv4 to Kea DHCPv4. And here you’ll have to do everything by hand. If we were setting everything up from scratch, there’d be no real choice, but when you’re doing this on a live setup with a lot of leases, it’s tedious, since there’s no automation. Go to the reservation section, click plus. In the drop-down menu, select the subnet where you want your device to be registered. After that, everything is logical and intuitive. In the ip field, set the desired ip. In the mac address field, enter your device’s mac address, set the hostname and description. The last one is optional. And that’s it. It took me longer to write this than it’ll take you to actually do it. Now go back to the settings section, check the box to activate the Kea DHCP server, go to ISC and deactivate it. That’s it. The job is done. After that you can watch in the logs as the device leases in ISC DHCPv4 expire and the devices show up in Kea DHCPv4.
