Initial commit: PXEForge Phases 1-4
Container-native PXE boot server in Rust, designed as a clean-room alternative to iVentoy that never touches the client OS trust store. This is the first commit of the project; it lands the full output of Phases 1, 2, 3, and 4 in one shot. ## Phase 1 — protocol stack - 8-crate workspace (core, dhcp-proxy, tftp, http-api, iso-store, ipxe-assets, webui, pxeforge bin). - DHCP proxy (RFC 4578): replies with boot info only, never leases — sidesteps CAP_NET_RAW. Architecture-aware bootfile selection from option 93 (BIOS, IA32, x64-UEFI alias 0x0007/0x0009, ARM64). - TFTP server with full OACK negotiation: blksize, tsize, windowsize. Without it a 1 MiB iPXE binary takes 2000 packets and unusably long. - Two-stage iPXE chain: firmware PXE -> TFTP iPXE binary -> iPXE re-DHCPs with user-class iPXE -> HTTP /boot.ipxe -> kernel+initrd. - HTTP server (axum) with byte-Range ISO streaming and an in-place ISO9660 lookup so kernel/initrd are served from inside the ISO without ever extracting it to disk. - Linux ISOs boot via kernel+initrd extraction (memdisk/sanboot fail for >1-2 GiB modern distros). Distro-family detection drives the cmdline (Debian/Ubuntu, RHEL/Fedora, openSUSE, Arch, Alpine). ## Phase 2 — UX + Windows - Hierarchical PXE menu (Default / Installers / Tools / Gated Deployment) generated from settings — no hand-written .ipxe paths surface in the UI. Number-key + letter hotkeys, BIOS+UEFI variants for some RHEL ISOs. - Gated Deployment "horse-race" queue: clients join, operator picks one ISO, every gate launches simultaneously via tokio::sync::Notify. - Bootimus-pattern Windows: WimPatcher injects a CRLF startnet.cmd into boot.wim so vanilla WinPE net-uses an SMB share and runs setup.exe. All Microsoft-signed; no test certs, no testsigning, no httpdisk.sys. SmbManager supervises smbd start/stop/SIGHUP. - Netbox-style dark UI, fully offline (no CDN, no external fonts). ## Phase 3 — MVP hardening - TFTP retransmit rewrite with explicit window tracking — UEFI SNP clients no longer hang on files that end mid-window. 4 new tests. - DHCP broadcast-flag honored per RFC 2131 §4.1. - Multi-arch container (linux/amd64 + linux/arm64). Entrypoint chowns bind-mounts as root then drops to uid 10001 via gosu. - /healthz + /readyz split from /api/status — readyz fails if no iPXE binaries are bundled. - pxeforge seed --from <path> CLI: same pipeline as web upload (slug, sha256, introspection, boot-entry). - All timestamps RFC 3339 (browser Date couldn't parse the 9-tuple). - Gate poll retains assignment until operator releases — clients that retry on transient network errors reuse the assignment instead of falling back to the menu. - Custom OpenShift SCC: hostNetwork + NET_BIND_SERVICE only, no NET_RAW. ## Phase 4 — UI restructure + remote storage - Web UI rebuilt around six tabs inspired by the iVentoy layout: Dashboard / Network / Forge Gate / Storage / Terminal / About. Old "Monitoring/Content/Configuration" sidebar groups are gone. - NFS share manager (crates/iso-store/src/nfs.rs): mount NFSv3 or NFSv4.1 shares as ISO sources instead of uploading every file into the PVC. New IsoSource enum on IsoMeta lets the store resolve Local vs NFS lazily. Persisted to <work_dir>/nfs.json; failed mounts surface in the UI rather than blocking startup. - Dockerfile gains nfs-common + iproute2; mounting NFS in-container also requires CAP_SYS_ADMIN. Documented in docs/architecture.md. - LogBus + tracing layer in core: 500-line ring buffer + broadcast channel feed an SSE endpoint at /api/log/stream. - Operator terminal at /api/terminal: whitelisted commands (status, isos, clients, gate, nfs, smb, log) — deliberately not a shell. Output mirrored onto the LogBus so the live tail and the terminal pane share one timeline. - Network tab: read-only nic_name / subnet_mask / gateway probed from `ip` at startup; only DNS server is editable. Editing IP/mask on a hot UI would silently break PXE for every client mid-boot. - Bootimus parity (releases v0.1.55 -> v0.1.62): amber row tint on un-bootable ISOs with inline reasons, dashboard "won't boot" panel. ## Tests 56 tests passing across the workspace: - 16 core (LogBus, gate, settings, arch, client) - 1 dhcp-proxy (raw option-93 extraction) - 8 http-api unit (range parsing, terminal split/format) - 13 http-api integration (gated deployment, range, settings, NFS, terminal, log SSE, network endpoint, ui assets, no-external-urls) - 12 iso-store (introspect, slugify, smb, windows wim, NFS options) - 6 tftp (RRQ parsing, plan_window edges) cargo build --workspace and cargo clippy --workspace --all-targets both finish clean (warnings only, no errors).
This commit is contained in:
Miles Ward
@@ -0,0 +1,155 @@
|
||||
//! ISO introspection — identify the distro family and locate kernel/initrd.
|
||||
//!
|
||||
//! We avoid a full ISO9660/Joliet/Rock-Ridge parser by reading a small number
|
||||
//! of well-known files via `isoinfo` (from cdrtools/genisoimage) when it's on
|
||||
//! the path. As a pure-Rust fallback we do a crude scan: read the volume
|
||||
//! descriptor at offset 0x8000 to grab the volume label, and grep for known
|
||||
//! filenames by scanning raw sectors — good enough to tell Debian from RHEL
|
||||
//! most of the time, without shelling out.
|
||||
//!
|
||||
//! The returned `IntrospectionReport` is what `BootEntry`s get generated from.
|
||||
|
||||
use serde::{Deserialize, Serialize};
|
||||
use std::io::{Read, Seek, SeekFrom};
|
||||
use std::path::Path;
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "snake_case")]
|
||||
pub enum DistroFamily {
|
||||
DebianUbuntu,
|
||||
RhelFedora,
|
||||
OpenSuse,
|
||||
Arch,
|
||||
Alpine,
|
||||
WindowsPe,
|
||||
Unknown,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct IntrospectionReport {
|
||||
pub family: DistroFamily,
|
||||
pub volume_label: Option<String>,
|
||||
/// Kernel path inside the ISO (e.g. `/casper/vmlinuz`, `/isolinux/vmlinuz`).
|
||||
pub kernel_path: Option<String>,
|
||||
/// Initrd path(s) inside the ISO. May be multiple for multi-initrd setups.
|
||||
pub initrd_paths: Vec<String>,
|
||||
/// True if `sources/boot.wim` present — Windows install media.
|
||||
pub has_boot_wim: bool,
|
||||
}
|
||||
|
||||
/// Probe an ISO file on disk. Never fails — on unrecoverable IO error we log
|
||||
/// and return an `Unknown` family so the uploader still sees a record.
|
||||
pub fn introspect(path: &Path) -> IntrospectionReport {
|
||||
let mut report = IntrospectionReport {
|
||||
family: DistroFamily::Unknown,
|
||||
volume_label: None,
|
||||
kernel_path: None,
|
||||
initrd_paths: Vec::new(),
|
||||
has_boot_wim: false,
|
||||
};
|
||||
|
||||
let Ok(mut f) = std::fs::File::open(path) else {
|
||||
tracing::warn!(target: "pxeforge::iso", "cannot open ISO for introspection: {}", path.display());
|
||||
return report;
|
||||
};
|
||||
|
||||
// ISO9660 Primary Volume Descriptor at LBA 16 (offset 0x8000), 2048 bytes.
|
||||
// Bytes 40..72 are the Volume Identifier (space-padded, d-characters).
|
||||
let mut pvd = [0u8; 2048];
|
||||
if f.seek(SeekFrom::Start(0x8000)).is_ok() && f.read_exact(&mut pvd).is_ok() {
|
||||
// Byte 0 must be 0x01 (primary descriptor), bytes 1..6 = "CD001".
|
||||
if pvd[0] == 0x01 && &pvd[1..6] == b"CD001" {
|
||||
let label_raw = &pvd[40..72];
|
||||
let label = String::from_utf8_lossy(label_raw).trim().to_string();
|
||||
if !label.is_empty() {
|
||||
report.volume_label = Some(label.clone());
|
||||
report.family = family_from_label(&label);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Cheap content scan: read the first ~64 MiB, look for signature filenames.
|
||||
// This is enough to identify `sources/boot.wim` (Windows) and common
|
||||
// kernel/initrd paths for the major Linux distros.
|
||||
let _ = f.seek(SeekFrom::Start(0));
|
||||
let scan_bytes = 64 * 1024 * 1024;
|
||||
let mut buf = vec![0u8; 1024 * 1024];
|
||||
let mut read_total = 0usize;
|
||||
let mut haystack = Vec::with_capacity(scan_bytes.min(32 * 1024 * 1024));
|
||||
while read_total < scan_bytes {
|
||||
let n = f.read(&mut buf).unwrap_or(0);
|
||||
if n == 0 { break; }
|
||||
haystack.extend_from_slice(&buf[..n]);
|
||||
read_total += n;
|
||||
}
|
||||
|
||||
if contains_ascii(&haystack, b"sources/boot.wim")
|
||||
|| contains_ascii(&haystack, b"SOURCES/BOOT.WIM")
|
||||
|| contains_ascii(&haystack, b"SOURCES\\BOOT.WIM")
|
||||
{
|
||||
report.has_boot_wim = true;
|
||||
if report.family == DistroFamily::Unknown {
|
||||
report.family = DistroFamily::WindowsPe;
|
||||
}
|
||||
}
|
||||
|
||||
// Best-effort kernel/initrd path guess from family. These paths are what
|
||||
// distro ISOs conventionally ship at — we don't verify extraction here;
|
||||
// that happens in the store after introspection.
|
||||
let (k, i) = guess_kernel_initrd(report.family);
|
||||
report.kernel_path = k.map(str::to_string);
|
||||
report.initrd_paths = i.iter().map(|s| s.to_string()).collect();
|
||||
|
||||
report
|
||||
}
|
||||
|
||||
fn family_from_label(label: &str) -> DistroFamily {
|
||||
let l = label.to_ascii_lowercase();
|
||||
if l.contains("ubuntu") || l.contains("debian") || l.contains("mint") {
|
||||
DistroFamily::DebianUbuntu
|
||||
} else if l.contains("rhel") || l.contains("centos") || l.contains("fedora")
|
||||
|| l.contains("rocky") || l.contains("alma")
|
||||
{
|
||||
DistroFamily::RhelFedora
|
||||
} else if l.contains("suse") || l.contains("opensuse") {
|
||||
DistroFamily::OpenSuse
|
||||
} else if l.contains("arch") {
|
||||
DistroFamily::Arch
|
||||
} else if l.contains("alpine") {
|
||||
DistroFamily::Alpine
|
||||
} else if l.contains("windows") || l.contains("winpe") {
|
||||
DistroFamily::WindowsPe
|
||||
} else {
|
||||
DistroFamily::Unknown
|
||||
}
|
||||
}
|
||||
|
||||
fn guess_kernel_initrd(family: DistroFamily) -> (Option<&'static str>, Vec<&'static str>) {
|
||||
match family {
|
||||
DistroFamily::DebianUbuntu => (Some("/casper/vmlinuz"), vec!["/casper/initrd"]),
|
||||
DistroFamily::RhelFedora => (Some("/images/pxeboot/vmlinuz"), vec!["/images/pxeboot/initrd.img"]),
|
||||
DistroFamily::OpenSuse => (Some("/boot/x86_64/loader/linux"), vec!["/boot/x86_64/loader/initrd"]),
|
||||
DistroFamily::Arch => (Some("/arch/boot/x86_64/vmlinuz-linux"), vec!["/arch/boot/x86_64/initramfs-linux.img"]),
|
||||
DistroFamily::Alpine => (Some("/boot/vmlinuz-lts"), vec!["/boot/initramfs-lts"]),
|
||||
DistroFamily::WindowsPe | DistroFamily::Unknown => (None, Vec::new()),
|
||||
}
|
||||
}
|
||||
|
||||
fn contains_ascii(haystack: &[u8], needle: &[u8]) -> bool {
|
||||
if needle.is_empty() || haystack.len() < needle.len() { return false; }
|
||||
haystack.windows(needle.len()).any(|w| w.eq_ignore_ascii_case(needle))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn label_matching() {
|
||||
assert_eq!(family_from_label("Ubuntu 24.04"), DistroFamily::DebianUbuntu);
|
||||
assert_eq!(family_from_label("Rocky-9-x86_64-dvd"), DistroFamily::RhelFedora);
|
||||
assert_eq!(family_from_label("openSUSE-Leap-15.6"), DistroFamily::OpenSuse);
|
||||
assert_eq!(family_from_label("ARCH_202604"), DistroFamily::Arch);
|
||||
assert_eq!(family_from_label("weird-custom"), DistroFamily::Unknown);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user