Miles Ward
49d0b00a8a
This is the bulk pre-beta cleanup pass. Bumps the workspace to 0.2.0.
Test count is 56 -> 66 (+10), clippy is fully clean across the
workspace (was several dozen warnings).
## New features
**Per-MAC host bindings** (Tinkerbell smee pattern). New
`HostBindings` registry maps a MAC -> preferred boot target, persisted
to <work_dir>/hosts.json. The DHCP reply now embeds `?mac=${mac}` in
the boot.ipxe URL; iPXE substitutes the literal MAC client-side, so
the HTTP layer can short-circuit straight to the bound target instead
of rendering the menu. Reserved menu shortcuts (`_local`, `_gate`,
`_tools_menu`) are valid targets too. New /api/hosts CRUD + a Hosts
tab in the sidebar.
**Prometheus `/metrics`** endpoint. Tiny lock-free implementation —
just AtomicU64s and a Display impl, no `prometheus` / `metrics-rs`
dep. Counters: DHCP replies (per arch label), DHCP declined, TFTP
transfers (per status), TFTP bytes, HTTP requests (per route).
Gauges: ISO count, client count, gate count, gate-imaging, NFS active
mounts, uptime, build info. Plain text exposition format,
text/plain;version=0.0.4 content-type, no auth (all metric values are
non-sensitive counts).
**Light + dark themes**. CSS tokens on `:root` and
`:root[data-theme=light]`, swap by toggle button (top-right) or `T`
hotkey. Persisted in localStorage; pre-paint inline script avoids
dark<->light flash. Light palette designed against the Netbox Labs
reference screenshot — near-white surfaces, soft grey dividers,
accent unchanged for brand consistency. Terminal pane stays dark in
both themes (it's a console, that's the right read).
**Animated SVG logo + forge widget**. New `logo.svg` is a refined
silver/grey anvil. New `anvil-forge.svg` adds rising sparks and a
pulsing underglow via SMIL — pure SVG, no GIF, no JS animation loop.
Used:
- in the **forge progress** widget on Dashboard + Forge Gate, paired
with a `linear-gradient(warn -> accent)` bar with a moving sheen;
goes idle (greyscale, no sheen) at zero imaging load
- in the page-load `<div class=loader>` that replaces the old
"Loading..." text
## Code cleanup pass
`cargo clippy --workspace --all-targets` is now warning-free. Spot
fixes across the tree:
- `format!()`-into-`String` -> `std::fmt::Write::write!`
- manual reverse comparators -> `Reverse`
- `map_or(false, ...)` -> `is_some_and`
- redundant closures -> method references
- `r#"..."#` raw strings without `"` -> `r"..."`
- `std::io::Error::new(Other, ...)` -> `Error::other`
- `as i32` on `c.id()` -> `cast_signed()`
- merged identical match arms
## Windows workflow validation
New integration test synthesizes an ISO9660 with the SOURCES\\BOOT.WIM
sentinel, uploads it, asserts:
1. introspection labels it `windows_pe` with has_boot_wim=true,
2. the boot entry is `BootKind::Wimboot` with all five canonical
files (bootmgr, bootmgr.efi, bcd, boot.sdi, boot.wim),
3. the rendered iPXE script chains wimboot with `initrd --name`
entries for each file, and
4. NO trust-store strings appear in the rendered output: bcdedit,
testsigning, certutil, httpdisk, and test-signed are all
explicitly forbidden as a hard guarantee.
WinPE bootstrap (startnet.cmd) picks up the Bootimus v0.1.58 lessons:
explicit `net start Workstation` before `net use` to avoid the SMB
client lazy-init race, and surfaces errors instead of blind retries.
## Docs
architecture.md gains a "Phase 5" section explaining the host-bindings
+ metrics + theming + Windows-test work, plus a refreshed "deferred
to Phase 6" list (real-hardware integration, autounattend library,
distro profile manifest, WoL trigger, syslog receiver, IPv6).
README updates the status line, the "what it does" list, and adds
the new Hosts/Terminal tab names.
302 lines
13 KiB
Markdown
302 lines
13 KiB
Markdown
# PXEForge
|
||
|
||
Container-native PXE boot server. A Rust reimplementation of
|
||
[iVentoy (ventoy/PXE)](https://github.com/ventoy/PXE), designed from scratch
|
||
for Docker/OCI and OpenShift. Upload `.iso` files via the web UI; network
|
||
clients PXE-boot them.
|
||
|
||
> **Status:** v0.2.0 / pre-beta. Phases 1–5 complete: full PXE stack,
|
||
> Gated Deployment queue, NFS-share ISO sources, live tracing log + an
|
||
> operator terminal, per-MAC host bindings (Tinkerbell-style),
|
||
> Prometheus `/metrics`, light/dark theme toggle, animated anvil
|
||
> imaging-progress widget. **66 tests passing**, clippy clean. Ready
|
||
> for real-hardware validation.
|
||
|
||
## Design non-negotiables
|
||
|
||
1. **Fully offline / air-gap deployable.** Zero CDN assets. Zero external
|
||
HTTP calls from the server, the browser, or the generated iPXE scripts.
|
||
Build the container once, run forever disconnected.
|
||
2. **iPXE is a backend implementation detail.** No `.ipxe` upload path, no
|
||
manual script editing, no iPXE terminology in the UI. Every knob in the
|
||
web UI maps to a specific script-generation behavior inside the binary.
|
||
3. **The client trust store is off-limits.** No test-signed drivers, no
|
||
`bcdedit /set testsigning on`, no certificates injected into WinPE or
|
||
the target OS.
|
||
|
||
## What it does
|
||
|
||
1. **DHCP proxy** (RFC 4578). Coexists with your existing DHCP server —
|
||
never assigns IPs. Listens on UDP 67 + UDP 4011.
|
||
2. **TFTP server** (RFC 1350 + RFC 2347/2348/2349/7440 option negotiation)
|
||
that serves architecture-specific iPXE binaries to firmware PXE ROMs.
|
||
3. **HTTP server** that serves the web UI, the generated iPXE boot scripts,
|
||
raw ISOs (with Range), and files inside ISOs without prior extraction.
|
||
4. **ISO introspection**: auto-detects the distro family and generates the
|
||
appropriate kernel+initrd or wimboot chain. No manual config.
|
||
5. **Hierarchical PXE menu** mirroring the Phase 2 spec:
|
||
```
|
||
Default > Boot from Local HDD
|
||
Installers > Linux Installers / Windows Installers
|
||
Tools > Utilities / PXEForge Shell / Network Card Info
|
||
Gated Deployment
|
||
```
|
||
6. **Gated Deployment queue** — the "horse race gate" flow. A client that
|
||
selects *Gated Deployment* gets a numbered position and waits. The
|
||
operator picks an ISO in the web UI and fires it to every waiting
|
||
client simultaneously.
|
||
7. **Web UI** (Netbox-style): sidebar nav (Dashboard / Network / Forge
|
||
Gate / Storage / Hosts / Terminal / About), light + dark themes
|
||
(toggle top-right or press `T`), animated anvil "forge progress"
|
||
widget when devices are imaging. All assets served from the binary —
|
||
no external requests.
|
||
8. **Per-MAC host bindings.** Pin a MAC to a boot target and the client
|
||
skips the menu, chains straight through. Inspired by Tinkerbell's
|
||
`smee` MAC-prepended URL pattern.
|
||
9. **Prometheus metrics** at `/metrics` — DHCP replies by arch, TFTP
|
||
transfer counts and bytes, HTTP request counts by route, gate /
|
||
imaging gauges, uptime, build info. Plain text exposition format,
|
||
no external metrics framework dependency.
|
||
8. **Settings API** lets you change the default boot-menu timeout (default
|
||
600s), the timeout action (stay / Local HDD / Gated Deployment), and
|
||
feature toggles like Windows ISO support. The iPXE scripts regenerate
|
||
on every request using current settings.
|
||
|
||
### Architectures supported on day one
|
||
|
||
| DHCP option 93 | Architecture | Binary served |
|
||
|----------------|-----------------|-------------------------|
|
||
| `0x0000` | Legacy x86 BIOS | `undionly.kpxe` |
|
||
| `0x0006` | IA32 UEFI | `snponly-i386.efi` |
|
||
| `0x0007`/`0x0009` | x86_64 UEFI | `snponly.efi` |
|
||
| `0x000B` | ARM64 UEFI | `snponly-arm64.efi` |
|
||
|
||
UEFI firmware that sends `HTTPClient` in option 60 is handled too — we
|
||
skip TFTP and respond with an HTTP URL.
|
||
|
||
## Quick start — MVP container (recommended)
|
||
|
||
```bash
|
||
# 1. Pull bundled iPXE binaries (~2 MB, one-time).
|
||
./scripts/fetch-ipxe.sh
|
||
|
||
# 2. Build the container image (~3 min first time).
|
||
docker buildx build -f deploy/docker/Dockerfile -t pxeforge:0.1.0 --load .
|
||
|
||
# 3. Run it on the box plugged into your PXE network. Set PUBLIC_IP to
|
||
# this host's LAN address so advertised iPXE URLs are reachable.
|
||
docker run -d --name pxeforge \
|
||
--network host \
|
||
-e PXEFORGE_PUBLIC_IP=10.0.0.5 \
|
||
-e PXEFORGE_DHCP_MODE=proxy \
|
||
-v $PWD/data/isos:/var/lib/pxeforge/isos \
|
||
-v $PWD/data/work:/var/lib/pxeforge/work \
|
||
pxeforge:0.1.0
|
||
|
||
# 4. Open the UI and drop an ISO in.
|
||
open http://10.0.0.5
|
||
```
|
||
|
||
Host networking is required in proxy mode so the container sees DHCPDISCOVER
|
||
broadcasts from the PXE VLAN. On macOS/Windows hosts Docker runs in a Linux
|
||
VM, so "host" means the VM — use `pxeforge-dev` in `docker-compose.yml` for
|
||
API-only testing on a laptop.
|
||
|
||
### Quick start — docker compose
|
||
|
||
```bash
|
||
# MVP / API testing on a laptop (no DHCP, high ports):
|
||
PXEFORGE_PUBLIC_IP=127.0.0.1 docker compose up pxeforge-dev
|
||
# Real PXE deployment on a Linux host (host network, DHCP proxy on):
|
||
PXEFORGE_PUBLIC_IP=10.0.0.5 docker compose up pxeforge
|
||
```
|
||
|
||
### Multi-arch build + push
|
||
|
||
For deploying to x86_64 servers, build both arches in one manifest:
|
||
|
||
```bash
|
||
# One-time: bootstrap a multi-arch builder.
|
||
docker buildx create --name pxeforge-multi --driver docker-container --use
|
||
|
||
# Build + push both linux/amd64 and linux/arm64 under one tag.
|
||
docker buildx build --builder pxeforge-multi \
|
||
--platform linux/amd64,linux/arm64 \
|
||
-t ghcr.io/YOUR-ORG/pxeforge:0.1.0 \
|
||
--push \
|
||
-f deploy/docker/Dockerfile .
|
||
```
|
||
|
||
On an Apple Silicon host, the amd64 stage runs under QEMU emulation (~10-15 min for a cold cache). On a Linux x86_64 host, both arches build natively at normal speed. CI runners on GitHub Actions with `docker/build-push-action@v5` handle this cleanly.
|
||
|
||
### Build from source (no container)
|
||
|
||
```bash
|
||
./scripts/fetch-ipxe.sh
|
||
cargo run --release # needs NET_BIND_SERVICE or root for :80/:69
|
||
```
|
||
|
||
### Container health probes
|
||
|
||
| Endpoint | Purpose |
|
||
|-------------|---------------------------------------------------------------|
|
||
| `/healthz` | Liveness — HTTP stack alive. Always 200. |
|
||
| `/readyz` | Readiness — 200 only if iPXE binaries bundled + ISO dir OK. |
|
||
| `/api/status` | Full JSON status: versions, assets, counts, live settings, SMB state. |
|
||
|
||
### Pre-seeding ISOs from a directory
|
||
|
||
For CI, pre-baked homelab deployments, or a fresh PVC, the binary has a
|
||
`seed` subcommand that imports every `*.iso` from a host path through the
|
||
same pipeline the web UI uses (introspection + boot-entry generation):
|
||
|
||
```bash
|
||
docker run --rm \
|
||
-v /my/iso-library:/seed:ro \
|
||
-v pxeforge-data:/var/lib/pxeforge/isos \
|
||
-e PXEFORGE_PUBLIC_IP=10.0.0.5 \
|
||
pxeforge:0.1.0 seed --from /seed
|
||
|
||
# Dry run first to see what would be imported:
|
||
docker run --rm -v /my/iso-library:/seed:ro pxeforge:0.1.0 seed --from /seed --dry-run
|
||
```
|
||
|
||
### Environment overrides
|
||
|
||
| Var | Default | Meaning |
|
||
|------------------------|-----------------------------|----------------------------------------|
|
||
| `PXEFORGE_HTTP_PORT` | `80` | Web UI + boot script HTTP port |
|
||
| `PXEFORGE_TFTP_PORT` | `69` | TFTP port |
|
||
| `PXEFORGE_DHCP_PORT` | `67` | DHCP server-side port |
|
||
| `PXEFORGE_DHCP_MODE` | `proxy` | `proxy` or `disabled` |
|
||
| `PXEFORGE_PUBLIC_IP` | auto-detect | Advertised IP for clients. Startup **fails** if unset and auto-detect returns loopback. |
|
||
| `PXEFORGE_ISO_DIR` | `/var/lib/pxeforge/isos` | Where uploaded ISOs live |
|
||
| `PXEFORGE_WORK_DIR` | `/var/lib/pxeforge/work` | Scratch + runtime settings |
|
||
| `PXEFORGE_LOG` | `info,pxeforge=debug` | `tracing` filter |
|
||
|
||
## What the boot menu looks like on a real client
|
||
|
||
```
|
||
PXEForge - network boot menu
|
||
|
||
------------------------- Default -------------------------
|
||
Boot from Local HDD
|
||
----------------------- Installers -----------------------
|
||
Linux Installers >
|
||
Windows Installers > (only if enabled in Settings)
|
||
-------------------------- Tools --------------------------
|
||
Tools > Utilities / Shell /
|
||
NIC Info / Reboot /
|
||
Exit and continue BIOS
|
||
---------------------- Gated Deployment ------------------
|
||
Gated Deployment (join queue)
|
||
```
|
||
|
||
Linux/Windows submenus show file sizes iVentoy-style:
|
||
|
||
```
|
||
PXEForge - Linux Installers
|
||
|
||
[ 4376 MB] CentOS-7-x86_64-DVD-1810
|
||
[ 2002 MB] Fedora-Workstation-Live-x86_64-38-1.6
|
||
[ 4699 MB] ubuntu-22.04.2-desktop-amd64
|
||
< Back to main menu
|
||
```
|
||
|
||
iPXE never appears in the UI — the whole hierarchy above is generated from
|
||
ISOs you upload via drag-and-drop in the web UI plus toggles in Settings.
|
||
|
||
## OpenShift
|
||
|
||
```bash
|
||
oc apply -f deploy/openshift/
|
||
oc -n pxeforge get all
|
||
oc -n pxeforge get route pxeforge -o jsonpath='{.spec.host}'
|
||
```
|
||
|
||
### Why a custom SCC?
|
||
|
||
The default `restricted-v2` blocks `hostNetwork` and all capabilities. PXE
|
||
cannot work without host network (CNI overlays don't deliver L2 broadcast
|
||
into pod netns), and we need `NET_BIND_SERVICE` to bind <1024. The custom
|
||
`pxeforge-scc` grants exactly those two and nothing else. No raw sockets,
|
||
no privileged mode — proxy-mode DHCP sidesteps the usual requirements.
|
||
|
||
### What's on host ports
|
||
|
||
| Port | Proto | Purpose |
|
||
|----------|-------|---------------------------------|
|
||
| 67 | UDP | DHCP server (proxy replies) |
|
||
| 69 | UDP | TFTP |
|
||
| 4011 | UDP | PXE Boot Server discovery |
|
||
| 80 | TCP | Web UI + HTTP boot assets |
|
||
|
||
The OpenShift Route only covers 80/TCP. Clients on the PXE network talk to
|
||
the node's host IP directly for UDP.
|
||
|
||
## Windows support
|
||
|
||
Enabled by toggling **Windows ISO support** under Settings. The flow:
|
||
|
||
1. Upload a stock Microsoft Windows install ISO (vanilla, no pre-processing).
|
||
2. On upload, PXEForge extracts the ISO and uses `wimlib-imagex` to rewrite
|
||
image index 2 (WinPE) of `sources/boot.wim`. It injects exactly two
|
||
plain-text files:
|
||
- `Windows/System32/winpeshl.ini` — tells WinPE to run `startnet.cmd`.
|
||
- `Windows/System32/startnet.cmd` — runs `wpeinit`, waits for the SMB
|
||
host to be reachable, `net use Z: \\<server>\<share> /user:guest`,
|
||
then `Z:\setup.exe`.
|
||
3. The container's Samba `smbd` serves the extracted install tree on :445.
|
||
4. The client gets chainloaded into wimboot → patched WinPE → Windows Setup
|
||
running off the SMB share. **Every binary the client executes is stock
|
||
Microsoft-signed.**
|
||
|
||
### What we never do
|
||
|
||
- Ship drivers — signed, test-signed, or otherwise — that load on the client.
|
||
- Install certificates into the target's trust store or WinPE boot policy.
|
||
- Recommend `bcdedit /set testsigning on` or any equivalent signing-policy
|
||
weakening.
|
||
|
||
### Credit & limitations
|
||
|
||
The SMB-based approach is adapted from [Bootimus](https://github.com/garybowers/bootimus)
|
||
(Apache-2.0). Re-implemented in Rust; no code was copied verbatim. Known
|
||
operational constraints inherited from the design:
|
||
|
||
- **Port 445 must be directly reachable from PXE clients.** `net use`
|
||
ignores alternate ports. In OpenShift this means `hostPort: 445` on the
|
||
deployment; on a host that already runs SMB it will collide.
|
||
- Windows 10/11 client SKUs are the tested target. Server SKUs untested.
|
||
- Hardware with NICs/storage controllers missing from WinPE's bundled
|
||
drivers will need a driver-pack injection step (not yet implemented).
|
||
|
||
## Gated Deployment
|
||
|
||
The "horse race gate" flow, end to end:
|
||
|
||
1. A client boots and picks **Gated Deployment** in the PXE menu (or falls
|
||
through on timeout with the default `timeout_action`).
|
||
2. The client joins the queue, gets a numbered gate position, and enters a
|
||
long-poll loop (25s per request, auto-renewed).
|
||
3. In the web UI's **Gated Deployment** tab, the operator sees each waiting
|
||
client with its MAC, IP, arch, and position.
|
||
4. The operator selects an image and clicks **Launch for all waiting**.
|
||
The server broadcasts the assignment to every gated client via a
|
||
`tokio::sync::Notify`; each client's next poll returns the boot script
|
||
for the chosen image.
|
||
5. Every client chains the same image at effectively the same moment — the
|
||
gate opens and the horses run together.
|
||
|
||
No user-facing iPXE anywhere in this flow. The client only ever runs
|
||
scripts we generate; the operator only interacts with the web UI.
|
||
|
||
## Architecture
|
||
|
||
See [`docs/architecture.md`](docs/architecture.md) for the protocol stack,
|
||
crate layout, and the full decision log.
|
||
|
||
## Licence
|
||
|
||
MIT OR Apache-2.0.
|