Setting Up a PXE Boot Server with netboot.xyz and dnsmasq

Network booting has become an essential tool for system administrators and developers who need to deploy or test operating systems across multiple machines. In this guide, I'll walk you through setting up a PXE (Preboot Execution Environment) boot server using netboot.xyz and dnsmasq.

What You'll Need

Before diving in, make sure you have:

1. Docker installed on your host machine
2. dnsmasq installed and accessible

Getting Started

Step 1: Deploy the netboot.xyz Container

The first thing you'll want to do is get the netboot.xyz Docker container running. Head over to the netbootxyz/docker-netbootxyz GitHub repository and follow their documentation to pull and start the container. This container handles the TFTP server and hosts the boot files, so you won't need to configure those separately.

Here's a docker-compose.yml example to get you started:

Save this as docker-compose.yml and start it with:

The web interface will be available at http://10.11.0.15:3000 where you can customize your boot menu and manage assets.

Step 2: Configure dnsmasq

This is where the magic happens. You'll need to configure dnsmasq to act as a DHCP proxy and direct PXE clients to your netboot.xyz server. Open up /etc/dnsmasq.conf and add the following configuration:

Let's break down what each directive does:

port=0 - Disables the DNS server functionality if you're not using dnsmasq for DNS. If you're already running another DNS server, this prevents conflicts.

interface=eth0 - Restricts dnsmasq to listen only on the eth0 interface. You can add multiple interface lines if you need to listen on several networks, or remove this entirely to listen on all interfaces.

log-dhcp - Enables logging of DHCP requests, which is incredibly useful for debugging boot issues.

bind-dynamic - Allows dnsmasq to bind to interfaces that are added after the service starts, particularly useful in dynamic network environments.

dhcp-authoritative - Tells dnsmasq to respond authoritatively to DHCP requests, which speeds up the boot process by reducing timeout periods.

dhcp-range with proxy mode - This is the critical configuration that makes everything work seamlessly. The 10.11.0.0 network address with 255.255.255.0 subnet mask defines your network range, but the real magic is in the proxy keyword.

Why proxy mode matters: By using proxy mode, dnsmasq doesn't assign IP addresses or interfere with your existing DHCP server. Instead, it listens for PXE boot requests and responds only to those, providing the necessary boot information while your existing DHCP server continues handling all IP address assignments. This means you don't need to touch your router, firewall, or primary DHCP server configuration at all. You can deploy this PXE boot server on any machine in your network without disrupting existing services or requiring administrative access to your main network infrastructure. It's a completely non-invasive addition to your network.

pxe-service lines - These define what happens when a client requests a PXE boot. You'll need two entries: one for legacy BIOS systems (x86PC) and one for modern UEFI systems (X86-64_EFI). The 10.11.0.15 address points to the machine running your netboot.xyz Docker container.

Notice that we're not including enable-tftp in this configuration. That's because the netboot.xyz Docker container already provides its own TFTP server, so enabling it in dnsmasq would create a conflict.

Step 3: Start Your Services

Once your configuration is in place, restart dnsmasq to apply the changes:

Verify that both dnsmasq and your Docker container are running without errors.

Testing Your Setup

To test your PXE boot server, configure a test machine (physical or virtual) to boot from the network. You should see the netboot.xyz menu appear, offering various installation options for different operating systems.

If you run into issues, check the dnsmasq logs (typically in /var/log/syslog or via journalctl -u dnsmasq) to see if DHCP requests are being received and processed correctly.

Wrapping Up

With this setup, you now have a flexible PXE boot server that can coexist with your existing network infrastructure. The beauty of the proxy mode approach is that it requires zero changes to your existing DHCP server or network configuration. You're simply adding PXE boot capabilities on top of what you already have, making this an ideal solution for home labs, testing environments, or anywhere you frequently need to deploy or reinstall systems without disrupting your production network.