docs(netboot-xyz): update guide — all 31 assets, 8GB disk, fix lint errors

2026-03-20 16:05:44 +01:00
parent 91950cc983
commit 0deb262d5f
1 changed files with 214 additions and 0 deletions
--- a/docs/guides/netboot-xyz.md
+++ 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://<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:
+
+```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`