Netboot from a Docker Container

This Docker container lets you PXE boot a whole bunch of installers and utilities on your local network, without much mucking about configuring DHCP and TFTP servers, using the excellent netboot.xyz project.

It provides a ProxyDHCP service, so for most clients your network's existing DHCP server (e.g. your home router) continues to hand out IP addresses as normal. However when a PXE client makes a DHCP request, this container also responds to announce itself as a TFTP network boot target. It does this using dnsmasq to run a very minimal DHCP server, on top of the linuxserver/docker-netboot.xyz container.

Why would I want this?!

I created this because I can never find a serviceable USB stick that's not in use when I want to run a Linux installer/memtest/Clonezilla etc, but I don't need to permanently run a DHCP and TFTP server - most of the time my router is just fine.

How do I run it on Linux?

Option 1: Running it directly

On Linux you can run something like:

docker run --net=host --cap-add=NET_ADMIN -e DHCP_RANGE_START=192.168.0.1 samdbmg/dhcp-netboot.xyz

Make sure you adjust the IP address in DHCP_RANGE_START to the first address on your network. dnsmasq will automatically figure out the right subnet mask to use based on your local network setup.

For this to work, it needs to have fairly low-level access to the target network (rather than the Docker internal bridge), which is why you need --net=host. It will need to open several ports on your system in order to act as a DHCP server, and also a web server to serve up the various menus. If that's not practical (e.g. because you're already using those ports), try Option 2.

Don't forget, if you've got a firewall running on your system you'll need to allow UDP traffic to ports 67 (DHCP), 69 (TFTP) and 4011 (PXE), along with TCP port 80 (HTTP) for the built in webserver. For ufw, try:

sudo ufw allow proto udp from any to any port 67
sudo ufw allow proto udp from any to any port 69
sudo ufw allow proto udp from any to any port 4011
sudo ufw allow proto tcp from any to any port 80

Don't forget to remove the rules when you're done!

Option 2: Docker Compose

Docker Compose has support for the ipvlan networking driver which creates virtual interfaces with their own IP address, and might be easier in some situations. This repository includes a docker-compose.yml file to run it that way.

You will need to identify a suitable IP address on your network to use for the container, along with the interface and IP ranges to use.

Run something along the lines of this, substituting the addresses for the ones on your network as needed:

export INTERFACE=`ip route | awk '/default/ { print $5 }'`
export GATEWAY=`ip route | awk '/default/ { print $3 }'`
export SUBNET=192.168.0.1
export CONTAINER_IP=192.168.0.250
docker-compose up

Make sure you do docker-compose down when you're finished to tidy up afterwards.

What about Mac/Windows?

On Mac and Windows Docker is usually a VM running in the background, and the client is set up to (mostly) transparently pass commands through to that VM and deal with forwarded ports and the like.

Unfortunately that doesn't work here, because then your Docker host doesn't have an address on the network it is acting as DHCP server for. However all is not lost, because a Vagrantfile is provided here to let you run the container in a Virtualbox VM. By default a simple vagrant up will only start the demo (see below), but you can specify the machine to start instead:

DHCP_RANGE_START=192.168.0.1 vagrant up netboot
vagrant ssh netboot -c 'docker logs -f samdbmg-dhcp-netboot.xyz'

Note: You might be prompted to select which network the VM should connect to, choose the one matching the IP address you gave.

It will boot an Ubuntu VM, install Docker on it and then fetch and start the container. The second command will SSH you into the VM and start tailing the netboot containers logs.

For this to work on Windows using Hyper-V as a backend, you'll need to use an Administrator command prompt.

Booting a Device

Either way, once you've got your container up and running on your network, boot another device on the same network and ask it to boot from "LAN" or "PXE" or "Network Boot" or whatever that device happens to call it.

You should be presented with a nice menu of live disks, installers and utilities to run, which will be downloaded from the Internet as needed.

Note: When using EFI systems, you might be prompted to push p to boot from a DHCP Proxy (see https://github.com/netbootxyz/netboot.xyz/pull/953 for more on that).

Demo

There's a Vagrantfile in this directory that demonstrates starting up a Virtualbox VM managed by Vagrant, bridged onto your host network and configured to PXE boot. To try it, run ./run-demo.sh 192.168.0.1 which will launch the Docker container and bring up a Vagrant box.

Note: You might be prompted to select which network the VM should connect to, choose the one matching the IP address you gave.

You should see something like (also at slightly better quality on YouTube):

Note that the Virtualbox Extension Pack might be needed for PXE boot to work, and it's configured with 3GB RAM so that live disks ISOs can be downloaded.

Running the demo on Mac/Windows with Virtualbox

Run DHCP_RANGE_START=192.168.0.1 vagrant up netboot demo.

You'll probably be prompted twice for the network to attach to.

Building Locally

Should be as simple as docker build .

Why doesn't it work on $SCHOOL or $COMPANY network

Enterprise-grade networking gear usually has some protections to prevent just anyone running a DHCP server, which might mean this doesn't work across a corporate/school network. Sorry.

Contributing

I've found a problem Open an Issue on the repo, I'll try and get back to you.

I've fixed a problem Yay! Open a PR!