nixos/docs/pxe-boot.md

pxe-boot

The pxe-boot host serves HTTP boot assets for iPXE clients.

Host Role

• Hostname: pxe-boot
• Web service: nginx on TCP port 80
• PXE root: /srv/pxe
• HTTP root for scripts and images: /srv/pxe/http
• TFTP root for first-stage bootloaders: /srv/pxe/tftp
• iPXE entry script: /srv/pxe/http/boot.ipxe
• Generated iPXE menu: /srv/pxe/http/menu.ipxe
• SystemRescue iPXE script: /srv/pxe/http/systemrescue.ipxe
• TFTP fallback script: /srv/pxe/tftp/autoexec.ipxe
• Boot binaries copied from the Nix ipxe package:
  • /srv/pxe/tftp/ipxe.efi
  • /srv/pxe/tftp/undionly.kpxe

Directory Layout

The host creates these directories with systemd tmpfiles:

/srv/pxe
/srv/pxe/http
/srv/pxe/http/images
/srv/pxe/http/nixos
/srv/pxe/http/systemrescue
/srv/pxe/http/ubuntu
/srv/pxe/http/rescue
/srv/pxe/tftp

Mount shared image storage under /srv/pxe/http, preferably /srv/pxe/http/images unless a menu entry expects files in a specific directory such as /srv/pxe/http/nixos.

The HTTP iPXE chain is:

undionly.kpxe or ipxe.efi
  -> autoexec.ipxe from the TFTP root, when iPXE requests it
  -> http://192.168.2.247/boot.ipxe
  -> http://192.168.2.247/menu.ipxe

The generated menu currently exposes entries for:

• NixOS installer
• SystemRescue environment
• iPXE shell
• Reboot

Kernel and initrd artifacts for the NixOS installer entry must be placed under /srv/pxe/http/nixos by an operator or a separate build process.

The SystemRescue entry expects the source ISO at:

/srv/pxe/http/images/systemrescue.iso

The stage-systemrescue.service oneshot extracts that ISO into:

/srv/pxe/http/systemrescue

The rescue menu entry then chains http://192.168.2.247/systemrescue.ipxe, which loads the SystemRescue kernel and initramfs from the extracted tree and uses archiso_http_srv to fetch the squashfs payload over HTTP.

Validation

Safe evaluation check:

nix eval .#nixosConfigurations.pxe-boot.config.system.build.toplevel.drvPath --raw

After deployment by an operator, basic service checks are:

curl http://pxe-boot/boot.ipxe
curl http://pxe-boot/menu.ipxe
curl http://pxe-boot/systemrescue.ipxe
curl -I http://pxe-boot/systemrescue/sysresccd/boot/x86_64/vmlinuz
curl -I http://pxe-boot/systemrescue/sysresccd/boot/x86_64/sysresccd.img

During a successful BIOS chainload, TFTP should deliver undionly.kpxe once, then nginx should log requests for /boot.ipxe and /menu.ipxe. Repeated TFTP downloads of undionly.kpxe indicate the iPXE stage is still not reaching the HTTP chain.