Module boot 

Composefs boot setup and configuration.

This module handles setting up boot entries for composefs-based deployments, including generating BLS (Boot Loader Specification) entries, copying kernel/initrd files, managing UKI (Unified Kernel Images), and configuring the ESP (EFI System Partition).

Boot Ordering

A critical aspect of this module is boot entry ordering, which must work correctly across both Grub and systemd-boot bootloaders despite their fundamentally different sorting behaviors.

Critical Context: Grub’s Filename Parsing

Grub does NOT read BLS fields - it parses the filename as an RPM package name! See: https://github.com/ostreedev/ostree/issues/2961

Grub’s split_package_string() parsing algorithm:

1. Strip .conf suffix
2. Find LAST - → extract release field
3. Find SECOND-TO-LAST - → extract version field
4. Remainder → name field

Example: kernel-5.14.0-362.fc38.conf

• name: kernel
• version: 5.14.0
• release: 362.fc38

Critical: Grub sorts by (name, version, release) in DESCENDING order.

Bootloader Differences

Grub

• Ignores BLS sort-key field completely
• Parses filename to extract name-version-release
• Sorts by (name, version, release) DESCENDING
• Any - in name/version gets incorrectly split

Systemd-boot

• Reads BLS sort-key field
• Sorts by sort-key ASCENDING (A→Z, 0→9)
• Filename is mostly irrelevant

Implementation Strategy

Filenames (for Grub’s RPM-style parsing and descending sort):

• Format: bootc_{os_id}-{version}-{priority}.conf
• Replace - with _ in os_id to prevent mis-parsing
• Primary: bootc_fedora-41.20251125.0-1.conf → (name=bootc_fedora, version=41.20251125.0, release=1)
• Secondary: bootc_fedora-41.20251124.0-0.conf → (name=bootc_fedora, version=41.20251124.0, release=0)
• Grub sorts: Primary (release=1) > Secondary (release=0) when versions equal

Sort-keys (for systemd-boot’s ascending sort):

• Primary: bootc-{os_id}-0 (lower value, sorts first)
• Secondary: bootc-{os_id}-1 (higher value, sorts second)

Boot Entry Ordering

After an upgrade, both bootloaders show:

1. Primary: New/upgraded deployment (default boot target)
2. Secondary: Currently booted deployment (rollback option)

Structs

BLSEntryPath 🔒

ExpectedBootImageIds 🔒

ExpectedComposefsDigest 🔒

The composefs digests embedded in the primary boot artifact, used to reconcile the freshly-generated boot image digest before it is mounted.

MountedImageRoot 🔒

A composefs image attached to a temporary directory with the ESP and a tmpfs mounted inside it, ready for bootloader installation.

PreparedAbootArtifacts 🔒

RecoveredBootImage 🔒

SecurebootKeys

UKIInfo 🔒

UkiComposefsCandidate 🔒

One composefs digest from a UKI command line.

Enums

BootSetupType 🔒

BootType

UKIDigestMismatch 🔒

UkiCandidateFormat 🔒

The EROFS format a UKI composefs kernel argument claims for its digest.

Constants

AUTH_EXT 🔒

BOOTC_AUTOENROLL_PATH 🔒

BOOTC_UKI_DIR 🔒

We want to be able to control the ordering of UKIs so we put them in a directory that’s not the directory specified by the BLS spec. We do this because we want systemd-boot to only look at our config files and not show the actual UKIs in the bootloader menu This is relative to the ESP

EFI_LINUX 🔒

The EFI Linux directory

EFI_UUID_FILE 🔒

Contains the EFP’s filesystem UUID. Used by grub

ESP_MOUNT_DATA 🔒

FAT mount options: owner-only permissions on files (0600) and dirs (0700).

ESP_MOUNT_FLAGS 🔒

Mount flags shared by all ESP mounts: non-executable, no setuid.

FILENAME_PRIORITY_PRIMARY 🔒

Filename release field for primary (new/upgraded) entry. Grub parses this as the “release” field and sorts descending, so “1” > “0”.

FILENAME_PRIORITY_SECONDARY 🔒

Filename release field for secondary (currently booted) entry.

GLOBAL_UKI_ADDONS_DIR 🔒

Directory (relative to the ESP) where systemd-stub looks for UKI addons that apply to every UKI, as opposed to addons scoped to a single UKI (which live alongside it under BOOTC_UKI_DIR). Unlike per-UKI addons, these aren’t tied to a single deployment, so they’re neither namespaced by deployment verity nor cleaned up by GC.

INITRD 🔒

SORTKEY_PRIORITY_PRIMARY 🔒

Sort-key priority for primary (new/upgraded) entry. Systemd-boot sorts by sort-key in ascending order, so “0” appears before “1”.

SORTKEY_PRIORITY_SECONDARY 🔒

Sort-key priority for secondary (currently booted) entry.

STAGED_GLOBAL_UKI_ADDONS_DIR 🔒

Where all staged Global UKI Addons are kept

VMLINUZ 🔒

Functions

aboot_disk_partition_payloads 🔒

aboot_partition_path 🔒

compute_aboot_boot_digest 🔒

compute_boot_digest 🔒

Compute SHA256Sum of VMlinuz + Initrd

compute_boot_digest_aboot 🔒

compute_boot_digest_type1 🔒

compute_boot_digest_uki 🔒

Compute SHA256Sum of .linux + .initrd section of the UKI

ensure_correct_composefs_digest 🔒

Validates that the freshly-generated boot image digest computed_id matches what’s embedded in the UKI (if any), and if not, searches for an [composefs_oci::XattrFiltering] mode whose boot image digest does match via [composefs_oci::find_matching_boot_image], before giving up.

expected_boot_image_ids 🔒

Associate every accepted boot image with its EROFS serialization format. A UKI’s V1 candidate must never be accepted merely because its digest is a valid V2 image (or vice versa). selected is the freshly generated image; recovered images are added with their actual format by the recovery path.

file_from_type2_entry 🔒

Return a UKI/UKI Addon as a file descriptor from a Type2Entry boot entry

find_expected_composefs_digest 🔒

Scans entries for the primary UKI or aboot payload and extracts the composefs digests embedded in its kernel cmdline.

find_vmlinuz_initrd_duplicate 🔒

Given the SHA256 sum of current VMlinuz + Initrd combo, find boot entry with the same SHA256Sum

get_efi_uuid_source 🔒

Returns the beginning of the grub2/user.cfg file where we source a file containing the ESPs filesystem UUID

get_global_uki_addon_name 🔒

Returns the name of a global UKI Addon directory given name with or without the .addon.efi prefix

get_scoped_uki_addon_name 🔒

Returns the name of a scoped/local UKI Addon directory given name with or without the .addon.efi prefix

get_secureboot_keys 🔒

get_type1_dir_name 🔒

Returns the name of the directory where we store Type1 boot entries

get_uki_addon_dir_name 🔒

Returns the name of a UKI Addon directory given verity digest

get_uki_name 🔒

Returns the name of a UKI given verity digest

grub_bls_abs_entries_path 🔒

The absolute path GRUB resolves the kernels and initramfses in BLS entries against: the root of the filesystem holding grub_boot_path.

image_bootloader 🔒

image_fsverity_policy 🔒

Inspect primary boot artifacts to discover the image’s fs-verity policy before creating the durable repository. Final artifact validation occurs while installing the boot artifact.

install_aboot_disk_payload 🔒

install_composefs_bootloader 🔒

install_ukiboot 🔒

mount_esp

Fresh mount(2) of the ESP into a tempdir. Returns EBUSY if the device is already mounted in the current mount namespace; callers should use mount_esp_readonly or mount_esp_writable instead of this primitive so that pre-existing mounts are handled.

mount_esp_at 🔒

Mount the ESP from device at the given path and return a guard that synchronously unmounts (and flushes) it on drop.

mount_esp_readonly

Get a read-only view of the ESP for the provided device, gracefully handling the case where the ESP is already mounted in the root mount namespace (e.g. via systemd.mount-extra=UUID=<ESP>:/boot:auto:ro). If the ESP is already mounted, that mount is cloned privately into a tempdir; otherwise a fresh read-write mount is performed. The returned mount may be rw or ro; callers must not write through it.

mount_esp_writable

Get a read-write view of the ESP for the provided device, gracefully handling the case where the ESP is already mounted (possibly read-only) in the current mount namespace.

os_id_from_sort_key 🔒

Returns the os_id in a sort key from primary_sort_key or secondary_sort_key, or None if it isn’t in their format.

parse_os_release

Parses /usr/lib/os-release and returns (id, title, version) Expects a reference to the root of the filesystem, or the root of a mounted EROFS

parse_uki_cmdline 🔒

Makes sure there is no composefs= cmdline in a global UKI Addon Makes sure if we already have a parsed cmdline, we don’t find another one

parse_uki_composefs_candidates 🔒

Parse every composefs argument emitted by supported bootc UKIs.

pe_output_dir 🔒

Determines the directory (under mounted_efi) that a PE binary should be written to.

prepare_composefs_aboot_artifacts 🔒

primary_boot_entry 🔒

Pick the first real bootable entry, skipping UKI addons.

primary_sort_key 🔒

Generate sort key for the primary (new/upgraded) boot entry. Format: bootc-{id}-0 Systemd-boot sorts ascending by sort-key, so “0” comes first. Grub ignores sort-key and uses filename/version ordering.

primary_uki_candidate 🔒

Retain the historical V1 preference for the deployment identity while validating every fallback candidate. This avoids changing the naming of existing dual-format UKIs when their kernel arguments are reordered.

print_uki_dumpfile_diff 🔒

print_uki_dumpfile_diff_on_mismatch 🔒

Print the dumpfile diff when a UKI digest mismatch is about to escape.

read_aboot_payload 🔒

read_dumpfile_from_fs 🔒

read_regular_file 🔒

reconcile_uki_candidates 🔒

The repository-independent part of ensure_correct_composefs_digest: every UKI candidate must name a boot image of an acceptable format, found either among expected_ids or via find_matching.

replace_composefs_karg 🔒

Replace either karg spelling to ensure only the selected EROFS format remains.

resolve_boot_image_match 🔒

Interprets the result of searching for a boot image whose digest matches expected (see [composefs_oci::find_matching_boot_image]): uses the matching mode’s digest if one was found, or fails with an error listing every combination tried if not.

secondary_sort_key 🔒

Generate sort key for the secondary (currently booted) boot entry. Format: bootc-{id}-1

setup_composefs_bls_boot 🔒

Sets up and writes BLS entries and binaries (VMLinuz + Initrd) to disk

setup_composefs_boot 🔒

setup_composefs_uki_boot 🔒

stage_global_uki_addons 🔒

Copies Global UKI Addons from loader/addons to loader/addons.staged in case of an upgrade/switch

type1_entry_conf_file_name

Generate BLS Type 1 entry filename compatible with Grub’s RPM-style parsing.

uki_candidates_policy 🔒

uki_file_name 🔒

validate_aboot_composefs_candidates 🔒

validate_aboot_disk_layout 🔒

validate_bootloader 🔒

validate_composefs_aboot_payload 🔒

validate_uki_candidates 🔒

write_aboot_partition 🔒

write_bls_boot_entries_to_disk 🔒

write_grub_uki_menuentry 🔒

write_pe_to_esp 🔒

Writes a PortableExecutable to ESP along with any PE specific or Global addons

write_systemd_uki_config 🔒

write_type1_entries 🔒

Writes a deployment’s Type 1 boot entry. A staged deployment replaces any earlier staged one, whose entry may have another version in its file name, and keeps the booted deployment’s entry next to it.