Hassle Free PXE With Netboot.xyz!

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?

1. A device (such as a laptop, desktop, or server) sends an Ethernet request for IP address configuration to a nearby DHCP server.
2. The DHCP server assigns an IP address and other networking information to the device.
3. 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.
4. The network source sends the requested boot file to the device, which executes it and boots up.

What Is It Used For?

1. 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.
2. 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.
3. 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.
4. 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.
5. 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 -su - .
• edit your interfaces file using nano /etc/network/interfacesnano /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 networkingsystemctl 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:

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 /dockertree -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 treeapt update && apt install tree

Edit The Docker Compose File

Use nano /docker/netboot/docker-compose.yamlnano /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 psdocker 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 netbootxyzdocker 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:

1. Under the “Menus” tab you will find your boot.cfg file as well as a variety of .ipxe files you can edit.
2. 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 IP192.168.1.2 and file namenetboot.xyz.kxpe

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-servernano /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 aip 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.confnano /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:

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:

1. Press F2 or DEL during boot to enter BIOS setup
2. Go to the Boot Menu (this may also be under the Advanced Settings depending on BIOS version)
3. Select Boot Priority (or Boot Configuration) and uncheck Boot Network Devices Last
4. Go to Network Boot and enable UEFI PXE & iSCSI
5. 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!