UKI

What It Is

A Unified Kernel Image (UKI) is a single UEFI PE executable that bundles a Linux kernel, an initramfs (initial RAM filesystem), kernel command-line parameters, and metadata into one file. Instead of a bootloader loading separate files from disk (kernel here, initramfs there, config somewhere else), everything is packed into one binary.

The concept was proposed by Lennart Poettering (creator of systemd) in 2022. The formal specification is maintained by the Linux Userspace API Group (uapi-group). The reference implementation uses systemd-stub as the boot stub, but FortrOS implements its own: ruki-stub, a minimal Rust UEFI application.

Why It Matters

Traditional Linux boot has a vulnerability: the kernel and initramfs are separate files, and the kernel command line lives in a config file (like grub.cfg). Even with Secure Boot, an attacker who can modify grub.cfg could add init=/bin/sh to get a root shell, or change root= to boot from a malicious filesystem.

With a UKI, the command line is embedded in the signed binary. Tamper with any component and the Secure Boot signature breaks. The entire boot payload is one atomic unit: signed as one, verified as one, measured as one.

UKIs also simplify boot management. Instead of managing separate kernel, initramfs, and config files per version, you have one file per version. Install a new kernel? Drop a new UKI on the ESP. Roll back? Point the boot entry at the old UKI. No partial updates, no version mismatches.

How It Works

PE/COFF Format

A UKI is a PE/COFF (Portable Executable / Common Object File Format) binary -- the same format as Windows .exe files and UEFI applications. This is required because UEFI firmware can only execute PE/COFF binaries directly. By using this format, a UKI is a standard UEFI application: firmware loads it, verifies its signature, and executes it.

Internal Structure

A UKI contains named PE sections, each holding a different payload:

Section	Contents	Required
`.linux`	The Linux kernel image	Yes
`.initrd`	Initial ramdisk	Yes (for most uses)
`.cmdline`	Kernel command-line parameters	Typical
`.osrel`	OS identification (from `/etc/os-release`)	Typical
`.ucode`	CPU microcode updates	Optional
`.splash`	Boot splash screen (BMP)	Optional
`.dtb`	DeviceTree blob (ARM/embedded)	Optional
`.uname`	Kernel version string	Optional
`.sbat`	Secure Boot revocation metadata	Recommended
`.pcrsig`	TPM PCR signature policy (JSON)	Optional
`.pcrpkey`	Public key for verifying `.pcrsig`	Optional

The Boot Stub (ruki-stub)

The UKI's entry point is a small UEFI application embedded as the PE executable's code. FortrOS uses ruki-stub -- a Rust #![no_std] UEFI application (~325 lines) with no systemd dependency. When firmware loads the UKI, ruki-stub:

Reads its own PE sections (.linux, .initrd, .cmdline)
Registers the initrd via the Linux EFI initrd protocol (LoadFile2 + vendor media device path) so the kernel can find it
Sets the command line as load options on the kernel image
Loads the kernel via UEFI LoadImage and starts it via StartImage

ruki-stub measures each PE section (name + contents) into TPM PCR 11 for measured boot. This enables TPM policies that seal secrets (like disk encryption keys) to a specific UKI build. If the UKI changes, the PCR values change, and the TPM refuses to release the secrets.

Building a UKI

FortrOS builds UKIs with ruki-build (its own Rust tool). The reference tool is ukify (part of systemd). Both use objcopy to add PE sections to a boot stub:

# FortrOS: ruki-build
ruki-build --stub ruki-stub.efi \
  --kernel bzImage \
  --initrd initramfs.cpio.gz \
  --cmdline "console=ttyS0 rdinit=/sbin/init" \
  -o preboot.efi

# Reference: ukify (requires systemd)
ukify build \
  --linux=vmlinuz-6.19 \
  --initrd=initramfs.img \
  --cmdline="root=/dev/vda2 quiet" \
  --output=fortros.efi

The output is a single .efi file that can be placed on the ESP and booted directly by firmware or a bootloader.

Signing

Because the UKI is a PE binary, it can be signed with standard tools:

sbsign --key org-signing.key --cert org-signing.crt \
  --output fortros-signed.efi fortros.efi

The signed UKI is verified by UEFI Secure Boot against the certificates in the firmware's db. No shim or separate signing chain needed (though shim can be used if you want compatibility with the existing Microsoft-signed chain).

How FortrOS Uses It

FortrOS uses the UKI format for both the preboot and generation images:

Preboot UKI: Org-scoped (same for all nodes in the org). Contains:

A minimal Linux kernel
An initramfs with the preboot agent, TLS stack, and DHCP client
The org's CA public key and gateway address baked into the initramfs
Kernel command line locked to the preboot's needs

Loaded directly by UEFI firmware from the ESP. Installed during provisioning. Updated via rolling upgrade.

Generation UKIs: Per-generation (different kernel configs per hardware profile). Same UKI packaging format (kernel + initramfs + cmdline in a signed PE binary) but loaded differently: the preboot reads the PE sections using the same ruki code, extracts the raw kernel and initramfs, and passes them to kexec separately. kexec needs raw components, not a PE binary -- the UKI is the distribution and signing format, ruki handles the extraction.

This gives one packaging format and one signing model for both stages. The preboot verifies the generation UKI's signature (the PE binary is signed as a unit), extracts the components, and kexec's. No separate signing for kernel and initramfs.

Alternatives

GRUB + separate files: The traditional approach. GRUB reads a config file, loads the kernel and initramfs as separate files. Flexible (can edit config without rebuilding) but the config file is an attack surface. Secure Boot for GRUB requires shim and a complex signing chain.

systemd-boot + Type 1/Type 2 entries: systemd-boot can load both separate files (Type 1, from .conf snippets) and UKIs (Type 2, autodetected from EFI/Linux/ on the ESP). Type 2 is essentially the UKI path.

EFISTUB (direct kernel boot): Linux kernels can be compiled as UEFI executables (EFI stub). Firmware loads the kernel directly, and the command line comes from NVRAM variables. No initramfs bundling, no single-binary signing. Simpler but less capable than UKIs.

UKI