diff --git a/docs/skills/ddi-installer.md b/docs/skills/ddi-installer.md index 4699417a..a22f5cd5 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 @@ -52,13 +52,18 @@ system credentials so the base image remains stateless. `systemd-sysusers` consumes root account records, `systemd-tmpfiles` consumes `tmpfiles.extra` for arbitrary first-boot files, and `systemd-network-generator` consumes `network.conf.*` / `network.link.*` / `network.netdev.*` / -`network.network.*` credentials before networkd starts. The stock interactive -`systemd-firstboot.service` stays masked, but -`bluefin-firstboot-credentials.service` runs `systemd-firstboot` -non-interactively when `firstboot.locale`, `firstboot.timezone`, -`firstboot.hostname`, or related credentials are present. When -`firstboot.hostname` is supplied, the service also applies the live kernel -hostname before `systemd-networkd` starts so first-boot DHCP uses it. With no +`network.network.*` credentials before networkd starts. Flatcar's `/usr` is +built without `systemd-firstboot`, so `bluefin-firstboot-credentials.service` +runs `/usr/libexec/bluefin-firstboot-credentials` (bash + coreutils) when +`firstboot.locale`, `firstboot.locale-messages`, `firstboot.keymap`, +`firstboot.timezone` or `firstboot.hostname` are present; it validates every +value (ASCII-only, at least as strict as systemd's own validators) and writes +the same files `systemd-firstboot` would (`/etc/locale.conf`, +`/etc/vconsole.conf`, `/etc/localtime`) and additionally `/etc/hostname` plus +the live kernel hostname — systemd ≤ v259 (Flatcar's) has no +`firstboot.hostname`; v260 added it as a static hostname applied only when +none is set, whereas Bluefin applies it unconditionally — before +`systemd-networkd` starts so first-boot DHCP uses it. With no credentials, the target keeps the default DHCP network and does not prompt. The target DDI also pre-stages the extracted CA certificate bundle diff --git a/docs/skills/tpm2-credential-sealing.md b/docs/skills/tpm2-credential-sealing.md index 1fa319e1..ed80e4b9 100644 --- a/docs/skills/tpm2-credential-sealing.md +++ b/docs/skills/tpm2-credential-sealing.md @@ -4,7 +4,7 @@ description: Securing provisioning credentials (such as hashed root passwords or metadata: type: how-to status: stable - last_updated: "2026-09-07" + last_updated: "2026-09-26" context7-sources: - /systemd/systemd --- @@ -21,7 +21,7 @@ decrypts and routes at boot: | Credential | Consumer | Purpose | |---|---|---| -| `passwd.hashed-password.root` | `systemd-sysusers` / `systemd-firstboot` | Optional root password hash for break-glass provisioning. | +| `passwd.hashed-password.root` | `systemd-sysusers` | Optional root password hash for break-glass provisioning. | | `tmpfiles.extra` | `systemd-tmpfiles` | Extra tmpfiles rules, such as writing an operator's SSH `authorized_keys`. | | `network.network.*`, `network.netdev.*`, `network.link.*`, `network.conf.*` | `systemd-network-generator` | Static network, routes, virtual devices, and networkd config. | | `network.dns`, `network.search_domains` | `systemd-resolved` | DNS resolver defaults. | diff --git a/elements/bluefin-server/os-creds-prov.bst b/elements/bluefin-server/os-creds-prov.bst index 11440c23..2ecea907 100644 --- a/elements/bluefin-server/os-creds-prov.bst +++ b/elements/bluefin-server/os-creds-prov.bst @@ -3,7 +3,16 @@ kind: manual description: | Install first-boot systemd credential provisioning contracts into the target OS. Supports sysusers credentials, systemd-network-generator network.* credentials, - and a non-interactive systemd-firstboot credential gate. + and the firstboot.* credentials (locale, keymap, timezone, hostname). + + Flatcar's /usr is built without systemd-firstboot, so the firstboot.* + credentials are applied by /usr/libexec/bluefin-firstboot-credentials, a + bash + coreutils helper that writes the same files systemd-firstboot would + (/etc/locale.conf, /etc/vconsole.conf, /etc/localtime) and additionally + /etc/hostname plus the live kernel hostname from firstboot.hostname, which + systemd <= v259 (Flatcar's) does not read; systemd v260 added it as a + static hostname honoured only when none is set, while this helper applies + it unconditionally. build-depends: - base/base-stack.bst @@ -15,6 +24,9 @@ sources: - kind: local path: files/os/creds/systemd/system directory: systemd-src + - kind: local + path: files/os/libexec + directory: libexec-src # Disable binary stripping; this element only installs text files and the # runtime-minimal sandbox does not include the stripper toolchain. @@ -29,3 +41,5 @@ config: install -Dm0644 sysusers-src/*.conf -t "%{install-root}/usr/lib/sysusers.d/" mkdir -p "%{install-root}/usr/lib/systemd/system" cp -a systemd-src/. "%{install-root}/usr/lib/systemd/system/" + install -Dm0755 libexec-src/bluefin-firstboot-credentials \ + "%{install-root}/usr/libexec/bluefin-firstboot-credentials" diff --git a/files/os/creds/systemd/system/bluefin-firstboot-credentials.service b/files/os/creds/systemd/system/bluefin-firstboot-credentials.service index 82e49eca..8223d1c5 100644 --- a/files/os/creds/systemd/system/bluefin-firstboot-credentials.service +++ b/files/os/creds/systemd/system/bluefin-firstboot-credentials.service @@ -1,6 +1,6 @@ [Unit] Description=Apply Bluefin first-boot system credentials -Documentation=man:systemd-firstboot(1) man:systemd.system-credentials(7) +Documentation=man:systemd.system-credentials(7) file:/usr/libexec/bluefin-firstboot-credentials ConditionPathIsReadWrite=/etc DefaultDependencies=no After=systemd-remount-fs.service systemd-sysusers.service systemd-tmpfiles-setup.service @@ -19,8 +19,7 @@ ImportCredential=firstboot.locale-messages ImportCredential=firstboot.keymap ImportCredential=firstboot.timezone ImportCredential=firstboot.hostname -ExecStart=systemd-firstboot --force --welcome=no -ExecStartPost=/bin/bash -eu -c 'if [ -n "$${CREDENTIALS_DIRECTORY:-}" ] && [ -s "$$CREDENTIALS_DIRECTORY/firstboot.hostname" ]; then hostname="$$(<"$$CREDENTIALS_DIRECTORY/firstboot.hostname")"; /usr/bin/hostname "$$hostname"; fi' +ExecStart=/usr/libexec/bluefin-firstboot-credentials ExecStartPost=/usr/bin/touch /etc/.bluefin-firstboot-credentials RemainAfterExit=yes diff --git a/files/os/libexec/bluefin-firstboot-credentials b/files/os/libexec/bluefin-firstboot-credentials new file mode 100755 index 00000000..5b90d941 --- /dev/null +++ b/files/os/libexec/bluefin-firstboot-credentials @@ -0,0 +1,135 @@ +#!/usr/bin/bash +# bluefin-firstboot-credentials — apply the firstboot.* system credentials. +# +# Writes the same files systemd-firstboot(1) would write, in the same format: +# firstboot.locale, firstboot.locale-messages -> /etc/locale.conf +# firstboot.keymap -> /etc/vconsole.conf +# firstboot.timezone -> /etc/localtime +# and additionally (systemd <= v259, Flatcar's, has no firstboot.hostname; +# systemd v260 added it as a static hostname applied only when none is set. +# Bluefin applies it unconditionally and also sets the live kernel hostname +# so the first DHCP request carries the name): +# firstboot.hostname -> /etc/hostname + kernel hostname +# from $CREDENTIALS_DIRECTORY, as populated by ImportCredential= in +# bluefin-firstboot-credentials.service. The OS payload is Flatcar's /usr, +# which is built without systemd-firstboot, so the unit cannot call it. +# +# Known differences from systemd-firstboot: trailing newlines in a credential +# are stripped rather than rejected; LC_MESSAGES= is written even when it +# equals LANG=; locales and keymaps are shape-checked, not checked against +# what is installed; timezones must exist under /usr/share/zoneinfo. The +# validators below are at least as strict as systemd's and ASCII-only (systemd +# accepts e.g. spaces and non-ASCII in locales, and '_' in hostnames). +# +# Every value is validated before anything is written; an invalid credential +# fails the whole run and leaves /etc untouched, so the unit fails visibly +# instead of applying a partial configuration. +# +# Deliberately bash builtins plus coreutils only: this runs before sysinit.target. +# +# Usage: bluefin-firstboot-credentials [--root=DIR] +# --root is for tests; the shipped unit passes nothing and writes to /. + +set -euo pipefail +# [[:alnum:]] in bash regexes is locale-dependent and PID 1 exports the LANG +# this helper itself writes to locale.conf; systemd's validators are ASCII-only. +export LC_ALL=C + +PROG="${0##*/}" +ROOT="" +for arg in "$@"; do + case "${arg}" in + --root=*) ROOT="${arg#--root=}"; ROOT="${ROOT%/}" ;; + *) printf '%s: unknown argument: %s\n' "${PROG}" "${arg}" >&2; exit 2 ;; + esac +done + +log() { printf '%s: %s\n' "${PROG}" "$*" >&2; } +die() { log "$*"; exit 1; } +# die_value MESSAGE VALUE: the value is %q-quoted so a stray CR or other +# control character in a credential shows up in the journal instead of vanishing. +die_value() { die "$1 $(printf '%q' "$2")"; } + +[ -n "${CREDENTIALS_DIRECTORY:-}" ] || die "CREDENTIALS_DIRECTORY is not set; run from a unit with ImportCredential=firstboot.*" + +[ -d "${CREDENTIALS_DIRECTORY}" ] || die "CREDENTIALS_DIRECTORY ${CREDENTIALS_DIRECTORY} is not a directory" + +# Returns the credential content with trailing newlines removed, or nothing +# when the credential is absent or empty. $( "${ROOT}/etc/locale.conf" + log "wrote /etc/locale.conf" +fi + +if [ -n "${KEYMAP}" ]; then + printf 'KEYMAP=%s\n' "${KEYMAP}" > "${ROOT}/etc/vconsole.conf" + log "wrote /etc/vconsole.conf" +fi + +if [ -n "${TIMEZONE}" ]; then + ln -sfn "../usr/share/zoneinfo/${TIMEZONE}" "${ROOT}/etc/localtime" + log "set /etc/localtime -> ${TIMEZONE}" +fi + +if [ -n "${HOSTNAME_VALUE}" ]; then + printf '%s\n' "${HOSTNAME_VALUE}" > "${ROOT}/etc/hostname" + # PID 1 already applied the image's /etc/hostname before this unit ran, so + # also set the live kernel hostname for the DHCP request networkd is about + # to send. + if [ -z "${ROOT}" ] && [ -w /proc/sys/kernel/hostname ]; then + printf '%s' "${HOSTNAME_VALUE}" > /proc/sys/kernel/hostname + fi + log "set hostname ${HOSTNAME_VALUE}" +fi + +# The unit's ExecStartPost stamp gates re-runs; flush the writes above before +# it is created so a power loss cannot leave the stamp without the files. +sync diff --git a/tests/unit/test_credentials_provisioning.py b/tests/unit/test_credentials_provisioning.py index 852207e1..eb5cad83 100644 --- a/tests/unit/test_credentials_provisioning.py +++ b/tests/unit/test_credentials_provisioning.py @@ -44,6 +44,7 @@ / "systemd-network-generator.service.d" / "10-bluefin-credentials.conf" ) +FIRSTBOOT_HELPER = REPO_ROOT / "files" / "os" / "libexec" / "bluefin-firstboot-credentials" NETWORK = REPO_ROOT / "files" / "os" / "systemd" / "network" / "20-wired.network" TPM2_SKILL = REPO_ROOT / "docs" / "skills" / "tpm2-credential-sealing.md" @@ -59,11 +60,16 @@ def test_creds_provisioning_element_stages_all_credential_consumers() -> None: assert sources == { "sysusers-src": "files/os/sysusers.d", "systemd-src": "files/os/creds/systemd/system", + "libexec-src": "files/os/libexec", } commands = "\n".join(data["config"]["install-commands"]) assert "/usr/lib/sysusers.d/" in commands assert "cp -a systemd-src/." in commands + assert "install -Dm0755 libexec-src/bluefin-firstboot-credentials" in commands + assert '"%{install-root}/usr/libexec/bluefin-firstboot-credentials"' in commands + assert FIRSTBOOT_HELPER.is_file() + assert FIRSTBOOT_HELPER.stat().st_mode & 0o111 def test_firstboot_credentials_are_noninteractive_and_presence_gated() -> None: @@ -79,17 +85,13 @@ def test_firstboot_credentials_are_noninteractive_and_presence_gated() -> None: assert f"ConditionCredential=|{credential}" in unit assert f"ImportCredential={credential}" in unit - assert "ExecStart=systemd-firstboot --force --welcome=no" in unit - assert '/usr/bin/hostname "$$hostname"' in unit - assert unit.index("/usr/bin/hostname") < unit.index("/usr/bin/touch /etc/.bluefin-firstboot-credentials") - # Verify that shell variables in ExecStartPost are escaped with $$ so systemd does not expand them - exec_post_lines = [ - line for line in unit.splitlines() if line.startswith("ExecStartPost=") - ] - hostname_post = [line for line in exec_post_lines if "/usr/bin/hostname" in line][0] - assert "$$hostname" in hostname_post - assert "$$CREDENTIALS_DIRECTORY" in hostname_post - assert "$hostname" not in hostname_post.replace("$$hostname", "") + # Flatcar's /usr ships no systemd-firstboot: the unit must not call it, or + # it fails at step EXEC and every firstboot.* credential is a silent no-op. + assert "systemd-firstboot" not in unit + assert "ExecStart=/usr/libexec/bluefin-firstboot-credentials" in unit + assert unit.index("ExecStart=/usr/libexec/bluefin-firstboot-credentials") < unit.index( + "ExecStartPost=/usr/bin/touch /etc/.bluefin-firstboot-credentials" + ) assert "--prompt" not in unit assert "ConditionPathIsReadWrite=/etc" in unit assert "ConditionPathExists=!/etc/.bluefin-firstboot-credentials" in unit diff --git a/tests/unit/test_firstboot_credentials_behavior.py b/tests/unit/test_firstboot_credentials_behavior.py new file mode 100644 index 00000000..23b096cf --- /dev/null +++ b/tests/unit/test_firstboot_credentials_behavior.py @@ -0,0 +1,213 @@ +"""Executed coverage for files/os/libexec/bluefin-firstboot-credentials. + +The helper replaces `systemd-firstboot --force --welcome=no` in +bluefin-firstboot-credentials.service because Flatcar's /usr is built without +systemd-firstboot. These tests drive it under bash against a scratch --root +with credentials laid out the way ImportCredential= presents them. +""" + +from __future__ import annotations + +import os +import shutil +import subprocess +from pathlib import Path + +import pytest + +REPO_ROOT = Path(__file__).resolve().parents[2] +HELPER = REPO_ROOT / "files" / "os" / "libexec" / "bluefin-firstboot-credentials" + + +def _run(tmp_path: Path, creds: dict[str, str], zoneinfo: tuple[str, ...] = ("Europe/Berlin", "UTC")): + root = tmp_path / "root" + creds_dir = tmp_path / "creds" + creds_dir.mkdir(parents=True) + for name, value in creds.items(): + (creds_dir / name).write_text(value, encoding="utf-8") + for tz in zoneinfo: + target = root / "usr" / "share" / "zoneinfo" / tz + target.parent.mkdir(parents=True, exist_ok=True) + target.write_bytes(b"TZif2") + (root / "etc").mkdir(parents=True, exist_ok=True) + env = dict(os.environ, CREDENTIALS_DIRECTORY=str(creds_dir)) + result = subprocess.run( + ["bash", str(HELPER), f"--root={root}"], + capture_output=True, + text=True, + env=env, + ) + return root, result + + +def test_helper_is_bash_that_passes_syntax() -> None: + # /usr/bin/bash, not /bin/bash: /bin is a tmpfiles-created symlink on + # Flatcar and the unit runs before sysinit.target. + assert HELPER.read_text(encoding="utf-8").startswith("#!/usr/bin/bash\n") + subprocess.run(["bash", "-n", str(HELPER)], check=True) + + +@pytest.mark.skipif(shutil.which("shellcheck") is None, reason="shellcheck not installed") +def test_helper_is_shellcheck_clean_at_warning_level() -> None: + subprocess.run(["shellcheck", "-S", "warning", str(HELPER)], check=True) + + +def test_all_five_credentials_write_what_systemd_firstboot_would(tmp_path: Path) -> None: + root, result = _run( + tmp_path, + { + "firstboot.locale": "de_DE.UTF-8\n", + "firstboot.locale-messages": "en_US.UTF-8", + "firstboot.keymap": "de-latin1\n", + "firstboot.timezone": "Europe/Berlin\n", + "firstboot.hostname": "node-01.lab.example\n", + }, + ) + assert result.returncode == 0, result.stderr + assert (root / "etc" / "locale.conf").read_text() == "LANG=de_DE.UTF-8\nLC_MESSAGES=en_US.UTF-8\n" + assert (root / "etc" / "vconsole.conf").read_text() == "KEYMAP=de-latin1\n" + localtime = root / "etc" / "localtime" + assert localtime.is_symlink() + assert os.readlink(localtime) == "../usr/share/zoneinfo/Europe/Berlin" + assert (root / "etc" / "hostname").read_text() == "node-01.lab.example\n" + + +def test_only_supplied_credentials_are_applied(tmp_path: Path) -> None: + root, result = _run(tmp_path, {"firstboot.hostname": "pxe-client"}) + assert result.returncode == 0, result.stderr + assert (root / "etc" / "hostname").read_text() == "pxe-client\n" + assert not (root / "etc" / "locale.conf").exists() + assert not (root / "etc" / "vconsole.conf").exists() + assert not (root / "etc" / "localtime").exists() + + +def test_existing_files_are_overwritten_like_force(tmp_path: Path) -> None: + root = tmp_path / "root" + (root / "etc").mkdir(parents=True) + (root / "etc" / "hostname").write_text("localhost\n") + (root / "etc" / "localtime").symlink_to("../usr/share/zoneinfo/UTC") + _, result = _run( + tmp_path, {"firstboot.hostname": "renamed", "firstboot.timezone": "Europe/Berlin"} + ) + assert result.returncode == 0, result.stderr + assert (root / "etc" / "hostname").read_text() == "renamed\n" + assert os.readlink(root / "etc" / "localtime") == "../usr/share/zoneinfo/Europe/Berlin" + + +@pytest.mark.parametrize( + ("creds", "message"), + [ + ({"firstboot.hostname": "bad host"}, "invalid hostname"), + ({"firstboot.hostname": "-leading"}, "invalid hostname"), + ({"firstboot.hostname": "trailing-"}, "invalid hostname"), + ({"firstboot.hostname": "foo-.bar"}, "invalid hostname"), + ({"firstboot.hostname": "foo..bar"}, "invalid hostname"), + ({"firstboot.hostname": "h\u00f4te"}, "invalid hostname"), + ({"firstboot.hostname": "host\r"}, "invalid hostname"), + ({"firstboot.hostname": "a" * 65}, "invalid hostname"), + ({"firstboot.timezone": "../../etc/passwd"}, "invalid or unknown timezone"), + ({"firstboot.timezone": "Mars/Olympus"}, "invalid or unknown timezone"), + ({"firstboot.locale": "en_US.UTF-8; rm -rf /"}, "invalid locale"), + ({"firstboot.keymap": "us/../../x"}, "invalid keymap"), + ], +) +def test_invalid_values_fail_without_writing(tmp_path: Path, creds: dict[str, str], message: str) -> None: + root, result = _run(tmp_path, {"firstboot.hostname": "good", **creds}) + assert result.returncode == 1 + assert message in result.stderr + assert sorted(p.name for p in (root / "etc").iterdir()) == [] + + +def test_non_ascii_keymap_is_rejected_under_a_utf8_locale(tmp_path: Path) -> None: + # PID 1 exports LANG from the locale.conf this helper writes; systemd's + # validators are ASCII-only, so [[:alnum:]] must not widen with the locale. + # The keymap regex uses [[:alnum:]] (the hostname one is literal + # [A-Za-z0-9], which does not widen under C.UTF-8), so this test fails if + # the helper's `export LC_ALL=C` is removed: "hôte" would then be written + # to vconsole.conf as a valid keymap. + root = tmp_path / "root" + creds_dir = tmp_path / "creds" + creds_dir.mkdir() + (creds_dir / "firstboot.keymap").write_text("h\u00f4te", encoding="utf-8") + (creds_dir / "firstboot.locale").write_text("h\u00f4te", encoding="utf-8") + (root / "etc").mkdir(parents=True) + env = dict(os.environ, CREDENTIALS_DIRECTORY=str(creds_dir), LC_ALL="C.UTF-8", LANG="C.UTF-8") + result = subprocess.run(["bash", str(HELPER), f"--root={root}"], capture_output=True, text=True, env=env) + assert result.returncode == 1 + assert "invalid locale" in result.stderr or "invalid keymap" in result.stderr + assert sorted(p.name for p in (root / "etc").iterdir()) == [] + + +def test_keymap_length_is_capped_like_systemd(tmp_path: Path) -> None: + # keymap_is_valid() requires strlen < 128. + root, result = _run(tmp_path, {"firstboot.keymap": "k" * 127}) + assert result.returncode == 0, result.stderr + assert (root / "etc" / "vconsole.conf").read_text() == "KEYMAP=" + "k" * 127 + "\n" + root, result = _run(tmp_path / "long", {"firstboot.keymap": "k" * 128}) + assert result.returncode == 1 + assert "invalid keymap" in result.stderr + + +def test_locale_only_and_messages_only_write_a_single_line(tmp_path: Path) -> None: + # The `{ [ -n ] && printf; ... } > file` group must not trip errexit when + # one of the two values is empty. + root, result = _run(tmp_path / "lang", {"firstboot.locale": "de_DE.UTF-8"}) + assert result.returncode == 0, result.stderr + assert (root / "etc" / "locale.conf").read_text() == "LANG=de_DE.UTF-8\n" + root, result = _run(tmp_path / "msgs", {"firstboot.locale-messages": "en_US.UTF-8"}) + assert result.returncode == 0, result.stderr + assert (root / "etc" / "locale.conf").read_text() == "LC_MESSAGES=en_US.UTF-8\n" + _, result = _run(tmp_path / "bad", {"firstboot.locale-messages": "en_US; rm -rf /"}) + assert result.returncode == 1 + assert "invalid locale" in result.stderr + + +def test_control_characters_in_a_rejected_value_are_made_visible(tmp_path: Path) -> None: + _, result = _run(tmp_path, {"firstboot.hostname": "host\r"}) + assert result.returncode == 1 + assert "invalid hostname in credential: $'host\\r'" in result.stderr + + +def test_hostname_labels_may_contain_interior_hyphens_and_digits(tmp_path: Path) -> None: + root, result = _run(tmp_path, {"firstboot.hostname": "a-1.b-2-c.example"}) + assert result.returncode == 0, result.stderr + assert (root / "etc" / "hostname").read_text() == "a-1.b-2-c.example\n" + + +def test_nul_byte_in_a_credential_is_rejected(tmp_path: Path) -> None: + # $( None: + env = dict(os.environ, CREDENTIALS_DIRECTORY=str(tmp_path / "missing")) + result = subprocess.run( + ["bash", str(HELPER), f"--root={tmp_path}"], capture_output=True, text=True, env=env + ) + assert result.returncode == 1 + assert "is not a directory" in result.stderr + + +def test_missing_credentials_directory_is_an_error(tmp_path: Path) -> None: + env = {k: v for k, v in os.environ.items() if k != "CREDENTIALS_DIRECTORY"} + result = subprocess.run( + ["bash", str(HELPER), f"--root={tmp_path}"], capture_output=True, text=True, env=env + ) + assert result.returncode == 1 + assert "CREDENTIALS_DIRECTORY is not set" in result.stderr + + +def test_empty_credential_is_treated_as_absent(tmp_path: Path) -> None: + root, result = _run(tmp_path, {"firstboot.hostname": "ok", "firstboot.keymap": "\n"}) + assert result.returncode == 0, result.stderr + assert not (root / "etc" / "vconsole.conf").exists() + assert (root / "etc" / "hostname").read_text() == "ok\n"