instantlinux/dhcpd-dns-pxe repository overview

⁠dhcpd-dns-pxe

Serve DNS and DHCP from one or more small Alpine Linux container(s). This supplies DNS and tftp (for network PXE booting) using dnsmasq, and DHCP using your choice of kea or dnsmasq. Any of the three services can be enabled or disabled. ISC dhcpd is deprecated by its maintainers, and replaced here with kea in January 2026 starting with tag 3.0.2-r0-2.91-r0. Look at the subnet and reservation definitions for breaking changes.

⁠Usage

In docker-compose.yml or helm, set the environment variables for your environment.

Mount these under /etc:

• /etc/kea.d/local/reserve-.conf: Add any hardware MAC addresses for which you want static IP assignments (see dhcpd man page⁠)
• /etc/dnsmasq.d/local/hosts: Add entries you want added dnsmasq's DNS service (see syntax⁠)

Mount your PXE boot images and client definitions under /tftpboot/pxelinux. Kea stores reservations on a mariadb/mysql database: generate a secret for database access, and create an empty database kea with a user kea@%:

CREATE DATABASE kea;
GRANT USAGE ON *.* TO `kea`@`%` IDENTIFIED BY '<password>';
GRANT ALL PRIVILEGES ON `kea`.* TO `kea`@`%`;

If you're using Swarm, see the docker-compose.yml file provided here in the source directory. This repo has complete instructions for building a kubernetes cluster⁠ where you can launch with helm⁠, or kubernetes.yaml⁠ using make and customizing Makefile.vars⁠ after cloning this repo:

git clone https://github.com/instantlinux/docker-tools.git
cd docker-tools/k8s
make dhcpd-dns-pxe

This builds a failsafe cluster of DHCP servers under kubernetes using the helm chart. Define a ConfigMap with your reservations defined as shown in kea documentation, and hosts defined as in the dnsmasq documentation. If a replica goes down, the others will continue to assign addresses. They won't conflict thanks to the way DHCP protocol works; a client will use the first address offered and ignore any additional offers from the server pool. Subsequent requests will be checked against the reservations database.

Verified to work with a single subnet and with the limited set of DHCP/DNS options supported in environment vars defined here. Additional options as defined in the dnsmasq man page⁠ can be specified as any .conf file under /etc/dnsmasq.d/local volume mount, and for dhcpd as any .conf file under /etc/dhcpd.d/local.

I don't use the DHCP feature of dnsmasq; its software configuration is hugely different from ISC/kea and much more difficult to customize if you've been using ISC all along. If you've been using dnsmasq all along, simply set variable DHCP_ENABLE=no and volume-mount your configuration as /etc/dnsmasq.d/local/dhcpd-options.conf; dnsmasq will serve DHCP on port 67 if you have any such options specified.

⁠Variables

These variables can be passed to the image from kubernetes.yaml or docker-compose.yml as needed:

⁠Secrets

⁠Contributing

If you want to make improvements to this image, see CONTRIBUTING⁠.