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
21 changes: 13 additions & 8 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 @@ -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
Expand Down
4 changes: 2 additions & 2 deletions docs/skills/tpm2-credential-sealing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
---
Expand All @@ -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. |
Expand Down
16 changes: 15 additions & 1 deletion elements/bluefin-server/os-creds-prov.bst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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"
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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

Expand Down
135 changes: 135 additions & 0 deletions files/os/libexec/bluefin-firstboot-credentials
Original file line number Diff line number Diff line change
@@ -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. $(<file) silently drops NUL bytes,
# which systemd's read_credential() rejects, so refuse them explicitly.
read_credential() {
local file="${CREDENTIALS_DIRECTORY}/$1" value
[ -s "${file}" ] || return 0
[ "$(tr -d '\0' <"${file}" | wc -c)" -eq "$(wc -c <"${file}")" ] \
|| die "NUL byte in credential $1"
value="$(<"${file}")"
printf '%s' "${value}"
}

LOCALE="$(read_credential firstboot.locale)"
LOCALE_MESSAGES="$(read_credential firstboot.locale-messages)"
KEYMAP="$(read_credential firstboot.keymap)"
TIMEZONE="$(read_credential firstboot.timezone)"
HOSTNAME_VALUE="$(read_credential firstboot.hostname)"

# At least as strict as systemd's locale_is_valid(), keymap_is_valid(),
# timezone_is_valid() and hostname_is_valid(); length caps match theirs.
LOCALE_RE='^[[:alnum:]][[:alnum:]_.@+-]*$'
KEYMAP_RE='^[[:alnum:]][[:alnum:]_.-]*$'
TIMEZONE_RE='^[[:alnum:]_+-]+(/[[:alnum:]_+-]+)*$'
HOSTNAME_RE='^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)*$'

for value in "${LOCALE}" "${LOCALE_MESSAGES}"; do
if [ -n "${value}" ]; then
[[ "${value}" =~ ${LOCALE_RE} ]] && [ "${#value}" -lt 128 ] \
|| die_value "invalid locale in credential:" "${value}"
fi
done
if [ -n "${KEYMAP}" ]; then
[[ "${KEYMAP}" =~ ${KEYMAP_RE} ]] && [ "${#KEYMAP}" -lt 128 ] \
|| die_value "invalid keymap in credential:" "${KEYMAP}"
fi
if [ -n "${TIMEZONE}" ]; then
[[ "${TIMEZONE}" =~ ${TIMEZONE_RE} ]] && [ -f "${ROOT}/usr/share/zoneinfo/${TIMEZONE}" ] \
|| die_value "invalid or unknown timezone in credential:" "${TIMEZONE}"
fi
if [ -n "${HOSTNAME_VALUE}" ]; then
[[ "${HOSTNAME_VALUE}" =~ ${HOSTNAME_RE} ]] && [ "${#HOSTNAME_VALUE}" -le 64 ] \
|| die_value "invalid hostname in credential:" "${HOSTNAME_VALUE}"
fi

umask 022
mkdir -p "${ROOT}/etc"

if [ -n "${LOCALE}" ] || [ -n "${LOCALE_MESSAGES}" ]; then
{
[ -n "${LOCALE}" ] && printf 'LANG=%s\n' "${LOCALE}"
[ -n "${LOCALE_MESSAGES}" ] && printf 'LC_MESSAGES=%s\n' "${LOCALE_MESSAGES}"
} > "${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
24 changes: 13 additions & 11 deletions tests/unit/test_credentials_provisioning.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand All @@ -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:
Expand All @@ -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
Expand Down
Loading