Docker - DHCP Server

Since mid 2023 I have been running a Docker ISC Kea Image using base Docker Alpine Linux images, with S6 init system. (ISC Kea is a modern replacement for their DHCP.) The main DHCP server runs on my main server and I have an automatic fall over back up on my separate Linux router. I basically followed the Kea template Home Network of a Power User. I was never quite sure I had the automatic fall over back-up working. On 2023-01-02 I modified a configuration file on the primary server with a syntax error. Today, 8 days later I notice millions of lines of errors on my log files. Sure enough the backup had simply been working. I fixed up the simple syntax error and the primary server took back over. Everything basically worked as expected.

ISC also has a project for a simple GUI interface primarily for Kea and basic for Bind9. There is apparently no Alpine package yet for Stork.

ISC-Kea seems to be provided in a number of packages

isc-kea-adminThis package provides backend database initialization and migration scripts and a DHCP benchmark tool. If you are not using a database backend, you may not need this.Not using a database backend at this time
isc-kea-commonCommon libraries for the ISC Kea DHCP server. Install this.Need this.
isc-kea-ctrl-agentThis package provides the REST API service agent for Kea DHCP.?
isc-kea-devDevelopment headers for ISC Kea DHCP server. Install if you plan to create any custom Kea hooks.Probably do not need.
isc-kea-dhcp4-serverDHCPv4 server.Need this.
isc-kea-dhcp6-serverDHCPv6 server.Do not need at this time.
isc-kea-dhcp-ddns-serverDDNS server.Need this.
isc-kea-docKea documentation. Highly recommended.On a Docker container?
isc-kea-hook-flex-optionFlexible Options hook.What is this?
isc-kea-hook-haHigh Availability hook.What is this?
isc-kea-hook-lease-cmdsLease Commands hook.What is this?
isc-kea-hook-mysql-cbMySQL Configuration Backend.Dont need this at this time.
isc-kea-hook-pgsql-cbPostgreSQL Configuration Backend.Dont need this.
isc-kea-hook-stat-cmdsStatistics Commands hook.?
isc-kea-httpThis package is essential, install it.It is essential…
isc-kea-perfdhcpOptional. Includes a DHCP performance testing tool from ISC.?
isc-kea-shellText client for Kea DHCP Control Agent.?

From IANA Service Name and Transport Protocol Port online Number Registry:

bootps    67   {tcp, udp}       Bootstrap Protocol Server (DHCP)
bootpc    68   {tcp, udp}       Bootstrap Protocol Client (DHCP)

The Kea Control Agent uses port 8000 by default, but that value can be manually defined in its configuration file. (Usually located at /etc/kea/kea-ctrl-agent.conf.) This port needs to be open and accessible on every server that hosts a Kea DHCP service and a Kea Control Agent.

This is a good case where the Docker network type needs to be set to host. The DHCP server needs to be directly on the host to function.

sudo nmap --script broadcast-dhcp-discover will test the DHCP servers on the same network.


  • kea-dhcp4 -t /app/dhcpv4.conf to test the kea-dhcp4 configuration files /app/dhcpv4.conf
  • kea-dhcp4 -c /app/dhcpv4.conf to start kea dhcp4 using configuration file /app/dhcpv4.conf

Use of symlink, TL;DR;

  • kea-dhcp4 -c /app/dhcpv4_plus.conf to start kea dhcp4 using configuration file /app/dhcpv4_plus.conf. This configuration file is designed to work with the kea control agent setup. Where as the basic configuration /app/dhcpv4_basic.conf is not.
  • kea-ctrl-agent -t /app/kea-ctrl-agent.conf to test the kea-cont-agent configuration file /app/kea-ctrl-agent.conf
  • kea-ctrl-agent -c /app/kea-ctrl-agent.conf to start the kea-cont-agent configuration file /app/kea-ctrl-agent.conf

I have stored log files in the .config directory that is a Docker mounted volume for persistence and easy external viewing outside container. The following logs files can be seen.

  • .config/log/kea-dhcp4-commands.log
  • .config/log/kea-dhcp4-dhcpsrv.log
  • .config/log/kea-dhcp4-leases.log
  • .config/log/kea-dhcp4.log
  • .config/log/kea-dhcp4-ha-hooks.log
  • docker attach kptr-kea-1 to attach to running container
  • kea-dhcp4 -v To check running version
  • /app/www/public/data/pages/docker_notes/docker-dhcp.txt
  • Last modified: 2024-02-24 Sat wk08 14:18
  • by baumkp