diff --git a/docs/NEXT_PHASE.md b/docs/NEXT_PHASE.md new file mode 100644 index 0000000..5459d1f --- /dev/null +++ b/docs/NEXT_PHASE.md @@ -0,0 +1,156 @@ +# Phase 6 — recommendations + +The v0.2.0 cut leaves PXEForge in a state where the entire protocol stack +and operator UI are exercised by 66 automated tests, the container is +multi-arch buildable, and the image ships at ~97 MB. What's left before +this looks and feels like a 1.0 product is mostly **real-hardware +validation** plus a small batch of features that can only sensibly be +designed once we've watched real machines image. + +This doc is a punch list, ordered by what I'd do first if I had a week. + +## Tier 1 — must-do before we call anything "stable" + +### 1. Real-hardware validation matrix + +We have CI tests for every protocol leg, but no end-to-end PXE on real +firmware. Build a small matrix: + +| client | firmware | OS family | pass criteria | +|-------------------------------------|-----------|------------|---------------------------| +| any 10-y-old mini-PC | Legacy BIOS | Ubuntu Server 24.04 | gets to GRUB / installer | +| Intel NUC / similar | UEFI x64 | Windows 11 | reaches "where do you want to install" | +| Raspberry Pi 4 | UEFI ARM64 | Raspberry Pi OS | gets to login prompt | +| Dell / HP business laptop | UEFI x64 | Fedora | one of: kernel boot or wimboot | + +Add a `docs/HARDWARE_VALIDATION.md` checklist that records what worked, +firmware versions, and any quirks. Anything weird gets a regression +test in the relevant crate. + +### 2. Boot menu hotkey + UI accessibility audit + +The iPXE menu has number-key + letter hotkeys but no documentation on +what they map to. Generate a printable cheat-sheet from +`crates/http-api/src/ipxe_script.rs` so operators don't have to read +the source. Run a screen-reader pass over the web UI — most of it +should be fine since we're mostly tables + form labels, but the +Terminal pane and the SSE log output need explicit `aria-live` +regions. + +### 3. Boot.wim re-patch detection + +Bootimus v0.1.62's "fingerprint of patched inputs + Save & Re-patch" +pattern is a small but high-value feature: when an operator changes +the SMB host override or upgrades wimboot, the existing patched +boot.wim is silently stale. We should: + +- Hash the inputs (smb_host, smb_share, startnet.cmd content, + wimboot binary digest) into the IsoMeta; +- Surface a "needs re-patch" warning on the Storage tab when the + hash drifts; +- Add a "Re-patch SMB" button that re-runs the WimPatcher. + +## Tier 2 — features that round out pre-beta + +### 4. Auto-install file library + +iVentoy and Bootimus both support attaching `autounattend.xml` / +`preseed.cfg` / `kickstart.cfg` to an image. The mechanics are +straightforward: store files under `/autoinstall//`, +expose CRUD via `/api/autoinstall-files`, and modify the WimPatcher ++ Linux kernel cmdline to fetch + apply the right file. Placeholders +worth supporting (Bootimus pattern): `{{MAC}}`, `{{HOSTNAME}}`, +`{{IP}}`, `{{SERVER_ADDR}}`, `{{IMAGE_FILENAME}}`, substituted +serve-side per request. + +### 5. Wake-on-LAN trigger + +A natural pair with per-MAC host bindings: bind a MAC to an image, +then click "Wake & Image" to send the magic packet and let PXEForge +do the rest. Implementation is small (`udp/9` broadcast, magic packet +construction) but it makes the bound-host workflow feel instant. + +### 6. Distro profile manifest + +Today, distro detection lives as Rust match arms in `introspect.rs` +and the kernel cmdline templates live in `store.rs`. Bootimus extracts +this into a JSON manifest that ships embedded in the binary AND is +overridable by the operator at runtime — so a new distro can be added +without rebuilding the container. Worth porting; it'd let community +contributions land as PRs to a single JSON file. + +### 7. Syslog receiver + +`smee` ships one. The use case: WinPE / Linux installers can be +configured to syslog over the network to the PXE server; if we have +an endpoint and a place in the UI to view per-client diagnostics, +post-mortem on a failed install gets dramatically easier. + +### 8. UEFI HTTP Boot validation + +Option 60 = `HTTPClient` is wired up in `decide()` already, but +we've never tested it on real firmware. Some Dell + Lenovo UEFIs +prefer it over PXE-via-TFTP. A quick check on a real machine +(disable TFTP boot in firmware, force HTTP boot) and a regression +test would be nice. + +## Tier 3 — bigger lifts, only if there's demand + +### 9. Pure-Rust SMB server + +`smbd` from Samba is ~80 MB of the runtime image. There are pure-Rust +SMB2 server crates (`smbd-server`, `smb-rs`) of varying maturity. +Replacing the dep would slim the image by ~40% and remove the +`CAP_SYS_ADMIN` requirement for SMB. Worth a spike, not necessarily +landable in Phase 6. + +### 10. IPv6 / DHCPv6 + +PXE-over-IPv6 is real (RFC 5970). Some sites are v6-only. Worth +implementing once we know we have one. Until then, IPv4-only is the +right default — flipping the bit on v6 without v6 testing is asking +for silent breakage. + +### 11. Multi-replica deployment + +The current design assumes one PXEForge per broadcast domain. Two +proxies on the same L2 will race; the gate queue is in-memory, etc. +For HA we'd need to: +- Externalize the gate queue (Redis, etcd) or lean into "the menu is + cheap to refetch if a replica dies"; +- Ensure DHCP proxy replies are deterministic so a client always + gets the same answer regardless of which replica replied; +- Document the L2 collision domain story. + +This is a large lift and should only happen if someone's actually +asking for it. + +### 12. Pi 4 / SBC quirks + +Raspberry Pi netboot uses a specific DHCP option-43 vendor field + +TFTP path layout that PXEForge doesn't currently special-case. There's +a spec; the work is small once we have a Pi to test on. + +## What I'd skip + +- **A custom DHCP server (not proxy).** The proxy mode is the right + abstraction; full DHCP would need raw sockets + a lot of corner-case + handling for problems no operator wants us to solve. +- **A pluggable backend abstraction à la Tinkerbell.** Tinkerbell does + it because they integrate with k8s CRDs. PXEForge's "the file system + IS the database" model is simpler and good enough for the target + audience. Don't add a Backend trait until something asks for it. +- **Multiple language UIs.** Bootimus added these in v0.1.62 and the + translations are LLM-generated. Skip until we have real users + asking for non-English. + +## Quick wins (could land in a single afternoon) + +- Add a Grafana dashboard JSON to `deploy/grafana/` driven off the + new `/metrics` endpoint. +- A `pxeforge bench` subcommand that runs a 10-second internal load + test (synthetic gate joins) so an operator can sanity-check tuning. +- Ship a basic `docker-compose.yml` for the Unraid path that demos + the new themes / progress widget. +- Generate a printable single-page operator runbook from the README + + architecture.md (e.g. `cargo xtask runbook`).