# 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`
- 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:

```text
/srv/pxe
/srv/pxe/http
/srv/pxe/http/images
/srv/pxe/http/nixos
/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:

```text
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
- Rescue environment
- iPXE shell
- Reboot

Kernel and initrd artifacts for installer or rescue entries must be placed under
the matching `/srv/pxe/http/<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.ipxe
curl http://pxe-boot/menu.ipxe
```

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.