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
11 changes: 9 additions & 2 deletions docs/skills/ddi-installer.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: Use when building or debugging the Bluefin Server DDI live installe
metadata:
type: reference
status: stable
last_updated: "2026-09-09"
last_updated: "2026-09-26"
context7-sources:
- /systemd/systemd
- /apache/buildstream
Expand Down Expand Up @@ -185,7 +185,13 @@ wrapper (`bluefin-sysinstall`) brings up DHCP via `systemd-networkd-wait-online`
streams the DDI down with `curl`, stream-decompresses it with `zstd`, and feeds
it into the **native** `systemd-sysinstall` flow by staging a temporary
`/usr/lib/repart.sysinstall.d/` override whose `20-root-a.conf` `CopyBlocks=`
points at the downloaded image — no custom installer logic.
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.

Example iPXE stanza (the PXE server mirrors the three assets, verified against
the signed `SHA256SUMS`):
Expand All @@ -212,6 +218,7 @@ in tmpfs, so plan roughly `live-env + DDI` of free RAM (~8 GiB guidance).
| "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. |
| "Put the DDI in the initrd cpio." | The DDI is 2 GiB+. 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
30 changes: 25 additions & 5 deletions elements/oci/bluefin-server-installer.bst
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,11 @@ config:
set -eux
# Ensure critical tools are present in the staged rootfs before packing
# ponytail: fail fast if critical dependencies are missing, preventing broken images
for tool in udevadm lsblk systemd-repart bootctl systemd-sysinstall; do
# The second row is every external command bluefin-sysinstall calls: the
# live initrd has no sed, awk or tar, so the wrapper's tool set is pinned
# here rather than discovered at install time (exit 127 after download).
for tool in udevadm lsblk systemd-repart bootctl systemd-sysinstall systemctl \
grep curl zstd modprobe mount umount sha256sum readlink ls cp mkdir sleep; do
if ! [ -x "/layer/usr/bin/${tool}" ] && ! [ -x "/layer/usr/sbin/${tool}" ]; then
echo "ERROR: Critical tool '${tool}' is missing from the staged rootfs at /layer!" >&2
exit 1
Expand Down Expand Up @@ -272,12 +276,27 @@ config:
# overriding only the root recipe's CopyBlocks=. systemd-sysinstall
# reads /usr/lib/repart.sysinstall.d/ when populated, else /usr/lib/
# repart.d/, so stage all three recipes with 20-root-a.conf repointed.
# The rewrite is plain Bash: the live initrd ships no sed or awk.
mkdir -p /usr/lib/repart.sysinstall.d
cp -a /usr/lib/repart.d/10-esp.conf /usr/lib/repart.sysinstall.d/
cp -a /usr/lib/repart.d/30-var.conf /usr/lib/repart.sysinstall.d/
sed 's#^CopyBlocks=.*#CopyBlocks=/run/installer/bluefin-server-ddi.raw#' \
/usr/lib/repart.d/20-root-a.conf \
> /usr/lib/repart.sysinstall.d/20-root-a.conf
# The key is matched at column 0, as files/installer/repart.d writes it.
# Recipe and wrapper ship from the same repo, so a recipe without a
# column-0 CopyBlocks= line is a repo bug: fail loudly before the disk
# is touched instead of guessing where the key belongs.
ROOT_COPYBLOCKS_LINE="CopyBlocks=/run/installer/bluefin-server-ddi.raw"
ROOT_COPYBLOCKS_SEEN=0
while IFS= read -r line || [ -n "${line}" ]; do
if [[ "${line}" == CopyBlocks=* ]]; then
line="${ROOT_COPYBLOCKS_LINE}"
ROOT_COPYBLOCKS_SEEN=1
fi
printf '%s\n' "${line}"
done < /usr/lib/repart.d/20-root-a.conf > /usr/lib/repart.sysinstall.d/20-root-a.conf
if [ "${ROOT_COPYBLOCKS_SEEN}" -eq 0 ]; then
echo "ERROR: /usr/lib/repart.d/20-root-a.conf has no CopyBlocks= line to repoint." >&2
exit 1
fi
fi

INSTALLER_PART=""
Expand Down Expand Up @@ -339,7 +358,8 @@ config:
udevadm settle --timeout=10 || true
local target="${TARGET_DISK:-}"
if [ -z "${target}" ]; then
local root_part="$(readlink -f /dev/disk/by-partlabel/bluefin-server-root-a 2>/dev/null || true)"
local root_part
root_part="$(readlink -f /dev/disk/by-partlabel/bluefin-server-root-a 2>/dev/null || true)"
if [ -n "${root_part}" ]; then
target="$(lsblk -p -n -d -o PKNAME "${root_part}" 2>/dev/null || true)"
fi
Expand Down
25 changes: 24 additions & 1 deletion tests/unit/conftest.py
Original file line number Diff line number Diff line change
@@ -1,13 +1,36 @@
"""Shared fixtures for the docs-checks unit tests."""
"""Shared fixtures for the unit tests."""

import importlib.util
import re
import sys
from pathlib import Path

import pytest

REPO_ROOT = Path(__file__).resolve().parents[2]
SCRIPT_PATH = REPO_ROOT / ".github" / "scripts" / "docs-checks.py"
INSTALLER_ELEMENT = REPO_ROOT / "elements" / "oci" / "bluefin-server-installer.bst"


@pytest.fixture(scope="session")
def installer_wrapper() -> str:
"""The ``bluefin-sysinstall`` script carved out of the installer element.

The wrapper lives in a quoted heredoc inside ``bluefin-server-installer.bst``
with six spaces of YAML indentation; this returns it as it lands in the
initrd so tests can run or inspect it as a plain bash script.
"""
element = INSTALLER_ELEMENT.read_text(encoding="utf-8")
match = re.search(
r"cat > /layer/usr/bin/bluefin-sysinstall << 'EOF'\n(.*?)\n EOF\n",
element,
flags=re.DOTALL,
)
assert match, "bluefin-sysinstall heredoc must be present"
return "\n".join(
line[6:] if line.startswith(" ") else line
for line in match.group(1).splitlines()
) + "\n"


def _load_module():
Expand Down
99 changes: 99 additions & 0 deletions tests/unit/test_installer_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
from __future__ import annotations

import re
import shlex
import subprocess
from pathlib import Path

import yaml
Expand Down Expand Up @@ -140,6 +142,103 @@ def test_installer_hard_preflight_aborts_on_missing_installer_data_part() -> Non
assert "lsblk -p -o NAME,TYPE,PARTLABEL,PKNAME,SIZE,FSTYPE" in installer_element


def test_installer_wrapper_does_not_call_sed_awk_or_tar(installer_wrapper: str) -> None:
# The released 26.08.0 PXE initrd failed with "sed: command not found"
# (exit 127) right after a successful download: the live initrd ships
# uutils coreutils, grep, curl, zstd and systemd, but no sed, awk or tar,
# so no command position may name any of them. Only a '#' at the start of
# a line or after whitespace opens a comment; '#' inside a string does not.
code_lines = [re.sub(r"(^|\s)#.*$", "", line) for line in installer_wrapper.splitlines()]
invoked = re.compile(r"(?:^|[\s|;&(`$])(sed|awk|tar)(?=[\s;|&)>]|$)")
offenders = [line for line in code_lines if invoked.search(line)]
assert offenders == [], offenders


def test_installer_build_pins_every_external_command_the_wrapper_calls() -> None:
# Step 1a of the element refuses to pack an initrd that lacks any of the
# wrapper's external commands, so a missing tool fails the build rather
# than the install (exit 127 after the DDI download, as sed did).
installer_element = INSTALLER_ELEMENT.read_text(encoding="utf-8")
match = re.search(r"for tool in ((?:[^;\n]|\\\n)+); do", installer_element)
assert match, "the build-time tool check loop must be present"
pinned = set(match.group(1).replace("\\\n", " ").split())
for tool in (
"grep", "curl", "zstd", "modprobe", "mount", "umount", "sha256sum",
"readlink", "lsblk", "udevadm", "systemd-sysinstall", "systemctl",
):
assert tool in pinned, f"{tool} is called by bluefin-sysinstall but not pinned at build time"


def _copyblocks_repoint_block(installer_wrapper: str) -> tuple[str, str]:
"""The CopyBlocks= rewrite carved out of the wrapper, plus the repointed line.

Coupled to the element text: the slice starts at the ROOT_COPYBLOCKS_LINE
assignment (column 0 after the fixture de-indents the heredoc) and ends at
the ``fi`` closing the ROOT_COPYBLOCKS_SEEN check.
"""
start = installer_wrapper.index('ROOT_COPYBLOCKS_LINE="CopyBlocks=')
seen_if = installer_wrapper.index('if [ "${ROOT_COPYBLOCKS_SEEN}" -eq 0 ]', start)
end = re.compile(r"^[ \t]*fi\n", re.MULTILINE).search(installer_wrapper, seen_if).end()
block = installer_wrapper[start:end]

copyblocks = re.search(r'^ROOT_COPYBLOCKS_LINE="(CopyBlocks=/\S+)"$', block, flags=re.MULTILINE)
assert copyblocks, "the wrapper must pin the repointed CopyBlocks= line in ROOT_COPYBLOCKS_LINE"
return block, copyblocks.group(1)


def _run_copyblocks_repoint(
tmp_path: Path, installer_wrapper: str, recipe_text: str
) -> tuple[subprocess.CompletedProcess[str], Path, str]:
block, copyblocks_line = _copyblocks_repoint_block(installer_wrapper)
src_dir = tmp_path / "repart.d"
dst_dir = tmp_path / "repart.sysinstall.d"
src_dir.mkdir(parents=True)
dst_dir.mkdir(parents=True)
(src_dir / "20-root-a.conf").write_text(recipe_text, encoding="utf-8")
block = block.replace("/usr/lib/repart.d", shlex.quote(str(src_dir))).replace(
"/usr/lib/repart.sysinstall.d", shlex.quote(str(dst_dir))
)
result = subprocess.run(
["bash", "-euo", "pipefail", "-c", block], capture_output=True, text=True
)
return result, dst_dir / "20-root-a.conf", copyblocks_line


def test_installer_wrapper_copyblocks_repoint_matches_the_sed_it_replaced(
tmp_path: Path, installer_wrapper: str
) -> None:
"""Run the Bash rewrite against the shipped recipe: only the CopyBlocks= line changes."""
recipe = (REPO_ROOT / "files" / "installer" / "repart.d" / "20-root-a.conf").read_text(
encoding="utf-8"
)
result, output, copyblocks_line = _run_copyblocks_repoint(tmp_path, installer_wrapper, recipe)
assert result.returncode == 0, result.stderr

expected = re.sub(r"^CopyBlocks=.*$", copyblocks_line, recipe, flags=re.MULTILINE)
assert output.read_text(encoding="utf-8") == expected
assert f"{copyblocks_line}\n" in expected


def test_installer_wrapper_copyblocks_repoint_fails_closed_without_a_copyblocks_line(
tmp_path: Path, installer_wrapper: str
) -> None:
# Recipe and wrapper ship from the same repo; a recipe with no column-0
# CopyBlocks= line is a repo bug, so the wrapper must error out before the
# disk is touched rather than guess where to put the key. An indented key
# (valid for systemd's parser) is deliberately not matched and hits the
# same error, instead of silently producing a second CopyBlocks= line.
for recipe in (
"[Partition]\nType=root\nLabel=bluefin-server-root-a\n",
"[Partition]\nType=root\n CopyBlocks=/dev/disk/by-partlabel/x\n",
):
result, output, copyblocks_line = _run_copyblocks_repoint(
tmp_path / str(len(recipe)), installer_wrapper, recipe
)
assert result.returncode == 1, (result.returncode, result.stderr)
assert "20-root-a.conf has no CopyBlocks= line" in result.stderr
assert copyblocks_line not in output.read_text(encoding="utf-8")


def test_interactive_installer_uses_local_virtual_console() -> None:
installer_element = INSTALLER_ELEMENT.read_text(encoding="utf-8")

Expand Down