From Gentoo Wiki
Jump to:navigation Jump to:search

Kea is a DHCP server developed by the Internet Systems Consortium. It is a newer (next generation) DHCP server from the same authors of ISC DHCP


USE flags

USE flags for net-misc/kea High-performance production grade DHCPv4 & DHCPv6 server

debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see
doc Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
filecaps Use Linux file capabilities to control privilege rather than set*id (this is orthogonal to USE=caps which uses capabilities at runtime e.g. libcap)
mysql Add mySQL Database support
openssl Use dev-libs/openssl instead of dev-libs/botan
postgres Add support for the postgresql database
samples Install sample configuration files
shell Install kea-shell text management client for Control Agent
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)


root #emerge --ask net-misc/kea


OpenRC only

After installing, the default configuration files are found in /etc/kea and are prefixed with kea, e.g. kea_dhcp4.conf.

If using OpenRC, these need to be renamed to match that used in the /etc/conf.d/kea daemon config, for example:

root #cp /etc/kea/kea_dhcp4.conf /etc/kea/dhcp4.conf

To use the high availability feature of Kea, the kea-ctrl-agent must be started to allow the primary & standby server(s) to communicate. Currently the OpenRC scripts do not contain the starting of the Kea-ctrl-agent and so need to be modified.

Edit the /etc/init.d/kea script and in each section add additional code for the agent. For example in the start() section, add the following:

FILE /etc/init.d/kea

if ${AGENT:-false} ; then
     start-stop-daemon -m -b -p ${agent_pidfile} \
          -s ${agent_command} -- -c ${agent_config} \
          || return 1

AGENT needs to be defined in /etc/conf.d/kea.

The agent_pidfile, agent_command and agent_config need to be defined at the top, like so:

FILE /etc/init.d/kea

Note: PID files are created by Kea with a filename that embeds the config used. The installed /etc/init.d/kea tells start-stop-daemon to also create pid files with a different path. This works, but can be confusing to see 2 PID files for the same process. It is possible to remove the '-m' option from start-stop-daemon call and specify in the '-p' option the PID filepath that the kea processes create.

So that kea is started after the network is up and for example; the network interface is eth0; add to /etc/conf.d/kea the following:

FILE /etc/conf.d/kea
rc_need="net.eth0 logger"

It is useful to require a logger, so any crash detected by start-stop-daemon is logged.



For OpenRC, the file paths are defined in /etc/conf.d/kea and /etc/init.d/kea, they can be modified if required.

  • /etc/kea/dhcp4.conf - Configuration for the kea-dhcp4 daemon
  • /etc/kea/dhcp6.conf - Configuration for the kea-dhcp6 daemon
  • /etc/kea/ddns.conf - Configuration for the kea-ddns daemon

If the modification to the daemon scripts have been performed, the following addition config is available:

  • /etc/kea/ctrl-agent.conf - Configuration for the kea-ctrl-agent daemon


For Systemd the file paths are the paths as defined in the unit files in /lib/systemd/system/kea*.

  • /etc/kea/kea-dhcp4.conf - Configuration for the kea-dhcp4 daemon
  • /etc/kea/kea-dhcp6.conf - Configuration for the kea-dhcp6 daemon
  • /etc/kea/kea-ddns.conf - Configuration for the kea-ddns daemon
  • /etc/kea/kea-ctrl-agent.conf - Configuration for the kea-ctrl-agent daemon



root #rc-update add kea
root #rc-service kea start

Runnng as non-root

By default Kea runs as root as it requires access to priviledged ports.

To avoid running as root, first install acct-user/dhcp (if not already installed). This creates a user and group called dhcp.

The binaries need capabilities added so they can access the priviledged ports and raw sockets.

root #setcap 'cap_net_bind_service,cap_net_raw=+ep' /usr/sbin/kea-dhcp4
root #setcap 'cap_net_bind_service=+ep' /usr/sbin/kea-dhcp6

If using OpenRC, the kea ini script needs to be modified so the option --u dhcp is passed as an additional argument to start-stop-daemon.

Check all kea config files are accessible via the dhcp user.

Set kea log & database files in /var to be owned by dhcp, or at least writable by kea.


Hook Libraries

Run Script Support

Kea has a useful interface to run scripts on certain events. For example this can be used to update DNS records when leases are allocated or revoked.



root #emerge --ask --depclean --verbose net-misc/kea

External resources