diff --git a/docs/skills/ddi-installer.md b/docs/skills/ddi-installer.md index 4699417a..3d362fd8 100644 --- a/docs/skills/ddi-installer.md +++ b/docs/skills/ddi-installer.md @@ -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 @@ -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`): @@ -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. | diff --git a/elements/oci/bluefin-server-installer.bst b/elements/oci/bluefin-server-installer.bst index 9a6a84ff..7df2c71a 100644 --- a/elements/oci/bluefin-server-installer.bst +++ b/elements/oci/bluefin-server-installer.bst @@ -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 @@ -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="" @@ -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 diff --git a/tests/unit/conftest.py b/tests/unit/conftest.py index 2e74f912..7cae690a 100644 --- a/tests/unit/conftest.py +++ b/tests/unit/conftest.py @@ -1,6 +1,7 @@ -"""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 @@ -8,6 +9,28 @@ 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(): diff --git a/tests/unit/test_installer_contract.py b/tests/unit/test_installer_contract.py index 42cd524f..d8108711 100644 --- a/tests/unit/test_installer_contract.py +++ b/tests/unit/test_installer_contract.py @@ -3,6 +3,8 @@ from __future__ import annotations import re +import shlex +import subprocess from pathlib import Path import yaml @@ -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")