Name update
This commit is contained in:
Miles Ward
+9
-9
@@ -1,6 +1,6 @@
|
||||
# Phase 6 — recommendations
|
||||
|
||||
The v0.2.0 cut leaves PXEForge in a state where the entire protocol stack
|
||||
The v0.2.0 cut leaves OpenPXE 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
|
||||
@@ -66,7 +66,7 @@ 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
|
||||
then click "Wake & Image" to send the magic packet and let OpenPXE
|
||||
do the rest. Implementation is small (`udp/9` broadcast, magic packet
|
||||
construction) but it makes the bound-host workflow feel instant.
|
||||
|
||||
@@ -113,10 +113,10 @@ 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.
|
||||
The current design assumes one OpenPXE per broadcast domain. Two
|
||||
proxies on the same L2 will race; the deployment queue is in-memory, etc.
|
||||
For HA we'd need to:
|
||||
- Externalize the gate queue (Redis, etcd) or lean into "the menu is
|
||||
- Externalize the deployment 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;
|
||||
@@ -128,7 +128,7 @@ 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
|
||||
TFTP path layout that OpenPXE 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
|
||||
@@ -137,7 +137,7 @@ a spec; the work is small once we have a Pi to test on.
|
||||
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
|
||||
it because they integrate with k8s CRDs. OpenPXE'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
|
||||
@@ -148,8 +148,8 @@ a spec; the work is small once we have a Pi to test on.
|
||||
|
||||
- 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.
|
||||
- A `openpxe bench` subcommand that runs a 10-second internal load
|
||||
test (synthetic queue 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
|
||||
|
||||
+29
-29
@@ -1,4 +1,4 @@
|
||||
# PXEForge architecture
|
||||
# OpenPXE architecture
|
||||
|
||||
## Protocol stack
|
||||
|
||||
@@ -8,7 +8,7 @@ Client firmware PXE ROM
|
||||
│ DHCPDISCOVER (UDP/67 broadcast, option 60 "PXEClient", option 93 arch)
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ PXEForge │
|
||||
│ OpenPXE │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
|
||||
│ │ DHCP proxy │ │ TFTP server │ │ HTTP server (axum) │ │
|
||||
@@ -33,7 +33,7 @@ Client runs iPXE
|
||||
│
|
||||
│ DHCPDISCOVER with option 77 "iPXE"
|
||||
▼
|
||||
PXEForge sees user-class "iPXE" → replies with HTTP URL: /boot.ipxe
|
||||
OpenPXE sees user-class "iPXE" → replies with HTTP URL: /boot.ipxe
|
||||
│
|
||||
│ HTTP GET /boot.ipxe (iPXE menu, auto-generated from IsoStore)
|
||||
▼
|
||||
@@ -48,14 +48,14 @@ Kernel boots with distro-specific args pointing back at /iso/<id>.iso
|
||||
|
||||
| Crate | Responsibility |
|
||||
|---------------------|-------------------------------------------------------------------|
|
||||
| `pxeforge-core` | Shared types: `Config`, `ClientArch`, `FirmwareClass`, `ClientRegistry` |
|
||||
| `pxeforge-ipxe-assets` | Embeds bundled iPXE binaries via `rust-embed` |
|
||||
| `pxeforge-iso-store` | On-disk ISO store, introspection, boot-entry generation |
|
||||
| `pxeforge-dhcp-proxy` | UDP listener + `dhcproto` reply builder; pure `decide()` unit-testable |
|
||||
| `pxeforge-tftp` | RFC 1350 + OACK (blksize / tsize / windowsize). Serves only embedded assets — no filesystem |
|
||||
| `pxeforge-http-api` | `axum` router: web UI, API, iPXE script generation, ISO streaming |
|
||||
| `pxeforge-webui` | Single `index.html` served as static string |
|
||||
| `pxeforge` (bin) | Wires everything together, runs the three servers concurrently |
|
||||
| `openpxe-core` | Shared types: `Config`, `ClientArch`, `FirmwareClass`, `ClientRegistry` |
|
||||
| `openpxe-ipxe-assets` | Embeds bundled iPXE binaries via `rust-embed` |
|
||||
| `openpxe-iso-store` | On-disk ISO store, introspection, boot-entry generation |
|
||||
| `openpxe-dhcp-proxy` | UDP listener + `dhcproto` reply builder; pure `decide()` unit-testable |
|
||||
| `openpxe-tftp` | RFC 1350 + OACK (blksize / tsize / windowsize). Serves only embedded assets — no filesystem |
|
||||
| `openpxe-http-api` | `axum` router: web UI, API, iPXE script generation, ISO streaming |
|
||||
| `openpxe-webui` | Single `index.html` served as static string |
|
||||
| `openpxe` (bin) | Wires everything together, runs the three servers concurrently |
|
||||
|
||||
## Key decisions and why
|
||||
|
||||
@@ -75,11 +75,11 @@ so plain `SOCK_DGRAM` is enough.
|
||||
|
||||
1. Firmware PXE ROM sends DHCPDISCOVER with option 60 = `PXEClient`,
|
||||
option 93 = arch.
|
||||
2. PXEForge replies with TFTP server + arch-specific iPXE binary
|
||||
2. OpenPXE replies with TFTP server + arch-specific iPXE binary
|
||||
(`undionly.kpxe` for Legacy BIOS, `snponly.efi` for x86_64 UEFI, etc.).
|
||||
3. Client TFTPs the iPXE binary and runs it.
|
||||
4. iPXE does its own DHCP, setting option 77 (user-class) to `iPXE`.
|
||||
5. PXEForge detects the user-class and this time replies with an HTTP URL
|
||||
5. OpenPXE detects the user-class and this time replies with an HTTP URL
|
||||
in option 67 pointing at `/boot.ipxe`.
|
||||
6. iPXE fetches and executes that script, which chains the selected OS.
|
||||
|
||||
@@ -105,7 +105,7 @@ Whatever we do for Windows, we never:
|
||||
- instruct users to enable `bcdedit /set testsigning on`
|
||||
- install any certificate into the target's root/trust store
|
||||
|
||||
iVentoy's `httpdisk.sys` approach broke this rule. PXEForge doesn't.
|
||||
iVentoy's `httpdisk.sys` approach broke this rule. OpenPXE doesn't.
|
||||
|
||||
### Linux ISO boot uses kernel+initrd extraction, not sanboot
|
||||
|
||||
@@ -157,13 +157,13 @@ release:
|
||||
root-owned" problem that breaks ISO upload on standard Docker hosts.
|
||||
- `/healthz` and `/readyz` split from `/api/status` — readyz fails if no
|
||||
iPXE binaries are bundled, giving K8s probes a real signal.
|
||||
- Startup aborts with a clear error if `PXEFORGE_PUBLIC_IP` can't be
|
||||
- Startup aborts with a clear error if `OPENPXE_PUBLIC_IP` can't be
|
||||
auto-detected (no more silent `127.0.0.1` advertisement).
|
||||
- `scripts/fetch-ipxe.sh` fails non-zero if zero binaries download; the
|
||||
Dockerfile uses arch-scoped paths (`x86_64-efi/snponly.efi` etc.).
|
||||
|
||||
**Windows boot plumbing** (new):
|
||||
- `pxeforge-iso-store::smb::SmbManager` supervises `smbd` on the Windows
|
||||
- `openpxe-iso-store::smb::SmbManager` supervises `smbd` on the Windows
|
||||
toggle: `start` → spawn + write `smb.conf`; `reconcile` → SIGHUP on
|
||||
share changes; `stop` → SIGTERM. `SmbState` surfaced to the UI for
|
||||
visibility.
|
||||
@@ -177,32 +177,32 @@ release:
|
||||
- ISO sizes in menu labels (`[ 4376 MB]`), iVentoy format.
|
||||
- `Reboot Computer` + `Exit and continue BIOS boot` in Tools menu.
|
||||
- Number-key hotkeys (1..9) on boot entries, letter hotkeys on tools.
|
||||
- Clients tab cross-joins the gate queue so an operator sees "at gate #2"
|
||||
- Clients tab cross-joins the deployment queue so an operator sees "in queue #2"
|
||||
or "assigned: ubuntu-linux" status inline.
|
||||
|
||||
**Developer ergonomics** (new):
|
||||
- `pxeforge seed --from <path>` CLI to import ISOs from a directory.
|
||||
- `openpxe seed --from <path>` CLI to import ISOs from a directory.
|
||||
Same pipeline as web upload (slug, sha256, introspection, boot-entry).
|
||||
- `docker-compose.yml` with `pxeforge` (host network, real PXE) and
|
||||
`pxeforge-dev` (published ports, DHCP disabled, for API testing).
|
||||
- `docker-compose.yml` with `openpxe` (host network, real PXE) and
|
||||
`openpxe-dev` (published ports, DHCP disabled, for API testing).
|
||||
|
||||
**API cleanliness**:
|
||||
- All timestamps now serialized as RFC 3339 strings (the `time` crate's
|
||||
default 9-tuple broke browser `Date` parsing).
|
||||
- Gate poll retains assignment until the operator releases it; if the
|
||||
- Queue poll retains assignment until the operator releases it; if the
|
||||
client's chain fails, it reuses the assignment instead of falling back
|
||||
to the menu.
|
||||
|
||||
## Phase 4 — UI restructure + remote storage
|
||||
|
||||
The web UI was rebuilt around six tabs (Dashboard / Network / Forge Gate /
|
||||
The web UI was rebuilt around six tabs (Dashboard / Network / Queue /
|
||||
Storage / Terminal / About) inspired by the iVentoy layout the user
|
||||
attached and Netbox Labs's compact-card pattern. The old hierarchical
|
||||
"Monitoring / Content / Configuration" sidebar grouping is gone — every
|
||||
tab is one click from the brand bar.
|
||||
|
||||
**NFS share manager** (`crates/iso-store/src/nfs.rs`):
|
||||
- Operators add a remote share via Storage → NFS shares; PXEForge mounts
|
||||
- Operators add a remote share via Storage → NFS shares; OpenPXE mounts
|
||||
it under `<work_dir>/nfs/<id>/` and walks it for `*.iso` files.
|
||||
- Each ISO found is registered with `IsoStore::register_external` using
|
||||
a new `IsoSource::Nfs { mount_id, relative_path }` variant. The store
|
||||
@@ -227,7 +227,7 @@ tab is one click from the brand bar.
|
||||
followed by live updates. Slow clients see a `lagged` event rather
|
||||
than dropping the stream.
|
||||
- `/api/terminal` accepts a single command line and dispatches to a
|
||||
whitelist (`status`, `isos`, `clients`, `gate {list,assign,release}`,
|
||||
whitelist (`status`, `isos`, `clients`, `queue {list,assign,release}`,
|
||||
`nfs {list,mount,unmount,scan}`, `smb {status,start,stop,reload}`,
|
||||
`log {clear,tail}`). Output is mirrored onto the LogBus so reading the
|
||||
live tail tells the same story as scrolling the terminal pane.
|
||||
@@ -240,7 +240,7 @@ tab is one click from the brand bar.
|
||||
read-only by design — silently changing the public IP on a hot UI
|
||||
would break PXE for every client mid-boot.
|
||||
- The only writable network field is `dns_server`, an optional
|
||||
informational hint stored in `Settings`. PXEForge does not run a DNS
|
||||
informational hint stored in `Settings`. OpenPXE does not run a DNS
|
||||
server; the field exists so operators don't have to dig out the
|
||||
upstream DNS at 3 AM.
|
||||
|
||||
@@ -252,7 +252,7 @@ tab is one click from the brand bar.
|
||||
warning.
|
||||
- Dashboard surfaces a "Images that won't boot" panel reusing the same
|
||||
predicate, so the operator sees the problem before they pick the ISO
|
||||
in the gate.
|
||||
in the queue.
|
||||
- Streaming uploads are already in place via axum multipart; the v0.1.62
|
||||
fix to "502 on big upload" doesn't apply.
|
||||
|
||||
@@ -260,7 +260,7 @@ tab is one click from the brand bar.
|
||||
|
||||
**Per-MAC host bindings** (`crates/core/src/host_bindings.rs`):
|
||||
- New `HostBindings` registry maps a MAC → preferred `BootEntry::id`
|
||||
(or one of the reserved menu shortcuts `_local`, `_gate`,
|
||||
(or one of the reserved menu shortcuts (`_local`, `_queue``,
|
||||
`_tools_menu`).
|
||||
- Persisted to `<work_dir>/hosts.json`. Like `SettingsStore`, in-memory
|
||||
is authoritative — disk corruption falls back to empty rather than
|
||||
@@ -278,7 +278,7 @@ tab is one click from the brand bar.
|
||||
- Counters: DHCP replies (per arch label), DHCP declined, TFTP
|
||||
transfers (per status label), TFTP bytes, HTTP requests (per route
|
||||
label).
|
||||
- Gauges: ISO count, client count, gate count, gate-imaging count,
|
||||
- Gauges: ISO count, client count, queue count, queue-imaging count,
|
||||
NFS active mounts, uptime, build info.
|
||||
- Exposed as plain Prometheus text at `/metrics`.
|
||||
|
||||
@@ -295,7 +295,7 @@ other idiom fixes.
|
||||
- New SVG logos: a refined anvil (`logo.svg`) and a SMIL-animated
|
||||
`anvil-forge.svg` (rising sparks + pulsing underglow). Pure SVG —
|
||||
no GIFs, no CSS keyframes for the sparks.
|
||||
- "Forge progress" widget on the Dashboard and Forge Gate: animated
|
||||
- "Forge progress" widget on the Dashboard and Queue: animated
|
||||
anvil paired with a `linear-gradient(warn → accent)` progress bar
|
||||
with a moving sheen. Goes idle (greyscale, no sheen) at zero
|
||||
imaging load.
|
||||
|
||||
Reference in New Issue
Block a user