Repository navigation
Description
Summary
Bluefin Server is currently installable only from physical/virtual media containing the full installer disk image (bluefin-server-installer-<ver>.raw.zst), where the OS DDI payload is embedded on the bluefin-installer-data partition. This makes it impossible to install over PXE/netboot, which is the standard provisioning path for homelabs and bare-metal fleets (the audience that a distroless, k3s-ready server image serves especially well).
This issue proposes two additive, backwards-compatible changes:
- Publish standalone PXE boot artifacts (kernel + installer initrd) as release assets, alongside the existing installer/DDI/UKI artifacts.
- Teach the installer to fetch the DDI over the network when directed to by kernel cmdline parameters, falling back to the existing embedded-partition behavior when absent.
With these in place, any PXE server (I'm building this against jeefy/booty, but it applies equally to netboot.xyz, Matchbox, dnsmasq+iPXE, etc.) can install Bluefin Server unattended over the LAN.
Motivation
- Fleet/homelab provisioning: PXE is how bare-metal Kubernetes nodes get imaged. Bluefin Server + k3s sysext is a natural fit for exactly this workflow, but today each machine needs hand-prepared USB/virtual media.
- No hardware media dance: Machines without easy USB access (rack servers via BMC, thin clients, mini-PC fleets) install straight from the network.
- Everything needed already exists in the build — the kernel and initrd are built today, they're just only consumed by
ukifyand never exported. The DDI is already a standalone release asset. The gap is small.
Current State (as of bce0067d)
Boot artifacts are baked into the UKI only
In elements/oci/bluefin-server-installer.bst (~L252-257), the installer UKI is assembled from a kernel and cpio initrd that are never exported separately:
ukify build \
--linux="/layer/boot/vmlinuz" \
--initrd=/installer.cpio.gz \
--cmdline="systemd.unit=system-install.target console=tty0 console=ttyS0,115200 rw unattended" \
--output=/layer/boot/efi/EFI/BOOT/BOOTX64.EFIPXE (via iPXE/GRUB) needs kernel + initrd as separate fetchable files with a caller-controlled cmdline. Chainloading the published .efi UKI directly is not sufficient because its cmdline is immutable — there is no way to inject a DDI URL (see below), and measured-boot-friendly UKIs are the point, so cmdline injection into the UKI would be the wrong direction anyway.
The installer cannot fetch the DDI over the network
The bluefin-sysinstall wrapper (installer.bst, ~L126-178) reads /proc/cmdline only to detect the unattended flag, and sources the DDI exclusively from the bluefin-installer-data GPT partition:
INSTALLER_PART="$(readlink -f /dev/disk/by-partlabel/bluefin-installer-data 2>/dev/null || true)"Under PXE there is no installer media, therefore no bluefin-installer-data partition, and the install cannot proceed.
Proposal
Part 1: Publish standalone PXE artifacts
Export the two components that already exist at UKI-build time as release assets:
| New asset | Source in build | Purpose |
|---|---|---|
bluefin-server-pxe-vmlinuz-<ver> |
/layer/boot/vmlinuz |
PXE kernel |
bluefin-server-pxe-initrd-<ver>.cpio.gz |
/installer.cpio.gz |
PXE initrd |
Changes:
elements/oci/bluefin-server-installer.bst: copy both files into the export area alongside the UKI.Justfile: newexport-pxerecipe in theinstallergroup..github/workflows/build.yml: upload both to the GitHub Release and include them in the (already GPG-signed)SHA256SUMS— consumers get artifact verification for free.
No new build work: these are byproducts of the existing installer build. The DDI (bluefin-server-ddi-<ver>.raw.zst) is already published, so no change is needed there.
Part 2: Network DDI pull in the installer
Extend bluefin-sysinstall (or better, the systemd-native machinery around it — see Design Discussion) to honor new kernel cmdline parameters:
| Parameter | Required | Behavior |
|---|---|---|
inst.ddi_url=<http(s) url> |
for netboot | Download the (zstd-compressed) DDI instead of reading the embedded partition |
inst.ddi_sha256=<hex> |
recommended | Verify the downloaded DDI before install; abort on mismatch |
inst.target_disk=/dev/... |
optional | Explicit target disk, overriding the current first-writable-disk auto-detection |
Behavior:
- If
inst.ddi_urlis absent → exactly today's behavior (embedded partition). Zero change for existing media users; offline-first design is preserved. - If present → bring up networking (DHCP), fetch the DDI, verify SHA256 if provided, then feed it into the same
systemd-sysinstall/systemd-repartflow the embedded path uses. - Download should stream-decompress (
zstd -d) rather than staging both compressed and decompressed copies in tmpfs, to keep RAM requirements sane. Minimum-RAM guidance should be documented either way. - On any fetch/verification failure: fail loudly to console, do not touch the target disk.
The installer initrd would need networking + fetch tooling present in installer-stack.bst if it isn't already (systemd-networkd DHCP; fetch via importctl/systemd-pull or curl — see below).
Part 3: Documentation
- New
docs/skills/pxe-netboot.md: boot flow, cmdline parameter reference, example iPXE stanza, RAM requirements, troubleshooting (serial console, DHCP). - Update
docs/skills/ddi-installer.mdwith a PXE section and cross-link. - Add PXE/netboot to the
AGENTS.mdskill routing table.
Design Discussion (maintainer input wanted)
1. Fetch mechanism: importctl / systemd-pull vs. curl.
AGENTS.md mandates the installer stay systemd-sysinstall-native with no custom scripting sprawl. systemd-importd's pull machinery (importctl pull-raw / systemd-pull) natively handles HTTP(S) download, zstd decompression, and SHA256SUMS+GPG verification — which matches the project's existing signed-manifest release format exactly. It seems like the most philosophically aligned option, at the cost of shipping importd in the installer initrd. Alternatively a small curl+zstd path in the existing bluefin-sysinstall wrapper is lighter but less "systemd-native." Which direction would you accept?
2. Cmdline namespace. inst.* follows Anaconda convention and is what PXE users will guess, but this project isn't Anaconda. Happy to use bluefin.install.* or sysinstall.* if preferred — bikeshed away.
3. UKI/measured-boot posture. Separate kernel+initrd PXE artifacts bypass the UKI's single-signed-object property. For a v1 targeting lab/fleet provisioning this seems acceptable (the installed system still boots its signed UKI), but if there's a desire to keep netboot within the UKI model long-term, UEFI HTTP boot of a netboot-variant UKI (with inst.ddi_url discovery via SMBIOS/DHCP instead of cmdline) could be a follow-up. I'd suggest not blocking v1 on it.
4. Per-host configuration (hostname, k3s join tokens, etc.) is explicitly out of scope here. A natural follow-up would be installer-fetched systemd credentials (inst.creds_url= or SMBIOS Type 11 OEM strings), which composes cleanly with this proposal.
Resulting PXE flow (for illustration)
#!ipxe
set base http://pxe-server:8080/data
kernel ${base}/bluefin-server-pxe-vmlinuz systemd.unit=system-install.target console=tty0 console=ttyS0,115200 rw unattended inst.ddi_url=${base}/bluefin-server-ddi.raw.zst inst.ddi_sha256=<sha256>
initrd ${base}/bluefin-server-pxe-initrd.cpio.gz
boot
The PXE server mirrors the three release assets (verified against the signed SHA256SUMS) and serves them over the LAN; the installer fetches the DDI locally, verifies, installs via the unchanged systemd-repart/bootctl path, and reboots into the installed OS.
Compatibility & Constraints
- Fully backwards compatible: no cmdline params → identical behavior to today. Existing installer media unaffected.
- Offline-first preserved: the embedded-DDI path remains the default; network pull is strictly opt-in.
- UEFI-only: unchanged — PXE clients boot via
ipxe.efi/UEFI netboot, consistent with the systemd-boot/UKI design. - Baseline x86_64: unchanged; artifacts are the same binaries already built.
- Distroless target OS: untouched — all changes are installer-side.
Activity
castrojo commentedon Aug 15, 2026
Triage & scoping — feasibility, architecture, and phased plan
Read this against current
main(bce0067). Verified every claim below against the repo tree and current upstream systemd sources (systemd main, FSDKfreedesktop-sdk-25.08.14).Feasibility verdict
Feasible within the hard constraints, with one correction to the issue's premises: the installer already has networking.
elements/oci/bluefin-server-installer.bstalready enablessystemd-networkd+systemd-resolvedinsystem-install.target.wantsand ships a catch-all DHCP config (80-dhcp.networkforen* eth* ens* enp*).ca-certificatesis already inelements/installer/installer-stack.bst, so HTTPS works too. The genuine gaps are smaller than the issue assumes:.raw.zstand the target UKI);No changes to
systemd-sysinstallitself are needed: it reads repart definitions from/usr/lib/repart.sysinstall.d/when populated (else/usr/lib/repart.d/), and--definitions=(v261) overrides that. That is the native seam for a network-sourced DDI: fetch the image, drop a repart definition whoseCopyBlocks=points at the downloaded file, invokesystemd-sysinstallunchanged. The wrapper script (bluefin-sysinstall) stays a thin pre-flight stage; all partitioning/copy/bootctl logic remains upstream's.Proposed netboot chain
Notes on the chain:
kernel/initrdis the right v1 vehicle precisely because the UKI cmdline is immutable, as the issue says. Chainloading the installer UKI (chain http://…/BOOTX64.EFI) also works with iPXE/UEFI HTTP Boot, but only with the baked cmdline — fine for a pure "netboot the USB media" scenario, useless for injecting a DDI URL. Both artifacts can ship; they serve different PXE servers.docs/ROOTFS_DISCOVERY.md, UEFI firmware HTTP(S) boot downloads a disk image into a RAM disk and boots its ESP — meaning today'sbluefin-server-installer-*.raw.zstmay already be firmware-HTTP-bootable on supporting hardware, at the cost of the whole image residing in RAM. Lab test before documenting.systemd-stubaccepts SMBIOS Type 11io.systemd.stub.kernel-cmdline-extra=(measured into PCR12). That composes with a signed netboot UKI, but SMBIOS strings are trivially settable for VMs, not bare metal — so it doesn't replace Part 1 for fleets. Defer.What exists vs. what is new
/layer/boot/vmlinuzelements/oci/bluefin-server-installer.bstStep 4 (ukify --linux=)/installer.cpio.gzelements/oci/bluefin-server-ddi.bst;.github/workflows/build.ymlSHA256SUMS+SHA256SUMS.gpgover all release assetsbuild.yml"Sign release SHA256SUMS manifest"files/os/sysupdate-keys/import-pubring.pgpviaelements/bluefin-server/os-sysupdate-keys.bstbluefin-server-installer.bstStep 1systemd-pullverification machineryelements/components/systemd-base.bstgpgbinary in installer envgnupganywhere inelements/(see Security)bluefin-sysinstallcurrently only checksunattendedsystemd-sysinstall(8)docs/skills/pxe-netboot.md+ index/AGENTS routingSecurity considerations (the high-risk part)
systemd-pull --verify=signatureconsumes: a flatSHA256SUMS+ detachedSHA256SUMS.gpgco-located with the assets, verified against/usr/lib/systemd/import-pubring.pgp. Grounding: upstreamsysupdate-resource.cinvokessystemd-pull raw --direct --verify=signature, and this repo's ownfiles/os/sysupdate.d/50-root.transferalready pullsbluefin-server-ddi-@v.raw.zstfrom GitHub Releases through that path in production.gpgin the installer env. Upstreamsrc/import/pull-common.cperforms signature verification by exec'inggpg2/gpgagainst the pubring. Nothing in this repo ships gnupg today (checked all ofelements/), soinstaller-stack.bstmust addfreedesktop-sdk.bst:components/gnupg.bstand stage the pubring (reusefiles/os/sysupdate-keys/import-pubring.pgp— single source of truth). Flag for maintainers:elements/bluefin-server/os-stack.bsthas no gnupg either, which suggests on-hostsystemd-sysupdatesignature verification may hit the same missing-gpgfailure. That predates this issue; please confirm — and if confirmed, the same one-line fix covers both.SHA256SUMS(fetched from the same server) is the control, exactly as upstream's ROOTFS_DISCOVERY trust section prescribes for network-fetched rootfs ("detached signatures (currently only GPG) or HTTPS certificate validation"). Rule: withinst.ddi_urlset, verification is mandatory — signature mode by default;inst.ddi_sha256=<hex>as a standalone checksum-only fallback; no unsigned/unchecked installs. Fail closed, before any disk is touched (fetch completes and verifies beforesystemd-sysinstallis exec'd).SHA256SUMSat mirror time. Per-boot, the payload that actually lands on disk (the DDI) is verified on-host.--secureboot-private-keyat CI time), and the target OS UKI is unsigned too. Netboot v1 inherits that posture — no regression, but SB-enforcing fleets need signed artifacts (signed iPXE + signed UKI, or self-enrolled keys via sd-boot's setup-mode enrollment). Recommend explicitly scoping SB signing out of this issue and tracking it separately.os-creds-prov.bst, TPM2 sealing roadmap) is untouched.Phased breakdown (each independently landable)
bluefin-server-installer.bstStep 7, also copy/layer/boot/vmlinuzand/installer.cpio.gzinto%{install-root}with versioned names and add them toSHA256SUMS; newexport-pxeJustfile recipe (installer group); upload inbuild.yml. No new build work — pure export of byproducts. (One check: the current Step 3 packs agzipinitrd while the element description sayscpio.zst; export whatever is actually built and reconcile the comment.)installer-stack.bst: addcomponents/gnupg.bst+ stageimport-pubring.pgp. Wrapper: parseinst.ddi_url/inst.ddi_sha256/inst.target_disk(namespace bikeshed below), fetch viasystemd-pull raw --directto tmpfs with mandatory verification, write theCopyBlocks=override, execsystemd-sysinstall --definitions=unchanged. Absence of params = byte-identical behavior to today. Add a build-time assertion forsystemd-pull/gpgmirroring the existing critical-tools check.show-me-the-futureQEMU recipe (or add a sibling) to boot the exported kernel/initrd via QEMU-kernel/-initrdwith a local HTTP server serving the DDI, reusing the existing OVMF flow. This is the regression net for Phase 2.docs/skills/pxe-netboot.md(chain, cmdline reference, iPXE stanza, RAM floor — see open questions — troubleshooting), PXE section inddi-installer.md, routing rows indocs/skills/index.md+AGENTS.md.Phases 1+4 alone already unblock "PXE-boot the installer with an embedded… nothing" for anyone willing to host a small custom initrd — but the real value is 1+2+3 landing together.
Open questions / maintainer decisions needed
inst.*(Anaconda muscle memory) vsbluefin.install.*vs aligning with systemd's ownsystemd.pull=precedent. No strong technical driver; needs an owner decision.systemd-pull(libexec binary; the exact invocation sysupdate uses, proven against this repo's release format) vsimportctl pull-raw(nicer CLI, but pulls in the importd daemon/D-Bus and its man page lists only gz/xz/bz2 for raw pulls — the pull engine sniffs compression by magic bytes so zstd works in practice, butsystemd-pullis the path already exercised by our OTA flow). Recommendation:systemd-pull. Confirm acceptable.gnupg.bst(initrd size grows modestly) is acceptable, and confirm/deny the suspected missing-gpggap for on-host sysupdate in the OS DDI.live-env + DDIof free RAM — expect to document ~8 GiB guidance pending measurement. Streaming directly to the target disk isn't possible without splitting repart into two phases; recommend accepting the RAM floor for v1 rather than engineering around it.bluefin-installer-datais absent (verified in the wrapper logic), so no change needed — noting for reviewers.Labels
Leaving labels untouched per the label workflow (humans triage;
status/triageasks a maintainer to set kind/area +/approve). Recommendation:kind/enhancement— the spec in the issue body satisfies that label's "spec must be written in issue body" requirement. Note the repo currently has noarea/*labels at all, so the triage contract can't be fully satisfied without creating one (e.g.area/installer) — also a maintainer call.castrojo commentedon Sep 5, 2026
Status update:
mainvia PR [scanner] fix: publish PXE boot artifacts #23 (commit 5e263a0). Standalone installer kernel (bluefin-server-pxe-vmlinuz-*) and initrd (bluefin-server-pxe-initrd-*.cpio.gz) are exported and published in releases.[scanner] fix: enable PXE DDI downloads), currently hold-gated for review.feat(installer): add opt-in PXE network DDI pull (#229)
refactor: switch OS payload to Flatcar base, drop displaced FSDK comp…
feat(installer): opt-in network credentials pull (inst.creds_url / in…