Installation of ISC Kea DHCP Server
First, apply a few fixes required for boost-1.89.0:
sed -e "s/, modules: \['system'\]//" -i meson.build &&
sed -e "/shared_ptr.hpp/a#include <boost/asio/deadline_timer.hpp>" \
-i src/lib/asiolink/interval_timer.cc &&
sed -e "/posix_time_types.hpp/a#include <boost/asio/deadline_timer.hpp>" \
-i src/lib/asiodns/io_fetch.cc &&
sed -e "/posix_time_types.hpp/a#include <boost/asio/deadline_timer.hpp>" \
-i src/lib/asiodns/tests/io_fetch_unittest.cc
Now, install ISC Kea DHCP Server
by running the following commands:
mkdir build &&
cd build &&
meson setup .. \
--prefix=/usr \
--sysconfdir=/etc \
--localstatedir=/var \
--buildtype=release \
-D crypto=openssl \
-D runstatedir=/run &&
ninja
If tests were enabled, run ninja
test to test the results. There are tests which
require a live database when any of the database hooks are built.
Some tests may fail if IPv6 support is not functional.
To install the ISC Kea DHCP Server
suite, issue the following commands as the root user:
ninja install
Fix some paths coded in the keactrl script:
sed -e "s;\${prefix}/;;" -i /usr/sbin/keactrl
Create some directories and fix their permission settings as the
root user:
install -dm0750 /var/lib/kea
install -dm0750 /var/log/kea
Command Explanations
-D crypto=openssl: Allows using OpenSSL
for communicating with the control-agent and for DNS updates. Use
-D crypto=botan if you want to use
botan. The default provider is openssl.
-D postgresql=enabled or -D mysql=enabled: ISC
Kea can store the leases on a database. This might be useful
in large environments running a cluster of DHCP servers. Using the
memfile backend (which is a
CSV file stored locally) is possible anyhow.
-D tests=enabled: This option is
required to build the test suite. Using this option causes the
build size to increase significantly, so it should only be enabled
if you are going to run the test suite.
-D krb5=enabled: This switch enables
integration with Kerberos for authenticating client computers in an
enterprise environment.
Configuring ISC Kea DHCP Server
The support of IPv4, IPv6 and DDNS has been split into separate
servers which run independently from each other. Each of them has
its own configuration file. Additional
configuration files come from the keactrl agent which is used to
control the servers in an easier way.
Note that the Kea Control Agent is deprecated since version 3.0.0.
Do not confuse kea-ctrl-agent with
keactrl.
Consult the Kea Administrator
Reference Manual for detailed information about the
configuration of ISC Kea as it is
a quite capable system. The configuration shown below is a bare
minimum to get a DHCP server running but it already includes
configuration for DDNS (Dynamic DNS). That setup is best for small
networks with a few clients and low amounts of network traffic. For
larger installations with thousands of clients, ISC Kea can be configured to use databases
such as (mariadb or postgresql) to store the leases and build a
cluster with multiple nodes. It can be integrated with ISC Stork,
which is a management dashboard to ISC
Kea.
If you want to start the DHCP Server at boot, install the
/etc/rc.d/init.d/kea-dhcpd init script
included in the blfs-bootscripts-20250225 package:
make install-kea-dhcpd
Config Files
/etc/kea/keactrl.conf, /etc/kea/kea-ctrl-agent.conf, /etc/kea/kea-dhcp4.conf, /etc/kea/kea-dhcp6.conf, and /etc/kea/kea-dhcp-ddns.conf
Kea Control
Configuration
keactrl is used to
control the independent servers (IPv4, IPv6, DDNS). Its
configuration file, /etc/kea/keactrl.conf, is installed by default
and includes many path settings which are defined from the
configure at build
time. It also includes settings to specify which of the servers
should be started.
-
Control Agent
The Control Agent is a daemon which allows the
(re)configuration of the Kea DHCP service via REST API. Set
ctrl_agent=yes to start the
control agent (service providing a REST API), set
ctrl_agent=no in case the
control agent is not needed.
-
IPv4 DHCP server
This daemon handles requests for IPv4 addresses. Set
dhcp4=yes to start it, set
dhcp4=no in case the IPv4
service is not needed.
-
IPv6 DHCP server
This daemon handles requests for IPv6 addresses. Set
dhcp6=yes to start it, set
dhcp6=no in case the IPv6
service is not needed.
-
Dynamic DNS
This daemon is used to update a DNS server dynamically when
Kea assigns an IP address to a device. Set dhcp_ddns=yes to enable it, set
dhcp_ddns=no if dynamic DNS
updates are not needed.
The Netconf service is not installed because the required
dependencies are not installed by BLFS, and configuring it
correctly is complicated.
With the following command, Kea will be configured to start the
DHCP service for IPv4 and the dynamic DNS update, while the
control agent and the DHCP service for IPv6 remain down. Tweak
the command to match your needs on started services and execute
as the root user:
sed -e "s/^dhcp4=.*/dhcp4=yes/" \
-e "s/^dhcp6=.*/dhcp6=no/" \
-e "s/^dhcp_ddns=.*/dhcp_ddns=yes/" \
-e "s/^ctrl_agent=.*/ctrl_agent=no/" \
-i /etc/kea/keactrl.conf
Control Agent Configuration
The provided configuration could be used without changes.
However, in BLFS, objects like sockets are stored in /run rather than in /tmp.
cat > /etc/kea/kea-ctrl-agent.conf << "EOF"
// Begin /etc/kea/kea-ctrl-agent.conf
{
// This is a basic configuration for the Kea Control Agent.
// The RESTful interface will be available at http://127.0.0.1:8000/
"Control-agent": {
"http-host": "127.0.0.1",
"http-port": 8000,
"control-sockets": {
"dhcp4": {
"socket-type": "unix",
"socket-name": "/run/kea/kea4-ctrl-socket"
},
"dhcp6": {
"socket-type": "unix",
"socket-name": "/run/kea/kea6-ctrl-socket"
},
"d2": {
"socket-type": "unix",
"socket-name": "/run/kea/kea-ddns-ctrl-socket"
}
},
"loggers": [
{
"name": "kea-ctrl-agent",
"output_options": [
{
"output": "/var/log/kea/kea-ctrl-agent.log",
"pattern": "%D{%Y-%m-%d %H:%M:%S.%q} %-5p %m\n"
}
],
"severity": "INFO",
"debuglevel": 0
}
]
}
}
// End /etc/kea/kea-ctrl-agent.conf
EOF
IPv4 DHCP
Server Configuration
A sample configuration file is created in /etc/kea/kea-dhcp4.conf. Adjust the file to
suit your needs or overwrite it by running the following command
as the root user (you'll need to
edit this file anyway: at least the interfaces field, the ddns-qualifying-suffix field, and
almost all the fields in Subnet4):
cat > /etc/kea/kea-dhcp4.conf << "EOF"
// Begin /etc/kea/kea-dhcp4.conf
{
"Dhcp4": {
// Add names of your network interfaces to listen on.
"interfaces-config": {
"interfaces": [ "eth0", "eth2" ]
},
"control-socket": {
"socket-type": "unix",
"socket-name": "/run/kea/kea4-ctrl-socket"
},
"lease-database": {
"type": "memfile",
"lfc-interval": 3600,
"name": "/var/lib/kea/kea-leases4.csv"
},
"expired-leases-processing": {
"reclaim-timer-wait-time": 10,
"flush-reclaimed-timer-wait-time": 25,
"hold-reclaimed-time": 3600,
"max-reclaim-leases": 100,
"max-reclaim-time": 250,
"unwarned-reclaim-cycles": 5
},
"renew-timer": 900,
"rebind-timer": 1800,
"valid-lifetime": 3600,
// Enable DDNS - Kea will dynamically update the BIND DNS server
"ddns-send-updates" : true,
"ddns-qualifying-suffix": "your.domain.tld",
"dhcp-ddns" : {
"enable-updates": true
},
"subnet4": [
{
"id": 1001, // Each subnet requires a unique numeric id
"subnet": "192.168.56.0/24",
"pools": [ { "pool": "192.168.56.16 - 192.168.56.254" } ],
"option-data": [
{
"name": "domain-name",
"data": "your.domain.tld"
},
{
"name": "domain-name-servers",
"data": "192.168.56.2, 192.168.3.7"
},
{
"name": "domain-search",
"data": "your.domain.tld"
},
{
"name": "routers",
"data": "192.168.56.2"
}
]
}
],
"loggers": [
{
"name": "kea-dhcp4",
"output_options": [
{
"output": "/var/log/kea/kea-dhcp4.log",
"pattern": "%D{%Y-%m-%d %H:%M:%S.%q} %-5p %m\n"
}
],
"severity": "INFO",
"debuglevel": 0
}
]
}
}
// End /etc/kea/kea-dhcp4.conf
EOF
IPv6 DHCP
Server Configuration
The configuration for IPv6 is similar to the configuration of
IPv4. The configuration file is /etc/kea/kea-dhcp6.conf.
Dynamic DNS Configuration
If there is a BIND-9.20.16 server running, ISC Kea can update the DNS records when it
gives an IP address to a client. A sample configuration file is
created in /etc/kea/kea-dhcp-ddns.conf. Adjust the file to
suit your needs or overwrite it by running the following command
as the root user:
cat > /etc/kea/kea-dhcp-ddns.conf << "EOF"
// Begin /etc/kea/kea-dhcp-ddns.conf
{
"DhcpDdns": {
"ip-address": "127.0.0.1",
"port": 53001,
"control-socket": {
"socket-type": "unix",
"socket-name": "/run/kea/kea-ddns-ctrl-socket"
},
"tsig-keys": [
{
"name" : "rndc-key",
"algorithm" : "hmac-sha256",
"secret" : "1FU5hD7faYaajQCjSdA54JkTPQxbbPrRnzOKqHcD9cM="
}
],
"forward-ddns" : {
"ddns-domains" : [
{
"name" : "your.domain.tld.",
"key-name": "rndc-key",
"dns-servers" : [
{
"ip-address" : "127.0.0.1",
"port" : 53
}
]
}
]
},
"reverse-ddns" : {
"ddns-domains" : [
{
"name" : "56.168.192.in-addr.arpa.",
"key-name": "rndc-key",
"dns-servers" : [
{
"ip-address" : "127.0.0.1",
"port" : 53
}
]
}
]
},
"loggers": [
{
"name": "kea-dhcp-ddns",
"output_options": [
{
"output": "/var/log/kea/kea-ddns.log",
"pattern": "%D{%Y-%m-%d %H:%M:%S.%q} %-5p %m\n"
}
],
"severity": "INFO",
"debuglevel": 0
}
]
}
}
// End /etc/kea/kea-dhcp-ddns.conf
EOF
![[Note]](../images/note.png)
Note
The value of secret is just an
example. Generate the key for your installation by using the
rndc-confgen -a
command or the tsig-keygen command which
both are provided by BIND-9.20.16.
In this example configuration, it is assumed that the DNS
server runs on the same machine as Kea does (accessible via
127.0.0.1) and that this machine
has the IP 192.168.56.2.