Miles Ward
9c6903351f
Operators can now lock individual ISOs behind a password set in the
WebUI. Picking a locked image at the PXE menu prompts the operator on
the client console; the boot script is only released after a correct
match. The plaintext never leaves the request — server stores bcrypt
hashes, scripts never echo the candidate.
## Backend
- New optional `password_hash: Option<String>` on `IsoMeta`. Skipped
during serialize when None, so existing meta.json files don't grow
a noisy `null` field.
- `IsoStore::set_password(id, Some("pw"))` hashes via bcrypt
`DEFAULT_COST` (10 — fast enough for an interactive iPXE prompt,
expensive enough to be hostile to brute force on a leaked
meta.json). `set_password(id, None)` and `set_password(id, Some(""))`
both clear.
- `IsoStore::verify_password` returns Ok(true) when no password is
set, so the gate stays open for the common case.
- `IsoMeta::is_password_protected()` predicate the HTTP layer + UI
share.
- NFS-sourced ISOs persist their hash in memory only — the share is
the source of truth for those, and it doesn't carry hash sidecars.
## HTTP API
- `PUT /api/isos/:id/password` body `{ "password": "..." }` to set,
`{ "password": null }` (or empty string) to clear.
- `DELETE /api/isos/:id/password` for the explicit clear.
- Both 204 on success, 404 for unknown ids.
- `/boot/<entry>.ipxe` now intercepts:
- no `?token=` -> render password-prompt script
- `?token=<wrong>` -> render auth-fail script (sleeps 2s, chains
back to the entry which re-prompts)
- `?token=<correct>` -> render the real boot script
- ISO without password ignores token entirely (per-MAC bookmarks
still work without changes).
## iPXE prompt
`render_password_prompt`:
- `set password ` then `read --secret password` — accepts input
without echoing.
- Empty input chains back to the main menu (lets the operator back
out of a misclick).
- Submit chains `?token=${password:uristring}`. The `:uristring`
modifier URL-encodes the value, so passwords with `&`, `?`, `=`,
spaces, etc. survive transport.
`render_password_failed`:
- Single line saying so + 2s sleep, then re-chains the entry.
- Server-side WARN log records the entry id only, never the
candidate value (verified in smoke test).
## UI
Storage tab's image table grows an `Auth` column showing
`protected` / `open`, plus a 🔒 next to the filename when locked.
Per-row "Set password" / "Password ✎" button toggles an inline
editor in the next table row containing:
- a "Password protect this image" checkbox
- a `<input type=password autocomplete=new-password>` (hidden when
the checkbox is off)
- a Save button
Save calls PUT or DELETE on `/api/isos/:id/password` based on the
checkbox state and clears the input field before re-rendering, so
the plaintext doesn't sit in the DOM longer than needed.
## Menu indicator
`render_family_menu` adds a `*` prefix immediately before the size
box on protected entries — ASCII only because some firmware menu
consoles mangle non-ASCII glyphs. Looks like:
item --key 1 win11_test-winpe *[ 5234 MB] Windows 11 Test ISO
## Tests
74 passing across the workspace (was 66 in v0.3.0):
- 3 new store unit tests (bcrypt round-trip, unknown-id error,
meta.json persistence across restart)
- 2 new ipxe_script unit tests (prompt/auth-fail invariants:
read --secret, uristring, no candidate echo)
- 3 new HTTP integration tests (full gate flow upload-set-prompt-
fail-success-clear, null/empty bodies, 404 on unknown id)
cargo clippy --workspace --all-targets clean.
Local smoke verified upload + lock + prompt + auth-fail + correct +
menu indicator + log scrub on a real release binary.
## Operational notes
- HTTP, not HTTPS — token rides in the query string. Acceptable on
a trusted boot VLAN; do NOT expose OpenPXE to untrusted networks
with this feature relied on for security. Reverse-proxy in front
of OpenPXE will end up with the token in access logs.
- bcrypt cost is `DEFAULT_COST` (10). One verify takes ~50ms on
modern x86, which is the worst-case latency added to a correct
boot. Tunable via the bcrypt crate if needed.
OpenPXE
Container-native PXE boot server. A Rust reimplementation of
iVentoy (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, Queued 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
- 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.
- iPXE is a backend implementation detail. No
.ipxeupload 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. - 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
- DHCP proxy (RFC 4578). Coexists with your existing DHCP server — never assigns IPs. Listens on UDP 67 + UDP 4011.
- TFTP server (RFC 1350 + RFC 2347/2348/2349/7440 option negotiation) that serves architecture-specific iPXE binaries to firmware PXE ROMs.
- HTTP server that serves the web UI, the generated iPXE boot scripts, raw ISOs (with Range), and files inside ISOs without prior extraction.
- ISO introspection: auto-detects the distro family and generates the appropriate kernel+initrd or wimboot chain. No manual config.
- Hierarchical PXE menu mirroring the Phase 2 spec:
Default > Boot from Local HDD Installers > Linux Installers / Windows Installers Tools > Utilities / OpenPXE Shell / Network Card Info Queued Deployment - Queued Deployment queue — the "horse race" launch flow. A client that selects Queued Deployment gets a numbered position and waits. The operator picks an ISO in the web UI and fires it to every waiting client simultaneously.
- 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. - Per-MAC host bindings. Pin a MAC to a boot target and the client
skips the menu, chains straight through. Inspired by Tinkerbell's
smeeMAC-prepended URL pattern. - Prometheus metrics at
/metrics— DHCP replies by arch, TFTP transfer counts and bytes, HTTP request counts by route, queue / imaging gauges, uptime, build info. Plain text exposition format, no external metrics framework dependency. - Settings API lets you change the default boot-menu timeout (default 600s), the timeout action (stay / Local HDD / Queued 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)
# 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 openpxe: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 openpxe \
--network host \
-e OPENPXE_PUBLIC_IP=10.0.0.5 \
-e OPENPXE_DHCP_MODE=proxy \
-v $PWD/data/isos:/var/lib/openpxe/isos \
-v $PWD/data/work:/var/lib/openpxe/work \
openpxe: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 openpxe-dev in docker-compose.yml for
API-only testing on a laptop.
Quick start — docker compose
# MVP / API testing on a laptop (no DHCP, high ports):
OPENPXE_PUBLIC_IP=127.0.0.1 docker compose up openpxe-dev
# Real PXE deployment on a Linux host (host network, DHCP proxy on):
OPENPXE_PUBLIC_IP=10.0.0.5 docker compose up openpxe
Multi-arch build + push
For deploying to x86_64 servers, build both arches in one manifest:
# One-time: bootstrap a multi-arch builder.
docker buildx create --name openpxe-multi --driver docker-container --use
# Build + push both linux/amd64 and linux/arm64 under one tag.
docker buildx build --builder openpxe-multi \
--platform linux/amd64,linux/arm64 \
-t ghcr.io/YOUR-ORG/openpxe: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)
./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):
docker run --rm \
-v /my/iso-library:/seed:ro \
-v openpxe-data:/var/lib/openpxe/isos \
-e OPENPXE_PUBLIC_IP=10.0.0.5 \
openpxe:0.1.0 seed --from /seed
# Dry run first to see what would be imported:
docker run --rm -v /my/iso-library:/seed:ro openpxe:0.1.0 seed --from /seed --dry-run
Environment overrides
| Var | Default | Meaning |
|---|---|---|
OPENPXE_HTTP_PORT |
80 |
Web UI + boot script HTTP port |
OPENPXE_TFTP_PORT |
69 |
TFTP port |
OPENPXE_DHCP_PORT |
67 |
DHCP server-side port |
OPENPXE_DHCP_MODE |
proxy |
proxy or disabled |
OPENPXE_PUBLIC_IP |
auto-detect | Advertised IP for clients. Startup fails if unset and auto-detect returns loopback. |
OPENPXE_ISO_DIR |
/var/lib/openpxe/isos |
Where uploaded ISOs live |
OPENPXE_WORK_DIR |
/var/lib/openpxe/work |
Scratch + runtime settings |
OPENPXE_LOG |
info,openpxe=debug |
tracing filter |
What the boot menu looks like on a real client
OpenPXE - 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
---------------------- Queued Deployment ------------------
Queued Deployment (join queue)
Linux/Windows submenus show file sizes iVentoy-style:
OpenPXE - 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
oc apply -f deploy/openshift/
oc -n openpxe get all
oc -n openpxe get route openpxe -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
openpxe-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:
- Upload a stock Microsoft Windows install ISO (vanilla, no pre-processing).
- On upload, OpenPXE extracts the ISO and uses
wimlib-imagexto rewrite image index 2 (WinPE) ofsources/boot.wim. It injects exactly two plain-text files:Windows/System32/winpeshl.ini— tells WinPE to runstartnet.cmd.Windows/System32/startnet.cmd— runswpeinit, waits for the SMB host to be reachable,net use Z: \\<server>\<share> /user:guest, thenZ:\setup.exe.
- The container's Samba
smbdserves the extracted install tree on :445. - 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 onor any equivalent signing-policy weakening.
Credit & limitations
The SMB-based approach is adapted from 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 useignores alternate ports. In OpenShift this meanshostPort: 445on 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).
Queued Deployment
The "horse race" launch flow, end to end:
- A client boots and picks Queued Deployment in the PXE menu (or falls
through on timeout with the default
timeout_action). - The client joins the queue, gets a numbered queue position, and enters a long-poll loop (25s per request, auto-renewed).
- In the web UI's Queued Deployment tab, the operator sees each waiting client with its MAC, IP, arch, and position.
- The operator selects an image and clicks Launch for all waiting.
The server broadcasts the assignment to every queued client via a
tokio::sync::Notify; each client's next poll returns the boot script for the chosen image. - Every client chains the same image at effectively the same moment — the queue releases 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 for the protocol stack,
crate layout, and the full decision log.
Licence
MIT OR Apache-2.0.