From fb5ed94ce6054e1ca6f739f087c2b3b08bec03c7 Mon Sep 17 00:00:00 2001 From: Danathar Date: Fri, 11 Sep 2026 11:47:43 -0400 Subject: [PATCH 1/2] test: validate Bluefin first-boot runtime Add an in-image first-boot diagnostic and extend the desktop contract to cover setup hooks, service enablement, retryable Flatpak state, optional Tailscale setup, and repeat-boot evidence. Make required service policy fail loudly and keep the stats unit runnable after image cleanup. Assisted-by: GPT-5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Danathar --- Containerfile | 4 +- Justfile | 8 + contracts/bluefin-desktop.toml | 29 ++ docs/building.md | 5 + docs/skills/desktop-contract.md | 46 ++- docs/skills/index.json | 4 +- docs/skills/index.md | 2 +- scripts/configure-services.sh | 52 ++-- scripts/verify-desktop-contract.py | 64 +++- scripts/verify-first-boot.sh | 286 ++++++++++++++++++ .../system-preset/85-utah-desktop.preset | 5 + .../system/bluefin-stats-refresh.service | 5 +- .../privileged-setup.hooks.d/10-tailscale.sh | 48 ++- tests/unit/test_first_boot.py | 149 +++++++++ 14 files changed, 665 insertions(+), 42 deletions(-) create mode 100755 scripts/verify-first-boot.sh create mode 100755 tests/unit/test_first_boot.py diff --git a/Containerfile b/Containerfile index fa5246d3..2893a230 100644 --- a/Containerfile +++ b/Containerfile @@ -57,6 +57,7 @@ COPY scripts/install-packages.py \ scripts/configure-services.sh \ scripts/configure-branding.sh \ scripts/verify-desktop-contract.py \ + scripts/verify-first-boot.sh \ scripts/verify-gnome-extensions.py \ /tmp/utah-scripts/ # Common publishes Bluefin artwork, desktop defaults, Brewfiles, and setup @@ -77,8 +78,9 @@ RUN for pair in install-packages.py:utah-install-packages \ configure-services.sh:utah-configure-services \ configure-branding.sh:utah-configure-branding \ verify-desktop-contract.py:utah-verify-desktop-contract \ + verify-first-boot.sh:utah-verify-first-boot \ verify-gnome-extensions.py:utah-verify-gnome-extensions; do \ - install -m 0755 "/tmp/utah-scripts/${pair%%:*}" "/usr/local/libexec/${pair##*:}" || exit 1; \ + install -Dm0755 "/tmp/utah-scripts/${pair%%:*}" "/usr/local/libexec/${pair##*:}" || exit 1; \ done && \ cp -a /tmp/utah-common/. / && \ cp -a /tmp/utah-bluefin/. / && \ diff --git a/Justfile b/Justfile index 6706129f..6fc9c5ab 100644 --- a/Justfile +++ b/Justfile @@ -21,6 +21,8 @@ check: grep -q 'enable ublue-system-setup.service' system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset test -f scripts/configure-services.sh bash -n scripts/configure-services.sh + test -f scripts/verify-first-boot.sh + bash -n scripts/verify-first-boot.sh test -f scripts/configure-branding.sh bash -n scripts/configure-branding.sh test -f scripts/verify-desktop-contract.py @@ -33,10 +35,16 @@ check: git submodule update --init --recursive python3 -m py_compile scripts/verify-desktop-contract.py scripts/verify-gnome-extensions.py python3 scripts/verify-desktop-contract.py --check contracts/bluefin-desktop.toml + test -f tests/unit/test_first_boot.py + python3 tests/unit/test_first_boot.py python3 scripts/verify-gnome-extensions.py --source grep -q '/system_files/bluefin' Containerfile grep -q 'flatpak-preinstall.service' scripts/configure-services.sh grep -q 'flathub.flatpakrepo' scripts/configure-services.sh + grep -q 'input-remapper.service' scripts/configure-services.sh + grep -q 'bluefin-stats-refresh.timer' scripts/configure-services.sh + grep -q 'UTAH_FIRST_BOOT_OK' scripts/verify-first-boot.sh + grep -q 'UTAH_EXPECT_REPEAT' scripts/verify-first-boot.sh test -f iso/live/Containerfile test -f iso/live/src/configure-live.sh test -f iso/live/src/install-flatpaks.sh diff --git a/contracts/bluefin-desktop.toml b/contracts/bluefin-desktop.toml index 5fbada3a..493f0106 100644 --- a/contracts/bluefin-desktop.toml +++ b/contracts/bluefin-desktop.toml @@ -129,14 +129,43 @@ apps = [ "page.tesk.Refine", ] +[first_boot] +# These are the hooks copied into the image by Utah or the Bluefin-derived +# common layer. The runtime verifier syntax-checks every one before checking +# first-boot service results. +hooks = [ + "/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh", + "/usr/share/ublue-os/privileged-setup.hooks.d/11-framework-ucsi-workaround.sh", + "/usr/share/ublue-os/privileged-setup.hooks.d/99-flatpaks.sh", + "/usr/share/ublue-os/user-setup.hooks.d/12-gnupg.sh", + "/usr/share/ublue-os/user-setup.hooks.d/20-framework.sh", + "/usr/share/ublue-os/user-setup.hooks.d/99-privileged.sh", +] +deferred_state = "/var/lib/ublue/setup-services/tailscale.deferred" + +[first_boot.file_contains] +"/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh" = [ + "command -v tailscale", + "tailscale.deferred", + "rerun ublue-privileged-setup", +] + [services] enabled = [ "bootc-unified-storage.service", + "bluefin-stats-refresh.timer", "brew-setup.service", "dconf-update.service", "flatpak-nuke-fedora.service", "flatpak-preinstall.service", "gdm.service", + "input-remapper.service", "ublue-system-setup.service", "uupd.timer", ] +user_enabled = [ + "ublue-user-setup.service", +] +optional = [ + "tailscaled.service", +] diff --git a/docs/building.md b/docs/building.md index 56ef36b0..1b105f03 100644 --- a/docs/building.md +++ b/docs/building.md @@ -11,6 +11,11 @@ just build-ghcr utah testing main just generate-bootable-image testing just boot-vm +# From the booted VM, validate first-boot units and repeat-boot state: +sudo /usr/local/libexec/utah-verify-first-boot +# Reboot, then run: +sudo UTAH_EXPECT_REPEAT=1 /usr/local/libexec/utah-verify-first-boot + # Optional local diagnostics over SSH (never use for a published image): ENABLE_SSHD=1 just build-ghcr utah testing main ``` diff --git a/docs/skills/desktop-contract.md b/docs/skills/desktop-contract.md index 5e6c1e4f..99486b2c 100644 --- a/docs/skills/desktop-contract.md +++ b/docs/skills/desktop-contract.md @@ -1,7 +1,7 @@ --- name: desktop-contract version: "1.0" -last_updated: "2026-09-05" +last_updated: "2026-09-11" id: desktop-contract one_line_purpose: Maintain Utah identity, Bluefin desktop defaults, and first-boot Flatpak policy. entry_point: docs/skills/desktop-contract.md @@ -54,10 +54,17 @@ The TOML's sections are the contract's table of contents: (`https://dl.flathub.org/repo/`), the Bazaar preinstall, the `99-flatpaks.sh` privileged-setup hook, and the system-flatpaks Brewfile whose app list the contract enumerates. +- **`[first_boot]`** — hooks that must be present and parse as shell before + the image is considered bootable. The Tailscale hook also documents the + persistent deferred-state file used when its optional binary is absent. - **`[services]`** — systemd units the preset must enable: `gdm.service`, `ublue-system-setup.service`, `flatpak-preinstall.service`, `flatpak-nuke-fedora.service`, `brew-setup.service`, `dconf-update.service`, - `bootc-unified-storage.service`, `uupd.timer`. + `bootc-unified-storage.service`, `input-remapper.service`, + `bluefin-stats-refresh.timer`, `uupd.timer`, and the global + `ublue-user-setup.service`. `tailscaled.service` is optional: when its unit + is present it must be enabled, and when its package is absent the hook must + leave a retryable state instead of invoking a missing command. ## GNOME extensions are pinned submodules @@ -98,6 +105,38 @@ under `[services]` in `packages/utah.toml` and configured in `scripts/configure-services.sh`, which also disables `PrivateTmp` on `systemd-resolved.service` for bootc early-boot DNS resolution. +`input-remapper.service` and `bluefin-stats-refresh.timer` are explicit policy, +not incidental package defaults. The stats unit checks the writable `/var` +mount and creates `/var/cache/bluefin` at execution time because image cleanup +removes build-time cache directories. + +## First-boot runtime validation + +The image contains `/usr/local/libexec/utah-verify-first-boot`. Run it from a +booted Utah system after the graphical session is available: + +```bash +sudo /usr/local/libexec/utah-verify-first-boot +``` + +It checks the enabled system and global user setup units, failed setup results, +hook syntax, the Flathub remote, the declared system Flatpaks, the update and +statistics policy, and the optional Tailscale path. It writes a persistent +key/value report to `/var/lib/utah/first-boot-status` and prints one of +`UTAH_FIRST_BOOT_OK`, `UTAH_FIRST_BOOT_RETRYABLE`, or +`UTAH_FIRST_BOOT_FAIL`. A missing network-dependent Flatpak or optional +Tailscale package is reported as retryable with the next action visible in the +report; it is not silently treated as installed. + +After rebooting the same disposable system, request the repeat-boot assertion: + +```bash +sudo UTAH_EXPECT_REPEAT=1 /usr/local/libexec/utah-verify-first-boot +``` + +The report records the boot ID and increments its boot count, so a second +invocation in the same boot cannot masquerade as a repeat-boot result. + ## The verifiers run twice The same verifier runs in the Containerfile and on demand, so a local image @@ -113,6 +152,9 @@ or a CI artifact can be checked after the fact (recipe comment, `Justfile`, already-composed image: the desktop verifier and the contract are bind-mounted from the working tree, the extension verifier runs from the image's own `/usr/local/libexec`. +- **After boot** — run `utah-verify-first-boot` in the guest. This is the only + check that can observe first-boot unit failures, actual Flatpak installation, + deferred optional setup, and a changed boot ID across a reboot. - **Off-image** — `verify-desktop-contract.py --check` validates the contract TOML itself in source-only CI and is part of `just check`; it asserts nothing about any image. diff --git a/docs/skills/index.json b/docs/skills/index.json index 9a380aa0..6749b9b7 100644 --- a/docs/skills/index.json +++ b/docs/skills/index.json @@ -1,5 +1,5 @@ { - "generated_at": "2026-09-05", + "generated_at": "2026-09-11", "schema_version": "1.0", "skills": [ { @@ -53,7 +53,7 @@ ], "description": "The runtime desktop contract in contracts/bluefin-desktop.toml and its in-image verifiers. Use when changing branding, os-release, service presets, GNOME extensions, or first-boot Flatpak behavior.", "version": "1.0", - "last_updated": "2026-09-05", + "last_updated": "2026-09-11", "doc_type": "policy" }, { diff --git a/docs/skills/index.md b/docs/skills/index.md index 2864a0b1..32e7fa05 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -3,7 +3,7 @@ This file is a human-readable mirror of `index.json`. Both are generated by `scripts/generate_skill_index.py` — do not hand-edit either file. -Generated: 2026-09-05 · schema 1.0 · 8 skills +Generated: 2026-09-11 · schema 1.0 · 8 skills | id | category | status | one-line purpose | |---|---|---|---| diff --git a/scripts/configure-services.sh b/scripts/configure-services.sh index 49e783dc..4282db18 100644 --- a/scripts/configure-services.sh +++ b/scripts/configure-services.sh @@ -25,8 +25,20 @@ user_unit_exists() { return 1 } -enable_unit() { - unit_exists "$1" && systemctl enable "$1" || true +enable_required_unit() { + if ! unit_exists "$1"; then + echo "Required desktop unit is missing: $1" >&2 + return 1 + fi + systemctl enable "$1" +} + +enable_optional_unit() { + if unit_exists "$1"; then + systemctl enable "$1" + else + echo "Optional desktop unit is unavailable; leaving it disabled: $1" + fi } disable_unit() { @@ -35,20 +47,21 @@ disable_unit() { # Services shared with Bluefin LTS. Optional units are guarded because # Hummingbird intentionally does not ship every Bluefin integration package. -enable_unit rechunker-group-fix.service -enable_unit brew-setup.service -enable_unit flatpak-nuke-fedora.service -enable_unit flatpak-preinstall.service -enable_unit gdm.service -enable_unit firewalld.service -enable_unit fwupd.service -enable_unit fwupd-refresh.timer -enable_unit dconf-update.service -enable_unit tailscaled.service -enable_unit uupd.timer -enable_unit ublue-system-setup.service -enable_unit systemd-resolved.service -enable_unit bootc-unified-storage.service +enable_optional_unit rechunker-group-fix.service +enable_required_unit brew-setup.service +enable_required_unit flatpak-nuke-fedora.service +enable_required_unit flatpak-preinstall.service +enable_required_unit gdm.service +enable_required_unit firewalld.service +enable_required_unit fwupd.service +enable_required_unit fwupd-refresh.timer +enable_required_unit dconf-update.service +enable_optional_unit tailscaled.service +enable_required_unit ublue-system-setup.service +enable_required_unit systemd-resolved.service +enable_required_unit bootc-unified-storage.service +enable_required_unit input-remapper.service +enable_required_unit bluefin-stats-refresh.timer # Bluefin's Brewfile and Bazaar preinstall hook need the Flathub remote before # first boot. Keep this as a .flatpakrepo descriptor so the remote is available @@ -68,7 +81,7 @@ systemctl mask bootc-fetch-apply-updates.timer bootc-fetch-apply-updates.service # local debug build. The preset must agree or first-boot preset-all will undo # the build-time enablement. if [[ "${ENABLE_SSHD:-0}" == "1" ]]; then - enable_unit sshd.service + enable_optional_unit sshd.service sed -i 's/^disable sshd.service$/enable sshd.service/' \ /usr/lib/systemd/system-preset/85-utah-desktop.preset else @@ -81,6 +94,9 @@ if user_unit_exists podman-auto-update.timer; then fi if user_unit_exists ublue-user-setup.service; then systemctl --global enable ublue-user-setup.service +else + echo "Required global user setup unit is missing: ublue-user-setup.service" >&2 + exit 1 fi # Match Bluefin's login behavior. The operations are idempotent and authselect @@ -93,7 +109,7 @@ authselect enable-feature with-fingerprint install -Dm0755 /tmp/uupd/uupd /usr/bin/uupd install -Dm0644 /tmp/uupd/uupd.service /usr/lib/systemd/system/uupd.service install -Dm0644 /tmp/uupd/uupd.timer /usr/lib/systemd/system/uupd.timer -systemctl enable uupd.timer +enable_required_unit uupd.timer # Avoid pulling the distrobox module on every update, as in Bluefin LTS. sed -i 's|uupd|& --disable-module-distrobox|' /usr/lib/systemd/system/uupd.service diff --git a/scripts/verify-desktop-contract.py b/scripts/verify-desktop-contract.py index d892a76c..e6d288d4 100644 --- a/scripts/verify-desktop-contract.py +++ b/scripts/verify-desktop-contract.py @@ -57,22 +57,36 @@ def parse_brewfile(path: Path) -> list[str]: return apps -def unit_enabled(unit: str) -> bool: - result = subprocess.run( - ["systemctl", "is-enabled", unit], capture_output=True, text=True, check=False - ) +def unit_exists(unit: str, *, global_scope: bool = False) -> bool: + command = ["systemctl"] + if global_scope: + command.append("--global") + command.extend(["cat", unit]) + result = subprocess.run(command, capture_output=True, text=True, check=False) + return result.returncode == 0 + + +def unit_enabled(unit: str, *, global_scope: bool = False) -> bool: + command = ["systemctl"] + if global_scope: + command.append("--global") + command.extend(["is-enabled", unit]) + result = subprocess.run(command, capture_output=True, text=True, check=False) return result.returncode == 0 and result.stdout.strip() in {"enabled", "enabled-runtime"} def validate_contract(contract: dict[str, Any]) -> list[str]: errors: list[str] = [] - for section in ("branding", "configuration", "flatpak", "services"): + for section in ("branding", "configuration", "flatpak", "first_boot", "services"): if section not in contract: errors.append(f"missing [{section}] section") - for section in ("branding", "configuration", "flatpak"): + for section in ("branding", "configuration", "flatpak", "first_boot"): for file_name in contract.get(section, {}).get("files", []): if not Path(file_name).is_absolute(): errors.append(f"{section} file must be absolute: {file_name}") + for hook_name in contract.get(section, {}).get("hooks", []): + if not Path(hook_name).is_absolute(): + errors.append(f"{section} hook must be absolute: {hook_name}") flatpak = contract.get("flatpak", {}) apps = flatpak.get("apps", []) if not apps: @@ -81,6 +95,8 @@ def validate_contract(contract: dict[str, Any]) -> list[str]: errors.append("Flatpak app contract contains duplicate IDs") if not str(flatpak.get("brewfile", "")).startswith("/"): errors.append("Flatpak Brewfile path must be absolute") + if not str(contract.get("first_boot", {}).get("deferred_state", "")).startswith("/"): + errors.append("first-boot deferred state path must be absolute") return errors @@ -102,12 +118,21 @@ def main() -> int: branding = contract["branding"] configuration = contract["configuration"] flatpak = contract["flatpak"] + first_boot = contract["first_boot"] services = contract["services"] - for section in (branding, configuration, flatpak): + for section in (branding, configuration, flatpak, first_boot): for file_name in section.get("files", []): if not Path(file_name).is_file(): errors.append(f"required file is missing: {file_name}") + for hook_name in section.get("hooks", []): + hook = Path(hook_name) + if not hook.is_file(): + errors.append(f"required first-boot hook is missing: {hook_name}") + elif subprocess.run( + ["bash", "-n", hook_name], capture_output=True, text=True, check=False + ).returncode != 0: + errors.append(f"first-boot hook is not valid shell: {hook_name}") os_release = read_os_release(Path("/usr/lib/os-release")) errors.extend( @@ -135,14 +160,15 @@ def main() -> int: ) ) - for file_name, expected_lines in configuration.get("file_contains", {}).items(): - path = Path(file_name) - if not path.is_file(): - continue - content = path.read_text() - for expected in expected_lines: - if expected not in content: - errors.append(f"{file_name} is missing required setting: {expected!r}") + for section in (configuration, first_boot): + for file_name, expected_lines in section.get("file_contains", {}).items(): + path = Path(file_name) + if not path.is_file(): + continue + content = path.read_text() + for expected in expected_lines: + if expected not in content: + errors.append(f"{file_name} is missing required setting: {expected!r}") brewfile = Path(flatpak["brewfile"]) if brewfile.is_file(): @@ -164,6 +190,14 @@ def main() -> int: if not unit_enabled(unit): errors.append(f"required service is not enabled: {unit}") + for unit in services.get("user_enabled", []): + if not unit_enabled(unit, global_scope=True): + errors.append(f"required global user service is not enabled: {unit}") + + for unit in services.get("optional", []): + if unit_exists(unit) and not unit_enabled(unit): + errors.append(f"optional service is present but not enabled: {unit}") + for error in errors: fail(error) if errors: diff --git a/scripts/verify-first-boot.sh b/scripts/verify-first-boot.sh new file mode 100755 index 00000000..fde5c1b1 --- /dev/null +++ b/scripts/verify-first-boot.sh @@ -0,0 +1,286 @@ +#!/usr/bin/env bash +# Check the parts of the Bluefin desktop contract that only become observable +# after a Utah image has booted. This is a diagnostic command, not a boot +# dependency: it reports network-dependent Flatpak work as retryable instead of +# turning an offline machine into a permanently failed boot. + +set -uo pipefail + +STATUS_FILE="${UTAH_FIRST_BOOT_STATUS_FILE:-/var/lib/utah/first-boot-status}" +TAILSCALE_DEFERRED_STATE="${UTAH_TAILSCALE_DEFERRED_STATE:-/var/lib/ublue/setup-services/tailscale.deferred}" +FLATHUB_DESCRIPTOR=/etc/flatpak/remotes.d/flathub.flatpakrepo +FLATPAK_BREWFILE=/usr/share/ublue-os/homebrew/system-flatpaks.Brewfile +DESKTOP_CONTRACT=/usr/share/utah/bluefin-desktop.toml +DESKTOP_VERIFIER=/usr/local/libexec/utah-verify-desktop-contract + +declare -a NOTES=() +declare -a MISSING_FLATPAKS=() +HARD_FAILURES=0 +RETRYABLE_FAILURES=0 + +note() { + NOTES+=("$*") + printf 'utah-first-boot: %s\n' "$*" +} + +hard_fail() { + HARD_FAILURES=$((HARD_FAILURES + 1)) + note "FAIL: $*" +} + +retryable() { + RETRYABLE_FAILURES=$((RETRYABLE_FAILURES + 1)) + note "RETRYABLE: $*" +} + +check_enabled() { + local unit="$1" + local state + state="$(systemctl is-enabled "$unit" 2>/dev/null || true)" + case "$state" in + enabled|enabled-runtime) + note "enabled: ${unit}" + ;; + *) + hard_fail "required unit is not enabled: ${unit} (${state:-not-found})" + ;; + esac +} + +check_optional_enabled() { + local unit="$1" + if systemctl cat "$unit" >/dev/null 2>&1; then + check_enabled "$unit" + else + note "optional unit is absent: ${unit}" + fi +} + +check_failed() { + local unit="$1" + local classification="$2" + if ! systemctl is-failed --quiet "$unit" 2>/dev/null; then + return 0 + fi + + if [[ "$classification" == retryable ]]; then + retryable "setup unit is failed and should be retried: ${unit}" + else + hard_fail "setup unit is failed: ${unit}" + fi + systemctl status "$unit" --no-pager -l 2>&1 | head -40 || true +} + +check_hook() { + local hook="$1" + if [[ ! -f "$hook" ]]; then + hard_fail "first-boot hook is missing: ${hook}" + return + fi + if bash -n "$hook"; then + note "hook syntax is valid: ${hook}" + else + hard_fail "first-boot hook has invalid shell syntax: ${hook}" + fi +} + +check_flatpaks() { + if [[ ! -f "$FLATHUB_DESCRIPTOR" ]]; then + hard_fail "Flathub descriptor is missing: ${FLATHUB_DESCRIPTOR}" + fi + if ! command -v flatpak >/dev/null 2>&1; then + hard_fail "flatpak is not installed" + return + fi + + local remotes + remotes="$(flatpak remotes --system --columns=name 2>/dev/null || true)" + if grep -Fxq flathub <<<"$remotes"; then + note "Flathub system remote is registered" + else + # The descriptor is immutable image state; registration can still be + # pending while flatpak-preinstall waits for network-online.target. + retryable "Flathub system remote is not registered yet" + fi + + if [[ ! -f "$FLATPAK_BREWFILE" ]]; then + hard_fail "declared system Flatpak Brewfile is missing: ${FLATPAK_BREWFILE}" + return + fi + + local installed app + installed="$(flatpak list --system --app --columns=application 2>/dev/null || true)" + while IFS= read -r app; do + [[ -n "$app" ]] || continue + if ! grep -Fxq "$app" <<<"$installed"; then + MISSING_FLATPAKS+=("$app") + fi + done < <(sed -nE 's/^[[:space:]]*flatpak[[:space:]]+"([^"]+)"[[:space:]]*$/\1/p' "$FLATPAK_BREWFILE") + + if ((${#MISSING_FLATPAKS[@]})); then + local missing + local old_ifs="$IFS" + IFS=, + missing="${MISSING_FLATPAKS[*]}" + IFS="$old_ifs" + retryable "declared system Flatpaks are pending or failed: ${missing}" + else + note "all declared system Flatpaks are installed" + fi +} + +check_tailscale() { + if command -v tailscale >/dev/null 2>&1; then + note "Tailscale binary is available" + if [[ -f "$TAILSCALE_DEFERRED_STATE" ]]; then + retryable "Tailscale still has deferred setup state: ${TAILSCALE_DEFERRED_STATE}" + fi + elif [[ -s "$TAILSCALE_DEFERRED_STATE" ]]; then + retryable "Tailscale is optional and setup is deferred; see ${TAILSCALE_DEFERRED_STATE}" + else + # The hook may not run until a user logs in. Keep this visible in the + # report even when the image has not yet had a chance to create its + # persistent marker. + retryable "Tailscale binary is absent; privileged setup will be deferred" + fi +} + +previous_boot_id="" +previous_boot_count=0 +if [[ -r "$STATUS_FILE" ]]; then + previous_boot_id="$(sed -n 's/^boot_id=//p' "$STATUS_FILE" | head -1)" + previous_boot_count="$(sed -n 's/^boot_count=//p' "$STATUS_FILE" | head -1)" +fi +[[ "$previous_boot_count" =~ ^[0-9]+$ ]] || previous_boot_count=0 +current_boot_id="$(cat /proc/sys/kernel/random/boot_id 2>/dev/null || echo unknown)" +repeat_boot=0 +boot_count=$((previous_boot_count + 1)) +if [[ -n "$previous_boot_id" && "$current_boot_id" != unknown && "$current_boot_id" != "$previous_boot_id" ]]; then + repeat_boot=1 +fi + +if ! command -v systemctl >/dev/null 2>&1; then + hard_fail "systemctl is not installed" +else + system_state="$(systemctl is-system-running 2>/dev/null || true)" + case "$system_state" in + running) + note "systemd is running" + ;; + degraded) + retryable "systemd is degraded; setup-unit results below are authoritative" + systemctl --failed --no-legend --no-pager || true + ;; + *) + hard_fail "systemd is not settled: ${system_state:-unknown}" + ;; + esac + + # Keep this list synchronized with [services] in the desktop contract. + for unit in \ + bootc-unified-storage.service \ + bluefin-stats-refresh.timer \ + brew-setup.service \ + dconf-update.service \ + flatpak-nuke-fedora.service \ + flatpak-preinstall.service \ + gdm.service \ + input-remapper.service \ + ublue-system-setup.service \ + uupd.timer; do + check_enabled "$unit" + done + + if systemctl --global is-enabled ublue-user-setup.service >/dev/null 2>&1; then + note "enabled globally: ublue-user-setup.service" + else + hard_fail "required global user service is not enabled: ublue-user-setup.service" + fi + + check_optional_enabled tailscaled.service + + for unit in bootc-unified-storage.service gdm.service ublue-system-setup.service \ + flatpak-nuke-fedora.service dconf-update.service input-remapper.service \ + bluefin-stats-refresh.service uupd.service; do + check_failed "$unit" hard + done + check_failed flatpak-preinstall.service retryable + check_failed brew-setup.service retryable + if systemctl cat tailscaled.service >/dev/null 2>&1; then + check_failed tailscaled.service retryable + fi +fi + +for hook in \ + /usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh \ + /usr/share/ublue-os/privileged-setup.hooks.d/11-framework-ucsi-workaround.sh \ + /usr/share/ublue-os/privileged-setup.hooks.d/99-flatpaks.sh \ + /usr/share/ublue-os/user-setup.hooks.d/12-gnupg.sh \ + /usr/share/ublue-os/user-setup.hooks.d/20-framework.sh \ + /usr/share/ublue-os/user-setup.hooks.d/99-privileged.sh; do + check_hook "$hook" +done + +check_flatpaks +check_tailscale + +if [[ ! -x "$DESKTOP_VERIFIER" ]]; then + hard_fail "desktop contract verifier is missing: ${DESKTOP_VERIFIER}" +elif [[ ! -f "$DESKTOP_CONTRACT" ]]; then + hard_fail "desktop contract is missing: ${DESKTOP_CONTRACT}" +else + if "$DESKTOP_VERIFIER" "$DESKTOP_CONTRACT"; then + note "static desktop contract passed from the booted image" + else + hard_fail "static desktop contract failed from the booted image" + fi +fi + +if [[ "${UTAH_EXPECT_REPEAT:-0}" == 1 && "$repeat_boot" -ne 1 ]]; then + hard_fail "repeat-boot validation requested, but no previous boot was recorded" +fi + +if ((${#MISSING_FLATPAKS[@]})); then + missing_flatpaks="${MISSING_FLATPAKS[*]}" +else + missing_flatpaks=none +fi + +write_status() { + local result="$1" + local status_dir status_tmp note_line + status_dir="$(dirname "$STATUS_FILE")" + if ! mkdir -p "$status_dir" 2>/dev/null; then + printf 'utah-first-boot: unable to create status directory: %s\n' "$status_dir" >&2 + return + fi + status_tmp="${STATUS_FILE}.tmp.$$" + { + printf 'format=1\n' + printf 'result=%s\n' "$result" + printf 'boot_id=%s\n' "$current_boot_id" + printf 'boot_count=%s\n' "$boot_count" + printf 'repeat_boot=%s\n' "$repeat_boot" + printf 'hard_failures=%s\n' "$HARD_FAILURES" + printf 'retryable_failures=%s\n' "$RETRYABLE_FAILURES" + printf 'missing_flatpaks=%s\n' "$missing_flatpaks" + for note_line in "${NOTES[@]}"; do + printf 'note=%s\n' "$note_line" + done + } >"$status_tmp" && mv -f "$status_tmp" "$STATUS_FILE" +} + +if ((HARD_FAILURES)); then + write_status failed + printf 'UTAH_FIRST_BOOT_FAIL hard_failures=%s retryable_failures=%s\n' \ + "$HARD_FAILURES" "$RETRYABLE_FAILURES" + exit 1 +elif ((RETRYABLE_FAILURES)); then + write_status retryable + printf 'UTAH_FIRST_BOOT_RETRYABLE retryable_failures=%s\n' "$RETRYABLE_FAILURES" + exit 0 +else + write_status passed + printf 'UTAH_FIRST_BOOT_OK boot_count=%s repeat_boot=%s\n' "$boot_count" "$repeat_boot" + exit 0 +fi diff --git a/system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset b/system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset index ad4db080..1b2166cd 100644 --- a/system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset +++ b/system_files/shared/usr/lib/systemd/system-preset/85-utah-desktop.preset @@ -4,6 +4,11 @@ enable gdm.service enable firewalld.service enable fwupd.service enable fwupd-refresh.timer +enable brew-setup.service +enable flatpak-nuke-fedora.service +enable flatpak-preinstall.service +enable input-remapper.service +enable bluefin-stats-refresh.timer enable tailscaled.service enable uupd.timer enable ublue-system-setup.service diff --git a/system_files/shared/usr/lib/systemd/system/bluefin-stats-refresh.service b/system_files/shared/usr/lib/systemd/system/bluefin-stats-refresh.service index 4e5a1657..d4863583 100644 --- a/system_files/shared/usr/lib/systemd/system/bluefin-stats-refresh.service +++ b/system_files/shared/usr/lib/systemd/system/bluefin-stats-refresh.service @@ -3,7 +3,10 @@ Description=Refresh Bluefin community stats for fastfetch Documentation=https://projectbluefin.io After=network-online.target Wants=network-online.target -ConditionPathIsReadWrite=/var/cache/bluefin +# /var/cache is intentionally removed from the immutable image during cleanup. +# Check the writable /var mount instead; ExecStartPre creates the cache before +# the first refresh, including after a fresh boot and on repeat boots. +ConditionPathIsReadWrite=/var [Service] Type=oneshot diff --git a/system_files/shared/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh b/system_files/shared/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh index ca3ed4d7..def8d395 100755 --- a/system_files/shared/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh +++ b/system_files/shared/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh @@ -3,8 +3,52 @@ # shellcheck source=/dev/null source /usr/lib/ublue/setup-services/libsetup.sh -version-script tailscale privileged 1 || exit 0 +TAILSCALE_DEFERRED_STATE="${TAILSCALE_DEFERRED_STATE:-/var/lib/ublue/setup-services/tailscale.deferred}" + +defer_tailscale() { + local reason="$1" + install -d -m0755 "$(dirname "${TAILSCALE_DEFERRED_STATE}")" + { + printf 'status=deferred\n' + printf 'reason=%s\n' "${reason}" + printf 'retry=rerun ublue-privileged-setup\n' + } >"${TAILSCALE_DEFERRED_STATE}" + echo "Tailscale setup deferred: ${reason}" +} + +# Tailscale is an optional integration in the setup hook. Do this check before +# version-script: recording a completed version while the package is absent +# would make the hook silently skip forever after Tailscale is installed. +if ! command -v tailscale >/dev/null 2>&1; then + defer_tailscale "the tailscale binary is not installed" + exit 0 +fi + +if [[ -z "${PKEXEC_UID:-}" ]]; then + defer_tailscale "pkexec did not provide PKEXEC_UID" + exit 0 +fi + +operator="$(getent passwd "${PKEXEC_UID}" | cut -d: -f1)" +if [[ -z "${operator}" ]]; then + defer_tailscale "no passwd entry exists for PKEXEC_UID=${PKEXEC_UID}" + exit 0 +fi + +# A deferred run must be retried even if an older version-script invocation +# recorded version 1 before the command became unavailable. A successful run +# removes the marker, after which version-script restores normal idempotency. +if [[ ! -e "${TAILSCALE_DEFERRED_STATE}" ]]; then + version-script tailscale privileged 1 || exit 0 +else + echo "Retrying previously deferred Tailscale setup" +fi set -xeuo pipefail -tailscale set --operator="$(getent passwd "$PKEXEC_UID" | cut -d: -f1)" +if ! tailscale set --operator="${operator}"; then + defer_tailscale "tailscale set --operator failed" + exit 0 +fi + +rm -f "${TAILSCALE_DEFERRED_STATE}" diff --git a/tests/unit/test_first_boot.py b/tests/unit/test_first_boot.py new file mode 100755 index 00000000..6cded28f --- /dev/null +++ b/tests/unit/test_first_boot.py @@ -0,0 +1,149 @@ +#!/usr/bin/env python3 +"""Focused source tests for Utah's first-boot desktop contract.""" + +from __future__ import annotations + +import os +import stat +import subprocess +import tempfile +import unittest +from pathlib import Path + +import tomllib + + +REPO_ROOT = Path(__file__).resolve().parents[2] +TAILSCALE_HOOK = ( + REPO_ROOT + / "system_files/shared/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh" +) +CONTRACT = REPO_ROOT / "contracts/bluefin-desktop.toml" + + +def executable(path: Path, contents: str) -> None: + path.write_text(contents) + path.chmod(path.stat().st_mode | stat.S_IXUSR) + + +class FirstBootTests(unittest.TestCase): + def test_contract_declares_runtime_policy(self) -> None: + contract = tomllib.loads(CONTRACT.read_text()) + first_boot = contract["first_boot"] + services = contract["services"] + + self.assertIn( + "/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh", + first_boot["hooks"], + ) + self.assertEqual( + first_boot["deferred_state"], + "/var/lib/ublue/setup-services/tailscale.deferred", + ) + self.assertIn("input-remapper.service", services["enabled"]) + self.assertIn("bluefin-stats-refresh.timer", services["enabled"]) + self.assertIn("ublue-user-setup.service", services["user_enabled"]) + self.assertEqual(services["optional"], ["tailscaled.service"]) + + def test_all_declared_hooks_and_runtime_checker_parse(self) -> None: + contract = tomllib.loads(CONTRACT.read_text()) + hooks = [ + REPO_ROOT / "system_files/shared" / Path(path).relative_to("/") + for path in contract["first_boot"]["hooks"] + ] + hooks.append(REPO_ROOT / "scripts/verify-first-boot.sh") + for hook in hooks: + with self.subTest(hook=hook): + result = subprocess.run( + ["bash", "-n", str(hook)], capture_output=True, text=True, check=False + ) + self.assertEqual(result.returncode, 0, result.stderr) + + def test_tailscale_missing_binary_is_deferred_without_invocation(self) -> None: + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + stub_bin = root / "bin" + stub_bin.mkdir() + # The hook needs these two coreutils to create its marker. Keeping + # the PATH isolated proves command -v cannot discover tailscale. + for command in ("dirname", "install"): + (stub_bin / command).symlink_to(f"/usr/bin/{command}") + + hook = root / "tailscale.sh" + hook.write_text( + TAILSCALE_HOOK.read_text().replace( + "source /usr/lib/ublue/setup-services/libsetup.sh", + "version-script() { return 0; }", + ) + ) + hook.chmod(0o755) + state = root / "tailscale.deferred" + env = { + **os.environ, + "PATH": str(stub_bin), + "TAILSCALE_DEFERRED_STATE": str(state), + "PKEXEC_UID": "1000", + "HOME": str(root / "home"), + } + result = subprocess.run( + ["/usr/bin/bash", str(hook)], env=env, capture_output=True, text=True, check=False + ) + + self.assertEqual(result.returncode, 0, result.stderr) + self.assertTrue(state.is_file()) + state_text = state.read_text() + self.assertIn("status=deferred", state_text) + self.assertIn("tailscale binary is not installed", state_text) + + def test_tailscale_success_clears_a_deferred_marker(self) -> None: + with tempfile.TemporaryDirectory() as directory: + root = Path(directory) + stub_bin = root / "bin" + stub_bin.mkdir() + for command in ("dirname", "install"): + (stub_bin / command).symlink_to(f"/usr/bin/{command}") + executable( + stub_bin / "tailscale", + "#!/usr/bin/bash\nprintf '%s\\n' \"$*\" >\"$TAILSCALE_LOG\"\n", + ) + executable( + stub_bin / "getent", + "#!/usr/bin/bash\nprintf 'testuser:x:1000:1000::/home/testuser:/bin/bash\\n'\n", + ) + + hook = root / "tailscale.sh" + hook.write_text( + TAILSCALE_HOOK.read_text().replace( + "source /usr/lib/ublue/setup-services/libsetup.sh", + "version-script() { return 0; }", + ) + ) + hook.chmod(0o755) + state = root / "tailscale.deferred" + state.write_text("status=deferred\nreason=previously missing\n") + log = root / "tailscale.log" + env = { + **os.environ, + "PATH": f"{stub_bin}:/usr/bin:/bin", + "TAILSCALE_DEFERRED_STATE": str(state), + "TAILSCALE_LOG": str(log), + "PKEXEC_UID": "1000", + "HOME": str(root / "home"), + } + result = subprocess.run( + ["/usr/bin/bash", str(hook)], env=env, capture_output=True, text=True, check=False + ) + + self.assertEqual(result.returncode, 0, result.stderr) + self.assertFalse(state.exists()) + self.assertIn("set --operator=testuser", log.read_text()) + + def test_service_script_makes_optional_policy_explicit(self) -> None: + script = (REPO_ROOT / "scripts/configure-services.sh").read_text() + self.assertIn("enable_optional_unit tailscaled.service", script) + self.assertIn("enable_required_unit input-remapper.service", script) + self.assertIn("enable_required_unit bluefin-stats-refresh.timer", script) + + +if __name__ == "__main__": + unittest.main() From a226ee43d134cd7905de8837bb1f17201d206ac3 Mon Sep 17 00:00:00 2001 From: Danathar Date: Sat, 12 Sep 2026 00:10:27 +0000 Subject: [PATCH 2/2] docs: clarify blast radius of required-unit policy and tailscale tolerance Review on #62 flagged that enable_required_unit() turning a soft check into a build-blocking assertion needed to be explicit about its consequence, and that the tailscale hook's new tolerance for an absent tailscale package matters to sibling PRs (#46, #60, #68) that are also moving tailscale between service categories. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01LNgJ8VMdoqzGequbxsP2Kc --- scripts/configure-services.sh | 3 +++ .../ublue-os/privileged-setup.hooks.d/10-tailscale.sh | 8 +++++--- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/scripts/configure-services.sh b/scripts/configure-services.sh index 4282db18..bb413c8f 100644 --- a/scripts/configure-services.sh +++ b/scripts/configure-services.sh @@ -25,6 +25,9 @@ user_unit_exists() { return 1 } +# Under `set -e` above, a missing required unit aborts this script and fails +# the image build for every flavor -- not just this one. Only mark a unit +# required here if losing it silently would be worse than a broken build. enable_required_unit() { if ! unit_exists "$1"; then echo "Required desktop unit is missing: $1" >&2 diff --git a/system_files/shared/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh b/system_files/shared/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh index def8d395..68a48819 100755 --- a/system_files/shared/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh +++ b/system_files/shared/usr/share/ublue-os/privileged-setup.hooks.d/10-tailscale.sh @@ -16,9 +16,11 @@ defer_tailscale() { echo "Tailscale setup deferred: ${reason}" } -# Tailscale is an optional integration in the setup hook. Do this check before -# version-script: recording a completed version while the package is absent -# would make the hook silently skip forever after Tailscale is installed. +# Tailscale is an optional integration: this hook tolerates the tailscale +# package/unit being absent entirely and defers rather than failing. Do this +# check before version-script: recording a completed version while the +# package is absent would make the hook silently skip forever after +# Tailscale is installed. if ! command -v tailscale >/dev/null 2>&1; then defer_tailscale "the tailscale binary is not installed" exit 0