ProxmoxVEDHelperScripts/docs/guides/netboot-xyz.md

netboot.xyz — Self-Hosted PXE Boot Server on Proxmox

What is netboot.xyz?

netboot.xyz is a network boot (PXE) utility. It lets any machine on your network boot from a menu of operating systems and tools — without a USB stick, CD/DVD, or pre-downloaded ISO.

Think of it like a universal boot menu that loads over the network.

What your self-hosted container actually does

Your LXC container hosts only two things:

• iPXE bootloader binaries (.efi, .kpxe files — a few hundred KB each)
• iPXE menu files (plain text .ipxe scripts that define the menu structure)

That's it. The container serves ~4 MB of files total.

When a machine PXE-boots, it:

1. Fetches the bootloader binary from your container (via TFTP or HTTP)
2. The bootloader loads the menu from your container
3. You pick an OS
4. The OS installer or live system loads directly from upstream internet mirrors at boot time

Your container is the signpost. The internet is the library.

Important: Clients need internet access to actually install/boot an OS. Your container itself does not need to store or proxy OS images.

What you can boot

Category	Examples
OS Installers	Debian, Ubuntu, Fedora, Rocky Linux, Alpine, Arch, NixOS, ...
Live Systems	Kali Live, Tails, Mint Live, Manjaro Live, ...
Rescue Tools	SystemRescue, Clonezilla, GParted, Rescuezilla, Memtest86
Virtualization	Proxmox VE, Harvester, VMware ESXi
BSD	FreeBSD, OpenBSD
Utilities	ShredOS (disk wipe), DBAN, ZFSBootMenu, Super Grub2

---

Installation

Run on your Proxmox host:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/netboot-xyz.sh)"

Creates a minimal Debian 13 LXC container:

Resource	Value
CPU	1 core
RAM	512 MB
Disk	4 GB
Port (HTTP)	80/TCP
Port (TFTP)	69/UDP

After installation, the web interface is available at:

http://<container-ip>/

It shows a directory listing of all available bootloaders and menu files.

---

How to PXE Boot a Machine

Step 1 — Configure your DHCP server

Your DHCP server needs to tell PXE clients where to find the bootloader.

Required settings:

Setting	Value
Next Server (TFTP)	<container-ip>
Boot filename (UEFI)	netboot.xyz.efi
Boot filename (BIOS/Legacy)	netboot.xyz.kpxe

OPNsense / pfSense: Services → DHCP Server → [interface] → Network Booting

• Enable: checked
• Next server: <container-ip>
• Default BIOS filename: netboot.xyz.kpxe
• UEFI 64-bit filename: netboot.xyz.efi

dnsmasq (Pi-hole, AdGuard Home, OpenWrt):

dhcp-boot=netboot.xyz.kpxe,<container-ip>   # BIOS
# or:
dhcp-boot=netboot.xyz.efi,<container-ip>    # UEFI

ISC DHCP (dhcpd.conf):

next-server <container-ip>;
filename "netboot.xyz.efi";

Step 2 — Enable PXE boot on your client

In the machine's BIOS/UEFI:

• Enable Network Boot / PXE Boot
• Set boot order: Network first (or select once via boot menu, usually F11/F12)

Step 3 — Boot

Power on the machine. The iPXE bootloader loads from your container, shows the menu, and you navigate with arrow keys.

---

UEFI HTTP Boot (no DHCP changes)

Modern UEFI firmware supports booting directly from an HTTP URL — no DHCP options needed.

Load the bootloader directly in the UEFI shell:

http://<container-ip>/netboot.xyz.efi

Proxmox VMs: Set the VM network boot URL in the UEFI shell, or use iPXE chaining in the VM BIOS.

---

Available Bootloader Files

All files are served at http://<container-ip>/:

File	Protocol	Architecture	Use case
netboot.xyz.efi	HTTP/TFTP	x86_64 UEFI	Standard UEFI boot
netboot.xyz-snp.efi	HTTP/TFTP	x86_64 UEFI	UEFI SNP — tries all network devices
netboot.xyz-snponly.efi	HTTP/TFTP	x86_64 UEFI	UEFI SNP — only chained device
netboot.xyz.kpxe	TFTP	x86_64 BIOS	Legacy BIOS, built-in iPXE NIC drivers
netboot.xyz-undionly.kpxe	TFTP	x86_64 BIOS	Legacy BIOS fallback (NIC issues)

BIOS vs UEFI: Use .efi for UEFI systems, .kpxe for legacy BIOS. Mixing them causes silent failures.

---

Customizing the Menu

Edit /var/www/html/boot.cfg inside the container:

# SSH into the container, then:
nano /var/www/html/boot.cfg

Changes take effect immediately — no service restart needed.

Common customizations:

# Set a default boot entry with 10-second timeout:
set menu-timeout 10000
set menu-default linux

# Override the mirror used for Ubuntu:
set mirror http://de.archive.ubuntu.com/ubuntu

Full documentation: netboot.xyz/docs

---

Updating

The update script preserves your boot.cfg customizations, updates menus and bootloaders to the latest release:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVED/main/ct/netboot-xyz.sh)"

---

Troubleshooting

Client can't reach the container / TFTP timeout

• Check that UDP/69 (TFTP) and TCP/80 (HTTP) are not blocked between client and container
• Proxmox firewall: add rules to allow these ports inbound on the container
• Check that the container is in the same VLAN/subnet as the client, or that inter-VLAN routing is configured

Menu loads but OS download fails or is slow

• Expected — OS files come from the internet, not your container
• Client needs internet access (direct or via NAT through Proxmox)
• For air-gapped networks, you need to mirror OS images locally (advanced, see netboot.xyz docs)

Machine boots to local disk instead of PXE

• Check boot order in BIOS/UEFI — network boot must come first, or select it manually via F11/F12
• Some UEFI systems require Secure Boot to be disabled for iPXE

UEFI machine ignores the boot filename

• Some DHCP servers send the same filename option to both BIOS and UEFI clients
• Use vendor class matching in your DHCP config to send .efi only to UEFI clients
• OPNsense/pfSense handle this automatically when you set both BIOS and UEFI filenames separately

netboot.xyz.kpxe works but netboot.xyz.efi doesn't (or vice versa)

• BIOS systems → use netboot.xyz.kpxe or netboot.xyz-undionly.kpxe
• UEFI systems → use netboot.xyz.efi or netboot.xyz-snp.efi