From 0deb262d5f64de9ae5d812991a11644f516bfc28 Mon Sep 17 00:00:00 2001 From: "CanbiZ (MickLesk)" <47820557+MickLesk@users.noreply.github.com> Date: Fri, 20 Mar 2026 16:05:44 +0100 Subject: [PATCH] =?UTF-8?q?docs(netboot-xyz):=20update=20guide=20=E2=80=94?= =?UTF-8?q?=20all=2031=20assets,=208GB=20disk,=20fix=20lint=20errors?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/guides/netboot-xyz.md | 214 +++++++++++++++++++++++++++++++++++++ 1 file changed, 214 insertions(+) create mode 100644 docs/guides/netboot-xyz.md diff --git a/docs/guides/netboot-xyz.md b/docs/guides/netboot-xyz.md new file mode 100644 index 000000000..651f5fa9b --- /dev/null +++ b/docs/guides/netboot-xyz.md @@ -0,0 +1,214 @@ +# 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 +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:/// +``` + +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) | `` | +| 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_: `` +- _Default BIOS filename_: `netboot.xyz.kpxe` +- _UEFI 64-bit filename_: `netboot.xyz.efi` + +**dnsmasq (Pi-hole, AdGuard Home, OpenWrt):** + +``` +dhcp-boot=netboot.xyz.kpxe, # BIOS +# or: +dhcp-boot=netboot.xyz.efi, # UEFI +``` + +**ISC DHCP (`dhcpd.conf`):** + +``` +next-server ; +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:///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:///`: + +| 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: + +```bash +# SSH into the container, then: +nano /var/www/html/boot.cfg +``` + +Changes take effect immediately — no service restart needed. + +Common customizations: + +```bash +# 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](https://netboot.xyz/docs/) + +--- + +## Updating + +The update script preserves your `boot.cfg` customizations, updates menus and bootloaders to the latest release: + +```bash +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`