Feature: _usi
Description
A feature that boots Garden Linux using a Unified System Image (USI): a Unified Kernel Image (UKI) with an embedded EROFS read-only root disk stored on the EFI System Partition (ESP).
What it does
Builds a Garden Linux image where the entire root filesystem is stored as an EROFS image embedded in the EFI System Partition, and booted via a Unified Kernel Image (UKI). This approach eliminates a separate root partition: the bootloader, kernel, initrd, and root filesystem are all contained in the ESP.
Key capabilities added by this feature:
- Image build:
image.esp.tarconstructs the EROFS root disk and embeds it into the ESP alongside the UKI. - Conversion:
convert.raw~esp.tarproduces a raw disk image from the ESP tarball;convert.uki~esp.tarextracts the standalone UKI EFI binary. - Initrd: mounts the EROFS root from the ESP in the initramfs using systemd
.mountunits andsystemd-repartto locate and mount the EFI partition. /etcoverlay: the initrd sets up a writable overlay on/etcso that runtime configuration can be written without modifying the read-only root.- Secure Boot key enrollment: installs Garden Linux Secure Boot keys and an OCI signing key into
/etc/gardenlinux/. - Persistent
/homeand/opt: moves these directories under/varso they survive across image updates. - Kernel command line: manages the kernel command line via
update-kernel-cmdlineand drops anetc-setup-hooksservice for first-boot configuration.
How it works
At build time, image.esp.tar packs the rootfs into an EROFS image, wraps it with a UKI, and produces an ESP tarball. convert.raw~esp.tar then formats a FAT32 EFI partition from the ESP tarball and wraps it in a raw GPT disk image.
At boot, the UKI is loaded by the UEFI firmware. The embedded initrd (populated from initrd.include/) mounts the EFI partition, finds the EROFS image, mounts it as the root filesystem, and sets up the /etc overlay before pivoting to the real root.
Files
Files present in this feature and their purpose. See the feature file reference for the semantics of each file type.
| File | Purpose |
|---|---|
convert.raw~esp.tar (ref) | Converts the ESP tarball into a bootable raw disk image with a FAT32 EFI partition. |
convert.uki~esp.tar (ref) | Extracts the standalone UKI EFI binary from the ESP tarball. |
exec.config (ref) | Enables systemd-bless-boot and gardenlinux-etc-setup-hooks services, runs update-kernel-cmdline, creates /efi, and patches the systemd-pcrphase symlink if missing. |
exec.post (ref) | Installs Garden Linux Secure Boot auth files and the OCI signing public key; moves /home and /opt under /var for persistence across updates. |
file.exclude (ref) | Removes Ignition-related configs and services, /root/ contents, and the image-dissect udev rule from the rootfs. |
file.include.markers.yaml (ref) | Maps files to test-coverage marker IDs. |
image.esp.tar (ref) | Creates the EROFS root disk image, embeds it in a UKI, and packages the result as an ESP tarball. |
info.yaml (ref) | Declares type: flag and included/excluded features. |
initrd.include.markers.yaml (ref) | Maps initrd files to test-coverage marker IDs. |
pkg.include (ref) | Installs dracut, systemd-ukify, systemd-boot-efi, systemd-tpm, efitools, tpm2-tools, cryptsetup, gardenlinux-update, and resizefat32. |
requirements.mod | Declares that the UEFI requirement must be satisfied (requirements["uefi"]=true). |
file.include/etc/kernel/cmdline.d/99-no-gpt-auto.cfg (file.include) | Disables GPT auto-discovery in the kernel command line so that only the ESP is auto-mounted. |
file.include/etc/systemd/system/gardenlinux-etc-setup-hooks.service (file.include) | Systemd service that runs first-boot /etc setup hooks after the overlay is ready. |
file.include/etc/update-motd.d/25-secureboot (file.include) | MOTD script that displays the current Secure Boot enrollment status. |
file.include/usr/local/sbin/update-kernel-cmdline (file.include) | Rebuilds the kernel command line file from fragments in /etc/kernel/cmdline.d/. |
file.include/usr/sbin/enroll-gardenlinux-secureboot-keys (file.include) | Enrolls the Garden Linux Secure Boot keys into the UEFI firmware key databases. |
file.include/usr/sbin/run-etc-setup-hooks (file.include) | Runs executable scripts from a hooks directory to apply first-boot /etc configuration. |
initrd.include/etc/repart.d/00-efi.conf (initrd.include) | systemd-repart partition definition used in the initrd to locate and grow the EFI partition. |
initrd.include/etc/systemd/system/setup-etc-overlay.service (initrd.include) | Initrd systemd service that creates and mounts the writable /etc overlay before pivot. |
initrd.include/etc/systemd/system/sysroot-etc.mount (initrd.include) | Mounts the /etc overlay onto /sysroot/etc in the initrd. |
initrd.include/etc/systemd/system/sysroot-home.mount (initrd.include) | Mounts /var/home onto /sysroot/home for user data persistence. |
initrd.include/etc/systemd/system/sysroot-opt.mount (initrd.include) | Mounts /var/opt onto /sysroot/opt for optional software persistence. |
initrd.include/etc/systemd/system/sysroot-root.mount (initrd.include) | Mounts /var/root onto /sysroot/root for root home persistence. |
initrd.include/etc/systemd/system/sysroot.mount (initrd.include) | Mounts the EROFS root image onto /sysroot in the initrd. |
initrd.include/etc/systemd/system/sysroot-opt.mount (initrd.include) | Mounts /var/opt onto /sysroot/opt. |
initrd.include/etc/systemd/system/initrd-root-fs.target.requires/ (initrd.include) | Systemd .requires symlinks ensuring all sysroot mount units are ordered before initrd-root-fs.target. |
initrd.include/etc/systemd/system-generators/detect-disk-by-efivars (initrd.include) | Systemd generator that identifies the boot disk by reading EFI variables, used to locate the ESP. |
initrd.include/etc/systemd/system-generators/dracut-crypt-generator (initrd.include) | Dracut-compatible generator for cryptsetup integration in the initrd. |
initrd.include/usr/bin/repart-esp-disk (initrd.include) | Helper script that invokes systemd-repart to locate and optionally grow the EFI partition. |
initrd.include/usr/bin/setup-etc-overlay (initrd.include) | Script invoked by setup-etc-overlay.service to create the tmpfs-based /etc overlay. |
Related features
Includes:
_nocrypt— disables disk encryption, which is incompatible with embedding the root filesystem in the ESP._unsigned— skips signing the UKI during local/development builds; replace with a signing feature for production.
Excludes (incompatible with):
_legacy— BIOS/legacy boot is incompatible with the UEFI-only UKI boot approach.