Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 63 additions & 8 deletions docs/skills/ddi-installer.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,14 @@ over the LAN with `inst.*` kernel parameters:
embedded installer partition.
- `inst.ddi_sha256=<hex>` — **mandatory** when `inst.ddi_url` is set; verify the
downloaded DDI before touching the target disk (fail closed if absent).
- `inst.creds_url=<url>` — download a tar archive of first-boot systemd
credentials (any `curl` scheme; the iPXE example uses plain `http://`) and
place them in the installed system's ESP at
`/loader/credentials/`, where `systemd-stub` hands them to the target OS on
first boot (consumers: [tpm2-credential-sealing.md](tpm2-credential-sealing.md)).
- `inst.creds_sha256=<hex>` — **mandatory** when `inst.creds_url` is set;
verify the downloaded archive before touching the target disk (fail closed
if absent).
- `inst.target_disk=/dev/...` — explicit target disk, overriding
first-writable-disk auto-detection.

Expand All @@ -195,18 +203,64 @@ decompresses it with `zstd`, and feeds it into the **native**
points at the downloaded image — no custom installer logic. The override is
written with plain Bash line handling: the live initrd contains only what
`installer-stack.bst` and its transitive runtime deps install (Bash, uutils
coreutils, util-linux, kmod, systemd, `grep`, `curl`, `zstd`, cryptsetup,
xfsprogs, dosfstools). `sed`, `awk` and `tar` are **not** present. Every
external command the wrapper calls is pinned by the Step 1a tool check in
`bluefin-server-installer.bst`, which fails the build when one is missing.
coreutils, util-linux, kmod, systemd, `grep`, `curl`, `zstd`, `tar` (declared
for the credentials archive), cryptsetup, xfsprogs, dosfstools). `sed` and
`awk` are **not** present. Every external command the wrapper calls is pinned
by the Step 1a tool check in `bluefin-server-installer.bst`, which fails the
build when one is missing.

The credentials archive is an **uncompressed** ustar/pax/gnu tar (the wrapper
checks the `ustar` magic and feeds tar on stdin, so a `.tar.zst`/`.tar.xz` is
rejected rather than transparently decompressed) and flat: at most 64
top-level regular files named `<name>.cred`, where `<name>` matches
`[A-Za-z0-9][A-Za-z0-9._@~-]*` (`~` is systemd's own drop-in namespace,
`systemd.unit-dropin.<unit>~<name>`), each filename at most 250 bytes, each
file at most 1 MiB, the whole archive at most 16 MiB. Names must be unique
even ignoring case — the ESP is vfat, where `a.cred` and `A.cred` are the same
file. The wrapper validates the `tar -tv` listing column by column before
extracting anything (no directories, symlinks, hardlinks, devices or FIFOs; no
path separators, spaces, control characters or leading dashes/dots in names),
cross-checks it against `tar -t`, extracts only the validated names with
`--no-same-owner --no-same-permissions`, pins its copies to `0644` and
re-checks each is a regular file; any violation rejects the whole archive with
the target disk untouched. Trust model: `inst.creds_sha256` arrives on the same
unauthenticated PXE command line as the URL, so the checksum protects against a
compromised or misconfigured file server, not against whoever controls
DHCP/TFTP — they control both. The archive hardening is defence against
operator error and a bad mirror, not a boundary against a hostile netboot
server; secrets belong in TPM2/host-key-sealed credentials.
Each file must be `systemd-creds encrypt`ed with `--name=<name>` matching the
filename — `systemd-stub` stages ESP credentials under
`/run/credentials/@encrypted`, so plaintext files fail with
`status=243/CREDENTIALS`. The null key suffices for non-secret data
(`firstboot.hostname`, `tmpfiles.extra`); use host/TPM2 keys for secrets:

```bash
systemd-creds --with-key=null encrypt --name=firstboot.hostname hostname.txt firstboot.hostname.cred
systemd-creds --with-key=null encrypt --name=tmpfiles.extra tmpfiles.conf tmpfiles.extra.cred
tar -cf <mac>.tar firstboot.hostname.cred tmpfiles.extra.cred
sha256sum <mac>.tar
```

Example iPXE stanza (the PXE server mirrors the three assets, verified against
the signed `SHA256SUMS`):
Ordering and guarantees: both downloads are fetched and verified together,
before any disk change, so a bad DDI or credentials download aborts the install
with the target untouched. The credentials are unpacked into
`/dev/shm/installer/credentials/` at that point and copied onto the ESP only
after `systemd-sysinstall` has created it; the wrapper locates the ESP by GPT
partition type (`c12a7328-f81f-11d2-ba4b-00a0c93ec93b`) on the target disk,
mounts it once, writes `/loader/credentials/*.cred` first, syncs, then stages
the best-effort UEFI fallback loader on the same mount and unmounts. If the ESP
cannot be found or mounted while `inst.creds_url` is set, the install fails
rather than leaving the host to boot unconfigured. Without `inst.creds_url`, no
credentials are written.

Example iPXE stanza (the PXE server mirrors the three release assets, verified
against the signed `SHA256SUMS`, plus one per-host credentials archive):

```ipxe
#!ipxe
set base http://pxe-server:8080/data
kernel ${base}/bluefin-server-pxe-vmlinuz-<ver> systemd.unit=system-install.target console=tty0 console=ttyS0,115200 rw unattended inst.ddi_url=${base}/bluefin-server-ddi-<ver>.raw.zst inst.ddi_sha256=<sha256>
kernel ${base}/bluefin-server-pxe-vmlinuz-<ver> systemd.unit=system-install.target console=tty0 console=ttyS0,115200 rw unattended inst.ddi_url=${base}/bluefin-server-ddi-<ver>.raw.zst inst.ddi_sha256=<sha256> inst.creds_url=${base}/creds/${mac}.tar inst.creds_sha256=<sha256>
initrd ${base}/bluefin-server-pxe-initrd-<ver>.cpio.gz
boot
```
Expand Down Expand Up @@ -248,8 +302,9 @@ unaffected.
| "Use knuckle instead." | knuckle is deprecated in favor of native `systemd-sysinstall` (systemd 261+). |
| "Hardcode `root=/dev/vda2` for QEMU." | Bare metal has different device names. Always use PARTUUID. |
| "Pull the DDI from the network at install time." | Network pull is opt-in via `inst.ddi_url`; verification is mandatory and failures abort before any disk change, while the embedded installer media stays the default. |
| "The live initrd has sed/awk/tar like any Linux box." | It does not. The initrd holds only `installer-stack.bst` plus transitive runtime deps (Bash, uutils coreutils, util-linux, kmod, systemd, `grep`, `curl`, `zstd`); `sed`, `awk` and `tar` are absent and fail with `command not found` (exit 127) after the download. Use Bash builtins, or declare the tool in `installer-stack.bst` and add it to the Step 1a build-time tool check. |
| "The live initrd has sed/awk like any Linux box." | It does not. The initrd holds only `installer-stack.bst` plus transitive runtime deps (Bash, uutils coreutils, util-linux, kmod, systemd, `grep`, `curl`, `zstd`, `tar`); `sed` and `awk` are absent and fail with `command not found` (exit 127) after the download. Use Bash builtins, or declare the tool in `installer-stack.bst` and add it to the Step 1a build-time tool check. |
| "`/run` can hold the downloaded DDI." | No. systemd mounts `/run` with `size=20%`; the network DDI stages in `/dev/shm/installer/` (kernel tmpfs default, 50% of RAM) and the wrapper checks tmpfs free space and `MemAvailable` before decompressing. See "Memory requirements". |
| "Per-host configuration needs a custom installer step." | `inst.creds_url` is opt-in and only delivers verified `*.cred` files to the ESP `/loader/credentials/`; the installed OS consumes them through stock systemd credential consumers, so no installer logic is added. |
| "Put the DDI in the initrd cpio." | The DDI is ≈1.6 GiB raw (2 GiB+ once sparse space is written out). The initrd cpio step must run before the DDI is placed in `/layer`. |
| "Store the DDI in the ESP (FAT32)." | FAT32 has a 4 GiB per-file limit. Use a separate XFS partition. |
| "Add an 8 GiB minimum size floor to the DDI." | The rootfs is immutable. It never grows in-place. Content + overhead is enough. |
Expand Down
4 changes: 2 additions & 2 deletions docs/skills/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: Lazy-load manifest for Bluefin Server skills. Load this file after
metadata:
type: index
status: stable
last_updated: "2026-09-08"
last_updated: "2026-09-25"
---
# docs/skills — Index

Expand All @@ -27,7 +27,7 @@ This is the lazy-load routing table for agent skills. Keep this file in memory w
| [`bump-fsdk-version.md`](bump-fsdk-version.md) | Pinning or retagging the FSDK junction | Update the pinned FSDK release and derived tags. |
| [`ci-tooling.md`](ci-tooling.md) | GitHub Actions, workflow SHA pinning, CI conventions | CI conventions and release pipeline rules. |
| [`ddi-installer-build.md`](ddi-installer-build.md) | Building the installer or DDI on the cluster | Cluster build pipeline and local installer/DDI build. |
| [`ddi-installer.md`](ddi-installer.md) | Installer boot flow, `systemd-sysinstall`, `systemd-repart`, PXE network DDI pull | High-level DDI install architecture and local smoke test. |
| [`ddi-installer.md`](ddi-installer.md) | Installer boot flow, `systemd-sysinstall`, `systemd-repart`, PXE network DDI / credentials pull | High-level DDI install architecture and local smoke test. |
| [`factory-integration.md`](factory-integration.md) | Lab integration, boot-test workflow, factory role | How Bluefin Server is consumed by the CI lab. |
| [`flatcar-parity-matrix.md`](flatcar-parity-matrix.md) | Flatcar version audit, component parity, substitution order | Version parity matrix and gap audit against Flatcar 4593.2.5. |
| [`gap-analysis-distros.md`](gap-analysis-distros.md) | Comparing Bluefin Server to other server OSes | Source-verified comparison to Ubuntu, Talos, Flatcar, FCOS. |
Expand Down
3 changes: 3 additions & 0 deletions elements/installer/installer-stack.bst
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,9 @@ depends:
# zstd-compressed DDI over the LAN, per inst.ddi_url in the wrapper).
- freedesktop-sdk.bst:components/curl.bst
- freedesktop-sdk.bst:components/zstd.bst
# tar unpacks the inst.creds_url first-boot credentials archive; nothing else
# in this stack (uutils, util-linux, systemd) ships a tar.
- freedesktop-sdk.bst:components/tar.bst

# Kernel (installer boots from this; vmlinuz used as the UKI --linux= arg)
- flatcar/flatcar-kernel.bst
Expand Down
Loading