updated documentation

docs/pxe-boot.md

@@ -0,0 +1,52 @@
+# 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:
+
+```text
+/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:
+
+```bash
+nix eval .#nixosConfigurations.pxe-boot.config.system.build.toplevel.drvPath --raw
+```
+
+After deployment by an operator, basic service checks are:
+
+```bash
+curl http://pxe-boot/boot/menu.ipxe
+curl -I http://pxe-boot/boot/ipxe.efi
+curl -I http://pxe-boot/boot/undionly.kpxe
+```