Kea

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

Installation

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 https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
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)

Emerge

root #emerge --ask net-misc/kea

Configuration

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
fi
...

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
...
agent_command="/usr/sbin/kea-ctrl-agent"
agent_config="${AGENT_CONFIG:-/etc/kea/ctrl-agent.conf}"
agent_pidfile="/run/kea-ctrl-agent.pid"

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.

Files

OpenRC

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

Systemd

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

Service

OpenRC

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.

Usage

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.

Removal

Unmerge

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

External resources

References