Public Repository

Last pushed: 4 months ago
Short Description
tftpd (tftp-hpa) in a container
Full Description

tftp-hpa (tftpd) in a container


Project URL:



This source is used to build an image for
The image contains:

  • H. Peter Anvin's tftp server
  • default, minimal configuration that you can easily override
  • syslinux files suitable for a PXE server
  • map file
    to rewrite certain request paths

The runtime image is quite small (roughly 9 MB) since it is based on
Alpine Linux.

The goal is to provide a compromise between a single, monolithic
tftpd image that contains all the things and a flexible tftpd
image that contains just enough to combine with custom-built
data containers or volumes an organization needs to bootstrap
their infrastructure.

Build integrity and docker tags

An unattended test harness runs the build script and acceptance tests.
If all tests pass on master branch in the unattended test harness,
circleci pushes the built image to the Docker hub.

The CI scripts on circleci apply two tags before pushing to docker hub:

  • jumanjiman/tftp-hpa:latest: latest successful build on master branch
  • jumanjiman/tftp-hpa:<date>T<time>-git-<git-hash>: a particular build on master branch

Therefore you can docker pull a specific tag if you don't want latest.


Fetch an already-built image

The runtime image is published as jumanjiman/tftp-hpa.

docker pull jumanjiman/tftp-hpa

List files in the image

The image contains the typical syslinux, efi, and pxelinux files
from syslinux 6.0.3 at /tftpboot/.
List them with:

docker run --rm -t \
  --entrypoint=/bin/sh \
  jumanjiman/tftp-hpa -c "find /tftpboot -type f"

Load NetFilter modules

Add helpers to track connections:

sudo modprobe nf_conntrack_tftp
sudo modprobe nf_nat_tftp

Configure and run

The published image contains just enough files to provide
a base tftpd to PXE-boot your hosts to a simple menu.
The simple menu and
only allow to skip PXE.
Therefore you probably want to override the built-in menu.

Run a container with your own pxelinux.cfg files:

docker run -d -p 69:69/udp \
  -v /path/to/your/pxelinux.cfg:/tftpboot/pxelinux.cfg:ro \

Run a container with your own pxelinux.cfg and map files:

docker run -d -p 69:69/udp \
  -v /path/to/your/pxelinux.cfg:/tftpboot/pxelinux.cfg:ro \
  -v /path/to/your/mapfile:/tftpboot/rules/default:ro \

Use multiple volumes to add site-local boot files and menus
in addition to the built-in syslinux files:

docker run -d -p 69:69/udp \
  -v /path/to/your/pxelinux.cfg:/tftpboot/pxelinux.cfg:ro \
  -v /path/to/your/bootfiles:/tftpboot/site:ro \

Use systemd for automatic startup

Review and potentially modify the sample systemd unit file at
systemd/tftp-hpa.service, then run:

sudo cp systemd/tftp-hpa.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl start tftp-hpa
sudo systemctl enable tftp-hpa


On a docker host, run:


Publish to a private registry

You can push the built image to a private docker registry:

docker tag tftp-hpa registry_id/your_id/tftp-hpa
docker push registry_id/your_id/tftp-hpa


See in this repo.


See LICENSE in this repo.

Docker Pull Command