Compare commits

...
4 Commits
Author SHA1 Message Date
Miles Ward 4e88305101 Name update 2026-05-06 14:14:09 -04:00
Miles Ward 20c585e3ed Name update 2026-05-06 14:13:38 -04:00
503432756 e1b7154b51 docs: add Linux network-boot runbook 2026-04-30 11:35:47 -04:00
Miles Ward 40064906de Name update 2026-04-30 02:30:05 -04:00
57 changed files with 1305 additions and 793 deletions
+1
View File
@@ -11,3 +11,4 @@ data/work/
# settings.local.json is your personal allowlist history and shouldn't be).
.claude/settings.local.json
.claude/worktrees/
.claude/scheduled_tasks.lock
+11 -11
View File
@@ -8,16 +8,16 @@ members = [
"crates/iso-store",
"crates/ipxe-assets",
"crates/webui",
"crates/pxeforge",
"crates/openpxe",
]
[workspace.package]
version = "0.2.0"
version = "0.3.0"
edition = "2021"
rust-version = "1.80"
license = "MIT OR Apache-2.0"
repository = "https://github.com/casperadmin/PXEForge"
authors = ["PXEForge contributors"]
repository = "https://gitea.milesward.dev/mward4/OpenPXE"
authors = ["OpenPXE contributors"]
[workspace.dependencies]
tokio = { version = "1.40", features = ["full"] }
@@ -57,13 +57,13 @@ 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" }
openpxe-core = { path = "crates/core" }
openpxe-dhcp-proxy = { path = "crates/dhcp-proxy" }
openpxe-tftp = { path = "crates/tftp" }
openpxe-http-api = { path = "crates/http-api" }
openpxe-iso-store = { path = "crates/iso-store" }
openpxe-ipxe-assets = { path = "crates/ipxe-assets" }
openpxe-webui = { path = "crates/webui" }
[workspace.lints.rust]
unsafe_code = "deny"
+48 -48
View File
@@ -1,4 +1,4 @@
# PXEForge
# OpenPXE
Container-native PXE boot server. A Rust reimplementation of
[iVentoy (ventoy/PXE)](https://github.com/ventoy/PXE), designed from scratch
@@ -6,7 +6,7 @@ for Docker/OCI and OpenShift. Upload `.iso` files via the web UI; network
clients PXE-boot them.
> **Status:** v0.2.0 / pre-beta. Phases 15 complete: full PXE stack,
> Gated Deployment queue, NFS-share ISO sources, live tracing log + an
> Queued Deployment queue, NFS-share ISO sources, live tracing log + an
> operator terminal, per-MAC host bindings (Tinkerbell-style),
> Prometheus `/metrics`, light/dark theme toggle, animated anvil
> imaging-progress widget. **66 tests passing**, clippy clean. Ready
@@ -38,11 +38,11 @@ clients PXE-boot them.
```
Default > Boot from Local HDD
Installers > Linux Installers / Windows Installers
Tools > Utilities / PXEForge Shell / Network Card Info
Gated Deployment
Tools > Utilities / OpenPXE Shell / Network Card Info
Queued Deployment
```
6. **Gated Deployment queue** — the "horse race gate" flow. A client that
selects *Gated Deployment* gets a numbered position and waits. The
6. **Queued Deployment queue** — the "horse race" launch flow. A client that
selects *Queued Deployment* gets a numbered position and waits. The
operator picks an ISO in the web UI and fires it to every waiting
client simultaneously.
7. **Web UI** (Netbox-style): sidebar nav (Dashboard / Network / Forge
@@ -54,11 +54,11 @@ clients PXE-boot them.
skips the menu, chains straight through. Inspired by Tinkerbell's
`smee` MAC-prepended URL pattern.
9. **Prometheus metrics** at `/metrics` — DHCP replies by arch, TFTP
transfer counts and bytes, HTTP request counts by route, gate /
transfer counts and bytes, HTTP request counts by route, queue /
imaging gauges, uptime, build info. Plain text exposition format,
no external metrics framework dependency.
8. **Settings API** lets you change the default boot-menu timeout (default
600s), the timeout action (stay / Local HDD / Gated Deployment), and
600s), the timeout action (stay / Local HDD / Queued Deployment), and
feature toggles like Windows ISO support. The iPXE scripts regenerate
on every request using current settings.
@@ -81,17 +81,17 @@ skip TFTP and respond with an HTTP URL.
./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 .
docker buildx build -f deploy/docker/Dockerfile -t openpxe:0.1.0 --load .
# 3. Run it on the box plugged into your PXE network. Set PUBLIC_IP to
# this host's LAN address so advertised iPXE URLs are reachable.
docker run -d --name pxeforge \
docker run -d --name openpxe \
--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
-e OPENPXE_PUBLIC_IP=10.0.0.5 \
-e OPENPXE_DHCP_MODE=proxy \
-v $PWD/data/isos:/var/lib/openpxe/isos \
-v $PWD/data/work:/var/lib/openpxe/work \
openpxe:0.1.0
# 4. Open the UI and drop an ISO in.
open http://10.0.0.5
@@ -99,16 +99,16 @@ 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
VM, so "host" means the VM — use `openpxe-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
OPENPXE_PUBLIC_IP=127.0.0.1 docker compose up openpxe-dev
# Real PXE deployment on a Linux host (host network, DHCP proxy on):
PXEFORGE_PUBLIC_IP=10.0.0.5 docker compose up pxeforge
OPENPXE_PUBLIC_IP=10.0.0.5 docker compose up openpxe
```
### Multi-arch build + push
@@ -117,12 +117,12 @@ 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
docker buildx create --name openpxe-multi --driver docker-container --use
# Build + push both linux/amd64 and linux/arm64 under one tag.
docker buildx build --builder pxeforge-multi \
docker buildx build --builder openpxe-multi \
--platform linux/amd64,linux/arm64 \
-t ghcr.io/YOUR-ORG/pxeforge:0.1.0 \
-t ghcr.io/YOUR-ORG/openpxe:0.1.0 \
--push \
-f deploy/docker/Dockerfile .
```
@@ -153,31 +153,31 @@ 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
-v openpxe-data:/var/lib/openpxe/isos \
-e OPENPXE_PUBLIC_IP=10.0.0.5 \
openpxe:0.1.0 seed --from /seed
# Dry run first to see what would be imported:
docker run --rm -v /my/iso-library:/seed:ro pxeforge:0.1.0 seed --from /seed --dry-run
docker run --rm -v /my/iso-library:/seed:ro openpxe: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 |
| `OPENPXE_HTTP_PORT` | `80` | Web UI + boot script HTTP port |
| `OPENPXE_TFTP_PORT` | `69` | TFTP port |
| `OPENPXE_DHCP_PORT` | `67` | DHCP server-side port |
| `OPENPXE_DHCP_MODE` | `proxy` | `proxy` or `disabled` |
| `OPENPXE_PUBLIC_IP` | auto-detect | Advertised IP for clients. Startup **fails** if unset and auto-detect returns loopback. |
| `OPENPXE_ISO_DIR` | `/var/lib/openpxe/isos` | Where uploaded ISOs live |
| `OPENPXE_WORK_DIR` | `/var/lib/openpxe/work` | Scratch + runtime settings |
| `OPENPXE_LOG` | `info,openpxe=debug` | `tracing` filter |
## What the boot menu looks like on a real client
```
PXEForge - network boot menu
OpenPXE - network boot menu
------------------------- Default -------------------------
Boot from Local HDD
@@ -188,14 +188,14 @@ docker run --rm -v /my/iso-library:/seed:ro pxeforge:0.1.0 seed --from /seed --d
Tools > Utilities / Shell /
NIC Info / Reboot /
Exit and continue BIOS
---------------------- Gated Deployment ------------------
Gated Deployment (join queue)
---------------------- Queued Deployment ------------------
Queued Deployment (join queue)
```
Linux/Windows submenus show file sizes iVentoy-style:
```
PXEForge - Linux Installers
OpenPXE - Linux Installers
[ 4376 MB] CentOS-7-x86_64-DVD-1810
[ 2002 MB] Fedora-Workstation-Live-x86_64-38-1.6
@@ -210,8 +210,8 @@ ISOs you upload via drag-and-drop in the web UI plus toggles in Settings.
```bash
oc apply -f deploy/openshift/
oc -n pxeforge get all
oc -n pxeforge get route pxeforge -o jsonpath='{.spec.host}'
oc -n openpxe get all
oc -n openpxe get route openpxe -o jsonpath='{.spec.host}'
```
### Why a custom SCC?
@@ -219,7 +219,7 @@ oc -n pxeforge get route pxeforge -o jsonpath='{.spec.host}'
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,
`openpxe-scc` grants exactly those two and nothing else. No raw sockets,
no privileged mode — proxy-mode DHCP sidesteps the usual requirements.
### What's on host ports
@@ -239,7 +239,7 @@ the node's host IP directly for UDP.
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
2. On upload, OpenPXE 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`.
@@ -271,22 +271,22 @@ operational constraints inherited from the design:
- Hardware with NICs/storage controllers missing from WinPE's bundled
drivers will need a driver-pack injection step (not yet implemented).
## Gated Deployment
## Queued Deployment
The "horse race gate" flow, end to end:
The "horse race" launch flow, end to end:
1. A client boots and picks **Gated Deployment** in the PXE menu (or falls
1. A client boots and picks **Queued 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
2. The client joins the queue, gets a numbered queue 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
3. In the web UI's **Queued 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
The server broadcasts the assignment to every queued client via a
`tokio::sync::Notify`; each client's next poll returns the boot script
for the chosen image.
5. Every client chains the same image at effectively the same moment — the
gate opens and the horses run together.
queue releases and the horses run together.
No user-facing iPXE anywhere in this flow. The client only ever runs
scripts we generate; the operator only interacts with the web UI.
+2 -2
View File
@@ -1,10 +1,10 @@
[package]
name = "pxeforge-core"
name = "openpxe-core"
version.workspace = true
edition.workspace = true
license.workspace = true
authors.workspace = true
description = "Shared types, config, and arch detection for PXEForge"
description = "Shared types, config, and arch detection for OpenPXE"
[lints]
workspace = true
+16 -16
View File
@@ -54,7 +54,7 @@ pub enum DhcpMode {
#[default]
Proxy,
/// Disabled — rely on an external DHCP server that has been manually
/// configured with `next-server` / `filename`. PXEForge only serves TFTP
/// configured with `next-server` / `filename`. OpenPXE only serves TFTP
/// + HTTP in this mode. Useful for home routers that can be pre-set.
Disabled,
}
@@ -72,7 +72,7 @@ pub struct Paths {
pub wimboot_path: Option<PathBuf>,
/// 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.
/// `/var/lib/openpxe/smb` in the container image.
pub smb_dir: PathBuf,
}
@@ -104,11 +104,11 @@ impl Default for NetworkConfig {
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"),
iso_dir: PathBuf::from("/var/lib/openpxe/isos"),
work_dir: PathBuf::from("/var/lib/openpxe/work"),
ipxe_dir: PathBuf::from("/usr/share/openpxe/ipxe"),
wimboot_path: None,
smb_dir: PathBuf::from("/var/lib/pxeforge/smb"),
smb_dir: PathBuf::from("/var/lib/openpxe/smb"),
}
}
}
@@ -124,38 +124,38 @@ impl Config {
}
/// Apply environment variable overrides. Env var names follow the pattern
/// `PXEFORGE_<SECTION>_<FIELD>`, uppercase. Unknown vars are ignored.
/// `OPENPXE_<SECTION>_<FIELD>`, 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(v) = std::env::var("OPENPXE_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(v) = std::env::var("OPENPXE_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(v) = std::env::var("OPENPXE_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(v) = std::env::var("OPENPXE_PUBLIC_IP") {
if let Ok(ip) = v.parse() { self.server.public_ip = Some(ip); }
}
if let Ok(v) = std::env::var("PXEFORGE_DHCP_MODE") {
if let Ok(v) = std::env::var("OPENPXE_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") {
if let Ok(v) = std::env::var("OPENPXE_ISO_DIR") {
self.paths.iso_dir = PathBuf::from(v);
}
if let Ok(v) = std::env::var("PXEFORGE_WORK_DIR") {
if let Ok(v) = std::env::var("OPENPXE_WORK_DIR") {
self.paths.work_dir = PathBuf::from(v);
}
if let Ok(v) = std::env::var("PXEFORGE_IPXE_DIR") {
if let Ok(v) = std::env::var("OPENPXE_IPXE_DIR") {
self.paths.ipxe_dir = PathBuf::from(v);
}
if let Ok(v) = std::env::var("PXEFORGE_SMB_DIR") {
if let Ok(v) = std::env::var("OPENPXE_SMB_DIR") {
self.paths.smb_dir = PathBuf::from(v);
}
}
+4 -4
View File
@@ -73,7 +73,7 @@ impl HostBindings {
}
Err(e) => {
tracing::warn!(
target: "pxeforge::hosts",
target: "openpxe::hosts",
"hosts.json present but unreadable ({e}); starting empty"
);
Inner::default()
@@ -149,7 +149,7 @@ impl HostBindings {
let body = match serde_json::to_vec_pretty(&items) {
Ok(b) => b,
Err(e) => {
tracing::warn!(target: "pxeforge::hosts", "serialize hosts.json: {e}");
tracing::warn!(target: "openpxe::hosts", "serialize hosts.json: {e}");
return;
}
};
@@ -158,11 +158,11 @@ impl HostBindings {
let _ = std::fs::create_dir_all(parent);
}
if let Err(e) = std::fs::write(&tmp, body) {
tracing::warn!(target: "pxeforge::hosts", "write hosts.json tmp: {e}");
tracing::warn!(target: "openpxe::hosts", "write hosts.json tmp: {e}");
return;
}
if let Err(e) = std::fs::rename(&tmp, self.path.as_path()) {
tracing::warn!(target: "pxeforge::hosts", "rename hosts.json: {e}");
tracing::warn!(target: "openpxe::hosts", "rename hosts.json: {e}");
}
}
}
+4 -4
View File
@@ -1,12 +1,12 @@
//! PXEForge shared core: config, arch detection, client state registry,
//! runtime settings, and the Gated Deployment queue.
//! OpenPXE shared core: config, arch detection, client state registry,
//! runtime settings, and the Queued Deployment queue.
#![forbid(unsafe_code)]
pub mod arch;
pub mod client;
pub mod config;
pub mod error;
pub mod gate;
pub mod queue;
pub mod host_bindings;
pub mod log_bus;
pub mod metrics;
@@ -16,7 +16,7 @@ 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 queue::{Gate, DeploymentQueue};
pub use host_bindings::{normalize_mac, HostBinding, HostBindings};
pub use log_bus::{LogBus, LogBusLayer, LogLine};
pub use metrics::{HttpRoute, Metrics};
+1 -1
View File
@@ -38,7 +38,7 @@ 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
// 2026-04-29T12:34:56Z [info] openpxe::http: HTTP listening on 0.0.0.0:80
let ts = self
.timestamp
.format(&time::format_description::well_known::Rfc3339)
+51 -51
View File
@@ -1,21 +1,21 @@
//! Tiny lock-free Prometheus-compatible metrics.
//!
//! We don't pull in `prometheus` or `metrics-rs` for this — they bring
//! their own runtime, registry, and complexity. PXEForge has a fixed,
//! their own runtime, registry, and complexity. OpenPXE has a fixed,
//! tiny set of counters/gauges and the exposition format is plain text.
//! A handful of `AtomicU64`s and a `Display` impl gets us everything
//! Prometheus / Grafana / VictoriaMetrics needs to scrape:
//!
//! pxeforge_dhcp_replies_total counter (per arch label)
//! pxeforge_tftp_transfers_total counter (per status label)
//! pxeforge_tftp_bytes_total counter
//! pxeforge_http_requests_total counter (per route label)
//! pxeforge_iso_count gauge
//! pxeforge_client_count gauge
//! pxeforge_gate_count gauge
//! pxeforge_gate_imaging gauge
//! pxeforge_uptime_seconds gauge
//! pxeforge_build_info{version} gauge (always 1)
//! openpxe_dhcp_replies_total counter (per arch label)
//! openpxe_tftp_transfers_total counter (per status label)
//! openpxe_tftp_bytes_total counter
//! openpxe_http_requests_total counter (per route label)
//! openpxe_iso_count gauge
//! openpxe_client_count gauge
//! openpxe_queue_count gauge
//! openpxe_queue_imaging gauge
//! openpxe_uptime_seconds gauge
//! openpxe_build_info{version} gauge (always 1)
//!
//! Cheap to clone — internal state is a couple of arcs. Counters use
//! `Relaxed` ordering: we don't synchronise across counters, just need
@@ -47,8 +47,8 @@ struct Inner {
// Gauges (set explicitly; not cumulative)
iso_count: AtomicU64,
client_count: AtomicU64,
gate_count: AtomicU64,
gate_imaging: AtomicU64,
queue_count: AtomicU64,
queue_imaging: AtomicU64,
nfs_mounts_active: AtomicU64,
}
@@ -113,9 +113,9 @@ impl Metrics {
self.inner.client_count.store(n, Ordering::Relaxed);
}
pub fn set_gate_counts(&self, total: u64, imaging: u64) {
self.inner.gate_count.store(total, Ordering::Relaxed);
self.inner.gate_imaging.store(imaging, Ordering::Relaxed);
pub fn set_queue_counts(&self, total: u64, imaging: u64) {
self.inner.queue_count.store(total, Ordering::Relaxed);
self.inner.queue_imaging.store(imaging, Ordering::Relaxed);
}
pub fn set_nfs_active(&self, n: u64) {
@@ -151,58 +151,58 @@ impl Metrics {
};
// Counters with one HELP/TYPE per metric name and per-label rows.
let _ = writeln!(out, "# HELP pxeforge_dhcp_replies_total Number of proxyDHCP replies sent, by client architecture.");
let _ = writeln!(out, "# TYPE pxeforge_dhcp_replies_total counter");
let _ = writeln!(out, "# HELP openpxe_dhcp_replies_total Number of proxyDHCP replies sent, by client architecture.");
let _ = writeln!(out, "# TYPE openpxe_dhcp_replies_total counter");
let _ = writeln!(
out,
"pxeforge_dhcp_replies_total{{arch=\"bios\"}} {}",
"openpxe_dhcp_replies_total{{arch=\"bios\"}} {}",
i.dhcp_replies_legacy.load(Ordering::Relaxed)
);
let _ = writeln!(
out,
"pxeforge_dhcp_replies_total{{arch=\"uefi\"}} {}",
"openpxe_dhcp_replies_total{{arch=\"uefi\"}} {}",
i.dhcp_replies_uefi.load(Ordering::Relaxed)
);
let _ = writeln!(
out,
"pxeforge_dhcp_replies_total{{arch=\"arm64\"}} {}",
"openpxe_dhcp_replies_total{{arch=\"arm64\"}} {}",
i.dhcp_replies_arm64.load(Ordering::Relaxed)
);
let _ = writeln!(
out,
"pxeforge_dhcp_replies_total{{arch=\"unknown\"}} {}",
"openpxe_dhcp_replies_total{{arch=\"unknown\"}} {}",
i.dhcp_replies_unknown.load(Ordering::Relaxed)
);
write_counter(
&mut out,
"pxeforge_dhcp_declined_total",
"openpxe_dhcp_declined_total",
"DHCP requests we saw but did not reply to (mac filter, arch unsupported, etc).",
i.dhcp_declined.load(Ordering::Relaxed),
"",
);
let _ = writeln!(out, "# HELP pxeforge_tftp_transfers_total TFTP transfers, by status.");
let _ = writeln!(out, "# TYPE pxeforge_tftp_transfers_total counter");
let _ = writeln!(out, "# HELP openpxe_tftp_transfers_total TFTP transfers, by status.");
let _ = writeln!(out, "# TYPE openpxe_tftp_transfers_total counter");
let _ = writeln!(
out,
"pxeforge_tftp_transfers_total{{status=\"ok\"}} {}",
"openpxe_tftp_transfers_total{{status=\"ok\"}} {}",
i.tftp_transfers_ok.load(Ordering::Relaxed)
);
let _ = writeln!(
out,
"pxeforge_tftp_transfers_total{{status=\"err\"}} {}",
"openpxe_tftp_transfers_total{{status=\"err\"}} {}",
i.tftp_transfers_err.load(Ordering::Relaxed)
);
write_counter(
&mut out,
"pxeforge_tftp_bytes_total",
"openpxe_tftp_bytes_total",
"Total bytes successfully delivered over TFTP.",
i.tftp_bytes.load(Ordering::Relaxed),
"",
);
let _ = writeln!(out, "# HELP pxeforge_http_requests_total HTTP requests served, by route family.");
let _ = writeln!(out, "# TYPE pxeforge_http_requests_total counter");
let _ = writeln!(out, "# HELP openpxe_http_requests_total HTTP requests served, by route family.");
let _ = writeln!(out, "# TYPE openpxe_http_requests_total counter");
for (label, counter) in [
("boot_script", &i.http_boot_script),
("iso_range", &i.http_iso_range),
@@ -212,22 +212,22 @@ impl Metrics {
] {
let _ = writeln!(
out,
"pxeforge_http_requests_total{{route=\"{label}\"}} {}",
"openpxe_http_requests_total{{route=\"{label}\"}} {}",
counter.load(Ordering::Relaxed)
);
}
// Gauges.
write_gauge(&mut out, "pxeforge_iso_count", "ISOs currently registered (local + NFS).", i.iso_count.load(Ordering::Relaxed), "");
write_gauge(&mut out, "pxeforge_client_count", "PXE clients seen this process lifetime.", i.client_count.load(Ordering::Relaxed), "");
write_gauge(&mut out, "pxeforge_gate_count", "Clients currently waiting at the deployment gate.", i.gate_count.load(Ordering::Relaxed), "");
write_gauge(&mut out, "pxeforge_gate_imaging", "Clients currently imaging (gate + assigned target).", i.gate_imaging.load(Ordering::Relaxed), "");
write_gauge(&mut out, "pxeforge_nfs_mounts_active", "NFS shares currently mounted.", i.nfs_mounts_active.load(Ordering::Relaxed), "");
write_gauge(&mut out, "pxeforge_uptime_seconds", "Seconds since this PXEForge instance started.", uptime_secs, "");
write_gauge(&mut out, "openpxe_iso_count", "ISOs currently registered (local + NFS).", i.iso_count.load(Ordering::Relaxed), "");
write_gauge(&mut out, "openpxe_client_count", "PXE clients seen this process lifetime.", i.client_count.load(Ordering::Relaxed), "");
write_gauge(&mut out, "openpxe_queue_count", "Clients currently waiting at the deployment queue.", i.queue_count.load(Ordering::Relaxed), "");
write_gauge(&mut out, "openpxe_queue_imaging", "Clients currently imaging (queue + assigned target).", i.queue_imaging.load(Ordering::Relaxed), "");
write_gauge(&mut out, "openpxe_nfs_mounts_active", "NFS shares currently mounted.", i.nfs_mounts_active.load(Ordering::Relaxed), "");
write_gauge(&mut out, "openpxe_uptime_seconds", "Seconds since this OpenPXE instance started.", uptime_secs, "");
let _ = writeln!(out, "# HELP pxeforge_build_info Build metadata. Always 1; the version is in the label.");
let _ = writeln!(out, "# TYPE pxeforge_build_info gauge");
let _ = writeln!(out, "pxeforge_build_info{{version=\"{version}\"}} 1");
let _ = writeln!(out, "# HELP openpxe_build_info Build metadata. Always 1; the version is in the label.");
let _ = writeln!(out, "# TYPE openpxe_build_info gauge");
let _ = writeln!(out, "openpxe_build_info{{version=\"{version}\"}} 1");
out
}
@@ -259,16 +259,16 @@ mod tests {
m.record_http(HttpRoute::Api);
m.set_iso_count(3);
let out = m.render("0.2.0", 42);
assert_eq!(out.matches("# TYPE pxeforge_dhcp_replies_total counter").count(), 1);
assert_eq!(out.matches("# TYPE pxeforge_iso_count gauge").count(), 1);
assert!(out.contains("pxeforge_dhcp_replies_total{arch=\"uefi\"} 1"));
assert!(out.contains("pxeforge_dhcp_replies_total{arch=\"bios\"} 1"));
assert!(out.contains("pxeforge_tftp_transfers_total{status=\"ok\"} 1"));
assert!(out.contains("pxeforge_tftp_bytes_total 1024"));
assert!(out.contains("pxeforge_http_requests_total{route=\"api\"} 1"));
assert!(out.contains("pxeforge_iso_count 3"));
assert!(out.contains("pxeforge_uptime_seconds 42"));
assert!(out.contains("pxeforge_build_info{version=\"0.2.0\"} 1"));
assert_eq!(out.matches("# TYPE openpxe_dhcp_replies_total counter").count(), 1);
assert_eq!(out.matches("# TYPE openpxe_iso_count gauge").count(), 1);
assert!(out.contains("openpxe_dhcp_replies_total{arch=\"uefi\"} 1"));
assert!(out.contains("openpxe_dhcp_replies_total{arch=\"bios\"} 1"));
assert!(out.contains("openpxe_tftp_transfers_total{status=\"ok\"} 1"));
assert!(out.contains("openpxe_tftp_bytes_total 1024"));
assert!(out.contains("openpxe_http_requests_total{route=\"api\"} 1"));
assert!(out.contains("openpxe_iso_count 3"));
assert!(out.contains("openpxe_uptime_seconds 42"));
assert!(out.contains("openpxe_build_info{version=\"0.2.0\"} 1"));
}
#[test]
@@ -278,6 +278,6 @@ mod tests {
a.record_dhcp_reply("bios");
b.record_dhcp_reply("bios");
let out = a.render("test", 0);
assert!(out.contains("pxeforge_dhcp_replies_total{arch=\"bios\"} 2"));
assert!(out.contains("openpxe_dhcp_replies_total{arch=\"bios\"} 2"));
}
}
@@ -1,14 +1,14 @@
//! Gated Deployment queue.
//! Queued 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/<id>`; the server holds the request open
//! When a client selects "Queued Deployment" at the PXE menu, iPXE POSTs to
//! `/api/queue/join` and receives a gate position. It then enters a poll
//! loop hitting `/api/queue/poll/<id>`; 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
//! `POST /api/queue/assign { iso_id, entry_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.
@@ -40,7 +40,7 @@ pub struct Gate {
}
#[derive(Debug)]
struct GateInner {
struct QueueEntryInner {
id: String,
position: u32,
mac: String,
@@ -54,7 +54,7 @@ struct GateInner {
notify: Arc<Notify>,
}
impl GateInner {
impl QueueEntryInner {
fn snapshot(&self) -> Gate {
Gate {
id: self.id.clone(),
@@ -70,11 +70,11 @@ impl GateInner {
}
#[derive(Debug, Default)]
pub struct GateQueue {
inner: RwLock<HashMap<String, GateInner>>,
pub struct DeploymentQueue {
inner: RwLock<HashMap<String, QueueEntryInner>>,
}
impl GateQueue {
impl DeploymentQueue {
#[must_use]
pub fn new() -> Arc<Self> {
Arc::new(Self::default())
@@ -97,7 +97,7 @@ impl GateQueue {
// 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 {
let inner = QueueEntryInner {
id: id.clone(),
position: next_pos,
mac: mac.to_string(),
@@ -115,16 +115,16 @@ impl GateQueue {
/// Look up the `Notify` primitive for a given gate id, for long-polling.
#[must_use]
pub fn notifier(&self, gate_id: &str) -> Option<Arc<Notify>> {
self.inner.read().get(gate_id).map(|g| g.notify.clone())
pub fn notifier(&self, entry_id: &str) -> Option<Arc<Notify>> {
self.inner.read().get(entry_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<Gate> {
pub fn touch(&self, entry_id: &str) -> Option<Gate> {
let mut guard = self.inner.write();
let g = guard.get_mut(gate_id)?;
let g = guard.get_mut(entry_id)?;
g.last_poll_at = OffsetDateTime::now_utc();
Some(g.snapshot())
}
@@ -132,10 +132,10 @@ impl GateQueue {
/// 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 {
pub fn assign(&self, entry_ids: &[String], target: &str) -> usize {
let mut guard = self.inner.write();
let mut updated = 0;
for id in gate_ids {
for id in entry_ids {
if let Some(g) = guard.get_mut(id) {
g.assigned_target = Some(target.to_string());
g.notify.notify_waiters();
@@ -147,9 +147,9 @@ impl GateQueue {
/// 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<Gate> {
pub fn release(&self, entry_id: &str) -> Option<Gate> {
let mut guard = self.inner.write();
let g = guard.remove(gate_id)?;
let g = guard.remove(entry_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).
@@ -164,7 +164,7 @@ impl GateQueue {
#[must_use]
pub fn list(&self) -> Vec<Gate> {
let guard = self.inner.read();
let mut v: Vec<_> = guard.values().map(GateInner::snapshot).collect();
let mut v: Vec<_> = guard.values().map(QueueEntryInner::snapshot).collect();
v.sort_by_key(|g| g.position);
v
}
@@ -186,7 +186,7 @@ mod tests {
#[test]
fn join_assigns_sequential_positions() {
let q = GateQueue::new();
let q = DeploymentQueue::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);
@@ -197,7 +197,7 @@ mod tests {
#[test]
fn rejoining_same_mac_is_idempotent() {
let q = GateQueue::new();
let q = DeploymentQueue::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);
@@ -207,7 +207,7 @@ mod tests {
#[test]
fn assign_broadcasts_target() {
let q = GateQueue::new();
let q = DeploymentQueue::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");
@@ -219,7 +219,7 @@ mod tests {
#[test]
fn release_renumbers() {
let q = GateQueue::new();
let q = DeploymentQueue::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);
@@ -234,7 +234,7 @@ mod tests {
#[tokio::test]
async fn assign_wakes_waiter() {
let q = GateQueue::new();
let q = DeploymentQueue::new();
let g = q.join("aa:00:00:00:00:01", None, None);
let notify = q.notifier(&g.id).unwrap();
+12 -8
View File
@@ -47,13 +47,13 @@ pub struct Settings {
/// `timeout_action = LocalHdd`).
pub default_local_hdd: bool,
/// When a client hits the Gated Deployment item, how long (seconds) to
/// When a client hits the Queued 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
/// informational today — OpenPXE 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,
@@ -66,16 +66,20 @@ pub enum TimeoutAction {
Stay,
/// Chain the "Boot from Local HDD" entry.
LocalHdd,
/// Put the client into the gate queue, waiting for operator assignment.
/// Put the client into the deployment queue, waiting for operator
/// assignment. The serde alias keeps v0.2.0 settings.json files
/// readable after the v0.3.0 rename — old `"gated_deployment"`
/// values deserialize transparently.
#[default]
GatedDeployment,
#[serde(alias = "gated_deployment")]
QueuedDeployment,
}
impl Default for Settings {
fn default() -> Self {
Self {
boot_menu_timeout_secs: 600,
timeout_action: TimeoutAction::GatedDeployment,
timeout_action: TimeoutAction::QueuedDeployment,
windows_enabled: false,
smb_host_override: String::new(),
extra_kernel_args: String::new(),
@@ -103,7 +107,7 @@ impl SettingsStore {
Ok(s) => s,
Err(e) => {
tracing::warn!(
target: "pxeforge::settings",
target: "openpxe::settings",
"settings.json present but unreadable ({e}); falling back to defaults"
);
Settings::default()
@@ -130,7 +134,7 @@ impl SettingsStore {
}
let snap = self.snapshot();
if let Err(e) = self.persist(&snap) {
tracing::warn!(target: "pxeforge::settings", "failed to persist settings: {e}");
tracing::warn!(target: "openpxe::settings", "failed to persist settings: {e}");
}
}
@@ -157,7 +161,7 @@ mod tests {
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_eq!(s.timeout_action, TimeoutAction::QueuedDeployment);
assert!(!s.windows_enabled);
}
+3 -3
View File
@@ -1,16 +1,16 @@
[package]
name = "pxeforge-dhcp-proxy"
name = "openpxe-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"
description = "DHCP proxy (RFC 4578) for OpenPXE — serves boot info, does not lease IPs"
[lints]
workspace = true
[dependencies]
pxeforge-core.workspace = true
openpxe-core.workspace = true
tokio.workspace = true
socket2.workspace = true
dhcproto.workspace = true
+1 -1
View File
@@ -9,7 +9,7 @@
//! 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 openpxe_core::{ClientArch, FirmwareClass};
use std::net::Ipv4Addr;
/// Where the reply directs the client next.
+8 -8
View File
@@ -4,7 +4,7 @@
use crate::reply::{build_reply, decide, BootDirective, ReplyContext};
use dhcproto::v4::{DhcpOption, Message, OptionCode};
use dhcproto::{Decodable, Decoder, Encodable, Encoder};
use pxeforge_core::{
use openpxe_core::{
ClientArch, ClientEvent, ClientRegistry, FirmwareClass,
};
use socket2::{Domain, Protocol, Socket, Type};
@@ -19,7 +19,7 @@ pub struct DhcpProxyServer {
our_ip: Ipv4Addr,
public_base_url: String,
clients: Arc<ClientRegistry>,
metrics: pxeforge_core::Metrics,
metrics: openpxe_core::Metrics,
}
impl DhcpProxyServer {
@@ -30,7 +30,7 @@ impl DhcpProxyServer {
our_ip: Ipv4Addr,
public_base_url: String,
clients: Arc<ClientRegistry>,
metrics: pxeforge_core::Metrics,
metrics: openpxe_core::Metrics,
) -> Self {
Self {
bind,
@@ -47,7 +47,7 @@ impl DhcpProxyServer {
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",
target: "openpxe::dhcp",
"DHCP proxy listening on {}:{} and :{}",
self.bind, self.dhcp_port, self.pxe_port
);
@@ -67,12 +67,12 @@ impl DhcpProxyServer {
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}");
tracing::warn!(target: "openpxe::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}");
tracing::warn!(target: "openpxe::dhcp", port=label, "handle error: {e}");
}
}
}
@@ -128,7 +128,7 @@ impl DhcpProxyServer {
if matches!(directive, BootDirective::Ignore) {
self.metrics.record_dhcp_decline();
tracing::debug!(
target: "pxeforge::dhcp",
target: "openpxe::dhcp",
mac=%mac, arch=?arch, "ignoring — no bootfile for arch"
);
return Ok(());
@@ -142,7 +142,7 @@ impl DhcpProxyServer {
let dest = reply_destination(&request, from);
sock.send_to(&out, dest).await?;
tracing::info!(
target: "pxeforge::dhcp",
target: "openpxe::dhcp",
mac=%mac, arch=arch.as_str(), class=?class, dest=%dest, directive=?directive,
"PXE reply sent"
);
+5 -5
View File
@@ -1,5 +1,5 @@
[package]
name = "pxeforge-http-api"
name = "openpxe-http-api"
version.workspace = true
edition.workspace = true
license.workspace = true
@@ -10,10 +10,10 @@ description = "HTTP server: ISO uploads, iPXE script generation, ISO streaming"
workspace = true
[dependencies]
pxeforge-core.workspace = true
pxeforge-iso-store.workspace = true
pxeforge-ipxe-assets.workspace = true
pxeforge-webui.workspace = true
openpxe-core.workspace = true
openpxe-iso-store.workspace = true
openpxe-ipxe-assets.workspace = true
openpxe-webui.workspace = true
tokio.workspace = true
tokio-util.workspace = true
tokio-stream.workspace = true
+57 -57
View File
@@ -4,7 +4,7 @@
//!
//! | Group | Purpose |
//! |------------------|-------------------------------------------------------|
//! | `/` | Web UI (served from `pxeforge-webui`) |
//! | `/` | Web UI (served from `openpxe-webui`) |
//! | `/boot.ipxe` | Top-level iPXE menu |
//! | `/boot/_*.ipxe` | Submenu scripts (hierarchy: linux, windows, tools, …) |
//! | `/boot/<id>.ipxe`| Per-entry boot script |
@@ -14,7 +14,7 @@
//! | `/api/*` | JSON/HTML API for the web UI |
use crate::ipxe_script::{
render_entry, render_family_menu, render_gate_entry, render_local_hdd,
render_entry, render_family_menu, render_queue_entry, render_local_hdd,
render_menu, render_nic_info, render_shell, render_tools_menu, render_util,
};
use crate::iso_fs;
@@ -29,9 +29,9 @@ use axum::{
routing::{delete, get, post},
Json, Router,
};
use pxeforge_core::{ClientEvent, Settings};
use pxeforge_ipxe_assets::asset_bytes;
use pxeforge_iso_store::{IsoMeta, NfsAddRequest};
use openpxe_core::{ClientEvent, Settings};
use openpxe_ipxe_assets::asset_bytes;
use openpxe_iso_store::{IsoMeta, NfsAddRequest};
use serde::Deserialize;
use serde_json::json;
use std::time::Duration;
@@ -45,7 +45,7 @@ pub fn build_router(state: AppState) -> Router {
.route("/assets/app.js", get(ui_js))
.route("/assets/app.css", get(ui_css))
.route("/assets/logo.svg", get(ui_logo))
.route("/assets/anvil-forge.svg", get(ui_anvil_forge))
.route("/assets/loader.svg", get(ui_loader))
// iPXE script endpoints.
.route("/boot.ipxe", get(boot_top_menu))
.route("/boot/:filename", get(boot_sub))
@@ -64,11 +64,11 @@ pub fn build_router(state: AppState) -> Router {
.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))
.route("/api/queue", get(api_list_queue))
.route("/api/queue/join", get(api_queue_join))
.route("/api/queue/poll/:entry_id", get(api_queue_poll))
.route("/api/queue/assign", post(api_queue_assign))
.route("/api/queue/:entry_id", delete(api_queue_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))
@@ -98,7 +98,7 @@ pub fn build_router(state: AppState) -> Router {
// ─── UI ────────────────────────────────────────────────────────────────────
async fn index(State(state): State<AppState>) -> Response {
let html = pxeforge_webui::index_html(&state.public_base_url);
let html = openpxe_webui::index_html(&state.public_base_url);
([(header::CONTENT_TYPE, HeaderValue::from_static("text/html; charset=utf-8"))], html)
.into_response()
}
@@ -106,28 +106,28 @@ async fn index(State(state): State<AppState>) -> Response {
async fn ui_js() -> Response {
(
[(header::CONTENT_TYPE, HeaderValue::from_static("application/javascript"))],
pxeforge_webui::app_js(),
openpxe_webui::app_js(),
).into_response()
}
async fn ui_css() -> Response {
(
[(header::CONTENT_TYPE, HeaderValue::from_static("text/css"))],
pxeforge_webui::app_css(),
openpxe_webui::app_css(),
).into_response()
}
async fn ui_logo() -> Response {
(
[(header::CONTENT_TYPE, HeaderValue::from_static("image/svg+xml"))],
pxeforge_webui::logo_svg(),
openpxe_webui::logo_svg(),
).into_response()
}
async fn ui_anvil_forge() -> Response {
async fn ui_loader() -> Response {
(
[(header::CONTENT_TYPE, HeaderValue::from_static("image/svg+xml"))],
pxeforge_webui::anvil_forge_svg(),
openpxe_webui::loader_svg(),
).into_response()
}
@@ -146,7 +146,7 @@ async fn boot_top_menu(
State(state): State<AppState>,
Query(p): Query<BootMenuParams>,
) -> Response {
state.metrics.record_http(pxeforge_core::HttpRoute::BootScript);
state.metrics.record_http(openpxe_core::HttpRoute::BootScript);
let isos = state.iso_store.list();
let settings = state.settings.snapshot();
let base = &state.public_base_url;
@@ -158,7 +158,7 @@ async fn boot_top_menu(
if let Some(mac) = p.mac.as_deref() {
if let Some(binding) = state.hosts.lookup(mac) {
tracing::info!(
target: "pxeforge::http",
target: "openpxe::http",
mac = %binding.mac, target = %binding.target,
"host binding applied"
);
@@ -168,7 +168,7 @@ async fn boot_top_menu(
// `/boot/<name>` route, so the URL is identical.
return text_plain(format!(
"#!ipxe\n\
echo PXEForge: per-MAC binding -> {target}\n\
echo OpenPXE: per-MAC binding -> {target}\n\
chain {base}/boot/{target}.ipxe || chain {base}/boot.ipxe\n"
));
}
@@ -203,7 +203,7 @@ async fn boot_sub(
"_util" => render_util(base),
"_shell" => render_shell(base),
"_nic" => render_nic_info(base),
"_gate" => render_gate_entry(base),
"_queue" => render_queue_entry(base),
other => {
for iso in &isos {
for entry in &iso.boot_entries {
@@ -391,7 +391,7 @@ async fn readyz(State(state): State<AppState>) -> Response {
// 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 assets = openpxe_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)");
@@ -420,7 +420,7 @@ async fn api_status(State(state): State<AppState>) -> Json<serde_json::Value> {
let nfs_active = nfs.iter().filter(|m| m.mounted).count();
let isos = state.iso_store.list();
let clients = state.clients.list();
let gates = state.gates.list();
let gates = state.queue.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();
@@ -430,9 +430,9 @@ async fn api_status(State(state): State<AppState>) -> Json<serde_json::Value> {
// gauges fresh without a dedicated scrape-time hook.
state.metrics.set_iso_count(isos.len() as u64);
state.metrics.set_client_count(clients.len() as u64);
state.metrics.set_gate_counts(gates.len() as u64, imaging as u64);
state.metrics.set_queue_counts(gates.len() as u64, imaging as u64);
state.metrics.set_nfs_active(nfs_active as u64);
state.metrics.record_http(pxeforge_core::HttpRoute::Api);
state.metrics.record_http(openpxe_core::HttpRoute::Api);
let now = time::OffsetDateTime::now_utc();
let uptime_secs = (now - state.started_at).whole_seconds().max(0);
Json(json!({
@@ -440,10 +440,10 @@ async fn api_status(State(state): State<AppState>) -> Json<serde_json::Value> {
"public_base_url": state.public_base_url,
"iso_count": isos.len(),
"client_count": clients.len(),
"gate_count": gates.len(),
"queue_count": gates.len(),
"imaging_count": imaging,
"waiting_count": waiting,
"ipxe_assets": pxeforge_ipxe_assets::list_assets(),
"ipxe_assets": openpxe_ipxe_assets::list_assets(),
"settings": state.settings.snapshot(),
"smb": smb,
"nfs_count": nfs.len(),
@@ -468,7 +468,7 @@ async fn api_put_settings(
// 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();
let assets = openpxe_ipxe_assets::list_assets();
if !assets.iter().any(|n| n == "wimboot") {
return (
StatusCode::BAD_REQUEST,
@@ -497,12 +497,12 @@ async fn api_put_settings(
StatusCode::NO_CONTENT.into_response()
}
// ─── Gated Deployment API ─────────────────────────────────────────────────
// ─── Queued Deployment API ─────────────────────────────────────────────────
async fn api_list_gates(State(state): State<AppState>) -> Json<serde_json::Value> {
async fn api_list_queue(State(state): State<AppState>) -> Json<serde_json::Value> {
Json(json!({
"gates": state.gates.list(),
"count": state.gates.list().len(),
"entries": state.queue.list(),
"count": state.queue.list().len(),
}))
}
@@ -514,9 +514,9 @@ struct GateJoinParams {
}
/// Called by iPXE via `chain --replace`. We respond with a tiny iPXE
/// script that hard-loops on `/api/gate/poll/<id>`. iPXE keeps fetching
/// script that hard-loops on `/api/queue/poll/<id>`. iPXE keeps fetching
/// until poll returns an actual boot script.
async fn api_gate_join(
async fn api_queue_join(
State(state): State<AppState>,
Query(p): Query<GateJoinParams>,
headers: HeaderMap,
@@ -528,10 +528,10 @@ async fn api_gate_join(
.and_then(|s| s.split(',').next())
.and_then(|s| s.trim().parse().ok());
let gate = state.gates.join(&mac, ip, None);
let gate = state.queue.join(&mac, ip, None);
state.clients.record(
&mac, ip, None,
ClientEvent::HttpScriptFetch { target: "gate-join".into() },
ClientEvent::HttpScriptFetch { target: "queue-join".into() },
);
let base = &state.public_base_url;
@@ -540,11 +540,11 @@ async fn api_gate_join(
"#!ipxe\n\
echo\n\
echo ==========================================\n\
echo Gated Deployment - Gate Position {}\n\
echo Queued 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",
chain {base}/api/queue/poll/{}\n",
gate.position, gate.id
);
text_plain(script)
@@ -553,11 +553,11 @@ async fn api_gate_join(
/// 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(
async fn api_queue_poll(
State(state): State<AppState>,
AxumPath(gate_id): AxumPath<String>,
AxumPath(entry_id): AxumPath<String>,
) -> Response {
let Some(notify) = state.gates.notifier(&gate_id) else {
let Some(notify) = state.queue.notifier(&entry_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"));
@@ -566,7 +566,7 @@ async fn api_gate_poll(
// 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 snap = state.queue.touch(&entry_id);
let base = &state.public_base_url;
match snap {
// Bind `target` directly so we can't observe an Option::None between
@@ -580,14 +580,14 @@ async fn api_gate_poll(
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,
target: "openpxe::queue",
entry_id=%entry_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"
chain {base}/boot/{target}.ipxe || chain {base}/api/queue/poll/{entry_id}\n"
))
}
Some(g) => {
@@ -596,7 +596,7 @@ async fn api_gate_poll(
text_plain(format!(
"#!ipxe\n\
echo Gate Position {} - still waiting\n\
chain {base}/api/gate/poll/{gate_id}\n",
chain {base}/api/queue/poll/{entry_id}\n",
g.position
))
}
@@ -610,17 +610,17 @@ struct GateAssignBody {
/// `/boot/<id>.ipxe`.
target: String,
/// Gate ids to assign. Empty = assign to all currently queued gates.
gate_ids: Vec<String>,
entry_ids: Vec<String>,
}
async fn api_gate_assign(
async fn api_queue_assign(
State(state): State<AppState>,
Json(body): Json<GateAssignBody>,
) -> Json<serde_json::Value> {
let ids = if body.gate_ids.is_empty() {
state.gates.list().into_iter().map(|g| g.id).collect::<Vec<_>>()
let ids = if body.entry_ids.is_empty() {
state.queue.list().into_iter().map(|g| g.id).collect::<Vec<_>>()
} else {
body.gate_ids
body.entry_ids
};
// Guard: target must exist as a BootEntry id.
let found = state.iso_store.list().into_iter().any(|i| {
@@ -629,15 +629,15 @@ async fn api_gate_assign(
if !found {
return Json(json!({ "ok": false, "error": "unknown target" }));
}
let n = state.gates.assign(&ids, &body.target);
let n = state.queue.assign(&ids, &body.target);
Json(json!({ "ok": true, "assigned": n, "target": body.target }))
}
async fn api_gate_release(
async fn api_queue_release(
State(state): State<AppState>,
AxumPath(gate_id): AxumPath<String>,
AxumPath(entry_id): AxumPath<String>,
) -> StatusCode {
match state.gates.release(&gate_id) {
match state.queue.release(&entry_id) {
Some(_) => StatusCode::NO_CONTENT,
None => StatusCode::NOT_FOUND,
}
@@ -783,11 +783,11 @@ async fn api_metrics(State(state): State<AppState>) -> Response {
state
.metrics
.set_client_count(state.clients.list().len() as u64);
let gates = state.gates.list();
let gates = state.queue.list();
let imaging = gates.iter().filter(|g| g.assigned_target.is_some()).count();
state
.metrics
.set_gate_counts(gates.len() as u64, imaging as u64);
.set_queue_counts(gates.len() as u64, imaging as u64);
state
.metrics
.set_nfs_active(state.nfs.list().iter().filter(|m| m.mounted).count() as u64);
+25 -25
View File
@@ -8,12 +8,12 @@
//! > Boot from Local HDD
//! Installers
//! > Linux Installers -> submenu of Linux ISOs
//! > Windows Installers -> submenu of Windows ISOs (gated by Settings::windows_enabled)
//! > Windows Installers -> submenu of Windows ISOs (controlled by Settings::windows_enabled)
//! Tools
//! > Utilities -> memtest, etc. (embedded assets only)
//! > PXEForge Shell -> drop to iPXE shell with branded prompt
//! > OpenPXE Shell -> drop to iPXE shell with branded prompt
//! > Network Card Info -> ifstat / config / route dump
//! Gated Deployment -> join the gate queue
//! Queued Deployment -> join the deployment queue
//! ```
//!
//! ## iPXE is entirely backend — users do not see or write iPXE
@@ -22,12 +22,12 @@
//! 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 openpxe_core::{Settings, TimeoutAction};
use openpxe_iso_store::{BootEntry, BootKind, IsoMeta};
use openpxe_iso_store::introspect::DistroFamily;
use std::fmt::Write as _;
/// Top-level PXEForge boot menu. Serialized identically for BIOS and UEFI
/// Top-level OpenPXE 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 {
@@ -35,7 +35,7 @@ pub fn render_menu(isos: &[IsoMeta], settings: &Settings, base_url: &str) -> Str
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::GatedDeployment => "gate",
TimeoutAction::QueuedDeployment => "queue",
// Stay -> iPXE's `--timeout 0` is "no timeout". Pick any default
// label; the client waits for keypress. We use the same label as
// LocalHdd to keep the menu's pre-highlight stable.
@@ -43,12 +43,12 @@ pub fn render_menu(isos: &[IsoMeta], settings: &Settings, base_url: &str) -> Str
};
let _ = writeln!(s, "#!ipxe");
let _ = writeln!(s, "# PXEForge top-level menu - auto-generated, do not edit");
let _ = writeln!(s, "# OpenPXE 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, "menu OpenPXE - network boot menu");
let _ = writeln!(s, "item --gap -- ------------------------- Default -------------------------");
let _ = writeln!(s, "item local Boot from Local HDD");
let _ = writeln!(s, "item --gap -- ----------------------- Installers -----------------------");
@@ -66,8 +66,8 @@ pub fn render_menu(isos: &[IsoMeta], settings: &Settings, base_url: &str) -> Str
}
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 -- ---------------------- Queued Deployment ---------------------");
let _ = writeln!(s, "item queue Queued Deployment (join queue)");
let _ = writeln!(s, "item --gap");
let _ = writeln!(s, "item --key x exit Exit iPXE");
@@ -84,7 +84,7 @@ pub fn render_menu(isos: &[IsoMeta], settings: &Settings, base_url: &str) -> Str
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}} queue && chain {base}/boot/_queue.ipxe || goto menu");
let _ = writeln!(s, "iseq ${{target}} exit && exit || goto menu");
let _ = writeln!(s, "goto menu");
s
@@ -101,7 +101,7 @@ pub fn render_family_menu(isos: &[IsoMeta], base_url: &str, is_windows: bool) ->
let _ = writeln!(s, "#!ipxe");
let _ = writeln!(s, "set base-url {base}");
let _ = writeln!(s, ":menu");
let _ = writeln!(s, "menu PXEForge - {title}");
let _ = writeln!(s, "menu OpenPXE - {title}");
let filter: fn(DistroFamily) -> bool =
if is_windows { is_windows_family } else { is_linux_family };
let mut count = 0;
@@ -156,9 +156,9 @@ pub fn render_tools_menu(base_url: &str) -> String {
let _ = writeln!(s, "#!ipxe");
let _ = writeln!(s, "set base-url {base}");
let _ = writeln!(s, ":menu");
let _ = writeln!(s, "menu PXEForge - Tools");
let _ = writeln!(s, "menu OpenPXE - Tools");
let _ = writeln!(s, "item --key u util Utilities (memtest, ...)");
let _ = writeln!(s, "item --key s shell PXEForge Shell");
let _ = writeln!(s, "item --key s shell OpenPXE 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");
@@ -202,7 +202,7 @@ pub fn render_util(base_url: &str) -> String {
let mut s = String::new();
let _ = writeln!(s, "#!ipxe");
let _ = writeln!(s, ":menu");
let _ = writeln!(s, "menu PXEForge - Utilities");
let _ = writeln!(s, "menu OpenPXE - Utilities");
let _ = writeln!(s, "item memtest MemTest86+ (RAM diagnostic)");
let _ = writeln!(s, "item --gap");
let _ = writeln!(s, "item back < Back");
@@ -213,14 +213,14 @@ pub fn render_util(base_url: &str) -> String {
s
}
/// "PXEForge Shell" — iPXE shell, branded.
/// "OpenPXE 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 OpenPXE Shell");
let _ = writeln!(s, "echo 'exit' returns to the main menu");
let _ = writeln!(s, "echo ==========================================");
let _ = writeln!(s, "shell");
@@ -247,20 +247,20 @@ pub fn render_nic_info(base_url: &str) -> String {
s
}
/// Gated Deployment entry point. Joins the queue, then enters a long-poll
/// Queued 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 {
pub fn render_queue_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...");
let _ = writeln!(s, "# Queued Deployment - join the queue and wait for operator");
let _ = writeln!(s, "echo Joining deployment 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
// the queue entry 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}}");
let _ = writeln!(s, "chain --replace {base}/api/queue/join?mac=${{mac}}");
s
}
+1 -1
View File
@@ -1,5 +1,5 @@
//! HTTP server — single axum app that serves:
//! - `/` the web UI (static assets from `pxeforge-webui`)
//! - `/` the web UI (static assets from `openpxe-webui`)
//! - `/api/*` JSON API for the web UI
//! - `/boot.ipxe` the generated top-level iPXE boot menu
//! - `/boot/<entry>.ipxe` per-entry iPXE scripts (one per boot target)
+2 -2
View File
@@ -12,7 +12,7 @@ use axum::{
Json,
};
use futures::stream::{Stream, StreamExt};
use pxeforge_core::LogLine;
use openpxe_core::LogLine;
use serde_json::json;
use std::convert::Infallible;
use std::time::Duration;
@@ -57,7 +57,7 @@ pub async fn clear(State(state): State<AppState>) -> Json<serde_json::Value> {
state.log_bus.clear();
state
.log_bus
.push("info", "pxeforge::terminal", "log buffer cleared by operator");
.push("info", "openpxe::terminal", "log buffer cleared by operator");
Json(json!({ "ok": true }))
}
+3 -3
View File
@@ -1,5 +1,5 @@
use pxeforge_core::{ClientRegistry, GateQueue, HostBindings, LogBus, Metrics, SettingsStore};
use pxeforge_iso_store::{IsoStore, NfsManager, SmbManager};
use openpxe_core::{ClientRegistry, DeploymentQueue, HostBindings, LogBus, Metrics, SettingsStore};
use openpxe_iso_store::{IsoStore, NfsManager, SmbManager};
use std::sync::Arc;
use time::OffsetDateTime;
@@ -8,7 +8,7 @@ pub struct AppState {
pub iso_store: IsoStore,
pub clients: Arc<ClientRegistry>,
pub settings: Arc<SettingsStore>,
pub gates: Arc<GateQueue>,
pub queue: Arc<DeploymentQueue>,
/// Per-MAC iPXE script overrides. When a client matching one of
/// these MACs requests `/boot.ipxe`, we chain straight to the
/// configured target instead of rendering the menu.
+33 -33
View File
@@ -36,7 +36,7 @@ pub async fn run_command(
// 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}"));
state.log_bus.push("info", "openpxe::terminal", format!("> {line}"));
let argv = shell_split(line);
if argv.is_empty() {
@@ -60,9 +60,9 @@ pub async fn run_command(
output.clone()
};
if ok {
state.log_bus.push("info", "pxeforge::terminal", mirror);
state.log_bus.push("info", "openpxe::terminal", mirror);
} else {
state.log_bus.push("warn", "pxeforge::terminal", mirror);
state.log_bus.push("warn", "openpxe::terminal", mirror);
}
(StatusCode::OK, Json(json!({ "output": output, "ok": ok })))
@@ -73,12 +73,12 @@ async fn dispatch(state: &AppState, argv: &[String]) -> Result<String, String> {
let tail = &argv[1..];
match head {
"help" | "?" => Ok(HELP_TEXT.to_string()),
"version" => Ok(format!("pxeforge {}", env!("CARGO_PKG_VERSION"))),
"version" => Ok(format!("openpxe {}", 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,
"queue" => gate_command(state, tail).await,
"nfs" => nfs_command(state, tail).await,
"smb" => smb_command(state, tail).await,
"log" => log_command(state, tail),
@@ -96,18 +96,18 @@ async fn dispatch(state: &AppState, argv: &[String]) -> Result<String, String> {
fn status_text(s: &AppState) -> String {
let isos = s.iso_store.list();
let clients = s.clients.list();
let gates = s.gates.list();
let gates = s.queue.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\
"OpenPXE {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\
queue: {n_entries}\n\
smb: {smb}\n\
nfs mounts: {n_total} configured ({n_active} active)\n",
ver = env!("CARGO_PKG_VERSION"),
@@ -115,10 +115,10 @@ fn status_text(s: &AppState) -> String {
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_local = isos.iter().filter(|i| matches!(i.source, openpxe_iso_store::IsoSource::Local)).count(),
n_nfs = isos.iter().filter(|i| !matches!(i.source, openpxe_iso_store::IsoSource::Local)).count(),
n_clients = clients.len(),
n_gates = gates.len(),
n_entries = gates.len(),
smb = smb.map_or_else(|| "(disabled)".into(), |s| format!("{s:?}")),
n_total = nfs.len(),
n_active = nfs_active,
@@ -138,8 +138,8 @@ fn isos_text(s: &AppState) -> String {
);
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}"),
openpxe_iso_store::IsoSource::Local => "local".to_string(),
openpxe_iso_store::IsoSource::Nfs { mount_id, .. } => format!("nfs:{mount_id}"),
};
let _ = writeln!(
out,
@@ -188,7 +188,7 @@ fn clients_text(s: &AppState) -> String {
async fn gate_command(s: &AppState, args: &[String]) -> Result<String, String> {
match args.first().map(String::as_str) {
None | Some("list") => {
let gs = s.gates.list();
let gs = s.queue.list();
if gs.is_empty() {
return Ok("(no gates)".into());
}
@@ -217,28 +217,28 @@ async fn gate_command(s: &AppState, args: &[String]) -> Result<String, String> {
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);
let ids: Vec<_> = s.queue.list().into_iter().map(|g| g.id).collect();
let n = s.queue.assign(&ids, target);
Ok(format!("assigned {n} gates -> {target}"))
}
Some("assign") => {
let gate_id = args
let entry_id = args
.get(1)
.ok_or_else(|| "usage: gate assign <gate_id> <iso_boot_entry_id>".to_string())?;
.ok_or_else(|| "usage: gate assign <entry_id> <iso_boot_entry_id>".to_string())?;
let target = args
.get(2)
.ok_or_else(|| "usage: gate assign <gate_id> <iso_boot_entry_id>".to_string())?;
let n = s.gates.assign(std::slice::from_ref(gate_id), target);
.ok_or_else(|| "usage: gate assign <entry_id> <iso_boot_entry_id>".to_string())?;
let n = s.queue.assign(std::slice::from_ref(entry_id), target);
if n == 0 {
return Err(format!("no such gate: {gate_id}"));
return Err(format!("no such gate: {entry_id}"));
}
Ok(format!("assigned 1 gate -> {target}"))
}
Some("release") => {
let gate_id = args.get(1).ok_or_else(|| "usage: gate release <gate_id>".to_string())?;
match s.gates.release(gate_id) {
Some(_) => Ok(format!("released {gate_id}")),
None => Err(format!("no such gate: {gate_id}")),
let entry_id = args.get(1).ok_or_else(|| "usage: gate release <entry_id>".to_string())?;
match s.queue.release(entry_id) {
Some(_) => Ok(format!("released {entry_id}")),
None => Err(format!("no such gate: {entry_id}")),
}
}
Some(other) => Err(format!(
@@ -269,8 +269,8 @@ async fn nfs_command(s: &AppState, args: &[String]) -> Result<String, String> {
"{:<24} {:<6} {:<7} {:<6} {}:{}",
truncate(&m.id, 24),
match m.version {
pxeforge_iso_store::NfsVersion::V3 => "v3",
pxeforge_iso_store::NfsVersion::V41 => "v4.1",
openpxe_iso_store::NfsVersion::V3 => "v3",
openpxe_iso_store::NfsVersion::V41 => "v4.1",
},
status,
m.iso_count,
@@ -292,12 +292,12 @@ async fn nfs_command(s: &AppState, args: &[String]) -> Result<String, String> {
.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("v3") => openpxe_iso_store::NfsVersion::V3,
Some("v41") | None => openpxe_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 {
let req = openpxe_iso_store::NfsAddRequest {
server: server.to_string(),
export: export.to_string(),
version,
@@ -453,7 +453,7 @@ pub fn shell_split(input: &str) -> Vec<String> {
}
const HELP_TEXT: &str = "\
PXEForge terminal — available commands:
OpenPXE terminal — available commands:
help show this help
version print server version
@@ -463,9 +463,9 @@ PXEForge terminal — available commands:
isos list registered ISOs
clients list PXE clients seen this session
gate list list gated-deployment queue
gate assign <gate_id> <target> assign one gate to a boot entry
gate assign <entry_id> <target> assign one gate to a boot entry
gate assign-all <target> assign every waiting gate
gate release <gate_id> release one gate
gate release <entry_id> release one gate
nfs list list NFS mounts
nfs mount <s>:<e> [v3|v41] [ro|rw] add and mount an NFS share
+31 -31
View File
@@ -3,7 +3,7 @@
//! 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,
//! ISO. Also drives the Queued 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
@@ -12,9 +12,9 @@
use axum::body::Body;
use axum::http::{header, Request, StatusCode};
use pxeforge_core::{ClientRegistry, GateQueue, HostBindings, LogBus, Metrics, SettingsStore};
use pxeforge_http_api::{build_router, AppState};
use pxeforge_iso_store::{IsoStore, NfsManager};
use openpxe_core::{ClientRegistry, DeploymentQueue, HostBindings, LogBus, Metrics, SettingsStore};
use openpxe_http_api::{build_router, AppState};
use openpxe_iso_store::{IsoStore, NfsManager};
use tempfile::tempdir;
use tower::ServiceExt;
@@ -87,7 +87,7 @@ async fn build_state() -> (AppState, tempfile::TempDir) {
let iso_store = IsoStore::new(dir.path().join("isos"));
iso_store.ensure_dirs().await.unwrap();
let clients = ClientRegistry::new();
let gates = GateQueue::new();
let gates = DeploymentQueue::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());
@@ -97,7 +97,7 @@ async fn build_state() -> (AppState, tempfile::TempDir) {
let state = AppState {
iso_store,
clients,
gates,
queue: gates,
settings,
hosts,
metrics,
@@ -198,7 +198,7 @@ async fn iso_range_request_slices_correctly() {
}
#[tokio::test]
async fn gated_deployment_full_flow() {
async fn queued_deployment_full_flow() {
let (state, _dir) = build_state().await;
let app = build_router(state.clone());
@@ -210,22 +210,22 @@ async fn gated_deployment_full_flow() {
.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 (_, join1) = get(&app, "/api/queue/join?mac=aa:bb:cc:00:00:01").await;
let (_, join2) = get(&app, "/api/queue/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/"))
let gate1_id = s1.lines().find_map(|l| l.strip_prefix("chain http://127.0.0.1/api/queue/poll/"))
.unwrap().to_string();
let gate2_id = s2.lines().find_map(|l| l.strip_prefix("chain http://127.0.0.1/api/gate/poll/"))
let gate2_id = s2.lines().find_map(|l| l.strip_prefix("chain http://127.0.0.1/api/queue/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}");
let uri = format!("/api/queue/poll/{gate1_id}");
get(&app2, &uri).await
});
@@ -233,15 +233,15 @@ async fn gated_deployment_full_flow() {
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;
let body = format!(r#"{{"target":"fake-alpine-linux","entry_ids":["{gate2_id}"]}}"#);
let (s, b) = post_json(&app, "/api/queue/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 = r#"{"target":"fake-alpine-linux","gate_ids":[]}"#;
post_json(&app, "/api/gate/assign", body).await;
let body = r#"{"target":"fake-alpine-linux","entry_ids":[]}"#;
post_json(&app, "/api/queue/assign", body).await;
let (poll_status, poll_body) = poll_future.await.unwrap();
assert_eq!(poll_status, StatusCode::OK);
@@ -251,12 +251,12 @@ async fn gated_deployment_full_flow() {
"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/"),
assert!(poll_s.contains("|| chain http://127.0.0.1/api/queue/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) = post_json(&app, "/api/queue/assign",
r#"{"target":"does-not-exist","entry_ids":[]}"#).await;
let bad_s = String::from_utf8(bad).unwrap();
assert!(bad_s.contains(r#""ok":false"#), "expected rejection: {bad_s}");
}
@@ -329,7 +329,7 @@ async fn ui_assets_served_offline() {
("/assets/app.js", "application/javascript"),
("/assets/app.css", "text/css"),
("/assets/logo.svg", "image/svg+xml"),
("/assets/anvil-forge.svg", "image/svg+xml"),
("/assets/loader.svg", "image/svg+xml"),
] {
let res = app
.clone()
@@ -406,14 +406,14 @@ async fn terminal_help_and_status_round_trip() {
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"));
assert!(v["output"].as_str().unwrap().contains("OpenPXE 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.starts_with("OpenPXE"), "unexpected status output: {out}");
assert!(out.contains("isos:"), "status missing iso line: {out}");
// Unknown command -> ok=false plus help hint.
@@ -477,7 +477,7 @@ async fn windows_iso_renders_clean_wimboot_script_with_no_trust_store_writes() {
.uri("/api/settings")
.header("content-type", "application/json")
.body(Body::from(
r#"{"boot_menu_timeout_secs":600,"timeout_action":"gated_deployment",
r#"{"boot_menu_timeout_secs":600,"timeout_action":"queued_deployment",
"windows_enabled":false,"smb_host_override":"","extra_kernel_args":"",
"default_local_hdd":true,"gate_wait_max_secs":0,"dns_server":""}"#
.to_string(),
@@ -623,19 +623,19 @@ async fn metrics_endpoint_emits_prometheus_format() {
let body = String::from_utf8(body.to_vec()).unwrap();
// Spot-check the must-have metric families.
for name in [
"pxeforge_dhcp_replies_total",
"pxeforge_tftp_transfers_total",
"pxeforge_http_requests_total",
"pxeforge_iso_count",
"pxeforge_uptime_seconds",
"pxeforge_build_info",
"openpxe_dhcp_replies_total",
"openpxe_tftp_transfers_total",
"openpxe_http_requests_total",
"openpxe_iso_count",
"openpxe_uptime_seconds",
"openpxe_build_info",
] {
assert!(body.contains(name), "missing metric {name} in:\n{body}");
}
// Each name appears exactly once as a `# TYPE` declaration.
for name in [
"pxeforge_dhcp_replies_total",
"pxeforge_iso_count",
"openpxe_dhcp_replies_total",
"openpxe_iso_count",
] {
let count = body.matches(&format!("# TYPE {name}")).count();
assert_eq!(count, 1, "{name} TYPE line appears {count} times");
+3 -3
View File
@@ -1,16 +1,16 @@
[package]
name = "pxeforge-ipxe-assets"
name = "openpxe-ipxe-assets"
version.workspace = true
edition.workspace = true
license.workspace = true
authors.workspace = true
description = "Bundled iPXE binaries and default chain scripts for PXEForge"
description = "Bundled iPXE binaries and default chain scripts for OpenPXE"
[lints]
workspace = true
[dependencies]
pxeforge-core.workspace = true
openpxe-core.workspace = true
rust-embed.workspace = true
tracing.workspace = true
thiserror.workspace = true
+4 -4
View File
@@ -1,7 +1,7 @@
//! 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
//! the workspace root. They are embedded into the OpenPXE 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.
@@ -16,7 +16,7 @@
//! - `wimboot` — Windows boot shim (fetched separately for WIM chains)
#![forbid(unsafe_code)]
use pxeforge_core::ClientArch;
use openpxe_core::ClientArch;
use rust_embed::Embed;
#[derive(Embed)]
@@ -66,10 +66,10 @@ pub fn log_availability() {
];
for (arch, name) in needed {
if have.contains(name) {
tracing::info!(target: "pxeforge::ipxe", "bundled iPXE for {}: {}", arch.as_str(), name);
tracing::info!(target: "openpxe::ipxe", "bundled iPXE for {}: {}", arch.as_str(), name);
} else {
tracing::warn!(
target: "pxeforge::ipxe",
target: "openpxe::ipxe",
"MISSING iPXE binary for {}: {} — clients of this arch will not PXE boot",
arch.as_str(), name
);
+3 -3
View File
@@ -1,16 +1,16 @@
[package]
name = "pxeforge-iso-store"
name = "openpxe-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"
description = "ISO upload, storage, introspection, and boot-entry generation for OpenPXE"
[lints]
workspace = true
[dependencies]
pxeforge-core.workspace = true
openpxe-core.workspace = true
tokio = { workspace = true }
tokio-util = { workspace = true }
serde.workspace = true
+1 -1
View File
@@ -49,7 +49,7 @@ pub fn introspect(path: &Path) -> IntrospectionReport {
};
let Ok(mut f) = std::fs::File::open(path) else {
tracing::warn!(target: "pxeforge::iso", "cannot open ISO for introspection: {}", path.display());
tracing::warn!(target: "openpxe::iso", "cannot open ISO for introspection: {}", path.display());
return report;
};
+9 -9
View File
@@ -37,7 +37,7 @@
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 openpxe_core::{Error, Result};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::path::{Path, PathBuf};
@@ -76,7 +76,7 @@ pub struct NfsMount {
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.
/// write can flip this off but OpenPXE itself never writes.
pub read_only: bool,
/// Local mount point under `<work_dir>/nfs/`.
pub local_path: PathBuf,
@@ -168,7 +168,7 @@ impl NfsManager {
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",
target: "openpxe::nfs",
id = %m.id, error = %e,
"could not remount NFS share on startup"
);
@@ -299,7 +299,7 @@ impl NfsManager {
match output {
Ok(out) if out.status.success() => {
tracing::info!(
target: "pxeforge::nfs",
target: "openpxe::nfs",
id = %id, server = %m.server, export = %m.export,
version = ?m.version,
"NFS mount succeeded"
@@ -315,13 +315,13 @@ impl NfsManager {
out.status.code().unwrap_or(-1),
String::from_utf8_lossy(&out.stderr).trim()
);
tracing::warn!(target: "pxeforge::nfs", id = %id, "{err}");
tracing::warn!(target: "openpxe::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}");
tracing::error!(target: "openpxe::nfs", id = %id, "{err}");
self.update_status(id, false, Some(err.clone()), now);
Err(Error::Invalid(err))
}
@@ -442,7 +442,7 @@ impl NfsManager {
let body = match serde_json::to_vec_pretty(&mounts) {
Ok(b) => b,
Err(e) => {
tracing::warn!(target: "pxeforge::nfs", "serialize NFS state: {e}");
tracing::warn!(target: "openpxe::nfs", "serialize NFS state: {e}");
return;
}
};
@@ -450,11 +450,11 @@ impl NfsManager {
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}");
tracing::warn!(target: "openpxe::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}");
tracing::warn!(target: "openpxe::nfs", "rename NFS state: {e}");
}
}
}
+6 -6
View File
@@ -20,7 +20,7 @@
//! - 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).
//! - smbd runs as the same non-root uid as openpxe (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.
@@ -100,7 +100,7 @@ impl SmbManager {
conf,
"\n[{name}]\n\
path = {}\n\
comment = PXEForge Windows install media ({name})\n\
comment = OpenPXE Windows install media ({name})\n\
read only = yes\n\
guest ok = yes\n\
guest only = yes\n\
@@ -152,7 +152,7 @@ impl SmbManager {
*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");
tracing::info!(target: "openpxe::smb", pid, shares=?self.state.lock(), "smbd started");
s
}
Err(e) => {
@@ -248,7 +248,7 @@ pid directory = /tmp
pub fn extract_windows_iso(iso_path: &Path, smb_dir: &Path, slug: &str) -> std::io::Result<PathBuf> {
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");
tracing::debug!(target: "openpxe::smb", slug, "ISO already extracted, skipping");
return Ok(target);
}
std::fs::create_dir_all(&target)?;
@@ -265,7 +265,7 @@ pub fn extract_windows_iso(iso_path: &Path, smb_dir: &Path, slug: &str) -> std::
.output()?;
if out.status.success() { return Ok(target); }
tracing::warn!(
target: "pxeforge::smb",
target: "openpxe::smb",
stderr=%String::from_utf8_lossy(&out.stderr),
"7z extract failed, trying bsdtar"
);
@@ -315,7 +315,7 @@ mod tests {
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");
std::env::set_var("PATH", "/usr/nowhere-openpxe-test");
let dir = tempdir().unwrap();
let m = SmbManager::new(dir.path().into());
let st = m.start();
+1 -1
View File
@@ -4,7 +4,7 @@ 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 openpxe_core::{Error, Result};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use std::collections::HashMap;
+1 -1
View File
@@ -160,7 +160,7 @@ fn render_startnet(host: &str, share: &str) -> String {
// Bootimus v0.1.58 lesson: surface `net use` errors instead of
// tight-looping on a blind retry. We retry but log every miss.
s.push_str("@echo off\r\n");
s.push_str("echo PXEForge WinPE bootstrap\r\n");
s.push_str("echo OpenPXE WinPE bootstrap\r\n");
s.push_str("wpeinit\r\n");
// v0.1.58: explicitly start Workstation before mapping the share —
// `net use` otherwise lazily inits SMB-client and races wpeinit.
@@ -1,5 +1,5 @@
[package]
name = "pxeforge"
name = "openpxe"
version.workspace = true
edition.workspace = true
license.workspace = true
@@ -10,16 +10,16 @@ description = "Container-native PXE boot server — a lightweight Rust clone of
workspace = true
[[bin]]
name = "pxeforge"
name = "openpxe"
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
openpxe-core.workspace = true
openpxe-dhcp-proxy.workspace = true
openpxe-tftp.workspace = true
openpxe-http-api.workspace = true
openpxe-iso-store.workspace = true
openpxe-ipxe-assets.workspace = true
tokio.workspace = true
axum.workspace = true
tracing.workspace = true
@@ -1,27 +1,27 @@
//! PXEForge entry point. Wires the three protocol servers (DHCP proxy,
//! OpenPXE 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, HostBindings, LogBus, LogBusLayer, Metrics,
use openpxe_core::{
ClientRegistry, Config, DhcpMode, DeploymentQueue, HostBindings, LogBus, LogBusLayer, Metrics,
SettingsStore,
};
use pxeforge_dhcp_proxy::DhcpProxyServer;
use pxeforge_http_api::{build_router, AppState};
use pxeforge_iso_store::{IsoStore, NfsManager, SmbManager};
use openpxe_dhcp_proxy::DhcpProxyServer;
use openpxe_http_api::{build_router, AppState};
use openpxe_iso_store::{IsoStore, NfsManager, SmbManager};
use std::sync::Arc;
use pxeforge_tftp::TftpServer;
use openpxe_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)]
#[command(name = "openpxe", 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")]
/// also be overridden with env vars (OPENPXE_*).
#[arg(long, env = "OPENPXE_CONFIG")]
config: Option<PathBuf>,
#[command(subcommand)]
@@ -38,8 +38,8 @@ enum Command {
/// Example:
/// docker run --rm \
/// -v /my/isos:/seed:ro \
/// -v pxeforge-data:/var/lib/pxeforge/isos \
/// pxeforge:0.1.0 seed --from /seed
/// -v openpxe-data:/var/lib/openpxe/isos \
/// openpxe:0.1.0 seed --from /seed
Seed {
/// Source directory containing one or more `.iso` files.
#[arg(long)]
@@ -70,7 +70,7 @@ async fn main() -> anyhow::Result<()> {
return run_command(cmd, config).await;
}
pxeforge_ipxe_assets::log_availability();
openpxe_ipxe_assets::log_availability();
let our_ip = match config.server.public_ip {
Some(ip) => {
@@ -88,7 +88,7 @@ async fn main() -> anyhow::Result<()> {
// message instead of serving a broken deployment.
anyhow::bail!(
"could not detect a non-loopback IPv4 address for this host. \
Set PXEFORGE_PUBLIC_IP=<your-ip> (e.g. `-e PXEFORGE_PUBLIC_IP=10.0.0.5` \
Set OPENPXE_PUBLIC_IP=<your-ip> (e.g. `-e OPENPXE_PUBLIC_IP=10.0.0.5` \
in docker, or the env block in OpenShift Deployment) to advertise \
a specific IP to PXE clients."
);
@@ -100,7 +100,7 @@ async fn main() -> anyhow::Result<()> {
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 gates = DeploymentQueue::new();
let settings = SettingsStore::load_or_default(&config.paths.work_dir);
let hosts = HostBindings::load_or_default(&config.paths.work_dir);
let metrics = Metrics::new();
@@ -120,7 +120,7 @@ async fn main() -> anyhow::Result<()> {
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}");
tracing::warn!(target: "openpxe::nfs", "could not reload NFS mounts: {e}");
}
// Sniff network details for the Network tab. None of these are
@@ -129,7 +129,7 @@ async fn main() -> anyhow::Result<()> {
// own gateway.
let net = detect_network_info(our_ip);
tracing::info!(
target: "pxeforge::net",
target: "openpxe::net",
nic = %net.nic_name, mask = %net.subnet_mask, gateway = %net.gateway,
"network info"
);
@@ -138,7 +138,7 @@ async fn main() -> anyhow::Result<()> {
iso_store: iso_store.clone(),
clients: clients.clone(),
settings: settings.clone(),
gates: gates.clone(),
queue: gates.clone(),
hosts: hosts.clone(),
metrics: metrics.clone(),
smb: Some(smb.clone()),
@@ -155,7 +155,7 @@ async fn main() -> anyhow::Result<()> {
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}");
tracing::info!(target: "openpxe::http", "HTTP listening on {http_addr}");
axum::serve(listener, router).await?;
Ok::<_, anyhow::Error>(())
});
@@ -182,7 +182,7 @@ async fn main() -> anyhow::Result<()> {
tokio::spawn(s.run())
}
DhcpMode::Disabled => {
tracing::info!(target: "pxeforge::dhcp", "DHCP disabled — external DHCP must set next-server + filename");
tracing::info!(target: "openpxe::dhcp", "DHCP disabled — external DHCP must set next-server + filename");
tokio::spawn(async { futures_forever().await })
}
};
@@ -231,7 +231,7 @@ async fn seed_from_dir(src: &std::path::Path, config: &Config, dry_run: bool) ->
let mut handle = match store.begin_upload(&filename).await {
Ok(h) => h,
Err(pxeforge_core::Error::Invalid(e)) => {
Err(openpxe_core::Error::Invalid(e)) => {
eprintln!(" skip: {e}");
skipped += 1;
continue;
@@ -258,7 +258,7 @@ async fn seed_from_dir(src: &std::path::Path, config: &Config, dry_run: bool) ->
/// 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.
/// `OPENPXE_PUBLIC_IP` explicitly.
fn detect_primary_ipv4() -> Option<Ipv4Addr> {
// First try: route to the public internet. `UdpSocket::connect` to a
// well-known external address causes the OS to populate `local_addr`
@@ -301,8 +301,8 @@ fn hostname() -> std::io::Result<String> {
fn init_tracing(bus: Arc<LogBus>) {
use tracing_subscriber::{fmt, prelude::*, EnvFilter};
let filter = EnvFilter::try_from_env("PXEFORGE_LOG")
.unwrap_or_else(|_| EnvFilter::new("info,pxeforge=debug"));
let filter = EnvFilter::try_from_env("OPENPXE_LOG")
.unwrap_or_else(|_| EnvFilter::new("info,openpxe=debug"));
tracing_subscriber::registry()
.with(filter)
.with(fmt::layer().with_target(true))
+3 -3
View File
@@ -1,5 +1,5 @@
[package]
name = "pxeforge-tftp"
name = "openpxe-tftp"
version.workspace = true
edition.workspace = true
license.workspace = true
@@ -10,8 +10,8 @@ description = "TFTP server (RFC 1350/2347/2348/2349/7440) for iPXE chainload"
workspace = true
[dependencies]
pxeforge-core.workspace = true
pxeforge-ipxe-assets.workspace = true
openpxe-core.workspace = true
openpxe-ipxe-assets.workspace = true
tokio.workspace = true
socket2.workspace = true
tracing.workspace = true
+13 -13
View File
@@ -7,12 +7,12 @@
//! `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,
//! We only serve files from `openpxe_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 openpxe_core::{ClientEvent, ClientRegistry};
use openpxe_ipxe_assets::asset_bytes;
use socket2::{Domain, Protocol, Socket, Type};
use std::net::{IpAddr, SocketAddr};
use std::sync::Arc;
@@ -35,7 +35,7 @@ pub struct TftpServer {
bind: IpAddr,
port: u16,
clients: Arc<ClientRegistry>,
metrics: pxeforge_core::Metrics,
metrics: openpxe_core::Metrics,
}
impl TftpServer {
@@ -43,14 +43,14 @@ impl TftpServer {
bind: IpAddr,
port: u16,
clients: Arc<ClientRegistry>,
metrics: pxeforge_core::Metrics,
metrics: openpxe_core::Metrics,
) -> Self {
Self { bind, port, clients, metrics }
}
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);
tracing::info!(target: "openpxe::tftp", "TFTP listening on {}:{}", self.bind, self.port);
let clients = self.clients.clone();
let metrics = self.metrics.clone();
let mut buf = vec![0u8; 2048];
@@ -58,7 +58,7 @@ impl TftpServer {
let (n, from) = match sock.recv_from(&mut buf).await {
Ok(v) => v,
Err(e) => {
tracing::warn!(target: "pxeforge::tftp", "recv error: {e}");
tracing::warn!(target: "openpxe::tftp", "recv error: {e}");
continue;
}
};
@@ -69,7 +69,7 @@ impl TftpServer {
tokio::spawn(async move {
if let Err(e) = handle_rrq(data, from, bind_ip, clients, metrics.clone()).await {
metrics.record_tftp_err();
tracing::warn!(target: "pxeforge::tftp", peer=%from, "handler error: {e}");
tracing::warn!(target: "openpxe::tftp", peer=%from, "handler error: {e}");
}
});
}
@@ -81,7 +81,7 @@ async fn handle_rrq(
peer: SocketAddr,
bind_ip: IpAddr,
clients: Arc<ClientRegistry>,
metrics: pxeforge_core::Metrics,
metrics: openpxe_core::Metrics,
) -> anyhow::Result<()> {
let Some(req) = parse_rrq(&packet) else {
return Ok(());
@@ -93,7 +93,7 @@ async fn handle_rrq(
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");
tracing::info!(target: "openpxe::tftp", peer=%peer, file=%filename, "404");
clients.record(
&peer.ip().to_string(),
Some(peer.ip()),
@@ -104,7 +104,7 @@ async fn handle_rrq(
};
tracing::info!(
target: "pxeforge::tftp",
target: "openpxe::tftp",
peer=%peer, file=%filename, size=file_bytes.len(),
"serving"
);
@@ -200,7 +200,7 @@ async fn handle_rrq(
tries += 1;
if tries > 5 {
tracing::warn!(
target: "pxeforge::tftp",
target: "openpxe::tftp",
peer=%peer, last_block=last_block_in_window,
"timeout after {tries} retries, aborting transfer"
);
@@ -241,7 +241,7 @@ async fn handle_rrq(
let _ = tokio::time::timeout(Duration::from_secs(3), recv_ack(&sock, peer)).await;
}
tracing::debug!(target: "pxeforge::tftp", peer=%peer, bytes=total, "transfer complete");
tracing::debug!(target: "openpxe::tftp", peer=%peer, bytes=total, "transfer complete");
metrics.record_tftp_ok(total as u64);
Ok(())
}
+2 -2
View File
@@ -1,10 +1,10 @@
[package]
name = "pxeforge-webui"
name = "openpxe-webui"
version.workspace = true
edition.workspace = true
license.workspace = true
authors.workspace = true
description = "Embedded single-file web UI for PXEForge"
description = "Embedded single-file web UI for OpenPXE"
[lints]
workspace = true
-81
View File
@@ -1,81 +0,0 @@
<svg viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg" fill="none">
<title>PXEForge — forging</title>
<defs>
<linearGradient id="afBody" x1="0" y1="0" x2="0" y2="1">
<stop offset="0%" stop-color="#aab3c2"/>
<stop offset="55%" stop-color="#7d8696"/>
<stop offset="100%" stop-color="#525a6b"/>
</linearGradient>
<linearGradient id="afFace" x1="0" y1="0" x2="0" y2="1">
<stop offset="0%" stop-color="#cdd5e1"/>
<stop offset="100%" stop-color="#9aa3b3"/>
</linearGradient>
<linearGradient id="afBase" x1="0" y1="0" x2="0" y2="1">
<stop offset="0%" stop-color="#3b4252"/>
<stop offset="100%" stop-color="#252a36"/>
</linearGradient>
<radialGradient id="afSpark" cx="50%" cy="50%" r="50%">
<stop offset="0%" stop-color="#fff5b8" stop-opacity="1"/>
<stop offset="40%" stop-color="#ff9a3a" stop-opacity="0.9"/>
<stop offset="100%" stop-color="#ff5a18" stop-opacity="0"/>
</radialGradient>
<radialGradient id="afEmber" cx="50%" cy="50%" r="50%">
<stop offset="0%" stop-color="#ffd47a" stop-opacity="1"/>
<stop offset="100%" stop-color="#ff7322" stop-opacity="0"/>
</radialGradient>
</defs>
<!-- Anvil shifted down so sparks have room to rise above -->
<g transform="translate(0,40)">
<!-- Horn + face -->
<path d="M14 36 L72 30 L162 30 L162 46 L72 46 Z"
fill="url(#afFace)" stroke="#1d2330" stroke-width="2.4" stroke-linejoin="round"/>
<!-- Body / waist -->
<path d="M70 46 L160 46 L142 70 L88 70 Z"
fill="url(#afBody)" stroke="#1d2330" stroke-width="2.4" stroke-linejoin="round"/>
<!-- Pillar -->
<rect x="92" y="70" width="46" height="26" fill="url(#afBody)"
stroke="#1d2330" stroke-width="2.4"/>
<!-- Base -->
<path d="M62 96 L168 96 L160 110 L70 110 Z"
fill="url(#afBase)" stroke="#0d1018" stroke-width="2.4" stroke-linejoin="round"/>
<line x1="74" y1="34" x2="158" y2="34" stroke="#e6ecf5" stroke-width="1.2" opacity="0.7"/>
<!-- Soft underglow on top face where the sparks land -->
<ellipse cx="115" cy="33" rx="42" ry="6" fill="url(#afEmber)" opacity="0.55">
<animate attributeName="opacity" values="0.35;0.7;0.35"
dur="1.6s" repeatCount="indefinite"/>
</ellipse>
</g>
<!-- Sparks. SMIL animations only — no JS, no CSS needed. Each spark
rises, fades, restarts at a staggered delay for an organic feel. -->
<g class="sparks">
<circle cx="116" cy="62" r="3.4" fill="url(#afSpark)" opacity="0">
<animate attributeName="cy" from="62" to="14" dur="1.4s" repeatCount="indefinite"/>
<animate attributeName="cx" values="116;112;120;116" dur="1.4s" repeatCount="indefinite"/>
<animate attributeName="r" values="2;3.6;1.4" dur="1.4s" repeatCount="indefinite"/>
<animate attributeName="opacity" values="0;1;0" dur="1.4s" repeatCount="indefinite"/>
</circle>
<circle cx="105" cy="62" r="2.4" fill="url(#afSpark)" opacity="0">
<animate attributeName="cy" from="62" to="22" dur="1.7s" begin="0.25s" repeatCount="indefinite"/>
<animate attributeName="cx" values="105;101;108;104" dur="1.7s" begin="0.25s" repeatCount="indefinite"/>
<animate attributeName="r" values="1.6;2.8;1" dur="1.7s" begin="0.25s" repeatCount="indefinite"/>
<animate attributeName="opacity" values="0;1;0" dur="1.7s" begin="0.25s" repeatCount="indefinite"/>
</circle>
<circle cx="125" cy="62" r="2.8" fill="url(#afSpark)" opacity="0">
<animate attributeName="cy" from="62" to="6" dur="1.9s" begin="0.55s" repeatCount="indefinite"/>
<animate attributeName="cx" values="125;130;121;127" dur="1.9s" begin="0.55s" repeatCount="indefinite"/>
<animate attributeName="r" values="1.8;3.2;1.2" dur="1.9s" begin="0.55s" repeatCount="indefinite"/>
<animate attributeName="opacity" values="0;1;0" dur="1.9s" begin="0.55s" repeatCount="indefinite"/>
</circle>
<circle cx="113" cy="62" r="2" fill="url(#afEmber)" opacity="0">
<animate attributeName="cy" from="62" to="32" dur="1.2s" begin="0.9s" repeatCount="indefinite"/>
<animate attributeName="opacity" values="0;0.9;0" dur="1.2s" begin="0.9s" repeatCount="indefinite"/>
</circle>
<circle cx="132" cy="62" r="2.2" fill="url(#afSpark)" opacity="0">
<animate attributeName="cy" from="62" to="20" dur="1.5s" begin="1.2s" repeatCount="indefinite"/>
<animate attributeName="cx" values="132;138;128" dur="1.5s" begin="1.2s" repeatCount="indefinite"/>
<animate attributeName="opacity" values="0;1;0" dur="1.5s" begin="1.2s" repeatCount="indefinite"/>
</circle>
</g>
</svg>

Before

Width:  |  Height:  |  Size: 4.6 KiB

+31 -31
View File
@@ -1,4 +1,4 @@
/* PXEForge web UI — Netbox-style minimal layout, fully offline.
/* OpenPXE web UI — Netbox-style minimal layout, fully offline.
*
* Theme tokens live on `:root` (dark default) and `:root[data-theme=light]`.
* Both palettes share variable *names*, so component CSS uses
@@ -279,35 +279,35 @@ label.check input { accent-color: var(--accent); }
.progress.active { display: block; }
.progress .bar { height: 100%; width: 0%; background: var(--accent); transition: width .25s; }
/* ── Forge progress widget ─────────────────────────────────────────
Anvil-with-sparks animation paired with a horizontal progress bar.
Used on the Forge Gate tab to give a sense of the "in-flight"
imaging count without having to read a number. */
.forge-progress {
/* ── Imaging progress widget ───────────────────────────────────────
Animated brand mark paired with a horizontal progress bar; surfaces
on Dashboard and the Queue tab. Renamed from `.forge-progress` in
v0.3.0 — the anvil-themed naming is gone with the rebrand. */
.queue-progress {
display: flex; align-items: center; gap: 16px;
padding: 16px;
}
.forge-progress .anvil {
width: 64px; height: 64px; flex: none;
background: url("/assets/anvil-forge.svg") no-repeat center / contain;
filter: drop-shadow(0 0 14px color-mix(in srgb, var(--warn) 40%, transparent));
.queue-progress .mark {
width: 56px; height: 56px; flex: none; border-radius: 50%;
background: url("/assets/loader.svg") no-repeat center / contain;
filter: drop-shadow(0 0 16px rgba(255, 255, 255, 0.10));
}
.forge-progress .info { flex: 1; min-width: 0; }
.forge-progress .info .label {
.queue-progress .info { flex: 1; min-width: 0; }
.queue-progress .info .label {
font-size: 12.5px; color: var(--fg-dim); margin-bottom: 6px;
}
.forge-progress .bar-track {
.queue-progress .bar-track {
height: 8px; background: var(--bg-elev); border-radius: 4px;
overflow: hidden; position: relative;
}
.forge-progress .bar-fill {
.queue-progress .bar-fill {
height: 100%;
background: linear-gradient(90deg, var(--warn), var(--accent));
background: linear-gradient(90deg, var(--accent-dim), var(--accent));
width: 0%;
transition: width 0.4s ease;
position: relative;
}
.forge-progress .bar-fill::after {
.queue-progress .bar-fill::after {
/* Subtle moving sheen so the bar feels alive even at 0% movement. */
content: ""; position: absolute; inset: 0;
background: linear-gradient(
@@ -315,24 +315,24 @@ label.check input { accent-color: var(--accent); }
rgba(255,255,255,0) 0%,
rgba(255,255,255,0.18) 50%,
rgba(255,255,255,0) 100%);
animation: forge-sheen 1.6s linear infinite;
animation: queue-sheen 1.6s linear infinite;
}
@keyframes forge-sheen {
@keyframes queue-sheen {
from { transform: translateX(-100%); }
to { transform: translateX(100%); }
}
.forge-progress.idle .anvil { filter: none; opacity: 0.45; }
.forge-progress.idle .bar-fill::after { animation: none; }
.queue-progress.idle .mark { filter: grayscale(0.85) opacity(0.55); }
.queue-progress.idle .bar-fill::after { animation: none; }
/* ── Page-load anvil ──────────────────────────────────────────────── */
/* ── Page-load loader ────────────────────────────────────────────── */
.loader {
display: flex; flex-direction: column; align-items: center; gap: 12px;
padding: 40px 20px;
color: var(--fg-dim);
}
.loader .anvil {
width: 110px; height: 110px;
background: url("/assets/anvil-forge.svg") no-repeat center / contain;
.loader .mark {
width: 96px; height: 96px;
background: url("/assets/loader.svg") no-repeat center / contain;
}
/* ── Top bar readiness chip ──────────────────────────────────────── */
@@ -381,22 +381,22 @@ tr.unbootable td:first-child { border-left: 3px solid var(--warn); }
@media (max-width: 900px) { .form-row { grid-template-columns: 1fr; } }
/* ── Gate queue "horse race" visual ──────────────────────────────── */
.gate-track {
.queue-track {
display: grid; gap: 6px;
padding: 10px 0;
}
.gate-row {
.queue-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; }
.queue-row.assigned { border-left-color: var(--ok); }
.queue-row .pos { font-family: var(--mono); font-size: 15px; color: var(--accent); font-weight: 600; }
.queue-row.assigned .pos { color: var(--ok); }
.queue-row .mac { font-family: var(--mono); font-size: 13px; }
.queue-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; }
+47 -47
View File
@@ -1,7 +1,7 @@
// PXEForge web UI — vanilla JS, no build step, no framework, no network
// OpenPXE 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 /
// Tabs (Phase 4): Dashboard / Network / Queue / Storage / Terminal /
// About. The shell swaps a single view into #view-root.
//
// Keep this readable — nobody wants to debug a clever vanilla-JS
@@ -75,19 +75,19 @@
return fetch(url, {method:'POST', headers:{'Content-Type':'application/json'}, body: JSON.stringify(body)});
}
// Animated "anvil + progress bar" widget. Built once here and inlined
// wherever a card wants to convey "an image is being forged onto the
// bench right now." Used on the dashboard and on the Forge Gate.
function forgeProgressWidget(imaging, gateTotal) {
const total = Math.max(gateTotal, imaging, 1);
// Animated brand-mark + progress bar widget. Built once here and inlined
// wherever a card wants to convey "an image is being deployed onto a
// queued client right now." Used on the Dashboard and the Queue tab.
function queueProgressWidget(imaging, queueTotal) {
const total = Math.max(queueTotal, imaging, 1);
const pct = imaging > 0 ? Math.round((imaging / total) * 100) : 0;
const root = el('div', {class: 'forge-progress' + (imaging === 0 ? ' idle' : '')}, [
el('div', {class: 'anvil', 'aria-hidden': 'true'}),
const root = el('div', {class: 'queue-progress' + (imaging === 0 ? ' idle' : '')}, [
el('div', {class: 'mark', 'aria-hidden': 'true'}),
el('div', {class: 'info'}, [
el('div', {class: 'label'},
imaging === 0
? 'No active imaging'
: (imaging + ' of ' + total + ' device' + (total === 1 ? '' : 's') + ' being forged')),
: (imaging + ' of ' + total + ' device' + (total === 1 ? '' : 's') + ' deploying')),
el('div', {class: 'bar-track'},
el('div', {class: 'bar-fill', style: 'width:' + pct + '%'})),
]),
@@ -120,7 +120,7 @@
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 entries = (await getJSON('/api/queue')).entries || [];
const ipxeOk = (status.ipxe_assets || []).length > 0;
const stats = el('div', {class: 'statstrip'}, [
@@ -136,9 +136,9 @@
el('div', {class: 'stat', style: 'padding-bottom:0'}, [
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: 'trend'}, (status.waiting_count || 0) + ' waiting in queue'),
]),
forgeProgressWidget(status.imaging_count || 0, status.gate_count || 0),
queueProgressWidget(status.imaging_count || 0, status.queue_count || 0),
]),
el('div', {class: 'card'}, el('div', {class: 'stat'}, [
el('div', {class: 'label'}, 'Images available'),
@@ -151,7 +151,7 @@
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),
el('div', {class: 'trend'}, 'OpenPXE ' + status.version),
])),
]);
@@ -159,10 +159,10 @@
// 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);
const g = entries.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');
else if (g) status = el('span', {class:'tag accent'}, '#' + g.position + ' in queue');
return el('tr', {}, [
el('td', {class: 'mono'}, c.mac),
el('td', {}, c.last_ip ? String(c.last_ip) : '-'),
@@ -229,13 +229,13 @@
]),
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 ' +
'To change them, set OPENPXE_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 ' +
'OpenPXE 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.'),
]),
@@ -247,8 +247,8 @@
},
gate: async () => {
const [{ gates = [] }, isos] = await Promise.all([
getJSON('/api/gate'), getJSON('/api/isos'),
const [{ entries = [] }, isos] = await Promise.all([
getJSON('/api/queue'), getJSON('/api/isos'),
]);
const targets = isos.flatMap(i => i.boot_entries.map(e => ({
id: e.id, title: e.title + ' — ' + familyLabel(i.introspection.family)
@@ -261,7 +261,7 @@
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: [] });
const r = await postJSON('/api/queue/assign', { target: pick.value, entry_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; }
@@ -270,9 +270,9 @@
render('gate');
};
const track = gates.length
? el('div', {class:'gate-track'},
gates.map(g => el('div', {class:'gate-row' + (g.assigned_target ? ' assigned' : '')}, [
const track = entries.length
? el('div', {class:'queue-track'},
entries.map(g => el('div', {class:'queue-row' + (g.assigned_target ? ' assigned' : '')}, [
el('div', {class:'pos'}, '#' + g.position),
el('div', {}, [
el('div', {class:'mac'}, g.mac),
@@ -283,20 +283,20 @@
? 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'});
await fetch('/api/queue/' + 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.');
'No clients at the gate. Boot a client and choose "Queued Deployment" in the PXE menu.');
const imaging = gates.filter(g => g.assigned_target).length;
const imaging = entries.filter(g => g.assigned_target).length;
return el('div', {class:'grid'}, [
el('div', {class:'card'}, [
el('header', {}, el('h2', {}, 'Forge')),
forgeProgressWidget(imaging, gates.length),
queueProgressWidget(imaging, entries.length),
]),
el('div', {class:'card'}, [
el('header', {}, el('h2', {}, 'Launch an image across the gate')),
@@ -313,7 +313,7 @@
el('div', {class:'card'}, [
el('header', {}, [
el('h2', {}, 'Gate positions'),
el('span', {class:'sub'}, gates.length + ' waiting'),
el('span', {class:'sub'}, entries.length + ' waiting'),
]),
el('div', {class:'body'}, track),
]),
@@ -516,7 +516,7 @@
// Reserved menu shortcuts that the operator might want to bind.
const reserved = [
{id: '_local', title: '↳ Boot from Local HDD (built-in)'},
{id: '_gate', title: '↳ Gated Deployment (built-in)'},
{id: '_queue', title: '↳ Queued Deployment (built-in)'},
{id: '_tools_menu', title: '↳ Tools menu (built-in)'},
];
@@ -583,7 +583,7 @@
]),
upsertBtn, msg,
el('p', {class:'msg', style:'margin-top:14px'},
'When a client with a bound MAC requests boot.ipxe, PXEForge ' +
'When a client with a bound MAC requests boot.ipxe, OpenPXE ' +
'short-circuits past the interactive menu and chains directly. ' +
'Inspired by Tinkerbell smee\'s MAC-prepended URL pattern.'),
]),
@@ -629,7 +629,7 @@
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') + '] '),
el('span', {class:'tg'}, '[' + (line.target || 'openpxe') + '] '),
line.message,
'\n',
]);
@@ -647,7 +647,7 @@
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',
append({timestamp: new Date().toISOString(), level:'warn', target:'openpxe::ui',
message: 'failed to load recent logs: ' + e.message});
}
@@ -655,12 +655,12 @@
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}); }
catch { append({timestamp: new Date().toISOString(), level:'debug', target:'openpxe::ui', message: ev.data}); }
};
es.addEventListener('lagged', (ev) => {
const j = JSON.parse(ev.data || '{}');
append({timestamp: new Date().toISOString(), level:'warn',
target:'pxeforge::ui',
target:'openpxe::ui',
message: 'log stream lagged: ' + (j.skipped || '?') + ' lines skipped'});
});
es.onerror = () => {
@@ -668,7 +668,7 @@
// 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',
append({timestamp: new Date().toISOString(), level:'warn', target:'openpxe::ui',
message: 'log stream connection lost — auto-reconnecting'});
setTimeout(() => { term._notedErr = false; }, 5000);
}
@@ -701,7 +701,7 @@
target: 'terminal-output', message: out});
} catch (err) {
append({timestamp: new Date().toISOString(), level:'error',
target:'pxeforge::ui', message: 'command failed: ' + err.message});
target:'openpxe::ui', message: 'command failed: ' + err.message});
}
} else if (e.key === 'ArrowUp') {
if (history.length === 0) return;
@@ -716,7 +716,7 @@
});
// Welcome banner.
append({timestamp: new Date().toISOString(), level:'info', target:'pxeforge::terminal',
append({timestamp: new Date().toISOString(), level:'info', target:'openpxe::terminal',
message: 'Connected. Type "help" for available commands.'});
// Focus the input on next tick (after view swap completes).
@@ -729,7 +729,7 @@
const status = await getJSON('/api/status');
return el('div', {class:'card'}, [
el('div', {class:'about-hero'}, [
el('h2', {}, 'PXEForge'),
el('h2', {}, 'OpenPXE'),
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 ' +
@@ -758,7 +758,7 @@
const viewTitles = {
dashboard: 'Dashboard',
network: 'Network',
gate: 'Forge Gate',
gate: 'Queue',
storage: 'Storage',
hosts: 'Hosts',
terminal: 'Terminal',
@@ -769,7 +769,7 @@
// script in index.html before paint; we just flip it here and persist.
function applyTheme(theme) {
document.documentElement.setAttribute('data-theme', theme);
try { localStorage.setItem('pxeforge-theme', theme); } catch {}
try { localStorage.setItem('openpxe-theme', theme); } catch {}
}
function currentTheme() {
return document.documentElement.getAttribute('data-theme') === 'light' ? 'light' : 'dark';
@@ -801,12 +801,12 @@
try { currentBody._cleanup(); } catch (e) { /* ignore */ }
}
root.innerHTML = '';
// Animated anvil loader. Replaces the old text "Loading…" so the
// user gets a sense of "the forge is heating up" instead of a flat
// spinner. The SVG itself drives all animation via SMIL, no JS.
// Animated rainbow-mark loader replacing the old plain-text
// \"Loading…\". The SVG drives all animation via SMIL — no JS, no
// CSS keyframes.
root.appendChild(el('div', {class:'loader'}, [
el('div', {class:'anvil'}),
el('div', {}, 'Heating the forge…'),
el('div', {class:'mark'}),
el('div', {}, 'Loading…'),
]));
try {
const body = await views[view]();
@@ -826,7 +826,7 @@
$$('[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));
$$('[data-bind=queue_count],[data-bind=queue_count2]').forEach(n => n.textContent = String(s.queue_count));
$$('[data-bind=host_count]').forEach(n => n.textContent = String(s.host_bindings || 0));
const chip = $('[data-bind=ready_chip]');
if (chip) {
+8 -8
View File
@@ -4,7 +4,7 @@
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="color-scheme" content="dark light" />
<title>PXEForge</title>
<title>OpenPXE</title>
<link rel="stylesheet" href="/assets/app.css" />
<link rel="icon" type="image/svg+xml" href="/assets/logo.svg" />
<!-- Theme is read from localStorage *before* paint to avoid the
@@ -13,7 +13,7 @@
<script>
(function() {
try {
var stored = localStorage.getItem('pxeforge-theme');
var stored = localStorage.getItem('openpxe-theme');
var theme = stored || (matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark');
document.documentElement.setAttribute('data-theme', theme);
} catch (e) {
@@ -28,16 +28,16 @@
<div class="brand">
<img src="/assets/logo.svg" alt="" />
<div>
<strong>PXEForge</strong>
<div class="sub">v<span data-bind="version">0.2.0</span></div>
<strong>OpenPXE</strong>
<div class="sub">v<span data-bind="version">0.3.0</span></div>
</div>
</div>
<nav>
<a data-view="dashboard" class="active">Dashboard</a>
<a data-view="network">Network</a>
<a data-view="gate">
Forge Gate
<span class="count" data-bind="gate_count">0</span>
<a data-view="queue">
Queue
<span class="count" data-bind="queue_count">0</span>
</a>
<a data-view="storage">
Storage
@@ -62,7 +62,7 @@
<span class="chip" data-bind="ready_chip" title="Server readiness">checking…</span>
<span class="chip"><strong data-bind="iso_count2">0</strong>&nbsp;images</span>
<span class="chip"><strong data-bind="client_count2">0</strong>&nbsp;clients</span>
<span class="chip"><strong data-bind="gate_count2">0</strong>&nbsp;at gate</span>
<span class="chip"><strong data-bind="queue_count2">0</strong>&nbsp;in queue</span>
<button id="theme-toggle" class="theme-toggle" type="button"
aria-label="Toggle light/dark theme" title="Toggle theme (T)">
<!-- Two glyphs; CSS shows whichever matches the active theme. -->
+10 -10
View File
@@ -1,7 +1,7 @@
//! 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.
//! OpenPXE 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.
@@ -23,14 +23,14 @@ pub fn app_css() -> &'static str { APP_CSS }
#[must_use]
pub fn logo_svg() -> &'static str { LOGO_SVG }
/// Animated forging anvil — sparks rise + glow pulse. Used for the
/// imaging-progress widget and any "I'm working" loading state. Pure
/// SVG + SMIL, no JS, no GIF.
/// Larger, faster-cycling rainbow disc — used for the page-load
/// transition and the imaging-progress widget on Dashboard / Queue.
/// Pure SVG + SMIL, no JS, no GIF.
#[must_use]
pub fn anvil_forge_svg() -> &'static str { ANVIL_FORGE_SVG }
pub fn loader_svg() -> &'static str { LOADER_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");
const ANVIL_FORGE_SVG: &str = include_str!("anvil-forge.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");
const LOADER_SVG: &str = include_str!("loader.svg");
+36
View File
@@ -0,0 +1,36 @@
<svg viewBox="0 0 64 64" xmlns="http://www.w3.org/2000/svg">
<title>OpenPXE — loading</title>
<!-- Larger, bolder version of the brand mark for "I'm working" states:
page transitions, the imaging-progress widget on Dashboard / Queue.
The gradient slide is faster (3s) and we add a subtle scale pulse
so the disc looks alive even when paired with a static progress bar.
White inner glow keeps the colours legible against the panel bg. -->
<defs>
<linearGradient id="opxRainbowLg" x1="0" y1="0" x2="1" y2="0">
<stop offset="0%" stop-color="#330f1f"/>
<stop offset="12.56%" stop-color="#c83228"/>
<stop offset="25.06%" stop-color="#fb8841"/>
<stop offset="37.56%" stop-color="#d3dd92"/>
<stop offset="50.06%" stop-color="#59824f"/>
<stop offset="62.06%" stop-color="#002414"/>
<stop offset="74.06%" stop-color="#00143d"/>
<stop offset="86.06%" stop-color="#2874d7"/>
<stop offset="100%" stop-color="#99c2ff"/>
<animate attributeName="x1" values="0;-1;0" dur="3s" repeatCount="indefinite"/>
<animate attributeName="x2" values="1;0;1" dur="3s" repeatCount="indefinite"/>
</linearGradient>
<radialGradient id="opxGlow" cx="50%" cy="50%" r="50%">
<stop offset="0%" stop-color="rgba(255,255,255,0.6)"/>
<stop offset="60%" stop-color="rgba(255,255,255,0.05)"/>
<stop offset="100%" stop-color="rgba(255,255,255,0)"/>
</radialGradient>
</defs>
<g>
<circle cx="32" cy="32" r="26" fill="url(#opxRainbowLg)"
stroke="rgba(0,0,0,0.2)" stroke-width="1.2">
<animate attributeName="r" values="25;27;25" dur="2.4s" repeatCount="indefinite"/>
</circle>
<!-- Inner highlight to give the disc a hint of dimensionality. -->
<circle cx="28" cy="26" r="14" fill="url(#opxGlow)"/>
</g>
</svg>

After

Width:  |  Height:  |  Size: 1.8 KiB

+21 -28
View File
@@ -1,32 +1,25 @@
<svg viewBox="0 0 200 130" xmlns="http://www.w3.org/2000/svg" fill="none">
<title>PXEForge</title>
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
<title>OpenPXE</title>
<!-- Brand mark to match openpxe.com: a circular medallion filled with
the "rainbow-horizon" gradient, sliding 200% across to give a slow
hue rotation. Subtle stroke + drop shadow for legibility on either
theme. SMIL keeps it self-driving with no JS or CSS dependency. -->
<defs>
<linearGradient id="anvilBody" x1="0" y1="0" x2="0" y2="1">
<stop offset="0%" stop-color="#aab3c2"/>
<stop offset="55%" stop-color="#7d8696"/>
<stop offset="100%" stop-color="#525a6b"/>
</linearGradient>
<linearGradient id="anvilFace" x1="0" y1="0" x2="0" y2="1">
<stop offset="0%" stop-color="#cdd5e1"/>
<stop offset="100%" stop-color="#9aa3b3"/>
</linearGradient>
<linearGradient id="anvilBase" x1="0" y1="0" x2="0" y2="1">
<stop offset="0%" stop-color="#3b4252"/>
<stop offset="100%" stop-color="#252a36"/>
<linearGradient id="opxRainbow" x1="0" y1="0" x2="1" y2="0">
<stop offset="0%" stop-color="#330f1f"/>
<stop offset="12.56%" stop-color="#c83228"/>
<stop offset="25.06%" stop-color="#fb8841"/>
<stop offset="37.56%" stop-color="#d3dd92"/>
<stop offset="50.06%" stop-color="#59824f"/>
<stop offset="62.06%" stop-color="#002414"/>
<stop offset="74.06%" stop-color="#00143d"/>
<stop offset="86.06%" stop-color="#2874d7"/>
<stop offset="100%" stop-color="#99c2ff"/>
<animate attributeName="x1" values="0;-1;0" dur="12s" repeatCount="indefinite"/>
<animate attributeName="x2" values="1;0;1" dur="12s" repeatCount="indefinite"/>
</linearGradient>
</defs>
<!-- Horn (left point) + face (top) -->
<path d="M14 36 L72 30 L162 30 L162 46 L72 46 Z"
fill="url(#anvilFace)" stroke="#1d2330" stroke-width="2.4" stroke-linejoin="round"/>
<!-- Body / waist -->
<path d="M70 46 L160 46 L142 70 L88 70 Z"
fill="url(#anvilBody)" stroke="#1d2330" stroke-width="2.4" stroke-linejoin="round"/>
<!-- Base plinth -->
<path d="M62 96 L168 96 L160 110 L70 110 Z"
fill="url(#anvilBase)" stroke="#0d1018" stroke-width="2.4" stroke-linejoin="round"/>
<!-- Pillar between body and base -->
<rect x="92" y="70" width="46" height="26" fill="url(#anvilBody)"
stroke="#1d2330" stroke-width="2.4"/>
<!-- Highlight along top face -->
<line x1="74" y1="34" x2="158" y2="34" stroke="#e6ecf5" stroke-width="1.2" opacity="0.7"/>
<!-- Outer hairline ring softens the edge in light mode; subtle in dark. -->
<circle cx="12" cy="12" r="10.5" fill="url(#opxRainbow)"
stroke="rgba(0,0,0,0.18)" stroke-width="0.6"/>
</svg>

Before

Width:  |  Height:  |  Size: 1.5 KiB

After

Width:  |  Height:  |  Size: 1.3 KiB

+19 -19
View File
@@ -1,6 +1,6 @@
# syntax=docker/dockerfile:1.7
#
# PXEForge — multi-stage build.
# OpenPXE — multi-stage build.
#
# Design:
# - stage `fetch`: runs scripts/fetch-ipxe.sh to pull official iPXE binaries
@@ -8,7 +8,7 @@
# - 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.
# attacker surface is just the openpxe 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
@@ -24,7 +24,7 @@ WORKDIR /src
COPY scripts/fetch-ipxe.sh scripts/fetch-ipxe.sh
RUN mkdir -p assets/ipxe && bash scripts/fetch-ipxe.sh
########## build pxeforge ##########
########## build openpxe ##########
FROM rust:${RUST_VERSION}-bookworm AS build
WORKDIR /src
@@ -43,9 +43,9 @@ COPY --from=fetch /src/assets/ipxe /src/assets/ipxe
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
cargo build --release --bin openpxe && \
cp target/release/openpxe /openpxe && \
ls -l /openpxe
########## runtime ##########
FROM debian:12-slim AS runtime
@@ -54,13 +54,13 @@ RUN apt-get update \
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
&& useradd --system --uid 10001 --home-dir /var/lib/openpxe --shell /usr/sbin/nologin openpxe \
&& mkdir -p /var/lib/openpxe/isos /var/lib/openpxe/work /var/lib/openpxe/smb \
&& chown -R openpxe:openpxe /var/lib/openpxe
# 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.
# to `net use`. Guest read-only, scoped to /var/lib/openpxe/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
@@ -74,23 +74,23 @@ RUN apt-get update \
# 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 --from=build /openpxe /usr/local/bin/openpxe
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
# This is the only capability OpenPXE needs for proxy-mode DHCP + TFTP + HTTP.
RUN setcap cap_net_bind_service=+ep /usr/local/bin/openpxe
# 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.
# IMPORTANT: we do NOT `USER openpxe` here. The entrypoint runs as root,
# chowns the mounted data dirs, then execs the binary via gosu as openpxe.
# 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
WORKDIR /var/lib/openpxe
ENV PXEFORGE_ISO_DIR=/var/lib/pxeforge/isos \
PXEFORGE_WORK_DIR=/var/lib/pxeforge/work \
PXEFORGE_LOG=info,pxeforge=info
ENV OPENPXE_ISO_DIR=/var/lib/openpxe/isos \
OPENPXE_WORK_DIR=/var/lib/openpxe/work \
OPENPXE_LOG=info,openpxe=info
EXPOSE 67/udp 69/udp 4011/udp 80/tcp 445/tcp
+9 -9
View File
@@ -2,9 +2,9 @@
# 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
# they come up owned by the host uid:gid — often root:root. The openpxe
# 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
# as root, chowns the two state dirs to the openpxe user, then drops
# privileges via gosu before execing the binary.
#
# If the container is already running as non-root (OpenShift does this via
@@ -13,20 +13,20 @@
# 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"
OPENPXE_UID=${OPENPXE_UID:-10001}
OPENPXE_GID=${OPENPXE_GID:-10001}
DATA_DIRS="/var/lib/openpxe/isos /var/lib/openpxe/work /var/lib/openpxe/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
chown -R "${OPENPXE_UID}:${OPENPXE_GID}" "$d" 2>/dev/null || true
fi
done
# Re-exec ourselves under the pxeforge user so the binary inherits a
# Re-exec ourselves under the openpxe user so the binary inherits a
# clean process environment and a predictable umask.
exec gosu "${PXEFORGE_UID}:${PXEFORGE_GID}" /usr/local/bin/pxeforge "$@"
exec gosu "${OPENPXE_UID}:${OPENPXE_GID}" /usr/local/bin/openpxe "$@"
fi
# Non-root: straight exec, no chown attempt.
exec /usr/local/bin/pxeforge "$@"
exec /usr/local/bin/openpxe "$@"
+1 -1
View File
@@ -1,7 +1,7 @@
apiVersion: v1
kind: Namespace
metadata:
name: pxeforge
name: openpxe
labels:
# Allow privileged pods (host-network) in this namespace only. The pod
# itself still runs non-root with only NET_BIND_SERVICE — privileged
+11 -11
View File
@@ -1,5 +1,5 @@
---
# Custom SCC for PXEForge.
# Custom SCC for OpenPXE.
#
# The default `restricted-v2` SCC blocks host network and all capabilities,
# which PXE cannot tolerate: DHCPDISCOVER is an L2 broadcast that CNI overlays
@@ -19,10 +19,10 @@
apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
name: pxeforge-scc
name: openpxe-scc
annotations:
kubernetes.io/description: >-
Minimal SCC for PXEForge: host network + NET_BIND_SERVICE only, no raw
Minimal SCC for OpenPXE: host network + NET_BIND_SERVICE only, no raw
sockets, no privileged mode.
allowPrivilegedContainer: false
allowPrivilegeEscalation: false
@@ -54,27 +54,27 @@ volumes:
users: []
groups: []
---
# Bind the SCC to the pxeforge service account.
# Bind the SCC to the openpxe service account.
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: pxeforge-scc-use
name: openpxe-scc-use
rules:
- apiGroups: ["security.openshift.io"]
resources: ["securitycontextconstraints"]
resourceNames: ["pxeforge-scc"]
resourceNames: ["openpxe-scc"]
verbs: ["use"]
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: pxeforge-scc-use
namespace: pxeforge
name: openpxe-scc-use
namespace: openpxe
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: pxeforge-scc-use
name: openpxe-scc-use
subjects:
- kind: ServiceAccount
name: pxeforge
namespace: pxeforge
name: openpxe
namespace: openpxe
+9 -9
View File
@@ -2,29 +2,29 @@
apiVersion: v1
kind: ServiceAccount
metadata:
name: pxeforge
namespace: pxeforge
name: openpxe
namespace: openpxe
---
apiVersion: v1
kind: ConfigMap
metadata:
name: pxeforge-config
namespace: pxeforge
name: openpxe-config
namespace: openpxe
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"
OPENPXE_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"
# OPENPXE_PUBLIC_IP: "10.0.0.5"
OPENPXE_LOG: "info,openpxe=info"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: pxeforge-isos
namespace: pxeforge
name: openpxe-isos
namespace: openpxe
spec:
# ReadWriteOnce is fine — we deploy as a single replica since DHCP proxy
# coordination across replicas is not useful (clients hit whichever node
+12 -12
View File
@@ -2,10 +2,10 @@
apiVersion: apps/v1
kind: Deployment
metadata:
name: pxeforge
namespace: pxeforge
name: openpxe
namespace: openpxe
labels:
app.kubernetes.io/name: pxeforge
app.kubernetes.io/name: openpxe
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
@@ -15,13 +15,13 @@ spec:
type: Recreate
selector:
matchLabels:
app.kubernetes.io/name: pxeforge
app.kubernetes.io/name: openpxe
template:
metadata:
labels:
app.kubernetes.io/name: pxeforge
app.kubernetes.io/name: openpxe
spec:
serviceAccountName: pxeforge
serviceAccountName: openpxe
# L2 broadcast (DHCPDISCOVER) does not cross most CNI overlays into
# pod netns. Host network is the working path.
hostNetwork: true
@@ -33,8 +33,8 @@ spec:
runAsUser: 10001
fsGroup: 10001
containers:
- name: pxeforge
image: ghcr.io/casperadmin/pxeforge:0.1.0
- name: openpxe
image: ghcr.io/casperadmin/openpxe:0.1.0
imagePullPolicy: IfNotPresent
ports:
- name: dhcp
@@ -59,7 +59,7 @@ spec:
protocol: TCP
envFrom:
- configMapRef:
name: pxeforge-config
name: openpxe-config
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
@@ -70,9 +70,9 @@ spec:
add: ["NET_BIND_SERVICE"]
volumeMounts:
- name: isos
mountPath: /var/lib/pxeforge/isos
mountPath: /var/lib/openpxe/isos
- name: work
mountPath: /var/lib/pxeforge/work
mountPath: /var/lib/openpxe/work
- name: tmp
mountPath: /tmp
readinessProbe:
@@ -97,7 +97,7 @@ spec:
volumes:
- name: isos
persistentVolumeClaim:
claimName: pxeforge-isos
claimName: openpxe-isos
- name: work
emptyDir: {}
- name: tmp
+7 -7
View File
@@ -5,14 +5,14 @@
apiVersion: v1
kind: Service
metadata:
name: pxeforge
namespace: pxeforge
name: openpxe
namespace: openpxe
labels:
app.kubernetes.io/name: pxeforge
app.kubernetes.io/name: openpxe
spec:
type: ClusterIP
selector:
app.kubernetes.io/name: pxeforge
app.kubernetes.io/name: openpxe
ports:
- name: http
port: 80
@@ -29,12 +29,12 @@ spec:
apiVersion: route.openshift.io/v1
kind: Route
metadata:
name: pxeforge
namespace: pxeforge
name: openpxe
namespace: openpxe
spec:
to:
kind: Service
name: pxeforge
name: openpxe
weight: 100
port:
targetPort: http
+23 -23
View File
@@ -1,12 +1,12 @@
# PXEForge on Unraid
# OpenPXE on Unraid
Three paths from "I have an Unraid box with Gitea on it" to "PXE clients
boot from PXEForge". Pick the one that matches what you have.
boot from OpenPXE". Pick the one that matches what you have.
## Path A — build on Unraid, push to Gitea registry, pull by tag
Recommended once you've done it once. Image is published to
`gitea.milesward.dev/mward4/pxeforge:0.1.0` (or your equivalent) and
`gitea.milesward.dev/mward4/openpxe:0.1.0` (or your equivalent) and
every Unraid template / docker-compose just references the tag.
Pre-flight:
@@ -24,12 +24,12 @@ Run on the Unraid host (Settings → Terminal, or `ssh root@unraid`):
GITEA_TOKEN=<your-token>
curl -fsSL \
-H "Authorization: token $GITEA_TOKEN" \
http://localhost:3000/mward4/PXEForge/raw/branch/main/scripts/build-and-publish-unraid.sh \
-o /tmp/pxeforge-publish.sh
http://localhost:3000/mward4/OpenPXE/raw/branch/main/scripts/build-and-publish-unraid.sh \
-o /tmp/openpxe-publish.sh
# Run it. ~6 min on Unraid hardware (native amd64, no QEMU).
chmod +x /tmp/pxeforge-publish.sh
GITEA_TOKEN=$GITEA_TOKEN /tmp/pxeforge-publish.sh
chmod +x /tmp/openpxe-publish.sh
GITEA_TOKEN=$GITEA_TOKEN /tmp/openpxe-publish.sh
```
What it does:
@@ -47,17 +47,17 @@ After it finishes, in Unraid → Docker → Add Container, set:
| Field | Value |
|------------|-------------------------------------------------|
| Repository | `gitea.milesward.dev/mward4/pxeforge:0.1.0` |
| Repository | `gitea.milesward.dev/mward4/openpxe:0.1.0` |
| Network | `host` |
| Extra args | `--cap-add=NET_BIND_SERVICE` |
Volume mounts (paths inside container in **bold**):
- **`/var/lib/pxeforge/isos`** ↔ `/mnt/user/appdata/pxeforge/isos`
- **`/var/lib/pxeforge/work`** ↔ `/mnt/user/appdata/pxeforge/work`
- **`/var/lib/pxeforge/smb`** ↔ `/mnt/user/appdata/pxeforge/smb`
- **`/var/lib/openpxe/isos`** ↔ `/mnt/user/appdata/openpxe/isos`
- **`/var/lib/openpxe/work`** ↔ `/mnt/user/appdata/openpxe/work`
- **`/var/lib/openpxe/smb`** ↔ `/mnt/user/appdata/openpxe/smb`
Or skip the manual UI by dropping `pxeforge.xml` (in this directory)
Or skip the manual UI by dropping `openpxe.xml` (in this directory)
into `/boot/config/plugins/dockerMan/templates-user/` and Unraid will
list it as a one-click template.
@@ -70,15 +70,15 @@ Skip the registry entirely. Useful for "hack on it locally" iterations.
```bash
ssh root@unraid
cd /mnt/user/appdata
git clone http://localhost:3000/mward4/PXEForge.git pxeforge-src
cd pxeforge-src
git clone http://localhost:3000/mward4/OpenPXE.git openpxe-src
cd openpxe-src
bash scripts/fetch-ipxe.sh
docker compose -f docker-compose.yml up -d --build pxeforge
docker compose -f docker-compose.yml up -d --build openpxe
```
The bundled `docker-compose.yml` already wires host networking, the
right cap_add, and bind-mounts to `./data/`. Edit those bind-mount
paths if you want them under `/mnt/user/appdata/pxeforge/`.
paths if you want them under `/mnt/user/appdata/openpxe/`.
## Path C — `docker load` from a tarball I built off-box
@@ -88,14 +88,14 @@ then:
```bash
# On the build host
docker save pxeforge:0.1.0 | gzip > pxeforge-0.1.0.tar.gz
docker save openpxe:0.1.0 | gzip > openpxe-0.1.0.tar.gz
# Transfer (rsync / scp / SMB / ZFS-replicate / sneakernet)
scp pxeforge-0.1.0.tar.gz root@unraid:/tmp/
scp openpxe-0.1.0.tar.gz root@unraid:/tmp/
# On Unraid
gunzip -c /tmp/pxeforge-0.1.0.tar.gz | docker load
docker tag pxeforge:0.1.0 gitea.milesward.dev/mward4/pxeforge:0.1.0
gunzip -c /tmp/openpxe-0.1.0.tar.gz | docker load
docker tag openpxe:0.1.0 gitea.milesward.dev/mward4/openpxe:0.1.0
```
If you want it pullable by tag from other Unraid templates, push to
@@ -119,16 +119,16 @@ show up in the Dashboard's "Recent connections" table within seconds.
## Common gotchas
- **DHCP collision.** Don't run two PXE _proxies_ on the same broadcast
domain. PXEForge runs in proxy mode and never offers IP leases, so
domain. OpenPXE runs in proxy mode and never offers IP leases, so
it coexists with whatever DHCP server is already on the network —
but two proxies racing each other will whichever-wins at random.
- **Host networking only.** Bridge mode containers don't see broadcast
DHCP. There's no working bridge-mode config for a PXE server.
- **Permissions on `/mnt/user/appdata/pxeforge`.** The container runs
- **Permissions on `/mnt/user/appdata/openpxe`.** The container runs
as uid 10001 by default. The entrypoint chowns the bind mounts to
10001 on first start, but only if the container itself has root —
`--user=root` isn't needed; the multi-stage Dockerfile starts as
root, fixes perms, then drops to pxeforge via gosu.
root, fixes perms, then drops to openpxe via gosu.
- **NFS mounts in the Storage tab.** Mounting NFS inside the container
needs `CAP_SYS_ADMIN`. To enable, add `--cap-add=SYS_ADMIN` to the
Unraid template's "Extra args" — but understand that's a meaningful
@@ -1,12 +1,12 @@
<?xml version="1.0"?>
<!--
Unraid Docker template for PXEForge.
Unraid Docker template for OpenPXE.
Drop this file into /boot/config/plugins/dockerMan/templates-user/
on your Unraid box (or import via the Docker tab → "Add Container" →
"Template Repositories" if you publish it on a Gitea raw URL).
IMPORTANT: PXEForge needs host networking for DHCP/TFTP raw broadcasts.
IMPORTANT: OpenPXE needs host networking for DHCP/TFTP raw broadcasts.
Bridge mode will NOT work — clients can't see broadcast DHCP from a
bridged container. The template forces NetworkType=host below.
@@ -21,20 +21,20 @@
Web UI: http://<unraid-ip>/ (port 80)
-->
<Container version="2">
<Name>PXEForge</Name>
<Repository>gitea.milesward.dev/mward4/pxeforge:latest</Repository>
<Registry>https://gitea.milesward.dev/mward4/-/packages/container/pxeforge</Registry>
<Name>OpenPXE</Name>
<Repository>gitea.milesward.dev/mward4/openpxe:latest</Repository>
<Registry>https://gitea.milesward.dev/mward4/-/packages/container/openpxe</Registry>
<Network>host</Network>
<MyIP/>
<Shell>sh</Shell>
<Privileged>false</Privileged>
<Support>https://gitea.milesward.dev/mward4/PXEForge/issues</Support>
<Project>https://gitea.milesward.dev/mward4/PXEForge</Project>
<Support>https://gitea.milesward.dev/mward4/OpenPXE/issues</Support>
<Project>https://gitea.milesward.dev/mward4/OpenPXE</Project>
<Overview>
Air-gapped network PXE boot server. Container-native Rust
implementation — DHCP proxy + TFTP + iPXE chainload + HTTP ISO
streaming, all in one process. Web UI for ISO upload, NFS share
mounting, and Gated Deployment ("horse-race" simultaneous launch
mounting, and Queued Deployment ("horse-race" simultaneous launch
of one ISO across many waiting clients).
NEVER touches the client OS trust store: no test-signed drivers,
@@ -44,7 +44,7 @@
<Category>Network:Other Network:Management</Category>
<WebUI>http://[IP]/</WebUI>
<TemplateURL/>
<Icon>https://gitea.milesward.dev/mward4/PXEForge/raw/branch/main/crates/webui/src/logo.svg</Icon>
<Icon>https://gitea.milesward.dev/mward4/OpenPXE/raw/branch/main/crates/webui/src/logo.svg</Icon>
<ExtraParams>--cap-add=NET_BIND_SERVICE</ExtraParams>
<PostArgs/>
<CPUset/>
@@ -53,23 +53,23 @@
<DonateLink/>
<Requires>
Host networking. Unraid&#39;s built-in DHCP server (if any) must
not collide with a network that already has DHCP — PXEForge runs
not collide with a network that already has DHCP — OpenPXE runs
in proxy mode and coexists, but only one DHCP _proxy_ should reply
per broadcast domain.
</Requires>
<Config Name="ISOs" Target="/var/lib/pxeforge/isos" Default="/mnt/user/appdata/pxeforge/isos"
<Config Name="ISOs" Target="/var/lib/openpxe/isos" Default="/mnt/user/appdata/openpxe/isos"
Mode="rw" Description="Where uploaded and seeded .iso files live."
Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/pxeforge/isos</Config>
<Config Name="Work dir" Target="/var/lib/pxeforge/work" Default="/mnt/user/appdata/pxeforge/work"
Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/openpxe/isos</Config>
<Config Name="Work dir" Target="/var/lib/openpxe/work" Default="/mnt/user/appdata/openpxe/work"
Mode="rw" Description="Settings, NFS state, and runtime scratch. Persisted across restarts."
Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/pxeforge/work</Config>
<Config Name="SMB share root" Target="/var/lib/pxeforge/smb" Default="/mnt/user/appdata/pxeforge/smb"
Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/openpxe/work</Config>
<Config Name="SMB share root" Target="/var/lib/openpxe/smb" Default="/mnt/user/appdata/openpxe/smb"
Mode="rw" Description="Where extracted Windows install media lives. Only used when Windows toggle is on."
Type="Path" Display="advanced" Required="false" Mask="false">/mnt/user/appdata/pxeforge/smb</Config>
<Config Name="Public IP" Target="PXEFORGE_PUBLIC_IP" Default=""
Type="Path" Display="advanced" Required="false" Mask="false">/mnt/user/appdata/openpxe/smb</Config>
<Config Name="Public IP" Target="OPENPXE_PUBLIC_IP" Default=""
Mode="" Description="IP advertised to PXE clients. Leave blank to auto-detect; set explicitly on multi-homed Unraid hosts."
Type="Variable" Display="always" Required="false" Mask="false"></Config>
<Config Name="Log filter" Target="PXEFORGE_LOG" Default="info,pxeforge=debug"
<Config Name="Log filter" Target="OPENPXE_LOG" Default="info,openpxe=debug"
Mode="" Description="tracing-subscriber EnvFilter expression."
Type="Variable" Display="advanced" Required="false" Mask="false">info,pxeforge=debug</Config>
Type="Variable" Display="advanced" Required="false" Mask="false">info,openpxe=debug</Config>
</Container>
+22 -22
View File
@@ -5,13 +5,13 @@
# 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
# docker compose up openpxe-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
# # First set OPENPXE_PUBLIC_IP to this host's LAN address in .env
# docker compose up openpxe
#
# On Linux hosts, `network_mode: host` gives the container direct access to
# the physical NIC — required for DHCP proxy because CNI overlays and Docker
@@ -19,13 +19,13 @@
#
# 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`
# VM, not your Mac. Proxy-DHCP is not feasible on macOS; use `openpxe-dev`
# with published ports and set DHCP-MODE=disabled.
services:
# Real PXE deployment (Linux hosts).
pxeforge:
image: pxeforge:0.1.0
openpxe:
image: openpxe:0.1.0
build:
context: .
dockerfile: deploy/docker/Dockerfile
@@ -34,33 +34,33 @@ services:
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
# this, OpenPXE 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
OPENPXE_PUBLIC_IP: ${OPENPXE_PUBLIC_IP:?set this to the host LAN IP}
OPENPXE_DHCP_MODE: proxy
OPENPXE_LOG: info
volumes:
- ./data/isos:/var/lib/pxeforge/isos
- ./data/work:/var/lib/pxeforge/work
- ./data/isos:/var/lib/openpxe/isos
- ./data/work:/var/lib/openpxe/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
openpxe-dev:
image: openpxe: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
OPENPXE_PUBLIC_IP: ${OPENPXE_PUBLIC_IP:-127.0.0.1}
OPENPXE_DHCP_MODE: disabled
OPENPXE_HTTP_PORT: "8080"
OPENPXE_TFTP_PORT: "6969"
OPENPXE_DHCP_PORT: "6767"
OPENPXE_LOG: info,openpxe=debug
ports:
- "8080:8080/tcp"
- "6969:6969/udp"
volumes:
- ./data/isos:/var/lib/pxeforge/isos
- ./data/work:/var/lib/pxeforge/work
- ./data/isos:/var/lib/openpxe/isos
- ./data/work:/var/lib/openpxe/work
+156
View File
@@ -0,0 +1,156 @@
# Phase 6 — recommendations
The v0.2.0 cut leaves OpenPXE in a state where the entire protocol stack
and operator UI are exercised by 66 automated tests, the container is
multi-arch buildable, and the image ships at ~97 MB. What's left before
this looks and feels like a 1.0 product is mostly **real-hardware
validation** plus a small batch of features that can only sensibly be
designed once we've watched real machines image.
This doc is a punch list, ordered by what I'd do first if I had a week.
## Tier 1 — must-do before we call anything "stable"
### 1. Real-hardware validation matrix
We have CI tests for every protocol leg, but no end-to-end PXE on real
firmware. Build a small matrix:
| client | firmware | OS family | pass criteria |
|-------------------------------------|-----------|------------|---------------------------|
| any 10-y-old mini-PC | Legacy BIOS | Ubuntu Server 24.04 | gets to GRUB / installer |
| Intel NUC / similar | UEFI x64 | Windows 11 | reaches "where do you want to install" |
| Raspberry Pi 4 | UEFI ARM64 | Raspberry Pi OS | gets to login prompt |
| Dell / HP business laptop | UEFI x64 | Fedora | one of: kernel boot or wimboot |
Add a `docs/HARDWARE_VALIDATION.md` checklist that records what worked,
firmware versions, and any quirks. Anything weird gets a regression
test in the relevant crate.
### 2. Boot menu hotkey + UI accessibility audit
The iPXE menu has number-key + letter hotkeys but no documentation on
what they map to. Generate a printable cheat-sheet from
`crates/http-api/src/ipxe_script.rs` so operators don't have to read
the source. Run a screen-reader pass over the web UI — most of it
should be fine since we're mostly tables + form labels, but the
Terminal pane and the SSE log output need explicit `aria-live`
regions.
### 3. Boot.wim re-patch detection
Bootimus v0.1.62's "fingerprint of patched inputs + Save & Re-patch"
pattern is a small but high-value feature: when an operator changes
the SMB host override or upgrades wimboot, the existing patched
boot.wim is silently stale. We should:
- Hash the inputs (smb_host, smb_share, startnet.cmd content,
wimboot binary digest) into the IsoMeta;
- Surface a "needs re-patch" warning on the Storage tab when the
hash drifts;
- Add a "Re-patch SMB" button that re-runs the WimPatcher.
## Tier 2 — features that round out pre-beta
### 4. Auto-install file library
iVentoy and Bootimus both support attaching `autounattend.xml` /
`preseed.cfg` / `kickstart.cfg` to an image. The mechanics are
straightforward: store files under `<work_dir>/autoinstall/<distro>/`,
expose CRUD via `/api/autoinstall-files`, and modify the WimPatcher
+ Linux kernel cmdline to fetch + apply the right file. Placeholders
worth supporting (Bootimus pattern): `{{MAC}}`, `{{HOSTNAME}}`,
`{{IP}}`, `{{SERVER_ADDR}}`, `{{IMAGE_FILENAME}}`, substituted
serve-side per request.
### 5. Wake-on-LAN trigger
A natural pair with per-MAC host bindings: bind a MAC to an image,
then click "Wake & Image" to send the magic packet and let OpenPXE
do the rest. Implementation is small (`udp/9` broadcast, magic packet
construction) but it makes the bound-host workflow feel instant.
### 6. Distro profile manifest
Today, distro detection lives as Rust match arms in `introspect.rs`
and the kernel cmdline templates live in `store.rs`. Bootimus extracts
this into a JSON manifest that ships embedded in the binary AND is
overridable by the operator at runtime — so a new distro can be added
without rebuilding the container. Worth porting; it'd let community
contributions land as PRs to a single JSON file.
### 7. Syslog receiver
`smee` ships one. The use case: WinPE / Linux installers can be
configured to syslog over the network to the PXE server; if we have
an endpoint and a place in the UI to view per-client diagnostics,
post-mortem on a failed install gets dramatically easier.
### 8. UEFI HTTP Boot validation
Option 60 = `HTTPClient` is wired up in `decide()` already, but
we've never tested it on real firmware. Some Dell + Lenovo UEFIs
prefer it over PXE-via-TFTP. A quick check on a real machine
(disable TFTP boot in firmware, force HTTP boot) and a regression
test would be nice.
## Tier 3 — bigger lifts, only if there's demand
### 9. Pure-Rust SMB server
`smbd` from Samba is ~80 MB of the runtime image. There are pure-Rust
SMB2 server crates (`smbd-server`, `smb-rs`) of varying maturity.
Replacing the dep would slim the image by ~40% and remove the
`CAP_SYS_ADMIN` requirement for SMB. Worth a spike, not necessarily
landable in Phase 6.
### 10. IPv6 / DHCPv6
PXE-over-IPv6 is real (RFC 5970). Some sites are v6-only. Worth
implementing once we know we have one. Until then, IPv4-only is the
right default — flipping the bit on v6 without v6 testing is asking
for silent breakage.
### 11. Multi-replica deployment
The current design assumes one OpenPXE per broadcast domain. Two
proxies on the same L2 will race; the deployment queue is in-memory, etc.
For HA we'd need to:
- Externalize the deployment queue (Redis, etcd) or lean into "the menu is
cheap to refetch if a replica dies";
- Ensure DHCP proxy replies are deterministic so a client always
gets the same answer regardless of which replica replied;
- Document the L2 collision domain story.
This is a large lift and should only happen if someone's actually
asking for it.
### 12. Pi 4 / SBC quirks
Raspberry Pi netboot uses a specific DHCP option-43 vendor field +
TFTP path layout that OpenPXE doesn't currently special-case. There's
a spec; the work is small once we have a Pi to test on.
## What I'd skip
- **A custom DHCP server (not proxy).** The proxy mode is the right
abstraction; full DHCP would need raw sockets + a lot of corner-case
handling for problems no operator wants us to solve.
- **A pluggable backend abstraction à la Tinkerbell.** Tinkerbell does
it because they integrate with k8s CRDs. OpenPXE's "the file system
IS the database" model is simpler and good enough for the target
audience. Don't add a Backend trait until something asks for it.
- **Multiple language UIs.** Bootimus added these in v0.1.62 and the
translations are LLM-generated. Skip until we have real users
asking for non-English.
## Quick wins (could land in a single afternoon)
- Add a Grafana dashboard JSON to `deploy/grafana/` driven off the
new `/metrics` endpoint.
- A `openpxe bench` subcommand that runs a 10-second internal load
test (synthetic queue joins) so an operator can sanity-check tuning.
- Ship a basic `docker-compose.yml` for the Unraid path that demos
the new themes / progress widget.
- Generate a printable single-page operator runbook from the README
+ architecture.md (e.g. `cargo xtask runbook`).
+29 -29
View File
@@ -1,4 +1,4 @@
# PXEForge architecture
# OpenPXE architecture
## Protocol stack
@@ -8,7 +8,7 @@ Client firmware PXE ROM
│ DHCPDISCOVER (UDP/67 broadcast, option 60 "PXEClient", option 93 arch)
┌─────────────────────────────────────────────────────────────────────────┐
PXEForge
OpenPXE
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ DHCP proxy │ │ TFTP server │ │ HTTP server (axum) │ │
@@ -33,7 +33,7 @@ Client runs iPXE
│ DHCPDISCOVER with option 77 "iPXE"
PXEForge sees user-class "iPXE" → replies with HTTP URL: /boot.ipxe
OpenPXE sees user-class "iPXE" → replies with HTTP URL: /boot.ipxe
│ HTTP GET /boot.ipxe (iPXE menu, auto-generated from IsoStore)
@@ -48,14 +48,14 @@ Kernel boots with distro-specific args pointing back at /iso/<id>.iso
| Crate | Responsibility |
|---------------------|-------------------------------------------------------------------|
| `pxeforge-core` | Shared types: `Config`, `ClientArch`, `FirmwareClass`, `ClientRegistry` |
| `pxeforge-ipxe-assets` | Embeds bundled iPXE binaries via `rust-embed` |
| `pxeforge-iso-store` | On-disk ISO store, introspection, boot-entry generation |
| `pxeforge-dhcp-proxy` | UDP listener + `dhcproto` reply builder; pure `decide()` unit-testable |
| `pxeforge-tftp` | RFC 1350 + OACK (blksize / tsize / windowsize). Serves only embedded assets — no filesystem |
| `pxeforge-http-api` | `axum` router: web UI, API, iPXE script generation, ISO streaming |
| `pxeforge-webui` | Single `index.html` served as static string |
| `pxeforge` (bin) | Wires everything together, runs the three servers concurrently |
| `openpxe-core` | Shared types: `Config`, `ClientArch`, `FirmwareClass`, `ClientRegistry` |
| `openpxe-ipxe-assets` | Embeds bundled iPXE binaries via `rust-embed` |
| `openpxe-iso-store` | On-disk ISO store, introspection, boot-entry generation |
| `openpxe-dhcp-proxy` | UDP listener + `dhcproto` reply builder; pure `decide()` unit-testable |
| `openpxe-tftp` | RFC 1350 + OACK (blksize / tsize / windowsize). Serves only embedded assets — no filesystem |
| `openpxe-http-api` | `axum` router: web UI, API, iPXE script generation, ISO streaming |
| `openpxe-webui` | Single `index.html` served as static string |
| `openpxe` (bin) | Wires everything together, runs the three servers concurrently |
## Key decisions and why
@@ -75,11 +75,11 @@ so plain `SOCK_DGRAM` is enough.
1. Firmware PXE ROM sends DHCPDISCOVER with option 60 = `PXEClient`,
option 93 = arch.
2. PXEForge replies with TFTP server + arch-specific iPXE binary
2. OpenPXE replies with TFTP server + arch-specific iPXE binary
(`undionly.kpxe` for Legacy BIOS, `snponly.efi` for x86_64 UEFI, etc.).
3. Client TFTPs the iPXE binary and runs it.
4. iPXE does its own DHCP, setting option 77 (user-class) to `iPXE`.
5. PXEForge detects the user-class and this time replies with an HTTP URL
5. OpenPXE detects the user-class and this time replies with an HTTP URL
in option 67 pointing at `/boot.ipxe`.
6. iPXE fetches and executes that script, which chains the selected OS.
@@ -105,7 +105,7 @@ Whatever we do for Windows, we never:
- instruct users to enable `bcdedit /set testsigning on`
- install any certificate into the target's root/trust store
iVentoy's `httpdisk.sys` approach broke this rule. PXEForge doesn't.
iVentoy's `httpdisk.sys` approach broke this rule. OpenPXE doesn't.
### Linux ISO boot uses kernel+initrd extraction, not sanboot
@@ -157,13 +157,13 @@ release:
root-owned" problem that breaks ISO upload on standard Docker hosts.
- `/healthz` and `/readyz` split from `/api/status` — readyz fails if no
iPXE binaries are bundled, giving K8s probes a real signal.
- Startup aborts with a clear error if `PXEFORGE_PUBLIC_IP` can't be
- Startup aborts with a clear error if `OPENPXE_PUBLIC_IP` can't be
auto-detected (no more silent `127.0.0.1` advertisement).
- `scripts/fetch-ipxe.sh` fails non-zero if zero binaries download; the
Dockerfile uses arch-scoped paths (`x86_64-efi/snponly.efi` etc.).
**Windows boot plumbing** (new):
- `pxeforge-iso-store::smb::SmbManager` supervises `smbd` on the Windows
- `openpxe-iso-store::smb::SmbManager` supervises `smbd` on the Windows
toggle: `start` → spawn + write `smb.conf`; `reconcile` → SIGHUP on
share changes; `stop` → SIGTERM. `SmbState` surfaced to the UI for
visibility.
@@ -177,32 +177,32 @@ release:
- ISO sizes in menu labels (`[ 4376 MB]`), iVentoy format.
- `Reboot Computer` + `Exit and continue BIOS boot` in Tools menu.
- Number-key hotkeys (1..9) on boot entries, letter hotkeys on tools.
- Clients tab cross-joins the gate queue so an operator sees "at gate #2"
- Clients tab cross-joins the deployment queue so an operator sees "in queue #2"
or "assigned: ubuntu-linux" status inline.
**Developer ergonomics** (new):
- `pxeforge seed --from <path>` CLI to import ISOs from a directory.
- `openpxe seed --from <path>` CLI to import ISOs from a directory.
Same pipeline as web upload (slug, sha256, introspection, boot-entry).
- `docker-compose.yml` with `pxeforge` (host network, real PXE) and
`pxeforge-dev` (published ports, DHCP disabled, for API testing).
- `docker-compose.yml` with `openpxe` (host network, real PXE) and
`openpxe-dev` (published ports, DHCP disabled, for API testing).
**API cleanliness**:
- All timestamps now serialized as RFC 3339 strings (the `time` crate's
default 9-tuple broke browser `Date` parsing).
- Gate poll retains assignment until the operator releases it; if the
- Queue poll retains assignment until the operator releases it; if the
client's chain fails, it reuses the assignment instead of falling back
to the menu.
## Phase 4 — UI restructure + remote storage
The web UI was rebuilt around six tabs (Dashboard / Network / Forge Gate /
The web UI was rebuilt around six tabs (Dashboard / Network / Queue /
Storage / Terminal / About) inspired by the iVentoy layout the user
attached and Netbox Labs's compact-card pattern. The old hierarchical
"Monitoring / Content / Configuration" sidebar grouping is gone — every
tab is one click from the brand bar.
**NFS share manager** (`crates/iso-store/src/nfs.rs`):
- Operators add a remote share via Storage → NFS shares; PXEForge mounts
- Operators add a remote share via Storage → NFS shares; OpenPXE mounts
it under `<work_dir>/nfs/<id>/` and walks it for `*.iso` files.
- Each ISO found is registered with `IsoStore::register_external` using
a new `IsoSource::Nfs { mount_id, relative_path }` variant. The store
@@ -227,7 +227,7 @@ tab is one click from the brand bar.
followed by live updates. Slow clients see a `lagged` event rather
than dropping the stream.
- `/api/terminal` accepts a single command line and dispatches to a
whitelist (`status`, `isos`, `clients`, `gate {list,assign,release}`,
whitelist (`status`, `isos`, `clients`, `queue {list,assign,release}`,
`nfs {list,mount,unmount,scan}`, `smb {status,start,stop,reload}`,
`log {clear,tail}`). Output is mirrored onto the LogBus so reading the
live tail tells the same story as scrolling the terminal pane.
@@ -240,7 +240,7 @@ tab is one click from the brand bar.
read-only by design — silently changing the public IP on a hot UI
would break PXE for every client mid-boot.
- The only writable network field is `dns_server`, an optional
informational hint stored in `Settings`. PXEForge does not run a DNS
informational hint stored in `Settings`. OpenPXE does not run a DNS
server; the field exists so operators don't have to dig out the
upstream DNS at 3 AM.
@@ -252,7 +252,7 @@ tab is one click from the brand bar.
warning.
- Dashboard surfaces a "Images that won't boot" panel reusing the same
predicate, so the operator sees the problem before they pick the ISO
in the gate.
in the queue.
- Streaming uploads are already in place via axum multipart; the v0.1.62
fix to "502 on big upload" doesn't apply.
@@ -260,7 +260,7 @@ tab is one click from the brand bar.
**Per-MAC host bindings** (`crates/core/src/host_bindings.rs`):
- New `HostBindings` registry maps a MAC → preferred `BootEntry::id`
(or one of the reserved menu shortcuts `_local`, `_gate`,
(or one of the reserved menu shortcuts (`_local`, `_queue``,
`_tools_menu`).
- Persisted to `<work_dir>/hosts.json`. Like `SettingsStore`, in-memory
is authoritative — disk corruption falls back to empty rather than
@@ -278,7 +278,7 @@ tab is one click from the brand bar.
- Counters: DHCP replies (per arch label), DHCP declined, TFTP
transfers (per status label), TFTP bytes, HTTP requests (per route
label).
- Gauges: ISO count, client count, gate count, gate-imaging count,
- Gauges: ISO count, client count, queue count, queue-imaging count,
NFS active mounts, uptime, build info.
- Exposed as plain Prometheus text at `/metrics`.
@@ -295,7 +295,7 @@ other idiom fixes.
- New SVG logos: a refined anvil (`logo.svg`) and a SMIL-animated
`anvil-forge.svg` (rising sparks + pulsing underglow). Pure SVG —
no GIFs, no CSS keyframes for the sparks.
- "Forge progress" widget on the Dashboard and Forge Gate: animated
- "Forge progress" widget on the Dashboard and Queue: animated
anvil paired with a `linear-gradient(warn → accent)` progress bar
with a moving sheen. Goes idle (greyscale, no sheen) at zero
imaging load.
+403
View File
@@ -0,0 +1,403 @@
# Runbook: Boot a Linux machine from an ISO over the network
End-to-end walkthrough: spin up OpenPXE, load an Ubuntu (or any
Linux) ISO into it, target a specific bare-metal or VM client by its
MAC address, and have that machine PXE-boot the installer over the
LAN — no USB stick, no console babysitting.
This runbook assumes:
- You have **one Linux host** to run the OpenPXE container (any
distro with Docker / Podman; 2 GB RAM, ~50 GB disk for the ISO
library).
- That host sits on the **same broadcast domain / VLAN** as the
client you want to boot. PXE is L2-broadcast — routed/VLANd
networks need a DHCP relay and are out of scope here.
- An **existing DHCP server** is already handing out IP leases on
that VLAN (your home router, OPNsense, Windows Server, etc.).
OpenPXE runs as a *DHCP proxy* — it never leases IPs, it only
layers the boot information on top of the existing DHCP exchange.
- The target client is configured to **PXE-boot** in BIOS/UEFI
firmware (usually `F12` boot menu → Network, or set as first boot
device).
If those dont hold, stop and read [troubleshooting.md](troubleshooting.md)
or [docs/architecture.md](../docs/architecture.md) first.
---
## 0. Pick your hosts LAN IP
You need the IPv4 address OpenPXE will advertise to clients. From
the host:
```bash
ip -4 -o addr show | awk '{print $2, $4}'
```
Pick the address on the interface that faces the PXE VLAN — for
example `10.0.0.5/24` on `eno1`. From here on we call it
`PXE_HOST_IP`.
> **Why this matters.** Every URL handed to clients (TFTP server,
> iPXE chain URL, ISO URL) is built from this IP. If OpenPXE
> auto-detects the wrong interface or loopback, clients will fetch
> from an unreachable address and silently fail. The startup will
> *fail loudly* if it can only auto-detect a loopback address.
---
## 1. Run OpenPXE
The MVP path is a single `docker run` against the published image,
with `--network host` so the container can see DHCP broadcasts on
the LAN.
```bash
mkdir -p ~/openpxe/isos ~/openpxe/work
docker run -d --name openpxe \
--restart unless-stopped \
--network host \
-e OPENPXE_PUBLIC_IP=10.0.0.5 \
-e OPENPXE_DHCP_MODE=proxy \
-v ~/openpxe/isos:/var/lib/openpxe/isos \
-v ~/openpxe/work:/var/lib/openpxe/work \
ghcr.io/YOUR-ORG/openpxe:0.2.0
```
Substitute your `OPENPXE_PUBLIC_IP`, of course. If youre building
from this repo instead of pulling, see the
[README quick start](../README.md#quick-start--mvp-container-recommended).
### Verify its alive
```bash
curl -fsS http://10.0.0.5/healthz # → 200 ok
curl -fsS http://10.0.0.5/readyz # → 200 ready (iPXE binaries present)
curl -fsS http://10.0.0.5/api/status | jq .
```
If `/readyz` is **not** 200, your container is missing iPXE binaries.
Fix that before going further — clients have nothing to boot
otherwise. See [README — Container health probes](../README.md#container-health-probes).
### Check the listening ports
OpenPXE holds three privileged UDP/TCP ports. From another shell on
the host:
```bash
sudo ss -lnup | grep -E ':(67|69|4011)\b' # DHCP proxy + TFTP
sudo ss -lntp | grep ':80\b' # HTTP UI / boot scripts
```
All four should be present. If port 67 is taken by `dnsmasq` or the
hosts own DHCP, stop that service or run OpenPXE on a separate box —
two listeners on `:67` will fight.
---
## 2. Load the ISO
Two options. Pick one.
### 2a. Web UI upload (recommended for one-offs)
1. Open `http://10.0.0.5/` in a browser.
2. Sidebar → **Storage**.
3. Click **Upload ISO**, pick e.g. `ubuntu-24.04.1-live-server-amd64.iso`.
4. Wait for upload + introspection. The row turns into a card showing:
- Distro family (`debian_ubuntu`)
- Volume label
- Detected kernel/initrd paths (`/casper/vmlinuz`, `/casper/initrd`)
- File size and SHA-256
Big ISOs stream — there is no 2 GB limit, but expect upload to be
throttled by your browser ↔ host link. The UI shows a progress bar; the
animated anvil on the Dashboard tab fires up while imaging is in
flight.
### 2b. Bulk seed from a directory (recommended for fresh deploys / CI)
If you already have a folder of ISOs on the host, skip the browser:
```bash
# Dry run first — see what would be imported, no writes:
docker exec openpxe openpxe seed \
--from /seed \
--dry-run
# For real, mount the source dir read-only into the container:
docker run --rm \
-v /my/iso-library:/seed:ro \
-v ~/openpxe/isos:/var/lib/openpxe/isos \
-v ~/openpxe/work:/var/lib/openpxe/work \
-e OPENPXE_PUBLIC_IP=10.0.0.5 \
ghcr.io/YOUR-ORG/openpxe:0.2.0 seed --from /seed
```
Each `*.iso` in `/seed` runs through the same upload pipeline as the
web UI: copy → introspection → boot-entry generation → metadata
sidecar. Re-running is idempotent.
### Confirm the ISO is registered
```bash
curl -fsS http://10.0.0.5/api/isos | jq '.[] | {id, name, family, size}'
```
You should see something like:
```json
{
"id": "ubuntu-24-04-1-live-server-amd64",
"name": "ubuntu-24.04.1-live-server-amd64.iso",
"family": "debian_ubuntu",
"size": 2748000000
}
```
The `id` is the **slug**. Remember it — youll bind a MAC to it in
the next step.
---
## 3. Find the target machines MAC address
You need the MAC of the **NIC that will PXE**, not the OSs
loopback or wifi.
### 3a. From the target itself (if its already running an OS)
```bash
ip -o link | awk '/ether/ {print $2, $17}' # Linux
```
Pick the line for the wired NIC plugged into the PXE VLAN.
### 3b. From the firmware (if its a fresh box)
Most BIOS/UEFI screens display the NIC MAC during the network-boot
attempt — usually as `MAC: AA-BB-CC-DD-EE-FF` flashing on the splash
right before "PXE-E53: No boot filename received". Write it down.
### 3c. By letting it boot once and watching OpenPXE
Easiest if the box is in front of you:
1. Power on, hit `F12`, pick **Network boot**.
2. Without any binding configured, the client will land on the
OpenPXE menu (Default / Installers / Tools / Queued Deployment).
3. Dont pick anything. On your laptop:
```bash
curl -fsS http://10.0.0.5/api/clients | jq .
```
4. The most-recent entry is your target. Copy its `mac`.
From here on we call this MAC `TARGET_MAC` (e.g. `aa:bb:cc:dd:ee:ff`).
Hyphens vs colons, upper vs lower case — OpenPXE normalizes both.
---
## 4. Pin that machine to the Ubuntu ISO
This is the **per-MAC host binding**. With it set, the client wont
see the menu at all — it goes straight to the bound boot entry,
Tinkerbell-style.
### 4a. Via the web UI
1. Sidebar → **Hosts**.
2. **Add binding**:
- **MAC**: `aa:bb:cc:dd:ee:ff`
- **Target**: pick `ubuntu-24-04-1-live-server-amd64` from the dropdown.
- **Label**: free-form, e.g. `lab-rack3-node07`.
3. Save.
### 4b. Via the API
```bash
curl -fsS -X POST http://10.0.0.5/api/hosts \
-H 'content-type: application/json' \
-d '{
"mac": "aa:bb:cc:dd:ee:ff",
"target": "ubuntu-24-04-1-live-server-amd64",
"label": "lab-rack3-node07"
}' | jq .
```
The binding is persisted to `~/openpxe/work/hosts.json` and survives
container restart.
### Confirm
```bash
curl -fsS http://10.0.0.5/api/hosts | jq '.[] | select(.mac=="aa:bb:cc:dd:ee:ff")'
```
You should see your entry with `created_at` and `updated_at`
timestamps.
---
## 5. Trigger the network boot on the target
Now actually boot the machine.
### 5a. Boot order
In firmware setup, set the wired NIC as the **first** boot device
(or hold `F12` / `F9` / `Esc` — vendor-specific — to pick "Network
Boot" interactively).
### 5b. What you should see on the target screen
In order, with timing:
| Stage | Approximate duration | What appears |
|-------|---------------------:|--------------|
| Firmware DHCPDISCOVER | ~1 s | `Start PXE over IPv4` / `Station IP address …` |
| TFTP iPXE binary fetch | ~1 s | `TFTP… snponly.efi` (or `undionly.kpxe` for legacy BIOS) |
| iPXE banner | ~1 s | The blue iPXE splash, version string |
| iPXE second-stage DHCP | ~1 s | `Configuring (net0 …)` then `ok` |
| HTTP boot script fetch | <1 s | `http://10.0.0.5/boot.ipxe?mac=…` |
| Per-MAC chain | <1 s | `OpenPXE: per-MAC binding -> ubuntu-24-04-1-…` |
| Kernel + initrd HTTP | 530 s | Two 200-OK fetches against `/iso/<id>/casper/vmlinuz` and `…/initrd` |
| Kernel boot | 510 s | Kernel banner, then the Ubuntu/cloud-init splash |
| Installer comes up | 3060 s | The distros normal Live/installer environment |
If everything works, youre looking at the Ubuntu Server installer
welcome screen end-to-end **without ever touching a USB stick**.
### 5c. Watch it from the server
In a third shell, tail the live log:
```bash
curl -N http://10.0.0.5/api/log/stream
```
Youll see each protocol step as it happens:
```
INFO openpxe::dhcp: reply mac=aa:bb:cc:dd:ee:ff arch=X8664Uefi target=tftp/snponly.efi
INFO openpxe::tftp: RRQ snponly.efi blksize=1468 windowsize=8 → 982 KiB in 412 ms
INFO openpxe::dhcp: reply mac=aa:bb:cc:dd:ee:ff (iPXE) target=http/boot.ipxe
INFO openpxe::http: GET /boot.ipxe?mac=aa:bb:cc:dd:ee:ff → host binding hit
INFO openpxe::http: GET /iso/ubuntu-…/casper/vmlinuz Range=bytes=0- 200 OK 14 MiB
INFO openpxe::http: GET /iso/ubuntu-…/casper/initrd Range=bytes=0- 200 OK 75 MiB
```
The **Terminal** tab in the web UI shows the same thing live, plus a
short whitelisted command palette (`status`, `clients`, `gate`,
`hosts`, `log`).
### 5d. Internet-side ISO sources
The runbook title says “via the internet” — the **client** itself
boots from your LAN, but the underlying ISO can come from anywhere
your *host* can reach:
- **Direct upload** from a remote workstation via the web UI (HTTPS
reverse-proxied if you put OpenPXE behind nginx/Caddy).
- **NFS mount** of a remote share — Sidebar → **Storage****NFS**
`nfs://files.lab.example.com/exports/isos`. Mounted ISOs show up in
the same list and are PXE-bootable directly without copying.
- **Pre-seed** from a CI job that `curl`s a vendor mirror and runs
`openpxe seed --from`.
OpenPXE itself never reaches out to the internet at boot time — all
client traffic stays on the LAN, served from the host.
---
## 6. After the install
Once Ubuntu has finished installing to the targets disk, you want
the next reboot to come up off the new local disk, **not** PXE
again. Two ways:
### 6a. One-shot — release the binding
```bash
curl -fsS -X DELETE http://10.0.0.5/api/hosts/aa:bb:cc:dd:ee:ff
```
Without a binding, the client either gets the menu (BIOS still set
to PXE first) or boots local disk normally.
### 6b. Permanent — pin to local disk
Re-bind to the reserved local-boot target:
```bash
curl -fsS -X POST http://10.0.0.5/api/hosts \
-H 'content-type: application/json' \
-d '{ "mac": "aa:bb:cc:dd:ee:ff", "target": "_local", "label": "lab-rack3-node07 (installed)" }'
```
Now if anyone hits `F12 → Network` by accident, OpenPXE replies
with a script that says *"chain back to local HDD"* and the box
boots its real OS instead of re-imaging itself. This is the safest
default for production hardware.
---
## 7. Re-imaging — the “Queued Deployment” flow
Different scenario: you have **a rack of 30 servers** to image
identically, all at once. Dont bind 30 MACs by hand. Use the gate.
1. **Dont** create host bindings.
2. PXE-boot every machine. They land on the menu.
3. On each: select **Queued Deployment**. They get position #1, #2,
…, #30 and start long-polling.
4. In the UI: **Forge Gate** tab shows all 30 lined up. Pick the
ISO, click **Assign to all waiting**.
5. Every clients open long-poll wakes up at the same instant and
chains the same boot script. They all start imaging
simultaneously — the “horse race gate” opens.
The animated anvil widget on the Dashboard runs while any client is
still in the kernel-fetch phase.
---
## Cheat sheet
| Goal | Command |
|------|---------|
| Health check | `curl http://$IP/healthz` |
| List ISOs | `curl http://$IP/api/isos \| jq .` |
| List clients seen | `curl http://$IP/api/clients \| jq .` |
| Bind MAC → ISO | `POST /api/hosts` with `{mac,target,label}` |
| Bind MAC → local disk | same with `target=_local` |
| Release binding | `DELETE /api/hosts/<mac>` |
| Live log | `curl -N http://$IP/api/log/stream` |
| Prometheus metrics | `curl http://$IP/metrics` |
| Bulk import folder | `openpxe seed --from /path` |
---
## Where to look when things break
- **Client gets `PXE-E53: No boot filename received`** — DHCP proxy
isnt replying. Check `:67` is bound (`ss -lnup`), check
`--network host`, check the host firewall on UDP 67/69/4011.
- **iPXE shows `No more network devices`** — firmware NIC isnt in
PXE mode, or VLAN tagging is wrong.
- **iPXE prints `Connection timed out (http://…)`**`OPENPXE_PUBLIC_IP`
is wrong. Clients cant reach that IP. Check `/api/status`
`public_base_url` and `ping` it from the client subnet.
- **Kernel panics during initrd load** — corrupt ISO upload. Check
`/api/isos`, compare the SHA-256 to the vendors, re-upload.
- **Boot menu shows but the bound entry doesnt fire** — the binding
target slug doesnt match any ISO `id`. Recheck
`GET /api/hosts` against `GET /api/isos`. The binding falls back
to the menu on miss (by design — never lock a client out).
- **General confusion** — Terminal tab → `status`, then `log`. That
tells you what protocol stages have run and which havent.
For deeper protocol-level debugging, see
[docs/architecture.md](../docs/architecture.md).
+9 -9
View File
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
# build-and-publish-unraid.sh — one-shot: clone PXEForge, build the image,
# build-and-publish-unraid.sh — one-shot: clone OpenPXE, build the image,
# push it to your local Gitea container registry. Run this ON the Unraid
# box (or any host that can reach Gitea on http://localhost:3000 or its
# LAN IP). No Cloudflare in the way; the proxy doesn't matter for this
@@ -10,31 +10,31 @@
# GITEA_HOST default: localhost:3000 (use 192.168.1.49:3000 if
# you're on the LAN but not on the Unraid host)
# GITEA_OWNER default: mward4
# GITEA_REPO default: PXEForge
# GITEA_REPO default: OpenPXE
# IMAGE_TAG default: 0.1.0 (also tagged :latest)
# PLATFORM default: linux/amd64 (Unraid is x86_64)
# WORKDIR default: /tmp/pxeforge-build (deleted on success)
# WORKDIR default: /tmp/openpxe-build (deleted on success)
#
# What it does:
# 1. git clone <gitea>/mward4/PXEForge.git into WORKDIR
# 1. git clone <gitea>/mward4/OpenPXE.git into WORKDIR
# 2. fetch iPXE binaries (scripts/fetch-ipxe.sh)
# 3. docker build deploy/docker/Dockerfile -> pxeforge:$TAG (and :latest)
# 3. docker build deploy/docker/Dockerfile -> openpxe:$TAG (and :latest)
# 4. docker login to GITEA_HOST using the token
# 5. docker push to <gitea>/<owner>/pxeforge:<tag> and :latest
# 5. docker push to <gitea>/<owner>/openpxe:<tag> and :latest
# 6. docker logout, scrub creds, clean WORKDIR
#
# After this, on any Unraid Docker template, set:
# Repository: <gitea>/mward4/pxeforge:0.1.0 (or :latest)
# Repository: <gitea>/mward4/openpxe:0.1.0 (or :latest)
# Network: host (DHCP/TFTP need raw L2)
set -euo pipefail
GITEA_HOST=${GITEA_HOST:-localhost:3000}
GITEA_OWNER=${GITEA_OWNER:-mward4}
GITEA_REPO=${GITEA_REPO:-PXEForge}
GITEA_REPO=${GITEA_REPO:-OpenPXE}
IMAGE_TAG=${IMAGE_TAG:-0.1.0}
PLATFORM=${PLATFORM:-linux/amd64}
WORKDIR=${WORKDIR:-/tmp/pxeforge-build}
WORKDIR=${WORKDIR:-/tmp/openpxe-build}
# Lowercase the image name — OCI distribution rejects uppercase paths.
IMAGE_NAME="$(printf '%s' "$GITEA_REPO" | tr '[:upper:]' '[:lower:]')"
+1 -1
View File
@@ -1,7 +1,7 @@
#!/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.
# OpenPXE's arch mapping expects.
#
# Why not build from source?
# - Building iPXE requires the toolchain + several megabytes of source, and