What is PXE Boot?
PXE (Preboot Execution Environment) Boot, also known as PXE boot, is a method of booting a computer from a network source. It allows a device to boot up automatically using a network connection instead of a traditional local storage medium such as a hard drive or USB drive. Services such as netboot.xyz help streamline this process.
How Does It Work?
- A device (such as a laptop, desktop, or server) sends an Ethernet request for IP address configuration to a nearby DHCP server.
- The DHCP server assigns an IP address and other networking information to the device.
- The device then requests a boot file from a PXE-compliant network source, such as a TFTP (Trivial File Transfer Protocol) server or a NAS (Network-Attached Storage) device.
- The network source sends the requested boot file to the device, which executes it and boots up.
What Is It Used For?
- Boot management : PXE boot allows administrators to easily manage boot settings for multiple devices, making it easier to deploy images or updates across a network.
- Image deployment : Organizations can use PXE boot to deploy operating systems, applications, or other software updates to their devices automatically, reducing the need for manual installation.
- Remote desktop and thin client management : PXE boot is often used in remote desktop and thin client environments, where devices are managed centrally from a server or network source.
- Automated testing and quality assurance : Developers can use PXE boot to automate testing and quality assurance processes by booting devices with custom images and running automated tests.
- Emergency recovery and troubleshooting : In the event of a failure or hardware issue, administrators can use PXE boot to quickly recover a device by booting it from a network source
Installing Netboot
Set A Static IP
This process varies depending on what network manager your OS uses. The following instructions work for Debian 12. Google “how to set a static IP on <distro name>” and follow the relevant instructions if your distribution is not Debian.
- Switch to root with the command
su -
. - edit your interfaces file using
nano /etc/network/interfaces
with the following information
# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).
source /etc/network/interfaces.d/*
# The loopback network interface
auto lo
iface lo inet loopback
# The primary network interface
allow-hotplug eth0
# Rename eth0 to your interface name. use the command "ip a" to find it
iface eth0 inet static
# Set the static IP and subnet mask you want for your server
address 192.168.1.2/24
# Enter your router's IP address
gateway 192.168.1.1
- Restart your networking service using
systemctl restart networking
Installing netboot.xyz using docker
Ensure your system meets the following minimum System Requirements:
- i686, x86_64, or aarch64 Processor
- Bare Metal or Virtual Machine
- A hard wired ethernet connection (WiFi networking is not supported)
- At least 4GB of RAM is recommended
The following instructions will be based on a headless Debian 12 Bookworm install running inside a virtual machine on TrueNAS Scale 24.10.02, but should work for any bare metal installation or virtualization software as long as the host network is accessible.
Install docker and docker compose using docker’s official guide. Supported distributions are:
Platform | x86_64 / amd64 | arm64 / aarch64 | arm (32-bit) | ppc64le | s390x |
---|---|---|---|---|---|
CentOS | ✅ | ✅ | ✅ | ||
Debian | ✅ | ✅ | ✅ | ✅ | |
Fedora | ✅ | ✅ | ✅ | ||
Raspberry Pi OS (32-bit) | ✅ | ||||
RHEL | ✅ | ✅ | ✅ | ||
SLES | ✅ | ||||
Ubuntu | ✅ | ✅ | ✅ | ✅ | ✅ |
Create Directories and Docker Compose YAML File
mkdir -p /docker/netboot/assets /docker/netboot/configtouch /docker/netboot/docker-compose.yaml
The output of
tree -L 2 /docker
should look like this
/docker
└── netboot
├── assets
├── config
└── docker-compose.yaml
if tree is not recognized, install it with
apt update && apt install tree
Edit The Docker Compose File
Use
nano /docker/netboot/docker-compose.yaml
to paste the following:
---
version: "2.1"
services:
netbootxyz:
image: ghcr.io/netbootxyz/netbootxyz
container_name: netbootxyz
environment:
- MENU_VERSION=2.0.47 # optional
- NGINX_PORT=80 # optional
- WEB_APP_PORT=3000 # optional
volumes:
- ./config:/config # optional
- ./assets:/assets # optional
ports:
- 3000:3000 # optional, destination should match ${WEB_APP_PORT} variable above.
- 69:69/udp
- 8080:80 # optional, destination should match ${NGINX_PORT} variable above.
restart: unless-stopped
Bring Up The Stack
cd /docker/netboot/
docker compose up -d
Check That Netboot Is Running
Enter
docker ps
in the command prompt. The output should look like this:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
83e6c5192156 lscr.io/linuxserver/netbootxyz:latest "/init" 14 seconds ago Up 12 seconds 0.0.0.0:69->69/udp, :::69->69/udp, 0.0.0.0:3000->3000/tcp, :::3000->3000/tcp, 0.0.0.0:8080->80/tcp, :::8080->80/tcp netbootxyz
Check the logs with
docker logs netbootxyz
.
Navigate to the Netboot Web UI
At this point the containers homepage should be accessible. Use the static IP we set earlier to access the interface on port 3000. If you set the same IP as in this guide that will be http://192.168.1.2:3000
You should see the dashboard like so:

- Under the “Menus” tab you will find your boot.cfg file as well as a variety of .ipxe files you can edit.
- Under the local assets tab you can find a list of remote assets that you can pull to host locally.
Creating a Local Mirror
If you would like to create a local mirror, you can do so by editing the boot.cfg file in the Menus section.

Just select the boot.cfg file in the left menu and replace “set live_endpoint https://github.com/netbootxyz” with
set live_endpoint http://192.168.1.2:8080
Be aware that you won’t be able to boot from any environments that haven’t been downloaded.
Configuring DHCP
Some routers allow their DHCP servers to be configured to point to a server for PXE booting. The UniFi UDM Pro/SE for instance can be configured under Settings > Network > Choose Network > DHCP Service Management > Show Options where you will find “Network Boot“. Enter the
Server IP
and
file name
Since most home routers don’t have that feature, we will set up a DHCP server on our server using isc-dhcp-server as per the official netboot.xyz docs.
Install isc-dhcp-server
To install the DHCP server under Debian and Ubuntu run:
sudo apt install isc-dhcp-server
Configuring the DHCP Server
edit the isc-dhcp-server config file with
nano /etc/default/isc-dhcp-server
and configure at least one of the interface variables with the name of the interface you want to run the DHCP server on. The modified section is highlighted in yellow.
Be sure to run
ip a
to check your interface name if you are unsure.
# Defaults for isc-dhcp-server (sourced by /etc/init.d/isc-dhcp-server)
# Path to dhcpd's config file (default: /etc/dhcp/dhcpd.conf).
#DHCPDv4_CONF=/etc/dhcp/dhcpd.conf
#DHCPDv6_CONF=/etc/dhcp/dhcpd6.conf
# Path to dhcpd's PID file (default: /var/run/dhcpd.pid).
#DHCPDv4_PID=/var/run/dhcpd.pid
#DHCPDv6_PID=/var/run/dhcpd6.pid
# Additional options to start dhcpd with.
# Don't use options -cf or -pf here; use DHCPD_CONF/ DHCPD_PID instead
#OPTIONS=""
# On what interfaces should the DHCP server (dhcpd) serve DHCP requests?
# Separate multiple interfaces with spaces, e.g. "eth0 eth1".
INTERFACESv4="eth0"
#INTERFACESv6=""
Open your dhcp.conf file with
nano /etc/dhcp/dhcpd.conf
and make the following changes:
option arch code 93 = unsigned integer 16;
subnet 192.168.1.0 netmask 255.255.255.0 {
range 192.168.1.10 192.168.1.60; # Change this range as appropriate for your network
next-server 192.168.0.2; # Change this to the address of your DHCP server
option subnet-mask 255.255.255.0;
option routers 192.168.1.1; # Change this to the address of your router
option broadcast-address 192.168.1.255;
option domain-name "debian_server.lan"; # This is optional
option domain-name-servers 1.1.1.1;
if exists user-class and ( option user-class = "iPXE" ) {
filename "http://boot.netboot.xyz/menu.ipxe";
} elsif option arch = encode-int ( 16, 16 ) {
filename "http://boot.netboot.xyz/ipxe/netboot.xyz.efi";
option vendor-class-identifier "HTTPClient";
} elsif option arch = 00:07 {
filename "netboot.xyz.efi";
} else {
filename "netboot.xyz.kpxe";
}
}
Once the changes are saved, restart the dhcp server.
sudo systemctl start isc-dhcp-server
Enable the DHCP server to autostart the server after reboots
sudo systemctl enable isc-dhcp-server
The DHCP configuration file can have the following bootfile names specified:
bootfile name | description |
---|---|
netboot.xyz.kpxe | Legacy DHCP boot image file, uses built-in iPXE NIC drivers |
netboot.xyz-undionly.kpxe | Legacy DHCP boot image file, use if you have NIC issues |
netboot.xyz.efi | UEFI boot image file, uses built-in UEFI NIC drivers |
netboot.xyz-snp.efi | UEFI w/ Simple Network Protocol, attempts to boot all net devices |
netboot.xyz-snponly.efi | UEFI w/ Simple Network Protocol, only boots from device chained from |
netboot.xyz-arm64.efi | DHCP EFI boot image file, uses built-in iPXE NIC drivers |
netboot.xyz-arm64-snp.efi | UEFI w/ Simple Network Protocol, attempts to boot all net devices |
netboot.xyz-arm64-snponly.efi | UEFI w/ Simple Network Protocol, only boots from device chained from |
etboot.xyz-rpi4-snp.efi | UEFI for Raspberry Pi 4, attempts to boot all net devices |
Connect A Client to Netboot
To connect your client to the PXE boot server you must first set PXE boot as the 1st boot priority in your BIOS’ boot config options. This process varies between motherboard manufacturers, but in general it requires the following steps:
- Press F2 or DEL during boot to enter BIOS setup
- Go to the Boot Menu (this may also be under the Advanced Settings depending on BIOS version)
- Select Boot Priority (or Boot Configuration) and uncheck Boot Network Devices Last
- Go to Network Boot and enable UEFI PXE & iSCSI
- Select either Ethernet1 Boot or Ethernet2 Boot
Please refer to your motherboard’s instruction manual for more detailed instructions.
All that’s left to do now is boot and let the magic happen!
If all went according to plan you should be greeted with the following page:

You can now select your distribution and iPXE will work it’s magic. Netboot will pull the required files from the internet and boot in to the OS!
Very nicely done!