Module boot

bootc_lib::bootc_composefs

Module boot 

Source
Expand description

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 🔒
SecurebootKeys
UKIInfo 🔒

Enums§

BootSetupType 🔒
BootType

Constants§

AUTH_EXT 🔒
BOOTC_AUTOENROLL_PATH 🔒
EFI_LINUX 🔒
The EFI Linux directory
EFI_UUID_FILE 🔒
Contains the EFP’s filesystem UUID. Used by grub
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.
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.
SYSTEMD_LOADER_CONF_PATH 🔒
SYSTEMD_TIMEOUT 🔒
Timeout for systemd-boot bootloader menu
SYSTEMD_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
VMLINUZ 🔒

Functions§

compute_boot_digest 🔒
Compute SHA256Sum of VMlinuz + Initrd
compute_boot_digest_uki 🔒
Compute SHA256Sum of .linux + .initrd section of the UKI
find_vmlinuz_initrd_duplicates 🔒
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_esp_partition
get_secureboot_keys 🔒
get_sysroot_parent_dev
mount_esp
Mount the ESP from the provided device
parse_os_release 🔒
Parses /usr/lib/os-release and returns (id, title, version)
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.
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 🔒
type1_entry_conf_file_name
Generate BLS Type 1 entry filename compatible with Grub’s RPM-style parsing.
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 🔒