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. Kea has several features ISC lacks, including: Modular components, JSON configuration with a REST API, data isolation, and a web based GUI.

Warning
ISC DHCP server is no longer maintained.

Installation

USE flags

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

+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)
+openssl Use dev-libs/openssl instead of dev-libs/botan
+samples Install sample configuration files
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
mysql Add mySQL Database support
postgres Add support for the postgresql database
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)
Data provided by the Gentoo Package Database · Last update: 2024-05-08 23:30 More information about USE flags

Emerge

root #emerge --ask net-misc/kea

Configuration

Note
Configurations in this article are represented as fragments which must be combined.

Files

Kea's configuration files are located in /etc/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

Many configuration directives are similar or shared between files.

interface-config

The interface-config directive is used to define which interfaces and IPs Kea listens on:

FILE /etc/kea/kea-dhcp4.conf
{
    "Dhcp4": {
        "interfaces-config": {
            "interfaces": [ "ethernet2/192.168.2.1", "fib.lan", "ax1800" ]
        }
    }
}
Tip
Defining the IP address is unnecessary, but may be done.
Note
Only the interface name must be defined, but an IP address can be specified to force Kea to only listen on that address.

subnet4

IPv4 subnet configuration in Kea is relatively straightforward. Each structure in this list must contain a subnet. In most cases, pools and option-data are also defined. reservations allow for advanced configuration, basic usage is described below.

subnet

The subnet, in {ip}/{cidr} format is mandatory for each subnet4 and defines which subnet is defined by the structure:

FILE /etc/kea/kea-dhcp4.confDefine subnet 192.168.2.0/24
{
    "Dhcp4": {
        "subnet4": [
            {
                "subnet": "192.168.2.0/24"
            }
        ]
    }
}

pools

Although not strictly required, pools are typically defined for each subnet, and define where hosts without reservations pull IPs:

FILE /etc/kea/kea-dhcp4.confDefine the pool to range from 192.169.2.100 to 192.168.2.200
{
    "Dhcp4": {
        "subnet4": [
            {
                "pools": [ { "pool": "192.168.2.100 - 192.168.2.200" } ]
            }
        ]
    }
}

option-data

In most cases, at least a router is provided by DHCP servers, but other DHCP options/codes can be defined here:

FILE /etc/kea/kea-dhcp4.confDefine the router as 192.168.2.1
{
    "Dhcp4": {
        "subnet4": [
            {
                "option-data": [
                    {
                        "name": "routers",
                        "data": "192.168.2.1"
                    }
                ]
            }
        ]
    }
}

Reservations

Kea offers several options for identifying and configuring hosts:

See also
KEA: Host Reservations in DHCPv4
FILE /etc/kea/kea-dhcp4.confReserve 192.168.2.10 for aa:bb:cc:11:22:33 with 1.1.1.1 as a DNS server.
{
    "Dhcp4": {
        "subnet4": [
            {
                "reservations": [
                    {
                        "hw-address": "aa:bb:cc:11:22:33",
                        "ip-address": "192.168.2.10",
                        "hostname": "larry",
                        "option-data": [ {
                            "name": "domain-name-servers",
                            "data": "1.1.1.1"
                        } ]
                    }
                ]
            }
        ]
    }
}

control-socket

Control sockets can be used to reload Kea's config at runtime, by default the following control-socket is defined:

FILE /etc/kea/kea-dhcp4.conf
{
    "Dhcp4": {
        "control-socket": {
            "socket-type": "unix",
            "socket-name": "/run/kea/kea4-ctrl-socket"
        }
    }
}

lease-database

By default, Kea uses a memfile lease-database backend. If compiled with the mysql USE flag, a SQL database can be used as the backend. The default lease-database config is as follows:

FILE /etc/kea/kea-dhcp4.conf
{
    "Dhcp4": {
        "lease-database": {
            "type": "memfile",
            "lfc-interval": 3600
        }
    }
}

expired-leases-processing

As described in the example config:

FILE /etc/kea/kea-dhcp4.confAnnotated default config
{
    "Dhcp4": {
        "expired-leases-processing": {
            "reclaim-timer-wait-time": 10,  // Expired leases will be reclaimed every 10 seconds
            "flush-reclaimed-timer-wait-time": 25,  // Every 25 seconds, reclaimed leases which have expired more than then hold-reclaimed-time will be removed
            "hold-reclaimed-time": 3600,  // The amount of time leases must be expire3d before they can be reclaimed
            "max-reclaim-leases": 100,  // The maximum number of leases which can be reclaimed during each cycled, defined by max-reclaim-time
            "max-reclaim-time": 250,  // The amount of time in ms between each reclaim cycle
            "unwarned-reclaim-cycles": 5  // The number of reclamation cycles allowed before an expired lease still present in the database will trigger an alert
        }
    }
}

loggers

See also
Kea: Logging

To make Kea log to syslog, the following adjustments can be made:

FILE /etc/kea/kea-dhcp4.confConfigure Kea to use syslog
{
    "Dhcp4": {
        "loggers": [
            {
                "name": "kea-dhcp4",
                "output_options": [
                    {
                        "output": "syslog"
                    }
                ],
    
                "severity": "INFO",  // One of FATAL, ERROR, WARN, INFO, DEBUG
                "debuglevel": 0  // 0 is least verbose, 99 is most verbose. Kea can generate LOTS of log information
            }
        ]
    }
}

Service

OpenRC

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

/etc/conf.d/kea contains settings for dhcp4, dhcp6, and ddns, as well as configuration locations for those files.

Warning
The default location specified in /etc/conf.d/kea likely differs from the default filenames in /etc/kea.

Once configured, Kea can be configured to run at startup, and start with:

root #rc-update add kea
root #rc-service kea start
High Availability
Important
Currently the Kea OpenRC scripts do not start the kea-ctrl-agent, so they must be modified for this functionality.

To use the high availability feature of Kea, the kea-ctrl-agent must be started to allow the primary & standby server(s) to communicate.

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
# snip
if ${AGENT:-false} ; then
    start-stop-daemon -m -b -p ${agent_pidfile} \
        -s ${agent_command} -- -c ${agent_config} \
        || return 1
fi
# snip

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
# snip
agent_command="/usr/sbin/kea-ctrl-agent"
agent_config="${AGENT_CONFIG:-/etc/kea/ctrl-agent.conf}"
agent_pidfile="/run/kea-ctrl-agent.pid"
# snip
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 results in 2 PID files being used 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.
Starting after the logger

To ensure Kea starts after eth0 has started, and logging is available, the following can be added to Kea's service configuration:

FILE /etc/conf.d/kea
# snip
rc_need="net.eth0 logger"
# snip
Tip
It is useful to require a logger, so any crash detected by start-stop-daemon is logged.
Runnng as non-root

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

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.

FILE /etc/init.d/kea
start() {
    einfo "Starting kea dhcp services"
    if ${DHCP4:-false} ; then
        start-stop-daemon -m -b -p ${dhcp4_pidfile} --user dhcp \
            -x ${dhcp4_command} -- -c ${dhcp4_config} \
            || return 1
    fi
    if ${DHCP6:-false} ; then
        start-stop-daemon -m -b -p ${dhcp6_pidfile} --user dhcp \
            -x ${dhcp6_command} -- -c ${dhcp6_config} \
            || return 1
    fi
    if ${DDNS:-false} ; then
        start-stop-daemon -m -b -p ${ddns_pidfile} --user dhcp \
            -x ${ddns_command} -- -c ${ddns_config} \
            || return 1
    fi
}

Finally, confirm all Kea configuration files are accessible by the dhcp user, including:

  • /etc/kea
  • Kea log & database files in /var

Usage

Check config

To check a Kea config file, kea-dhcp4 -t can be used:

root #kea-dhcp4 -t /etc/kea/kea-dhcp4.conf
2023-08-08 10:41:23.712 INFO  [kea-dhcp4.hosts/4527.140104273917056] HOSTS_BACKENDS_REGISTERED the following host backend types are available: 
2023-08-08 10:41:23.713 INFO  [kea-dhcp4.dhcpsrv/4527.140104273917056] DHCPSRV_CFGMGR_USE_ADDRESS listening on address 192.168.2.1, on interface ethernet2
2023-08-08 10:41:23.713 INFO  [kea-dhcp4.dhcpsrv/4527.140104273917056] DHCPSRV_CFGMGR_SOCKET_TYPE_DEFAULT "dhcp-socket-type" not specified , using default socket type raw
2023-08-08 10:41:23.714 INFO  [kea-dhcp4.dhcpsrv/4527.140104273917056] DHCPSRV_CFGMGR_NEW_SUBNET4 a new subnet has been added to configuration: 192.168.2.0/24 with params: t1=900, t2=1800, valid-lifetime=3600

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.

External resources

References

Retrieved from "https://wiki.gentoo.org/index.php?title=Kea&oldid=1265538"