#### Beyond Linux® From Scratch (System V Edition) - Version 12.3

### Chapter 20. Major Servers

- Prev

  BIND-9.20.6

- Next

  ProFTPD-1.3.8b

- Up
- Home

# Kea 2.6.1 DHCP Server

## Introduction to ISC Kea DHCP Server

The ISC Kea package contains the server programs for DHCP. It is the successor of the old ISC DHCP server which is end-of-life since December 2022.

This package is known to build and work properly using an LFS 12.3 platform.

### Package Information

- Download (HTTP): https://downloads.isc.org/isc/kea/2.6.1/kea-2.6.1.tar.gz

- Download MD5 sum: 5f4fe79ed29f5ff2802e2961d1827b25

- Download size: 9.9 MB

- Estimated disk space required: 1.5 GB (332 MB installed; add 4 GB for tests)

- Estimated build time: 4.1 SBU (with parallelism=4; add 12 SBU for tests)

### Additional Downloads

- Required patch: https://www.linuxfromscratch.org/patches/blfs/12.3/kea-2.6.1-fix_boost_1_87-1.patch

### Kea Dependencies

#### Required

Boost-1.87.0 and log4cplus-2.1.2

#### Optional

MIT Kerberos V5-1.21.3, Valgrind-3.24.0; for documentation: Doxygen-1.13.2, Graphviz-12.2.1, and sphinx_rtd_theme-3.0.2; for tests: GoogleTest

#### Optional database backends

MariaDB-11.4.5 or MySQL, and PostgreSQL-17.4

## Kernel Configuration

You must have Packet Socket support. IPv6 support is optional.

    [*] Networking support --->                                                [NET]
      Networking options --->
        <*/M> Packet socket                                                 [PACKET]
        [*]   TCP/IP networking                                               [INET]
        <*>     The IPv6 protocol --->                                        [IPV6]

## Installation of ISC Kea DHCP Server

First, apply a patch which fixes an issue with the most recent version of boost:

    patch -Np1 -i ../kea-2.6.1-fix_boost_1_87-1.patch

Install ISC Kea DHCP Server by running the following commands:

    ./configure --prefix=/usr        \
                --sysconfdir=/etc    \
                --localstatedir=/var \
                --enable-shell       \
                --with-openssl       \
                --disable-static     \
                --docdir=/usr/share/doc/kea-2.6.1 &&
    make

To test the results, you must have installed GoogleTest and kept its source. You should also have passed `--with-gtest-source=/path/to/googletest/sourcedir` to configure above. Run the tests with make check. Three tests in the TLSTest suite are known to fail.

To install the ISC Kea DHCP Server suite, issue the following commands as the `root` user:

    make -j1 install

## Command Explanations

`--enable-shell`: Allows building kea-shell, a command line interface for the control agent.

`--with-openssl`: Allows using OpenSSL for communicating with the control-agent and for DNS updates.

`--disable-static`: This switch prevents installation of static versions of the libraries.

`--with-pgsql` or `--with-mysql`: 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.

`--enable-generate-docs`: If documentation is to be rebuilt, add that option. Several dependencies must be installed for generating the documentation.

make -j1 install: ISC does not recommend any form of parallel or job server options when doing the install.

## Configuring ISC Kea DHCP Server

The support of IPv4, IPv6 and DDNS has been split into separate servers which runs 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 easy way.

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 might be working for small networks with a few clients and low traffic. For greater installations with thousands of clients, ISC Kea can be configured to use databases (mariadb or postgresql) to store the leases and build a cluster with multiple nodes. It can be integrated to 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 due to 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 DHCP service for IPv4 is not wanted.

- IPv6 DHCP server

  This daemon handles requests for IPv6 addresses. Set `dhcp6=yes` to start it, set `dhcp6=no` in case DHCP service for IPv6 is not wanted.

- 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` in case dynamic DNS updates are not wanted.

The Netconf service is not installed because required dependencies are not covered by the current BLFS book. .

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 but 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.
      // RESTful interface to 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/kea4-ctrl-socket"
          },
          "dhcp6": {
            "socket-type": "unix",
            "socket-name": "/run/kea6-ctrl-socket"
          },
          "d2": {
            "socket-type": "unix",
            "socket-name": "/run/kea-ddns-ctrl-socket"
          }
        },

        "loggers": [
          {
            "name": "kea-ctrl-agent",
            "output_options": [
              {
                "output": "/var/log/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/kea4-ctrl-socket"
        },

        "lease-database": {
          "type": "memfile",
          "lfc-interval": 3600
        },

        "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 DNS
        "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-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.6 server running, ISC Kea can update the DNS 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-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-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

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

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

## Contents

Installed Programs: keactrl, kea-admin, kea-ctrl-agent, kea-dhcp4, kea-dhcp6, kea-dhcp-ddns, kea-lfc, kea-shell
Installed Libraries: libkea-asiodns.so, libkea-asiolink.so, libkea-cc.so, libkea-cgfclient.so, libkea-cryptolink.so, libkea-d2srv.so, libkea-database.so, libkea-dhcp_ddns.so, libkea-dhcp++.so, libkea-dhcpsrv.so, libkea-dns++.so, libkea-eval.so, libkea-exceptions.so, libkea-hooks.so, libkea-http.so, libkea-log.so, libkea-process.so, libkea-stats.so, libkea-tcp.so, libkea-util.so, and libkea-util-io.so
Installed Directories: /etc/kea, /usr/include/kea, /usr/lib/kea, /usr/lib/python3.13/site-packages/kea, /usr/share/kea, /usr/share/doc/kea-2.6.1, and /var/lib/kea

### Short Descriptions

keactrl | Tool to control (start/stop) the server processes.
kea-admin | kea-admin is a shell script which offers database maintenance.
kea-ctrl-agent | Daemon which exposes a RESTful control interface for managing Kea servers.
kea-dhcp4 | The server daemon providing IPv4 addresses.
kea-dhcp6 | The server daemon providing IPv6 addresses.
kea-dhcp-ddns | The server daemon performing the dynamic DNS updates.
kea-lfc | The kea-lfc service process removes redundant information from the files used to provide persistent storage for the memfile database backend. It is run by the Kea DHCP server.
keashell | RESTful client to the ISC Kea services.

- Prev

  BIND-9.20.6

- Next

  ProFTPD-1.3.8b

- Up
- Home