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,8 @@
|
||||
target
|
||||
data/isos
|
||||
data/work
|
||||
.git
|
||||
.github
|
||||
docs
|
||||
*.md
|
||||
.claude
|
||||
@@ -0,0 +1,97 @@
|
||||
# syntax=docker/dockerfile:1.7
|
||||
#
|
||||
# PXEForge — multi-stage build.
|
||||
#
|
||||
# Design:
|
||||
# - stage `fetch`: runs scripts/fetch-ipxe.sh to pull official iPXE binaries
|
||||
# into assets/ipxe/ so the rust build can embed them via rust-embed.
|
||||
# - stage `build`: compiles the workspace with cargo in release mode.
|
||||
# - stage `runtime`: Debian slim image with setcap for NET_BIND_SERVICE,
|
||||
# running as a non-root UID. No shell in PATH for the service user;
|
||||
# attacker surface is just the pxeforge binary + libc.
|
||||
#
|
||||
# Why not distroless? We want setcap support and easy debug (`oc rsh`).
|
||||
# Debian slim at ~75 MB + binary ~25 MB is fine for a PXE server that
|
||||
# spends most of its life idle.
|
||||
|
||||
ARG RUST_VERSION=1.82
|
||||
|
||||
########## fetch iPXE binaries ##########
|
||||
FROM debian:12-slim AS fetch
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
WORKDIR /src
|
||||
COPY scripts/fetch-ipxe.sh scripts/fetch-ipxe.sh
|
||||
RUN mkdir -p assets/ipxe && bash scripts/fetch-ipxe.sh
|
||||
|
||||
########## build pxeforge ##########
|
||||
FROM rust:${RUST_VERSION}-bookworm AS build
|
||||
WORKDIR /src
|
||||
|
||||
# Copy the whole workspace in one go. We used to do a two-pass "cache-prime
|
||||
# with stubs, then real build" dance for dep-compile reuse; that turned out
|
||||
# to silently serve stale stub binaries when cargo's fingerprint didn't
|
||||
# notice the source swap. A single build is ~1.5 min longer on cold cache
|
||||
# but guarantees the binary reflects the sources we copied.
|
||||
COPY Cargo.toml rust-toolchain.toml ./
|
||||
COPY crates/ crates/
|
||||
COPY --from=fetch /src/assets/ipxe /src/assets/ipxe
|
||||
|
||||
# Cache cargo registry + target across builds. The `--no-edit` touch is
|
||||
# belt-and-suspenders: cargo occasionally misses mtime-only changes on
|
||||
# networked FS; this forces a fingerprint check.
|
||||
RUN --mount=type=cache,target=/usr/local/cargo/registry \
|
||||
--mount=type=cache,target=/src/target,sharing=locked \
|
||||
find crates -name '*.rs' -exec touch {} + && \
|
||||
cargo build --release --bin pxeforge && \
|
||||
cp target/release/pxeforge /pxeforge && \
|
||||
ls -l /pxeforge
|
||||
|
||||
########## runtime ##########
|
||||
FROM debian:12-slim AS runtime
|
||||
RUN apt-get update \
|
||||
&& apt-get install -y --no-install-recommends \
|
||||
ca-certificates libcap2-bin tini gosu iproute2 \
|
||||
wimtools samba nfs-common \
|
||||
&& rm -rf /var/lib/apt/lists/* \
|
||||
&& useradd --system --uid 10001 --home-dir /var/lib/pxeforge --shell /usr/sbin/nologin pxeforge \
|
||||
&& mkdir -p /var/lib/pxeforge/isos /var/lib/pxeforge/work /var/lib/pxeforge/smb \
|
||||
&& chown -R pxeforge:pxeforge /var/lib/pxeforge
|
||||
# Runtime deps explained:
|
||||
# wimtools - provides `wimlib-imagex`, used to inject startnet.cmd into boot.wim.
|
||||
# samba - `smbd` serves extracted Windows install media on :445 for WinPE
|
||||
# to `net use`. Guest read-only, scoped to /var/lib/pxeforge/smb.
|
||||
# nfs-common - provides `mount.nfs` / `mount.nfs4` for the Storage tab's
|
||||
# NFS share manager. Mount also requires the container to run
|
||||
# with CAP_SYS_ADMIN — without it, mount(2) returns EPERM and
|
||||
# the manager surfaces a clear error in the UI instead of
|
||||
# failing silently.
|
||||
# iproute2 - `ip addr` / `ip route` for the auto-detected Network tab
|
||||
# fields (NIC name, subnet mask, default gateway). Tiny,
|
||||
# always available; we don't pull in netlink crates for
|
||||
# this one-shot startup probe.
|
||||
# gosu - drops privileges cleanly from root after the entrypoint fixes
|
||||
# bind-mount ownership (common OpenShift/Docker UX issue).
|
||||
# Windows-specific tools only activate when the WebUI toggle is on.
|
||||
|
||||
COPY --from=build /pxeforge /usr/local/bin/pxeforge
|
||||
COPY deploy/docker/entrypoint.sh /usr/local/bin/entrypoint.sh
|
||||
RUN chmod +x /usr/local/bin/entrypoint.sh
|
||||
|
||||
# Grant the binary the ability to bind <1024 ports as a non-root user.
|
||||
# This is the only capability PXEForge needs for proxy-mode DHCP + TFTP + HTTP.
|
||||
RUN setcap cap_net_bind_service=+ep /usr/local/bin/pxeforge
|
||||
|
||||
# IMPORTANT: we do NOT `USER pxeforge` here. The entrypoint runs as root,
|
||||
# chowns the mounted data dirs, then execs the binary via gosu as pxeforge.
|
||||
# OpenShift ignores USER directives anyway (it injects its own uid), and
|
||||
# there entrypoint.sh's non-root branch just execs directly.
|
||||
WORKDIR /var/lib/pxeforge
|
||||
|
||||
ENV PXEFORGE_ISO_DIR=/var/lib/pxeforge/isos \
|
||||
PXEFORGE_WORK_DIR=/var/lib/pxeforge/work \
|
||||
PXEFORGE_LOG=info,pxeforge=info
|
||||
|
||||
EXPOSE 67/udp 69/udp 4011/udp 80/tcp 445/tcp
|
||||
|
||||
ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/entrypoint.sh"]
|
||||
@@ -0,0 +1,32 @@
|
||||
#!/bin/sh
|
||||
# Container entrypoint that handles the common bind-mount-as-root case.
|
||||
#
|
||||
# When volumes are bind-mounted into the container (e.g. `-v ./data/isos:...`),
|
||||
# they come up owned by the host uid:gid — often root:root. The pxeforge
|
||||
# binary runs as uid 10001 and can't write there. This script, when started
|
||||
# as root, chowns the two state dirs to the pxeforge user, then drops
|
||||
# privileges via gosu before execing the binary.
|
||||
#
|
||||
# If the container is already running as non-root (OpenShift does this via
|
||||
# its own uid assignment from the SCC), we skip the chown attempt and just
|
||||
# exec the binary — OpenShift either preconfigures the volume with fsGroup
|
||||
# or the operator is on their own for permissions.
|
||||
set -e
|
||||
|
||||
PXEFORGE_UID=${PXEFORGE_UID:-10001}
|
||||
PXEFORGE_GID=${PXEFORGE_GID:-10001}
|
||||
DATA_DIRS="/var/lib/pxeforge/isos /var/lib/pxeforge/work /var/lib/pxeforge/smb"
|
||||
|
||||
if [ "$(id -u)" = "0" ]; then
|
||||
for d in $DATA_DIRS; do
|
||||
if [ -d "$d" ]; then
|
||||
chown -R "${PXEFORGE_UID}:${PXEFORGE_GID}" "$d" 2>/dev/null || true
|
||||
fi
|
||||
done
|
||||
# Re-exec ourselves under the pxeforge user so the binary inherits a
|
||||
# clean process environment and a predictable umask.
|
||||
exec gosu "${PXEFORGE_UID}:${PXEFORGE_GID}" /usr/local/bin/pxeforge "$@"
|
||||
fi
|
||||
|
||||
# Non-root: straight exec, no chown attempt.
|
||||
exec /usr/local/bin/pxeforge "$@"
|
||||
Reference in New Issue
Block a user