Repository navigation
fix(installer): stage the network DDI in /dev/shm and check free space before decompressing - #251
Conversation
🐝 Possible duplicateThis PR changes exactly the same files as #250, which was opened first:
Evidence — identical changed-file set (4 file(s)):
This is a suggestion, not a verdict. Hive will not close, label, approve or merge anything here — a human decides. It was produced by comparing changed-file sets across open PRs, which is a candidate generator: PRs that share a file are not necessarily the same work. Here the patches DIFFER, so this is the weaker tier: dependency-bump PRs that edit one shared manifest, and unrelated fixes to one busy file, both land in it. Read the diffs before acting. |
9bee13a to
56bcf59
Compare
…e before decompressing The inst.ddi_url path staged the download in /run, which systemd PID 1 mounts as tmpfs with size=20% of RAM (~1.6 GiB on an 8 GiB machine). The 26.08.0 DDI is 365 MiB compressed and 1.58 GiB raw, and `zstd --rm` removes the compressed copy only after a successful decompress, so decompression needs ~1.95 GiB of tmpfs and failed on the released installer with zstd: error 70 : Write error : cannot write block : No space left on device on any machine with less than roughly 10 GiB of RAM. Stage under /dev/shm/installer instead: PID 1 mounts /dev/shm without a size option, so it gets the kernel tmpfs default of 50% of RAM. The wrapper first checks that /dev/shm is a mountpoint (so it never stages on devtmpfs). After download and verification, before decompressing, compare the raw size recorded in the zstd frame header (or 5x the compressed size when the header does not carry it, with a WARN) against both `df --output=avail` of the staging directory and MemAvailable from /proc/meminfo minus 256 MiB of headroom, in KiB rounded up, and abort with all the numbers instead of dying mid-write. The MemAvailable bound is needed because the tmpfs cap alone is not proof of memory: the unpacked initrd is its own tmpfs, so df on /dev/shm can report space the kernel cannot back and the write would OOM instead. df failures and unparsable output fail closed with a message. Drop the pre-created /layer/run/installer: the wrapper creates its staging directory itself. mountpoint, stat, df and tail join the Step 1a build-time tool check. test_installer_contract.py asserts the wrapper stages under /dev/shm/installer with the preflight between verification and zstd, and runs the extracted preflight block against a real zstd frame (header size wins) and a non-zstd payload (5x fallback, WARN emitted) with a stand-in right-aligned df and a fake /proc/meminfo (DDI_MEMINFO is overridden in the carved-out block), checking the one-KiB pass/fail boundary on both the tmpfs and the MemAvailable bound, the error text, and that a meminfo without MemAvailable fails closed. Assisted-by: Claude Fable 5.1 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace the "~8 GiB guidance" line with a Memory requirements section: the network DDI stages in /dev/shm/installer because /run is mounted with size=20% while /dev/shm gets the kernel tmpfs default of 50% of RAM, both the compressed and decompressed DDI must fit at once, and the wrapper checks both the tmpfs free space and MemAvailable (minus 256 MiB headroom) before zstd runs, since the tmpfs cap alone does not prove the kernel can back the pages. State the requirement as "MemAvailable after the download must exceed the raw DDI plus headroom"; 8 GiB is the tested and recommended size for the 26.08.0 Flatcar-based DDI and smaller machines are not boot-tested. Add the matching Common Rationalizations row and fix the "2 GiB+" row to the real ~1.6 GiB raw size. Assisted-by: Claude Fable 5.1 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
56bcf59 to
63f40d5
Compare
…254) ## Problem On the installed image `bluefin-firstboot-credentials.service` fails on every boot that carries a `firstboot.*` credential: ```text bluefin-firstboot-credentials.service: Failed at step EXEC spawning systemd-firstboot: No such file or directory ``` so `firstboot.locale`, `firstboot.locale-messages`, `firstboot.keymap`, `firstboot.timezone` and `firstboot.hostname` are silent no-ops — including the ones `systemd-sysinstall` itself propagates from the installer environment (locale/keymap/timezone, see the "Propagates installer environment settings" bullet in `ddi-installer.md`). Observed in QEMU on the installed `installer-v26.08.0` image with credentials staged on the ESP (`Received untrusted credentials: firstboot.hostname, firstboot.locale, firstboot.timezone, …` followed by the EXEC failure). Found while integrating with the [jeefy/booty](https://github.com/jeefy/booty) PXE server, which delivers `firstboot.hostname` per host. ## Root cause The unit runs `ExecStart=systemd-firstboot --force --welcome=no`, written when the OS payload was FSDK's systemd. #132 cut the payload over to Flatcar's `/usr` (`flatcar-usr.bst`), and **Flatcar builds systemd without `systemd-firstboot`**: `flatcar-container.tar.gz` for 4593.2.5 contains neither `/usr/bin/systemd-firstboot` nor `systemd-firstboot.service` (verified by listing the archive; the `ln -sf /dev/null …/systemd-firstboot.service` mask in `bluefin-server-ddi.bst` is therefore a no-op too, harmless). `installer-stack.bst` still has FSDK's systemd with `systemd-firstboot`, which is why the *installer* side works and the *target* side does not. ## Fix Replace the binary with `/usr/libexec/bluefin-firstboot-credentials`, a bash + coreutils helper (both shipped by Flatcar), staged by `os-creds-prov.bst`. It reads the five credentials from `$CREDENTIALS_DIRECTORY`, validates them at least as strictly as systemd's validators (`hostname_is_valid`-style: labels `[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?`, no leading/trailing hyphen, ≤ 64 chars total; timezone must match `[A-Za-z0-9_+-]+(/…)*` **and** exist under `/usr/share/zoneinfo`; locale/keymap restricted to safe characters and < 128 bytes like `locale_is_valid()`/`keymap_is_valid()`; everything ASCII-only under `export LC_ALL=C`, since PID 1 exports the `LANG` this helper itself writes and `[[:alnum:]]` would otherwise widen with it; a NUL byte in a credential is rejected rather than silently dropped by `$(<file)`), and writes the same files `systemd-firstboot` would, in the same format — plus `/etc/hostname`. On `firstboot.hostname`: systemd ≤ v259 (Flatcar 4593.2.5 ships 257.9) has no such credential; systemd v260 added it as a *static* hostname honoured only when none is set yet, whereas this helper applies it unconditionally and additionally sets the live kernel hostname (systemd's own transient hostname credential remains `system.hostname`, consumed by PID 1): | credential | file | |---|---| | `firstboot.locale` / `firstboot.locale-messages` | `/etc/locale.conf` (`LANG=` / `LC_MESSAGES=`) | | `firstboot.keymap` | `/etc/vconsole.conf` (`KEYMAP=`) | | `firstboot.timezone` | `/etc/localtime -> ../usr/share/zoneinfo/<tz>` | | `firstboot.hostname` | `/etc/hostname` + live kernel hostname (`/proc/sys/kernel/hostname`) so the first DHCP request carries it — new relative to `main` (the old `ExecStartPost` set the kernel hostname but never persisted `/etc/hostname`); semantics differ from systemd v260's (always applied, not only when no static hostname exists) | Any invalid value fails the run **before** anything is written (unit fails visibly, stamp file not created; control characters in the rejected value are `%q`-quoted in the log). The helper `sync`s before exiting so the `ExecStartPost` stamp cannot outlive the files on power loss. The unit's ordering, conditions, `ImportCredential=` lines and the `/etc/.bluefin-firstboot-credentials` stamp are unchanged; the old `ExecStartPost` hostname one-liner folds into the helper. Shebang is `/usr/bin/bash` so EXEC does not depend on the tmpfiles-created `/bin` symlink. `--root=DIR` exists for tests only. Known, deliberate differences from `systemd-firstboot` (stated in the helper's header): trailing newlines in a credential are stripped rather than rejected; `LC_MESSAGES=` is written even when it equals `LANG=`; locales/keymaps are shape-checked, not checked against what is installed (Flatcar ships the full zoneinfo, so the timezone existence check is real). ### Why not ship the binary Pulling FSDK's `systemd-firstboot` into the Flatcar `/usr` was the other option and was rejected: it links `libsystemd-shared-<ver>.so` from a different systemd build, so it would drag a second libsystemd-shared into the image and reintroduce exactly the FSDK/Flatcar userspace split #132 removed. The helper is ~100 lines with no dependencies beyond what the payload already has, and follows the precedent of #246's `files/os/libexec/bluefin-root-cred-sync`. ## Verification - `tests/unit/test_credentials_provisioning.py` — unit no longer names `systemd-firstboot`, `ExecStart` points at the helper and precedes the stamp; element stages `files/os/libexec` and installs the helper 0755. - `tests/unit/test_firstboot_credentials_behavior.py` (new, 26 tests) — executes the helper against a scratch `--root`: all five credentials produce the exact files above; a subset writes only its files; `--force`-style overwrite of existing `/etc/hostname` and `/etc/localtime`; interior hyphens/digits in labels accepted; twelve invalid inputs (`bad host`, `-leading`, `trailing-`, `foo-.bar`, `foo..bar`, `hôte`, `host\r`, 65-char hostname, `../../etc/passwd` and unknown timezone, shell metacharacters in locale, `..` in keymap) exit 1 with a named error and write **nothing**; a non-ASCII **keymap/locale** (`[[:alnum:]]` regexes) is rejected with `LC_ALL=C.UTF-8`/`LANG=C.UTF-8` in the environment — this test **fails when `export LC_ALL=C` is removed from the helper** (verified by mutation; the round-1 hostname variant did not, because `[A-Za-z0-9]` does not widen under `C.UTF-8`); 127-byte keymap accepted / 128 rejected; locale-only and messages-only `locale.conf`; invalid `locale-messages`; a NUL byte; the CR case logs `$'host\r'`; empty credential treated as absent; missing and nonexistent `CREDENTIALS_DIRECTORY` are errors; `bash -n`; `shellcheck -S warning` (skipped visibly, not silently passed, when shellcheck is absent — CI's `unit-tests.yml` does not install it). - `python3 -m pytest tests/unit -q` — 371 passed, 1 xfailed (pre-existing). `test_files_payload_reachability` confirms the new `files/os/libexec/` path is staged. - `python3 .github/scripts/docs-checks.py` + the `check-*` scripts — pass. - Not run: `just validate` / `just build-ddi` (no local BuildStream) and a rebuilt-image boot. The helper has only been exercised by the executed unit tests against a scratch `--root`; a first boot with `firstboot.*` credentials on a rebuilt DDI is the remaining proof and I am happy to run it against a CI artefact. Docs: `ddi-installer.md` describes what the unit actually runs and writes (same files as `systemd-firstboot` plus the hostname handling, with the ≤ v259 / v260 distinction); `tpm2-credential-sealing.md` drops `systemd-firstboot` as a consumer of `passwd.hashed-password.root`. No relation to the installer PR stack (#250, #251, #252, #253); no textual or compose overlap with #246 (`bluefin-root-cred-sync` is installed from a separate element).
There was a problem hiding this comment.
Read elements/oci/bluefin-server-installer.bst at 63f40d5 in full, not just the hunks. Looks correct to me.
- The wrapper is written with
#!/bin/bash(bst:199), so the[[ … =~ ]]/BASH_REMATCHsize parsing is valid there. - No reference to
/run/installersurvives anywhere in the element after droppingmkdir -p /layer/run/installer; every staging path and theCopyBlocks=override line now agree on/dev/shm/installer. mountpoint,stat,df,tailare added to the step 1a build-time check, so a missing tool fails the build rather than the PXE client (the initrd has no sed/awk, per the existing comment above the loop).- The preflight sits between
sha256sum --checkandzstd -d, and takes the min ofdfavail andMemAvailable − 256 MiB, both in KiB. The arithmetic rounds up, so a raw image a few KiB too large is refused, not waved through.
Not duplicated by #252: that PR is a declared stack carrying these exact two commits (c021ec4, 63f40d5) plus one more, so merge order is #250 → this → #252.
Confidence: 5/5 (safe)
— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88
…st.creds_sha256) for PXE installs (#253) **Stacked on #252** (wait-online) ← #251 (`/dev/shm` staging) ← #250 (sed rewrite) — only the last four commits (`feat`, `docs`, `test`, `docs`) are new here; the credentials pull shares the same staging directory and network wait, so the diff shrinks to those four as the fixes merge. ## Motivation #229 made PXE installs self-contained by letting the installer pull the DDI over the LAN (`inst.ddi_url` / `inst.ddi_sha256`). Its feature request (#14 §4) left per-host configuration out of scope, naming the natural follow-up: installer-fetched systemd credentials. A PXE fleet still needs a hostname, an operator SSH key and usually a first-boot callback per machine, and the only delivery path today is an operator hand-mounting the ESP after the install. This PR closes that gap with the same shape as the DDI pull: two opt-in kernel parameters, mandatory verification, no new installer logic — the files are handed to the stock systemd credential consumers already documented in `docs/skills/tpm2-credential-sealing.md` (`firstboot.*`, `tmpfiles.extra`, `network.*`, `passwd.*`). Found while integrating with the [jeefy/booty](https://github.com/jeefy/booty) PXE server, which serves `GET /creds/<mac>.tar` per host. ## Behaviour | Parameter | Meaning | |---|---| | `inst.creds_url=<url>` | Download a **flat, uncompressed tar archive** of `systemd-creds encrypt`ed `*.cred` files (any `curl` scheme; the example uses plain `http://`) and place them in the installed system's ESP at `/loader/credentials/`. | | `inst.creds_sha256=<hex>` | **Mandatory** when `inst.creds_url` is set. Verified before anything is unpacked or written. | iPXE example (`${mac}` expanded by iPXE): ```text 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> ``` Archive contract: an **uncompressed** ustar/pax/gnu tar (the wrapper checks the `ustar` magic at offset 257 and feeds tar on stdin, where GNU tar refuses compressed input instead of transparently decompressing a `.tar.zst` into an unbounded listing) of at most **64** top-level regular files named `<name>.cred`, `<name>` matching `[A-Za-z0-9][A-Za-z0-9._@~-]*` (`~` is systemd's own `systemd.unit-dropin.<unit>~<name>` credential namespace), each name at most **250 bytes**, each file at most **1 MiB**, the archive at most **16 MiB**, and no name repeated even ignoring case (the ESP is vfat, where `a.cred` and `A.cred` are the same file). Any other member (directory, `./` prefix, symlink, hardlink, device, FIFO, path, space/control character/leading dash or dot in the name, non-`.cred` name, over-long or duplicate name) rejects the whole archive with a wrapper-level message before anything is extracted. Build with `tar -cf <mac>.tar -C <dir> a.cred b.cred`. 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 security boundary against a hostile netboot server; secrets belong in TPM2/host-key-sealed credentials. ## Guarantees - **Absent → behaviourally unchanged.** Without `inst.creds_url` the wrapper behaves as before; the one shared change is that the ESP is now located by GPT partition type instead of "first vfat on the target" (design note 1). The commit message and in-script comment now say the same (round 1 said "byte-for-byte", which was wrong). - **Fail closed on missing checksum**, same wording as the DDI check. - **Nothing touches the disk before both downloads verify, and nothing unverified is used.** The archive is fetched right after the DDI (one shared `systemd-networkd-wait-online`), capped at 16 MiB (`curl --max-filesize` — curl ≥ 8.4 aborts a transfer of unknown length once it crosses the cap; re-checked with `stat` after the checksum so the bound does not depend on the curl version), `sha256sum --check`ed, checked for the `ustar` magic, and only then listed — via stdin, so tar cannot auto-decompress. The `tar -tv` listing is validated column by column *before extraction* — type must be a regular file (no directories, symlinks, hardlinks, devices, FIFOs), size numeric and ≤ 1 MiB, date/time columns where GNU tar puts them (`LC_ALL=C`), name matching the strict pattern (which also rejects the backslash sequences `--quoting-style=escape` emits for a smuggled newline or other control character) and ≤ 250 bytes, no duplicate or case-colliding names, ≤ 64 members — and cross-checked against the plain `tar -t` listing so a column shift (e.g. an owner name with a space) is caught. Only the validated names are extracted (`--no-same-owner --no-same-permissions`), pinned to `0644`, and re-checked as regular non-symlink files. Everything lands in `/dev/shm/installer/credentials/` (tmpfs) *before* `systemd-sysinstall` runs. A bad download aborts with the target untouched. - **Placement happens after `systemd-sysinstall`** in the existing post-install ESP pass (`stage_fallback_bootloader` → `finalize_target_esp`): one `mount -t vfat` of the ESP identified by type GUID `c12a7328-f81f-11d2-ba4b-00a0c93ec93b` on the target disk, `mkdir -p loader/credentials`, `cp -- "$CREDS_DIR/$name"` for each validated name (never a glob over the extraction directory), `sync` — **first**, then the best-effort fallback-loader copy on the same mount, so a loader hiccup cannot abort the function with the mandatory step undone — then `umount`. - **Fail closed after install too.** If `inst.creds_url` was given and the ESP cannot be found or mounted, the wrapper exits 1 (→ `FailureAction=poweroff`) instead of letting an unconfigured, unreachable host reboot. - **Credentials must be `systemd-creds` encrypted.** `systemd-stub` stages ESP credentials under `/run/credentials/@encrypted`, so plaintext `*.cred` files are rejected by the consuming services (`status=243/CREDENTIALS`); null-key encrypted files (`systemd-creds --with-key=null encrypt --name=<name> - <name>.cred`) apply. The docs say so and show the commands. - **One new tool**: GNU `tar` (`components/tar.bst`, present at the pinned `freedesktop-sdk-26.08.0`; runtime deps glibc, symlinks, utf-locale) in `installer-stack.bst`, also added to the build-time tool check together with `dd`, `rm`, `chmod`, `sync` (all confirmed in the released initrd). `curl`, `sha256sum`, `stat`, `mount`, `lsblk`, `udevadm` were already there (confirmed against the released 26.08.0 initrd's file list: uutils coreutils 0.11.0, GNU grep, curl, zstd, util-linux; no `sed`/`awk`/`tar`). ## Verification - `tests/unit/test_installer_contract.py::test_installer_network_credentials_pull_contract` — parameter parsing, mandatory-checksum wording, fetch → verify → size cap → `ustar` magic → listing → unpack → `systemd-sysinstall` ordering, tar only ever reading the archive from stdin, the 16 MiB / 64 / 250-byte / 1 MiB caps, mode and name patterns, case-insensitive duplicate check, listing cross-check, 0644 pin and regular-file re-check, ESP lookup by type GUID on a single vfat mount with per-name copies (no glob) written before the loader, fail-closed message, `tar.bst` in the stack and `tar` in the build-time tool check. - `tests/unit/test_installer_creds_pull_behavior.py` (new, 29 tests) — runs the wrapper (shared `installer_wrapper` fixture) under bash: `bash -n`, `shellcheck -S warning` when installed, and the fetch/verify/validate/unpack block against real tar archives with a stand-in `curl`. Accepted: a flat archive lands in tmpfs at `0644` regardless of archive modes/owners and the download is removed; 64 members incl. a 1 MiB member (boundary); a `systemd.unit-dropin.multi-user.target~booty.cred` member; a 250-byte name. Rejected without creating the credentials directory: checksum mismatch, non-`.cred` names, directories, `./` prefixes, symlinks, hardlinks, char/block devices, FIFOs, names with spaces / newlines / colons / leading dash / leading dot, an owner field with a space (column shift), a 1 MiB + 1 B member, 65 members, a 251-byte name, a repeated name, two names differing only by case, a 17 MiB archive, a zstd-compressed tar (rejected at the magic check; GNU tar on stdin is also shown to refuse it), empty and non-tar payloads. **Not executed here**: the curl-side `--max-filesize` (the stand-in curl ignores it; the `stat` re-check is executed) and `finalize_target_esp` (string assertions only) — stated in the module docstring. Tests skip unless GNU tar is present. - `python3 -m pytest tests/unit -q` — 383 passed, 1 xfailed (pre-existing). - `bash -n` + `shellcheck -S warning` on the extracted wrapper — clean. - `python3 .github/scripts/docs-checks.py` + the `check-*` scripts — pass. - **End to end in QEMU** (OVMF, q35/KVM, 8 GiB, 20 GiB virtio disk, single NIC) with the *combined* wrapper of this stack and GNU tar dropped into the released `installer-v26.08.0` initrd, booted via iPXE from a Booty instance serving all four `inst.*` parameters: archive fetched and verified before any disk change, a 7-file `*.cred` archive accepted, `systemd-sysinstall` runs, `finalize_target_esp` stages the fallback loader and writes `/loader/credentials/*.cred` on `/dev/vda1`; on first boot the target logs `Received untrusted credentials: firstboot.hostname, firstboot.locale, firstboot.timezone, tmpfiles.extra, …`, `tmpfiles.extra` is applied and SSH as the provisioned operator works. - **Not booted**: the archive-hardening pass (size caps, column-by-column listing validation, cross-check, `--no-same-permissions`/`0644` pin, per-name copy) and the `--any` on wait-online were added *after* that QEMU run from review; the happy path is behaviourally identical for a well-formed archive (the executed unit tests exercise the exact block that ships), but the current wrapper has not been re-booted. The archive-rejection paths, the ESP-not-found/unmountable failure and the wait-online timeout are unit-tested only. - Not run: `just validate` / `just build-installer` (no local BuildStream); the tested initrd was hand-assembled from the released one. Two target-side observations from that run, both outside this PR: (a) null-key credentials are honoured by `ImportCredential=` consumers (tmpfiles, sysusers, …) but refused by PID 1 and generators (`system.hostname`, `systemd.extra-unit.*`: `Operation not supported`), so anything beyond those consumers needs host/TPM2-key encryption; (b) `bluefin-firstboot-credentials.service` fails on the released image with `Failed at step EXEC spawning systemd-firstboot`, so `firstboot.*` are no-ops there — fixed separately in `fix/firstboot-credentials-binary` (#254). ## Design notes / questions 1. **ESP lookup by partition type.** The fallback-loader pass previously took the first `vfat` partition on the target disk. I switched it to the ESP type GUID so the credentials cannot land on an unrelated vfat data partition on an install-alongside layout. Same partition in every layout the installer produces today; flagging it because it touches the non-PXE path. 2. **Mount reuse vs. separate pass.** I reused the single existing post-install mount rather than mounting twice, so the fallback loader and the credentials share one function. Happy to split it if you prefer the bootloader staging to stay strictly best-effort and isolated. 3. **`sha256sum` vs. `importctl`.** I mirrored the DDI path (`curl` + `sha256sum --check`). If you would rather move both network pulls to `importctl pull-raw --verify=checksum` with a `SHA256SUMS`, I can do that in a follow-up covering both. 4. **Encrypted-only enforcement.** The wrapper checks archive shape, not contents. Should it additionally check for the `systemd-creds` header and refuse plaintext up front? 6. **Caps.** 64 members / 1 MiB each / 16 MiB total are generous for encrypted credentials (a few KiB each) but arbitrary; happy to tune. 5. **`tar` as the only new dep.** GNU tar was the smallest thing that reads the archive; a `cpio` or a DDI-wrapped credentials volume felt heavier for a handful of small files.
Branch:
fix/installer-ddi-staging-shm. Stacked on #250 (fix/installer-sed-missing) — only the last two commits (fix(installer): stage the network DDI in /dev/shm …,docs(installer): memory requirements …) are new here; the diff shrinks to those once #250 merges. Next in the stack: #252 (wait-online) → #253 (inst.creds_url).Problem
The
inst.ddi_urlpath staged the download in/run. systemd PID 1 mounts/runas tmpfs withsize=20%(20 % of RAM ; ≈1.6 GiB on an 8 GiB machine). The 26.08.0 DDI is 365 MiB compressed / 1.58 GiB raw, andzstd --rmremoves the compressed copy only after a successful decompress, so the staging tmpfs must hold ~1.95 GiB at once. On the releasedinstaller-v26.08.0PXE initrd that fails on anything below ~10 GiB of RAM (1.95 GiB / 20 %):Reproduced in QEMU (OVMF, q35/KVM) at 8 GiB with the released initrd; passes at 16 GiB. Found while integrating with the jeefy/booty PXE server.
Fix
/dev/shm/installer: PID 1 mounts/dev/shmwithout asize=option, so it gets the kernel tmpfs default of 50 % of RAM. The wrapper first checksmountpoint -q /dev/shmso it never stages on devtmpfs.WARN) against bothdf -k --output=availof the staging directory andMemAvailablefrom/proc/meminfominus 256 MiB of headroom — in KiB, rounded up, so MiB truncation cannot wave through an image a few KiB too large — and abort with all the numbers instead of dying mid-write or being OOM-killed:ERROR: not enough RAM-backed temporary space in /dev/shm/installer to decompress the DDI (need ~N MiB; tmpfs has M MiB free, MemAvailable is K MiB with 256 MiB headroom); add RAM to this machine.The
MemAvailablebound matters because the tmpfs cap is not proof of memory: the unpacked initrd is its own tmpfs, sodfon/dev/shmcan report space the kernel cannot back.dffailure or unparsable output fails closed with a message./layer/run/installer(the wrapper creates its own staging dir).mountpoint,stat,df,tailjoin the Step 1a build-time tool check.Docs:
ddi-installer.mdreplaces the "~8 GiB guidance" line with a Memory requirements section (why/runcannot hold the DDI, both copies must fit, the check needsMemAvailableafter the download ≥ raw DDI + 256 MiB and the/dev/shmcap to hold both copies; 8 GiB tested and recommended for the 26.08.0 Flatcar-based DDI, smaller machines not boot-tested — the earlier "computed minimum ≈4 GiB" is gone because the tmpfs-only arithmetic could pass the check and still OOM), adds a Common Rationalizations row and fixes the "2 GiB+" DDI size to ≈1.6 GiB raw.Verification
tests/unit/test_installer_contract.py:test_installer_network_ddi_stages_in_dev_shm_with_space_preflight—mountpointguard, staging path, no/run/installer, preflight ordered betweensha256sum --checkandzstd -d,MemAvailableread fromDDI_MEMINFO.test_installer_space_preflight_uses_the_zstd_frame_header— runs the extracted preflight block against a real zstd frame with a stand-in right-aligneddfand a fake/proc/meminfo(the block'sDDI_MEMINFO=/proc/meminfois overridden): a 3 MiB + 1 B raw image passes with 3073 KiB free, fails with 3072 KiB, and the message carriesneed ~4 MiB; tmpfs has 3 MiB free, MemAvailable is 65536 MiB.test_installer_space_preflight_is_bounded_by_mem_available— huge tmpfs,MemAvailable= headroom + 3073 KiB passes, + 3072 KiB fails; a meminfo withoutMemAvailablefails closed.test_installer_space_preflight_falls_back_to_five_times_compressed— non-zstd payload, 5× rule, one-KiB boundary,WARNemitted.main's element; theMemAvailabletest also fails against the round-1 tmpfs-only check (verified by mutation). The tests use the sharedinstaller_wrapperfixture from fix(installer): rewrite the network DDI repart override without sed #250.python3 -m pytest tests/unit -q— 352 passed, 1 xfailed (pre-existing).bash -n+shellcheck -S warningon the extracted wrapper — clean.python3 .github/scripts/docs-checks.py+ thecheck-*scripts — pass.just validate/just build-installer(no local BuildStream)./dev/shmstaging + wait-online +inst.creds_url) was dropped into the releasedinstaller-v26.08.0initrd; decompression succeeds and the install completes where the released initrd hitENOSPC. The preflight abort path was not booted (no machine small enough was tried) — it is covered by the executed unit tests only, and the KiB-rounding change post-dates the QEMU run.Review round 2
Applied from the line-by-line review:
MemAvailablebound (bashwhile readover/proc/meminfo, no awk) with 256 MiB headroom; the error prints tmpfs free,MemAvailableand the need. Docs drop the "≈4 GiB computed minimum" for "the check needsMemAvailable≥ raw + headroom; 8 GiB tested".mountpoint -q /dev/shmguard;dffailure / non-numeric output fail closed;WARNwhen the zstd header carries no size (5× fallback); "systemd caps/dev/shmat 50 %" → kernel tmpfs default,/runissize=20%; "2 GiB+" row fixed; fakedfright-aligned like the real one; block slice ends at a^\s*fi$line; PR/commit title says "before decompressing".trap … ERRcleanup of/dev/shm/installer(the unit isFailureAction=poweroff, so cleanup on the failure paths has no observable effect).build(run 36259015748) passed; the new build is running.