commit 3517c678311460f0a14783d117115a030f37b4b1 Author: Miles Ward Date: Wed Apr 29 02:47:00 2026 -0400 Name update diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..e5fd138 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,38 @@ +# Keep the Docker build context small and fast. +# Anything the multi-stage Dockerfile actually needs is explicitly COPYed. + +# Cargo output (huge — ~1.5 GB locally). +target/ +**/target/ + +# Uploaded ISOs and per-iso scratch (runtime-only, huge). +data/ +/tmp/ + +# VCS + editor noise. +.git/ +.github/ +.idea/ +.vscode/ +.DS_Store +*.swp + +# Claude / local tooling state. +.claude/ +MEMORY.md + +# Local operator metadata. +/private/ + +# Never include iPXE binaries pre-fetched on the host — the `fetch` stage +# in the Dockerfile downloads them fresh inside the container so CI/prod +# builds are hermetic. +assets/ipxe/*.kpxe +assets/ipxe/*.efi +assets/ipxe/wimboot + +# Docs & meta. +docs/ +*.md +!README.md +LICENSE* diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..960fcc7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,13 @@ +/target +Cargo.lock +data/isos/*.iso +data/isos/*.partial +data/isos/*.meta.json +data/work/ +*.swp +.DS_Store + +# Per-user Claude Code state (project-shared settings.json is committed, +# settings.local.json is your personal allowlist history and shouldn't be). +.claude/settings.local.json +.claude/worktrees/ diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..b74258e --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,90 @@ +[workspace] +resolver = "2" +members = [ + "crates/core", + "crates/dhcp-proxy", + "crates/tftp", + "crates/http-api", + "crates/iso-store", + "crates/ipxe-assets", + "crates/webui", + "crates/pxeforge", +] + +[workspace.package] +version = "0.1.0" +edition = "2021" +rust-version = "1.80" +license = "MIT OR Apache-2.0" +repository = "https://github.com/casperadmin/PXEForge" +authors = ["PXEForge contributors"] + +[workspace.dependencies] +tokio = { version = "1.40", features = ["full"] } +tokio-util = { version = "0.7", features = ["io"] } +tokio-stream = { version = "0.1", features = ["sync"] } +futures = "0.3" +async-trait = "0.1" + +dhcproto = "0.12" +socket2 = { version = "0.5", features = ["all"] } +bytes = "1.7" +nom = "7.1" + +axum = { version = "0.7", features = ["macros", "multipart", "http2"] } +tower = "0.5" +tower-http = { version = "0.6", features = ["fs", "trace", "cors", "limit"] } +hyper = "1.4" +reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "stream"] } +mime = "0.3" +mime_guess = "2.0" + +serde = { version = "1.0", features = ["derive"] } +serde_json = "1.0" +toml = "0.8" + +tracing = "0.1" +tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] } + +anyhow = "1.0" +thiserror = "1.0" +clap = { version = "4.5", features = ["derive", "env"] } +uuid = { version = "1.10", features = ["v4", "serde"] } +time = { version = "0.3", features = ["serde", "serde-human-readable", "formatting", "macros"] } +sha2 = "0.10" +hex = "0.4" +once_cell = "1.19" +parking_lot = "0.12" +rust-embed = { version = "8.5", features = ["include-exclude"] } + +pxeforge-core = { path = "crates/core" } +pxeforge-dhcp-proxy = { path = "crates/dhcp-proxy" } +pxeforge-tftp = { path = "crates/tftp" } +pxeforge-http-api = { path = "crates/http-api" } +pxeforge-iso-store = { path = "crates/iso-store" } +pxeforge-ipxe-assets = { path = "crates/ipxe-assets" } +pxeforge-webui = { path = "crates/webui" } + +[workspace.lints.rust] +unsafe_code = "deny" +rust_2018_idioms = { level = "warn", priority = -1 } + +[workspace.lints.clippy] +pedantic = { level = "warn", priority = -1 } +module_name_repetitions = "allow" +missing_errors_doc = "allow" +missing_panics_doc = "allow" +must_use_candidate = "allow" +doc_markdown = "allow" +items_after_statements = "allow" +cast_possible_truncation = "allow" +cast_lossless = "allow" +cast_sign_loss = "allow" +similar_names = "allow" +too_many_lines = "allow" + +[profile.release] +lto = "thin" +codegen-units = 1 +strip = "symbols" +opt-level = 3 diff --git a/README.md b/README.md new file mode 100644 index 0000000..fdc2d02 --- /dev/null +++ b/README.md @@ -0,0 +1,290 @@ +# 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:** Phase 3 MVP. Container image builds and runs, gate flow +> validated end-to-end (two clients join queue → operator assigns in UI → +> both wake within 1 s with the correct boot script). 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 / Clients / Gated + Deployment / Images / Settings / About), top tabs, dark theme, teal + accents. All assets served from the binary — no external requests. +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: \\\ /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. diff --git a/assets/ipxe/.gitkeep b/assets/ipxe/.gitkeep new file mode 100644 index 0000000..4c4994d --- /dev/null +++ b/assets/ipxe/.gitkeep @@ -0,0 +1 @@ +# Placeholder — real iPXE binaries fetched by scripts/fetch-ipxe.sh or built from source. diff --git a/assets/ipxe/ipxe.efi b/assets/ipxe/ipxe.efi new file mode 100644 index 0000000..5064a71 Binary files /dev/null and b/assets/ipxe/ipxe.efi differ diff --git a/assets/ipxe/snponly-arm64.efi b/assets/ipxe/snponly-arm64.efi new file mode 100644 index 0000000..049bc2e Binary files /dev/null and b/assets/ipxe/snponly-arm64.efi differ diff --git a/assets/ipxe/snponly-i386.efi b/assets/ipxe/snponly-i386.efi new file mode 100644 index 0000000..9f86d57 Binary files /dev/null and b/assets/ipxe/snponly-i386.efi differ diff --git a/assets/ipxe/snponly.efi b/assets/ipxe/snponly.efi new file mode 100644 index 0000000..51e1cc5 Binary files /dev/null and b/assets/ipxe/snponly.efi differ diff --git a/assets/ipxe/undionly.kpxe b/assets/ipxe/undionly.kpxe new file mode 100644 index 0000000..5274cd5 Binary files /dev/null and b/assets/ipxe/undionly.kpxe differ diff --git a/assets/ipxe/wimboot b/assets/ipxe/wimboot new file mode 100644 index 0000000..3a5cb4a Binary files /dev/null and b/assets/ipxe/wimboot differ diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml new file mode 100644 index 0000000..d63f52d --- /dev/null +++ b/crates/core/Cargo.toml @@ -0,0 +1,26 @@ +[package] +name = "pxeforge-core" +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +description = "Shared types, config, and arch detection for PXEForge" + +[lints] +workspace = true + +[dependencies] +serde.workspace = true +serde_json.workspace = true +toml.workspace = true +thiserror.workspace = true +anyhow.workspace = true +tracing.workspace = true +tracing-subscriber.workspace = true +time.workspace = true +uuid.workspace = true +parking_lot.workspace = true +tokio = { workspace = true, features = ["sync", "rt", "macros", "time"] } + +[dev-dependencies] +tempfile = "3.12" diff --git a/crates/core/src/arch.rs b/crates/core/src/arch.rs new file mode 100644 index 0000000..2779741 --- /dev/null +++ b/crates/core/src/arch.rs @@ -0,0 +1,151 @@ +//! Client architecture detection from DHCP options. +//! +//! Primary source is DHCP option 93 (Client System Architecture, RFC 4578/5970). +//! Some firmwares report `0x0009` ("EFI BC") instead of `0x0007` — aliased here. +//! Secondary: option 60 vendor-class with `HTTPClient` signals native UEFI HTTP +//! boot, in which case we can skip TFTP and return an http:// URL directly. + +use serde::{Deserialize, Serialize}; + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)] +pub enum ClientArch { + /// Legacy x86 BIOS PXE (option 93 = 0x0000). + LegacyX86, + /// IA32 UEFI (option 93 = 0x0006). + Ia32Uefi, + /// x86_64 UEFI (option 93 = 0x0007 or 0x0009). + X64Uefi, + /// ARM32 UEFI (option 93 = 0x000A). + Arm32Uefi, + /// ARM64 UEFI (option 93 = 0x000B). + Arm64Uefi, + /// Unknown / unsupported architecture; caller should log and skip. + Unknown(u16), +} + +impl ClientArch { + #[must_use] + pub fn from_option_93(value: u16) -> Self { + match value { + 0x0000 => Self::LegacyX86, + 0x0006 => Self::Ia32Uefi, + 0x0007 | 0x0009 => Self::X64Uefi, + 0x000A => Self::Arm32Uefi, + 0x000B => Self::Arm64Uefi, + other => Self::Unknown(other), + } + } + + /// Default iPXE binary filename to return via TFTP for this architecture. + /// Uses `snponly` variants which reuse the firmware's UNDI/SNP network + /// stack — smaller binaries and broader hardware compatibility than the + /// all-drivers-included `ipxe.efi`. + #[must_use] + pub fn ipxe_bootfile(self) -> Option<&'static str> { + Some(match self { + Self::LegacyX86 => "undionly.kpxe", + Self::Ia32Uefi => "snponly-i386.efi", + Self::X64Uefi => "snponly.efi", + // ARM32 UEFI: upstream boot.ipxe.org does not publish a prebuilt + // snponly variant for this arch. We return None so the DHCP + // proxy declines rather than advertising a file we can't serve. + Self::Arm32Uefi => return None, + Self::Arm64Uefi => "snponly-arm64.efi", + Self::Unknown(_) => return None, + }) + } + + #[must_use] + pub fn as_str(self) -> &'static str { + match self { + Self::LegacyX86 => "bios", + Self::Ia32Uefi => "uefi-ia32", + Self::X64Uefi => "uefi-x64", + Self::Arm32Uefi => "uefi-arm32", + Self::Arm64Uefi => "uefi-arm64", + Self::Unknown(_) => "unknown", + } + } +} + +/// Which firmware class issued the DHCP request. Used to decide the reply +/// path — PXEClient gets TFTP/iPXE chainload, HTTPClient gets an HTTP URL, +/// iPXE itself gets the boot script URL. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum FirmwareClass { + /// Firmware PXE ROM (option 60 = "PXEClient"). + PxeClient, + /// UEFI HTTP boot (option 60 = "HTTPClient"). + HttpClient, + /// iPXE (option 77 user-class = "iPXE"). + IpxeUserClass, + /// No recognised signature — likely not a PXE client at all. + Other, +} + +impl FirmwareClass { + /// Classify a DHCP request. `vendor_class_60` is option 60 (vendor class + /// identifier); `user_class_77` is option 77 (user class). Check user-class + /// first because iPXE-that-we-chainloaded will set option 60 to PXEClient + /// *and* option 77 to iPXE, and the iPXE classification wins. + #[must_use] + pub fn classify(vendor_class_60: Option<&[u8]>, user_class_77: Option<&[u8]>) -> Self { + if let Some(uc) = user_class_77 { + if uc.windows(b"iPXE".len()).any(|w| w == b"iPXE") { + return Self::IpxeUserClass; + } + } + match vendor_class_60 { + Some(v) if v.starts_with(b"PXEClient") => Self::PxeClient, + Some(v) if v.starts_with(b"HTTPClient") => Self::HttpClient, + _ => Self::Other, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn arch_aliases_0x0009_to_x64() { + assert_eq!(ClientArch::from_option_93(0x0007), ClientArch::X64Uefi); + assert_eq!(ClientArch::from_option_93(0x0009), ClientArch::X64Uefi); + } + + #[test] + fn legacy_and_arm() { + assert_eq!(ClientArch::from_option_93(0x0000), ClientArch::LegacyX86); + assert_eq!(ClientArch::from_option_93(0x000B), ClientArch::Arm64Uefi); + assert!(matches!( + ClientArch::from_option_93(0x1234), + ClientArch::Unknown(0x1234) + )); + } + + #[test] + fn bootfile_names_stable() { + assert_eq!(ClientArch::LegacyX86.ipxe_bootfile(), Some("undionly.kpxe")); + assert_eq!(ClientArch::X64Uefi.ipxe_bootfile(), Some("snponly.efi")); + assert_eq!(ClientArch::Arm64Uefi.ipxe_bootfile(), Some("snponly-arm64.efi")); + assert_eq!(ClientArch::Unknown(0xFFFF).ipxe_bootfile(), None); + } + + #[test] + fn firmware_class_detects_ipxe_over_pxeclient() { + let c = FirmwareClass::classify(Some(b"PXEClient:Arch:00007"), Some(b"iPXE")); + assert_eq!(c, FirmwareClass::IpxeUserClass); + } + + #[test] + fn firmware_class_http() { + let c = FirmwareClass::classify(Some(b"HTTPClient:Arch:00016"), None); + assert_eq!(c, FirmwareClass::HttpClient); + } + + #[test] + fn firmware_class_plain_pxe() { + let c = FirmwareClass::classify(Some(b"PXEClient"), None); + assert_eq!(c, FirmwareClass::PxeClient); + } +} diff --git a/crates/core/src/client.rs b/crates/core/src/client.rs new file mode 100644 index 0000000..b9fcd55 --- /dev/null +++ b/crates/core/src/client.rs @@ -0,0 +1,100 @@ +//! In-memory client state registry — the "who has contacted us" table the +//! web UI displays. Not persisted: PXE sessions are ephemeral by nature. + +use crate::arch::ClientArch; +use parking_lot::RwLock; +use serde::{Deserialize, Serialize}; +use std::collections::HashMap; +use std::net::IpAddr; +use std::sync::Arc; +use time::OffsetDateTime; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub enum ClientEvent { + DhcpDiscover, + DhcpRequest, + PxeBootServerRequest, + TftpRead { file: String }, + HttpScriptFetch { target: String }, + HttpIsoAsset { file: String }, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ClientSnapshot { + pub mac: String, + pub last_ip: Option, + pub arch: Option, + pub hostname: Option, + #[serde(with = "time::serde::rfc3339")] + pub first_seen: OffsetDateTime, + #[serde(with = "time::serde::rfc3339")] + pub last_seen: OffsetDateTime, + // Events are left with default serialization (9-tuple) — they're + // diagnostic only and not consumed by the UI today. + pub events: Vec<(OffsetDateTime, ClientEvent)>, + /// The boot target (ISO id) last selected via the iPXE menu, if any. + pub selected_target: Option, +} + +#[derive(Debug, Default)] +pub struct ClientRegistry { + inner: RwLock>, +} + +impl ClientRegistry { + #[must_use] + pub fn new() -> Arc { + Arc::new(Self::default()) + } + + pub fn record( + &self, + mac: &str, + ip: Option, + arch: Option, + event: ClientEvent, + ) { + let mut guard = self.inner.write(); + let now = OffsetDateTime::now_utc(); + let entry = guard.entry(mac.to_string()).or_insert_with(|| ClientSnapshot { + mac: mac.to_string(), + last_ip: ip, + arch, + hostname: None, + first_seen: now, + last_seen: now, + events: Vec::new(), + selected_target: None, + }); + entry.last_seen = now; + if ip.is_some() { entry.last_ip = ip; } + if arch.is_some() { entry.arch = arch; } + entry.events.push((now, event)); + // Cap event history per client to keep memory bounded. + const MAX_EVENTS: usize = 64; + if entry.events.len() > MAX_EVENTS { + let drop_n = entry.events.len() - MAX_EVENTS; + entry.events.drain(..drop_n); + } + } + + pub fn set_selected_target(&self, mac: &str, target: Option) { + let mut guard = self.inner.write(); + if let Some(c) = guard.get_mut(mac) { + c.selected_target = target; + } + } + + #[must_use] + pub fn list(&self) -> Vec { + let guard = self.inner.read(); + let mut v: Vec<_> = guard.values().cloned().collect(); + v.sort_by(|a, b| b.last_seen.cmp(&a.last_seen)); + v + } + + #[must_use] + pub fn get(&self, mac: &str) -> Option { + self.inner.read().get(mac).cloned() + } +} diff --git a/crates/core/src/config.rs b/crates/core/src/config.rs new file mode 100644 index 0000000..7d9c420 --- /dev/null +++ b/crates/core/src/config.rs @@ -0,0 +1,168 @@ +use serde::{Deserialize, Serialize}; +use std::net::{IpAddr, Ipv4Addr}; +use std::path::{Path, PathBuf}; + +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(default)] +pub struct Config { + pub server: ServerConfig, + pub network: NetworkConfig, + pub paths: Paths, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(default)] +pub struct ServerConfig { + /// Address the web/API server binds to. + pub http_bind: IpAddr, + /// Port for the web/API + ISO/iPXE HTTP server (single port, multiplexed by path). + pub http_port: u16, + /// Address the TFTP server binds to. + pub tftp_bind: IpAddr, + /// Port for TFTP (RFC 1350 default is 69). + pub tftp_port: u16, + /// External hostname/IP clients should use to reach this server. If + /// `None`, auto-detect from the interface that received the DHCP request + /// (via IP_PKTINFO). This is what ends up in DHCP option 54 / siaddr, + /// option 66 (TFTP server), and the base of generated iPXE URLs. + pub public_ip: Option, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(default)] +pub struct NetworkConfig { + pub dhcp_mode: DhcpMode, + /// Address the DHCP proxy/server binds to. For proxy mode, usually 0.0.0.0. + pub dhcp_bind: IpAddr, + /// UDP port for DHCP server-side receive. Standard is 67. + pub dhcp_port: u16, + /// UDP port for PXE Boot Server discovery. Standard is 4011. + pub pxe_port: u16, + /// Optional allowlist of client MAC prefixes (OUI). Empty = serve everyone. + pub mac_allowlist: Vec, + /// Optional allowlist of subnets (CIDR). Empty = serve everyone. + pub subnet_allowlist: Vec, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "lowercase")] +pub enum DhcpMode { + /// Run as DHCP proxy (RFC 4578): reply with boot info only, don't lease + /// IPs. Coexists with an existing DHCP server on the network. Default + /// because it's the only mode that works in most real deployments without + /// taking over address assignment. + #[default] + Proxy, + /// Disabled — rely on an external DHCP server that has been manually + /// configured with `next-server` / `filename`. PXEForge only serves TFTP + /// + HTTP in this mode. Useful for home routers that can be pre-set. + Disabled, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(default)] +pub struct Paths { + /// Directory holding uploaded ISO files. + pub iso_dir: PathBuf, + /// Directory for extracted kernel/initrd and other per-ISO derived assets. + pub work_dir: PathBuf, + /// Directory containing bundled iPXE binaries (undionly.kpxe, snponly.efi, ...). + pub ipxe_dir: PathBuf, + /// Path to the wimboot binary for Windows ISOs (optional — feature-gated). + pub wimboot_path: Option, + /// Directory under which Windows ISOs are extracted and served via SMB. + /// Only used when `settings.windows_enabled = true`. Defaults to + /// `/var/lib/pxeforge/smb` in the container image. + pub smb_dir: PathBuf, +} + +impl Default for ServerConfig { + fn default() -> Self { + Self { + http_bind: IpAddr::V4(Ipv4Addr::UNSPECIFIED), + http_port: 80, + tftp_bind: IpAddr::V4(Ipv4Addr::UNSPECIFIED), + tftp_port: 69, + public_ip: None, + } + } +} + +impl Default for NetworkConfig { + fn default() -> Self { + Self { + dhcp_mode: DhcpMode::Proxy, + dhcp_bind: IpAddr::V4(Ipv4Addr::UNSPECIFIED), + dhcp_port: 67, + pxe_port: 4011, + mac_allowlist: Vec::new(), + subnet_allowlist: Vec::new(), + } + } +} + +impl Default for Paths { + fn default() -> Self { + Self { + iso_dir: PathBuf::from("/var/lib/pxeforge/isos"), + work_dir: PathBuf::from("/var/lib/pxeforge/work"), + ipxe_dir: PathBuf::from("/usr/share/pxeforge/ipxe"), + wimboot_path: None, + smb_dir: PathBuf::from("/var/lib/pxeforge/smb"), + } + } +} + +impl Default for Config { + fn default() -> Self { + Self { + server: ServerConfig::default(), + network: NetworkConfig::default(), + paths: Paths::default(), + } + } +} + +impl Config { + pub fn from_toml_file(path: &Path) -> crate::Result { + let text = std::fs::read_to_string(path)?; + toml::from_str(&text).map_err(|e| crate::Error::Config(e.to_string())) + } + + /// Apply environment variable overrides. Env var names follow the pattern + /// `PXEFORGE_
_`, uppercase. Unknown vars are ignored. + /// Call this after loading the TOML file so env takes precedence. + pub fn apply_env(&mut self) { + if let Ok(v) = std::env::var("PXEFORGE_HTTP_PORT") { + if let Ok(p) = v.parse() { self.server.http_port = p; } + } + if let Ok(v) = std::env::var("PXEFORGE_TFTP_PORT") { + if let Ok(p) = v.parse() { self.server.tftp_port = p; } + } + if let Ok(v) = std::env::var("PXEFORGE_DHCP_PORT") { + if let Ok(p) = v.parse() { self.network.dhcp_port = p; } + } + if let Ok(v) = std::env::var("PXEFORGE_PUBLIC_IP") { + if let Ok(ip) = v.parse() { self.server.public_ip = Some(ip); } + } + if let Ok(v) = std::env::var("PXEFORGE_DHCP_MODE") { + self.network.dhcp_mode = match v.to_ascii_lowercase().as_str() { + "proxy" => DhcpMode::Proxy, + "disabled" | "off" | "none" => DhcpMode::Disabled, + _ => self.network.dhcp_mode, + }; + } + if let Ok(v) = std::env::var("PXEFORGE_ISO_DIR") { + self.paths.iso_dir = PathBuf::from(v); + } + if let Ok(v) = std::env::var("PXEFORGE_WORK_DIR") { + self.paths.work_dir = PathBuf::from(v); + } + if let Ok(v) = std::env::var("PXEFORGE_IPXE_DIR") { + self.paths.ipxe_dir = PathBuf::from(v); + } + if let Ok(v) = std::env::var("PXEFORGE_SMB_DIR") { + self.paths.smb_dir = PathBuf::from(v); + } + } +} diff --git a/crates/core/src/error.rs b/crates/core/src/error.rs new file mode 100644 index 0000000..9f2e239 --- /dev/null +++ b/crates/core/src/error.rs @@ -0,0 +1,17 @@ +use thiserror::Error; + +#[derive(Debug, Error)] +pub enum Error { + #[error("io: {0}")] + Io(#[from] std::io::Error), + #[error("config: {0}")] + Config(String), + #[error("not found: {0}")] + NotFound(String), + #[error("invalid input: {0}")] + Invalid(String), + #[error(transparent)] + Other(#[from] anyhow::Error), +} + +pub type Result = std::result::Result; diff --git a/crates/core/src/gate.rs b/crates/core/src/gate.rs new file mode 100644 index 0000000..acfd13f --- /dev/null +++ b/crates/core/src/gate.rs @@ -0,0 +1,254 @@ +//! Gated Deployment queue. +//! +//! When a client selects "Gated Deployment" at the PXE menu, iPXE POSTs to +//! `/api/gate/join` and receives a gate position. It then enters a poll +//! loop hitting `/api/gate/poll/`; the server holds the request open +//! until either (a) the operator assigns an ISO from the WebUI, in which +//! case the poll returns an iPXE `chain` URL, or (b) the poll times out +//! (iPXE's HTTP client has its own timeout), in which case iPXE re-POSTs. +//! +//! The WebUI shows the queue (`GET /api/gate`) and issues +//! `POST /api/gate/assign { iso_id, gate_ids: [...] }` to launch a single +//! ISO across many gated clients at once. This is the "horse-race gate" +//! UX the user asked for — every horse leaves the line simultaneously. + +use parking_lot::RwLock; +use serde::{Deserialize, Serialize}; +use std::collections::HashMap; +use std::net::IpAddr; +use std::sync::Arc; +use time::OffsetDateTime; +use tokio::sync::Notify; +use uuid::Uuid; + +use crate::ClientArch; + +/// Per-gate state visible to the WebUI. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct Gate { + pub id: String, + /// 1-based race-gate position — position 1 is whoever got there first. + pub position: u32, + pub mac: String, + pub ip: Option, + pub arch: Option, + #[serde(with = "time::serde::rfc3339")] + pub joined_at: OffsetDateTime, + #[serde(with = "time::serde::rfc3339")] + pub last_poll_at: OffsetDateTime, + pub assigned_target: Option, +} + +#[derive(Debug)] +struct GateInner { + id: String, + position: u32, + mac: String, + ip: Option, + arch: Option, + joined_at: OffsetDateTime, + last_poll_at: OffsetDateTime, + assigned_target: Option, + /// Broadcast primitive that wakes the long-poll as soon as an + /// assignment lands — no polling on our side, no sleep-loops. + notify: Arc, +} + +impl GateInner { + fn snapshot(&self) -> Gate { + Gate { + id: self.id.clone(), + position: self.position, + mac: self.mac.clone(), + ip: self.ip, + arch: self.arch, + joined_at: self.joined_at, + last_poll_at: self.last_poll_at, + assigned_target: self.assigned_target.clone(), + } + } +} + +#[derive(Debug, Default)] +pub struct GateQueue { + inner: RwLock>, +} + +impl GateQueue { + #[must_use] + pub fn new() -> Arc { + Arc::new(Self::default()) + } + + /// Add a client to the gate. Returns the new `Gate` snapshot. If the + /// MAC is already queued, the existing gate is returned unchanged — + /// retrying iPXE clients don't duplicate their slot. + pub fn join(&self, mac: &str, ip: Option, arch: Option) -> Gate { + let now = OffsetDateTime::now_utc(); + let mut guard = self.inner.write(); + + if let Some(existing) = guard.values_mut().find(|g| g.mac == mac) { + existing.last_poll_at = now; + if ip.is_some() { existing.ip = ip; } + if arch.is_some() { existing.arch = arch; } + return existing.snapshot(); + } + + // Race position = max(position) + 1, or 1 if empty. + let next_pos = guard.values().map(|g| g.position).max().unwrap_or(0) + 1; + let id = Uuid::new_v4().to_string(); + let inner = GateInner { + id: id.clone(), + position: next_pos, + mac: mac.to_string(), + ip, + arch, + joined_at: now, + last_poll_at: now, + assigned_target: None, + notify: Arc::new(Notify::new()), + }; + let snap = inner.snapshot(); + guard.insert(id, inner); + snap + } + + /// Look up the `Notify` primitive for a given gate id, for long-polling. + #[must_use] + pub fn notifier(&self, gate_id: &str) -> Option> { + self.inner.read().get(gate_id).map(|g| g.notify.clone()) + } + + /// Update the last-poll timestamp (keeps the gate's "live" indicator + /// fresh in the UI) and return the current snapshot. Returns None if + /// the gate was released/expired between requests. + pub fn touch(&self, gate_id: &str) -> Option { + let mut guard = self.inner.write(); + let g = guard.get_mut(gate_id)?; + g.last_poll_at = OffsetDateTime::now_utc(); + Some(g.snapshot()) + } + + /// Operator assigns an ISO entry (boot_entry id) to one or more gates. + /// Returns the number of gates that were updated. Gates not in the + /// queue are silently skipped. + pub fn assign(&self, gate_ids: &[String], target: &str) -> usize { + let mut guard = self.inner.write(); + let mut updated = 0; + for id in gate_ids { + if let Some(g) = guard.get_mut(id) { + g.assigned_target = Some(target.to_string()); + g.notify.notify_waiters(); + updated += 1; + } + } + updated + } + + /// Remove a gate and return its final snapshot. Called after the client + /// has successfully chained onto its assignment. + pub fn release(&self, gate_id: &str) -> Option { + let mut guard = self.inner.write(); + let g = guard.remove(gate_id)?; + g.notify.notify_waiters(); + // Renumber positions so the display stays contiguous (1..N). This + // is O(N) but the queue is expected to be small (dozens of hosts). + let mut remaining: Vec<_> = guard.values_mut().collect(); + remaining.sort_by_key(|g| g.position); + for (i, g) in remaining.iter_mut().enumerate() { + g.position = (i + 1) as u32; + } + Some(g.snapshot()) + } + + #[must_use] + pub fn list(&self) -> Vec { + let guard = self.inner.read(); + let mut v: Vec<_> = guard.values().map(GateInner::snapshot).collect(); + v.sort_by_key(|g| g.position); + v + } + + #[must_use] + pub fn len(&self) -> usize { + self.inner.read().len() + } + + #[must_use] + pub fn is_empty(&self) -> bool { + self.len() == 0 + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn join_assigns_sequential_positions() { + let q = GateQueue::new(); + let g1 = q.join("aa:bb:cc:00:00:01", None, None); + let g2 = q.join("aa:bb:cc:00:00:02", None, None); + let g3 = q.join("aa:bb:cc:00:00:03", None, None); + assert_eq!(g1.position, 1); + assert_eq!(g2.position, 2); + assert_eq!(g3.position, 3); + } + + #[test] + fn rejoining_same_mac_is_idempotent() { + let q = GateQueue::new(); + let g1 = q.join("aa:bb:cc:00:00:01", None, None); + let g2 = q.join("aa:bb:cc:00:00:01", None, None); + assert_eq!(g1.id, g2.id); + assert_eq!(g1.position, g2.position); + assert_eq!(q.len(), 1); + } + + #[test] + fn assign_broadcasts_target() { + let q = GateQueue::new(); + let g1 = q.join("aa:bb:cc:00:00:01", None, None); + let g2 = q.join("aa:bb:cc:00:00:02", None, None); + let n = q.assign(&[g1.id.clone(), g2.id.clone()], "ubuntu-24-04-linux"); + assert_eq!(n, 2); + for g in q.list() { + assert_eq!(g.assigned_target.as_deref(), Some("ubuntu-24-04-linux")); + } + } + + #[test] + fn release_renumbers() { + let q = GateQueue::new(); + let a = q.join("aa:00:00:00:00:01", None, None); + let _b = q.join("aa:00:00:00:00:02", None, None); + let c = q.join("aa:00:00:00:00:03", None, None); + q.release(&a.id); + let list = q.list(); + assert_eq!(list.len(), 2); + assert_eq!(list[0].position, 1); + assert_eq!(list[1].position, 2); + // c had position 3, now renumbered to 2. + assert_eq!(list[1].id, c.id); + } + + #[tokio::test] + async fn assign_wakes_waiter() { + let q = GateQueue::new(); + let g = q.join("aa:00:00:00:00:01", None, None); + let notify = q.notifier(&g.id).unwrap(); + + let q2 = Arc::new(q); + let q3 = q2.clone(); + let id = g.id.clone(); + let fut = tokio::spawn(async move { + notify.notified().await; + q3.touch(&id) + }); + tokio::time::sleep(std::time::Duration::from_millis(10)).await; + q2.assign(&[g.id.clone()], "x"); + let result = fut.await.unwrap(); + assert!(result.is_some()); + assert_eq!(result.unwrap().assigned_target.as_deref(), Some("x")); + } +} diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs new file mode 100644 index 0000000..fc80e82 --- /dev/null +++ b/crates/core/src/lib.rs @@ -0,0 +1,19 @@ +//! PXEForge shared core: config, arch detection, client state registry, +//! runtime settings, and the Gated Deployment queue. +#![forbid(unsafe_code)] + +pub mod arch; +pub mod client; +pub mod config; +pub mod error; +pub mod gate; +pub mod log_bus; +pub mod settings; + +pub use arch::{ClientArch, FirmwareClass}; +pub use client::{ClientEvent, ClientRegistry, ClientSnapshot}; +pub use config::{Config, DhcpMode, NetworkConfig, Paths, ServerConfig}; +pub use error::{Error, Result}; +pub use gate::{Gate, GateQueue}; +pub use log_bus::{LogBus, LogBusLayer, LogLine}; +pub use settings::{Settings, SettingsStore, TimeoutAction}; diff --git a/crates/core/src/log_bus.rs b/crates/core/src/log_bus.rs new file mode 100644 index 0000000..0ef49e9 --- /dev/null +++ b/crates/core/src/log_bus.rs @@ -0,0 +1,200 @@ +//! In-process log bus. +//! +//! The web UI's Terminal tab streams live server logs over SSE. To feed it +//! we install a `tracing_subscriber::Layer` that captures formatted lines +//! and pushes them onto: +//! +//! 1. A bounded `tokio::sync::broadcast` channel for live subscribers. +//! 2. A small in-memory ring buffer (default 500 lines) so a UI that +//! connects mid-session sees recent context, not a blank pane. +//! +//! No file logging happens here — Docker/OpenShift already capture stdout. +//! This is purely an extra fan-out for the UI. + +use parking_lot::Mutex; +use serde::{Deserialize, Serialize}; +use std::collections::VecDeque; +use std::sync::Arc; +use time::OffsetDateTime; +use tokio::sync::broadcast; +use tracing::field::{Field, Visit}; +use tracing::{Event, Level, Subscriber}; +use tracing_subscriber::layer::Context; +use tracing_subscriber::registry::LookupSpan; +use tracing_subscriber::Layer; + +/// One captured log line. Cheap to clone (small struct, short strings). +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct LogLine { + #[serde(with = "time::serde::rfc3339")] + pub timestamp: OffsetDateTime, + /// Lowercase: `error`, `warn`, `info`, `debug`, `trace`. + pub level: String, + pub target: String, + pub message: String, +} + +impl LogLine { + /// Compact one-line "tail -f"-style render. + #[must_use] + pub fn render(&self) -> String { + // 2026-04-29T12:34:56Z [info] pxeforge::http: HTTP listening on 0.0.0.0:80 + let ts = self + .timestamp + .format(&time::format_description::well_known::Rfc3339) + .unwrap_or_else(|_| "?".into()); + format!( + "{ts} [{:>5}] {}: {}", + self.level, self.target, self.message + ) + } +} + +#[derive(Debug)] +pub struct LogBus { + tx: broadcast::Sender, + buf: Mutex>, + cap: usize, +} + +impl LogBus { + #[must_use] + pub fn new(capacity: usize) -> Arc { + // 256 = upper bound on concurrent live subscribers' lag tolerance. + // If a slow client falls behind it'll get a Lagged error and skip + // ahead — which is what we want for a live tail. + let (tx, _) = broadcast::channel(256); + Arc::new(Self { + tx, + buf: Mutex::new(VecDeque::with_capacity(capacity)), + cap: capacity, + }) + } + + /// Subscribe to new log lines as they're emitted. + #[must_use] + pub fn subscribe(&self) -> broadcast::Receiver { + self.tx.subscribe() + } + + /// Snapshot of the recent ring buffer (oldest → newest). + #[must_use] + pub fn recent(&self) -> Vec { + self.buf.lock().iter().cloned().collect() + } + + /// Drop everything in the recent ring buffer. + pub fn clear(&self) { + self.buf.lock().clear(); + } + + /// Manually push a synthetic log line (used by the terminal-command + /// handler so operator commands appear inline in the live tail). + pub fn push(&self, level: &str, target: &str, message: impl Into) { + let line = LogLine { + timestamp: OffsetDateTime::now_utc(), + level: level.to_string(), + target: target.to_string(), + message: message.into(), + }; + self.record(line); + } + + fn record(&self, line: LogLine) { + { + let mut g = self.buf.lock(); + if g.len() == self.cap { + g.pop_front(); + } + g.push_back(line.clone()); + } + // Send errors are fine — just means no live subscribers right now. + let _ = self.tx.send(line); + } +} + +/// `tracing_subscriber::Layer` that funnels every event into the LogBus. +/// +/// Install once in `main` alongside the existing `fmt::layer()` so console +/// output and the UI tail see the same stream. +pub struct LogBusLayer { + bus: Arc, +} + +impl LogBusLayer { + #[must_use] + pub fn new(bus: Arc) -> Self { + Self { bus } + } +} + +impl Layer for LogBusLayer +where + S: Subscriber + for<'a> LookupSpan<'a>, +{ + fn on_event(&self, event: &Event<'_>, _ctx: Context<'_, S>) { + let meta = event.metadata(); + let level = match *meta.level() { + Level::ERROR => "error", + Level::WARN => "warn", + Level::INFO => "info", + Level::DEBUG => "debug", + Level::TRACE => "trace", + }; + let mut visitor = MessageVisitor::default(); + event.record(&mut visitor); + let line = LogLine { + timestamp: OffsetDateTime::now_utc(), + level: level.to_string(), + target: meta.target().to_string(), + message: visitor.message, + }; + self.bus.record(line); + } +} + +#[derive(Default)] +struct MessageVisitor { + message: String, +} + +impl Visit for MessageVisitor { + fn record_str(&mut self, field: &Field, value: &str) { + if field.name() == "message" { + self.message = value.to_string(); + } + } + fn record_debug(&mut self, field: &Field, value: &dyn std::fmt::Debug) { + if field.name() == "message" { + self.message = format!("{value:?}").trim_matches('"').to_string(); + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[tokio::test(flavor = "current_thread")] + async fn push_and_recent() { + let bus = LogBus::new(3); + bus.push("info", "test", "first"); + bus.push("info", "test", "second"); + bus.push("info", "test", "third"); + bus.push("info", "test", "fourth"); + let r = bus.recent(); + assert_eq!(r.len(), 3); + assert_eq!(r[0].message, "second"); + assert_eq!(r[2].message, "fourth"); + } + + #[tokio::test(flavor = "current_thread")] + async fn subscribe_sees_new_lines() { + let bus = LogBus::new(8); + let mut rx = bus.subscribe(); + bus.push("info", "test", "live"); + let l = rx.recv().await.unwrap(); + assert_eq!(l.message, "live"); + assert_eq!(l.level, "info"); + } +} diff --git a/crates/core/src/settings.rs b/crates/core/src/settings.rs new file mode 100644 index 0000000..f823807 --- /dev/null +++ b/crates/core/src/settings.rs @@ -0,0 +1,187 @@ +//! Runtime-mutable settings, distinct from the static `Config`. +//! +//! Rationale: `Config` holds bind addresses, paths, and other things that +//! can only reasonably change at process start. `Settings` holds everything +//! the web UI can flip at runtime: timeouts, default boot action, Windows +//! feature toggles, etc. Persisted to `/settings.json` so they +//! survive pod restarts without requiring a ConfigMap edit. +//! +//! **Crucial property:** every UI-facing "feature flag" in here maps to a +//! specific iPXE script-generation behavior elsewhere in the codebase. The +//! user never writes iPXE; they toggle a setting and we translate. + +use parking_lot::RwLock; +use serde::{Deserialize, Serialize}; +use std::path::{Path, PathBuf}; +use std::sync::Arc; + +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(default)] +pub struct Settings { + /// Seconds to wait at the top-level boot menu before falling through + /// to `timeout_action`. Default 600s per the Phase 2 spec. + pub boot_menu_timeout_secs: u32, + + /// What happens if the boot-menu timer hits zero with no selection. + pub timeout_action: TimeoutAction, + + /// Master enable for Windows ISO support. When off, Windows ISOs are + /// listed in the UI as "Windows — disabled" and not exposed in the + /// PXE menu. Off by default: Windows support requires bundling Samba + /// and wimlib in the runtime image (see deploy/docker/Dockerfile). + pub windows_enabled: bool, + + /// SMB share hostname/IP the patched WinPE's startnet.cmd will + /// `net use` against. Empty string = auto-fill with the public IP at + /// script-generation time. + pub smb_host_override: String, + + /// Global kernel-args append (added to every Linux entry's cmdline). + /// Useful for things like `console=ttyS0,115200` on serial-only boxes. + /// Do NOT accept raw iPXE script fragments here; this is literal kernel + /// args only. + pub extra_kernel_args: String, + + /// If true, the "Default → Boot from Local HDD" menu item is the + /// pre-selected entry (and is what the timeout falls to if + /// `timeout_action = LocalHdd`). + pub default_local_hdd: bool, + + /// When a client hits the Gated Deployment item, how long (seconds) to + /// hold it at the gate before giving up and falling back to the menu. + /// 0 = forever. + pub gate_wait_max_secs: u32, + + /// Optional DNS server advertised on the Network tab. Purely + /// informational today — PXEForge does not run a DNS server, but + /// operators expect to be able to record what the upstream DNS is. + /// Empty string = unset (UI shows placeholder). + pub dns_server: String, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum TimeoutAction { + /// Sit at the menu forever (no fallthrough). + Stay, + /// Chain the "Boot from Local HDD" entry. + LocalHdd, + /// Put the client into the gate queue, waiting for operator assignment. + #[default] + GatedDeployment, +} + +impl Default for Settings { + fn default() -> Self { + Self { + boot_menu_timeout_secs: 600, + timeout_action: TimeoutAction::GatedDeployment, + windows_enabled: false, + smb_host_override: String::new(), + extra_kernel_args: String::new(), + default_local_hdd: true, + gate_wait_max_secs: 0, + dns_server: String::new(), + } + } +} + +#[derive(Debug)] +pub struct SettingsStore { + path: PathBuf, + inner: RwLock, +} + +impl SettingsStore { + /// Load from `work_dir/settings.json`, or create with defaults if the + /// file is missing/corrupt. Never fails — a bad settings file on disk + /// is not a reason to refuse to start. + pub fn load_or_default(work_dir: &Path) -> Arc { + let path = work_dir.join("settings.json"); + let initial = match std::fs::read_to_string(&path) { + Ok(text) => match serde_json::from_str::(&text) { + Ok(s) => s, + Err(e) => { + tracing::warn!( + target: "pxeforge::settings", + "settings.json present but unreadable ({e}); falling back to defaults" + ); + Settings::default() + } + }, + Err(_) => Settings::default(), + }; + Arc::new(Self { path, inner: RwLock::new(initial) }) + } + + #[must_use] + pub fn snapshot(&self) -> Settings { + self.inner.read().clone() + } + + /// Atomically replace settings and persist. The caller supplies the full + /// `Settings` struct — partial updates happen at the HTTP layer via + /// merge-then-store. Persistence errors are logged but not returned; + /// settings live in memory authoritatively and only SHOULD be on disk. + pub fn replace(&self, new: Settings) { + { + let mut g = self.inner.write(); + *g = new; + } + let snap = self.snapshot(); + if let Err(e) = self.persist(&snap) { + tracing::warn!(target: "pxeforge::settings", "failed to persist settings: {e}"); + } + } + + fn persist(&self, s: &Settings) -> std::io::Result<()> { + let tmp = self.path.with_extension("json.tmp"); + if let Some(parent) = self.path.parent() { + std::fs::create_dir_all(parent)?; + } + let body = serde_json::to_vec_pretty(s) + .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))?; + std::fs::write(&tmp, body)?; + std::fs::rename(tmp, &self.path) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use tempfile::tempdir; + + #[test] + fn defaults_roundtrip() { + let dir = tempdir().unwrap(); + let store = SettingsStore::load_or_default(dir.path()); + let s = store.snapshot(); + assert_eq!(s.boot_menu_timeout_secs, 600); + assert_eq!(s.timeout_action, TimeoutAction::GatedDeployment); + assert!(!s.windows_enabled); + } + + #[test] + fn replace_persists() { + let dir = tempdir().unwrap(); + let store = SettingsStore::load_or_default(dir.path()); + let mut new = store.snapshot(); + new.boot_menu_timeout_secs = 30; + new.windows_enabled = true; + store.replace(new); + // Reload from disk. + drop(store); + let reloaded = SettingsStore::load_or_default(dir.path()); + let s = reloaded.snapshot(); + assert_eq!(s.boot_menu_timeout_secs, 30); + assert!(s.windows_enabled); + } + + #[test] + fn corrupt_file_falls_back_to_default() { + let dir = tempdir().unwrap(); + std::fs::write(dir.path().join("settings.json"), b"{ not json }").unwrap(); + let store = SettingsStore::load_or_default(dir.path()); + assert_eq!(store.snapshot().boot_menu_timeout_secs, 600); + } +} diff --git a/crates/dhcp-proxy/Cargo.toml b/crates/dhcp-proxy/Cargo.toml new file mode 100644 index 0000000..34017fe --- /dev/null +++ b/crates/dhcp-proxy/Cargo.toml @@ -0,0 +1,20 @@ +[package] +name = "pxeforge-dhcp-proxy" +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +description = "DHCP proxy (RFC 4578) for PXEForge — serves boot info, does not lease IPs" + +[lints] +workspace = true + +[dependencies] +pxeforge-core.workspace = true +tokio.workspace = true +socket2.workspace = true +dhcproto.workspace = true +tracing.workspace = true +thiserror.workspace = true +anyhow.workspace = true +bytes.workspace = true diff --git a/crates/dhcp-proxy/src/lib.rs b/crates/dhcp-proxy/src/lib.rs new file mode 100644 index 0000000..21f83dc --- /dev/null +++ b/crates/dhcp-proxy/src/lib.rs @@ -0,0 +1,23 @@ +//! DHCP proxy (RFC 4578 "PXE Boot Server Discovery"). +//! +//! Listens on UDP/67 (broadcast) and UDP/4011 (PXE boot server). Never +//! assigns IPs — only returns boot parameters (siaddr, option 66 TFTP server, +//! option 67 boot filename, and the mandatory option 60 "PXEClient" echo). +//! +//! Key decisions (see architecture memory for rationale): +//! - Single code path handles both 67 and 4011; distinguished by port. +//! - We set `SO_REUSEADDR` + `SO_BROADCAST` and enable `IP_PKTINFO` so we can +//! (a) learn the destination interface for multi-homed pods and (b) reply +//! back through the correct interface. This lets us run behind host-network +//! in OpenShift without needing `SO_BINDTODEVICE` (which requires NET_RAW). +//! - Classification is: option 77 user-class `iPXE` → serve HTTP script URL; +//! option 60 starts `HTTPClient` → serve HTTP URL directly (UEFI HTTP boot); +//! otherwise → TFTP + arch-specific iPXE binary. +//! - We MUST echo `option 60 = "PXEClient"` (or `"HTTPClient"`) in replies or +//! clients silently drop them. +#![forbid(unsafe_code)] + +pub mod reply; +pub mod server; + +pub use server::DhcpProxyServer; diff --git a/crates/dhcp-proxy/src/reply.rs b/crates/dhcp-proxy/src/reply.rs new file mode 100644 index 0000000..42ef8a0 --- /dev/null +++ b/crates/dhcp-proxy/src/reply.rs @@ -0,0 +1,122 @@ +//! Build DHCP proxy replies. +//! +//! Proxy replies look like a normal DHCPOFFER/ACK except: +//! - `yiaddr` (your IP) is 0 — we don't lease. +//! - `siaddr` (server IP) is us — the client will TFTP from here. +//! - option 60 (vendor class) MUST be echoed as `PXEClient` or clients drop. +//! - option 66 (TFTP server name) points at us. +//! - option 67 (bootfile name) is per-architecture iPXE binary on first +//! pass, or the HTTP URL of the boot script once iPXE has chained. + +use dhcproto::v4::{DhcpOption, Message, MessageType, Opcode, OptionCode}; +use pxeforge_core::{ClientArch, FirmwareClass}; +use std::net::Ipv4Addr; + +/// Where the reply directs the client next. +#[derive(Debug, Clone)] +pub enum BootDirective { + /// Serve an iPXE binary over TFTP (first-stage chainload). + TftpIpxe { filename: String }, + /// Serve an iPXE boot script directly over HTTP. Used when the client is + /// iPXE itself (option 77 = "iPXE") or UEFI HTTP boot (option 60 starts + /// with "HTTPClient"). + HttpScript { url: String }, + /// Refuse to respond (architecture we don't have a binary for, or + /// not-a-PXE-client). Caller should skip sending anything. + Ignore, +} + +pub struct ReplyContext<'a> { + pub request: &'a Message, + pub our_ip: Ipv4Addr, + pub arch: ClientArch, + pub class: FirmwareClass, + /// Public base URL (scheme://host[:port]) used in HTTP directives. + pub public_base_url: &'a str, +} + +/// Decide what to do for an incoming request. Pure function — easy to unit +/// test. Does NOT send anything. +#[must_use] +pub fn decide(ctx: &ReplyContext<'_>) -> BootDirective { + match ctx.class { + FirmwareClass::IpxeUserClass => BootDirective::HttpScript { + url: format!("{}/boot.ipxe", ctx.public_base_url.trim_end_matches('/')), + }, + FirmwareClass::HttpClient => { + // UEFI HTTP boot: client wants an http:// URL in option 67 + // pointing at an EFI executable. We serve ipxe.efi over HTTP; + // it'll then do the same script-fetch the iPXE path does. + let name = ctx.arch.ipxe_bootfile().unwrap_or("snponly.efi"); + BootDirective::HttpScript { + url: format!("{}/ipxe/{}", ctx.public_base_url.trim_end_matches('/'), name), + } + } + FirmwareClass::PxeClient => match ctx.arch.ipxe_bootfile() { + Some(name) => BootDirective::TftpIpxe { filename: name.to_string() }, + None => BootDirective::Ignore, + }, + FirmwareClass::Other => BootDirective::Ignore, + } +} + +/// Build the outgoing DHCPOFFER (or ACK, matching request type) for a +/// directive. Caller is responsible for sending the bytes on the wire. +pub fn build_reply(ctx: &ReplyContext<'_>, directive: &BootDirective) -> Option { + let reply_type = match request_message_type(ctx.request)? { + MessageType::Discover => MessageType::Offer, + MessageType::Request | MessageType::Inform => MessageType::Ack, + _ => return None, + }; + + let mut msg = Message::default(); + msg.set_opcode(Opcode::BootReply) + .set_htype(ctx.request.htype()) + .set_hops(0) + .set_xid(ctx.request.xid()) + .set_secs(0) + .set_flags(ctx.request.flags()) + .set_ciaddr(Ipv4Addr::UNSPECIFIED) + .set_yiaddr(Ipv4Addr::UNSPECIFIED) // proxy does not lease + .set_siaddr(ctx.our_ip) + .set_giaddr(ctx.request.giaddr()) + .set_chaddr(ctx.request.chaddr()); + + // Set the BOOTP `file` field for legacy PXE stacks before we take the + // options borrow (the two borrows can't overlap). + if let BootDirective::TftpIpxe { filename } = directive { + msg.set_fname_str(filename); + } + + let class_echo: &[u8] = match ctx.class { + FirmwareClass::HttpClient => b"HTTPClient", + _ => b"PXEClient", + }; + let opts = msg.opts_mut(); + opts.insert(DhcpOption::MessageType(reply_type)); + opts.insert(DhcpOption::ServerIdentifier(ctx.our_ip)); + // Echo the vendor class — REQUIRED by spec for the client to accept. + opts.insert(DhcpOption::ClassIdentifier(class_echo.to_vec())); + + match directive { + BootDirective::TftpIpxe { filename } => { + opts.insert(DhcpOption::TFTPServerName(ctx.our_ip.to_string().into_bytes())); + opts.insert(DhcpOption::BootfileName(filename.as_bytes().to_vec())); + } + BootDirective::HttpScript { url } => { + opts.insert(DhcpOption::BootfileName(url.as_bytes().to_vec())); + opts.insert(DhcpOption::TFTPServerName(ctx.our_ip.to_string().into_bytes())); + } + BootDirective::Ignore => return None, + } + + opts.insert(DhcpOption::End); + Some(msg) +} + +fn request_message_type(m: &Message) -> Option { + m.opts().get(OptionCode::MessageType).and_then(|o| match o { + DhcpOption::MessageType(t) => Some(*t), + _ => None, + }) +} diff --git a/crates/dhcp-proxy/src/server.rs b/crates/dhcp-proxy/src/server.rs new file mode 100644 index 0000000..c64f834 --- /dev/null +++ b/crates/dhcp-proxy/src/server.rs @@ -0,0 +1,236 @@ +//! UDP listener loop for the DHCP proxy. Accepts on :67 (and :4011 on a +//! second socket) and dispatches each datagram through the pure reply logic. + +use crate::reply::{build_reply, decide, BootDirective, ReplyContext}; +use dhcproto::v4::{DhcpOption, Message, OptionCode}; +use dhcproto::{Decodable, Decoder, Encodable, Encoder}; +use pxeforge_core::{ + ClientArch, ClientEvent, ClientRegistry, FirmwareClass, +}; +use socket2::{Domain, Protocol, Socket, Type}; +use std::net::{IpAddr, Ipv4Addr, SocketAddr, SocketAddrV4}; +use std::sync::Arc; +use tokio::net::UdpSocket; + +pub struct DhcpProxyServer { + bind: IpAddr, + dhcp_port: u16, + pxe_port: u16, + our_ip: Ipv4Addr, + public_base_url: String, + clients: Arc, +} + +impl DhcpProxyServer { + pub fn new( + bind: IpAddr, + dhcp_port: u16, + pxe_port: u16, + our_ip: Ipv4Addr, + public_base_url: String, + clients: Arc, + ) -> Self { + Self { bind, dhcp_port, pxe_port, our_ip, public_base_url, clients } + } + + pub async fn run(self) -> anyhow::Result<()> { + let dhcp_sock = bind_udp(self.bind, self.dhcp_port, true)?; + let pxe_sock = bind_udp(self.bind, self.pxe_port, false)?; + tracing::info!( + target: "pxeforge::dhcp", + "DHCP proxy listening on {}:{} and :{}", + self.bind, self.dhcp_port, self.pxe_port + ); + + let ctx = Arc::new(self); + let c1 = ctx.clone(); + let c2 = ctx.clone(); + let a = tokio::spawn(async move { c1.serve_loop(dhcp_sock, "67").await }); + let b = tokio::spawn(async move { c2.serve_loop(pxe_sock, "4011").await }); + let _ = tokio::try_join!(a, b)?; + Ok(()) + } + + async fn serve_loop(&self, sock: UdpSocket, label: &'static str) -> anyhow::Result<()> { + let mut buf = vec![0u8; 4096]; + loop { + let (n, from) = match sock.recv_from(&mut buf).await { + Ok(v) => v, + Err(e) => { + tracing::warn!(target: "pxeforge::dhcp", port=label, "recv error: {e}"); + continue; + } + }; + if let Err(e) = self.handle_datagram(&sock, &buf[..n], from, label).await { + tracing::warn!(target: "pxeforge::dhcp", port=label, "handle error: {e}"); + } + } + } + + async fn handle_datagram( + &self, + sock: &UdpSocket, + data: &[u8], + from: SocketAddr, + label: &'static str, + ) -> anyhow::Result<()> { + let request = Message::decode(&mut Decoder::new(data))?; + + let vendor_class = request.opts().get(OptionCode::ClassIdentifier).and_then(|o| { + if let DhcpOption::ClassIdentifier(v) = o { Some(v.as_slice()) } else { None } + }); + let user_class = request.opts().get(OptionCode::UserClass).and_then(|o| { + if let DhcpOption::UserClass(v) = o { Some(v.as_slice()) } else { None } + }); + let class = FirmwareClass::classify(vendor_class, user_class); + if matches!(class, FirmwareClass::Other) { + // Not a PXE client (e.g. a regular DHCP DISCOVER from a phone). + // Silently ignore — we are a proxy, we only speak to PXE clients. + return Ok(()); + } + + // dhcproto types option 93 as an enum that drops unknown codes; + // re-parse from the raw wire bytes so firmware quirks like 0x0009 + // come through intact. + let raw_arch = extract_raw_arch(data).unwrap_or(0); + let arch = ClientArch::from_option_93(raw_arch); + + let chaddr = request.chaddr(); + let mac = format_mac(chaddr); + self.clients.record( + &mac, + None, + Some(arch), + match label { + "4011" => ClientEvent::PxeBootServerRequest, + _ => ClientEvent::DhcpDiscover, + }, + ); + + let ctx = ReplyContext { + request: &request, + our_ip: self.our_ip, + arch, + class, + public_base_url: &self.public_base_url, + }; + let directive = decide(&ctx); + if matches!(directive, BootDirective::Ignore) { + tracing::debug!( + target: "pxeforge::dhcp", + mac=%mac, arch=?arch, "ignoring — no bootfile for arch" + ); + return Ok(()); + } + + let Some(reply) = build_reply(&ctx, &directive) else { return Ok(()); }; + let mut out = Vec::with_capacity(512); + reply.encode(&mut Encoder::new(&mut out))?; + + let dest = reply_destination(&request, from); + sock.send_to(&out, dest).await?; + tracing::info!( + target: "pxeforge::dhcp", + mac=%mac, arch=arch.as_str(), class=?class, dest=%dest, directive=?directive, + "PXE reply sent" + ); + Ok(()) + } +} + +/// Choose where to send the reply. DHCP semantics (RFC 2131 §4.1): +/// 1. If the request came via a relay agent (`giaddr` != 0), reply to +/// that agent on port 67. The relay will forward to the client. +/// 2. If the client already has an IP (`ciaddr`), unicast there on :68. +/// 3. If the broadcast flag is set in the BOOTP flags (bit 15), the +/// client cannot receive unicast frames yet — we MUST broadcast. +/// 4. Otherwise, per the spec we MAY unicast to `chaddr` if we ARP-inject, +/// but since we don't craft raw frames (proxy mode, no NET_RAW), we +/// fall back to broadcast which every client accepts. +/// 5. Special case for the PXE Boot Server port 4011: reply to the +/// source address/port exactly — this is a unicast query and the +/// client expects a unicast answer there. +fn reply_destination(request: &Message, from: SocketAddr) -> SocketAddr { + // (1) relayed request + let giaddr = request.giaddr(); + if giaddr != Ipv4Addr::UNSPECIFIED { + return SocketAddr::V4(SocketAddrV4::new(giaddr, 67)); + } + // (5) PXE Boot Server discovery is unicast + if from.port() == 4011 { + return from; + } + // (2) client has an IP and has NOT requested broadcast-only + let ciaddr = request.ciaddr(); + let bflag = request.flags().broadcast(); + if ciaddr != Ipv4Addr::UNSPECIFIED && !bflag { + return SocketAddr::V4(SocketAddrV4::new(ciaddr, 68)); + } + // (3, 4) broadcast to 255.255.255.255:68 + SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::BROADCAST, 68)) +} + +fn bind_udp(bind: IpAddr, port: u16, broadcast: bool) -> anyhow::Result { + let domain = match bind { + IpAddr::V4(_) => Domain::IPV4, + IpAddr::V6(_) => Domain::IPV6, + }; + let sock = Socket::new(domain, Type::DGRAM, Some(Protocol::UDP))?; + sock.set_reuse_address(true)?; + #[cfg(unix)] + sock.set_reuse_port(true)?; + if broadcast { + sock.set_broadcast(true)?; + } + sock.set_nonblocking(true)?; + let addr: SocketAddr = SocketAddr::new(bind, port); + sock.bind(&addr.into())?; + let std_sock: std::net::UdpSocket = sock.into(); + Ok(UdpSocket::from_std(std_sock)?) +} + +fn format_mac(chaddr: &[u8]) -> String { + let take = chaddr.iter().take(6).copied().collect::>(); + take.iter().map(|b| format!("{b:02x}")).collect::>().join(":") +} + +/// Walk raw DHCP options looking for option 93 (Client System Architecture) +/// and return the first 2-byte big-endian value. This bypasses dhcproto's +/// typed decoding because some firmwares emit values outside the IANA table +/// that the typed decoder may drop. +fn extract_raw_arch(packet: &[u8]) -> Option { + // DHCPv4 fixed header is 240 bytes including the 4-byte magic cookie. + // Options start at offset 240. + let opts = packet.get(240..)?; + let mut i = 0; + while i < opts.len() { + let code = opts[i]; + if code == 0xff { return None; } // END + if code == 0x00 { i += 1; continue; } // PAD + i += 1; + if i >= opts.len() { return None; } + let len = opts[i] as usize; + i += 1; + if code == 93 && len >= 2 && i + 2 <= opts.len() { + return Some(u16::from_be_bytes([opts[i], opts[i + 1]])); + } + i += len; + } + None +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn extracts_arch_from_raw_options() { + // Minimal BOOTP header + magic cookie + option 93 (arch)=0x0007 + END. + let mut pkt = vec![0u8; 240]; + pkt[236..240].copy_from_slice(&[99, 130, 83, 99]); // magic cookie + pkt.extend_from_slice(&[53, 1, 1]); // option 53 DHCPDISCOVER + pkt.extend_from_slice(&[93, 2, 0x00, 0x07]); + pkt.push(0xff); + assert_eq!(extract_raw_arch(&pkt), Some(0x0007)); + } +} diff --git a/crates/http-api/Cargo.toml b/crates/http-api/Cargo.toml new file mode 100644 index 0000000..5c4f1b8 --- /dev/null +++ b/crates/http-api/Cargo.toml @@ -0,0 +1,40 @@ +[package] +name = "pxeforge-http-api" +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +description = "HTTP server: ISO uploads, iPXE script generation, ISO streaming" + +[lints] +workspace = true + +[dependencies] +pxeforge-core.workspace = true +pxeforge-iso-store.workspace = true +pxeforge-ipxe-assets.workspace = true +pxeforge-webui.workspace = true +tokio.workspace = true +tokio-util.workspace = true +tokio-stream.workspace = true +time.workspace = true +axum.workspace = true +tower.workspace = true +tower-http.workspace = true +hyper.workspace = true +serde.workspace = true +serde_json.workspace = true +tracing.workspace = true +thiserror.workspace = true +anyhow.workspace = true +bytes.workspace = true +futures.workspace = true +mime.workspace = true +mime_guess.workspace = true + +[dev-dependencies] +tokio = { workspace = true, features = ["macros", "rt", "rt-multi-thread", "time"] } +tower = { workspace = true } +tempfile = "3.12" +serde_json = { workspace = true } +time = { workspace = true } diff --git a/crates/http-api/src/app.rs b/crates/http-api/src/app.rs new file mode 100644 index 0000000..f91ab23 --- /dev/null +++ b/crates/http-api/src/app.rs @@ -0,0 +1,680 @@ +//! Axum router, handlers, and API endpoints. +//! +//! Route groups: +//! +//! | Group | Purpose | +//! |------------------|-------------------------------------------------------| +//! | `/` | Web UI (served from `pxeforge-webui`) | +//! | `/boot.ipxe` | Top-level iPXE menu | +//! | `/boot/_*.ipxe` | Submenu scripts (hierarchy: linux, windows, tools, …) | +//! | `/boot/.ipxe`| Per-entry boot script | +//! | `/ipxe/` | Bundled iPXE binaries + wimboot + memtest | +//! | `/iso/.iso` | Raw ISO with Range support | +//! | `/iso//*` | Files inside the ISO (for wimboot & kernel/initrd) | +//! | `/api/*` | JSON/HTML API for the web UI | + +use crate::ipxe_script::{ + render_entry, render_family_menu, render_gate_entry, render_local_hdd, + render_menu, render_nic_info, render_shell, render_tools_menu, render_util, +}; +use crate::iso_fs; +use crate::log_stream; +use crate::state::AppState; +use crate::terminal; +use axum::{ + body::Body, + extract::{DefaultBodyLimit, Multipart, Path as AxumPath, Query, State}, + http::{header, HeaderMap, HeaderValue, StatusCode}, + response::{IntoResponse, Response}, + routing::{delete, get, post}, + Json, Router, +}; +use pxeforge_core::{ClientEvent, Settings}; +use pxeforge_ipxe_assets::asset_bytes; +use pxeforge_iso_store::{IsoMeta, NfsAddRequest}; +use serde::Deserialize; +use serde_json::json; +use std::time::Duration; +use tokio::io::{AsyncReadExt, AsyncSeekExt}; +use tower_http::trace::TraceLayer; + +pub fn build_router(state: AppState) -> Router { + Router::new() + // Web UI (fully offline — no CDN, no external fonts/images). + .route("/", get(index)) + .route("/assets/app.js", get(ui_js)) + .route("/assets/app.css", get(ui_css)) + .route("/assets/logo.svg", get(ui_logo)) + // iPXE script endpoints. + .route("/boot.ipxe", get(boot_top_menu)) + .route("/boot/:filename", get(boot_sub)) + // Bundled binaries and raw ISO access. + .route("/ipxe/:name", get(ipxe_binary)) + .route("/iso/:filename", get(iso_raw)) + .route("/iso/:id/*path", get(iso_file)) + // Container health/readiness probes. `/healthz` is always 200 OK + // while the HTTP task is alive. `/readyz` additionally requires at + // least one bundled iPXE binary (without one, no client can PXE). + .route("/healthz", get(healthz)) + .route("/readyz", get(readyz)) + // JSON API. + .route("/api/isos", get(api_list_isos).post(api_upload_iso)) + .route("/api/isos/:id", delete(api_delete_iso)) + .route("/api/clients", get(api_list_clients)) + .route("/api/status", get(api_status)) + .route("/api/settings", get(api_get_settings).put(api_put_settings)) + .route("/api/gate", get(api_list_gates)) + .route("/api/gate/join", get(api_gate_join)) + .route("/api/gate/poll/:gate_id", get(api_gate_poll)) + .route("/api/gate/assign", post(api_gate_assign)) + .route("/api/gate/:gate_id", delete(api_gate_release)) + // Phase 4: NFS share manager. + .route("/api/nfs", get(api_nfs_list).post(api_nfs_add)) + .route("/api/nfs/:id", delete(api_nfs_remove)) + .route("/api/nfs/:id/scan", post(api_nfs_scan)) + // Phase 4: Network info (read-only) + DNS edit. + .route("/api/network", get(api_network).put(api_network_put)) + // Phase 4: live-log stream + recent buffer for the Terminal tab. + .route("/api/log/stream", get(log_stream::stream)) + .route("/api/log/recent", get(log_stream::recent)) + .route("/api/log/clear", post(log_stream::clear)) + // Phase 4: operator terminal commands (whitelisted). + .route("/api/terminal", post(terminal::run_command)) + .layer(TraceLayer::new_for_http()) + // 16 GiB upload cap — ISOs are big; chunks stream so this isn't memory use. + .layer(DefaultBodyLimit::max(16 * 1024 * 1024 * 1024)) + .with_state(state) +} + +// ─── UI ──────────────────────────────────────────────────────────────────── + +async fn index(State(state): State) -> Response { + let html = pxeforge_webui::index_html(&state.public_base_url); + ([(header::CONTENT_TYPE, HeaderValue::from_static("text/html; charset=utf-8"))], html) + .into_response() +} + +async fn ui_js() -> Response { + ( + [(header::CONTENT_TYPE, HeaderValue::from_static("application/javascript"))], + pxeforge_webui::app_js(), + ).into_response() +} + +async fn ui_css() -> Response { + ( + [(header::CONTENT_TYPE, HeaderValue::from_static("text/css"))], + pxeforge_webui::app_css(), + ).into_response() +} + +async fn ui_logo() -> Response { + ( + [(header::CONTENT_TYPE, HeaderValue::from_static("image/svg+xml"))], + pxeforge_webui::logo_svg(), + ).into_response() +} + +// ─── iPXE scripts ────────────────────────────────────────────────────────── + +fn text_plain(body: String) -> Response { + ([(header::CONTENT_TYPE, HeaderValue::from_static("text/plain; charset=utf-8"))], body) + .into_response() +} + +async fn boot_top_menu(State(state): State) -> Response { + let isos = state.iso_store.list(); + let settings = state.settings.snapshot(); + text_plain(render_menu(&isos, &settings, &state.public_base_url)) +} + +async fn boot_sub( + State(state): State, + AxumPath(filename): AxumPath, +) -> Response { + // `/boot/.ipxe` where `` is either one of our reserved + // submenu names (prefixed `_`) or a boot entry id. + let name = filename.strip_suffix(".ipxe").unwrap_or(&filename); + let isos = state.iso_store.list(); + let settings = state.settings.snapshot(); + let base = &state.public_base_url; + let script = match name { + "_local" => render_local_hdd(base), + "_linux_menu" => render_family_menu(&isos, base, false), + "_windows_menu" => render_family_menu(&isos, base, true), + "_tools_menu" => render_tools_menu(base), + "_util" => render_util(base), + "_shell" => render_shell(base), + "_nic" => render_nic_info(base), + "_gate" => render_gate_entry(base), + other => { + for iso in &isos { + for entry in &iso.boot_entries { + if entry.id == other { + return text_plain(render_entry(entry, &settings, base)); + } + } + } + return (StatusCode::NOT_FOUND, "no such boot entry").into_response(); + } + }; + text_plain(script) +} + +// ─── bundled iPXE binaries (memtest lives here too) ─────────────────────── + +async fn ipxe_binary(AxumPath(name): AxumPath) -> Response { + if name.contains('/') || name.contains('\\') { + return (StatusCode::BAD_REQUEST, "invalid name").into_response(); + } + let Some(bytes) = asset_bytes(&name) else { + return (StatusCode::NOT_FOUND, "no such ipxe asset").into_response(); + }; + ( + [ + (header::CONTENT_TYPE, HeaderValue::from_static("application/octet-stream")), + (header::CONTENT_LENGTH, HeaderValue::from(bytes.len())), + ], + bytes, + ).into_response() +} + +// ─── ISO streaming (raw + in-ISO) ───────────────────────────────────────── + +async fn iso_raw( + State(state): State, + AxumPath(filename): AxumPath, + headers: HeaderMap, +) -> Response { + let id = filename.strip_suffix(".iso").unwrap_or(&filename); + let Some(path) = state.iso_store.iso_path_for(id) else { + return (StatusCode::NOT_FOUND, "no such iso").into_response(); + }; + match stream_file_range(&path, headers.get(header::RANGE)).await { + Ok(r) => r, + Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, format!("{e}")).into_response(), + } +} + +async fn iso_file( + State(state): State, + AxumPath((id, path)): AxumPath<(String, String)>, +) -> Response { + let Some(iso_path) = state.iso_store.iso_path_for(&id) else { + return (StatusCode::NOT_FOUND, "no such iso").into_response(); + }; + let p = iso_path.clone(); + let in_path = format!("/{}", path); + let loc = tokio::task::spawn_blocking(move || iso_fs::lookup(&p, &in_path)) + .await.ok().flatten(); + let Some(loc) = loc else { + return (StatusCode::NOT_FOUND, "not found inside iso").into_response(); + }; + match stream_byte_range(&iso_path, loc.offset, loc.length).await { + Ok(r) => r, + Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, format!("{e}")).into_response(), + } +} + +async fn stream_file_range( + path: &std::path::Path, + range: Option<&HeaderValue>, +) -> anyhow::Result { + let meta = tokio::fs::metadata(path).await?; + let total = meta.len(); + let (start, end, partial) = parse_range(range, total); + let len = end - start + 1; + let mut file = tokio::fs::File::open(path).await?; + file.seek(std::io::SeekFrom::Start(start)).await?; + let reader = file.take(len); + let stream = tokio_util::io::ReaderStream::new(reader); + let body = Body::from_stream(stream); + let status = if partial { StatusCode::PARTIAL_CONTENT } else { StatusCode::OK }; + let mut builder = Response::builder() + .status(status) + .header(header::CONTENT_TYPE, "application/octet-stream") + .header(header::ACCEPT_RANGES, "bytes") + .header(header::CONTENT_LENGTH, len); + if partial { + builder = builder.header(header::CONTENT_RANGE, format!("bytes {start}-{end}/{total}")); + } + Ok(builder.body(body).unwrap()) +} + +async fn stream_byte_range( + path: &std::path::Path, + offset: u64, + length: u64, +) -> anyhow::Result { + let mut file = tokio::fs::File::open(path).await?; + file.seek(std::io::SeekFrom::Start(offset)).await?; + let reader = file.take(length); + let stream = tokio_util::io::ReaderStream::new(reader); + let body = Body::from_stream(stream); + Ok(Response::builder() + .status(StatusCode::OK) + .header(header::CONTENT_TYPE, "application/octet-stream") + .header(header::CONTENT_LENGTH, length) + .body(body) + .unwrap()) +} + +fn parse_range(h: Option<&HeaderValue>, total: u64) -> (u64, u64, bool) { + let Some(h) = h else { return (0, total.saturating_sub(1), false); }; + let Ok(s) = h.to_str() else { return (0, total.saturating_sub(1), false); }; + let Some(spec) = s.strip_prefix("bytes=") else { return (0, total.saturating_sub(1), false); }; + let spec = spec.split(',').next().unwrap_or("").trim(); + if let Some(suffix) = spec.strip_prefix('-') { + if let Ok(n) = suffix.parse::() { + let n = n.min(total); + return (total.saturating_sub(n), total.saturating_sub(1), true); + } + } + let mut parts = spec.splitn(2, '-'); + let start = parts.next().and_then(|s| s.parse::().ok()).unwrap_or(0); + let end = parts.next().and_then(|s| s.parse::().ok()).unwrap_or(total.saturating_sub(1)); + (start, end.min(total.saturating_sub(1)), true) +} + +// ─── ISO upload / list / delete ─────────────────────────────────────────── + +async fn api_list_isos(State(state): State) -> Json> { + Json(state.iso_store.list()) +} + +async fn api_delete_iso( + State(state): State, + AxumPath(id): AxumPath, +) -> StatusCode { + match state.iso_store.delete(&id).await { + Ok(()) => StatusCode::NO_CONTENT, + Err(_) => StatusCode::INTERNAL_SERVER_ERROR, + } +} + +async fn api_upload_iso( + State(state): State, + mut multipart: Multipart, +) -> Response { + while let Ok(Some(mut field)) = multipart.next_field().await { + if field.name() != Some("file") { continue; } + let filename = field.file_name().unwrap_or("uploaded.iso").to_string(); + if !filename.to_ascii_lowercase().ends_with(".iso") { + return (StatusCode::BAD_REQUEST, "only .iso uploads accepted").into_response(); + } + let mut handle = match state.iso_store.begin_upload(&filename).await { + Ok(h) => h, + Err(e) => return (StatusCode::CONFLICT, format!("{e}")).into_response(), + }; + while let Ok(Some(chunk)) = field.chunk().await { + if let Err(e) = handle.write_chunk(&chunk).await { + let _ = handle.abort().await; + return (StatusCode::INTERNAL_SERVER_ERROR, format!("{e}")).into_response(); + } + } + let meta = match handle.finish(&state.iso_store).await { + Ok(m) => m, + Err(e) => return (StatusCode::INTERNAL_SERVER_ERROR, format!("{e}")).into_response(), + }; + return (StatusCode::CREATED, Json(meta)).into_response(); + } + (StatusCode::BAD_REQUEST, "no 'file' part").into_response() +} + +// ─── health / readiness ─────────────────────────────────────────────────── + +async fn healthz() -> Response { + // Simple liveness — HTTP task is responsive. Does not touch storage or + // other subsystems so we never fail for downstream reasons. + ([(header::CONTENT_TYPE, HeaderValue::from_static("text/plain"))], "ok\n").into_response() +} + +async fn readyz(State(state): State) -> Response { + // Readiness — can we actually serve clients? + // 1. At least one iPXE binary must be bundled (without one, TFTP 404s + // and no client boots). + // 2. The ISO directory must exist and be readable. + let assets = pxeforge_ipxe_assets::list_assets(); + let mut problems: Vec<&str> = Vec::new(); + if assets.is_empty() { + problems.push("no iPXE binaries bundled (run scripts/fetch-ipxe.sh before building)"); + } + let iso_dir_ok = state.iso_store.list_ok(); + if !iso_dir_ok { + problems.push("iso directory not readable"); + } + if problems.is_empty() { + ([(header::CONTENT_TYPE, HeaderValue::from_static("text/plain"))], "ready\n").into_response() + } else { + let body = format!("not ready:\n- {}\n", problems.join("\n- ")); + (StatusCode::SERVICE_UNAVAILABLE, body).into_response() + } +} + +// ─── clients + status + settings ────────────────────────────────────────── + +async fn api_list_clients(State(state): State) -> Json { + Json(json!({ "clients": state.clients.list() })) +} + +async fn api_status(State(state): State) -> Json { + let smb = state.smb.as_ref().map(|s| s.snapshot()); + let nfs = state.nfs.list(); + let nfs_active = nfs.iter().filter(|m| m.mounted).count(); + let isos = state.iso_store.list(); + let gates = state.gates.list(); + // Phase 4: dashboard tracks "imaging" as gates with an assignment + // already issued — they're the ones actively chaining a boot script. + let imaging = gates.iter().filter(|g| g.assigned_target.is_some()).count(); + let waiting = gates.len() - imaging; + let now = time::OffsetDateTime::now_utc(); + let uptime_secs = (now - state.started_at).whole_seconds().max(0); + Json(json!({ + "version": env!("CARGO_PKG_VERSION"), + "public_base_url": state.public_base_url, + "iso_count": isos.len(), + "client_count": state.clients.list().len(), + "gate_count": gates.len(), + "imaging_count": imaging, + "waiting_count": waiting, + "ipxe_assets": pxeforge_ipxe_assets::list_assets(), + "settings": state.settings.snapshot(), + "smb": smb, + "nfs_count": nfs.len(), + "nfs_active": nfs_active, + "uptime_secs": uptime_secs, + "started_at": state.started_at, + "nic_name": state.nic_name, + "subnet_mask": state.subnet_mask, + "gateway": state.gateway, + })) +} + +async fn api_get_settings(State(state): State) -> Json { + Json(state.settings.snapshot()) +} + +async fn api_put_settings( + State(state): State, + Json(mut new): Json, +) -> Response { + // Guardrail: Windows boot requires the wimboot shim to be bundled. + // Without it, clients chain a non-existent /ipxe/wimboot and stall. + if new.windows_enabled { + let assets = pxeforge_ipxe_assets::list_assets(); + if !assets.iter().any(|n| n == "wimboot") { + return ( + StatusCode::BAD_REQUEST, + "cannot enable Windows: 'wimboot' binary is not bundled. \ + Place a signed wimboot build at assets/ipxe/wimboot and rebuild \ + the container. See docs/architecture.md for details.", + ).into_response(); + } + } + new.smb_host_override = new.smb_host_override.trim().to_string(); + + // Detect whether this PUT changes the Windows toggle, so we only + // restart smbd when it actually flipped. + let was_enabled = state.settings.snapshot().windows_enabled; + let want_enabled = new.windows_enabled; + state.settings.replace(new); + + if let Some(smb) = &state.smb { + match (was_enabled, want_enabled) { + (false, true) => { let _ = smb.start(); } + (true, false) => { smb.stop(); } + (true, true) => { let _ = smb.reconcile(); } + (false, false) => {} + } + } + StatusCode::NO_CONTENT.into_response() +} + +// ─── Gated Deployment API ───────────────────────────────────────────────── + +async fn api_list_gates(State(state): State) -> Json { + Json(json!({ + "gates": state.gates.list(), + "count": state.gates.list().len(), + })) +} + +#[derive(Debug, Deserialize)] +struct GateJoinParams { + /// Client MAC from iPXE's `${mac}` variable. iPXE substitutes before + /// the HTTP request so we receive a plain colon-separated MAC. + mac: Option, +} + +/// Called by iPXE via `chain --replace`. We respond with a tiny iPXE +/// script that hard-loops on `/api/gate/poll/`. iPXE keeps fetching +/// until poll returns an actual boot script. +async fn api_gate_join( + State(state): State, + Query(p): Query, + headers: HeaderMap, +) -> Response { + let mac = p.mac.unwrap_or_else(|| "unknown".to_string()); + let ip = headers + .get("x-forwarded-for") + .and_then(|h| h.to_str().ok()) + .and_then(|s| s.split(',').next()) + .and_then(|s| s.trim().parse().ok()); + + let gate = state.gates.join(&mac, ip, None); + state.clients.record( + &mac, ip, None, + ClientEvent::HttpScriptFetch { target: "gate-join".into() }, + ); + + let base = &state.public_base_url; + // ASCII only - some iPXE builds on firmware consoles mangle non-ASCII. + let script = format!( + "#!ipxe\n\ + echo\n\ + echo ==========================================\n\ + echo Gated Deployment - Gate Position {}\n\ + echo Waiting for operator to assign an image\n\ + echo (Ctrl-B returns to the iPXE shell)\n\ + echo ==========================================\n\ + chain {base}/api/gate/poll/{}\n", + gate.position, gate.id + ); + text_plain(script) +} + +/// Long-poll endpoint. Waits up to 25s for an assignment; if none, returns +/// a script that loops back to itself. 25s keeps us well inside typical +/// HTTP idle timeouts for iPXE and intermediaries. +async fn api_gate_poll( + State(state): State, + AxumPath(gate_id): AxumPath, +) -> Response { + let Some(notify) = state.gates.notifier(&gate_id) else { + // Gate was released; send client back to the main menu. + let base = &state.public_base_url; + return text_plain(format!("#!ipxe\nchain {base}/boot.ipxe\n")); + }; + + // Wait for an assignment or timeout. + let _ = tokio::time::timeout(Duration::from_secs(25), notify.notified()).await; + + let snap = state.gates.touch(&gate_id); + let base = &state.public_base_url; + match snap { + // Bind `target` directly so we can't observe an Option::None between + // the guard and the unwrap (the old code had a race with concurrent + // `release`). We also do NOT release the gate here — the web UI + // operator releases it explicitly, which keeps a record of "this + // machine was assigned image X" visible until the client is known + // to have started. Clients that retry on transient network errors + // still get a valid boot script instead of falling back to the + // menu. + Some(g) if g.assigned_target.is_some() => { + let target = g.assigned_target.clone().unwrap_or_default(); + tracing::info!( + target: "pxeforge::gate", + gate_id=%gate_id, mac=%g.mac, target=%target, + "gate assignment delivered" + ); + text_plain(format!( + "#!ipxe\n\ + echo Gate assignment received: {target}\n\ + chain {base}/boot/{target}.ipxe || chain {base}/api/gate/poll/{gate_id}\n" + )) + } + Some(g) => { + // No assignment yet - loop and re-poll. Repaint position so the + // UI count stays accurate if other gates were released meanwhile. + text_plain(format!( + "#!ipxe\n\ + echo Gate Position {} - still waiting\n\ + chain {base}/api/gate/poll/{gate_id}\n", + g.position + )) + } + None => text_plain(format!("#!ipxe\nchain {base}/boot.ipxe\n")), + } +} + +#[derive(Debug, Deserialize)] +struct GateAssignBody { + /// Boot entry id (from `BootEntry::id`). Same one used in + /// `/boot/.ipxe`. + target: String, + /// Gate ids to assign. Empty = assign to all currently queued gates. + gate_ids: Vec, +} + +async fn api_gate_assign( + State(state): State, + Json(body): Json, +) -> Json { + let ids = if body.gate_ids.is_empty() { + state.gates.list().into_iter().map(|g| g.id).collect::>() + } else { + body.gate_ids + }; + // Guard: target must exist as a BootEntry id. + let found = state.iso_store.list().into_iter().any(|i| { + i.boot_entries.iter().any(|e| e.id == body.target) + }); + if !found { + return Json(json!({ "ok": false, "error": "unknown target" })); + } + let n = state.gates.assign(&ids, &body.target); + Json(json!({ "ok": true, "assigned": n, "target": body.target })) +} + +async fn api_gate_release( + State(state): State, + AxumPath(gate_id): AxumPath, +) -> StatusCode { + match state.gates.release(&gate_id) { + Some(_) => StatusCode::NO_CONTENT, + None => StatusCode::NOT_FOUND, + } +} + +// ─── NFS share API ───────────────────────────────────────────────────────── + +async fn api_nfs_list(State(state): State) -> Json { + Json(json!({ "mounts": state.nfs.list() })) +} + +async fn api_nfs_add( + State(state): State, + Json(req): Json, +) -> Response { + match state.nfs.add(req).await { + Ok(m) => (StatusCode::CREATED, Json(m)).into_response(), + // Anything from the manager surfaces as a user-fixable validation + // error — bad host, kernel without NFS support, missing + // `mount.nfs`, dead server. We pass the message through verbatim + // so the UI can show it to the operator. + Err(e) => (StatusCode::BAD_REQUEST, format!("{e}")).into_response(), + } +} + +async fn api_nfs_remove( + State(state): State, + AxumPath(id): AxumPath, +) -> Response { + match state.nfs.remove(&id).await { + Ok(()) => StatusCode::NO_CONTENT.into_response(), + Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, format!("{e}")).into_response(), + } +} + +async fn api_nfs_scan( + State(state): State, + AxumPath(id): AxumPath, +) -> Response { + match state.nfs.rescan(&id).await { + Ok(n) => Json(json!({ "ok": true, "iso_count": n })).into_response(), + Err(e) => (StatusCode::BAD_REQUEST, format!("{e}")).into_response(), + } +} + +// ─── Network info API ────────────────────────────────────────────────────── + +async fn api_network(State(state): State) -> Json { + Json(json!({ + "server_ip": state.public_base_url + .strip_prefix("http://") + .unwrap_or(&state.public_base_url), + "nic_name": state.nic_name, + "subnet_mask": state.subnet_mask, + "gateway": state.gateway, + "dns_server": state.settings.snapshot().dns_server, + "public_base_url": state.public_base_url, + })) +} + +#[derive(Debug, Deserialize)] +struct NetworkPut { + /// Operators can set or clear an informational DNS hint. Server IP / + /// NIC / mask / gateway are auto-detected and not editable from the + /// UI — changing them in the wrong direction would silently break + /// PXE for every client. + dns_server: String, +} + +async fn api_network_put( + State(state): State, + Json(body): Json, +) -> StatusCode { + let mut s = state.settings.snapshot(); + s.dns_server = body.dns_server.trim().to_string(); + state.settings.replace(s); + StatusCode::NO_CONTENT +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn range_full() { + let (s, e, p) = parse_range(None, 1000); + assert_eq!((s, e, p), (0, 999, false)); + } + #[test] + fn range_open_ended() { + let h = HeaderValue::from_static("bytes=500-"); + let (s, e, p) = parse_range(Some(&h), 1000); + assert_eq!((s, e, p), (500, 999, true)); + } + #[test] + fn range_suffix() { + let h = HeaderValue::from_static("bytes=-100"); + let (s, e, p) = parse_range(Some(&h), 1000); + assert_eq!((s, e, p), (900, 999, true)); + } + #[test] + fn range_explicit() { + let h = HeaderValue::from_static("bytes=10-99"); + let (s, e, p) = parse_range(Some(&h), 1000); + assert_eq!((s, e, p), (10, 99, true)); + } +} diff --git a/crates/http-api/src/ipxe_script.rs b/crates/http-api/src/ipxe_script.rs new file mode 100644 index 0000000..29286ca --- /dev/null +++ b/crates/http-api/src/ipxe_script.rs @@ -0,0 +1,327 @@ +//! iPXE script generator. +//! +//! ## Menu hierarchy (per Phase 2 spec) +//! +//! ```text +//! Top level: +//! Default +//! > Boot from Local HDD +//! Installers +//! > Linux Installers -> submenu of Linux ISOs +//! > Windows Installers -> submenu of Windows ISOs (gated by Settings::windows_enabled) +//! Tools +//! > Utilities -> memtest, etc. (embedded assets only) +//! > PXEForge Shell -> drop to iPXE shell with branded prompt +//! > Network Card Info -> ifstat / config / route dump +//! Gated Deployment -> join the gate queue +//! ``` +//! +//! ## iPXE is entirely backend — users do not see or write iPXE +//! +//! All user-facing knobs live in `Settings`. Script generation translates +//! those knobs into iPXE primitives (chain, menu, item, choose, etc.). +//! There is intentionally no UI path to upload a custom `.ipxe` script. + +use pxeforge_core::{Settings, TimeoutAction}; +use pxeforge_iso_store::{BootEntry, BootKind, IsoMeta}; +use pxeforge_iso_store::introspect::DistroFamily; +use std::fmt::Write as _; + +/// Top-level PXEForge boot menu. Serialized identically for BIOS and UEFI +/// clients because iPXE normalises the menu primitives across firmwares. +#[must_use] +pub fn render_menu(isos: &[IsoMeta], settings: &Settings, base_url: &str) -> String { + let mut s = String::new(); + let base = base_url.trim_end_matches('/'); + let timeout_ms = settings.boot_menu_timeout_secs.saturating_mul(1000); + let default_item = match settings.timeout_action { + TimeoutAction::LocalHdd => "local", + TimeoutAction::GatedDeployment => "gate", + // Stay -> iPXE's `--timeout 0` is "no timeout". Pick any default + // label; the client waits for keypress. + TimeoutAction::Stay => "local", + }; + + let _ = writeln!(s, "#!ipxe"); + let _ = writeln!(s, "# PXEForge top-level menu - auto-generated, do not edit"); + let _ = writeln!(s, "set base-url {base}"); + let _ = writeln!(s, "set esc:hex 1b"); + let _ = writeln!(s, "set cls ${{esc:string}}[2J"); + let _ = writeln!(s, ":menu"); + let _ = writeln!(s, "menu PXEForge - network boot menu"); + let _ = writeln!(s, "item --gap -- ------------------------- Default -------------------------"); + let _ = writeln!(s, "item local Boot from Local HDD"); + let _ = writeln!(s, "item --gap -- ----------------------- Installers -----------------------"); + if has_family(isos, is_linux_family) { + let _ = writeln!(s, "item linux Linux Installers >"); + } else { + let _ = writeln!(s, "item --gap -- (no Linux ISOs uploaded)"); + } + if settings.windows_enabled && has_family(isos, is_windows_family) { + let _ = writeln!(s, "item windows Windows Installers >"); + } else if settings.windows_enabled { + let _ = writeln!(s, "item --gap -- (no Windows ISOs uploaded)"); + } else { + let _ = writeln!(s, "item --gap -- (Windows support disabled in Settings)"); + } + let _ = writeln!(s, "item --gap -- -------------------------- Tools --------------------------"); + let _ = writeln!(s, "item tools Tools >"); + let _ = writeln!(s, "item --gap -- ---------------------- Gated Deployment ---------------------"); + let _ = writeln!(s, "item gate Gated Deployment (join queue)"); + let _ = writeln!(s, "item --gap"); + let _ = writeln!(s, "item --key x exit Exit iPXE"); + + if matches!(settings.timeout_action, TimeoutAction::Stay) { + let _ = writeln!(s, "choose --default {default_item} target || goto menu"); + } else { + let _ = writeln!(s, "choose --default {default_item} --timeout {timeout_ms} target || goto menu"); + } + + // iPXE's `||` is strict about what follows. Each test uses `goto menu` + // as the fallthrough target so the parser never sees a bare `||` with + // trailing whitespace — some iPXE builds reject that. + let _ = writeln!(s, "iseq ${{target}} local && chain {base}/boot/_local.ipxe || goto menu"); + let _ = writeln!(s, "iseq ${{target}} linux && chain {base}/boot/_linux_menu.ipxe || goto menu"); + let _ = writeln!(s, "iseq ${{target}} windows && chain {base}/boot/_windows_menu.ipxe || goto menu"); + let _ = writeln!(s, "iseq ${{target}} tools && chain {base}/boot/_tools_menu.ipxe || goto menu"); + let _ = writeln!(s, "iseq ${{target}} gate && chain {base}/boot/_gate.ipxe || goto menu"); + let _ = writeln!(s, "iseq ${{target}} exit && exit || goto menu"); + let _ = writeln!(s, "goto menu"); + s +} + +/// Per-family submenu (Linux or Windows). Each item shows the ISO size +/// in MiB, iVentoy-style (`[ 4376 MB] ubuntu-22.04-desktop-amd64`). +#[must_use] +pub fn render_family_menu(isos: &[IsoMeta], base_url: &str, is_windows: bool) -> String { + let base = base_url.trim_end_matches('/'); + let title = if is_windows { "Windows Installers" } else { "Linux Installers" }; + let label = if is_windows { "windows" } else { "linux" }; + let mut s = String::new(); + let _ = writeln!(s, "#!ipxe"); + let _ = writeln!(s, "set base-url {base}"); + let _ = writeln!(s, ":menu"); + let _ = writeln!(s, "menu PXEForge - {title}"); + let filter: fn(DistroFamily) -> bool = + if is_windows { is_windows_family } else { is_linux_family }; + let mut count = 0; + for iso in isos { + if !filter(iso.introspection.family) { continue; } + for entry in &iso.boot_entries { + let size_label = fmt_size_mib(iso.size_bytes); + let key = hotkey_for_index(count); + let _ = writeln!( + s, "item {}{} [{:>6}] {}", + key, + entry.id, + size_label, + escape_label(&entry.title), + ); + count += 1; + } + } + if count == 0 { + let _ = writeln!(s, "item --gap -- (no {label} images uploaded yet)"); + } + let _ = writeln!(s, "item --gap"); + let _ = writeln!(s, "item --key b back < Back to main menu"); + let _ = writeln!(s, "choose target || goto menu"); + let _ = writeln!(s, "iseq ${{target}} back && chain {base}/boot.ipxe || goto menu"); + let _ = writeln!(s, "chain {base}/boot/${{target}}.ipxe || goto menu"); + s +} + +/// Format a byte count as `NNNN MB` (iVentoy-style — MB not MiB, to match +/// operator expectations from the original tool). +fn fmt_size_mib(bytes: u64) -> String { + let mib = bytes / (1024 * 1024); + format!("{} MB", mib) +} + +/// Assign `--key N ` hotkeys 1..9, then nothing for positions >=9. +/// iPXE's menu needs the --key prefix as a separate token before the id. +fn hotkey_for_index(i: usize) -> String { + if i < 9 { + format!("--key {} ", i + 1) + } else { + String::new() + } +} + +/// Tools submenu — Utilities, Shell, NIC Info, Reboot, Exit to firmware. +#[must_use] +pub fn render_tools_menu(base_url: &str) -> String { + let base = base_url.trim_end_matches('/'); + let mut s = String::new(); + let _ = writeln!(s, "#!ipxe"); + let _ = writeln!(s, "set base-url {base}"); + let _ = writeln!(s, ":menu"); + let _ = writeln!(s, "menu PXEForge - Tools"); + let _ = writeln!(s, "item --key u util Utilities (memtest, ...)"); + let _ = writeln!(s, "item --key s shell PXEForge Shell"); + let _ = writeln!(s, "item --key n nic Network Card Info"); + let _ = writeln!(s, "item --gap"); + let _ = writeln!(s, "item --key r reboot Reboot Computer"); + let _ = writeln!(s, "item --key e firmware Exit and continue BIOS boot"); + let _ = writeln!(s, "item --gap"); + let _ = writeln!(s, "item --key b back < Back to main menu"); + let _ = writeln!(s, "choose target || goto menu"); + let _ = writeln!(s, "iseq ${{target}} util && chain {base}/boot/_util.ipxe || goto menu"); + let _ = writeln!(s, "iseq ${{target}} shell && chain {base}/boot/_shell.ipxe || goto menu"); + let _ = writeln!(s, "iseq ${{target}} nic && chain {base}/boot/_nic.ipxe || goto menu"); + let _ = writeln!(s, "iseq ${{target}} reboot && reboot || goto menu"); + let _ = writeln!(s, "iseq ${{target}} firmware && exit 0 || goto menu"); + let _ = writeln!(s, "iseq ${{target}} back && chain {base}/boot.ipxe || goto menu"); + let _ = writeln!(s, "goto menu"); + s +} + +/// "Boot from Local HDD". On BIOS, we sanboot the first local drive; on +/// UEFI we `exit` so the firmware moves to the next boot entry (normally +/// the internal disk). +#[must_use] +pub fn render_local_hdd(base_url: &str) -> String { + let base = base_url.trim_end_matches('/'); + let mut s = String::new(); + let _ = writeln!(s, "#!ipxe"); + let _ = writeln!(s, "# Boot from Local HDD - platform-sensitive"); + let _ = writeln!(s, "iseq ${{platform}} pcbios && sanboot --no-describe --drive 0x80 || "); + let _ = writeln!(s, "# UEFI path: fall through to the firmware's next boot entry"); + let _ = writeln!(s, "exit 0"); + let _ = writeln!(s, "# If the above exit returns, loop back to the main menu"); + let _ = writeln!(s, "chain {base}/boot.ipxe"); + s +} + +/// Utilities submenu. For Phase 2 we bundle memtest86+ as an optional +/// asset (if absent, the item is listed but errors gracefully). No third- +/// party tools are fetched at runtime. +#[must_use] +pub fn render_util(base_url: &str) -> String { + let base = base_url.trim_end_matches('/'); + let mut s = String::new(); + let _ = writeln!(s, "#!ipxe"); + let _ = writeln!(s, ":menu"); + let _ = writeln!(s, "menu PXEForge - Utilities"); + let _ = writeln!(s, "item memtest MemTest86+ (RAM diagnostic)"); + let _ = writeln!(s, "item --gap"); + let _ = writeln!(s, "item back < Back"); + let _ = writeln!(s, "choose target || goto menu"); + let _ = writeln!(s, "iseq ${{target}} memtest && chain {base}/ipxe/memtest.bin || "); + let _ = writeln!(s, "iseq ${{target}} back && chain {base}/boot/_tools_menu.ipxe || "); + let _ = writeln!(s, "goto menu"); + s +} + +/// "PXEForge Shell" — iPXE shell, branded. +#[must_use] +pub fn render_shell(base_url: &str) -> String { + let base = base_url.trim_end_matches('/'); + let mut s = String::new(); + let _ = writeln!(s, "#!ipxe"); + let _ = writeln!(s, "echo =========================================="); + let _ = writeln!(s, "echo PXEForge Shell"); + let _ = writeln!(s, "echo 'exit' returns to the main menu"); + let _ = writeln!(s, "echo =========================================="); + let _ = writeln!(s, "shell"); + let _ = writeln!(s, "chain {base}/boot.ipxe"); + s +} + +/// "Network Card Info" — print ifstat + route + config. +#[must_use] +pub fn render_nic_info(base_url: &str) -> String { + let base = base_url.trim_end_matches('/'); + let mut s = String::new(); + let _ = writeln!(s, "#!ipxe"); + let _ = writeln!(s, "echo =========================================="); + let _ = writeln!(s, "echo Network Card Info"); + let _ = writeln!(s, "echo =========================================="); + let _ = writeln!(s, "ifstat"); + let _ = writeln!(s, "echo"); + let _ = writeln!(s, "route"); + let _ = writeln!(s, "echo"); + let _ = writeln!(s, "echo 'Press any key to return to menu'"); + let _ = writeln!(s, "prompt --timeout 30000"); + let _ = writeln!(s, "chain {base}/boot.ipxe"); + s +} + +/// Gated Deployment entry point. Joins the queue, then enters a long-poll +/// loop (iPXE repeats the chain on 3xx redirects / HTTP errors until a +/// real script comes back). +#[must_use] +pub fn render_gate_entry(base_url: &str) -> String { + let base = base_url.trim_end_matches('/'); + let mut s = String::new(); + let _ = writeln!(s, "#!ipxe"); + let _ = writeln!(s, "# Gated Deployment - join the queue and wait for operator"); + let _ = writeln!(s, "echo Joining gate queue..."); + // imgfetch writes the body to a file in iPXE's transient FS; we read + // the gate id out of the Location-style header by asking the server + // to put it in the response body as a single token. + let _ = writeln!(s, "chain --replace {base}/api/gate/join?mac=${{mac}}"); + s +} + +/// Per-entry boot script (same as Phase 1, with extra_kernel_args appended). +#[must_use] +pub fn render_entry(entry: &BootEntry, settings: &Settings, base_url: &str) -> String { + let mut s = String::new(); + let base = base_url.trim_end_matches('/'); + let _ = writeln!(s, "#!ipxe"); + let _ = writeln!(s, "set base-url {base}"); + match &entry.kind { + BootKind::LinuxKernel { kernel_url, initrd_urls, args } => { + let mut cmdline = args.cmdline.replace("${base-url}", base); + if !settings.extra_kernel_args.trim().is_empty() { + cmdline.push(' '); + cmdline.push_str(settings.extra_kernel_args.trim()); + } + let _ = writeln!(s, "kernel {base}/{kernel_url} {cmdline}"); + for u in initrd_urls { + let _ = writeln!(s, "initrd {base}/{u}"); + } + let _ = writeln!(s, "boot || goto failed"); + } + BootKind::Wimboot { wimboot_url, files } => { + let _ = writeln!(s, "kernel {base}/{wimboot_url}"); + for (tag, url) in files { + let _ = writeln!(s, "initrd --name {tag} {base}/{url} {tag}"); + } + let _ = writeln!(s, "boot || goto failed"); + } + BootKind::SanBootIso { iso_url } => { + let _ = writeln!(s, "sanboot --no-describe {base}/{iso_url} || goto failed"); + } + } + let _ = writeln!(s, ":failed"); + let _ = writeln!(s, "echo Boot failed - returning to menu in 5s"); + let _ = writeln!(s, "sleep 5"); + let _ = writeln!(s, "chain {base}/boot.ipxe"); + s +} + +fn is_linux_family(f: DistroFamily) -> bool { + matches!( + f, + DistroFamily::DebianUbuntu + | DistroFamily::RhelFedora + | DistroFamily::OpenSuse + | DistroFamily::Arch + | DistroFamily::Alpine + | DistroFamily::Unknown + ) +} + +fn is_windows_family(f: DistroFamily) -> bool { + matches!(f, DistroFamily::WindowsPe) +} + +fn has_family(isos: &[IsoMeta], pred: fn(DistroFamily) -> bool) -> bool { + isos.iter().any(|i| pred(i.introspection.family)) +} + +fn escape_label(s: &str) -> String { + s.chars().map(|c| match c { '\n' | '\r' => ' ', c => c }).collect() +} diff --git a/crates/http-api/src/iso_fs.rs b/crates/http-api/src/iso_fs.rs new file mode 100644 index 0000000..0ddaf76 --- /dev/null +++ b/crates/http-api/src/iso_fs.rs @@ -0,0 +1,112 @@ +//! Minimal read-only ISO9660 lookup. Given an uploaded ISO file and an +//! in-ISO path (e.g. `/casper/vmlinuz`), locate the file and return a +//! `(start_byte, length_bytes)` pair so the HTTP handler can stream just +//! that range from the on-disk ISO without full extraction. +//! +//! We only implement what we need: the Primary Volume Descriptor and Rock +//! Ridge / Joliet extensions are ignored. Paths are matched case-insensitive +//! against plain ISO9660 filenames (uppercase, `;1` version suffix stripped). +//! This is sufficient for the kernel/initrd and wimboot files we serve; +//! if a requested path isn't found, the handler returns 404 and the user +//! can still download the whole ISO via `/iso/.iso`. + +use std::io::{Read, Seek, SeekFrom}; +use std::path::Path; + +const SECTOR: u64 = 2048; + +#[derive(Debug, Clone)] +pub struct FileLocation { + pub offset: u64, + pub length: u64, +} + +/// Look up `in_iso_path` (leading slash optional, case-insensitive) in the +/// ISO at `iso_path`. Returns None on any parsing or IO failure. +pub fn lookup(iso_path: &Path, in_iso_path: &str) -> Option { + let mut f = std::fs::File::open(iso_path).ok()?; + let root = read_root_directory(&mut f)?; + let components: Vec<&str> = in_iso_path + .trim_start_matches('/') + .split('/') + .filter(|c| !c.is_empty()) + .collect(); + if components.is_empty() { return None; } + walk(&mut f, root.offset, root.length, &components) +} + +fn read_root_directory(f: &mut std::fs::File) -> Option { + // Primary Volume Descriptor at LBA 16. + let mut pvd = [0u8; 2048]; + f.seek(SeekFrom::Start(16 * SECTOR)).ok()?; + f.read_exact(&mut pvd).ok()?; + if pvd[0] != 0x01 || &pvd[1..6] != b"CD001" { return None; } + // Root directory record is at offset 156, length 34. + let rec = &pvd[156..156 + 34]; + let (offset, length) = parse_dir_record_ext(rec)?; + Some(FileLocation { offset: offset * SECTOR, length }) +} + +/// Walk components down the directory tree starting at `dir_offset`. +fn walk( + f: &mut std::fs::File, + dir_offset: u64, + dir_len: u64, + components: &[&str], +) -> Option { + let mut dir = vec![0u8; dir_len as usize]; + f.seek(SeekFrom::Start(dir_offset)).ok()?; + f.read_exact(&mut dir).ok()?; + + let target = components[0]; + let rest = &components[1..]; + let mut i = 0; + while i < dir.len() { + let len = dir[i] as usize; + if len == 0 { + // Padding to sector boundary. + let next = (i / SECTOR as usize + 1) * SECTOR as usize; + if next <= i { break; } + i = next; + continue; + } + if i + len > dir.len() { break; } + let rec = &dir[i..i + len]; + let name = dir_record_name(rec); + let is_dir = (rec.get(25).copied().unwrap_or(0) & 0x02) != 0; + // Skip "." (0x00) and ".." (0x01) pseudo-entries. + let is_pseudo = matches!(rec.get(32).copied(), Some(1)) && rec.get(33).copied() == Some(0x00) + || matches!(rec.get(32).copied(), Some(1)) && rec.get(33).copied() == Some(0x01); + if !is_pseudo && name.eq_ignore_ascii_case(target) { + let (child_off, child_len) = parse_dir_record_ext(rec)?; + if rest.is_empty() && !is_dir { + return Some(FileLocation { offset: child_off * SECTOR, length: child_len }); + } else if !rest.is_empty() && is_dir { + return walk(f, child_off * SECTOR, child_len, rest); + } + } + i += len; + } + None +} + +/// Extract (extent LBA, data length in bytes) from a directory record. +/// Layout per ISO9660: bytes 2..10 extent LBA (LE+BE duplicate), 10..18 +/// data length (LE+BE duplicate). We trust the little-endian copy. +fn parse_dir_record_ext(rec: &[u8]) -> Option<(u64, u64)> { + if rec.len() < 34 { return None; } + let lba = u32::from_le_bytes(rec[2..6].try_into().ok()?) as u64; + let len = u32::from_le_bytes(rec[10..14].try_into().ok()?) as u64; + Some((lba, len)) +} + +/// Extract the identifier from a directory record, stripping ISO9660's +/// `;1` version suffix. +fn dir_record_name(rec: &[u8]) -> String { + let name_len = *rec.get(32).unwrap_or(&0) as usize; + if name_len == 0 || rec.len() < 33 + name_len { return String::new(); } + let raw = &rec[33..33 + name_len]; + let s = String::from_utf8_lossy(raw).to_string(); + // Strip `;N` version suffix. + if let Some(i) = s.rfind(';') { s[..i].to_string() } else { s } +} diff --git a/crates/http-api/src/lib.rs b/crates/http-api/src/lib.rs new file mode 100644 index 0000000..063a28a --- /dev/null +++ b/crates/http-api/src/lib.rs @@ -0,0 +1,24 @@ +//! HTTP server — single axum app that serves: +//! - `/` the web UI (static assets from `pxeforge-webui`) +//! - `/api/*` JSON API for the web UI +//! - `/boot.ipxe` the generated top-level iPXE boot menu +//! - `/boot/.ipxe` per-entry iPXE scripts (one per boot target) +//! - `/ipxe/` bundled iPXE binaries (for UEFI HTTP boot) +//! - `/iso/.iso` raw ISO file (with Range support) +//! - `/iso//` files inside the ISO (for wimboot WIM fetches +//! and Linux kernel/initrd, without having to +//! re-extract on every request) +//! +//! The `/` handler uses a read-only ISO9660 shim (see `iso_fs`) +//! that lseeks into the ISO on disk — so we never keep extracted copies. +#![forbid(unsafe_code)] + +pub mod app; +pub mod ipxe_script; +pub mod iso_fs; +pub mod log_stream; +pub mod state; +pub mod terminal; + +pub use app::build_router; +pub use state::AppState; diff --git a/crates/http-api/src/log_stream.rs b/crates/http-api/src/log_stream.rs new file mode 100644 index 0000000..e1d347c --- /dev/null +++ b/crates/http-api/src/log_stream.rs @@ -0,0 +1,66 @@ +//! Server-Sent Events stream for the Terminal tab's live log pane. +//! +//! On connection we emit the recent ring buffer (so the UI doesn't open +//! to a blank pane), then forward every new line from the broadcast +//! channel. Slow clients that fall behind get a `lagged` event and +//! resume — better than dropping the connection mid-tail. + +use crate::state::AppState; +use axum::{ + extract::State, + response::sse::{Event, KeepAlive, Sse}, + Json, +}; +use futures::stream::{Stream, StreamExt}; +use pxeforge_core::LogLine; +use serde_json::json; +use std::convert::Infallible; +use std::time::Duration; +use tokio_stream::wrappers::BroadcastStream; + +/// SSE handler. Each `data:` payload is a JSON object matching `LogLine`. +pub async fn stream( + State(state): State, +) -> Sse>> { + // 1. Snapshot the recent buffer first so a fresh UI sees context. + let recent = state.log_bus.recent(); + let recent_stream = futures::stream::iter( + recent + .into_iter() + .map(|l| Ok(Event::default().data(line_json(&l)))), + ); + + // 2. Then live updates. BroadcastStream yields Result; on + // a lagged client we send a synthetic event so the UI can flag it + // rather than silently dropping data. + let rx = state.log_bus.subscribe(); + let live = BroadcastStream::new(rx).map(|res| match res { + Ok(line) => Ok(Event::default().data(line_json(&line))), + Err(tokio_stream::wrappers::errors::BroadcastStreamRecvError::Lagged(n)) => Ok(Event::default() + .event("lagged") + .data(json!({ "skipped": n }).to_string())), + }); + + Sse::new(recent_stream.chain(live)) + .keep_alive(KeepAlive::new().interval(Duration::from_secs(15))) +} + +/// Plain JSON snapshot of the recent buffer, for clients that prefer a +/// pull-based fetch over an SSE subscription. +pub async fn recent(State(state): State) -> Json { + Json(json!({ "lines": state.log_bus.recent() })) +} + +/// Drop the in-memory ring buffer. Live subscribers are unaffected (they +/// keep streaming new lines as they arrive). +pub async fn clear(State(state): State) -> Json { + state.log_bus.clear(); + state + .log_bus + .push("info", "pxeforge::terminal", "log buffer cleared by operator"); + Json(json!({ "ok": true })) +} + +fn line_json(l: &LogLine) -> String { + serde_json::to_string(l).unwrap_or_else(|_| "{}".to_string()) +} diff --git a/crates/http-api/src/state.rs b/crates/http-api/src/state.rs new file mode 100644 index 0000000..a57726b --- /dev/null +++ b/crates/http-api/src/state.rs @@ -0,0 +1,38 @@ +use pxeforge_core::{ClientRegistry, GateQueue, LogBus, SettingsStore}; +use pxeforge_iso_store::{IsoStore, NfsManager, SmbManager}; +use std::sync::Arc; +use time::OffsetDateTime; + +#[derive(Clone)] +pub struct AppState { + pub iso_store: IsoStore, + pub clients: Arc, + pub settings: Arc, + pub gates: Arc, + /// Optional SMB manager. Present when the binary was given a writable + /// `smb_dir` at startup; `None` in pure-Linux-only deployments where + /// Windows support is not wired in. Settings toggle drives start/stop. + pub smb: Option>, + /// NFS share manager. Always present (mounting is opt-in by the + /// operator from the Storage tab); `add()` requires `mount.nfs` to be + /// available in the runtime image. Surfaces errors per-mount rather + /// than failing the global state. + pub nfs: NfsManager, + /// Live log bus consumed by the Terminal tab via SSE. Operator-issued + /// terminal commands also push synthetic lines onto it so the tail + /// shows them inline. + pub log_bus: Arc, + /// Wall-clock instant the server bound — used for the uptime chip. + pub started_at: OffsetDateTime, + /// Base URL advertised to PXE clients (e.g. `http://10.0.0.5`). Used when + /// rendering iPXE scripts so every URL resolves offline. + pub public_base_url: String, + /// Name of the network interface auto-detected at startup (e.g. + /// `enp1s0`). Surfaced read-only on the Network tab. Empty if the + /// interface couldn't be identified. + pub nic_name: String, + /// Subnet mask of the public interface in dotted-quad form. + pub subnet_mask: String, + /// Default gateway IPv4 address. + pub gateway: String, +} diff --git a/crates/http-api/src/terminal.rs b/crates/http-api/src/terminal.rs new file mode 100644 index 0000000..83bf041 --- /dev/null +++ b/crates/http-api/src/terminal.rs @@ -0,0 +1,524 @@ +//! Operator terminal — typed commands over HTTP. +//! +//! The Terminal tab posts a single command line per request. We split it +//! into argv, dispatch to a whitelisted handler, and return plain-text +//! output. The handler also pushes the input line and any output onto +//! the LogBus so commands and their results show up inline in the live +//! tail (Minecraft-server-style). +//! +//! ## Why a whitelist +//! +//! Exposing a real shell would be a remote-code-execution endpoint. We +//! keep the surface tiny and read-mostly; mutations are limited to the +//! same operations the rest of the UI already exposes. + +use crate::state::AppState; +use axum::{extract::State, http::StatusCode, response::IntoResponse, Json}; +use serde::Deserialize; +use serde_json::json; +use std::fmt::Write as _; + +#[derive(Debug, Deserialize)] +pub struct CommandRequest { + /// Raw input as typed by the operator. Empty / all-whitespace is OK + /// (returns the help banner). + pub command: String, +} + +pub async fn run_command( + State(state): State, + Json(req): Json, +) -> impl IntoResponse { + let line = req.command.trim(); + if line.is_empty() { + return (StatusCode::OK, Json(json!({ "output": HELP_TEXT, "ok": true }))); + } + + // Echo the typed command into the live log so the Terminal tab shows + // operator activity in-band with server-emitted log lines. + state.log_bus.push("info", "pxeforge::terminal", format!("> {line}")); + + let argv = shell_split(line); + if argv.is_empty() { + return ( + StatusCode::OK, + Json(json!({ "output": HELP_TEXT, "ok": true })), + ); + } + + let result = dispatch(&state, &argv).await; + let (ok, output) = match result { + Ok(s) => (true, s), + Err(s) => (false, s), + }; + // Mirror command output to the log bus (truncated for noisy commands) + // so reading the live tail tells the same story as scrolling the + // terminal pane. + let mirror = if output.len() > 1024 { + format!("{}\n... ({} bytes truncated)", &output[..1024], output.len() - 1024) + } else { + output.clone() + }; + if ok { + state.log_bus.push("info", "pxeforge::terminal", mirror); + } else { + state.log_bus.push("warn", "pxeforge::terminal", mirror); + } + + (StatusCode::OK, Json(json!({ "output": output, "ok": ok }))) +} + +async fn dispatch(state: &AppState, argv: &[String]) -> Result { + let head = argv[0].as_str(); + let tail = &argv[1..]; + match head { + "help" | "?" => Ok(HELP_TEXT.to_string()), + "version" => Ok(format!("pxeforge {}", env!("CARGO_PKG_VERSION"))), + "uptime" => Ok(uptime_string(state)), + "status" => Ok(status_text(state)), + "isos" | "images" => Ok(isos_text(state)), + "clients" => Ok(clients_text(state)), + "gate" => gate_command(state, tail).await, + "nfs" => nfs_command(state, tail).await, + "smb" => smb_command(state, tail).await, + "log" => log_command(state, tail), + "whoami" => Ok("operator".to_string()), + "echo" => Ok(tail.join(" ")), + "clear" => Ok("\x0c".to_string()), // form feed — frontend clears panel + other => Err(format!( + "unknown command: {other}\ntype 'help' for the list" + )), + } +} + +// ── status / lists ───────────────────────────────────────────────────── + +fn status_text(s: &AppState) -> String { + let isos = s.iso_store.list(); + let clients = s.clients.list(); + let gates = s.gates.list(); + let smb = s.smb.as_ref().map(|m| m.snapshot()); + let nfs = s.nfs.list(); + let nfs_active = nfs.iter().filter(|m| m.mounted).count(); + format!( + "PXEForge {ver}\n\ + base url: {base}\n\ + interface: {nic}\n\ + uptime: {up}\n\ + isos: {n_isos} (local: {n_local}, nfs: {n_nfs})\n\ + clients: {n_clients}\n\ + gates: {n_gates}\n\ + smb: {smb}\n\ + nfs mounts: {n_total} configured ({n_active} active)\n", + ver = env!("CARGO_PKG_VERSION"), + base = s.public_base_url, + nic = if s.nic_name.is_empty() { "?" } else { s.nic_name.as_str() }, + up = uptime_string(s), + n_isos = isos.len(), + n_local = isos.iter().filter(|i| matches!(i.source, pxeforge_iso_store::IsoSource::Local)).count(), + n_nfs = isos.iter().filter(|i| !matches!(i.source, pxeforge_iso_store::IsoSource::Local)).count(), + n_clients = clients.len(), + n_gates = gates.len(), + smb = smb.map_or_else(|| "(disabled)".into(), |s| format!("{s:?}")), + n_total = nfs.len(), + n_active = nfs_active, + ) +} + +fn isos_text(s: &AppState) -> String { + let isos = s.iso_store.list(); + if isos.is_empty() { + return "(no isos)".into(); + } + let mut out = String::new(); + let _ = writeln!( + out, + "{:<32} {:<10} {:<10} {:<8}", + "ID", "FAMILY", "SIZE", "SOURCE" + ); + for i in isos { + let src = match i.source { + pxeforge_iso_store::IsoSource::Local => "local".to_string(), + pxeforge_iso_store::IsoSource::Nfs { mount_id, .. } => format!("nfs:{mount_id}"), + }; + let _ = writeln!( + out, + "{:<32} {:<10} {:<10} {:<8}", + truncate(&i.id, 32), + format!("{:?}", i.introspection.family), + human_bytes(i.size_bytes), + src, + ); + } + out +} + +fn clients_text(s: &AppState) -> String { + let clients = s.clients.list(); + if clients.is_empty() { + return "(no clients yet)".into(); + } + let mut out = String::new(); + let _ = writeln!( + out, + "{:<19} {:<16} {:<8} {}", + "MAC", "IP", "EVENTS", "LAST SEEN" + ); + for c in clients { + let ip = c.last_ip.map_or_else(|| "-".into(), |i| i.to_string()); + let _ = writeln!( + out, + "{:<19} {:<16} {:<8} {}", + c.mac, + ip, + c.events.len(), + c.last_seen + .format(&time::format_description::well_known::Rfc3339) + .unwrap_or_default() + ); + } + out +} + +// ── gate ─────────────────────────────────────────────────────────────── + +// `async` for symmetry with the other dispatch helpers — gate operations +// are sync today but might grow to await on a database in a future phase. +#[allow(clippy::unused_async)] +async fn gate_command(s: &AppState, args: &[String]) -> Result { + match args.first().map(String::as_str) { + None | Some("list") => { + let gs = s.gates.list(); + if gs.is_empty() { + return Ok("(no gates)".into()); + } + let mut out = String::new(); + for g in gs { + let _ = writeln!( + out, + "#{:<3} {:<19} {:<16} target={}", + g.position, + g.mac, + g.id, + g.assigned_target.unwrap_or_else(|| "-".into()) + ); + } + Ok(out) + } + Some("assign-all") => { + let target = args.get(1).ok_or_else(|| { + "usage: gate assign-all ".to_string() + })?; + let found = s + .iso_store + .list() + .into_iter() + .any(|i| i.boot_entries.iter().any(|e| &e.id == target)); + if !found { + return Err(format!("no such boot entry: {target}")); + } + let ids: Vec<_> = s.gates.list().into_iter().map(|g| g.id).collect(); + let n = s.gates.assign(&ids, target); + Ok(format!("assigned {n} gates -> {target}")) + } + Some("assign") => { + let gate_id = args + .get(1) + .ok_or_else(|| "usage: gate assign ".to_string())?; + let target = args + .get(2) + .ok_or_else(|| "usage: gate assign ".to_string())?; + let n = s.gates.assign(std::slice::from_ref(gate_id), target); + if n == 0 { + return Err(format!("no such gate: {gate_id}")); + } + Ok(format!("assigned 1 gate -> {target}")) + } + Some("release") => { + let gate_id = args.get(1).ok_or_else(|| "usage: gate release ".to_string())?; + match s.gates.release(gate_id) { + Some(_) => Ok(format!("released {gate_id}")), + None => Err(format!("no such gate: {gate_id}")), + } + } + Some(other) => Err(format!( + "unknown gate subcommand: {other}\ntry: gate [list|assign-all|assign|release]" + )), + } +} + +// ── nfs ──────────────────────────────────────────────────────────────── + +async fn nfs_command(s: &AppState, args: &[String]) -> Result { + match args.first().map(String::as_str) { + None | Some("list") => { + let mounts = s.nfs.list(); + if mounts.is_empty() { + return Ok("(no NFS mounts configured)".into()); + } + let mut out = String::new(); + let _ = writeln!( + out, + "{:<24} {:<6} {:<7} {:<6} {}", + "ID", "VER", "STATUS", "ISOS", "TARGET" + ); + for m in mounts { + let status = if m.mounted { "ok" } else { "down" }; + let _ = writeln!( + out, + "{:<24} {:<6} {:<7} {:<6} {}:{}", + truncate(&m.id, 24), + match m.version { + pxeforge_iso_store::NfsVersion::V3 => "v3", + pxeforge_iso_store::NfsVersion::V41 => "v4.1", + }, + status, + m.iso_count, + m.server, + m.export, + ); + if let Some(e) = m.last_error { + let _ = writeln!(out, " error: {e}"); + } + } + Ok(out) + } + Some("mount") => { + // nfs mount : [v3|v41] [ro|rw] + let target = args + .get(1) + .ok_or_else(|| "usage: nfs mount : [v3|v41] [ro|rw]".to_string())?; + let (server, export) = target + .split_once(':') + .ok_or_else(|| "target must be 'server:/export'".to_string())?; + let version = match args.get(2).map(String::as_str) { + Some("v3") => pxeforge_iso_store::NfsVersion::V3, + Some("v41") | None => pxeforge_iso_store::NfsVersion::V41, + Some(other) => return Err(format!("unknown nfs version: {other} (expect v3 or v41)")), + }; + let read_only = !matches!(args.get(3).map(String::as_str), Some("rw")); + let req = pxeforge_iso_store::NfsAddRequest { + server: server.to_string(), + export: export.to_string(), + version, + read_only, + }; + match s.nfs.add(req).await { + Ok(m) => Ok(format!("mounted {} ({} isos)", m.id, m.iso_count)), + Err(e) => Err(format!("mount failed: {e}")), + } + } + Some("unmount") => { + let id = args.get(1).ok_or_else(|| "usage: nfs unmount ".to_string())?; + match s.nfs.remove(id).await { + Ok(()) => Ok(format!("unmounted {id}")), + Err(e) => Err(format!("unmount failed: {e}")), + } + } + Some("scan") => { + let id = args.get(1).ok_or_else(|| "usage: nfs scan ".to_string())?; + match s.nfs.rescan(id).await { + Ok(n) => Ok(format!("re-scanned {id}: {n} isos")), + Err(e) => Err(format!("scan failed: {e}")), + } + } + Some(other) => Err(format!( + "unknown nfs subcommand: {other}\ntry: nfs [list|mount|unmount|scan]" + )), + } +} + +// ── smb ──────────────────────────────────────────────────────────────── + +#[allow(clippy::unused_async)] +async fn smb_command(s: &AppState, args: &[String]) -> Result { + let smb = s + .smb + .as_ref() + .ok_or_else(|| "SMB manager not configured (Windows support disabled)".to_string())?; + match args.first().map(String::as_str) { + None | Some("status") => Ok(format!("{:#?}", smb.snapshot())), + Some("start") => { + // start/reconcile return the new SmbState — there's no + // separate Result type. The state itself indicates success + // or failure via its variant. + let st = smb.start(); + Ok(format!("smbd start requested -> {st:?}")) + } + Some("stop") => { + smb.stop(); + Ok("smbd stop requested".into()) + } + Some("reload") => { + let st = smb.reconcile(); + Ok(format!("smbd reload (SIGHUP) sent -> {st:?}")) + } + Some(other) => Err(format!( + "unknown smb subcommand: {other}\ntry: smb [status|start|stop|reload]" + )), + } +} + +// ── log ──────────────────────────────────────────────────────────────── + +fn log_command(s: &AppState, args: &[String]) -> Result { + match args.first().map(String::as_str) { + Some("clear") => { + s.log_bus.clear(); + Ok("log buffer cleared".into()) + } + Some("tail") => { + let n: usize = args + .get(1) + .and_then(|v| v.parse().ok()) + .unwrap_or(20); + let lines = s.log_bus.recent(); + let start = lines.len().saturating_sub(n); + let mut out = String::new(); + for l in &lines[start..] { + let _ = writeln!(out, "{}", l.render()); + } + if out.is_empty() { + Ok("(empty)".into()) + } else { + Ok(out) + } + } + _ => Err("usage: log [clear|tail [n]]".into()), + } +} + +// ── helpers ──────────────────────────────────────────────────────────── + +fn uptime_string(s: &AppState) -> String { + let now = time::OffsetDateTime::now_utc(); + let secs = (now - s.started_at).whole_seconds().max(0); + let h = secs / 3600; + let m = (secs % 3600) / 60; + let s = secs % 60; + format!("{h}h {m}m {s}s") +} + +fn truncate(s: &str, max: usize) -> String { + if s.len() <= max { + s.to_string() + } else { + format!("{}…", &s[..max.saturating_sub(1)]) + } +} + +fn human_bytes(n: u64) -> String { + const U: &[&str] = &["B", "KB", "MB", "GB", "TB"]; + // Loss-of-precision past 2^52 is academic for ISO file sizes — even + // a 4 PiB file still rounds to the right unit. + #[allow(clippy::cast_precision_loss)] + let mut x = n as f64; + let mut i = 0; + while x >= 1024.0 && i < U.len() - 1 { + x /= 1024.0; + i += 1; + } + if i == 0 || x >= 10.0 { + format!("{:.0} {}", x, U[i]) + } else { + format!("{:.1} {}", x, U[i]) + } +} + +/// Tiny shell-like splitter — splits on whitespace, honoring `'…'` and +/// `"…"` quoted segments. We deliberately don't expand `$VAR` or any +/// other shell metacharacters; this is a parser for our own command +/// vocabulary, not a real shell. +pub fn shell_split(input: &str) -> Vec { + let mut out = Vec::new(); + let mut current = String::new(); + let mut in_single = false; + let mut in_double = false; + for ch in input.chars() { + match ch { + '\'' if !in_double => in_single = !in_single, + '"' if !in_single => in_double = !in_double, + c if c.is_whitespace() && !in_single && !in_double => { + if !current.is_empty() { + out.push(std::mem::take(&mut current)); + } + } + c => current.push(c), + } + } + if !current.is_empty() { + out.push(current); + } + out +} + +const HELP_TEXT: &str = "\ +PXEForge terminal — available commands: + + help show this help + version print server version + status high-level server status + uptime time since startup + + isos list registered ISOs + clients list PXE clients seen this session + gate list list gated-deployment queue + gate assign assign one gate to a boot entry + gate assign-all assign every waiting gate + gate release release one gate + + nfs list list NFS mounts + nfs mount : [v3|v41] [ro|rw] add and mount an NFS share + nfs unmount unmount and forget a share + nfs scan re-scan a share for new ISOs + + smb status SMB (Samba) state + smb start | stop | reload control smbd + + log clear drop the in-memory log ring buffer + log tail [n] show the last n buffered lines (default 20) + clear clear the terminal pane + +Tab to autocomplete is not implemented (sorry).\n"; + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn shell_split_basic() { + assert_eq!(shell_split(""), Vec::::new()); + assert_eq!(shell_split("nfs list"), vec!["nfs", "list"]); + assert_eq!( + shell_split("nfs mount 10.0.0.5:/srv v41 ro"), + vec!["nfs", "mount", "10.0.0.5:/srv", "v41", "ro"] + ); + } + + #[test] + fn shell_split_quoted() { + assert_eq!( + shell_split("echo 'hello world' done"), + vec!["echo", "hello world", "done"] + ); + assert_eq!( + shell_split(r#"echo "double quotes" 'and singles'"#), + vec!["echo", "double quotes", "and singles"] + ); + } + + #[test] + fn human_bytes_units() { + assert_eq!(human_bytes(0), "0 B"); + assert_eq!(human_bytes(1023), "1023 B"); + assert_eq!(human_bytes(1024), "1.0 KB"); + assert_eq!(human_bytes(2 * 1024 * 1024), "2.0 MB"); + assert_eq!(human_bytes(5 * 1024u64.pow(3)), "5.0 GB"); + } + + #[test] + fn truncate_keeps_short() { + assert_eq!(truncate("hi", 10), "hi"); + assert_eq!(truncate("longerthanfive", 5), "long…"); + } +} diff --git a/crates/http-api/tests/full_flow.rs b/crates/http-api/tests/full_flow.rs new file mode 100644 index 0000000..dd67e53 --- /dev/null +++ b/crates/http-api/tests/full_flow.rs @@ -0,0 +1,470 @@ +//! End-to-end HTTP integration test. +//! +//! Spins up the real axum router against a temp ISO store + settings store, +//! then walks an imaginary iPXE client through: dashboard status → upload +//! ISO → fetch top-level boot menu → fetch per-entry script → Range-GET the +//! ISO. Also drives the Gated Deployment flow end-to-end: two clients join, +//! operator assigns, both polls return the chain script with retry fallback. +//! +//! This is the closest we can get to "real PXE client" without QEMU; the +//! TFTP leg is separately unit-tested in `crates/tftp`. Between the two, +//! every HTTP endpoint a real client touches is covered by a test. + +use axum::body::Body; +use axum::http::{header, Request, StatusCode}; +use pxeforge_core::{ClientRegistry, GateQueue, LogBus, SettingsStore}; +use pxeforge_http_api::{build_router, AppState}; +use pxeforge_iso_store::{IsoStore, NfsManager}; +use tempfile::tempdir; +use tower::ServiceExt; + +/// Build a tiny valid ISO9660 blob with volume label "ALPINE-TEST" so +/// introspection identifies it as Alpine. +fn fake_alpine_iso() -> Vec { + let mut buf = vec![0u8; 32 * 2048]; + let off = 16 * 2048; + buf[off] = 0x01; + buf[off + 1..off + 6].copy_from_slice(b"CD001"); + buf[off + 6] = 0x01; + let label = b"ALPINE-TEST".to_vec(); + let mut padded = label.clone(); + padded.resize(32, b' '); + buf[off + 40..off + 40 + 32].copy_from_slice(&padded); + let term = 17 * 2048; + buf[term] = 0xFF; + buf[term + 1..term + 6].copy_from_slice(b"CD001"); + buf[term + 6] = 0x01; + buf +} + +fn multipart_iso_body(filename: &str, bytes: &[u8]) -> (String, Vec) { + let boundary = "----PxeForgeTestBoundary1234"; + let mut body = Vec::new(); + body.extend_from_slice(format!("--{boundary}\r\n").as_bytes()); + body.extend_from_slice( + format!( + "Content-Disposition: form-data; name=\"file\"; filename=\"{filename}\"\r\n" + ).as_bytes(), + ); + body.extend_from_slice(b"Content-Type: application/octet-stream\r\n\r\n"); + body.extend_from_slice(bytes); + body.extend_from_slice(format!("\r\n--{boundary}--\r\n").as_bytes()); + let ct = format!("multipart/form-data; boundary={boundary}"); + (ct, body) +} + +async fn get(router: &axum::Router, path: &str) -> (StatusCode, Vec) { + let res = router + .clone() + .oneshot(Request::builder().uri(path).body(Body::empty()).unwrap()) + .await + .unwrap(); + let status = res.status(); + let body = axum::body::to_bytes(res.into_body(), usize::MAX).await.unwrap().to_vec(); + (status, body) +} + +async fn post_json(router: &axum::Router, path: &str, body: &str) -> (StatusCode, Vec) { + let res = router + .clone() + .oneshot( + Request::builder() + .method("POST") + .uri(path) + .header("content-type", "application/json") + .body(Body::from(body.to_owned())) + .unwrap(), + ) + .await + .unwrap(); + let status = res.status(); + let body = axum::body::to_bytes(res.into_body(), usize::MAX).await.unwrap().to_vec(); + (status, body) +} + +async fn build_state() -> (AppState, tempfile::TempDir) { + let dir = tempdir().unwrap(); + let iso_store = IsoStore::new(dir.path().join("isos")); + iso_store.ensure_dirs().await.unwrap(); + let clients = ClientRegistry::new(); + let gates = GateQueue::new(); + let settings = SettingsStore::load_or_default(dir.path()); + let nfs = NfsManager::new(dir.path(), iso_store.clone()); + iso_store.set_nfs_root(nfs.mount_root()); + let log_bus = LogBus::new(64); + let state = AppState { + iso_store, + clients, + gates, + settings, + smb: None, + nfs, + log_bus, + started_at: time::OffsetDateTime::now_utc(), + public_base_url: "http://127.0.0.1".into(), + nic_name: "lo".into(), + subnet_mask: "255.0.0.0".into(), + gateway: "127.0.0.1".into(), + }; + (state, dir) +} + +#[tokio::test] +async fn health_and_ready_endpoints() { + let (state, _dir) = build_state().await; + let app = build_router(state); + let (s, b) = get(&app, "/healthz").await; + assert_eq!(s, StatusCode::OK); + assert_eq!(b, b"ok\n"); + // /readyz should 503 when no iPXE binaries bundled at test time — this + // actually depends on whether CI has fetched them. Accept either. + let (s2, _) = get(&app, "/readyz").await; + assert!( + s2 == StatusCode::OK || s2 == StatusCode::SERVICE_UNAVAILABLE, + "unexpected readyz status: {s2}" + ); +} + +#[tokio::test] +async fn upload_introspects_and_generates_boot_entry() { + let (state, _dir) = build_state().await; + let app = build_router(state.clone()); + + let iso = fake_alpine_iso(); + let (ct, body) = multipart_iso_body("fake-alpine.iso", &iso); + let res = app + .clone() + .oneshot( + Request::builder() + .method("POST") + .uri("/api/isos") + .header("content-type", ct) + .body(Body::from(body)) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(res.status(), StatusCode::CREATED, "upload failed"); + + // Confirm the ISO shows up in the menu. + let (_, menu) = get(&app, "/boot.ipxe").await; + let menu = String::from_utf8(menu).unwrap(); + assert!(menu.contains("Linux Installers"), "menu missing Linux submenu:\n{menu}"); + + let (_, linux) = get(&app, "/boot/_linux_menu.ipxe").await; + let linux = String::from_utf8(linux).unwrap(); + assert!(linux.contains("fake-alpine-linux"), "linux submenu missing entry:\n{linux}"); + assert!(linux.contains("[ 0 MB]") || linux.contains("[ 0 MB]"), + "size label missing in {linux}"); + + // Per-entry boot script should include kernel + initrd URLs + boot. + let (_, entry) = get(&app, "/boot/fake-alpine-linux.ipxe").await; + let entry = String::from_utf8(entry).unwrap(); + assert!(entry.contains("kernel http://127.0.0.1/iso/fake-alpine/boot/vmlinuz-lts")); + assert!(entry.contains("initrd http://127.0.0.1/iso/fake-alpine/boot/initramfs-lts")); + assert!(entry.contains("boot || goto failed")); +} + +#[tokio::test] +async fn iso_range_request_slices_correctly() { + let (state, _dir) = build_state().await; + let app = build_router(state.clone()); + let iso = fake_alpine_iso(); + let (ct, body) = multipart_iso_body("fake-alpine.iso", &iso); + app.clone() + .oneshot( + Request::builder() + .method("POST").uri("/api/isos") + .header("content-type", ct) + .body(Body::from(body)).unwrap()).await.unwrap(); + + // Range bytes=0x8000-0x8005 should return the PVD signature byte. + let res = app + .clone() + .oneshot( + Request::builder() + .uri("/iso/fake-alpine.iso") + .header(header::RANGE, "bytes=32768-32773") + .body(Body::empty()).unwrap()) + .await.unwrap(); + assert_eq!(res.status(), StatusCode::PARTIAL_CONTENT); + let slice = axum::body::to_bytes(res.into_body(), usize::MAX).await.unwrap(); + assert_eq!(slice[0], 0x01); // PVD type + assert_eq!(&slice[1..6], b"CD001"); +} + +#[tokio::test] +async fn gated_deployment_full_flow() { + let (state, _dir) = build_state().await; + let app = build_router(state.clone()); + + // Upload an ISO so the target exists. + let (ct, body) = multipart_iso_body("fake-alpine.iso", &fake_alpine_iso()); + app.clone() + .oneshot(Request::builder().method("POST").uri("/api/isos") + .header("content-type", ct).body(Body::from(body)).unwrap()) + .await.unwrap(); + + // Two clients join. + let (_, join1) = get(&app, "/api/gate/join?mac=aa:bb:cc:00:00:01").await; + let (_, join2) = get(&app, "/api/gate/join?mac=aa:bb:cc:00:00:02").await; + let s1 = String::from_utf8(join1).unwrap(); + let s2 = String::from_utf8(join2).unwrap(); + assert!(s1.contains("Gate Position 1")); + assert!(s2.contains("Gate Position 2")); + + let gate1_id = s1.lines().find_map(|l| l.strip_prefix("chain http://127.0.0.1/api/gate/poll/")) + .unwrap().to_string(); + let gate2_id = s2.lines().find_map(|l| l.strip_prefix("chain http://127.0.0.1/api/gate/poll/")) + .unwrap().to_string(); + + // Kick off a long-poll for client 1 in the background. Then assign. + let app2 = app.clone(); + let poll_future = tokio::spawn(async move { + let uri = format!("/api/gate/poll/{gate1_id}"); + get(&app2, &uri).await + }); + + // Give the poll a moment to register its notify subscription. + tokio::time::sleep(std::time::Duration::from_millis(50)).await; + + // Operator assigns. + let body = format!(r#"{{"target":"fake-alpine-linux","gate_ids":["{gate2_id}"]}}"#); + let (s, b) = post_json(&app, "/api/gate/assign", &body).await; + assert_eq!(s, StatusCode::OK); + let assign_json = String::from_utf8(b).unwrap(); + assert!(assign_json.contains(r#""assigned":1"#), "assign response: {assign_json}"); + + // Now assign to gate 1 too so the background poll wakes. + let body = format!(r#"{{"target":"fake-alpine-linux","gate_ids":[]}}"#); + post_json(&app, "/api/gate/assign", &body).await; + + let (poll_status, poll_body) = poll_future.await.unwrap(); + assert_eq!(poll_status, StatusCode::OK); + let poll_s = String::from_utf8(poll_body).unwrap(); + assert!( + poll_s.contains("chain http://127.0.0.1/boot/fake-alpine-linux.ipxe"), + "poll response should chain the boot script:\n{poll_s}" + ); + // Retry-on-error fallback must be present. + assert!(poll_s.contains("|| chain http://127.0.0.1/api/gate/poll/"), + "retry fallback missing"); + + // Bad target must be rejected. + let (_, bad) = post_json(&app, "/api/gate/assign", + r#"{"target":"does-not-exist","gate_ids":[]}"#).await; + let bad_s = String::from_utf8(bad).unwrap(); + assert!(bad_s.contains(r#""ok":false"#), "expected rejection: {bad_s}"); +} + +#[tokio::test] +async fn settings_put_persists_across_reads() { + let (state, _dir) = build_state().await; + let app = build_router(state); + let body = serde_json::json!({ + "boot_menu_timeout_secs": 42, + "timeout_action": "local_hdd", + "windows_enabled": false, + "smb_host_override": "", + "extra_kernel_args": "console=ttyS0", + "default_local_hdd": true, + "gate_wait_max_secs": 0 + }).to_string(); + + let res = app + .clone() + .oneshot( + Request::builder() + .method("PUT") + .uri("/api/settings") + .header("content-type", "application/json") + .body(Body::from(body)) + .unwrap()) + .await + .unwrap(); + assert_eq!(res.status(), StatusCode::NO_CONTENT); + + let (_, g) = get(&app, "/api/settings").await; + let got: serde_json::Value = serde_json::from_slice(&g).unwrap(); + assert_eq!(got["boot_menu_timeout_secs"], 42); + assert_eq!(got["timeout_action"], "local_hdd"); + assert_eq!(got["extra_kernel_args"], "console=ttyS0"); + + // And the menu should now use the new timeout. + let (_, menu) = get(&app, "/boot.ipxe").await; + let menu = String::from_utf8(menu).unwrap(); + assert!(menu.contains("--timeout 42000"), + "menu should reflect 42s timeout:\n{menu}"); + assert!(menu.contains("--default local"), + "menu should default to local:\n{menu}"); +} + +#[tokio::test] +async fn reboot_and_firmware_exit_in_tools_menu() { + let (state, _dir) = build_state().await; + let app = build_router(state); + let (_, tools) = get(&app, "/boot/_tools_menu.ipxe").await; + let tools = String::from_utf8(tools).unwrap(); + assert!(tools.contains("Reboot Computer"), + "tools menu missing Reboot item:\n{tools}"); + assert!(tools.contains("Exit and continue BIOS boot"), + "tools menu missing firmware-exit item:\n{tools}"); + assert!(tools.contains("&& reboot"), + "reboot command not wired:\n{tools}"); + assert!(tools.contains("&& exit 0"), + "firmware exit command not wired:\n{tools}"); +} + +#[tokio::test] +async fn ui_assets_served_offline() { + let (state, _dir) = build_state().await; + let app = build_router(state); + + for (path, ct) in [ + ("/", "text/html"), + ("/assets/app.js", "application/javascript"), + ("/assets/app.css", "text/css"), + ("/assets/logo.svg", "image/svg+xml"), + ] { + let res = app + .clone() + .oneshot(Request::builder().uri(path).body(Body::empty()).unwrap()) + .await.unwrap(); + assert_eq!(res.status(), StatusCode::OK, "{path} not 200"); + let got = res.headers() + .get(header::CONTENT_TYPE).unwrap() + .to_str().unwrap(); + assert!(got.starts_with(ct), "{path} ct={got}, expected {ct}"); + } +} + +#[tokio::test] +async fn no_external_urls_in_generated_ipxe() { + // Sanity check that nothing we serve points off-server. + let (state, _dir) = build_state().await; + let app = build_router(state); + for path in ["/boot.ipxe", "/boot/_tools_menu.ipxe", "/boot/_linux_menu.ipxe", + "/boot/_shell.ipxe", "/boot/_nic.ipxe", "/boot/_local.ipxe"] { + let (_, body) = get(&app, path).await; + let s = String::from_utf8(body).unwrap(); + // The only URLs we should emit are relative to our own public_base_url. + for url in ["github.com", "googleapis", "cdn.", "cdnjs", "unpkg", "jsdelivr"] { + assert!(!s.contains(url), "{path} references external host {url}:\n{s}"); + } + // Confirm URLs are all ours. + for line in s.lines() { + if let Some(idx) = line.find("http://") { + let rest = &line[idx..]; + assert!(rest.starts_with("http://127.0.0.1"), + "{path} references non-public-base URL: {line}"); + } + } + } +} + +// ── Phase 4 integration tests ──────────────────────────────────────────── + +#[tokio::test] +async fn nfs_add_with_bad_export_is_rejected() { + // Validation must happen before we shell out to /bin/mount — + // otherwise the operator sees opaque kernel errors instead of a + // clear "your export must start with /" hint. + let (state, _dir) = build_state().await; + let app = build_router(state); + let (s, b) = post_json( + &app, + "/api/nfs", + r#"{"server":"10.0.0.5","export":"isos","version":"v41","read_only":true}"#, + ) + .await; + assert_eq!(s, StatusCode::BAD_REQUEST); + let msg = String::from_utf8_lossy(&b); + assert!(msg.contains("export"), "expected validation hint, got: {msg}"); +} + +#[tokio::test] +async fn nfs_list_starts_empty() { + let (state, _dir) = build_state().await; + let app = build_router(state); + let (s, b) = get(&app, "/api/nfs").await; + assert_eq!(s, StatusCode::OK); + let v: serde_json::Value = serde_json::from_slice(&b).unwrap(); + assert_eq!(v["mounts"].as_array().unwrap().len(), 0); +} + +#[tokio::test] +async fn terminal_help_and_status_round_trip() { + let (state, _dir) = build_state().await; + let app = build_router(state); + + // Empty command -> help banner. + let (s, b) = post_json(&app, "/api/terminal", r#"{"command":""}"#).await; + assert_eq!(s, StatusCode::OK); + let v: serde_json::Value = serde_json::from_slice(&b).unwrap(); + assert!(v["output"].as_str().unwrap().contains("PXEForge terminal")); + + // status -> contains the version banner. + let (s, b) = post_json(&app, "/api/terminal", r#"{"command":"status"}"#).await; + assert_eq!(s, StatusCode::OK); + let v: serde_json::Value = serde_json::from_slice(&b).unwrap(); + let out = v["output"].as_str().unwrap(); + assert!(out.starts_with("PXEForge"), "unexpected status output: {out}"); + assert!(out.contains("isos:"), "status missing iso line: {out}"); + + // Unknown command -> ok=false plus help hint. + let (_, b) = post_json(&app, "/api/terminal", r#"{"command":"frobnicate"}"#).await; + let v: serde_json::Value = serde_json::from_slice(&b).unwrap(); + assert_eq!(v["ok"], false); + assert!(v["output"].as_str().unwrap().contains("unknown command")); +} + +#[tokio::test] +async fn log_recent_returns_buffered_lines() { + // The terminal command we issued seeds the log bus, so a follow-up + // /api/log/recent must surface those lines as JSON. + let (state, _dir) = build_state().await; + let app = build_router(state); + let _ = post_json(&app, "/api/terminal", r#"{"command":"version"}"#).await; + let (s, b) = get(&app, "/api/log/recent").await; + assert_eq!(s, StatusCode::OK); + let v: serde_json::Value = serde_json::from_slice(&b).unwrap(); + let lines = v["lines"].as_array().expect("lines array"); + assert!(!lines.is_empty(), "log buffer should have at least one line"); + // Every entry should have the canonical timestamp/level/target/message. + for l in lines { + for k in ["timestamp", "level", "target", "message"] { + assert!(l.get(k).is_some(), "missing field {k} in log line: {l}"); + } + } +} + +#[tokio::test] +async fn network_endpoint_exposes_dns_round_trip() { + let (state, _dir) = build_state().await; + let app = build_router(state); + + // GET starts blank. + let (_, b) = get(&app, "/api/network").await; + let v: serde_json::Value = serde_json::from_slice(&b).unwrap(); + assert_eq!(v["dns_server"], ""); + assert_eq!(v["nic_name"], "lo"); + + // PUT updates only the DNS field. + let res = app + .clone() + .oneshot( + Request::builder() + .method("PUT") + .uri("/api/network") + .header("content-type", "application/json") + .body(Body::from(r#"{"dns_server":"10.0.0.1"}"#)) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(res.status(), StatusCode::NO_CONTENT); + + let (_, b) = get(&app, "/api/network").await; + let v: serde_json::Value = serde_json::from_slice(&b).unwrap(); + assert_eq!(v["dns_server"], "10.0.0.1"); +} diff --git a/crates/ipxe-assets/Cargo.toml b/crates/ipxe-assets/Cargo.toml new file mode 100644 index 0000000..577de9c --- /dev/null +++ b/crates/ipxe-assets/Cargo.toml @@ -0,0 +1,16 @@ +[package] +name = "pxeforge-ipxe-assets" +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +description = "Bundled iPXE binaries and default chain scripts for PXEForge" + +[lints] +workspace = true + +[dependencies] +pxeforge-core.workspace = true +rust-embed.workspace = true +tracing.workspace = true +thiserror.workspace = true diff --git a/crates/ipxe-assets/src/lib.rs b/crates/ipxe-assets/src/lib.rs new file mode 100644 index 0000000..67225ba --- /dev/null +++ b/crates/ipxe-assets/src/lib.rs @@ -0,0 +1,70 @@ +//! Bundled iPXE boot binaries and default chain script. +//! +//! At build time, we expect the iPXE binaries to live at `assets/ipxe/` at +//! the workspace root. They are embedded into the PXEForge binary via +//! `rust-embed` so the container image is self-contained. If a binary is +//! missing, that architecture simply won't have PXE support — we log at +//! startup and serve what we have. +//! +//! Filename convention (matches `ClientArch::ipxe_bootfile`): +//! - `undionly.kpxe` — Legacy x86 BIOS +//! - `snponly-i386.efi` — IA32 UEFI +//! - `snponly.efi` — x86_64 UEFI +//! - `snponly-arm32.efi` — ARM32 UEFI +//! - `snponly-arm64.efi` — ARM64 UEFI +//! - `ipxe.efi` (fallback) — UEFI with bundled drivers, if snponly fails on a NIC +//! - `wimboot` — Windows boot shim (fetched separately for WIM chains) +#![forbid(unsafe_code)] + +use pxeforge_core::ClientArch; +use rust_embed::Embed; + +#[derive(Embed)] +#[folder = "../../assets/ipxe/"] +#[include = "*.kpxe"] +#[include = "*.efi"] +#[include = "wimboot"] +pub struct IpxeAssets; + +/// Return the embedded iPXE binary for `arch`, or `None` if we didn't bundle +/// one for that architecture. +#[must_use] +pub fn bootfile_bytes(arch: ClientArch) -> Option> { + let name = arch.ipxe_bootfile()?; + IpxeAssets::get(name).map(|f| f.data.into_owned()) +} + +/// Return a named asset directly (e.g. `wimboot`, or a fallback `ipxe.efi`). +#[must_use] +pub fn asset_bytes(name: &str) -> Option> { + IpxeAssets::get(name).map(|f| f.data.into_owned()) +} + +/// Enumerate embedded asset filenames. Useful for startup logging so the +/// operator can immediately tell which architectures will work. +pub fn list_assets() -> Vec { + IpxeAssets::iter().map(|c| c.into_owned()).collect() +} + +/// Log at startup which iPXE binaries are present and which are missing. +pub fn log_availability() { + let have: std::collections::HashSet = list_assets().into_iter().collect(); + let needed = [ + (ClientArch::LegacyX86, "undionly.kpxe"), + (ClientArch::Ia32Uefi, "snponly-i386.efi"), + (ClientArch::X64Uefi, "snponly.efi"), + // ARM32 UEFI deferred — no upstream snponly binary published. + (ClientArch::Arm64Uefi, "snponly-arm64.efi"), + ]; + for (arch, name) in needed { + if have.contains(name) { + tracing::info!(target: "pxeforge::ipxe", "bundled iPXE for {}: {}", arch.as_str(), name); + } else { + tracing::warn!( + target: "pxeforge::ipxe", + "MISSING iPXE binary for {}: {} — clients of this arch will not PXE boot", + arch.as_str(), name + ); + } + } +} diff --git a/crates/iso-store/Cargo.toml b/crates/iso-store/Cargo.toml new file mode 100644 index 0000000..6a24220 --- /dev/null +++ b/crates/iso-store/Cargo.toml @@ -0,0 +1,31 @@ +[package] +name = "pxeforge-iso-store" +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +description = "ISO upload, storage, introspection, and boot-entry generation for PXEForge" + +[lints] +workspace = true + +[dependencies] +pxeforge-core.workspace = true +tokio = { workspace = true } +tokio-util = { workspace = true } +serde.workspace = true +serde_json.workspace = true +tracing.workspace = true +thiserror.workspace = true +anyhow.workspace = true +sha2.workspace = true +hex.workspace = true +uuid.workspace = true +time.workspace = true +parking_lot.workspace = true +bytes.workspace = true +tempfile = "3.12" +libc = "0.2" + +[dev-dependencies] +tempfile = "3.12" diff --git a/crates/iso-store/src/entry.rs b/crates/iso-store/src/entry.rs new file mode 100644 index 0000000..0f832af --- /dev/null +++ b/crates/iso-store/src/entry.rs @@ -0,0 +1,39 @@ +use serde::{Deserialize, Serialize}; + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct BootEntry { + /// Stable id (also the URL slug in generated iPXE scripts). + pub id: String, + /// Display label shown in the iPXE boot menu. + pub title: String, + pub kind: BootKind, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(tag = "kind", rename_all = "snake_case")] +pub enum BootKind { + /// Linux kernel + initrd chainload. Kernel args carry the distro-specific + /// pointer back to the ISO contents served over HTTP. + LinuxKernel { + kernel_url: String, + initrd_urls: Vec, + args: KernelArgs, + }, + /// Windows WinPE boot via wimboot shim. `files` maps in-memory tags to + /// HTTP URLs the client fetches. See https://ipxe.org/wimboot . + Wimboot { + wimboot_url: String, + files: Vec<(String, String)>, + }, + /// Last-resort: SAN-boot the ISO as an emulated CD. Only works for small + /// ISOs (<~1 GiB) and older distros. Kept for completeness, not the + /// default. + SanBootIso { iso_url: String }, +} + +#[derive(Debug, Clone, Default, Serialize, Deserialize)] +pub struct KernelArgs { + /// Raw kernel command line, already distro-adapted. Do not quote — iPXE + /// takes a single space-separated command line. + pub cmdline: String, +} diff --git a/crates/iso-store/src/introspect.rs b/crates/iso-store/src/introspect.rs new file mode 100644 index 0000000..531d406 --- /dev/null +++ b/crates/iso-store/src/introspect.rs @@ -0,0 +1,155 @@ +//! ISO introspection — identify the distro family and locate kernel/initrd. +//! +//! We avoid a full ISO9660/Joliet/Rock-Ridge parser by reading a small number +//! of well-known files via `isoinfo` (from cdrtools/genisoimage) when it's on +//! the path. As a pure-Rust fallback we do a crude scan: read the volume +//! descriptor at offset 0x8000 to grab the volume label, and grep for known +//! filenames by scanning raw sectors — good enough to tell Debian from RHEL +//! most of the time, without shelling out. +//! +//! The returned `IntrospectionReport` is what `BootEntry`s get generated from. + +use serde::{Deserialize, Serialize}; +use std::io::{Read, Seek, SeekFrom}; +use std::path::Path; + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum DistroFamily { + DebianUbuntu, + RhelFedora, + OpenSuse, + Arch, + Alpine, + WindowsPe, + Unknown, +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct IntrospectionReport { + pub family: DistroFamily, + pub volume_label: Option, + /// Kernel path inside the ISO (e.g. `/casper/vmlinuz`, `/isolinux/vmlinuz`). + pub kernel_path: Option, + /// Initrd path(s) inside the ISO. May be multiple for multi-initrd setups. + pub initrd_paths: Vec, + /// True if `sources/boot.wim` present — Windows install media. + pub has_boot_wim: bool, +} + +/// Probe an ISO file on disk. Never fails — on unrecoverable IO error we log +/// and return an `Unknown` family so the uploader still sees a record. +pub fn introspect(path: &Path) -> IntrospectionReport { + let mut report = IntrospectionReport { + family: DistroFamily::Unknown, + volume_label: None, + kernel_path: None, + initrd_paths: Vec::new(), + has_boot_wim: false, + }; + + let Ok(mut f) = std::fs::File::open(path) else { + tracing::warn!(target: "pxeforge::iso", "cannot open ISO for introspection: {}", path.display()); + return report; + }; + + // ISO9660 Primary Volume Descriptor at LBA 16 (offset 0x8000), 2048 bytes. + // Bytes 40..72 are the Volume Identifier (space-padded, d-characters). + let mut pvd = [0u8; 2048]; + if f.seek(SeekFrom::Start(0x8000)).is_ok() && f.read_exact(&mut pvd).is_ok() { + // Byte 0 must be 0x01 (primary descriptor), bytes 1..6 = "CD001". + if pvd[0] == 0x01 && &pvd[1..6] == b"CD001" { + let label_raw = &pvd[40..72]; + let label = String::from_utf8_lossy(label_raw).trim().to_string(); + if !label.is_empty() { + report.volume_label = Some(label.clone()); + report.family = family_from_label(&label); + } + } + } + + // Cheap content scan: read the first ~64 MiB, look for signature filenames. + // This is enough to identify `sources/boot.wim` (Windows) and common + // kernel/initrd paths for the major Linux distros. + let _ = f.seek(SeekFrom::Start(0)); + let scan_bytes = 64 * 1024 * 1024; + let mut buf = vec![0u8; 1024 * 1024]; + let mut read_total = 0usize; + let mut haystack = Vec::with_capacity(scan_bytes.min(32 * 1024 * 1024)); + while read_total < scan_bytes { + let n = f.read(&mut buf).unwrap_or(0); + if n == 0 { break; } + haystack.extend_from_slice(&buf[..n]); + read_total += n; + } + + if contains_ascii(&haystack, b"sources/boot.wim") + || contains_ascii(&haystack, b"SOURCES/BOOT.WIM") + || contains_ascii(&haystack, b"SOURCES\\BOOT.WIM") + { + report.has_boot_wim = true; + if report.family == DistroFamily::Unknown { + report.family = DistroFamily::WindowsPe; + } + } + + // Best-effort kernel/initrd path guess from family. These paths are what + // distro ISOs conventionally ship at — we don't verify extraction here; + // that happens in the store after introspection. + let (k, i) = guess_kernel_initrd(report.family); + report.kernel_path = k.map(str::to_string); + report.initrd_paths = i.iter().map(|s| s.to_string()).collect(); + + report +} + +fn family_from_label(label: &str) -> DistroFamily { + let l = label.to_ascii_lowercase(); + if l.contains("ubuntu") || l.contains("debian") || l.contains("mint") { + DistroFamily::DebianUbuntu + } else if l.contains("rhel") || l.contains("centos") || l.contains("fedora") + || l.contains("rocky") || l.contains("alma") + { + DistroFamily::RhelFedora + } else if l.contains("suse") || l.contains("opensuse") { + DistroFamily::OpenSuse + } else if l.contains("arch") { + DistroFamily::Arch + } else if l.contains("alpine") { + DistroFamily::Alpine + } else if l.contains("windows") || l.contains("winpe") { + DistroFamily::WindowsPe + } else { + DistroFamily::Unknown + } +} + +fn guess_kernel_initrd(family: DistroFamily) -> (Option<&'static str>, Vec<&'static str>) { + match family { + DistroFamily::DebianUbuntu => (Some("/casper/vmlinuz"), vec!["/casper/initrd"]), + DistroFamily::RhelFedora => (Some("/images/pxeboot/vmlinuz"), vec!["/images/pxeboot/initrd.img"]), + DistroFamily::OpenSuse => (Some("/boot/x86_64/loader/linux"), vec!["/boot/x86_64/loader/initrd"]), + DistroFamily::Arch => (Some("/arch/boot/x86_64/vmlinuz-linux"), vec!["/arch/boot/x86_64/initramfs-linux.img"]), + DistroFamily::Alpine => (Some("/boot/vmlinuz-lts"), vec!["/boot/initramfs-lts"]), + DistroFamily::WindowsPe | DistroFamily::Unknown => (None, Vec::new()), + } +} + +fn contains_ascii(haystack: &[u8], needle: &[u8]) -> bool { + if needle.is_empty() || haystack.len() < needle.len() { return false; } + haystack.windows(needle.len()).any(|w| w.eq_ignore_ascii_case(needle)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn label_matching() { + assert_eq!(family_from_label("Ubuntu 24.04"), DistroFamily::DebianUbuntu); + assert_eq!(family_from_label("Rocky-9-x86_64-dvd"), DistroFamily::RhelFedora); + assert_eq!(family_from_label("openSUSE-Leap-15.6"), DistroFamily::OpenSuse); + assert_eq!(family_from_label("ARCH_202604"), DistroFamily::Arch); + assert_eq!(family_from_label("weird-custom"), DistroFamily::Unknown); + } +} diff --git a/crates/iso-store/src/lib.rs b/crates/iso-store/src/lib.rs new file mode 100644 index 0000000..19e6bc1 --- /dev/null +++ b/crates/iso-store/src/lib.rs @@ -0,0 +1,31 @@ +//! ISO store: uploads, listing, introspection, boot-entry generation. +//! +//! An ISO goes through three states: +//! 1. **Uploading** — bytes streaming to a `.partial` file under `iso_dir`. +//! 2. **Introspecting** — once upload completes, we probe the ISO to detect +//! the distro family and extract kernel/initrd if applicable. Metadata +//! persisted as a sibling `.meta.json` file. +//! 3. **Ready** — listed in the menu, servable over HTTP. +//! +//! Introspection is best-effort. If we can't identify the distro, the ISO is +//! still bootable via a generic `memdisk`/`sanboot` fallback path (not +//! recommended but better than nothing). +//! +//! The `smb` submodule needs exactly one `unsafe` call to `libc::kill` for +//! SIGHUP-based Samba reload — the call is documented inline and every +//! other file in this crate is `#![forbid(unsafe_code)]`-equivalent via +//! the workspace lints. + +pub mod entry; +pub mod introspect; +pub mod nfs; +pub mod smb; +pub mod store; +pub mod windows; + +pub use entry::{BootEntry, BootKind, KernelArgs}; +pub use introspect::{DistroFamily, IntrospectionReport}; +pub use nfs::{NfsAddRequest, NfsManager, NfsMount, NfsVersion}; +pub use smb::{extract_windows_iso, SmbManager, SmbState}; +pub use store::{generate_boot_entries_for, slugify_str, IsoMeta, IsoSource, IsoStore, UploadHandle}; +pub use windows::{WimPatcher, WinPatchState}; diff --git a/crates/iso-store/src/nfs.rs b/crates/iso-store/src/nfs.rs new file mode 100644 index 0000000..a105a66 --- /dev/null +++ b/crates/iso-store/src/nfs.rs @@ -0,0 +1,564 @@ +//! NFS share manager. +//! +//! Lets an operator mount a remote NFS export as an ISO source instead of +//! uploading every ISO into the container's PVC. Supports NFSv3 and +//! NFSv4.1 — the two versions the user explicitly asked for. +//! +//! ## How it works +//! +//! 1. Operator submits a mount spec via the Storage tab: +//! `{ server: "10.0.0.20", export: "/srv/isos", version: "v41" }`. +//! 2. We slugify a stable id, mkdir `/nfs//`, then shell out +//! to `/bin/mount -t nfs -o vers=...,ro,nolock server:export local`. +//! 3. On success we walk the mount point looking for `*.iso` files and +//! register each one with the `IsoStore` as an external source — same +//! introspection pipeline as a web upload, but no sha256 (the bytes +//! live on a remote machine; hashing them would suck them through the +//! network on every restart). +//! 4. On failure we record `last_error` on the spec and persist anyway +//! so the UI can show a row in red rather than silently dropping it. +//! +//! ## Operational notes +//! +//! - Mounting NFS inside a container needs `CAP_SYS_ADMIN` and the +//! `nfs-common` package. The default image ships these (see Dockerfile). +//! - On OpenShift, the SCC must allow `CAP_SYS_ADMIN`. The bundled SCC +//! doesn't — operators have to opt in by switching to a more privileged +//! SCC or running NFS mounts as a CSI driver outside the pod. +//! - Mount commands are issued sequentially under a single mutex to avoid +//! `mount` racing on the same target dir. +//! +//! ## Persistence +//! +//! Mount specs (without runtime state) live at `/nfs.json`, +//! re-mounted on startup. Mounts that fail to come back online keep their +//! spec and their `last_error` so the operator sees what happened. + +use crate::introspect::{introspect, IntrospectionReport}; +use crate::store::{generate_boot_entries_for, slugify_str, IsoSource, IsoStore}; +use parking_lot::Mutex; +use pxeforge_core::{Error, Result}; +use serde::{Deserialize, Serialize}; +use std::collections::HashMap; +use std::path::{Path, PathBuf}; +use std::sync::Arc; +use time::OffsetDateTime; +use tokio::process::Command; + +/// Wire-protocol versions we support. Keep this enum closed — silently +/// accepting "auto" or letting the kernel negotiate would mean operators +/// could never confirm which version is in use. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "lowercase")] +pub enum NfsVersion { + /// NFSv3 — UDP/TCP, separate `mountd` protocol. Required for many + /// older NAS appliances. + V3, + /// NFSv4.1 — single TCP port (2049), session-based. Modern default. + V41, +} + +impl NfsVersion { + fn vers_arg(self) -> &'static str { + match self { + Self::V3 => "vers=3", + Self::V41 => "vers=4.1", + } + } +} + +/// One configured mount. The id is generated from server+export so the +/// operator can re-add the same export idempotently. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct NfsMount { + pub id: String, + pub server: String, + pub export: String, + pub version: NfsVersion, + /// Read-only by default — most ISO libraries are. Operators that need + /// write can flip this off but PXEForge itself never writes. + pub read_only: bool, + /// Local mount point under `/nfs/`. + pub local_path: PathBuf, + /// Whether the mount is currently active. + pub mounted: bool, + /// Last error encountered on a `mount` or `umount` attempt; cleared on + /// success. + pub last_error: Option, + #[serde(with = "time::serde::rfc3339::option")] + pub last_attempt: Option, + /// Number of `.iso` files found on the share (re-counted on each scan). + pub iso_count: u32, +} + +/// Spec submitted by the UI. Server and export are normalized before use. +#[derive(Debug, Clone, Deserialize)] +pub struct NfsAddRequest { + pub server: String, + pub export: String, + #[serde(default = "default_version")] + pub version: NfsVersion, + #[serde(default = "default_ro")] + pub read_only: bool, +} + +fn default_version() -> NfsVersion { + NfsVersion::V41 +} +fn default_ro() -> bool { + true +} + +#[derive(Debug, Default)] +struct Inner { + mounts: HashMap, +} + +/// Manages NFS mounts and surfaces them as ISO sources. +/// +/// Cheap to clone — internal state is `Arc>`. +#[derive(Debug, Clone)] +pub struct NfsManager { + work_root: Arc, + state_path: Arc, + inner: Arc>, + iso_store: IsoStore, + /// Single-writer lock around the actual `mount`/`umount` shell-outs; + /// avoids racing on the same target directory. + mount_lock: Arc>, +} + +impl NfsManager { + /// Construct a manager rooted at `work_dir`. Mount points live under + /// `/nfs//`. State persists to `/nfs.json`. + #[must_use] + pub fn new(work_dir: &Path, iso_store: IsoStore) -> Self { + let work_root = work_dir.join("nfs"); + let state_path = work_dir.join("nfs.json"); + Self { + work_root: Arc::new(work_root), + state_path: Arc::new(state_path), + inner: Arc::new(Mutex::new(Inner::default())), + iso_store, + mount_lock: Arc::new(tokio::sync::Mutex::new(())), + } + } + + /// Where this manager mounts shares. Used by `IsoStore` to resolve + /// NFS-backed `IsoMeta`s to their on-disk path. + #[must_use] + pub fn mount_root(&self) -> PathBuf { + self.work_root.as_ref().clone() + } + + /// Load persisted state and re-attempt every mount. Errors are logged + /// per-mount but never fail the call — startup must not block on a + /// remote NFS server being slow. + pub async fn load_and_remount(&self) -> Result<()> { + tokio::fs::create_dir_all(self.work_root.as_path()).await?; + let mounts = match tokio::fs::read_to_string(self.state_path.as_path()).await { + Ok(text) => serde_json::from_str::>(&text).unwrap_or_default(), + Err(_) => Vec::new(), + }; + for mut m in mounts { + // Always start from "not mounted" — the kernel state was lost + // when the process died. We'll try to remount each one. + m.mounted = false; + m.last_error = None; + self.inner.lock().mounts.insert(m.id.clone(), m.clone()); + if let Err(e) = self.try_mount(&m.id).await { + tracing::warn!( + target: "pxeforge::nfs", + id = %m.id, error = %e, + "could not remount NFS share on startup" + ); + } + } + Ok(()) + } + + /// Add a new mount. Returns the resulting `NfsMount` (with `mounted` + /// reflecting reality) or an error if the spec was invalid. + pub async fn add(&self, req: NfsAddRequest) -> Result { + let server = req.server.trim().to_string(); + let export = req.export.trim().to_string(); + if server.is_empty() { + return Err(Error::Invalid("server is required".into())); + } + if !export.starts_with('/') { + return Err(Error::Invalid("export path must start with '/'".into())); + } + + let id = mount_id(&server, &export); + let local_path = self.work_root.join(&id); + tokio::fs::create_dir_all(&local_path).await?; + + let mount = NfsMount { + id: id.clone(), + server, + export, + version: req.version, + read_only: req.read_only, + local_path, + mounted: false, + last_error: None, + last_attempt: None, + iso_count: 0, + }; + self.inner.lock().mounts.insert(id.clone(), mount); + self.persist_locked(); + self.try_mount(&id).await?; + Ok(self.get(&id).expect("mount just inserted")) + } + + /// Unmount and forget a share. Removes any ISOs it contributed from + /// the IsoStore and deletes the local mount point. Idempotent. + pub async fn remove(&self, id: &str) -> Result<()> { + // Best-effort umount; even if it fails (e.g. server unreachable) + // we still want to drop the in-memory record. + let _ = self.umount_one(id).await; + let local_path = { + let mut g = self.inner.lock(); + g.mounts.remove(id).map(|m| m.local_path) + }; + self.persist_locked(); + self.iso_store.drop_external_source(id); + if let Some(p) = local_path { + // rmdir only — never recurse, the mount could still be live + // on some kernel error path and we don't want to nuke a + // remote filesystem. + let _ = tokio::fs::remove_dir(&p).await; + } + Ok(()) + } + + /// Re-scan a mounted share for ISOs, refreshing the IsoStore. + pub async fn rescan(&self, id: &str) -> Result { + let mount = self + .get(id) + .ok_or_else(|| Error::Invalid(format!("no such mount '{id}'")))?; + if !mount.mounted { + return Err(Error::Invalid(format!("mount '{id}' is not active"))); + } + let count = self.scan_and_register(&mount).await?; + if let Some(m) = self.inner.lock().mounts.get_mut(id) { + m.iso_count = count; + } + self.persist_locked(); + Ok(count) + } + + /// Snapshot of every configured mount. + #[must_use] + pub fn list(&self) -> Vec { + let g = self.inner.lock(); + let mut v: Vec<_> = g.mounts.values().cloned().collect(); + v.sort_by(|a, b| a.id.cmp(&b.id)); + v + } + + /// Look up a single mount by id. + #[must_use] + pub fn get(&self, id: &str) -> Option { + self.inner.lock().mounts.get(id).cloned() + } + + // ── internals ───────────────────────────────────────────────────── + + async fn try_mount(&self, id: &str) -> Result<()> { + let _g = self.mount_lock.lock().await; + + let m = self + .get(id) + .ok_or_else(|| Error::Invalid(format!("no such mount '{id}'")))?; + let now = OffsetDateTime::now_utc(); + + // Already mounted? Skip — `mount` would error on a busy target + // and confuse the operator's UI status. + if is_mountpoint(&m.local_path).await { + self.update_status(id, true, None, now); + // Even though already mounted, we still want a fresh ISO count. + let count = self.scan_and_register(&m).await.unwrap_or(0); + self.update_iso_count(id, count); + return Ok(()); + } + + let opts = mount_options(&m); + let target = format!("{}:{}", m.server, m.export); + + let output = Command::new("mount") + .arg("-t") + .arg("nfs") + .arg("-o") + .arg(&opts) + .arg(&target) + .arg(&m.local_path) + .output() + .await; + + match output { + Ok(out) if out.status.success() => { + tracing::info!( + target: "pxeforge::nfs", + id = %id, server = %m.server, export = %m.export, + version = ?m.version, + "NFS mount succeeded" + ); + self.update_status(id, true, None, now); + let count = self.scan_and_register(&m).await.unwrap_or(0); + self.update_iso_count(id, count); + Ok(()) + } + Ok(out) => { + let err = format!( + "mount exit {}: {}", + out.status.code().unwrap_or(-1), + String::from_utf8_lossy(&out.stderr).trim() + ); + tracing::warn!(target: "pxeforge::nfs", id = %id, "{err}"); + self.update_status(id, false, Some(err.clone()), now); + Err(Error::Invalid(err)) + } + Err(e) => { + let err = format!("could not exec /bin/mount: {e}"); + tracing::error!(target: "pxeforge::nfs", id = %id, "{err}"); + self.update_status(id, false, Some(err.clone()), now); + Err(Error::Invalid(err)) + } + } + } + + async fn umount_one(&self, id: &str) -> Result<()> { + let _g = self.mount_lock.lock().await; + let Some(m) = self.get(id) else { return Ok(()) }; + if !is_mountpoint(&m.local_path).await { + self.update_status(id, false, None, OffsetDateTime::now_utc()); + return Ok(()); + } + // -l = lazy: detach immediately, finish when no process has a + // handle. Important if a stale ISO read is still in flight. + let out = Command::new("umount") + .arg("-l") + .arg(&m.local_path) + .output() + .await; + match out { + Ok(o) if o.status.success() => { + self.update_status(id, false, None, OffsetDateTime::now_utc()); + Ok(()) + } + Ok(o) => { + let e = format!( + "umount exit {}: {}", + o.status.code().unwrap_or(-1), + String::from_utf8_lossy(&o.stderr).trim() + ); + self.update_status(id, false, Some(e.clone()), OffsetDateTime::now_utc()); + Err(Error::Invalid(e)) + } + Err(e) => { + let e = format!("could not exec /bin/umount: {e}"); + self.update_status(id, false, Some(e.clone()), OffsetDateTime::now_utc()); + Err(Error::Invalid(e)) + } + } + } + + /// Walk the mount point for `*.iso` files, introspect each one, and + /// register it with the IsoStore as an NFS-sourced entry. Returns the + /// count of ISOs registered. + async fn scan_and_register(&self, m: &NfsMount) -> Result { + // Drop any prior entries from this mount before re-registering, so + // a removed file disappears from the store. + self.iso_store.drop_external_source(&m.id); + + let mut walker = tokio::fs::read_dir(&m.local_path).await?; + let mut count = 0u32; + while let Some(entry) = walker.next_entry().await? { + let p = entry.path(); + if p.extension() + .and_then(|e| e.to_str()) + .map(str::to_ascii_lowercase) + .as_deref() + != Some("iso") + { + continue; + } + let filename = match p.file_name().and_then(|s| s.to_str()) { + Some(f) => f.to_string(), + None => continue, + }; + let size = tokio::fs::metadata(&p).await?.len(); + // Introspection is sync + IO-bound (reads ISO9660 PVD). Push + // it to a blocking thread so the runtime stays responsive on + // a slow share. + let p_owned = p.clone(); + let report: IntrospectionReport = + tokio::task::spawn_blocking(move || introspect(&p_owned)) + .await + .map_err(|e| Error::Other(e.into()))?; + let id = format!("nfs-{}-{}", m.id, slugify_str(&filename)); + let boot_entries = generate_boot_entries_for(&id, &filename, &report); + let source = IsoSource::Nfs { + mount_id: m.id.clone(), + relative_path: filename.clone(), + }; + self.iso_store.register_external( + id, + filename, + size, + report, + boot_entries, + source, + ); + count += 1; + } + Ok(count) + } + + fn update_status(&self, id: &str, mounted: bool, err: Option, ts: OffsetDateTime) { + if let Some(m) = self.inner.lock().mounts.get_mut(id) { + m.mounted = mounted; + m.last_error = err; + m.last_attempt = Some(ts); + } + self.persist_locked(); + } + + fn update_iso_count(&self, id: &str, count: u32) { + if let Some(m) = self.inner.lock().mounts.get_mut(id) { + m.iso_count = count; + } + self.persist_locked(); + } + + /// Atomically replace the on-disk JSON with the current state. + /// Persistence errors are logged, never propagated — settings live in + /// memory authoritatively, matching the SettingsStore policy. + fn persist_locked(&self) { + let mounts: Vec = self.inner.lock().mounts.values().cloned().collect(); + let path = self.state_path.as_path(); + let tmp = path.with_extension("json.tmp"); + let body = match serde_json::to_vec_pretty(&mounts) { + Ok(b) => b, + Err(e) => { + tracing::warn!(target: "pxeforge::nfs", "serialize NFS state: {e}"); + return; + } + }; + if let Some(parent) = path.parent() { + let _ = std::fs::create_dir_all(parent); + } + if let Err(e) = std::fs::write(&tmp, body) { + tracing::warn!(target: "pxeforge::nfs", "write NFS state tmp: {e}"); + return; + } + if let Err(e) = std::fs::rename(&tmp, path) { + tracing::warn!(target: "pxeforge::nfs", "rename NFS state: {e}"); + } + } +} + +fn mount_options(m: &NfsMount) -> String { + let mut opts = vec![m.version.vers_arg().to_string()]; + if m.read_only { + opts.push("ro".into()); + } else { + opts.push("rw".into()); + } + // `nolock` for v3 — many storage appliances disable lockd; we don't + // need locking for read-only ISO access anyway. + if matches!(m.version, NfsVersion::V3) { + opts.push("nolock".into()); + } + // Soft mount with a generous timeout — better to surface a hung share + // as a user-visible error than to wedge the iPXE client forever on a + // dead NFS server. + opts.push("soft".into()); + opts.push("timeo=100".into()); + opts.push("retrans=3".into()); + opts.join(",") +} + +fn mount_id(server: &str, export: &str) -> String { + let raw = format!("{server}{export}"); + slugify_str(&raw) +} + +/// Detect whether `path` is currently a mount point. We don't have +/// `is_mountpoint(2)`, so compare the parent's device id to the dir's; +/// if they differ the dir is a mount. +async fn is_mountpoint(path: &Path) -> bool { + let Some(parent) = path.parent() else { + return false; + }; + let Ok(m1) = tokio::fs::metadata(path).await else { + return false; + }; + let Ok(m2) = tokio::fs::metadata(parent).await else { + return false; + }; + use std::os::unix::fs::MetadataExt; + m1.dev() != m2.dev() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn version_arg() { + assert_eq!(NfsVersion::V3.vers_arg(), "vers=3"); + assert_eq!(NfsVersion::V41.vers_arg(), "vers=4.1"); + } + + #[test] + fn mount_options_v3_includes_nolock() { + let m = NfsMount { + id: "x".into(), + server: "s".into(), + export: "/e".into(), + version: NfsVersion::V3, + read_only: true, + local_path: PathBuf::from("/tmp/x"), + mounted: false, + last_error: None, + last_attempt: None, + iso_count: 0, + }; + let opts = mount_options(&m); + assert!(opts.contains("vers=3")); + assert!(opts.contains("ro")); + assert!(opts.contains("nolock")); + assert!(opts.contains("soft")); + } + + #[test] + fn mount_options_v41_no_nolock() { + let m = NfsMount { + id: "x".into(), + server: "s".into(), + export: "/e".into(), + version: NfsVersion::V41, + read_only: false, + local_path: PathBuf::from("/tmp/x"), + mounted: false, + last_error: None, + last_attempt: None, + iso_count: 0, + }; + let opts = mount_options(&m); + assert!(opts.contains("vers=4.1")); + assert!(opts.contains("rw")); + assert!(!opts.contains("nolock")); + } + + #[test] + fn mount_id_is_stable_and_safe() { + let a = mount_id("10.0.0.5", "/srv/isos"); + let b = mount_id("10.0.0.5", "/srv/isos"); + assert_eq!(a, b); + assert!(!a.contains('/')); + assert!(!a.contains('.')); + } +} diff --git a/crates/iso-store/src/smb.rs b/crates/iso-store/src/smb.rs new file mode 100644 index 0000000..93290c9 --- /dev/null +++ b/crates/iso-store/src/smb.rs @@ -0,0 +1,343 @@ +//! SMB share manager. Spawns and supervises `smbd` for serving extracted +//! Windows install trees on port 445. This is the server side of the +//! Bootimus-pattern Windows boot: WinPE does `net use Z: \\server\` +//! and runs Setup from there. +//! +//! Lifecycle: +//! +//! 1. Web UI toggles `windows_enabled = true` → `SmbManager::start()`. +//! We write an `smb.conf` that declares one share per extracted +//! Windows ISO, then `smbd --foreground --no-process-group`. +//! 2. When a Windows ISO is uploaded, `extract_windows_iso()` unpacks +//! it under `smb_dir//` and `SmbManager::reconcile_shares()` +//! rewrites `smb.conf` and signals smbd to reload (SIGHUP). +//! 3. When the toggle flips off, `stop()` sends SIGTERM to smbd and +//! leaves the extracted trees in place (in case the toggle comes +//! back on). +//! +//! Safety posture: +//! - Guest-mode SMB, read-only (`writable = no`, `guest ok = yes`). +//! - SMB2 minimum (no SMB1 legacy, not needed for WinPE). +//! - Bound to 0.0.0.0:445; operator MUST put this on a trusted install +//! VLAN — guest SMB is not for the general internet. +//! - smbd runs as the same non-root uid as pxeforge (10001). +//! - If `smbd` isn't on PATH (e.g. lightweight container build without +//! Samba), we return `SmbState::SmbdMissing` and the UI surfaces the +//! gap. No panics, no retries, no silent failure. + +use serde::{Deserialize, Serialize}; +use std::path::{Path, PathBuf}; +use std::process::{Child, Command, Stdio}; +use std::sync::Arc; +use parking_lot::Mutex; + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[serde(rename_all = "snake_case", tag = "state")] +pub enum SmbState { + /// Windows support is off — smbd not running. + Disabled, + /// `smbd` is missing from the image. Operator enabled Windows but the + /// runtime container didn't include Samba. + SmbdMissing, + /// Started and healthy. + Running { pid: u32, shares: Vec }, + /// Tried to start but smbd exited. Reason is captured for the UI. + Failed { reason: String }, +} + +pub struct SmbManager { + smb_dir: PathBuf, + conf_path: PathBuf, + child: Arc>>, + state: Arc>, +} + +impl SmbManager { + pub fn new(smb_dir: PathBuf) -> Self { + let conf_path = smb_dir.join("smb.conf"); + Self { + smb_dir, + conf_path, + child: Arc::new(Mutex::new(None)), + state: Arc::new(Mutex::new(SmbState::Disabled)), + } + } + + #[must_use] + pub fn snapshot(&self) -> SmbState { + self.state.lock().clone() + } + + /// Enumerate `/*/` sub-dirs as shares. An extracted Windows + /// ISO under `smb_dir//` becomes a share named ``. Returns + /// the sorted list. + pub fn discover_shares(&self) -> Vec { + let Ok(rd) = std::fs::read_dir(&self.smb_dir) else { return vec![]; }; + let mut out: Vec = rd + .flatten() + .filter(|e| e.path().is_dir()) + .filter_map(|e| e.file_name().to_str().map(str::to_owned)) + // Ignore hidden / internal dirs. + .filter(|n| !n.starts_with('.') && n != "tmp") + .collect(); + out.sort(); + out + } + + /// Write out `smb.conf` for the currently-discovered shares. Safe to + /// call while smbd is running — smbd reloads on SIGHUP. + pub fn write_conf(&self) -> std::io::Result> { + std::fs::create_dir_all(&self.smb_dir)?; + let shares = self.discover_shares(); + let mut conf = String::new(); + conf.push_str(SMB_CONF_GLOBAL); + for name in &shares { + let path = self.smb_dir.join(name); + conf.push_str(&format!( + "\n[{name}]\n\ + path = {}\n\ + comment = PXEForge Windows install media ({name})\n\ + read only = yes\n\ + guest ok = yes\n\ + guest only = yes\n\ + browseable = yes\n\ + available = yes\n", + path.display(), + )); + } + let tmp = self.conf_path.with_extension("conf.tmp"); + std::fs::write(&tmp, conf)?; + std::fs::rename(tmp, &self.conf_path)?; + Ok(shares) + } + + /// Start smbd. No-op if already running. + pub fn start(&self) -> SmbState { + let mut g = self.child.lock(); + if g.as_ref().map_or(false, |c| c.id() > 0) { + return self.state.lock().clone(); + } + if !smbd_present() { + let s = SmbState::SmbdMissing; + *self.state.lock() = s.clone(); + return s; + } + let shares = match self.write_conf() { + Ok(v) => v, + Err(e) => { + let s = SmbState::Failed { reason: format!("write smb.conf: {e}") }; + *self.state.lock() = s.clone(); + return s; + } + }; + let child = Command::new("smbd") + .args([ + "--foreground", + "--no-process-group", + "--configfile", self.conf_path.to_str().unwrap_or(""), + "--log-stdout", + ]) + .stdin(Stdio::null()) + .stdout(Stdio::inherit()) + .stderr(Stdio::inherit()) + .spawn(); + match child { + Ok(c) => { + let pid = c.id(); + *g = Some(c); + let s = SmbState::Running { pid, shares }; + *self.state.lock() = s.clone(); + tracing::info!(target: "pxeforge::smb", pid, shares=?self.state.lock(), "smbd started"); + s + } + Err(e) => { + let s = SmbState::Failed { reason: format!("spawn smbd: {e}") }; + *self.state.lock() = s.clone(); + s + } + } + } + + /// Rewrite smb.conf and SIGHUP smbd so it picks up new/removed shares. + /// No-op if smbd isn't running. + #[allow(unsafe_code)] + pub fn reconcile(&self) -> SmbState { + let mut g = self.child.lock(); + if g.is_none() { return self.state.lock().clone(); } + let shares = match self.write_conf() { + Ok(v) => v, + Err(e) => { + let s = SmbState::Failed { reason: format!("write smb.conf: {e}") }; + *self.state.lock() = s.clone(); + return s; + } + }; + if let Some(c) = g.as_mut() { + let pid = c.id() as i32; + // SAFETY: libc::kill is FFI-safe; we pass a pid we own (returned + // from `Child::id` above, the child is alive because we hold the + // Mutex guard `g`) and a well-defined signal constant. Return + // value ignored because there's no meaningful recovery if SIGHUP + // fails — the next reconcile will retry. + // Rationale for not using a safe wrapper: the only crate that + // covers this is `nix`, which pulls ~40 transitive deps for a + // single signal send. One documented unsafe call is the better + // tradeoff for a container-first project. + unsafe { libc::kill(pid, libc::SIGHUP); } + let s = SmbState::Running { pid: pid as u32, shares }; + *self.state.lock() = s.clone(); + s + } else { + self.state.lock().clone() + } + } + + /// Stop smbd. Safe to call repeatedly. + pub fn stop(&self) { + let mut g = self.child.lock(); + if let Some(mut c) = g.take() { + let _ = c.kill(); + let _ = c.wait(); + } + *self.state.lock() = SmbState::Disabled; + } +} + +fn smbd_present() -> bool { + let Ok(paths) = std::env::var("PATH") else { return false; }; + for dir in std::env::split_paths(&paths) { + if dir.join("smbd").is_file() { return true; } + } + false +} + +const SMB_CONF_GLOBAL: &str = r#"[global] +workgroup = PXEFORGE +server min protocol = SMB2 +smb ports = 445 +log level = 1 +max log size = 1024 +disable netbios = yes +server role = standalone +map to guest = Bad User +guest account = nobody +# Anchor to container-friendly paths; tdb + log files under the data dir +# so a read-only rootfs in OpenShift doesn't block Samba. +lock directory = /tmp +state directory = /tmp +cache directory = /tmp +pid directory = /tmp +"#; + +/// Extract a Windows ISO at `iso_path` into `smb_dir//`. Uses +/// `7z` when available (most reliable for UDF + ISO9660 hybrid images); +/// falls back to `bsdtar -xf` which also handles UDF on many distros. +/// Returns the share name (i.e. the slug) on success. +/// +/// Idempotent: if the target dir already contains `sources/boot.wim`, we +/// skip extraction. Callers who want a forced re-extract should remove the +/// dir first. +pub fn extract_windows_iso(iso_path: &Path, smb_dir: &Path, slug: &str) -> std::io::Result { + let target = smb_dir.join(slug); + if target.join("sources").join("boot.wim").is_file() { + tracing::debug!(target: "pxeforge::smb", slug, "ISO already extracted, skipping"); + return Ok(target); + } + std::fs::create_dir_all(&target)?; + + // Try 7z first. + if which("7z").is_some() { + let out = Command::new("7z") + .args(["x", "-y", "-bd", "-bb0"]) + .arg(format!("-o{}", target.display())) + .arg(iso_path) + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::piped()) + .output()?; + if out.status.success() { return Ok(target); } + tracing::warn!( + target: "pxeforge::smb", + stderr=%String::from_utf8_lossy(&out.stderr), + "7z extract failed, trying bsdtar" + ); + } + // bsdtar fallback. + if which("bsdtar").is_some() { + let out = Command::new("bsdtar") + .args(["-xf"]) + .arg(iso_path) + .args(["-C"]) + .arg(&target) + .output()?; + if out.status.success() { return Ok(target); } + return Err(std::io::Error::new( + std::io::ErrorKind::Other, + format!("bsdtar failed: {}", String::from_utf8_lossy(&out.stderr)), + )); + } + Err(std::io::Error::new( + std::io::ErrorKind::NotFound, + "neither 7z nor bsdtar available for ISO extraction", + )) +} + +fn which(cmd: &str) -> Option { + let paths = std::env::var_os("PATH")?; + for dir in std::env::split_paths(&paths) { + let p = dir.join(cmd); + if p.is_file() { return Some(p); } + } + None +} + +#[cfg(test)] +mod tests { + use super::*; + use tempfile::tempdir; + + #[test] + fn disabled_by_default() { + let dir = tempdir().unwrap(); + let m = SmbManager::new(dir.path().into()); + assert_eq!(m.snapshot(), SmbState::Disabled); + } + + #[test] + fn start_without_smbd_reports_missing() { + // Drop smbd from PATH for this test. + let saved = std::env::var_os("PATH"); + std::env::set_var("PATH", "/usr/nowhere-pxeforge-test"); + let dir = tempdir().unwrap(); + let m = SmbManager::new(dir.path().into()); + let st = m.start(); + // Restore PATH before asserting so any subsequent failure is legible. + if let Some(p) = saved { std::env::set_var("PATH", p); } + assert_eq!(st, SmbState::SmbdMissing); + } + + #[test] + fn discover_shares_lists_iso_subdirs() { + let dir = tempdir().unwrap(); + std::fs::create_dir_all(dir.path().join("win10-pro")).unwrap(); + std::fs::create_dir_all(dir.path().join("win11")).unwrap(); + std::fs::create_dir_all(dir.path().join(".hidden")).unwrap(); + let m = SmbManager::new(dir.path().into()); + assert_eq!(m.discover_shares(), vec!["win10-pro", "win11"]); + } + + #[test] + fn write_conf_emits_share_blocks() { + let dir = tempdir().unwrap(); + std::fs::create_dir_all(dir.path().join("win10")).unwrap(); + let m = SmbManager::new(dir.path().into()); + let shares = m.write_conf().unwrap(); + assert_eq!(shares, vec!["win10"]); + let conf = std::fs::read_to_string(dir.path().join("smb.conf")).unwrap(); + assert!(conf.contains("[global]")); + assert!(conf.contains("[win10]")); + assert!(conf.contains("guest ok = yes")); + assert!(conf.contains("read only = yes")); + assert!(conf.contains("server min protocol = SMB2")); + } +} diff --git a/crates/iso-store/src/store.rs b/crates/iso-store/src/store.rs new file mode 100644 index 0000000..7cda264 --- /dev/null +++ b/crates/iso-store/src/store.rs @@ -0,0 +1,430 @@ +//! On-disk ISO store with sidecar metadata files. + +use crate::entry::{BootEntry, BootKind, KernelArgs}; +use crate::introspect::{introspect, DistroFamily, IntrospectionReport}; +use bytes::Bytes; +use parking_lot::RwLock; +use pxeforge_core::{Error, Result}; +use serde::{Deserialize, Serialize}; +use sha2::{Digest, Sha256}; +use std::collections::HashMap; +use std::path::{Path, PathBuf}; +use std::sync::Arc; +use time::OffsetDateTime; +use tokio::io::AsyncWriteExt; + +/// Where the bytes for an ISO actually live. +/// +/// The default is `Local` — uploaded ISOs sit in `/.iso`. +/// `Nfs` entries point at a file inside a remote share that the +/// `NfsManager` is keeping mounted. We resolve the on-disk path lazily +/// in [`IsoStore::iso_path_for`] using the `nfs_root` set at startup. +#[derive(Debug, Clone, Serialize, Deserialize)] +#[serde(tag = "kind", rename_all = "snake_case")] +pub enum IsoSource { + Local, + Nfs { + mount_id: String, + /// Path relative to the mount point — typically just the filename. + relative_path: String, + }, +} + +impl Default for IsoSource { + fn default() -> Self { + Self::Local + } +} + +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct IsoMeta { + /// Stable slug used in URLs (derived from the uploaded filename). + pub id: String, + pub filename: String, + pub size_bytes: u64, + pub sha256_hex: Option, + #[serde(with = "time::serde::rfc3339")] + pub uploaded_at: OffsetDateTime, + pub introspection: IntrospectionReport, + /// Boot entries this ISO currently exposes in the PXE menu. Usually one, + /// occasionally two (BIOS + UEFI variant for some RHEL ISOs). + pub boot_entries: Vec, + /// Source of the bytes — local upload (default) or NFS mount. + /// Old `meta.json` files without this field deserialize as `Local`. + #[serde(default)] + pub source: IsoSource, +} + +pub struct UploadHandle { + pub id: String, + pub partial_path: PathBuf, + final_path: PathBuf, + filename: String, + hasher: Sha256, + bytes_written: u64, + file: tokio::fs::File, +} + +impl UploadHandle { + pub async fn write_chunk(&mut self, chunk: &Bytes) -> Result<()> { + self.file.write_all(chunk).await?; + self.hasher.update(chunk); + self.bytes_written += chunk.len() as u64; + Ok(()) + } + + /// Flush, close, and atomically rename to the final path. Returns the + /// final `IsoMeta` including introspection results. + pub async fn finish(mut self, store: &IsoStore) -> Result { + self.file.flush().await?; + self.file.sync_all().await?; + drop(self.file); + tokio::fs::rename(&self.partial_path, &self.final_path).await?; + + let hash = hex::encode(self.hasher.finalize()); + let introspection = { + let p = self.final_path.clone(); + tokio::task::spawn_blocking(move || introspect(&p)) + .await + .map_err(|e| Error::Other(e.into()))? + }; + + let boot_entries = generate_boot_entries(&self.id, &self.filename, &introspection); + let meta = IsoMeta { + id: self.id.clone(), + filename: self.filename, + size_bytes: self.bytes_written, + sha256_hex: Some(hash), + uploaded_at: OffsetDateTime::now_utc(), + introspection, + boot_entries, + source: IsoSource::Local, + }; + store.persist_meta(&meta).await?; + store.insert(meta.clone()); + Ok(meta) + } + + pub async fn abort(self) -> Result<()> { + drop(self.file); + let _ = tokio::fs::remove_file(&self.partial_path).await; + Ok(()) + } +} + +#[derive(Debug, Default)] +struct Inner { + isos: HashMap, +} + +#[derive(Debug, Clone)] +pub struct IsoStore { + iso_dir: Arc, + /// Where NFS mounts land on disk. Set at startup via + /// [`IsoStore::set_nfs_root`]; required for resolving any + /// `IsoSource::Nfs` entry. + nfs_root: Arc>>, + inner: Arc>, +} + +impl IsoStore { + pub fn new(iso_dir: PathBuf) -> Self { + Self { + iso_dir: Arc::new(iso_dir), + nfs_root: Arc::new(RwLock::new(None)), + inner: Arc::new(RwLock::new(Inner::default())), + } + } + + /// Tell the store where NFS mounts live. Without this set, + /// `IsoSource::Nfs` entries cannot be resolved to a file path. + pub fn set_nfs_root(&self, root: PathBuf) { + *self.nfs_root.write() = Some(root); + } + + pub async fn ensure_dirs(&self) -> Result<()> { + tokio::fs::create_dir_all(self.iso_dir.as_path()).await?; + Ok(()) + } + + /// Scan the ISO directory on startup and load any sidecar `.meta.json` + /// files. ISOs without metadata are introspected lazily — we don't block + /// startup on potentially many GB of scanning. + pub async fn load_from_disk(&self) -> Result<()> { + self.ensure_dirs().await?; + let mut entries = tokio::fs::read_dir(self.iso_dir.as_path()).await?; + while let Some(e) = entries.next_entry().await? { + let p = e.path(); + if p.extension().and_then(|s| s.to_str()) != Some("json") { continue; } + if !p.file_name().and_then(|s| s.to_str()).map_or(false, |n| n.ends_with(".meta.json")) { + continue; + } + if let Ok(text) = tokio::fs::read_to_string(&p).await { + if let Ok(meta) = serde_json::from_str::(&text) { + self.insert(meta); + } + } + } + Ok(()) + } + + fn insert(&self, meta: IsoMeta) { + self.inner.write().isos.insert(meta.id.clone(), meta); + } + + async fn persist_meta(&self, meta: &IsoMeta) -> Result<()> { + let path = self.meta_path(&meta.id); + let text = serde_json::to_string_pretty(meta).map_err(|e| Error::Other(e.into()))?; + tokio::fs::write(path, text).await?; + Ok(()) + } + + fn meta_path(&self, id: &str) -> PathBuf { + self.iso_dir.join(format!("{id}.meta.json")) + } + + fn iso_path(&self, id: &str) -> PathBuf { + self.iso_dir.join(format!("{id}.iso")) + } + + pub async fn begin_upload(&self, filename: &str) -> Result { + self.ensure_dirs().await?; + let id = slugify(filename); + let final_path = self.iso_path(&id); + if final_path.exists() { + return Err(Error::Invalid(format!("iso '{id}' already exists"))); + } + let partial_path = self.iso_dir.join(format!("{id}.partial")); + let file = tokio::fs::File::create(&partial_path).await?; + Ok(UploadHandle { + id, + partial_path, + final_path, + filename: filename.to_string(), + hasher: Sha256::new(), + bytes_written: 0, + file, + }) + } + + /// Readiness probe — is the backing directory reachable? Distinct from + /// "is there content in it", to avoid an empty store failing health. + #[must_use] + pub fn list_ok(&self) -> bool { + std::fs::read_dir(self.iso_dir.as_path()).is_ok() + } + + #[must_use] + pub fn list(&self) -> Vec { + let g = self.inner.read(); + let mut v: Vec<_> = g.isos.values().cloned().collect(); + v.sort_by(|a, b| b.uploaded_at.cmp(&a.uploaded_at)); + v + } + + #[must_use] + pub fn get(&self, id: &str) -> Option { + self.inner.read().isos.get(id).cloned() + } + + /// Resolve an ISO id to its on-disk path, if any. For local entries + /// this is `/.iso`; for NFS entries it's + /// `//`. Returns None if the file + /// is missing or the source isn't resolvable (e.g. NFS share + /// unmounted). + pub fn iso_path_for(&self, id: &str) -> Option { + let meta = self.get(id)?; + let path = match &meta.source { + IsoSource::Local => self.iso_path(id), + IsoSource::Nfs { + mount_id, + relative_path, + } => { + let root = self.nfs_root.read().clone()?; + root.join(mount_id).join(relative_path) + } + }; + if path.exists() { + Some(path) + } else { + None + } + } + + /// Delete an ISO and its sidecar metadata. Only acts on local ISOs; + /// for NFS-backed ISOs the operator must remove the file from the + /// share or unmount the NFS share entirely. + pub async fn delete(&self, id: &str) -> Result<()> { + let meta = self.get(id); + let is_local = matches!(meta.as_ref().map(|m| &m.source), Some(IsoSource::Local) | None); + if is_local { + let iso = self.iso_path(id); + let meta_path = self.meta_path(id); + let _ = tokio::fs::remove_file(&iso).await; + let _ = tokio::fs::remove_file(&meta_path).await; + } + self.inner.write().isos.remove(id); + Ok(()) + } + + /// Register an externally-sourced ISO (e.g. NFS-mounted). Used by + /// `NfsManager` after walking a freshly-mounted share. We do **not** + /// persist a `meta.json` on disk for these — the source of truth is + /// the share itself, and the NFS manager re-scans on startup. + pub fn register_external( + &self, + id: String, + filename: String, + size_bytes: u64, + introspection: IntrospectionReport, + boot_entries: Vec, + source: IsoSource, + ) { + let meta = IsoMeta { + id: id.clone(), + filename, + size_bytes, + sha256_hex: None, + uploaded_at: OffsetDateTime::now_utc(), + introspection, + boot_entries, + source, + }; + self.inner.write().isos.insert(id, meta); + } + + /// Drop every entry that belongs to `mount_id`. Used by the NFS + /// manager when an operator removes a share, or before re-scanning + /// to clean out stale entries. + pub fn drop_external_source(&self, mount_id: &str) { + let mut g = self.inner.write(); + g.isos.retain(|_, m| { + !matches!(&m.source, IsoSource::Nfs { mount_id: mid, .. } if mid == mount_id) + }); + } +} + +fn slugify(filename: &str) -> String { + let stem = Path::new(filename) + .file_stem() + .and_then(|s| s.to_str()) + .unwrap_or("iso"); + slugify_str(stem) +} + +/// Slugify an arbitrary string to lowercase ASCII alphanumerics, hyphens, +/// and underscores. Public so the NFS manager can mint ids that follow the +/// same rules as upload-time ISO ids. +#[must_use] +pub fn slugify_str(input: &str) -> String { + input + .chars() + .map(|c| { + if c.is_ascii_alphanumeric() || c == '-' || c == '_' { + c.to_ascii_lowercase() + } else { + '-' + } + }) + .collect::() + .trim_matches('-') + .to_string() +} + +/// Public wrapper around [`generate_boot_entries`] so the NFS manager can +/// build entries for shares it just scanned, using the same logic as the +/// upload pipeline. Re-exported via the crate root. +#[must_use] +pub fn generate_boot_entries_for( + id: &str, + filename: &str, + r: &IntrospectionReport, +) -> Vec { + generate_boot_entries(id, filename, r) +} + +/// Build `BootEntry`s from the introspection report. URLs are relative — +/// the HTTP layer rewrites them with the public base URL per request. +fn generate_boot_entries(id: &str, filename: &str, r: &IntrospectionReport) -> Vec { + let title = r.volume_label.clone().unwrap_or_else(|| filename.to_string()); + match r.family { + DistroFamily::WindowsPe if r.has_boot_wim => { + // Standard wimboot chain. Paths are in-ISO; the HTTP layer maps + // `iso//` to on-disk extraction via ISO9660 lookup. + let base = format!("iso/{id}"); + vec![BootEntry { + id: format!("{id}-winpe"), + title: format!("{title} (Windows / wimboot)"), + kind: BootKind::Wimboot { + wimboot_url: "ipxe/wimboot".to_string(), + files: vec![ + ("bootmgr".into(), format!("{base}/bootmgr")), + ("bootmgr.efi".into(), format!("{base}/bootmgr.efi")), + ("bcd".into(), format!("{base}/boot/bcd")), + ("boot.sdi".into(), format!("{base}/boot/boot.sdi")), + ("boot.wim".into(), format!("{base}/sources/boot.wim")), + ], + }, + }] + } + fam if r.kernel_path.is_some() => { + let base = format!("iso/{id}"); + let kernel_url = format!("{base}{}", r.kernel_path.as_deref().unwrap_or("")); + let initrd_urls = r.initrd_paths.iter().map(|p| format!("{base}{p}")).collect(); + let args = KernelArgs { cmdline: linux_cmdline(fam, id) }; + vec![BootEntry { + id: format!("{id}-linux"), + title, + kind: BootKind::LinuxKernel { kernel_url, initrd_urls, args }, + }] + } + _ => { + // Last-resort SAN boot. Won't work for large modern ISOs, but + // lets the ISO at least appear in the menu. + vec![BootEntry { + id: format!("{id}-sanboot"), + title: format!("{title} (SAN boot — may fail for >1GiB ISOs)"), + kind: BootKind::SanBootIso { iso_url: format!("iso/{id}.iso") }, + }] + } + } +} + +fn linux_cmdline(family: DistroFamily, id: &str) -> String { + // The HTTP layer resolves `${base-url}` at render time. + let iso_url = format!("${{base-url}}/iso/{id}.iso"); + match family { + DistroFamily::DebianUbuntu => format!( + "boot=casper netboot=url url={iso_url} ip=dhcp ---" + ), + DistroFamily::RhelFedora => format!( + "inst.repo={iso_url} inst.stage2={iso_url} ip=dhcp" + ), + DistroFamily::OpenSuse => format!( + "install={iso_url} netsetup=dhcp" + ), + DistroFamily::Arch => format!( + "archiso_http_srv=${{base-url}}/iso/ archisobasedir=arch ip=dhcp copytoram" + ), + DistroFamily::Alpine => format!( + "alpine_repo=${{base-url}}/iso/{id}/ modloop=${{base-url}}/iso/{id}/boot/modloop-lts ip=dhcp" + ), + _ => "ip=dhcp".into(), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn slugify_basic() { + // Upload filenames come from multipart parts (no path components); + // file_stem drops the extension, then non-alphanumerics become `-`. + assert_eq!(slugify("Ubuntu 24.04 Desktop.iso"), "ubuntu-24-04-desktop"); + assert_eq!(slugify("Rocky-9.4-x86_64-dvd.iso"), "rocky-9-4-x86_64-dvd"); + assert_eq!(slugify("arch.iso"), "arch"); + // If a path sneaks in, file_stem strips the directory — OK, not a hazard. + assert_eq!(slugify("/etc/passwd"), "passwd"); + } +} diff --git a/crates/iso-store/src/windows.rs b/crates/iso-store/src/windows.rs new file mode 100644 index 0000000..4e153bc --- /dev/null +++ b/crates/iso-store/src/windows.rs @@ -0,0 +1,209 @@ +//! Windows ISO post-processing. Patches `boot.wim` (image index 2, WinPE) +//! with two plain-text files so the client hits our SMB share and runs +//! Windows Setup from there. +//! +//! Credit: the *technique* (not the code) is adapted from Bootimus +//! (Apache-2.0, https://github.com/garybowers/bootimus). We reimplement in +//! Rust and shell out to `wimlib-imagex` at container runtime because +//! there is no maintained pure-Rust wimlib binding. +//! +//! What we inject — and why these are safe: +//! +//! * `Windows/System32/winpeshl.ini`: a plain INI that WinPE reads at +//! startup and uses to launch `startnet.cmd` instead of the default +//! interactive shell. No driver, no executable, no signed code. +//! +//! * `Windows/System32/startnet.cmd`: a batch file that runs `wpeinit`, +//! waits for a DHCP lease, then `net use Z: \\\ /user:guest` +//! and invokes `Z:\setup.exe`. Everything the client executes is stock +//! Microsoft-signed WinPE + `setup.exe`. We add zero native code to +//! the client's boot path. The trust store is untouched. +//! +//! What we *do not* inject: +//! * No `.sys` drivers, signed or otherwise. +//! * No `.cer`, no registry hive edits, no `bcdedit` changes. +//! * No `bypass*` Windows 11 tweaks (operators who want those can use an +//! unattend.xml; they will never be injected silently by us). + +use std::path::{Path, PathBuf}; +use std::process::Command; + +/// Public identifier of whether/how Windows patching ran for an ISO. +/// Stored on `IsoMeta` so the UI can show a clear "SMB ready" indicator. +#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, PartialEq, Eq)] +#[serde(rename_all = "snake_case")] +pub enum WinPatchState { + /// Not a Windows ISO, nothing to do. + NotApplicable, + /// Windows ISO detected but Windows support is disabled in settings. + DisabledBySettings, + /// wimlib-imagex isn't on PATH — operator needs to install the runtime + /// dependency before Windows ISOs can be patched. + WimlibMissing, + /// Patching succeeded; the ISO's boot.wim was rewritten in-place. + Patched { smb_host: String, smb_share: String }, + /// wimlib returned an error. + Failed { reason: String }, +} + +pub struct WimPatcher { + pub smb_host: String, + pub smb_share: String, +} + +impl WimPatcher { + #[must_use] + pub fn new(smb_host: String, smb_share: String) -> Self { + Self { smb_host, smb_share } + } + + /// Apply WinPE patches to `boot.wim` inside `extracted_iso_dir`. Returns + /// a state enum — never panics. Designed to be safely re-runnable; each + /// call rebuilds image 2 from scratch via `wimlib-imagex update`. + pub fn patch(&self, extracted_iso_dir: &Path) -> WinPatchState { + if !wimlib_present() { + return WinPatchState::WimlibMissing; + } + let boot_wim = extracted_iso_dir.join("sources").join("boot.wim"); + if !boot_wim.exists() { + // Not a standard Windows install ISO layout. + return WinPatchState::NotApplicable; + } + + let work = match tempfile::tempdir() { + Ok(d) => d, + Err(e) => return WinPatchState::Failed { reason: format!("tempdir: {e}") }, + }; + + // Stage the two files we want present at /Windows/System32/. + let staging = work.path().join("stage/Windows/System32"); + if let Err(e) = std::fs::create_dir_all(&staging) { + return WinPatchState::Failed { reason: format!("staging mkdir: {e}") }; + } + if let Err(e) = std::fs::write(staging.join("winpeshl.ini"), WINPESHL_INI) { + return WinPatchState::Failed { reason: format!("write winpeshl.ini: {e}") }; + } + let startnet = render_startnet(&self.smb_host, &self.smb_share); + if let Err(e) = std::fs::write(staging.join("startnet.cmd"), startnet) { + return WinPatchState::Failed { reason: format!("write startnet.cmd: {e}") }; + } + + // Build a wimlib update command file: + // add /Windows/System32 /Windows/System32 + let update_file = work.path().join("update.cmd"); + let update_cmd = format!( + "add \"{}\" \"/Windows/System32\"\n", + staging.display() + ); + if let Err(e) = std::fs::write(&update_file, update_cmd) { + return WinPatchState::Failed { reason: format!("write update.cmd: {e}") }; + } + + // Run wimlib-imagex update against image index 2 (WinPE). + let output = Command::new("wimlib-imagex") + .arg("update") + .arg(&boot_wim) + .arg("2") + .arg("--rebuild") + .arg("--command-file") + .arg(&update_file) + .output(); + match output { + Ok(o) if o.status.success() => WinPatchState::Patched { + smb_host: self.smb_host.clone(), + smb_share: self.smb_share.clone(), + }, + Ok(o) => WinPatchState::Failed { + reason: format!( + "wimlib-imagex update failed (exit {:?}): {}", + o.status.code(), + String::from_utf8_lossy(&o.stderr) + ), + }, + Err(e) => WinPatchState::Failed { reason: format!("spawn wimlib-imagex: {e}") }, + } + } +} + +fn wimlib_present() -> bool { + which("wimlib-imagex").is_some() +} + +fn which(cmd: &str) -> Option { + let paths = std::env::var_os("PATH")?; + for dir in std::env::split_paths(&paths) { + let p = dir.join(cmd); + if p.is_file() { return Some(p); } + } + None +} + +/// The winpeshl.ini contents. This file tells WinPE "don't run cmd.exe +/// interactively; run startnet.cmd and exit when it returns". +const WINPESHL_INI: &str = "[LaunchApps]\r\n\ +\"%SYSTEMROOT%\\system32\\startnet.cmd\"\r\n"; + +/// Render startnet.cmd. The script: +/// 1. Loads WinPE networking (`wpeinit`) and renews DHCP. +/// 2. Waits until the SMB server is reachable. +/// 3. Maps the install share to Z: as guest. +/// 4. Runs setup.exe from the share. +/// +/// Uses CRLF line endings because WinPE cmd.exe requires them for .cmd files +/// created on unix hosts. +fn render_startnet(host: &str, share: &str) -> String { + let mut s = String::new(); + let host = host.trim(); + let share = share.trim_matches('/'); + s.push_str("@echo off\r\n"); + s.push_str("echo PXEForge WinPE bootstrap\r\n"); + s.push_str("wpeinit\r\n"); + s.push_str("ipconfig /renew\r\n"); + s.push_str(&format!("echo Waiting for SMB server {host} to be reachable...\r\n")); + s.push_str(&format!(":waitsmb\r\nping -n 1 -w 500 {host} >nul && goto havenet\r\ntimeout /t 2 /nobreak >nul\r\ngoto waitsmb\r\n")); + s.push_str(":havenet\r\n"); + s.push_str(&format!("echo Mapping install media from \\\\{host}\\{share}...\r\n")); + s.push_str(&format!(":mapshare\r\nnet use Z: \\\\{host}\\{share} /user:guest \"\" /persistent:no && goto mapped\r\ntimeout /t 3 /nobreak >nul\r\ngoto mapshare\r\n")); + s.push_str(":mapped\r\n"); + s.push_str("echo Starting Windows Setup\r\n"); + s.push_str("Z:\\setup.exe\r\n"); + s.push_str("echo Setup exited; dropping to cmd for diagnosis\r\n"); + s.push_str("cmd\r\n"); + s +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn startnet_has_crlf_and_no_testsigning() { + let s = render_startnet("10.0.0.5", "win11"); + assert!(s.contains("\r\n")); + // Hard guard: must never include trust-store or driver-policy mutations. + assert!(!s.to_lowercase().contains("bcdedit")); + assert!(!s.to_lowercase().contains("testsigning")); + assert!(!s.to_lowercase().contains("certutil")); + assert!(s.contains("net use Z:")); + assert!(s.contains("setup.exe")); + } + + #[test] + fn patcher_reports_wimlib_missing_gracefully() { + // We don't assume wimlib is present in CI; this checks the missing + // branch is the noisy-but-survivable one we expect. + let patcher = WimPatcher::new("10.0.0.5".into(), "win11".into()); + let dir = tempfile::tempdir().unwrap(); + // Construct a fake "sources/boot.wim". + std::fs::create_dir_all(dir.path().join("sources")).unwrap(); + std::fs::write(dir.path().join("sources/boot.wim"), b"placeholder").unwrap(); + let result = patcher.patch(dir.path()); + // Depending on whether wimlib is installed on the runner, we get + // either WimlibMissing or Failed(...). Both mean "no silent + // success with trust-store mutation" — that's the invariant. + assert!(matches!( + result, + WinPatchState::WimlibMissing | WinPatchState::Failed { .. } + )); + } +} diff --git a/crates/pxeforge/Cargo.toml b/crates/pxeforge/Cargo.toml new file mode 100644 index 0000000..3061814 --- /dev/null +++ b/crates/pxeforge/Cargo.toml @@ -0,0 +1,32 @@ +[package] +name = "pxeforge" +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +description = "Container-native PXE boot server — a lightweight Rust clone of iVentoy" + +[lints] +workspace = true + +[[bin]] +name = "pxeforge" +path = "src/main.rs" + +[dependencies] +pxeforge-core.workspace = true +pxeforge-dhcp-proxy.workspace = true +pxeforge-tftp.workspace = true +pxeforge-http-api.workspace = true +pxeforge-iso-store.workspace = true +pxeforge-ipxe-assets.workspace = true +tokio.workspace = true +axum.workspace = true +tracing.workspace = true +tracing-subscriber.workspace = true +anyhow.workspace = true +clap.workspace = true +serde.workspace = true +toml.workspace = true +bytes.workspace = true +time.workspace = true diff --git a/crates/pxeforge/src/main.rs b/crates/pxeforge/src/main.rs new file mode 100644 index 0000000..85518d2 --- /dev/null +++ b/crates/pxeforge/src/main.rs @@ -0,0 +1,372 @@ +//! PXEForge entry point. Wires the three protocol servers (DHCP proxy, +//! TFTP, HTTP) to the shared ISO store and client registry, then runs +//! them concurrently. + +use clap::{Parser, Subcommand}; +use pxeforge_core::{ClientRegistry, Config, DhcpMode, GateQueue, LogBus, LogBusLayer, SettingsStore}; +use pxeforge_dhcp_proxy::DhcpProxyServer; +use pxeforge_http_api::{build_router, AppState}; +use pxeforge_iso_store::{IsoStore, NfsManager, SmbManager}; +use std::sync::Arc; +use pxeforge_tftp::TftpServer; +use std::net::{Ipv4Addr, SocketAddr}; +use std::path::PathBuf; +use tokio::io::AsyncReadExt; + +#[derive(Debug, Parser)] +#[command(name = "pxeforge", about = "Container-native PXE boot server", version)] +struct Cli { + /// Path to a TOML config file. All fields have sensible defaults and can + /// also be overridden with env vars (PXEFORGE_*). + #[arg(long, env = "PXEFORGE_CONFIG")] + config: Option, + + #[command(subcommand)] + command: Option, +} + +#[derive(Debug, Subcommand)] +enum Command { + /// Import every `.iso` from a host directory into the ISO store, running + /// the same introspection + boot-entry generation pass the web upload + /// does. Useful for pre-populating the store before starting the server + /// (e.g. in a CI setup or after copying ISOs to a fresh PVC). + /// + /// Example: + /// docker run --rm \ + /// -v /my/isos:/seed:ro \ + /// -v pxeforge-data:/var/lib/pxeforge/isos \ + /// pxeforge:0.1.0 seed --from /seed + Seed { + /// Source directory containing one or more `.iso` files. + #[arg(long)] + from: PathBuf, + /// Don't actually import — print what would happen. + #[arg(long)] + dry_run: bool, + }, +} + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + // The LogBus has to exist before we install tracing layers, since one + // of those layers fans out into it. The web UI's Terminal tab + // subscribes to this bus over SSE. + let log_bus = LogBus::new(500); + init_tracing(log_bus.clone()); + + let cli = Cli::parse(); + let mut config = match &cli.config { + Some(p) if p.exists() => Config::from_toml_file(p)?, + _ => Config::default(), + }; + config.apply_env(); + + // Dispatch subcommands before bringing up the server. + if let Some(cmd) = cli.command { + return run_command(cmd, config).await; + } + + pxeforge_ipxe_assets::log_availability(); + + let our_ip = match config.server.public_ip { + Some(ip) => { + tracing::info!("using configured public IP: {ip}"); + ip + } + None => match detect_primary_ipv4() { + Some(ip) => { + tracing::info!("auto-detected public IPv4: {ip}"); + ip + } + None => { + // Without a reachable IP, every generated iPXE URL would + // be unreachable from real clients. Exit with a clear + // message instead of serving a broken deployment. + anyhow::bail!( + "could not detect a non-loopback IPv4 address for this host. \ + Set PXEFORGE_PUBLIC_IP= (e.g. `-e PXEFORGE_PUBLIC_IP=10.0.0.5` \ + in docker, or the env block in OpenShift Deployment) to advertise \ + a specific IP to PXE clients." + ); + } + }, + }; + let public_base_url = format!("http://{our_ip}"); + + let iso_store = IsoStore::new(config.paths.iso_dir.clone()); + iso_store.load_from_disk().await?; + let clients = ClientRegistry::new(); + let gates = GateQueue::new(); + let settings = SettingsStore::load_or_default(&config.paths.work_dir); + + // Build the SMB manager unconditionally — it starts/stops on the + // Windows toggle, not at process start. If the `smb_dir` isn't + // writable (e.g. read-only filesystem), the manager will surface that + // as `SmbState::Failed` when the operator flips the toggle. + let smb = Arc::new(SmbManager::new(config.paths.smb_dir.clone())); + if settings.snapshot().windows_enabled { + let _ = smb.start(); + } + + // NFS manager. The mount root has to be set on the IsoStore *before* + // we replay any persisted mounts, otherwise an in-memory IsoMeta + // pointing at an NFS source can't resolve to a path. + let nfs = NfsManager::new(&config.paths.work_dir, iso_store.clone()); + iso_store.set_nfs_root(nfs.mount_root()); + if let Err(e) = nfs.load_and_remount().await { + tracing::warn!(target: "pxeforge::nfs", "could not reload NFS mounts: {e}"); + } + + // Sniff network details for the Network tab. None of these are + // required for PXE to work — they're informational, surfaced in the + // UI so an operator doesn't have to drop to a shell to find their + // own gateway. + let net = detect_network_info(our_ip); + tracing::info!( + target: "pxeforge::net", + nic = %net.nic_name, mask = %net.subnet_mask, gateway = %net.gateway, + "network info" + ); + + let state = AppState { + iso_store: iso_store.clone(), + clients: clients.clone(), + settings: settings.clone(), + gates: gates.clone(), + smb: Some(smb.clone()), + nfs: nfs.clone(), + log_bus: log_bus.clone(), + started_at: time::OffsetDateTime::now_utc(), + public_base_url: public_base_url.clone(), + nic_name: net.nic_name, + subnet_mask: net.subnet_mask, + gateway: net.gateway, + }; + + let http_addr = SocketAddr::new(config.server.http_bind, config.server.http_port); + let router = build_router(state); + let http_task = tokio::spawn(async move { + let listener = tokio::net::TcpListener::bind(http_addr).await?; + tracing::info!(target: "pxeforge::http", "HTTP listening on {http_addr}"); + axum::serve(listener, router).await?; + Ok::<_, anyhow::Error>(()) + }); + + let tftp = TftpServer::new(config.server.tftp_bind, config.server.tftp_port, clients.clone()); + let tftp_task = tokio::spawn(tftp.run()); + + let dhcp_task: tokio::task::JoinHandle> = match config.network.dhcp_mode { + DhcpMode::Proxy => { + let s = DhcpProxyServer::new( + config.network.dhcp_bind, + config.network.dhcp_port, + config.network.pxe_port, + our_ip, + public_base_url.clone(), + clients.clone(), + ); + tokio::spawn(s.run()) + } + DhcpMode::Disabled => { + tracing::info!(target: "pxeforge::dhcp", "DHCP disabled — external DHCP must set next-server + filename"); + tokio::spawn(async { futures_forever().await }) + } + }; + + tokio::select! { + r = http_task => { tracing::error!("http task exited: {:?}", r); r??; } + r = tftp_task => { tracing::error!("tftp task exited: {:?}", r); r??; } + r = dhcp_task => { tracing::error!("dhcp task exited: {:?}", r); r??; } + } + Ok(()) +} + +async fn futures_forever() -> anyhow::Result<()> { + std::future::pending::<()>().await; + Ok(()) +} + +async fn run_command(cmd: Command, config: Config) -> anyhow::Result<()> { + match cmd { + Command::Seed { from, dry_run } => seed_from_dir(&from, &config, dry_run).await, + } +} + +/// Walk `src` for `*.iso`, stream each file through the normal upload path. +/// Reuses `IsoStore::begin_upload` / `finish` so the resulting meta on disk +/// is identical to a web upload — same slug rules, same introspection, same +/// sha256. +async fn seed_from_dir(src: &std::path::Path, config: &Config, dry_run: bool) -> anyhow::Result<()> { + let store = IsoStore::new(config.paths.iso_dir.clone()); + store.load_from_disk().await?; + let mut entries = tokio::fs::read_dir(src).await?; + let mut imported = 0u32; + let mut skipped = 0u32; + while let Some(entry) = entries.next_entry().await? { + let p = entry.path(); + if p.extension().and_then(|e| e.to_str()).map(str::to_ascii_lowercase).as_deref() != Some("iso") { + continue; + } + let filename = p + .file_name() + .and_then(|s| s.to_str()) + .ok_or_else(|| anyhow::anyhow!("non-utf8 filename: {}", p.display()))? + .to_string(); + println!(" {} ({} bytes)", filename, tokio::fs::metadata(&p).await?.len()); + if dry_run { continue; } + + let mut handle = match store.begin_upload(&filename).await { + Ok(h) => h, + Err(pxeforge_core::Error::Invalid(e)) => { + eprintln!(" skip: {e}"); + skipped += 1; + continue; + } + Err(e) => return Err(e.into()), + }; + let mut file = tokio::fs::File::open(&p).await?; + let mut buf = vec![0u8; 1024 * 1024]; + loop { + let n = file.read(&mut buf).await?; + if n == 0 { break; } + let chunk: bytes::Bytes = buf[..n].to_vec().into(); + handle.write_chunk(&chunk).await?; + } + let meta = handle.finish(&store).await?; + println!(" -> id={} family={:?}", meta.id, meta.introspection.family); + imported += 1; + } + println!("\nimported={imported} skipped={skipped} {}", if dry_run { "(dry run)" } else { "" }); + Ok(()) +} + +/// Pick the first non-loopback IPv4 address on this host. Returns `None` if +/// detection fails — callers should fail startup rather than silently using +/// a loopback address (which would give every PXE client an unreachable +/// `http://127.0.0.1/...`). Users in multi-homed setups should set +/// `PXEFORGE_PUBLIC_IP` explicitly. +fn detect_primary_ipv4() -> Option { + // First try: route to the public internet. `UdpSocket::connect` to a + // well-known external address causes the OS to populate `local_addr` + // with the source IP it would use — this is the standard "which of my + // interfaces is the internet-facing one" idiom. + if let Ok(sock) = std::net::UdpSocket::bind("0.0.0.0:0") { + if sock.connect("8.8.8.8:80").is_ok() { + if let Ok(std::net::SocketAddr::V4(addr)) = sock.local_addr() { + let v4 = *addr.ip(); + if !v4.is_loopback() && !v4.is_unspecified() { + return Some(v4); + } + } + } + } + // Fallback: hostname resolution. + if let Ok(hostname) = hostname() { + if let Ok(addrs) = std::net::ToSocketAddrs::to_socket_addrs(&format!("{hostname}:0")) { + for a in addrs { + if let std::net::IpAddr::V4(v4) = a.ip() { + if !v4.is_loopback() && !v4.is_unspecified() { + return Some(v4); + } + } + } + } + } + None +} + +fn hostname() -> std::io::Result { + // Tiny shim: read /proc/sys/kernel/hostname on Linux, fall back to `uname -n` via env. + if let Ok(h) = std::fs::read_to_string("/proc/sys/kernel/hostname") { + return Ok(h.trim().to_string()); + } + std::env::var("HOSTNAME").map_err(|_| std::io::Error::new( + std::io::ErrorKind::NotFound, "no hostname", + )) +} + +fn init_tracing(bus: Arc) { + use tracing_subscriber::{fmt, prelude::*, EnvFilter}; + let filter = EnvFilter::try_from_env("PXEFORGE_LOG") + .unwrap_or_else(|_| EnvFilter::new("info,pxeforge=debug")); + tracing_subscriber::registry() + .with(filter) + .with(fmt::layer().with_target(true)) + .with(LogBusLayer::new(bus)) + .init(); +} + +#[derive(Debug, Default)] +struct NetworkInfo { + nic_name: String, + subnet_mask: String, + gateway: String, +} + +/// Best-effort population of the Network tab's read-only fields. We shell +/// out to standard Linux tools (`ip route`) instead of pulling in a +/// netlink crate — these calls run once at startup, so the cost of +/// spawning a process is negligible. Empty strings are perfectly fine +/// fallbacks; the UI shows a `?` placeholder. +fn detect_network_info(our_ip: Ipv4Addr) -> NetworkInfo { + use std::process::Command; + let mut info = NetworkInfo::default(); + + // `ip -o -f inet addr show` lists every interface with its + // `inet a.b.c.d/mask`. We match the line that mentions our IP. + if let Ok(out) = Command::new("ip").args(["-o", "-f", "inet", "addr", "show"]).output() { + if let Ok(text) = String::from_utf8(out.stdout) { + for line in text.lines() { + if !line.contains(&our_ip.to_string()) { + continue; + } + // Format: "2: enp1s0 inet 10.0.0.5/24 brd ..." + let mut parts = line.split_whitespace(); + let _idx = parts.next(); + if let Some(name) = parts.next() { + info.nic_name = name.trim_end_matches(':').to_string(); + } + if let Some(addr) = line.split_whitespace().find(|p| p.contains('/')) { + if let Some((_, prefix_str)) = addr.split_once('/') { + if let Ok(prefix) = prefix_str.parse::() { + info.subnet_mask = prefix_to_dotted(prefix); + } + } + } + break; + } + } + } + + // `ip route show default` -> "default via 10.0.0.1 dev enp1s0 ..." + if let Ok(out) = Command::new("ip").args(["route", "show", "default"]).output() { + if let Ok(text) = String::from_utf8(out.stdout) { + if let Some(line) = text.lines().next() { + let mut parts = line.split_whitespace(); + while let Some(p) = parts.next() { + if p == "via" { + if let Some(gw) = parts.next() { + info.gateway = gw.to_string(); + } + break; + } + } + } + } + } + + info +} + +fn prefix_to_dotted(prefix: u8) -> String { + let prefix = prefix.min(32); + let mask: u32 = if prefix == 0 { 0 } else { u32::MAX << (32 - prefix) }; + format!( + "{}.{}.{}.{}", + (mask >> 24) & 0xff, + (mask >> 16) & 0xff, + (mask >> 8) & 0xff, + mask & 0xff + ) +} diff --git a/crates/tftp/Cargo.toml b/crates/tftp/Cargo.toml new file mode 100644 index 0000000..8068b10 --- /dev/null +++ b/crates/tftp/Cargo.toml @@ -0,0 +1,20 @@ +[package] +name = "pxeforge-tftp" +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +description = "TFTP server (RFC 1350/2347/2348/2349/7440) for iPXE chainload" + +[lints] +workspace = true + +[dependencies] +pxeforge-core.workspace = true +pxeforge-ipxe-assets.workspace = true +tokio.workspace = true +socket2.workspace = true +tracing.workspace = true +thiserror.workspace = true +anyhow.workspace = true +bytes.workspace = true diff --git a/crates/tftp/src/lib.rs b/crates/tftp/src/lib.rs new file mode 100644 index 0000000..53f2c91 --- /dev/null +++ b/crates/tftp/src/lib.rs @@ -0,0 +1,17 @@ +//! Minimal TFTP server sufficient to deliver iPXE binaries (~1 MiB each) +//! to firmware PXE ROMs. Only implements RRQ (read requests) because we +//! never receive WRQs in our use case. +//! +//! Implements RFC 1350 base protocol plus: +//! - RFC 2347 option negotiation (OACK) +//! - RFC 2348 `blksize` (critical — default 512 makes transfers unusably slow) +//! - RFC 2349 `tsize` (some PXE ROMs require it) +//! - RFC 7440 `windowsize` (huge throughput improvement for supporting clients) +//! +//! Files served are backed by the embedded iPXE asset store; there is no +//! filesystem path traversal surface because we only look up by asset name. +#![forbid(unsafe_code)] + +pub mod server; + +pub use server::TftpServer; diff --git a/crates/tftp/src/server.rs b/crates/tftp/src/server.rs new file mode 100644 index 0000000..9e17abf --- /dev/null +++ b/crates/tftp/src/server.rs @@ -0,0 +1,443 @@ +//! TFTP server implementation. +//! +//! Design: the main socket on :69 accepts RRQ packets. For each RRQ we spawn +//! a task that creates a new ephemeral UDP socket and handles the full +//! transfer there (per RFC 1350 — each transfer uses its own port pair so +//! multiple clients can download concurrently). This matches exactly how +//! `tftpd`/`in.tftpd` works and is why TFTP is awkward behind stateful NAT: +//! the ephemeral ports must be reachable from the client. +//! +//! We only serve files from `pxeforge_ipxe_assets::asset_bytes` — that is, +//! the bundled iPXE binaries and wimboot. No filesystem is ever opened, so +//! `../` path traversal attempts simply return ENOENT. + +use pxeforge_core::{ClientEvent, ClientRegistry}; +use pxeforge_ipxe_assets::asset_bytes; +use socket2::{Domain, Protocol, Socket, Type}; +use std::net::{IpAddr, SocketAddr}; +use std::sync::Arc; +use std::time::Duration; +use tokio::net::UdpSocket; + +// TFTP opcodes. +const OP_RRQ: u16 = 1; +const OP_DATA: u16 = 3; +const OP_ACK: u16 = 4; +const OP_ERROR: u16 = 5; +const OP_OACK: u16 = 6; + +// Error codes (RFC 1350). +const ERR_NOT_DEFINED: u16 = 0; +const ERR_FILE_NOT_FOUND: u16 = 1; +const ERR_ILLEGAL_OP: u16 = 4; + +pub struct TftpServer { + bind: IpAddr, + port: u16, + clients: Arc, +} + +impl TftpServer { + pub fn new(bind: IpAddr, port: u16, clients: Arc) -> Self { + Self { bind, port, clients } + } + + pub async fn run(self) -> anyhow::Result<()> { + let sock = bind_udp(self.bind, self.port)?; + tracing::info!(target: "pxeforge::tftp", "TFTP listening on {}:{}", self.bind, self.port); + let clients = self.clients.clone(); + let mut buf = vec![0u8; 2048]; + loop { + let (n, from) = match sock.recv_from(&mut buf).await { + Ok(v) => v, + Err(e) => { + tracing::warn!(target: "pxeforge::tftp", "recv error: {e}"); + continue; + } + }; + let data = buf[..n].to_vec(); + let clients = clients.clone(); + let bind_ip = self.bind; + tokio::spawn(async move { + if let Err(e) = handle_rrq(data, from, bind_ip, clients).await { + tracing::warn!(target: "pxeforge::tftp", peer=%from, "handler error: {e}"); + } + }); + } + } +} + +async fn handle_rrq( + packet: Vec, + peer: SocketAddr, + bind_ip: IpAddr, + clients: Arc, +) -> anyhow::Result<()> { + let req = match parse_rrq(&packet) { + Some(r) => r, + None => return Ok(()), + }; + let Request { filename, options, .. } = req; + + // Per-transfer ephemeral socket. + let sock = bind_udp(bind_ip, 0)?; + + let Some(file_bytes) = asset_bytes(&filename) else { + let _ = send_error(&sock, peer, ERR_FILE_NOT_FOUND, "no such file").await; + tracing::info!(target: "pxeforge::tftp", peer=%peer, file=%filename, "404"); + clients.record( + &peer.ip().to_string(), + Some(peer.ip()), + None, + ClientEvent::TftpRead { file: filename.clone() }, + ); + return Ok(()); + }; + + tracing::info!( + target: "pxeforge::tftp", + peer=%peer, file=%filename, size=file_bytes.len(), + "serving" + ); + clients.record( + &peer.ip().to_string(), + Some(peer.ip()), + None, + ClientEvent::TftpRead { file: filename.clone() }, + ); + + // Negotiate options. + let mut blksize: usize = 512; + let mut window: u16 = 1; + let mut accepted_opts: Vec<(String, String)> = Vec::new(); + + for (k, v) in &options { + match k.as_str() { + "blksize" => { + if let Ok(n) = v.parse::() { + blksize = n.clamp(8, 65464); + accepted_opts.push(("blksize".into(), blksize.to_string())); + } + } + "tsize" => { + accepted_opts.push(("tsize".into(), file_bytes.len().to_string())); + } + "windowsize" => { + if let Ok(n) = v.parse::() { + window = n.clamp(1, 64); + accepted_opts.push(("windowsize".into(), window.to_string())); + } + } + _ => {} + } + } + + if !accepted_opts.is_empty() { + let oack = encode_oack(&accepted_opts); + // Loop until client ACKs block 0 (the OACK). + if !wait_for_ack(&sock, peer, 0, &oack).await? { + return Ok(()); + } + } + + // DATA transfer. Block numbers are u16 and may wrap at 65535 — we handle + // that via `wrapping_add`. For each window we remember the starting + // (offset, block_no) explicitly; on retransmit we replay from there + // instead of trying to compute it back from `last_block_in_window` which + // is wrong when a window short-sends at EOF (previous bug: window=8 but + // only 3 blocks sent, then rewind subtracted 7 landing in the wrong id). + let total = file_bytes.len(); + let mut offset: usize = 0; + let mut block_no: u16 = 1; + let mut needs_zero_final = false; // spec: if last data block == blksize, follow with empty DATA + + 'transfer: loop { + let window_start_offset = offset; + let window_start_block = block_no; + let mut last_block_in_window = block_no; + let mut window_reached_eof = false; + let mut last_chunk_len = 0usize; + + // Send one window worth of DATA. + for _ in 0..window { + if offset >= total { break; } + let end = (offset + blksize).min(total); + let chunk = &file_bytes[offset..end]; + let pkt = encode_data(block_no, chunk); + sock.send_to(&pkt, peer).await?; + last_block_in_window = block_no; + last_chunk_len = chunk.len(); + offset = end; + block_no = block_no.wrapping_add(1); + if end == total { + window_reached_eof = true; + break; + } + } + + // Wait for an ACK of the last block we actually sent (not the + // nominal last block of a theoretical full window). + let mut tries = 0u8; + loop { + match tokio::time::timeout(Duration::from_secs(3), recv_ack(&sock, peer)).await { + Ok(Ok(acked)) if acked == last_block_in_window => break, + Ok(Ok(_)) => continue, // stale ACK from an earlier block — ignore + Ok(Err(e)) => return Err(e), + Err(_) => { + tries += 1; + if tries > 5 { + tracing::warn!( + target: "pxeforge::tftp", + peer=%peer, last_block=last_block_in_window, + "timeout after {tries} retries, aborting transfer" + ); + return Ok(()); + } + // Rewind to the start of this window and resend exactly + // the same blocks (same count, same block numbers). This + // is cheap and correct even for short final windows. + offset = window_start_offset; + block_no = window_start_block; + let mut resent = 0; + while resent < window && offset < total { + let end = (offset + blksize).min(total); + let pkt = encode_data(block_no, &file_bytes[offset..end]); + sock.send_to(&pkt, peer).await?; + last_block_in_window = block_no; + last_chunk_len = end - offset; + offset = end; + block_no = block_no.wrapping_add(1); + resent += 1; + } + } + } + } + + if window_reached_eof || offset >= total { + // If the very last DATA was exactly blksize, RFC 1350 requires a + // following zero-length DATA to signal end-of-transfer. If it + // was shorter, the short block already signals EOF. + needs_zero_final = last_chunk_len == blksize; + break 'transfer; + } + } + + if needs_zero_final { + let pkt = encode_data(block_no, &[]); + sock.send_to(&pkt, peer).await?; + let _ = tokio::time::timeout(Duration::from_secs(3), recv_ack(&sock, peer)).await; + } + + tracing::debug!(target: "pxeforge::tftp", peer=%peer, bytes=total, "transfer complete"); + Ok(()) +} + +#[derive(Debug)] +struct Request { + filename: String, + #[allow(dead_code)] + mode: String, + options: Vec<(String, String)>, +} + +fn parse_rrq(pkt: &[u8]) -> Option { + if pkt.len() < 4 { return None; } + let op = u16::from_be_bytes([pkt[0], pkt[1]]); + if op != OP_RRQ { return None; } + let mut rest = &pkt[2..]; + let filename = read_cstr(&mut rest)?; + let mode = read_cstr(&mut rest)?; + let mut options = Vec::new(); + while !rest.is_empty() { + let k = match read_cstr(&mut rest) { Some(s) => s, None => break }; + if k.is_empty() { break; } + let v = read_cstr(&mut rest).unwrap_or_default(); + options.push((k.to_ascii_lowercase(), v)); + } + Some(Request { filename, mode, options }) +} + +fn read_cstr(buf: &mut &[u8]) -> Option { + let pos = buf.iter().position(|b| *b == 0)?; + let s = std::str::from_utf8(&buf[..pos]).ok()?.to_string(); + *buf = &buf[pos + 1..]; + Some(s) +} + +fn encode_data(block: u16, chunk: &[u8]) -> Vec { + let mut v = Vec::with_capacity(4 + chunk.len()); + v.extend_from_slice(&OP_DATA.to_be_bytes()); + v.extend_from_slice(&block.to_be_bytes()); + v.extend_from_slice(chunk); + v +} + +fn encode_oack(opts: &[(String, String)]) -> Vec { + let mut v = Vec::new(); + v.extend_from_slice(&OP_OACK.to_be_bytes()); + for (k, val) in opts { + v.extend_from_slice(k.as_bytes()); + v.push(0); + v.extend_from_slice(val.as_bytes()); + v.push(0); + } + v +} + +async fn send_error( + sock: &UdpSocket, + peer: SocketAddr, + code: u16, + msg: &str, +) -> std::io::Result<()> { + let mut v = Vec::with_capacity(5 + msg.len()); + v.extend_from_slice(&OP_ERROR.to_be_bytes()); + v.extend_from_slice(&code.to_be_bytes()); + v.extend_from_slice(msg.as_bytes()); + v.push(0); + sock.send_to(&v, peer).await.map(|_| ()) +} + +async fn recv_ack(sock: &UdpSocket, peer: SocketAddr) -> anyhow::Result { + let mut buf = [0u8; 32]; + loop { + let (n, from) = sock.recv_from(&mut buf).await?; + if from.ip() != peer.ip() { continue; } + if n < 4 { continue; } + let op = u16::from_be_bytes([buf[0], buf[1]]); + match op { + OP_ACK => return Ok(u16::from_be_bytes([buf[2], buf[3]])), + OP_ERROR => { + let code = u16::from_be_bytes([buf[2], buf[3]]); + anyhow::bail!("client error {code}"); + } + _ => continue, + } + } +} + +async fn wait_for_ack( + sock: &UdpSocket, + peer: SocketAddr, + expect_block: u16, + to_retx: &[u8], +) -> anyhow::Result { + let mut tries = 0; + loop { + sock.send_to(to_retx, peer).await?; + match tokio::time::timeout(Duration::from_secs(3), recv_ack(sock, peer)).await { + Ok(Ok(b)) if b == expect_block => return Ok(true), + Ok(Ok(_)) => continue, + Ok(Err(_)) | Err(_) => { + tries += 1; + if tries > 5 { return Ok(false); } + } + } + } +} + +fn bind_udp(bind: IpAddr, port: u16) -> anyhow::Result { + let domain = match bind { IpAddr::V4(_) => Domain::IPV4, IpAddr::V6(_) => Domain::IPV6 }; + let sock = Socket::new(domain, Type::DGRAM, Some(Protocol::UDP))?; + sock.set_reuse_address(true)?; + sock.set_nonblocking(true)?; + let addr: SocketAddr = SocketAddr::new(bind, port); + sock.bind(&addr.into())?; + let std_sock: std::net::UdpSocket = sock.into(); + Ok(UdpSocket::from_std(std_sock)?) +} + +#[allow(dead_code)] +const _UNUSED: (u16, u16) = (ERR_NOT_DEFINED, ERR_ILLEGAL_OP); + +/// Pure-logic helper used by the unit tests below and (in a refactor) by +/// `handle_rrq`. Given a position in the file and the window, return the +/// (block_no, chunk_len) list this window will emit. Useful as a sanity +/// check that our windowing math matches the wire behavior the spec +/// requires — tested against edge cases (exact-blksize tail, short tail, +/// single-block window). +#[must_use] +pub fn plan_window( + total: usize, + offset: usize, + blksize: usize, + window: u16, + starting_block: u16, +) -> Vec<(u16, usize)> { + let mut out = Vec::new(); + let mut o = offset; + let mut b = starting_block; + for _ in 0..window { + if o >= total { break; } + let end = (o + blksize).min(total); + out.push((b, end - o)); + o = end; + b = b.wrapping_add(1); + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn parses_rrq_with_options() { + // RRQ "snponly.efi" mode "octet" blksize=1468 tsize=0 + let mut pkt = vec![0, OP_RRQ as u8]; + pkt.extend_from_slice(b"snponly.efi\0octet\0blksize\01468\0tsize\00\0"); + let r = parse_rrq(&pkt).unwrap(); + assert_eq!(r.filename, "snponly.efi"); + assert_eq!(r.mode, "octet"); + assert_eq!(r.options.len(), 2); + assert_eq!(r.options[0].0, "blksize"); + assert_eq!(r.options[0].1, "1468"); + } + + #[test] + fn encode_decode_data() { + let p = encode_data(7, b"hello"); + assert_eq!(&p[0..2], &OP_DATA.to_be_bytes()); + assert_eq!(&p[2..4], &7u16.to_be_bytes()); + assert_eq!(&p[4..], b"hello"); + } + + #[test] + fn plan_window_full_blocks() { + // 4 KB file, 1024 blksize, window 4 → one window of 4 full blocks. + let p = plan_window(4096, 0, 1024, 4, 1); + assert_eq!(p, vec![(1, 1024), (2, 1024), (3, 1024), (4, 1024)]); + } + + #[test] + fn plan_window_short_tail_at_eof() { + // 3.5 KB file, 1024 blksize, window 8 starting at offset 0. + // Expect 3 full + 1 half, then stop (below 8 blocks). + let p = plan_window(3584, 0, 1024, 8, 1); + assert_eq!(p, vec![(1, 1024), (2, 1024), (3, 1024), (4, 512)]); + } + + #[test] + fn plan_window_exact_boundary_needs_zero_final() { + // 2 KB file, 1024 blksize, window 8 — last block is exactly blksize. + // `handle_rrq` checks `last_chunk_len == blksize` to decide whether to + // emit the terminating zero-length DATA. Assert that condition here. + let p = plan_window(2048, 0, 1024, 8, 1); + assert_eq!(p, vec![(1, 1024), (2, 1024)]); + let last = p.last().unwrap(); + assert_eq!(last.1, 1024); // => needs zero final per RFC 1350 + } + + #[test] + fn plan_window_wraparound() { + // Block number wraps from u16::MAX to 0 on next window — 2 blocks, + // starting at 65534. + let p = plan_window(2048, 0, 1024, 2, 65534); + assert_eq!(p, vec![(65534, 1024), (65535, 1024)]); + let p2 = plan_window(2048, 2048, 1024, 2, 0); + assert!(p2.is_empty()); // nothing past EOF + // And a cross-boundary case: + let p3 = plan_window(3072, 0, 1024, 3, 65535); + assert_eq!(p3, vec![(65535, 1024), (0, 1024), (1, 1024)]); + } +} diff --git a/crates/webui/Cargo.toml b/crates/webui/Cargo.toml new file mode 100644 index 0000000..dff7073 --- /dev/null +++ b/crates/webui/Cargo.toml @@ -0,0 +1,12 @@ +[package] +name = "pxeforge-webui" +version.workspace = true +edition.workspace = true +license.workspace = true +authors.workspace = true +description = "Embedded single-file web UI for PXEForge" + +[lints] +workspace = true + +[dependencies] diff --git a/crates/webui/src/app.css b/crates/webui/src/app.css new file mode 100644 index 0000000..8f740d9 --- /dev/null +++ b/crates/webui/src/app.css @@ -0,0 +1,371 @@ +/* PXEForge web UI — Netbox-style layout, fully offline. + * Design tokens are CSS variables so a later phase can re-theme without + * touching markup or JS. */ + +:root { + --bg: #0b1018; + --bg-panel: #121826; + --bg-panel-2: #1a2334; + --bg-elev: #223047; + --fg: #e4e8ef; + --fg-dim: #8a94a7; + --fg-dimmer: #5a6379; + --accent: #00d4b4; /* Netbox-ish teal */ + --accent-dim: #07a38c; + --warn: #ffb347; + --err: #ef6e6e; + --ok: #4ade80; + --border: #223047; + --border-soft: #172033; + --radius: 6px; + --radius-lg: 10px; + --sidebar-w: 240px; + --topbar-h: 54px; + --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; + --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, system-ui, sans-serif; +} + +* { box-sizing: border-box; } +html, body { height: 100%; } +body { + margin: 0; font-family: var(--sans); font-size: 14px; line-height: 1.5; + background: var(--bg); color: var(--fg); +} +a { color: var(--accent); text-decoration: none; } +a:hover { text-decoration: underline; } +code, kbd { font-family: var(--mono); font-size: 12.5px; + background: var(--bg-panel-2); padding: 1px 5px; border-radius: 3px; } + +/* ── Shell ─────────────────────────────────────────────────────────── */ + +.shell { + display: grid; + grid-template-columns: var(--sidebar-w) 1fr; + grid-template-rows: var(--topbar-h) 1fr; + grid-template-areas: + "sidebar topbar" + "sidebar main"; + height: 100vh; +} +.sidebar { + grid-area: sidebar; + background: var(--bg-panel); + border-right: 1px solid var(--border); + display: flex; flex-direction: column; +} +.sidebar .brand { + display: flex; align-items: center; gap: 12px; + padding: 14px 18px; + border-bottom: 1px solid var(--border); +} +.sidebar .brand img { width: 40px; height: auto; } +.sidebar .brand strong { font-size: 16px; letter-spacing: 0.4px; } +.sidebar .brand .sub { color: var(--fg-dim); font-size: 11px; } +.sidebar nav { padding: 10px 0; flex: 1; overflow-y: auto; } +.sidebar nav .group { + padding: 10px 18px 6px; + font-size: 10.5px; color: var(--fg-dimmer); text-transform: uppercase; + letter-spacing: 1px; +} +.sidebar nav a { + display: flex; align-items: center; gap: 10px; + padding: 7px 18px; color: var(--fg); font-size: 13.5px; + border-left: 2px solid transparent; +} +.sidebar nav a:hover { background: var(--bg-panel-2); text-decoration: none; } +.sidebar nav a.active { + background: var(--bg-panel-2); + border-left-color: var(--accent); + color: var(--accent); +} +.sidebar nav a .count { + margin-left: auto; + background: var(--bg-elev); color: var(--fg-dim); + padding: 1px 7px; font-size: 11px; border-radius: 10px; + font-variant-numeric: tabular-nums; +} +.sidebar nav a.active .count { background: var(--accent); color: #002923; } +.sidebar .footer { + padding: 10px 18px; border-top: 1px solid var(--border); + color: var(--fg-dimmer); font-size: 11px; +} +.sidebar .footer code { background: transparent; color: var(--fg-dim); padding: 0; } + +/* ── Top bar ───────────────────────────────────────────────────────── */ + +.topbar { + grid-area: topbar; + display: flex; align-items: center; + padding: 0 20px; gap: 18px; + background: var(--bg-panel); + border-bottom: 1px solid var(--border); +} +.topbar h1 { + margin: 0; font-size: 15px; font-weight: 600; + color: var(--fg); letter-spacing: 0.2px; +} +.topbar .tabs { display: flex; gap: 4px; margin-left: 24px; } +.topbar .tabs button { + background: transparent; border: 0; + color: var(--fg-dim); font: inherit; + padding: 10px 14px; cursor: pointer; + border-bottom: 2px solid transparent; +} +.topbar .tabs button:hover { color: var(--fg); } +.topbar .tabs button.active { color: var(--accent); border-bottom-color: var(--accent); } +.topbar .spacer { flex: 1; } +.topbar .chip { + background: var(--bg-panel-2); border: 1px solid var(--border); + color: var(--fg-dim); font-size: 12px; + padding: 4px 10px; border-radius: 12px; +} +.topbar .chip strong { color: var(--fg); font-weight: 600; } + +/* ── Main content ─────────────────────────────────────────────────── */ + +.main { + grid-area: main; + overflow: auto; + padding: 22px 26px 40px; +} +.grid { display: grid; gap: 20px; } +.grid.cols-3 { grid-template-columns: repeat(3, 1fr); } +.grid.cols-2 { grid-template-columns: repeat(2, 1fr); } +@media (max-width: 1024px) { + .grid.cols-3, .grid.cols-2 { grid-template-columns: 1fr; } +} + +/* ── Cards / panels ───────────────────────────────────────────────── */ + +.card { + background: var(--bg-panel); + border: 1px solid var(--border); + border-radius: var(--radius-lg); + overflow: hidden; +} +.card > header { + padding: 12px 16px; + background: var(--bg-panel-2); + border-bottom: 1px solid var(--border); + display: flex; align-items: center; gap: 10px; +} +.card > header h2 { margin: 0; font-size: 13.5px; font-weight: 600; color: var(--fg); } +.card > header .sub { color: var(--fg-dim); font-size: 12px; margin-left: auto; } +.card .body { padding: 16px; } + +.stat { + padding: 16px; +} +.stat .label { color: var(--fg-dim); font-size: 11.5px; text-transform: uppercase; letter-spacing: 0.8px; } +.stat .value { font-size: 28px; font-weight: 600; line-height: 1.1; margin-top: 4px; color: var(--fg); } +.stat .trend { font-size: 12px; color: var(--fg-dim); margin-top: 4px; } + +/* ── Tables ───────────────────────────────────────────────────────── */ + +table { width: 100%; border-collapse: collapse; } +th, td { text-align: left; padding: 9px 16px; border-bottom: 1px solid var(--border-soft); } +th { + color: var(--fg-dim); font-weight: 500; font-size: 11px; + text-transform: uppercase; letter-spacing: 1px; + background: var(--bg-panel-2); +} +tr:hover td { background: var(--bg-panel-2); } +td.mono { font-family: var(--mono); font-size: 12.5px; } +td.num { text-align: right; font-variant-numeric: tabular-nums; } + +/* ── Tags / pills ─────────────────────────────────────────────────── */ + +.tag { + display: inline-block; + padding: 2px 8px; border-radius: 10px; + font-size: 11px; font-weight: 600; + background: #1b3148; color: #a2c5e8; +} +.tag.ok { background: #103428; color: var(--ok); } +.tag.warn { background: #3a2a10; color: var(--warn); } +.tag.err { background: #3a1515; color: var(--err); } +.tag.accent { background: #072f29; color: var(--accent); } +.tag.arch { text-transform: uppercase; } + +/* ── Forms ────────────────────────────────────────────────────────── */ + +button, .btn { + background: var(--accent); color: #002923; + border: 0; border-radius: var(--radius); + padding: 7px 14px; font: inherit; font-weight: 600; + cursor: pointer; +} +button:hover, .btn:hover { background: var(--accent-dim); color: #fff; } +button.ghost { background: transparent; color: var(--fg); border: 1px solid var(--border); } +button.ghost:hover { background: var(--bg-panel-2); color: var(--fg); } +button.danger { background: transparent; color: var(--err); border: 1px solid #4a1f1f; } +button.danger:hover { background: #2a0b0b; color: var(--err); } + +label.field { + display: grid; gap: 4px; margin-bottom: 14px; +} +label.field .name { color: var(--fg-dim); font-size: 12px; } +label.field .hint { color: var(--fg-dimmer); font-size: 11px; } +label.field input[type="text"], +label.field input[type="number"], +label.field select, +label.field textarea { + width: 100%; background: var(--bg); color: var(--fg); + border: 1px solid var(--border); border-radius: var(--radius); + padding: 7px 10px; font: inherit; +} +label.field input:focus, label.field select:focus, label.field textarea:focus { + outline: none; border-color: var(--accent); +} +label.check { + display: flex; gap: 10px; align-items: center; + padding: 8px 10px; margin-bottom: 6px; + border: 1px solid var(--border-soft); border-radius: var(--radius); +} +label.check input { accent-color: var(--accent); } + +/* ── Drop zone ────────────────────────────────────────────────────── */ + +.drop { + border: 2px dashed var(--border); + border-radius: var(--radius-lg); + padding: 32px; text-align: center; + color: var(--fg-dim); cursor: pointer; + transition: border-color .15s, color .15s, background .15s; +} +.drop.hover, .drop:hover { + border-color: var(--accent); color: var(--fg); + background: var(--bg-panel-2); +} +.drop strong { color: var(--accent); } +.progress { height: 6px; background: var(--bg-panel-2); border-radius: 3px; overflow: hidden; margin-top: 12px; display: none; } +.progress.active { display: block; } +.progress .bar { height: 100%; width: 0%; background: var(--accent); transition: width .25s; } + +/* ── Gate queue "horse race" visual ───────────────────────────────── */ + +.gate-track { + display: grid; gap: 6px; + padding: 10px 0; +} +.gate-row { + display: grid; grid-template-columns: 32px 1fr auto auto; align-items: center; + gap: 14px; + padding: 8px 14px; + background: var(--bg-panel-2); border-radius: var(--radius); + border-left: 3px solid var(--accent); +} +.gate-row.assigned { border-left-color: var(--ok); } +.gate-row .pos { font-family: var(--mono); font-size: 15px; color: var(--accent); font-weight: 600; } +.gate-row.assigned .pos { color: var(--ok); } +.gate-row .mac { font-family: var(--mono); font-size: 13px; } +.gate-row .meta { color: var(--fg-dim); font-size: 12px; } + +.empty { color: var(--fg-dim); padding: 30px; text-align: center; } +.msg { color: var(--fg-dim); font-size: 12.5px; margin-top: 8px; } +.msg.err { color: var(--err); } +.msg.ok { color: var(--ok); } + +/* ── Top bar readiness chip ──────────────────────────────────────── */ +.chip.ready { background: #103428; color: var(--ok); border-color: #1a4f3c; } +.chip.notready { background: #3a1515; color: var(--err); border-color: #5a1f1f; } +.chip.warming { background: #3a2a10; color: var(--warn); border-color: #4a3a18; } + +/* ── Dashboard stat strip ────────────────────────────────────────── */ +.statstrip { display: grid; grid-template-columns: repeat(4, 1fr); gap: 14px; } +@media (max-width: 1100px) { .statstrip { grid-template-columns: repeat(2, 1fr); } } + +.kv { display: grid; grid-template-columns: 160px 1fr; gap: 6px 14px; + padding: 4px 0; font-size: 13px; } +.kv .k { color: var(--fg-dim); } +.kv .v { font-family: var(--mono); color: var(--fg); word-break: break-all; } +.kv .v.warn { color: var(--warn); } +.kv .v.err { color: var(--err); } +.kv .v.ok { color: var(--ok); } + +/* ── Image rows: amber tint on un-bootable images (Bootimus pattern) ── */ +tr.unbootable td { background: rgba(255, 179, 71, 0.07) !important; } +tr.unbootable td:first-child { border-left: 3px solid var(--warn); } +.row-warn { color: var(--warn); font-size: 11.5px; margin-top: 2px; } + +/* ── Table source badge ──────────────────────────────────────────── */ +.src-badge { font-family: var(--mono); font-size: 11px; padding: 1px 6px; + border-radius: 4px; background: var(--bg-elev); color: var(--fg-dim); } +.src-badge.nfs { background: #122a3a; color: #7cd3ff; } + +/* ── NFS modal-ish add form ──────────────────────────────────────── */ +.nfs-row { display: grid; grid-template-columns: 32px 1fr auto auto auto; align-items: center; + gap: 14px; padding: 10px 14px; background: var(--bg-panel-2); + border-left: 3px solid var(--accent); border-radius: var(--radius); } +.nfs-row.down { border-left-color: var(--err); } +.nfs-row .id { font-family: var(--mono); font-size: 12.5px; color: var(--fg); } +.nfs-row .meta { color: var(--fg-dim); font-size: 12px; } +.nfs-row .err { color: var(--err); font-size: 11.5px; word-break: break-all; } +.dot { width: 8px; height: 8px; border-radius: 50%; display: inline-block; } +.dot.ok { background: var(--ok); } +.dot.err { background: var(--err); } +.dot.warn { background: var(--warn); } + +/* ── Inline form rows (used by Network + NFS add) ───────────────── */ +.form-row { display: grid; grid-template-columns: repeat(4, 1fr); gap: 10px 14px; } +@media (max-width: 900px) { .form-row { grid-template-columns: 1fr; } } + +/* ── Terminal pane ──────────────────────────────────────────────── */ +.terminal { + display: flex; flex-direction: column; + border: 1px solid var(--border); + border-radius: var(--radius-lg); + background: #06090e; + overflow: hidden; + height: calc(100vh - var(--topbar-h) - 90px); + min-height: 480px; +} +.terminal .pane { + flex: 1; overflow: auto; + padding: 10px 14px; + font-family: var(--mono); font-size: 12.5px; line-height: 1.5; + color: #cfd6e2; + white-space: pre-wrap; word-break: break-word; +} +.terminal .pane .lvl-error { color: var(--err); } +.terminal .pane .lvl-warn { color: var(--warn); } +.terminal .pane .lvl-info { color: #cfd6e2; } +.terminal .pane .lvl-debug { color: var(--fg-dim); } +.terminal .pane .lvl-trace { color: var(--fg-dimmer); } +.terminal .pane .ts { color: var(--fg-dimmer); } +.terminal .pane .tg { color: #7cd3ff; } +.terminal .pane .echo { color: var(--accent); } +.terminal .input-row { + display: flex; align-items: center; gap: 8px; + padding: 8px 14px; + background: #0a0e15; + border-top: 1px solid var(--border); +} +.terminal .input-row .prompt { color: var(--accent); font-family: var(--mono); } +.terminal .input-row input { + flex: 1; background: transparent; border: 0; color: var(--fg); + font: inherit; font-family: var(--mono); font-size: 13px; + outline: none; padding: 4px 0; +} +.terminal .toolbar { + display: flex; gap: 8px; align-items: center; + padding: 8px 14px; + background: var(--bg-panel-2); + border-bottom: 1px solid var(--border); + font-size: 12px; color: var(--fg-dim); +} +.terminal .toolbar .right { margin-left: auto; display: flex; gap: 6px; } +.terminal .toolbar button { + padding: 3px 9px; font-size: 11px; + background: transparent; color: var(--fg-dim); border: 1px solid var(--border); + font-weight: 500; +} +.terminal .toolbar button:hover { color: var(--fg); background: var(--bg-elev); } + +/* ── About card ─────────────────────────────────────────────────── */ +.about-hero { padding: 20px 24px; } +.about-hero h2 { font-size: 22px; margin: 0 0 8px; color: var(--fg); } +.about-hero .lead { color: var(--fg-dim); font-size: 14px; max-width: 60ch; } +.about-hero .who { margin-top: 18px; font-size: 13px; } +.about-hero .who span { color: var(--fg-dim); } +.about-hero .who strong { color: var(--accent); } diff --git a/crates/webui/src/app.js b/crates/webui/src/app.js new file mode 100644 index 0000000..0fa6aa8 --- /dev/null +++ b/crates/webui/src/app.js @@ -0,0 +1,696 @@ +// PXEForge web UI — vanilla JS, no build step, no framework, no network +// dependencies. Uses fetch() + EventSource only. +// +// Tabs (Phase 4): Dashboard / Network / Forge Gate / Storage / Terminal / +// About. The shell swaps a single view into #view-root. +// +// Keep this readable — nobody wants to debug a clever vanilla-JS +// framework at 3 AM. Plain dumb DOM construction is the design. + +(function () { + const $ = (sel, root = document) => root.querySelector(sel); + const $$ = (sel, root = document) => Array.from(root.querySelectorAll(sel)); + const el = (tag, attrs = {}, children = []) => { + const e = document.createElement(tag); + for (const [k, v] of Object.entries(attrs)) { + if (k === 'class') e.className = v; + else if (k === 'html') e.innerHTML = v; + else if (k.startsWith('on') && typeof v === 'function') e.addEventListener(k.slice(2), v); + else if (v !== false && v != null) e.setAttribute(k, v); + } + for (const c of [].concat(children)) { + if (c == null || c === false) continue; + if (typeof c === 'string') e.appendChild(document.createTextNode(c)); + else e.appendChild(c); + } + return e; + }; + const fmtBytes = (n) => { + const u = ['B','KB','MB','GB','TB']; let i = 0; + while (n >= 1024 && i < u.length-1) { n /= 1024; i++; } + return n.toFixed(n >= 10 || i === 0 ? 0 : 1) + ' ' + u[i]; + }; + const fmtAgo = (ts) => { + const d = (ts instanceof Date) ? ts : new Date(ts); + if (isNaN(d.getTime())) return '-'; + const ds = Math.floor((Date.now() - d.getTime()) / 1000); + if (ds < 0) return 'in ' + Math.abs(ds) + 's'; + if (ds < 60) return ds + 's ago'; + if (ds < 3600) return Math.floor(ds/60) + 'm ago'; + if (ds < 86400) return Math.floor(ds/3600) + 'h ago'; + return d.toLocaleString(); + }; + const fmtUptime = (secs) => { + secs = Math.max(0, Math.floor(secs || 0)); + const h = Math.floor(secs/3600), m = Math.floor((secs%3600)/60), s = secs%60; + if (h) return h + 'h ' + m + 'm'; + if (m) return m + 'm ' + s + 's'; + return s + 's'; + }; + const familyLabel = (f) => ({ + debian_ubuntu: 'Debian / Ubuntu', rhel_fedora: 'RHEL family', + open_suse: 'openSUSE', arch: 'Arch', alpine: 'Alpine', + windows_pe: 'Windows', unknown: 'Unknown', + }[f] || f); + const archLabel = (a) => { + if (!a) return '—'; + if (typeof a === 'string') return a; + if (a && typeof a === 'object') { + if ('Unknown' in a) return 'unknown(0x' + a.Unknown.toString(16) + ')'; + return JSON.stringify(a); + } + return String(a); + }; + + // ── network helpers ────────────────────────────────────────────── + async function getJSON(url) { + const r = await fetch(url); + if (!r.ok) throw new Error(url + ': ' + r.status); + return r.json(); + } + async function putJSON(url, body) { + return fetch(url, {method:'PUT', headers:{'Content-Type':'application/json'}, body: JSON.stringify(body)}); + } + async function postJSON(url, body) { + return fetch(url, {method:'POST', headers:{'Content-Type':'application/json'}, body: JSON.stringify(body)}); + } + + // Categorize an ISO row's "bootable now" status — drives the amber + // tint borrowed from Bootimus v0.1.62. Returns {ok, reason}. + function bootability(iso, settings) { + const fam = iso.introspection.family; + const isWin = fam === 'windows_pe'; + if (isWin && !settings.windows_enabled) { + return { ok: false, reason: 'Windows boot disabled in Settings' }; + } + if (!isWin && !iso.introspection.kernel_path && fam !== 'windows_pe') { + // Linux without a detected kernel falls through to sanboot which + // rarely works for >1 GiB ISOs. + if (iso.size_bytes > 1.5 * 1024 * 1024 * 1024) { + return { ok: false, reason: 'no kernel/initrd detected; ISO too large for sanboot fallback' }; + } + return { ok: true, warn: 'no kernel detected — sanboot fallback may not work' }; + } + return { ok: true }; + } + + // ── views ──────────────────────────────────────────────────────── + const views = { + dashboard: async () => { + const status = await getJSON('/api/status'); + const isos = await getJSON('/api/isos'); + const clients = (await getJSON('/api/clients')).clients || []; + const gates = (await getJSON('/api/gate')).gates || []; + + const ipxeOk = (status.ipxe_assets || []).length > 0; + const stats = el('div', {class: 'statstrip'}, [ + el('div', {class: 'card'}, el('div', {class: 'stat'}, [ + el('div', {class: 'label'}, 'Server status'), + el('div', {class: 'value', style: 'font-size:18px;color:' + (ipxeOk ? 'var(--ok)' : 'var(--err)')}, + ipxeOk ? 'Ready' : 'Not ready'), + el('div', {class: 'trend'}, + ipxeOk ? 'Bootloaders bundled, accepting clients' + : 'No iPXE binaries bundled'), + ])), + el('div', {class: 'card'}, el('div', {class: 'stat'}, [ + el('div', {class: 'label'}, 'Imaging now'), + el('div', {class: 'value'}, String(status.imaging_count || 0)), + el('div', {class: 'trend'}, (status.waiting_count || 0) + ' waiting at gate'), + ])), + el('div', {class: 'card'}, el('div', {class: 'stat'}, [ + el('div', {class: 'label'}, 'Images available'), + el('div', {class: 'value'}, String(isos.length)), + el('div', {class: 'trend'}, + isos.filter(i => i.introspection.family === 'windows_pe').length + ' Windows · ' + + isos.filter(i => i.introspection.family !== 'windows_pe').length + ' Linux · ' + + (status.nfs_active || 0) + ' NFS active'), + ])), + el('div', {class: 'card'}, el('div', {class: 'stat'}, [ + el('div', {class: 'label'}, 'Uptime'), + el('div', {class: 'value', style: 'font-size:22px'}, fmtUptime(status.uptime_secs)), + el('div', {class: 'trend'}, 'PXEForge ' + status.version), + ])), + ]); + + // Recent connections — the operator's at-a-glance "who tried to + // boot" log. Use last_seen desc (already sorted by API). + const recent = clients.slice(0, 8); + const recentRows = recent.map(c => { + const g = gates.find(g => g.mac === c.mac); + let status = el('span', {class: 'tag ok'}, 'active'); + if (g && g.assigned_target) status = el('span', {class:'tag ok'}, 'assigned: ' + g.assigned_target); + else if (g) status = el('span', {class:'tag accent'}, '#' + g.position + ' at gate'); + return el('tr', {}, [ + el('td', {class: 'mono'}, c.mac), + el('td', {}, c.last_ip ? String(c.last_ip) : '-'), + el('td', {}, el('span', {class:'tag arch'}, archLabel(c.arch))), + el('td', {}, fmtAgo(c.last_seen)), + el('td', {}, status), + ]); + }); + const recentBlock = el('div', {class: 'card'}, [ + el('header', {}, [ + el('h2', {}, 'Recent connections'), + el('span', {class: 'sub'}, clients.length + ' total'), + ]), + recent.length + ? el('table', {}, [ + el('thead', {}, el('tr', {}, [ + el('th',{},'MAC'), el('th',{},'IP'), el('th',{},'Arch'), + el('th',{},'Last seen'), el('th',{},'Status'), + ])), + el('tbody', {}, recentRows), + ]) + : el('div', {class: 'empty'}, 'No PXE clients have contacted this server yet.'), + ]); + + // At-a-glance pool of problem images — Bootimus-style early warning. + const settings = status.settings; + const problems = isos.map(i => ({i, b: bootability(i, settings)})).filter(x => !x.b.ok); + const problemsBlock = problems.length ? el('div', {class:'card'}, [ + el('header', {}, [el('h2', {}, 'Images that won\'t boot with current settings')]), + el('div', {class:'body'}, + problems.map(({i, b}) => el('div', {class:'row-warn'}, + '⚠ ' + i.filename + ' — ' + b.reason))) + ]) : null; + + return el('div', {class:'grid'}, [stats, recentBlock, problemsBlock].filter(Boolean)); + }, + + network: async () => { + const net = await getJSON('/api/network'); + const dns = el('input', {type:'text', value: net.dns_server || '', + placeholder: 'Optional, e.g. 8.8.8.8 or 1.1.1.1'}); + const msg = el('div', {class:'msg'}); + + const save = el('button', {onclick: async () => { + const r = await putJSON('/api/network', { dns_server: dns.value }); + if (r.status === 204) { msg.textContent = 'Saved.'; msg.className = 'msg ok'; } + else { msg.textContent = 'Save failed: ' + r.status; msg.className = 'msg err'; } + }}, 'Save'); + + const networkCard = el('div', {class:'card'}, [ + el('header', {}, el('h2', {}, 'Network')), + el('div', {class:'body'}, [ + el('div', {class:'kv'}, [ + el('div', {class:'k'}, 'Server IP'), + el('div', {class:'v'}, net.server_ip || '?'), + el('div', {class:'k'}, 'NIC name'), + el('div', {class:'v'}, net.nic_name || '(auto-detect failed)'), + el('div', {class:'k'}, 'Subnet mask'), + el('div', {class:'v'}, net.subnet_mask || '?'), + el('div', {class:'k'}, 'Gateway'), + el('div', {class:'v'}, net.gateway || '?'), + el('div', {class:'k'}, 'Public base URL'), + el('div', {class:'v'}, net.public_base_url), + ]), + el('p', {class:'msg'}, + 'Server IP, NIC, mask, and gateway are auto-detected at startup. ' + + 'To change them, set PXEFORGE_PUBLIC_IP and restart — editing them ' + + 'from a hot UI would silently break PXE for every client mid-boot.'), + el('label', {class:'field', style:'margin-top:18px'}, [ + el('span', {class:'name'}, 'DNS server (optional, informational)'), + dns, + el('span', {class:'hint'}, + 'PXEForge does not run a DNS server itself; this field records ' + + 'what your upstream DNS is so you don\'t have to dig it out at ' + + '3 AM during a deployment.'), + ]), + save, msg, + ]), + ]); + + return el('div', {class:'grid'}, [networkCard]); + }, + + gate: async () => { + const [{ gates = [] }, isos] = await Promise.all([ + getJSON('/api/gate'), getJSON('/api/isos'), + ]); + const targets = isos.flatMap(i => i.boot_entries.map(e => ({ + id: e.id, title: e.title + ' — ' + familyLabel(i.introspection.family) + }))); + const pick = el('select', {}, + [el('option', {value: ''}, '— choose an image —')] + .concat(targets.map(t => el('option', {value: t.id}, t.title))) + ); + const launch = el('button', {}, 'Launch for all waiting'); + const msg = el('div', {class:'msg'}); + launch.onclick = async () => { + if (!pick.value) { msg.textContent = 'Pick an image first.'; msg.className='msg err'; return; } + const r = await postJSON('/api/gate/assign', { target: pick.value, gate_ids: [] }); + if (!r.ok) { msg.textContent = 'Assign failed: ' + r.status; msg.className='msg err'; return; } + const j = await r.json(); + if (!j.ok) { msg.textContent = 'Assign failed: ' + (j.error || 'unknown'); msg.className='msg err'; return; } + msg.textContent = 'Launched ' + j.assigned + ' client' + (j.assigned===1?'':'s') + ' → ' + j.target; + msg.className = 'msg ok'; + render('gate'); + }; + + const track = gates.length + ? el('div', {class:'gate-track'}, + gates.map(g => el('div', {class:'gate-row' + (g.assigned_target ? ' assigned' : '')}, [ + el('div', {class:'pos'}, '#' + g.position), + el('div', {}, [ + el('div', {class:'mac'}, g.mac), + el('div', {class:'meta'}, + (g.ip ? String(g.ip) + ' · ' : '') + archLabel(g.arch) + ' · joined ' + fmtAgo(g.joined_at)), + ]), + el('div', {}, g.assigned_target + ? el('span', {class:'tag ok'}, '→ ' + g.assigned_target) + : el('span', {class:'tag accent'}, 'waiting')), + el('button', {class:'ghost', onclick: async () => { + await fetch('/api/gate/' + encodeURIComponent(g.id), {method:'DELETE'}); + render('gate'); + }}, 'Release'), + ])) + ) + : el('div', {class:'empty'}, + 'No clients at the gate. Boot a client and choose "Gated Deployment" in the PXE menu.'); + + return el('div', {class:'grid'}, [ + el('div', {class:'card'}, [ + el('header', {}, el('h2', {}, 'Launch an image across the gate')), + el('div', {class:'body'}, [ + el('label', {class:'field'}, [ + el('span', {class:'name'}, 'Target image'), + pick, + el('span', {class:'hint'}, + 'Selecting "Launch" starts every waiting client on the chosen image simultaneously.'), + ]), + launch, msg, + ]), + ]), + el('div', {class:'card'}, [ + el('header', {}, [ + el('h2', {}, 'Gate positions'), + el('span', {class:'sub'}, gates.length + ' waiting'), + ]), + el('div', {class:'body'}, track), + ]), + ]); + }, + + storage: async () => { + const [isos, settings, nfsRes] = await Promise.all([ + getJSON('/api/isos'), getJSON('/api/settings'), getJSON('/api/nfs'), + ]); + const mounts = nfsRes.mounts || []; + + // ── Upload card ── + const drop = el('div', {class:'drop', id:'drop'}, [ + el('div', {}, ['Drop an ', el('strong', {}, '.iso'), ' here, or click to choose.']), + el('div', {style:'font-size:12px;margin-top:6px'}, + 'Linux + Windows installers auto-detected on upload. Streaming, no 502s on big files.'), + ]); + const file = el('input', {type:'file', accept:'.iso,application/octet-stream', + style:'display:none', id:'file'}); + const prog = el('div', {class:'progress', id:'prog'}, el('div', {class:'bar', id:'bar'})); + const upMsg = el('div', {class:'msg', id:'upmsg'}); + + drop.onclick = () => file.click(); + drop.addEventListener('dragover', e => { e.preventDefault(); drop.classList.add('hover'); }); + drop.addEventListener('dragleave', () => drop.classList.remove('hover')); + drop.addEventListener('drop', e => { + e.preventDefault(); drop.classList.remove('hover'); + if (e.dataTransfer.files[0]) upload(e.dataTransfer.files[0]); + }); + file.onchange = () => { if (file.files[0]) upload(file.files[0]); }; + + function upload(f) { + upMsg.textContent = 'Uploading ' + f.name + ' (' + fmtBytes(f.size) + ')…'; + upMsg.className = 'msg'; + prog.classList.add('active'); + const fd = new FormData(); fd.append('file', f); + const xhr = new XMLHttpRequest(); + xhr.upload.onprogress = e => { + if (e.lengthComputable) $('#bar').style.width = (e.loaded/e.total*100).toFixed(1) + '%'; + }; + xhr.onload = () => { + prog.classList.remove('active'); + $('#bar').style.width = '0'; + if (xhr.status >= 200 && xhr.status < 300) { + upMsg.textContent = 'Uploaded & analyzed.'; upMsg.className = 'msg ok'; + render('storage'); + } else { + upMsg.textContent = 'Upload failed: ' + xhr.status + ' ' + xhr.responseText; + upMsg.className = 'msg err'; + } + }; + xhr.onerror = () => { upMsg.textContent = 'Network error.'; upMsg.className = 'msg err'; }; + xhr.open('POST', '/api/isos'); + xhr.send(fd); + } + + // ── ISO table (mixed local + NFS) ── + const rows = isos.map(i => { + const b = bootability(i, settings); + const isNfs = i.source && i.source.kind === 'nfs'; + const tr = el('tr', b.ok ? {} : {class: 'unbootable'}, [ + el('td', {}, [ + el('div', {}, i.filename), + !b.ok ? el('div', {class:'row-warn'}, '⚠ ' + b.reason) + : (b.warn ? el('div', {class:'row-warn'}, '⚠ ' + b.warn) : null), + ]), + el('td', {}, el('span', {class:'tag'}, familyLabel(i.introspection.family))), + el('td', {class:'num'}, fmtBytes(i.size_bytes)), + el('td', {}, + el('span', {class:'src-badge' + (isNfs ? ' nfs' : '')}, + isNfs ? ('nfs:' + i.source.mount_id) : 'local')), + el('td', {}, fmtAgo(i.uploaded_at)), + el('td', {style:'text-align:right'}, + isNfs + ? el('span', {class:'tag', style:'opacity:.6'}, 'manage on NFS share') + : el('button', {class:'danger', onclick: async () => { + if (!confirm('Remove this image?')) return; + await fetch('/api/isos/' + encodeURIComponent(i.id), {method:'DELETE'}); + render('storage'); + }}, 'Remove')), + ]); + return tr; + }); + const isoTable = isos.length + ? el('table', {}, [ + el('thead', {}, el('tr', {}, [ + el('th',{},'Name'), el('th',{},'Type'), + el('th',{class:'num'},'Size'), + el('th',{},'Source'), el('th',{},'Uploaded'), el('th',{},''), + ])), + el('tbody', {}, rows), + ]) + : el('div', {class:'empty'}, 'No images yet. Upload an ISO or mount an NFS share.'); + + // ── NFS section ── + const nfsMsg = el('div', {class:'msg'}); + const nfsServer = el('input', {type:'text', placeholder:'10.0.0.20'}); + const nfsExport = el('input', {type:'text', placeholder:'/srv/isos'}); + const nfsVer = el('select', {}, [ + el('option', {value:'v41'}, 'NFSv4.1 (default)'), + el('option', {value:'v3'}, 'NFSv3'), + ]); + const nfsRo = el('input', {type:'checkbox'}); nfsRo.checked = true; + const addNfs = el('button', {onclick: async () => { + if (!nfsServer.value || !nfsExport.value) { + nfsMsg.textContent = 'Server and export are required.'; nfsMsg.className='msg err'; return; + } + nfsMsg.textContent = 'Mounting…'; nfsMsg.className = 'msg'; + const r = await postJSON('/api/nfs', { + server: nfsServer.value, export: nfsExport.value, + version: nfsVer.value, read_only: nfsRo.checked, + }); + if (r.ok) { + nfsMsg.textContent = 'Mounted.'; nfsMsg.className = 'msg ok'; + render('storage'); + } else { + const t = await r.text(); + nfsMsg.textContent = 'Mount failed: ' + t; nfsMsg.className = 'msg err'; + } + }}, 'Mount share'); + + const nfsRows = mounts.length ? mounts.map(m => el('div', {class: 'nfs-row' + (m.mounted ? '' : ' down')}, [ + el('span', {class: 'dot ' + (m.mounted ? 'ok' : 'err')}), + el('div', {}, [ + el('div', {class:'id'}, m.server + ':' + m.export), + el('div', {class:'meta'}, + (m.version === 'v3' ? 'NFSv3' : 'NFSv4.1') + ' · ' + + (m.read_only ? 'read-only' : 'read-write') + ' · ' + + (m.mounted ? m.iso_count + ' isos' : 'not mounted')), + m.last_error ? el('div', {class:'err'}, '⚠ ' + m.last_error) : null, + ]), + el('button', {class:'ghost', onclick: async () => { + const r = await postJSON('/api/nfs/' + encodeURIComponent(m.id) + '/scan', {}); + if (r.ok) render('storage'); + }}, 'Re-scan'), + el('button', {class:'danger', onclick: async () => { + if (!confirm('Unmount ' + m.server + ':' + m.export + '?')) return; + await fetch('/api/nfs/' + encodeURIComponent(m.id), {method:'DELETE'}); + render('storage'); + }}, 'Unmount'), + el('span'), + ])) : [el('div', {class:'empty'}, 'No NFS shares mounted.')]; + + return el('div', {class:'grid'}, [ + el('div', {class:'card'}, [ + el('header', {}, el('h2', {}, 'Upload ISO')), + el('div', {class:'body'}, [drop, file, prog, upMsg]), + ]), + el('div', {class:'card'}, [ + el('header', {}, [ + el('h2', {}, 'NFS shares'), + el('span', {class:'sub'}, mounts.length + ' configured'), + ]), + el('div', {class:'body'}, [ + el('div', {class:'form-row'}, [ + el('label', {class:'field'}, [ + el('span', {class:'name'}, 'NFS server'), + nfsServer, + ]), + el('label', {class:'field'}, [ + el('span', {class:'name'}, 'Export path'), + nfsExport, + ]), + el('label', {class:'field'}, [ + el('span', {class:'name'}, 'Version'), + nfsVer, + ]), + el('label', {class:'check', style:'margin-top:18px'}, [ + nfsRo, el('span', {}, 'Read-only'), + ]), + ]), + addNfs, nfsMsg, + el('div', {style:'margin-top:18px;display:grid;gap:8px'}, nfsRows), + el('p', {class:'msg', style:'margin-top:14px'}, + 'Mounting NFS inside a container requires CAP_SYS_ADMIN and the ' + + 'mount.nfs binary (bundled in the default Docker image). On ' + + 'OpenShift, your SCC must allow CAP_SYS_ADMIN or you can run ' + + 'NFS mounts as a CSI driver outside the pod.'), + ]), + ]), + el('div', {class:'card'}, [ + el('header', {}, [ + el('h2', {}, 'Available images'), + el('span', {class:'sub'}, isos.length + ' image' + (isos.length === 1 ? '' : 's')), + ]), + isoTable, + ]), + ]); + }, + + terminal: async () => { + // Two-pane layout: live log on top (auto-scrolling), command line + // on bottom. Mirrors the Minecraft-server console feel from the + // brief — output and input share one continuous timeline. + const pane = el('div', {class:'pane'}); + const input = el('input', {type:'text', placeholder:'type a command, or "help"', spellcheck:'false', autocapitalize:'off', autocomplete:'off'}); + const auto = el('input', {type:'checkbox'}); auto.checked = true; + const clearBtn = el('button', {onclick: () => { pane.innerHTML = ''; }}, 'Clear pane'); + const tailBtn = el('button', {onclick: () => { auto.checked = !auto.checked; }}, 'Auto-scroll'); + + const term = el('div', {class:'terminal'}, [ + el('div', {class:'toolbar'}, [ + el('span', {}, 'Live log + operator console'), + el('div', {class:'right'}, [ + el('label', {class:'check', style:'border:0;padding:0;margin:0;background:transparent'}, + [auto, el('span', {style:'color:var(--fg-dim);font-size:11px'}, 'Auto-scroll')]), + clearBtn, + ]), + ]), + pane, + el('div', {class:'input-row'}, [ + el('span', {class:'prompt'}, '>'), + input, + ]), + ]); + + function append(line, kind) { + const lvl = (line.level || 'info').toLowerCase(); + const ts = (line.timestamp || new Date().toISOString()).replace(/\.\d+/, '').replace('T', ' ').replace('Z', ''); + const span = el('span', {class: 'lvl-' + lvl}, [ + el('span', {class:'ts'}, ts + ' '), + el('span', {class:'tg'}, '[' + (line.target || 'pxeforge') + '] '), + line.message, + '\n', + ]); + if (kind === 'echo') { + span.firstChild.nextSibling.textContent = ''; + span.firstChild.textContent = ''; + span.classList.add('echo'); + } + pane.appendChild(span); + if (auto.checked) pane.scrollTop = pane.scrollHeight; + } + + // Initial fetch — show recent buffer in case SSE is slow to open. + try { + const r = await getJSON('/api/log/recent'); + for (const l of (r.lines || [])) append(l); + } catch (e) { + append({timestamp: new Date().toISOString(), level:'warn', target:'pxeforge::ui', + message: 'failed to load recent logs: ' + e.message}); + } + + // Live SSE stream. EventSource auto-reconnects on disconnect. + const es = new EventSource('/api/log/stream'); + es.onmessage = (ev) => { + try { append(JSON.parse(ev.data)); } + catch { append({timestamp: new Date().toISOString(), level:'debug', target:'pxeforge::ui', message: ev.data}); } + }; + es.addEventListener('lagged', (ev) => { + const j = JSON.parse(ev.data || '{}'); + append({timestamp: new Date().toISOString(), level:'warn', + target:'pxeforge::ui', + message: 'log stream lagged: ' + (j.skipped || '?') + ' lines skipped'}); + }); + es.onerror = () => { + // EventSource quietly retries; surface a hint without spamming. + // We only append once, on transition from connected → erroring. + if (!term._notedErr) { + term._notedErr = true; + append({timestamp: new Date().toISOString(), level:'warn', target:'pxeforge::ui', + message: 'log stream connection lost — auto-reconnecting'}); + setTimeout(() => { term._notedErr = false; }, 5000); + } + }; + // Close the SSE when the view changes — avoids piling up streams. + term._cleanup = () => es.close(); + + // Command history (in-memory only, ↑/↓ to recall). + const history = []; + let hi = -1; + + input.addEventListener('keydown', async (e) => { + if (e.key === 'Enter') { + const cmd = input.value; + if (!cmd.trim()) return; + input.value = ''; + history.unshift(cmd); if (history.length > 100) history.pop(); + hi = -1; + // The echo also comes back from the server in the live tail, + // so we don't append it locally — keeps the order consistent. + try { + const r = await postJSON('/api/terminal', {command: cmd}); + const j = await r.json(); + const out = j.output || ''; + if (out === '\f') { pane.innerHTML = ''; return; } + // Output also gets pushed onto the LogBus by the server, but + // include it locally so even if the SSE stream dropped we + // see it. Tagged "echo" so it stands out from regular logs. + append({timestamp: new Date().toISOString(), level: j.ok ? 'info' : 'warn', + target: 'terminal-output', message: out}); + } catch (err) { + append({timestamp: new Date().toISOString(), level:'error', + target:'pxeforge::ui', message: 'command failed: ' + err.message}); + } + } else if (e.key === 'ArrowUp') { + if (history.length === 0) return; + hi = Math.min(hi + 1, history.length - 1); + input.value = history[hi]; + e.preventDefault(); + } else if (e.key === 'ArrowDown') { + hi = Math.max(hi - 1, -1); + input.value = hi < 0 ? '' : history[hi]; + e.preventDefault(); + } + }); + + // Welcome banner. + append({timestamp: new Date().toISOString(), level:'info', target:'pxeforge::terminal', + message: 'Connected. Type "help" for available commands.'}); + + // Focus the input on next tick (after view swap completes). + setTimeout(() => input.focus(), 50); + + return term; + }, + + about: async () => { + const status = await getJSON('/api/status'); + return el('div', {class:'card'}, [ + el('div', {class:'about-hero'}, [ + el('h2', {}, 'PXEForge'), + el('p', {class:'lead'}, + 'Air-gapped network PXE boot, container-native, that anyone can run. ' + + 'No CDN calls, no telemetry, no surprise external dependencies — ship ' + + 'the image once, run it forever.'), + el('div', {class:'who'}, [ + el('span', {}, 'Developer: '), el('strong', {}, 'Miles Ward'), el('br'), + el('span', {}, 'Version: '), el('strong', {}, status.version || '?'), el('br'), + el('span', {}, 'Base URL: '), el('strong', {}, status.public_base_url), + ]), + el('p', {class:'msg', style:'margin-top:18px'}, + 'iPXE is an internal implementation detail. Everything the firmware ' + + 'executes is generated from the settings on these tabs — there is no ' + + 'hand-written .ipxe path anywhere in this product.'), + el('p', {class:'msg'}, + 'Vision: a deployment-grade tool that works on first try in the most ' + + 'awkward environments — air-gapped labs, customer sites without ' + + 'internet, OpenShift clusters with strict SCCs — without ever asking ' + + 'an operator to install drivers signed with test certificates or to ' + + 'flip "testsigning" on a target machine.'), + ]), + ]); + }, + }; + + // ── shell ──────────────────────────────────────────────────────── + const viewTitles = { + dashboard: 'Dashboard', + network: 'Network', + gate: 'Forge Gate', + storage: 'Storage', + terminal: 'Terminal', + about: 'About', + }; + + let currentBody = null; + + async function render(view) { + view = view || 'dashboard'; + $$('.sidebar nav a').forEach(a => a.classList.toggle('active', a.dataset.view === view)); + $('[data-bind=view_title]').textContent = viewTitles[view] || view; + const root = $('#view-root'); + // Clean up any per-view resources (e.g. terminal SSE) before swap. + if (currentBody && typeof currentBody._cleanup === 'function') { + try { currentBody._cleanup(); } catch (e) { /* ignore */ } + } + root.innerHTML = ''; + root.appendChild(el('div', {class:'msg'}, 'Loading…')); + try { + const body = await views[view](); + root.innerHTML = ''; + root.appendChild(body); + currentBody = body; + } catch (e) { + root.innerHTML = ''; + root.appendChild(el('div', {class:'msg err'}, 'Error: ' + e.message)); + } + } + + async function refreshChips() { + try { + const s = await getJSON('/api/status'); + const r = await fetch('/readyz'); + $$('[data-bind=version]').forEach(n => n.textContent = s.version); + $$('[data-bind=iso_count],[data-bind=iso_count2]').forEach(n => n.textContent = String(s.iso_count)); + $$('[data-bind=client_count],[data-bind=client_count2]').forEach(n => n.textContent = String(s.client_count)); + $$('[data-bind=gate_count],[data-bind=gate_count2]').forEach(n => n.textContent = String(s.gate_count)); + const chip = $('[data-bind=ready_chip]'); + if (chip) { + if (r.ok) { chip.textContent = '● ready'; chip.className = 'chip ready'; } + else { chip.textContent = '● not ready'; chip.className = 'chip notready'; } + } + } catch { + const chip = $('[data-bind=ready_chip]'); + if (chip) { chip.textContent = '● unreachable'; chip.className = 'chip notready'; } + } + } + + document.addEventListener('click', (e) => { + const a = e.target.closest('.sidebar nav a[data-view]'); + if (a) { e.preventDefault(); render(a.dataset.view); } + }); + + render('dashboard'); + refreshChips(); + setInterval(refreshChips, 3000); +})(); diff --git a/crates/webui/src/index.html b/crates/webui/src/index.html new file mode 100644 index 0000000..e007239 --- /dev/null +++ b/crates/webui/src/index.html @@ -0,0 +1,54 @@ + + + + + + PXEForge + + + + +
+ + +
+

Dashboard

+
+ checking… + 0 images + 0 clients + 0 at gate +
+ +
+
+ + + + diff --git a/crates/webui/src/lib.rs b/crates/webui/src/lib.rs new file mode 100644 index 0000000..dad5b1a --- /dev/null +++ b/crates/webui/src/lib.rs @@ -0,0 +1,29 @@ +//! Offline-only web UI. Everything the browser needs (HTML, CSS, JS, SVG +//! logo) is embedded in the compiled binary via `include_str!` / +//! `include_bytes!`. No CDN, no external fonts, no remote images — +//! PXEForge renders identically on an air-gapped network. +//! +//! Layout follows the Netbox Labs pattern: dark left sidebar with primary +//! nav, top bar with secondary tabs, card-dense content panels. +#![forbid(unsafe_code)] + +/// Render the top-level page. `base_url` is interpolated into the footer +/// so operators can see at a glance what URL clients are PXE-booting from. +#[must_use] +pub fn index_html(base_url: &str) -> String { + INDEX_HTML.replace("{{BASE_URL}}", base_url) +} + +#[must_use] +pub fn app_js() -> &'static str { APP_JS } + +#[must_use] +pub fn app_css() -> &'static str { APP_CSS } + +#[must_use] +pub fn logo_svg() -> &'static str { LOGO_SVG } + +const INDEX_HTML: &str = include_str!("index.html"); +const APP_CSS: &str = include_str!("app.css"); +const APP_JS: &str = include_str!("app.js"); +const LOGO_SVG: &str = include_str!("logo.svg"); diff --git a/crates/webui/src/logo.svg b/crates/webui/src/logo.svg new file mode 100644 index 0000000..1a973ad --- /dev/null +++ b/crates/webui/src/logo.svg @@ -0,0 +1,14 @@ + + PXEForge + + + + + + + + + + + + diff --git a/deploy/docker/.dockerignore b/deploy/docker/.dockerignore new file mode 100644 index 0000000..30b612a --- /dev/null +++ b/deploy/docker/.dockerignore @@ -0,0 +1,8 @@ +target +data/isos +data/work +.git +.github +docs +*.md +.claude diff --git a/deploy/docker/Dockerfile b/deploy/docker/Dockerfile new file mode 100644 index 0000000..54255f5 --- /dev/null +++ b/deploy/docker/Dockerfile @@ -0,0 +1,97 @@ +# syntax=docker/dockerfile:1.7 +# +# PXEForge — multi-stage build. +# +# Design: +# - stage `fetch`: runs scripts/fetch-ipxe.sh to pull official iPXE binaries +# into assets/ipxe/ so the rust build can embed them via rust-embed. +# - stage `build`: compiles the workspace with cargo in release mode. +# - stage `runtime`: Debian slim image with setcap for NET_BIND_SERVICE, +# running as a non-root UID. No shell in PATH for the service user; +# attacker surface is just the pxeforge binary + libc. +# +# Why not distroless? We want setcap support and easy debug (`oc rsh`). +# Debian slim at ~75 MB + binary ~25 MB is fine for a PXE server that +# spends most of its life idle. + +ARG RUST_VERSION=1.82 + +########## fetch iPXE binaries ########## +FROM debian:12-slim AS fetch +RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \ + && rm -rf /var/lib/apt/lists/* +WORKDIR /src +COPY scripts/fetch-ipxe.sh scripts/fetch-ipxe.sh +RUN mkdir -p assets/ipxe && bash scripts/fetch-ipxe.sh + +########## build pxeforge ########## +FROM rust:${RUST_VERSION}-bookworm AS build +WORKDIR /src + +# Copy the whole workspace in one go. We used to do a two-pass "cache-prime +# with stubs, then real build" dance for dep-compile reuse; that turned out +# to silently serve stale stub binaries when cargo's fingerprint didn't +# notice the source swap. A single build is ~1.5 min longer on cold cache +# but guarantees the binary reflects the sources we copied. +COPY Cargo.toml rust-toolchain.toml ./ +COPY crates/ crates/ +COPY --from=fetch /src/assets/ipxe /src/assets/ipxe + +# Cache cargo registry + target across builds. The `--no-edit` touch is +# belt-and-suspenders: cargo occasionally misses mtime-only changes on +# networked FS; this forces a fingerprint check. +RUN --mount=type=cache,target=/usr/local/cargo/registry \ + --mount=type=cache,target=/src/target,sharing=locked \ + find crates -name '*.rs' -exec touch {} + && \ + cargo build --release --bin pxeforge && \ + cp target/release/pxeforge /pxeforge && \ + ls -l /pxeforge + +########## runtime ########## +FROM debian:12-slim AS runtime +RUN apt-get update \ + && apt-get install -y --no-install-recommends \ + ca-certificates libcap2-bin tini gosu iproute2 \ + wimtools samba nfs-common \ + && rm -rf /var/lib/apt/lists/* \ + && useradd --system --uid 10001 --home-dir /var/lib/pxeforge --shell /usr/sbin/nologin pxeforge \ + && mkdir -p /var/lib/pxeforge/isos /var/lib/pxeforge/work /var/lib/pxeforge/smb \ + && chown -R pxeforge:pxeforge /var/lib/pxeforge +# Runtime deps explained: +# wimtools - provides `wimlib-imagex`, used to inject startnet.cmd into boot.wim. +# samba - `smbd` serves extracted Windows install media on :445 for WinPE +# to `net use`. Guest read-only, scoped to /var/lib/pxeforge/smb. +# nfs-common - provides `mount.nfs` / `mount.nfs4` for the Storage tab's +# NFS share manager. Mount also requires the container to run +# with CAP_SYS_ADMIN — without it, mount(2) returns EPERM and +# the manager surfaces a clear error in the UI instead of +# failing silently. +# iproute2 - `ip addr` / `ip route` for the auto-detected Network tab +# fields (NIC name, subnet mask, default gateway). Tiny, +# always available; we don't pull in netlink crates for +# this one-shot startup probe. +# gosu - drops privileges cleanly from root after the entrypoint fixes +# bind-mount ownership (common OpenShift/Docker UX issue). +# Windows-specific tools only activate when the WebUI toggle is on. + +COPY --from=build /pxeforge /usr/local/bin/pxeforge +COPY deploy/docker/entrypoint.sh /usr/local/bin/entrypoint.sh +RUN chmod +x /usr/local/bin/entrypoint.sh + +# Grant the binary the ability to bind <1024 ports as a non-root user. +# This is the only capability PXEForge needs for proxy-mode DHCP + TFTP + HTTP. +RUN setcap cap_net_bind_service=+ep /usr/local/bin/pxeforge + +# IMPORTANT: we do NOT `USER pxeforge` here. The entrypoint runs as root, +# chowns the mounted data dirs, then execs the binary via gosu as pxeforge. +# OpenShift ignores USER directives anyway (it injects its own uid), and +# there entrypoint.sh's non-root branch just execs directly. +WORKDIR /var/lib/pxeforge + +ENV PXEFORGE_ISO_DIR=/var/lib/pxeforge/isos \ + PXEFORGE_WORK_DIR=/var/lib/pxeforge/work \ + PXEFORGE_LOG=info,pxeforge=info + +EXPOSE 67/udp 69/udp 4011/udp 80/tcp 445/tcp + +ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/entrypoint.sh"] diff --git a/deploy/docker/entrypoint.sh b/deploy/docker/entrypoint.sh new file mode 100644 index 0000000..7c10bfe --- /dev/null +++ b/deploy/docker/entrypoint.sh @@ -0,0 +1,32 @@ +#!/bin/sh +# Container entrypoint that handles the common bind-mount-as-root case. +# +# When volumes are bind-mounted into the container (e.g. `-v ./data/isos:...`), +# they come up owned by the host uid:gid — often root:root. The pxeforge +# binary runs as uid 10001 and can't write there. This script, when started +# as root, chowns the two state dirs to the pxeforge user, then drops +# privileges via gosu before execing the binary. +# +# If the container is already running as non-root (OpenShift does this via +# its own uid assignment from the SCC), we skip the chown attempt and just +# exec the binary — OpenShift either preconfigures the volume with fsGroup +# or the operator is on their own for permissions. +set -e + +PXEFORGE_UID=${PXEFORGE_UID:-10001} +PXEFORGE_GID=${PXEFORGE_GID:-10001} +DATA_DIRS="/var/lib/pxeforge/isos /var/lib/pxeforge/work /var/lib/pxeforge/smb" + +if [ "$(id -u)" = "0" ]; then + for d in $DATA_DIRS; do + if [ -d "$d" ]; then + chown -R "${PXEFORGE_UID}:${PXEFORGE_GID}" "$d" 2>/dev/null || true + fi + done + # Re-exec ourselves under the pxeforge user so the binary inherits a + # clean process environment and a predictable umask. + exec gosu "${PXEFORGE_UID}:${PXEFORGE_GID}" /usr/local/bin/pxeforge "$@" +fi + +# Non-root: straight exec, no chown attempt. +exec /usr/local/bin/pxeforge "$@" diff --git a/deploy/openshift/00-namespace.yaml b/deploy/openshift/00-namespace.yaml new file mode 100644 index 0000000..08e2a35 --- /dev/null +++ b/deploy/openshift/00-namespace.yaml @@ -0,0 +1,11 @@ +apiVersion: v1 +kind: Namespace +metadata: + name: pxeforge + labels: + # Allow privileged pods (host-network) in this namespace only. The pod + # itself still runs non-root with only NET_BIND_SERVICE — privileged + # here is about namespace pod-security, not container privileges. + pod-security.kubernetes.io/enforce: privileged + pod-security.kubernetes.io/warn: privileged + pod-security.kubernetes.io/audit: privileged diff --git a/deploy/openshift/10-scc.yaml b/deploy/openshift/10-scc.yaml new file mode 100644 index 0000000..f8ab8d2 --- /dev/null +++ b/deploy/openshift/10-scc.yaml @@ -0,0 +1,80 @@ +--- +# Custom SCC for PXEForge. +# +# The default `restricted-v2` SCC blocks host network and all capabilities, +# which PXE cannot tolerate: DHCPDISCOVER is an L2 broadcast that CNI overlays +# do not deliver into pod netns. We grant the minimum set needed: +# +# - allowHostNetwork: true — required to receive broadcast DHCP +# - allowHostPorts: true — exposes 67/69/4011/80 on the node +# - requiredDropCapabilities strips the usual dangerous caps +# - allowedCapabilities: +# NET_BIND_SERVICE — bind <1024 as non-root +# - runAsUser.type: MustRunAsRange — force non-root uid mapped via setcap +# - readOnlyRootFilesystem: true — binary is in / (set by image), data +# dirs are mounted elsewhere +# +# We do NOT grant NET_RAW / NET_ADMIN / SYS_ADMIN. Proxy-mode DHCP does not +# need raw sockets (see architecture memory). +apiVersion: security.openshift.io/v1 +kind: SecurityContextConstraints +metadata: + name: pxeforge-scc + annotations: + kubernetes.io/description: >- + Minimal SCC for PXEForge: host network + NET_BIND_SERVICE only, no raw + sockets, no privileged mode. +allowPrivilegedContainer: false +allowPrivilegeEscalation: false +allowHostNetwork: true +allowHostPorts: true +allowHostPID: false +allowHostIPC: false +allowedCapabilities: + - NET_BIND_SERVICE +requiredDropCapabilities: + - ALL +defaultAddCapabilities: [] +readOnlyRootFilesystem: true +runAsUser: + type: MustRunAsRange +seLinuxContext: + type: MustRunAs +fsGroup: + type: MustRunAs +supplementalGroups: + type: RunAsAny +volumes: + - configMap + - downwardAPI + - emptyDir + - persistentVolumeClaim + - projected + - secret +users: [] +groups: [] +--- +# Bind the SCC to the pxeforge service account. +kind: ClusterRole +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: pxeforge-scc-use +rules: + - apiGroups: ["security.openshift.io"] + resources: ["securitycontextconstraints"] + resourceNames: ["pxeforge-scc"] + verbs: ["use"] +--- +kind: RoleBinding +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: pxeforge-scc-use + namespace: pxeforge +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: pxeforge-scc-use +subjects: + - kind: ServiceAccount + name: pxeforge + namespace: pxeforge diff --git a/deploy/openshift/20-sa-pvc-config.yaml b/deploy/openshift/20-sa-pvc-config.yaml new file mode 100644 index 0000000..e6fbfbb --- /dev/null +++ b/deploy/openshift/20-sa-pvc-config.yaml @@ -0,0 +1,35 @@ +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: pxeforge + namespace: pxeforge +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: pxeforge-config + namespace: pxeforge +data: + # Toggle DHCP proxy on or off. "proxy" = answer PXE clients alongside an + # existing DHCP server. "disabled" = require operator to point an external + # DHCP at us via next-server/filename. + PXEFORGE_DHCP_MODE: "proxy" + # Override if auto-detection picks the wrong NIC in multi-homed pods. + # Leave unset to auto-detect from the node's primary IPv4. + # PXEFORGE_PUBLIC_IP: "10.0.0.5" + PXEFORGE_LOG: "info,pxeforge=info" +--- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: pxeforge-isos + namespace: pxeforge +spec: + # ReadWriteOnce is fine — we deploy as a single replica since DHCP proxy + # coordination across replicas is not useful (clients hit whichever node + # hostNetwork catches their broadcast). + accessModes: ["ReadWriteOnce"] + resources: + requests: + storage: 200Gi diff --git a/deploy/openshift/30-deployment.yaml b/deploy/openshift/30-deployment.yaml new file mode 100644 index 0000000..8250bd8 --- /dev/null +++ b/deploy/openshift/30-deployment.yaml @@ -0,0 +1,104 @@ +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: pxeforge + namespace: pxeforge + labels: + app.kubernetes.io/name: pxeforge +spec: + # Single replica by design (see PVC comment). If HA is needed later, split + # the HTTP/web plane (scalable, stateless) from the DHCP-proxy/TFTP plane + # (anycast / per-node daemonset). + replicas: 1 + strategy: + type: Recreate + selector: + matchLabels: + app.kubernetes.io/name: pxeforge + template: + metadata: + labels: + app.kubernetes.io/name: pxeforge + spec: + serviceAccountName: pxeforge + # L2 broadcast (DHCPDISCOVER) does not cross most CNI overlays into + # pod netns. Host network is the working path. + hostNetwork: true + dnsPolicy: ClusterFirstWithHostNet + securityContext: + # setcap on the binary allows non-root <1024 binding. No need to + # run as root. + runAsNonRoot: true + runAsUser: 10001 + fsGroup: 10001 + containers: + - name: pxeforge + image: ghcr.io/casperadmin/pxeforge:0.1.0 + imagePullPolicy: IfNotPresent + ports: + - name: dhcp + containerPort: 67 + hostPort: 67 + protocol: UDP + - name: tftp + containerPort: 69 + hostPort: 69 + protocol: UDP + - name: pxe + containerPort: 4011 + hostPort: 4011 + protocol: UDP + - name: http + containerPort: 80 + hostPort: 80 + protocol: TCP + - name: smb + containerPort: 445 + hostPort: 445 + protocol: TCP + envFrom: + - configMapRef: + name: pxeforge-config + securityContext: + allowPrivilegeEscalation: false + readOnlyRootFilesystem: true + runAsNonRoot: true + runAsUser: 10001 + capabilities: + drop: ["ALL"] + add: ["NET_BIND_SERVICE"] + volumeMounts: + - name: isos + mountPath: /var/lib/pxeforge/isos + - name: work + mountPath: /var/lib/pxeforge/work + - name: tmp + mountPath: /tmp + readinessProbe: + httpGet: + path: /api/status + port: 80 + initialDelaySeconds: 3 + periodSeconds: 5 + livenessProbe: + httpGet: + path: /api/status + port: 80 + initialDelaySeconds: 15 + periodSeconds: 15 + resources: + requests: + cpu: 100m + memory: 128Mi + limits: + cpu: 1000m + memory: 512Mi + volumes: + - name: isos + persistentVolumeClaim: + claimName: pxeforge-isos + - name: work + emptyDir: {} + - name: tmp + emptyDir: {} diff --git a/deploy/openshift/40-service-route.yaml b/deploy/openshift/40-service-route.yaml new file mode 100644 index 0000000..71b4e5b --- /dev/null +++ b/deploy/openshift/40-service-route.yaml @@ -0,0 +1,43 @@ +--- +# Service for the web UI / API. Using host network means the pod IP is the +# node IP, so this Service is mostly useful for cluster-internal ingress to +# the management UI via Route below. +apiVersion: v1 +kind: Service +metadata: + name: pxeforge + namespace: pxeforge + labels: + app.kubernetes.io/name: pxeforge +spec: + type: ClusterIP + selector: + app.kubernetes.io/name: pxeforge + ports: + - name: http + port: 80 + targetPort: 80 + protocol: TCP + - name: smb + port: 445 + targetPort: 445 + protocol: TCP +--- +# Expose the web UI through an OpenShift Route. Clients on the PXE network +# still talk to the node directly on UDP 67/69/4011 — the Route only covers +# the TCP/80 management plane. +apiVersion: route.openshift.io/v1 +kind: Route +metadata: + name: pxeforge + namespace: pxeforge +spec: + to: + kind: Service + name: pxeforge + weight: 100 + port: + targetPort: http + tls: + termination: edge + insecureEdgeTerminationPolicy: Redirect diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..9c90768 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,66 @@ +# docker-compose for local / homelab deployment. +# +# Two usage patterns: +# +# 1. Local MVP test — host network, proxy-DHCP off (don't fight your +# existing DHCP server on the LAN), TFTP + HTTP exposed on the host: +# +# docker compose up pxeforge-dev +# +# 2. Real PXE deployment — host network, proxy-DHCP on, runs on a box +# plugged into the PXE network: +# +# # First set PXEFORGE_PUBLIC_IP to this host's LAN address in .env +# docker compose up pxeforge +# +# On Linux hosts, `network_mode: host` gives the container direct access to +# the physical NIC — required for DHCP proxy because CNI overlays and Docker +# bridges do not forward DHCPDISCOVER broadcasts into containers. +# +# On macOS / Windows hosts, `network_mode: host` is limited — the daemon +# runs in a Linux VM (Colima/Docker Desktop) so the "host" network is the +# VM, not your Mac. Proxy-DHCP is not feasible on macOS; use `pxeforge-dev` +# with published ports and set DHCP-MODE=disabled. + +services: + # Real PXE deployment (Linux hosts). + pxeforge: + image: pxeforge:0.1.0 + build: + context: . + dockerfile: deploy/docker/Dockerfile + restart: unless-stopped + network_mode: host + environment: + # REQUIRED on multi-homed hosts. Set to this machine's LAN IP so the + # advertised iPXE URLs actually resolve from the PXE clients. Without + # this, PXEForge will refuse to start rather than advertise a + # loopback address that can't be reached. + PXEFORGE_PUBLIC_IP: ${PXEFORGE_PUBLIC_IP:?set this to the host LAN IP} + PXEFORGE_DHCP_MODE: proxy + PXEFORGE_LOG: info + volumes: + - ./data/isos:/var/lib/pxeforge/isos + - ./data/work:/var/lib/pxeforge/work + + # Dev / MVP container: published ports, DHCP disabled, HTTP on 8080. + # Use this on laptops where you want to curl the API or UI without + # running an actual PXE chain. + pxeforge-dev: + image: pxeforge:0.1.0 + build: + context: . + dockerfile: deploy/docker/Dockerfile + environment: + PXEFORGE_PUBLIC_IP: ${PXEFORGE_PUBLIC_IP:-127.0.0.1} + PXEFORGE_DHCP_MODE: disabled + PXEFORGE_HTTP_PORT: "8080" + PXEFORGE_TFTP_PORT: "6969" + PXEFORGE_DHCP_PORT: "6767" + PXEFORGE_LOG: info,pxeforge=debug + ports: + - "8080:8080/tcp" + - "6969:6969/udp" + volumes: + - ./data/isos:/var/lib/pxeforge/isos + - ./data/work:/var/lib/pxeforge/work diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..891c514 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,270 @@ +# PXEForge architecture + +## Protocol stack + +``` +Client firmware PXE ROM + │ + │ DHCPDISCOVER (UDP/67 broadcast, option 60 "PXEClient", option 93 arch) + ▼ +┌─────────────────────────────────────────────────────────────────────────┐ +│ PXEForge │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ +│ │ DHCP proxy │ │ TFTP server │ │ HTTP server (axum) │ │ +│ │ :67, :4011 │ │ :69 │ │ :80 │ │ +│ │ (dhcproto) │ │ (custom) │ │ │ │ +│ └──────┬───────┘ └──────┬───────┘ └──────┬───────────────┘ │ +│ │ │ │ │ +│ └────────────────────┼─────────────────────┘ │ +│ │ │ +│ ┌──────────▼────────────┐ │ +│ │ IsoStore (on disk) │ │ +│ │ + ClientRegistry │ │ +│ └───────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────┘ + │ + ▼ reply with option 60, option 66 tftp-server, option 67 bootfile +Client firmware PXE ROM + │ + │ TFTP RRQ: snponly.efi (or undionly.kpxe for BIOS) + ▼ +Client runs iPXE + │ + │ DHCPDISCOVER with option 77 "iPXE" + ▼ +PXEForge sees user-class "iPXE" → replies with HTTP URL: /boot.ipxe + │ + │ HTTP GET /boot.ipxe (iPXE menu, auto-generated from IsoStore) + ▼ +User picks entry; iPXE chains /boot/.ipxe + │ + │ HTTP GET kernel + initrd (or wimboot + WIM files) + ▼ +Kernel boots with distro-specific args pointing back at /iso/.iso +``` + +## Crate layout + +| 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 | + +## Key decisions and why + +### DHCP proxy only, not a full DHCP server + +Proxy mode (RFC 4578) replies with boot parameters (`siaddr`, option 66, 67) +but never sets `yiaddr` — it does not lease IPs. The client merges proxy +replies with its normal DHCP lease from the network's existing DHCP server. + +This sidesteps needing `CAP_NET_RAW` or AF_PACKET. A full DHCP server has +to craft Ethernet frames to a client that doesn't yet have an IP — that +requires raw sockets and elevated privileges. A proxy replies on UDP to a +client that already has an IP (or will shortly, from the other DHCP server), +so plain `SOCK_DGRAM` is enough. + +### Two-stage iPXE chain + +1. Firmware PXE ROM sends DHCPDISCOVER with option 60 = `PXEClient`, + option 93 = arch. +2. PXEForge 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 + in option 67 pointing at `/boot.ipxe`. +6. iPXE fetches and executes that script, which chains the selected OS. + +The split is essential because firmware PXE ROMs only speak TFTP; they +don't do HTTP. iPXE adds HTTP (and a lot more), and is small enough to fit +in the TFTP hop. + +### TFTP option negotiation is mandatory + +Default 512-byte blocks means an ~1 MiB iPXE binary is ~2000 packets. +On anything less than pristine wired Ethernet this is unusably slow or +outright fails. We negotiate: + +- `blksize` (RFC 2348): up to ~1468 bytes for Ethernet MTU +- `tsize` (RFC 2349): file size; some PXE ROMs require it present +- `windowsize` (RFC 7440): 8–16 gives order-of-magnitude throughput gains + +### Do not touch the client OS trust store + +Whatever we do for Windows, we never: + +- ship drivers signed with test/development certificates +- 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. + +### Linux ISO boot uses kernel+initrd extraction, not sanboot + +Loading a full ISO into RAM via `memdisk` or `sanboot` fails: +- Above ~1–2 GiB, RAM emulation is too slow or too large. +- Most modern distros can't find the emulated CD device from the initramfs. + +We instead extract `vmlinuz` + `initrd` at upload time (well, look up their +locations — we serve them via ISO9660 byte-range lookup, no extraction on +disk) and pass distro-specific kernel args that point the installer back at +the HTTP-served ISO. + +### No iPXE UX + +iPXE is an implementation detail. The web UI only accepts `.iso` uploads +and shows distros, not `.ipxe` scripts or boot targets. If someone who +knows iPXE wants to peek, they can `curl /boot.ipxe` — that's fine. But +the UI never surfaces it. + +## Unit tests + +Run with `cargo test --workspace --lib`. Current coverage: + +- `ClientArch` alias handling (0x0009 → x86_64 UEFI) +- `FirmwareClass` classification (iPXE wins over PXEClient echo) +- Raw option-93 extraction from the wire +- TFTP RRQ parsing with options +- HTTP Range header parsing (full, open-ended, suffix, explicit) +- Distro family detection from volume label +- ISO id slugification + +## Phase 3 hardening + +A code-review pass after Phase 2 turned up 16 issues across the protocol +stack and container surface. Everything P0/P1/P2 is addressed in this +release: + +**Protocol reliability** (review P1 #10/#12): +- TFTP retransmit loop rewritten with explicit window tracking so UEFI SNP + clients no longer hang on files that end mid-window. Covered by 4 new + unit tests (`plan_window_*` in `crates/tftp`). +- DHCP proxy now honors the broadcast-flag bit (RFC 2131 §4.1) when + choosing unicast vs broadcast reply destination. + +**Container posture** (review P1 #2/#13/#14/#15): +- Multi-arch container (linux/amd64 + linux/arm64) via `buildx`. +- New entrypoint (`deploy/docker/entrypoint.sh`) chowns data dirs as root, + then drops to uid 10001 via `gosu` — fixes the "bind-mount comes up + 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 + 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 + toggle: `start` → spawn + write `smb.conf`; `reconcile` → SIGHUP on + share changes; `stop` → SIGTERM. `SmbState` surfaced to the UI for + visibility. +- `extract_windows_iso` shells out to `7z` (or `bsdtar` fallback) to + unpack the ISO tree into `smb_dir//` as the SMB share root. +- `WimPatcher` (from Phase 2) is still in place for `boot.wim` injection. +- Guardrail: flipping the Windows toggle in `/api/settings` is rejected + with a 400 if `wimboot` isn't bundled. + +**iVentoy/Bootimus parity** (P2): +- 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" + or "assigned: ubuntu-linux" status inline. + +**Developer ergonomics** (new): +- `pxeforge seed --from ` 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). + +**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 + 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 / +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 + it under `/nfs//` 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 + resolves these to disk lazily via `set_nfs_root`, so adding NFS + required exactly one new field on `IsoMeta` (with a serde default for + forward compatibility with old `meta.json` files). +- Versions: `vers=3` and `vers=4.1` only. v3 also gets `nolock` since + appliances commonly disable `lockd`. All mounts use `soft,timeo=100` + so a dead server surfaces as a UI error rather than wedging iPXE. +- State persists to `/nfs.json`. On startup the manager + re-attempts every spec; failures are logged per-mount and surfaced in + the UI rather than blocking startup. +- Container requirement: `mount.nfs` binary plus `CAP_SYS_ADMIN`. The + default Dockerfile bundles `nfs-common`. OpenShift operators must + swap to a more permissive SCC or use a CSI driver. + +**Live log + operator terminal** (`crates/core/src/log_bus.rs`, +`crates/http-api/src/{log_stream,terminal}.rs`): +- A `LogBusLayer` feeds every tracing event into a 500-line ring buffer + plus a `tokio::sync::broadcast` channel. +- `/api/log/stream` is an SSE endpoint that emits the recent buffer + 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}`, + `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. +- The whitelist exists deliberately — exposing a raw shell to the web + would be an RCE endpoint. + +**Network tab**: +- `/api/network` exposes auto-detected `nic_name`, `subnet_mask`, and + `gateway` (parsed from `ip route` / `ip addr` at startup). These are + 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 + server; the field exists so operators don't have to dig out the + upstream DNS at 3 AM. + +**Bootimus parity nicks** (Bootimus v0.1.55 → v0.1.62): +- Storage table tints amber for ISOs that won't boot with current + settings (Windows ISO when Windows is disabled, Linux ISO with no + detected kernel + over the sanboot size threshold). Each row carries + an inline reason — same affordance as Bootimus's "Image Properties" + 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. +- Streaming uploads are already in place via axum multipart; the v0.1.62 + fix to "502 on big upload" doesn't apply. + +## What's deferred to Phase 5 + +- Full ISO9660 + Joliet + Rock Ridge parser (current lookup is plain ISO9660 — Debian ISOs with Rock Ridge extensions may miss some paths). +- Real-hardware Windows boot validation (plumbing tested; no MS ISO pushed through the full pipeline yet). +- Real-hardware NFS validation (mount manager tested; no real NAS pushed + through the full pipeline yet). +- UEFI HTTP Boot protocol (option 60 = `HTTPClient`) untested on real firmware. +- Raspberry Pi netboot quirks (option 43 vendor-specific, per-MAC prefixes). +- Multi-replica / daemonset deployment model (single replica for now). +- Pure-Rust SMB server (replace smbd) — slim image, no Samba. +- Auto-install / autounattend file library (Bootimus v0.1.58 pattern). +- Per-client / per-group menus (Bootimus v0.1.16 pattern). diff --git a/rust-toolchain.toml b/rust-toolchain.toml new file mode 100644 index 0000000..73cb934 --- /dev/null +++ b/rust-toolchain.toml @@ -0,0 +1,3 @@ +[toolchain] +channel = "stable" +components = ["rustfmt", "clippy"] diff --git a/scripts/fetch-ipxe.sh b/scripts/fetch-ipxe.sh new file mode 100755 index 0000000..34ce285 --- /dev/null +++ b/scripts/fetch-ipxe.sh @@ -0,0 +1,83 @@ +#!/usr/bin/env bash +# Fetch prebuilt iPXE binaries from the official distribution at +# https://boot.ipxe.org/ and place them under assets/ipxe/ with the filenames +# PXEForge's arch mapping expects. +# +# Why not build from source? +# - Building iPXE requires the toolchain + several megabytes of source, and +# the official binaries are rebuilt nightly from upstream master with the +# standard driver set. For Phase 1 we use those. A later iteration can +# add an optional Dockerfile build stage that compiles iPXE with custom +# driver or scripting patches if needed. +# +# Safety: +# - Upstream (boot.ipxe.org) serves over HTTPS. +# - We do NOT pin by sha256 because upstream is a nightly rolling build; +# pinning would mean stale binaries with known CVEs. If you need +# deterministic builds, mirror these to your own artifact store and +# point the Dockerfile there instead. +# - Each binary is boot firmware the client executes. Only fetch from +# upstream or a mirror you trust; never from random sources. + +set -euo pipefail + +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +DEST="$ROOT/assets/ipxe" +mkdir -p "$DEST" + +# Map: local filename <- upstream path on boot.ipxe.org +# Upstream uses arch-scoped subdirectories; we flatten to the names our +# ClientArch::ipxe_bootfile() expects. +declare -a MAP=( + "undionly.kpxe=undionly.kpxe" + "snponly.efi=x86_64-efi/snponly.efi" + "snponly-i386.efi=i386-efi/snponly.efi" + "snponly-arm64.efi=arm64-efi/snponly.efi" + "ipxe.efi=x86_64-efi/ipxe.efi" # fallback with bundled drivers +) + +BASE="https://boot.ipxe.org" + +# wimboot lives in its own GitHub release. Fetching it enables the Windows +# toggle in the WebUI. Safe to leave disabled — the binary is vendor-signed +# for iPXE's own use; we never modify it and it only runs inside iPXE's +# memory space, never the target OS. +WIMBOOT_URL="https://github.com/ipxe/wimboot/releases/latest/download/wimboot" + +fetched=0 +for entry in "${MAP[@]}"; do + local_name="${entry%%=*}" + upstream_name="${entry#*=}" + url="$BASE/$upstream_name" + out="$DEST/$local_name" + echo ">> fetching $url -> $out" + if ! curl --fail --silent --show-error --location --output "$out.tmp" "$url"; then + echo " skip: upstream not available ($url)" + rm -f "$out.tmp" + continue + fi + mv "$out.tmp" "$out" + fetched=$((fetched+1)) +done + +if [ "$fetched" -eq 0 ]; then + echo + echo "ERROR: zero iPXE binaries were downloaded. The container would build" + echo " but no PXE client could boot. Check your network egress to" + echo " $BASE and re-run this script. Aborting." + exit 2 +fi + +echo +echo ">> fetching wimboot (optional, enables Windows ISO support)" +if curl --fail --silent --show-error --location --output "$DEST/wimboot.tmp" "$WIMBOOT_URL"; then + mv "$DEST/wimboot.tmp" "$DEST/wimboot" + echo " wimboot installed" +else + echo " skip: wimboot unreachable — Windows toggle will stay disabled in the WebUI" + rm -f "$DEST/wimboot.tmp" +fi + +echo +echo "iPXE assets now in $DEST:" +ls -lh "$DEST" | tail -n +2