This is an old revision of the document!
Docker - DHCP Kea 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, 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.
The article by Lee Hutchinson Finally upgrading from isc-dhcp-server to isc-kea for my homelab was writen after I made the upgrade. He wrote an a much earlier article on running BIND9 and ISC_DHCP in his blog. It looks like he updated this Doing DNS and DHCP for your LAN the old way—the way that works with a semi related part 2 Banish OEM self-signed certs forever and roll your own private LetsEncrypt
Kea Packages and Hooks
ISC-Kea seems to be provided in a number of packages
| Package | Use | Descriptiion | Comment |
|---|---|---|---|
| isc-kea | ISC Kea metapackage | This installs everything | |
| isc-kea-admin | This 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-common | X | Common libraries for the ISC Kea DHCP server. Install this. | Need this. |
| isc-kea-ctrl-agent | X | This package provides the REST API service agent for Kea DHCP. | ? |
| isc-kea-dev | Development headers for ISC Kea DHCP server. Install if you plan to create any custom Kea hooks. | Probably do not need. | |
| isc-kea-dhcp4-server | X | DHCPv4 server. (isc-kea-dhcp4 for Alpine) | Need this. |
| isc-kea-dhcp6-server | DHCPv6 server. (isc-kea-dhcp6 for Alpine) | Do not need at this time. | |
| isc-kea-dhcp-ddns | DDNS server. | Need this. | |
| isc-kea-doc | Kea documentation. Highly recommended. Example documents are located here /usr/share/doc/kea/examples/ | On a Docker container? | |
| isc-kea-hook-flex-option | Flexible Options hook. | What is this? | |
| isc-kea-hook-ha | X | High Availability hook. | What is this? |
| isc-kea-hook-lease-cmds | X | Lease Commands hook. | What is this? |
| isc-kea-hook-mysql-cb | MySQL Configuration Backend. | Dont need this at this time. | |
| isc-kea-hook-pgsql-cb | PostgreSQL Configuration Backend. | Dont need this. | |
| isc-kea-hook-stat-cmds | Statistics Commands hook. | ? | |
| isc-kea-http | This package is essential, install it. | It is essential… | |
| isc-kea-perfdhcp | Optional. Includes a DHCP performance testing tool from ISC. | ? | |
| isc-kea-shell | X | Text client for Kea DHCP Control Agent. | ? |
See 16.4. Available Hook Libraries for the available hook libraries. I have removed the hook reference from the above table that I do not use.
Network Ports
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.
Docker Network Type
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.
DHCP testing
sudo nmap --script broadcast-dhcp-discover will test for DHCP servers on the same network. It will only report the first DHCP server discovered.
Reference
main dhcp4
kea-dhcp4 -t /app/dhcpv4.confto test the kea-dhcp4 configuration files/app/dhcpv4.confkea-dhcp4 -c /app/dhcpv4.confto start kea dhcp4 using configuration file/app/dhcpv4.conf
- Kea Docs The DHCPv4 Server
kea-dhcp4 -c /app/dhcpv4_plus.confto 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.confis not.
Upgrade problem to 2.6.0 with dhcp4 parameter id in subnet configuration, TL;DR;
ctrl-agent -t /app/kea-ctrl-agent.conf
kea-ctrl-agent -t /app/kea-ctrl-agent.confto test the kea-cont-agent configuration file/app/kea-ctrl-agent.confkea-ctrl-agent -c /app/kea-ctrl-agent.confto start the kea-cont-agent configuration file/app/kea-ctrl-agent.conf
Kea logging
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
Kea Miscellaneous
docker attach kptr-kea-1to attach to running containerkea-dhcp4 -vTo check running version
References
- KPTree.net's bare metal implementation of dns - dhcp, based upon ISC Bind9 and DHCP on Debian 10 (was originally Ubuntu).
- ISC documentation
Kea read the docs https://kea.readthedocs.io/en/latest/arm/intro.html Intro give the latest docs and the into states which version this is. A specific version can be found by changing the latest in the html path to the Kea version required, e.g. as of writing the current verion I am using is 2.6.1, so 'https://kea.readthedocs.io/en/2.6.1/arm/intro.html'' Intro