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
• Generated iPXE menu: /srv/pxe/boot/menu.ipxe
• Boot binaries copied from the Nix ipxe package:
  • /srv/pxe/boot/ipxe.efi
  • /srv/pxe/boot/undionly.kpxe

Directory Layout

The host creates these directories with systemd tmpfiles:

/srv/pxe
/srv/pxe/boot
/srv/pxe/nixos
/srv/pxe/ubuntu
/srv/pxe/rescue

The generated menu currently exposes entries for:

• NixOS installer
• Rescue environment
• iPXE shell
• Reboot

Kernel and initrd artifacts for installer or rescue entries must be placed under the matching /srv/pxe/<entry>/ directories by an operator or a separate build process. This repository defines the service and menu, not the installer images.

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/menu.ipxe
curl -I http://pxe-boot/boot/ipxe.efi
curl -I http://pxe-boot/boot/undionly.kpxe