Skip to content
Closed
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
2 changes: 1 addition & 1 deletion docs/skills/ddi-installer-build.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ The release process is driven by `.github/workflows/build.yml`:
- [ ] The live installer does not bake hardcoded SSH keys or pre-hashed root
passwords.
- [ ] The DDI is decompressed after the cpio step.
- [ ] `files/installer/repart.d/20-root-a.conf` has `GrowFileSystem=yes`.
- [ ] `files/installer/repart.d/50-root.conf` has `GrowFileSystem=yes`.

## See also

Expand Down
37 changes: 26 additions & 11 deletions docs/skills/ddi-installer.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ metadata:
- Writing or refining `systemd-repart`, `bootctl`, or `ukify` configurations.
- Packaging or publishing DDI assets to GitHub Releases.
- Managing partition recipes for the target disk layout (`10-esp.conf`,
`20-root-a.conf`, `30-var.conf`).
`20-usr-a.conf`, `30-usr-b.conf`, `40-oem.conf`, `50-root.conf`).

## When NOT to Use

Expand Down Expand Up @@ -72,13 +72,20 @@ container runtime pod sandboxes.
5. `systemd-sysinstall` reads partition recipes from
`/usr/lib/repart.sysinstall.d/` if it is populated; otherwise it falls back
to `/usr/lib/repart.d/`. The target recipes are staged at
`/usr/lib/repart.d/` (`10-esp.conf`, `20-root-a.conf`, `30-var.conf`).
6. `20-root-a.conf` copies the DDI block-for-block from
`/usr/lib/repart.d/` (`10-esp.conf`, `20-usr-a.conf`, `30-usr-b.conf`,
`40-oem.conf`, `50-root.conf`).
6. `20-usr-a.conf` copies the DDI payload block-for-block from
`/dev/disk/by-partlabel/bluefin-installer-data` (the embedded DDI data
partition on the installer media).
7. Target OS volume expansion is handled by `systemd-growfs`; the target OS
stack includes `xfsprogs` so the root and `/var` filesystems can grow to fill
their partitions on first boot.
partition on the installer media). The payload is mounted read-only as
`/usr` via the target UKI cmdline (`mount.usr=PARTLABEL=USR-A`).
7. `50-root.conf` formats ROOT (ext4) and seeds it via `CopyFiles=`: the
offline k0s sysext at `/var/lib/k0s/k0s.raw` and the target `/etc` from
`/usr/lib/bluefin-server/etc-seed` (assembled by the installer element —
the DDI payload is `/usr`-only, so its `/etc` is not visible on the
installed system).
8. Target OS volume expansion is handled by `systemd-growfs`; the target OS
stack includes `xfsprogs` so the `/usr` filesystem can be grown on first
boot.

## Partition Layout

Expand All @@ -93,9 +100,17 @@ container runtime pod sandboxes.

| Partition | Type | Size | Contents |
|---|---|---|---|
| ESP | vfat | 500 MiB – 1 GiB | `systemd-boot` + target OS UKI (`bluefin-server.efi`) |
| `bluefin-server-root-a` | XFS | 4 GiB – 16 GiB | OS root filesystem (copied from installer data partition) |
| `var` | XFS | ≥ 4 GiB | Writable persistent `/var`; grows to fill remaining disk |
| `EFI-SYSTEM` | vfat (ESP GUID `c12a7328-…`) | 500 MiB – 1 GiB | `systemd-boot` + target OS UKI (`bluefin-server.efi`) |
| `USR-A` | Flatcar usr GUID `5dfbf5f4-…` | ≥ 4 GiB | read-only `/usr` (DDI payload copied block-for-block) |
| `USR-B` | Flatcar usr GUID `5dfbf5f4-…` | ≥ 4 GiB | empty A/B rollback slot |
| `OEM` | Flatcar OEM GUID `0fc63daf-…` (ext4) | 1 GiB | provider/first-boot state; filesystem label `OEM` (Flatcar stage 2 waits on `dev-disk-by-label-OEM.device`) |
| `ROOT` | Flatcar root GUID `3884dd41-…` (ext4) | ≥ 4 GiB | writable state: `/etc` (seeded via `CopyFiles=`), `/var`, `/home`; grows to fill remaining disk |

The target UKI cmdline places the filesystems explicitly:
`root=PARTLABEL=ROOT mount.usr=PARTLABEL=USR-A mount.usrfstype=xfs
mount.usrflags=ro`. `root=` is mandatory because the Flatcar ROOT GUID is not
a Discoverable Partitions Specification type, so
`systemd-gpt-auto-generator` cannot discover it.

## Installer Boot Flow

Expand Down Expand Up @@ -187,7 +202,7 @@ offline installation.
- [ ] The interactive installer service sets `TTYPath=/dev/tty0` so the TUI
appears on the attached display even when serial is the primary console.
- [ ] `bluefin-server-installer.bst` decompresses the DDI after the cpio step.
- [ ] `files/installer/repart.d/20-root-a.conf` has `GrowFileSystem=yes`.
- [ ] `files/installer/repart.d/50-root.conf` has `GrowFileSystem=yes`.

## See also

Expand Down
14 changes: 9 additions & 5 deletions docs/skills/gap-analysis-distros.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ Bluefin Server is a BuildStream 2-based, image-based Linux server OS built from
| Axis | Bluefin Server (as-implemented) |
|------|---------------------------------|
| **Philosophy** | Systemd-native, minimal, image-based server OS appliance; base DDI includes bash for login and bring-up while heavy developer/debug tools live in sysexts or system containers; intended to run container workloads and Kubernetes via optional sysexts. Sources: [AGENTS.md](../../AGENTS.md), [factory-integration.md](factory-integration.md). |
| **State model** | Target OS DDI is an XFS filesystem image. A separate persistent `/var` partition is created by the installer. There is no second root slot provisioned today, and the UKI cmdline currently uses `rw`, so the root is not mounted read-only at runtime. Sources: [bluefin-server-ddi.bst](../../elements/oci/bluefin-server-ddi.bst), [20-root-a.conf](../../files/installer/repart.d/20-root-a.conf), [bluefin-server-installer.bst](../../elements/oci/bluefin-server-installer.bst). |
| **State model** | Target OS DDI is an XFS filesystem image mounted read-only as `/usr` from the `USR-A` slot. The installer provisions a separate writable `ROOT` state partition (ext4, grows into remaining disk) seeded at install time with the offline k0s sysext and `/etc`; `USR-B` is provisioned as an empty A/B rollback slot. The UKI cmdline carries `root=PARTLABEL=ROOT mount.usr=PARTLABEL=USR-A mount.usrfstype=xfs mount.usrflags=ro`, so the root is writable while `/usr` is mounted read-only at runtime. Sources: [bluefin-server-ddi.bst](../../elements/oci/bluefin-server-ddi.bst), [20-usr-a.conf](../../files/installer/repart.d/20-usr-a.conf), [50-root.conf](../../files/installer/repart.d/50-root.conf), [bluefin-server-installer.bst](../../elements/oci/bluefin-server-installer.bst). |
| **Updates** | `systemd-sysupdate` reads root/UKI transfers from `files/os/sysupdate.d/` and the optional k0s transfer from the `k0s` component directory. Assets are published to GitHub Releases, and the combined `SHA256SUMS` manifest is signed in CI with a GPG key. `Verify=yes` is the default. Sources: [systemd-sysupdate-verification.md](systemd-sysupdate-verification.md), [50-root.transfer](../../files/os/sysupdate.d/50-root.transfer), [60-uki.transfer](../../files/os/sysupdate.d/60-uki.transfer), [70-k0s.transfer](../../files/os/sysupdate.k0s.d/70-k0s.transfer), also `systemd-sysupdate(8)`. |
| **Provisioning** | The installer is an offline `systemd-sysinstall` image that embeds the DDI as a data partition. First-boot configuration is intended to be delivered via `systemd-creds` through the ESP or hypervisor metadata. Today only `passwd.hashed-password.root` is consumed via `systemd-sysusers.d`; the documented `tmpfiles.extra` path for SSH keys and similar files is not implemented. Sources: [bluefin-server-installer.bst](../../elements/oci/bluefin-server-installer.bst), [10-root-creds.conf](../../files/os/sysusers.d/10-root-creds.conf), [os-creds-prov.bst](../../elements/bluefin-server/os-creds-prov.bst), [systemd-creds(1)](https://www.freedesktop.org/software/systemd/man/latest/systemd-creds.html). |
| **Customization** | Adds software through `systemd-sysext` (overlay `/usr`) and `systemd-confext` (overlay `/etc`) images. The base OS `os-release` advertises `ID=flatcar` and a matching `VERSION_ID` so pre-built Flatcar Bakery extensions load. k0s is shipped as a separately built, optionally enabled sysext. Sources: [systemd-sysext-extensions.md](systemd-sysext-extensions.md), [k0s-sysext.md](k0s-sysext.md), [os-release-flatcar.bst](../../elements/bluefin-server/os-release-flatcar.bst), [systemd-sysext(8)](https://www.freedesktop.org/software/systemd/man/latest/systemd-sysext.html). |
Expand All @@ -105,11 +105,14 @@ Bluefin Server is a BuildStream 2-based, image-based Linux server OS built from

### Root filesystem and A/B rollback

- **Gap:** Bluefin's `systemd-sysupdate` root transfer already names two target partitions (`root-a` and `root-b`) in `50-root.transfer`, but the installer only creates one root partition (`20-root-a.conf`).
There is no `root-b` partition yet, so `systemd-sysupdate` cannot stage an update into an inactive slot and the OS has no atomic rollback path comparable to Flatcar/Fedora CoreOS/Talos today.
- **Gap:** The DDI filesystem is created as a writable XFS image and the installed UKI boots it with `rw`. A read-only `/usr` state model, as intended by the sysext-first design, is not enforced at runtime.
- **Gap:** Bluefin's `systemd-sysupdate` root transfer names legacy target partition labels (`bluefin-server-root-<ver>_a/_b`) in `50-root.transfer`, but the Flatcar layout installed since #134 provisions `USR-A`/`USR-B` instead and the transfer has not been rewired to those slots.
`USR-B` is provisioned empty, so `systemd-sysupdate` cannot stage an update into an inactive slot and the OS has no atomic rollback path comparable to Flatcar/Fedora CoreOS/Talos today.
- **Gap:** There is no mechanism to select the previous OS version at boot if an update fails; recovery currently depends on reinstalling from media.

### Update delivery

- **Gap:** The root transfer uses `Type=partition Path=auto`, which requires `systemd-sysupdate` to discover a matching GPT partition label. The shipped `50-root.transfer` patterns (`bluefin-server-root-a`/`root-b`) no longer match any partition the installer provisions (#134 replaced them with `USR-A`/`USR-B`), so OTA updates resolve to no slot until the transfer is rewired.

### Provisioning

- **Gap:** The documented `systemd-creds` first-boot provisioning for SSH keys (`tmpfiles.extra`) is not present in the build (`os-creds-prov.bst` only ships `sysusers.d`).
Expand Down Expand Up @@ -189,7 +192,8 @@ These gaps drive the priorities in [architecture-roadmap.md](architecture-roadma
- [elements/bluefin-server/os-release-flatcar.bst](../../elements/bluefin-server/os-release-flatcar.bst)
- [elements/bluefin-server/os-creds-prov.bst](../../elements/bluefin-server/os-creds-prov.bst)
- [elements/bluefin-server/os-kured-hook.bst](../../elements/bluefin-server/os-kured-hook.bst)
- [files/installer/repart.d/20-root-a.conf](../../files/installer/repart.d/20-root-a.conf)
- [files/installer/repart.d/20-usr-a.conf](../../files/installer/repart.d/20-usr-a.conf)
- [files/installer/repart.d/50-root.conf](../../files/installer/repart.d/50-root.conf)
- [files/os/sysupdate.d/50-root.transfer](../../files/os/sysupdate.d/50-root.transfer)
- [files/os/sysupdate.d/60-uki.transfer](../../files/os/sysupdate.d/60-uki.transfer)
- [files/os/sysupdate.k0s.d/70-k0s.transfer](../../files/os/sysupdate.k0s.d/70-k0s.transfer)
Expand Down
10 changes: 6 additions & 4 deletions elements/installer/installer-repart.bst
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,12 @@ description: |
"systemd-repart --dry-run=no DEVICE", it reads these configs to know how
to partition and populate the TARGET disk.

Partition layout:
10-esp.conf EFI System Partition (vfat, 500M–1G)
20-root-a.conf Root slot A — DDI filesystem image copied here
30-var.conf /var — xfs, writable, grows to fill disk
Partition layout (Flatcar GPT layout, projectbluefin/server#134):
10-esp.conf EFI-SYSTEM (vfat, 500M–1G)
20-usr-a.conf USR-A — DDI /usr payload copied here block-for-block
30-usr-b.conf USR-B — empty A/B rollback slot
40-oem.conf OEM — ext4, filesystem label OEM (stage 2 boot dep)
50-root.conf ROOT — writable ext4 state, CopyFiles seeds, grows

sources:
- kind: local
Expand Down
57 changes: 12 additions & 45 deletions elements/oci/bluefin-server-ddi.bst
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,12 @@ description: |
Output: bluefin-server-ddi-<ver>.raw.zst + SHA256SUMS

The output .raw is a filesystem image consumed by installer repart config:
files/installer/repart.d/20-root-a.conf via CopyBlocks=.
files/installer/repart.d/20-usr-a.conf via CopyBlocks= — the Flatcar layout
(projectbluefin/server#134) mounts this payload read-only as the system's
/usr (mount.usr=PARTLABEL=USR-A). Only /usr is visible on the target; the
writable ROOT partition is a fresh ext4 filesystem seeded with /etc state by
the installer element (files/installer/repart.d/50-root.conf CopyFiles=),
so this payload carries no target /etc content.

build-depends:
- base/base-stack.bst
Expand Down Expand Up @@ -40,50 +45,12 @@ config:
rm -f "/layer/usr/lib/modules/${KVER}/vmlinux" "/layer/usr/lib/modules/${KVER}/System.map"
depmod -b /layer "${KVER}"

# Stage extracted CA certificate bundle into target DDI rootfs
mkdir -p /layer/etc/pki/ca-trust/extracted /layer/etc/ssl/certs /layer/etc/pki/tls/certs
cp -a /etc/pki/ca-trust/extracted/* /layer/etc/pki/ca-trust/extracted/
ln -sf /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem /layer/etc/ssl/certs/ca-certificates.crt
ln -sf /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem /layer/etc/pki/tls/certs/ca-bundle.crt
ln -sf /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem /layer/etc/pki/tls/cert.pem

# Mask systemd-firstboot to prevent interactive prompts on headless first boot
mkdir -p /layer/etc/systemd/system
ln -sf /dev/null /layer/etc/systemd/system/systemd-firstboot.service

# Mask audit-rules to prevent failure on shell-free OS (augenrules requires /bin/sh)
ln -sf /dev/null /layer/etc/systemd/system/audit-rules.service

# Silence kernel and audit log spam on the console
mkdir -p /layer/etc/systemd/journald.conf.d /layer/etc/sysctl.d
printf '[Journal]\nForwardToConsole=no\nMaxLevelConsole=warning\n' > /layer/etc/systemd/journald.conf.d/10-console.conf
printf 'kernel.printk = 3 4 1 3\n' > /layer/etc/sysctl.d/10-console.conf
ln -sf /dev/null /layer/etc/systemd/system/systemd-journald-audit.socket

# Ensure standard /etc/hosts exists for container runtimes (containerd/podman)
printf '127.0.0.1 localhost\n::1 localhost ip6-localhost ip6-loopback\n' > /layer/etc/hosts

# Ensure persistent /var is mounted from its partition label
printf '/dev/disk/by-partlabel/var /var xfs defaults 0 0\n' > /layer/etc/fstab

# Ensure all standard virtual, serial, and hypervisor consoles allow root login
printf 'tty0\ntty1\ntty2\ntty3\ntty4\ntty5\ntty6\nttyS0\nttyS1\nconsole\nhvc0\n' > /layer/etc/securetty

# Seed default root password 'bluefin' into /etc/shadow for console and ssh login
mkdir -p /layer/etc
printf 'root:$6$bluefin123$o2pQjPN1n3ZCnYUROlA01xAdnGO7mhVRAVw98x4xc8LAUIJv7b44bBNoER6fM4P.rrj4ePYFfkx9WvZICU8nt/:19700:0:99999:7:::\n' > /layer/etc/shadow
chmod 0600 /layer/etc/shadow
printf 'root:x:0:0:root:/root:/bin/bash\n' > /layer/etc/passwd
chmod 0644 /layer/etc/passwd
printf 'root:x:0:\n' > /layer/etc/group
chmod 0644 /layer/etc/group

# Pre-generate SSH host keys for first boot remote diagnostics
mkdir -p /layer/etc/ssh
ssh-keygen -q -N "" -t ed25519 -f /layer/etc/ssh/ssh_host_ed25519_key
ssh-keygen -q -N "" -t rsa -b 3072 -f /layer/etc/ssh/ssh_host_rsa_key
chmod 0600 /layer/etc/ssh/ssh_host_*_key
chmod 0644 /layer/etc/ssh/ssh_host_*.pub
# Note: no /etc content is stamped here. Under the Flatcar layout
# (projectbluefin/server#134) this image is mounted read-only at /usr, so
# anything written to /layer/etc would be invisible on the installed
# system. The writable ROOT partition is seeded instead — see the /etc
# seed assembly in elements/oci/bluefin-server-installer.bst and the
# CopyFiles= lines in files/installer/repart.d/50-root.conf.

# Sum actual file sizes across bind mounts (du -sb reports content bytes, not overlay blocks).
ROOT_BYTES=$(du -sb /layer | cut -f1)
Expand Down
Loading