netboot.xyz

netboot.xyz is an iPXE-based boot menu. Machines on the LAN start over the network and pick from installers, live systems and tools for dozens of operating systems: Debian, Ubuntu, Fedora, Rocky, Alma, Arch, Clonezilla, GParted, memtest and more. Kernels, initrds and images are fetched from the internet on demand, so no ISO files have to be uploaded or kept on the node.

The netboot.xyz app announcement TBA

netboot.xyz is a community application from the tebbiworld repository. Documentation and source can be found on Github

The upstream image ghcr.io/netbootxyz/netbootxyz is pinned to version 0.7.6-nbxyz24. The module adds:

• a split into two rootless containers, so the menu web app does not sit in the host network;
• a password in front of the menu web app, which has no login of its own;
• a proxyDHCP configuration generated from the settings in the NethServer interface, serving the boot file that matches each client's firmware;
• integration with Traefik (TLS, optional client-network allowlist), firewall openings and backup.

The signed Secure Boot files are taken unmodified from the releases of the iPXE project.

• One instance per node. TFTP and proxyDHCP bind fixed ports in the host network.
• Only one PXE server may answer in a network.
• Clients need internet access; the operating system images always come from the internet.
• IPv4 only.
• The web app can mirror images locally, but the module does not publish that store over HTTP.
• Secure Boot requires firmware that trusts the “Microsoft 3rd party UEFI CA”, and always loads its menus from boot.netboot.xyz.

The host network is required because TFTP transfers use changing ports and proxyDHCP has to see LAN broadcasts. NethServer sets net.ipv4.ip_unprivileged_port_start=23, so the rootless container can bind these ports. dnsmasq needs NET_ADMIN and NET_RAW for DHCP; rootless, these apply only inside the module's namespace.

Both containers share the volume netbootxyz-config with the boot files and menus. On first start the image downloads the menus and boot files of the current netboot.xyz version and the Secure Boot files, which takes one to two minutes.

The module lives in the software repository tebbiworld:

https://raw.githubusercontent.com/tebbiworld/ns8-huginn/repomd/ns8/updates/

Install it on a NethServer 8 node:

add-module ghcr.io/tebbiworld/netbootxyz:latest 1

Save the settings once after the installation. To remove the instance:

remove-module --no-preserve netbootxyz1

Switch proxyDHCP on in the module. The existing DHCP server keeps assigning addresses; the node only adds the boot information for machines that start over the network, and picks the file from the firmware identifier in DHCP option 93:

Clients that already are iPXE — Proxmox and QEMU virtual machines, many server network cards, recognised by the user class iPXE — receive the boot file directly in the first proxyDHCP offer, because iPXE discards the broadcast reply of the boot server exchange on port 4011.

Set option 66 to the address of the node and option 67 to the name of the boot file, both as ASCII text. If your DHCP server has a Next Server field (SIADDR), set it to the address of the node as well.

Important limitation: routers send the same boot file to every client. A BIOS machine that receives netboot.xyz.efi aborts with “exec format error” and reboots endlessly. For mixed networks, prefer proxyDHCP.

LAN » General Setup » the affected subnet » DHCP Server Option, data type “ASCII Character”.

Configurations for other routers are welcome here.

After it starts, the netboot.xyz file looks for local menus on the TFTP server that the DHCP server announced as next server, which is not necessarily this node.

• If the DHCP server announces none, netboot.xyz loads its menus from boot.netboot.xyz over HTTPS.
• If next server points at this node, the local menus are used. They can be edited in the web app.
• If it points at a device without TFTP, a few timeouts occur; at the prompt “DHCP proxy detected” the key p switches to this node.

The operating system images come from the internet in every case.

• The netboot.xyz web app has no login of its own. The module puts an nginx with basic auth in front of it and publishes it only through Traefik; the web app itself cannot be reached from outside.
• Whoever has access to the web app decides what every PXE client in the network boots. Set a password and use the allowlist of client networks.
• proxyDHCP affects every machine in the selected network that starts over the network.

The backup covers the volume netbootxyz-config with the boot files, the menus and your own customisations, and the credentials file of the web app.

• netboot.xyz
• Upstream container image
• iPXE releases
• Module repository and bug reports

Private hobby project, shared as-is. No warranty, no guaranteed support, use at your own risk. Unofficial community package, not affiliated with or endorsed by the netboot.xyz project. netboot.xyz is licensed Apache-2.0; the module's own code is licensed GPL-3.0-or-later.