Migrating from ISC DHCP to Kea DHCP using the Migration Assistant
  • 23 Feb 2022
  • 4 Minutes to read
  • Contributors
  • Dark
  • PDF

Migrating from ISC DHCP to Kea DHCP using the Migration Assistant

  • Dark
  • PDF

On May 22, 2019, Alan Clegg presented a webinar on migrating from ISC DHCP to Kea DHCP using the Kea Migration Assistant. This article recaps the highlights of the webinar for those who may be interested in the migration steps. You can also watch a recording of the webinar here.

Migration is hard – so why do it?

Moving to a new software package may be necessary to get the benefits of new code or new hardware. However, migration is also an opportunity to learn more about aspects of your network and your DHCP configuration that may not have been touched in a while. As a result, your configuration may become simpler and cleaner. Migration also gives you a chance to document the new configuration, something which can often get overlooked.

But since migration can be a daunting process, ISC recommends several small- to mid-sized migrations over time rather than one large migration.

When is the best time to migrate?

Ideally, the best time to undertake a migration is when you already have other changes going on, and it will be less disruptive to try something new. For example, if you have already planned major infrastructure changes, you are already adding new office locations, or your existing infrastructure is reaching its End of Life, it may make sense to use those changes as an opportunity to migrate.

How should I start the migration from ISC DHCP to Kea?

First, begin by documenting and reviewing your existing configuration.

Then, evaluate the different Kea options. Kea offers several features that are not available in ISC DHCP, such as the ability to use database backends, high availability, and IPv6 deployment. Read about the options and decide which ones are likely to be most useful for your environment. Full details about all the features available in Kea can be found on our website, at https://www.isc.org/kea or in the Kea Administrator Reference Manual.

So how do I migrate from ISC DHCP to Kea DHCP?

  1. It is, of course, possible to rewrite the configuration file manually; however, ISC has developed the Kea Migration Assistant (or "KeaMA") tool to make it easier for users to translate their configuration files from one format to the other. (See below for more details about KeaMA.)

  2. Once you have a working Kea configuration file, it is essential to test it in a lab environment for both functionality and performance.

  3. When your lab testing is complete, you can migrate the leases. No ISC DHCP-to-Kea DHCP migration tool is currently available, so existing leases need to be rebuilt from scratch.

  4. Finally, perform the cutover to Kea. We recommend enabling small pieces at a time, during off-hours, to minimize end-user disruption.

There are several important differences between ISC DHCP and Kea, which you will need to consider as you plan and execute your migration:

  1. Server failover, which was available in ISC DHCP, is not implemented in Kea. The Kea High-Availability hooks library offers similar functionality if that is a desired feature for your organization.
  2. Option inheritance scoping is different between ISC DHCP and Kea, so administrators will need to manage that difference.

There are also several new Kea features that you may want to implement:

  1. Configuration backend, which offers the ability to store configurations in a database and apply them to servers from there, instead of locally on each server.
  2. Host reservations used to be kept in a leases file or DHCP configuration, but now can be stored in a database backend.
  3. A lease database was previously stored in logfile format, with new leases added to the end; Kea now allows you to keep leases in a database for simplified management.

So what does the Kea Migration Assistant do?

KeaMA, the Kea Migration Assistant, is a branch of the legacy ISC DHCP server and is available at https://gitlab.isc.org/isc-projects/dhcp/tree/master/keama. It takes the existing ISC DHCP configuration language and outputs it as a Kea JSON configuration.

Administrators need to run it once each for IPv6 and IPv4 configurations; KeaMA produces separate output files for each.

KeaMA provides diagnostic messages when a direct translation is not available or possible, and provides a link to the related Kea GitLab issue. For example, in the image below, the error message (indicated here in red) refers the user to GitLab issue #245 for additional information.


Many issues can be resolved by just looking at the error message and reference number that come up in KeaMA; however, there are some configuration options that don’t translate directly from ISC DHCP to Kea, and which will need to be addressed manually.

The new Kea configuration file will be more verbose than the old ISC DHCP one.

Kea MA can handle ISC DHCP configurations with multiple include files.)

Basic compile/run instructions for KeaMA may be found at https://gitlab.isc.org/isc-projects/dhcp/tree/master/keama. Note that KeaMA is also provided as a package in ISC's Cloudsmith repository.
curl -1sLf \ 'https://dl.cloudsmith.io/public/isc/keama/setup.rpm.sh' \ | sudo -E bash