Overview

Immutable OS

One signed image, booted A/B, upgraded atomically with a health gate and automatic rollback.

SiHA does not run a general-purpose Linux you log into and maintain. It runs a single, immutable OS image: a read-only squashfs root, booted under enforced UEFI SecureBoot, with a tiny supervisor as PID 1. There is no SSH, no systemd, and no cloud-init on the appliance — the attack surface is deliberately small, and nothing about the running system drifts.

A/B ATOMIC UPGRADESLOT Av1.4active · known-goodSLOT Bv1.5new image · stagedreboot → Bone-shot tryhealth gateprobe T=0 · T=2s✓ commitB becomes active↩ rollbackauto: back to AbootSIGNED BOOT CHAINUEFI SecureBoot›signed UKI›sd-boot›kernel · lockdown›squashfs · ro

One image, two slots

The whole OS ships as one versioned artifact. A node keeps two image slots, A and B: one is active and known-good, the other is free. You never patch the running system in place — an upgrade writes a new whole image into the inactive slot. Because the root is read-only and content-addressed, two nodes on the same version are byte-identical, and “what’s running” is always a single version number.

Health-gated upgrades, automatic rollback

Switching versions is atomic and safe by construction:

  1. The new image is written to the inactive slot (B).
  2. The bootloader is told to try B once — a one-shot boot, with A still pinned as the fallback default.
  3. The node reboots into B and the control plane runs health probes.
  4. Healthy → commit: B is marked the new known-good default. Unhealthy (or no confirmation) → automatic rollback: the bootloader’s boot counter lapses and the node comes back up on A, untouched.

The worst case for an upgrade is therefore one extra reboot back onto the version you were already running. No half-applied package sets, no manual recovery.

The signed boot chain

Integrity of the boot path is established by signatures, end to end:

UEFI SecureBoot → signed UKI (kernel + initrd + cmdline in one signed image) → sd-boot → kernel (in lockdown) → the read-only squashfs root.

Under enforced SecureBoot the kernel enters lockdown, which is also why the dataplane binds NICs through the IOMMU (vfio-pci) rather than the lockdown-blocked uio_pci_generic — see the architecture and the DPDK post.

A debug build variant (SecureBoot off) exists purely for fast iteration — it lets a daemon be hot-swapped without a full image rebuild. The shipped release variant is signed and enforced.

What ships today

To be precise about scope, the immutable platform delivers:

  • a signed boot chain (UKI + sd-boot under enforced SecureBoot),
  • health-gated atomic A/B upgrades with automatic rollback,
  • a reduced attack surface: no SSH / systemd / cloud-init, read-only root.

dm-verity root-content integrity and LUKS/TPM data-at-rest encryption are not shipped yet — they’re planned for a later milestone. Read the current model as signed boot + safe upgrades + small surface, not verified-boot-of-root-content or encryption-at-rest.