A docker container which provides a TFTP server preconfigured for installing Debian on PXE-booting clients

debian-install docker-container pxe tftp

Dockerfile 49.4%
Makefile 40.3%
Shell 10.3%

Find a file

Karl E. Jorgensen fb9c3ec5e9 All checks were successful Docker Build / build (push) Successful in 1m29s Details Add link to helm chart		2026-02-16 17:26:14 +00:00
.forgejo/workflows	Back to a single architecture	2026-02-16 12:16:04 +00:00
menu.conf.d
.dockerignore
.gitignore
Dockerfile	Add healthcheck and better dox	2026-02-16 13:21:46 +00:00
entrypoint	Add healthcheck and better dox	2026-02-16 13:21:46 +00:00
healthcheck	Add healthcheck and better dox	2026-02-16 13:21:46 +00:00
LICENSE	Update license	2026-02-16 12:23:14 +00:00
local-dev.md
Makefile
openlogo-nd.svg
README.md	Add link to helm chart	2026-02-16 17:26:14 +00:00
screenshot.png
splash.png
splash.svg
Tux.svg

README.md

pxeboot

This container provides a TFTP server preconfigured to allow PXE Booting clients to install Debian GNU/Linux.

This allows installation of the operating system using only a network connection, and requires no local media.

To make use of it, the DHCP server should be configured with:

next-server << ip address of pxeboot server>>;
filename "lpxelinux.0";

When booting, clients should be presented with a menu similar to this:

Worth reading:

https://www.debian.org/releases/stable/amd64/ch04s05.en.html

Running it

PXE-booting clients rely on the DHCP response to give directions to the TFTP server. So the DHCP server needs to be configured accordingly. Exactly how this is done depends on your DHCP server (many are available). Reading https://wiki.syslinux.org/wiki/index.php?title=PXELINUX is a good starting point.

PXE-booting clients generally do not support using DNS to resolve names into IP addresses.

Some DHCP servers may support resolving the DNS name into an IP address; but may only resolve the name upon startup, rather than at run-time - the latter will incur a time penalty which might get in the way of giving timely DHCP response.

The end result is that the IP address of the TFTP server usually needs to be static. It cannot be dynamically assigned (e.g. via DHCP) - unless you plan on restarting the DHCP server(s) whenever the IP address changes.

For the ISC DHCP Server adding this at the right place in the configuration should suffice:

# IP address of TFTP server:
next-server 1.2.3.4;
# Filename to load from the TFTP server
filename "lpxelinux.0";

TFTP is a protocol which does not work well with Network Address Translation (NAT) or IP masquerading. It can be made to work with NAT/masquerading, using the nf_nat_tftp & nf_conntrack_tftp netfilter kernel modules; although these modules are not loaded by default by most installations.

In other words: The TFTP server needs to be routable by clients without "interference" by NAT/masquerading in most cases.

Thus: If running this container in docker: network selection matters. The default docker network implements NAT, and does not load the tftp helper modules.

To run this in Kubernetes, see the accompanying helm chart.

Healthcheck

The container provides a healthcheck script at /pxeboot-healthcheck - this will give an exit status of zero if all is well.

Extending It

New menu entries can be added as files in /srv/tftp/pxelinux.cfg/default.d. When the container starts, it will simply concatenate all *.conf files (in asciibetical order) to create the menu.

License

The Linux Mascot (a.k.a. "Tux"): Copyright by Larry Ewing (Thanks to lewing@isc.tamu.edu Larry Ewing and The GIMP). The SVG version (used here) is licensed under the Creative Commons CC0 1.0 Universal Public Domain Dedication

The Debian Logo is Copyright (c) 1999 Software in the Public Interest, Inc., and are released under the terms of the GNU Lesser General Public License, version 3 or any later version, or, at your option, of the Creative Commons Attribution-ShareAlike 3.0 Unported License.