Skip to content

Commit f3dec8c

Browse files
committed
composefs: Use an XBOOTLDR partition with systemd-boot
The Boot Loader Specification lets systemd-boot read Type #1 entries and UKIs from an Extended Boot Loader Partition (XBOOTLDR) on the ESP's disk. The composefs backend always wrote them to the ESP, which doesn't work when the ESP is small. That's the usual case next to Windows: its ESP is often 100 MB, a UKI with a full initramfs can be bigger than that, and composefs keeps the booted, staged and rollback ones side by side. With systemd-boot, use a VFAT XBOOTLDR partition next to the ESP when there is one for UKIs, BLS entries and their kernels and initramfs images, when installing, upgrading and in BootedStorage, which rollback, finalize and GC go through. When booted, that's the partition next to the ESP named by LoaderDevicePartUUID. The bootloader and loader.conf, which systemd-boot only reads from the ESP, stay there. GRUB keeps its own /boot handling, and grub-cc is left alone since it's unclear whether it reads XBOOTLDR. The new tmt test splits the VM's ESP into a 100 MiB ESP and an XBOOTLDR partition, then switches, upgrades and rolls back. Assisted-by: AI Signed-off-by: Kristof Imeri <kristof@lanth.me>
1 parent 35e2808 commit f3dec8c

8 files changed

Lines changed: 373 additions & 28 deletions

File tree

‎crates/lib/src/bootc_composefs/boot.rs‎

Lines changed: 60 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -490,6 +490,43 @@ pub(crate) fn mount_esp_at(
490490
)
491491
}
492492

493+
/// The partition holding UKIs, Type #1 entries and their kernels and
494+
/// initramfs images.
495+
#[derive(Debug)]
496+
pub(crate) enum BootPartition {
497+
/// The EFI System Partition
498+
Esp(String),
499+
/// An Extended Boot Loader Partition on the ESP's disk, which systemd-boot
500+
/// reads entries from per the Boot Loader Specification. It holds UKIs
501+
/// that don't fit on a small ESP, such as one shared with Windows.
502+
Xbootldr(String),
503+
}
504+
505+
impl BootPartition {
506+
/// Use the VFAT XBOOTLDR partition next to the ESP at `esp` when booting
507+
/// with systemd-boot and there is one, and the ESP otherwise.
508+
pub(crate) fn for_esp(esp: String, bootloader: Bootloader) -> Result<Self> {
509+
if bootloader != Bootloader::Systemd {
510+
return Ok(Self::Esp(esp));
511+
}
512+
let xbootldr = bootc_blockdev::list_dev(Utf8Path::new(&esp))?.find_sibling_xbootldr()?;
513+
Ok(match xbootldr {
514+
Some(xbootldr) => {
515+
tracing::debug!("Using XBOOTLDR partition {} next to {esp}", xbootldr.path());
516+
Self::Xbootldr(xbootldr.path())
517+
}
518+
None => Self::Esp(esp),
519+
})
520+
}
521+
522+
/// The partition's device path
523+
pub(crate) fn device(&self) -> &str {
524+
match self {
525+
Self::Esp(device) | Self::Xbootldr(device) => device,
526+
}
527+
}
528+
}
529+
493530
/// Filename release field for primary (new/upgraded) entry.
494531
/// Grub parses this as the "release" field and sorts descending, so "1" > "0".
495532
pub(crate) const FILENAME_PRIORITY_PRIMARY: &str = "1";
@@ -781,7 +818,7 @@ pub(crate) fn setup_composefs_bls_boot(
781818
) -> Result<String> {
782819
let id_hex = id.to_hex();
783820

784-
let (esp_device, mut cmdline_refs, bootloader) = match setup_type {
821+
let (boot_partition, mut cmdline_refs, bootloader) = match setup_type {
785822
BootSetupType::Setup((root_setup, state, postfetch, allow_missing_fsverity)) => {
786823
// root_setup.kargs has [root=UUID=<UUID>, "rw"]
787824
let mut cmdline_options = Cmdline::new();
@@ -821,7 +858,7 @@ pub(crate) fn setup_composefs_bls_boot(
821858
let esp_part = root_setup.device_info.find_first_colocated_esp()?;
822859

823860
(
824-
esp_part.path(),
861+
BootPartition::for_esp(esp_part.path(), postfetch.detected_bootloader)?,
825862
cmdline_options,
826863
postfetch.detected_bootloader.clone(),
827864
)
@@ -854,7 +891,7 @@ pub(crate) fn setup_composefs_bls_boot(
854891
)?;
855892

856893
(
857-
find_booted_from_esp(&storage.physical_root)?,
894+
BootPartition::for_esp(find_booted_from_esp(&storage.physical_root)?, bootloader)?,
858895
cmdline,
859896
bootloader,
860897
)
@@ -890,7 +927,8 @@ pub(crate) fn setup_composefs_bls_boot(
890927
}
891928

892929
BootloaderKind::BLSCompatible => {
893-
let efi_mount = mount_esp_writable(&esp_device).context("Mounting ESP")?;
930+
let efi_mount =
931+
mount_esp_writable(boot_partition.device()).context("Mounting boot partition")?;
894932

895933
let mounted_efi = Utf8PathBuf::from(efi_mount.dir.path().as_str()?);
896934
let efi_linux_dir = mounted_efi.join(EFI_LINUX);
@@ -1621,7 +1659,7 @@ fn write_grub_uki_menuentry(
16211659
setup_type: &BootSetupType,
16221660
boot_label: String,
16231661
id: &Sha512HashValue,
1624-
esp_device: &String,
1662+
esp_device: &str,
16251663
) -> Result<()> {
16261664
let boot_dir = setup_type.grub_boot_path()?;
16271665
create_dir_all(&boot_dir).context("Failed to create boot dir")?;
@@ -1672,7 +1710,7 @@ fn write_grub_uki_menuentry(
16721710
// Open grub2/efiuuid.cfg and write the EFI partition fs-UUID in there
16731711
// This will be sourced by grub2/user.cfg to be used for `--fs-uuid`
16741712
let esp_uuid = Task::new("blkid for ESP UUID", "blkid")
1675-
.args(["-s", "UUID", "-o", "value", &esp_device])
1713+
.args(["-s", "UUID", "-o", "value", esp_device])
16761714
.read()?;
16771715

16781716
grub_dir.atomic_write(
@@ -1702,6 +1740,7 @@ fn write_grub_uki_menuentry(
17021740
#[context("Writing systemd UKI config")]
17031741
fn write_systemd_uki_config(
17041742
esp_dir: &Dir,
1743+
boot_partition: &BootPartition,
17051744
setup_type: &BootSetupType,
17061745
boot_label: String,
17071746
version: Option<String>,
@@ -1759,8 +1798,10 @@ fn write_systemd_uki_config(
17591798
)?;
17601799
}
17611800

1762-
// Write the timeout for bootloader menu if not exists
1763-
if !esp_dir.exists(SYSTEMD_LOADER_CONF_PATH) {
1801+
// Write the timeout for bootloader menu if not exists. systemd-boot only
1802+
// reads it from the ESP.
1803+
if matches!(boot_partition, BootPartition::Esp(_)) && !esp_dir.exists(SYSTEMD_LOADER_CONF_PATH)
1804+
{
17641805
esp_dir
17651806
.atomic_write(SYSTEMD_LOADER_CONF_PATH, SYSTEMD_TIMEOUT)
17661807
.with_context(|| format!("Writing to {SYSTEMD_LOADER_CONF_PATH}"))?;
@@ -1782,7 +1823,7 @@ pub(crate) fn setup_composefs_uki_boot(
17821823
boot_ids: &ExpectedBootImageIds,
17831824
entries: Vec<ComposefsBootEntry<Sha512HashValue>>,
17841825
) -> Result<(String, Sha512HashValue)> {
1785-
let (esp_device, bootloader, missing_fsverity_allowed, uki_addons) = match setup_type {
1826+
let (boot_partition, bootloader, missing_fsverity_allowed, uki_addons) = match setup_type {
17861827
BootSetupType::Setup((root_setup, state, postfetch, allow_missing_fsverity)) => {
17871828
state.require_no_kargs_for_uki()?;
17881829

@@ -1793,7 +1834,7 @@ pub(crate) fn setup_composefs_uki_boot(
17931834
let esp_part = root_setup.device_info.find_first_colocated_esp()?;
17941835

17951836
(
1796-
esp_part.path(),
1837+
BootPartition::for_esp(esp_part.path(), postfetch.detected_bootloader)?,
17971838
postfetch.detected_bootloader.clone(),
17981839
allow_missing_fsverity,
17991840
state.composefs_options.uki_addon.as_ref(),
@@ -1804,7 +1845,7 @@ pub(crate) fn setup_composefs_uki_boot(
18041845
let bootloader = host.require_composefs_booted()?.bootloader.clone();
18051846

18061847
(
1807-
find_booted_from_esp(&storage.physical_root)?,
1848+
BootPartition::for_esp(find_booted_from_esp(&storage.physical_root)?, bootloader)?,
18081849
bootloader,
18091850
booted_cfs.cmdline.allow_missing_fsverity,
18101851
// TODO: We never (re)install UKI addons on upgrade, only on initial
@@ -1816,7 +1857,8 @@ pub(crate) fn setup_composefs_uki_boot(
18161857
}
18171858
};
18181859

1819-
let esp_mount = mount_esp_writable(&esp_device).context("Mounting ESP")?;
1860+
let esp_mount =
1861+
mount_esp_writable(boot_partition.device()).context("Mounting boot partition")?;
18201862

18211863
let mut uki_info: Option<UKIInfo> = None;
18221864

@@ -1887,11 +1929,12 @@ pub(crate) fn setup_composefs_uki_boot(
18871929

18881930
match bootloader.kind()? {
18891931
BootloaderKind::GRUBClassic => {
1890-
write_grub_uki_menuentry(&setup_type, boot_label, &deploy_id, &esp_device)?
1932+
write_grub_uki_menuentry(&setup_type, boot_label, &deploy_id, boot_partition.device())?
18911933
}
18921934

18931935
BootloaderKind::BLSCompatible => write_systemd_uki_config(
18941936
&esp_mount.fd,
1937+
&boot_partition,
18951938
&setup_type,
18961939
boot_label,
18971940
version,
@@ -1966,9 +2009,10 @@ impl MountedImageRoot {
19662009
let composefs = TempMount::mount_fd(composefs_mnt_fd)
19672010
.context("Attaching composefs image to temporary directory")?;
19682011

1969-
// TODO: support XBOOTLDR. Per BLS, the ESP should be mounted at /efi
1970-
// when a separate XBOOTLDR partition is present at /boot. bootc does
1971-
// not yet detect or use XBOOTLDR in the composefs install path, so
2012+
// TODO: Per BLS, the ESP should be mounted at /efi when a separate
2013+
// XBOOTLDR partition is present at /boot. Only the bootloader is
2014+
// installed through this mount, and that always goes on the ESP;
2015+
// bootc writes the boot entries itself (see `BootPartition`), so
19722016
// unconditionally mount the ESP at /boot for now.
19732017
let esp_subdir = "boot";
19742018

‎crates/lib/src/bootloader.rs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -284,7 +284,8 @@ pub(crate) fn install_systemd_boot(
284284
root_path,
285285
"--esp-path",
286286
esp_path_in_root.as_str(),
287-
// If we supported XBOOTLDR in the future, that'd go here with --boot-path.
287+
// No --boot-path: bootc writes the boot entries itself, to an
288+
// XBOOTLDR partition if there is one (see `BootPartition`).
288289
];
289290

290291
if configopts.generic_image {

‎crates/lib/src/store/mod.rs‎

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,9 @@ use composefs::repository::{RepositoryConfig, RepositoryOpenError};
117117
use composefs_ctl::composefs;
118118

119119
use crate::bootc_composefs::backwards_compat::bcompat_boot::prepend_custom_prefix;
120-
use crate::bootc_composefs::boot::{EFI_LINUX, mount_esp, mount_esp_readonly, mount_esp_writable};
120+
use crate::bootc_composefs::boot::{
121+
BootPartition, EFI_LINUX, mount_esp, mount_esp_readonly, mount_esp_writable,
122+
};
121123
use crate::bootc_composefs::status::{ComposefsCmdline, composefs_booted, get_bootloader};
122124
use crate::composefs_consts::{BLS_ENTRY_FILE_PREFIX, TYPE1_ENT_PATH};
123125
use crate::install::BOOT;
@@ -596,22 +598,23 @@ impl BootedStorage {
596598
// respective ESP device UUID
597599
//
598600
// Both mount variants transparently reuse an already-mounted
599-
// ESP when present (e.g. auto-mounted at /boot ro via
601+
// partition when present (e.g. auto-mounted at /boot ro via
600602
// `systemd.mount-extra` in the deployment cmdline).
601-
let esp_path = find_booted_from_esp(&physical_root)?;
603+
let bootloader = get_bootloader()?;
604+
let boot_partition =
605+
BootPartition::for_esp(find_booted_from_esp(&physical_root)?, bootloader)?;
602606

603607
let esp_mount = match esp_access {
604-
EspAccess::ReadOnly => mount_esp_readonly(&esp_path)?,
605-
EspAccess::ReadWrite => mount_esp_writable(&esp_path)?,
608+
EspAccess::ReadOnly => mount_esp_readonly(boot_partition.device())?,
609+
EspAccess::ReadWrite => mount_esp_writable(boot_partition.device())?,
606610
};
607611

608-
let (boot_dir, grub_boot_path) = match get_bootloader()?.kind()? {
612+
let (boot_dir, grub_boot_path) = match bootloader.kind()? {
609613
// We can have a separate /boot and not /sysroot/boot
610614
BootloaderKind::GRUBClassic => {
611615
let (dir, path) = get_boot_dir_for_grub(&physical_root)?;
612616
(dir, Some(path))
613617
}
614-
// NOTE: Handle XBOOTLDR partitions here if and when we use it
615618
BootloaderKind::BLSCompatible => {
616619
(esp_mount.fd.try_clone().context("Cloning fd")?, None)
617620
}
@@ -725,13 +728,15 @@ pub(crate) struct Storage {
725728
/// The 'boot' directory, useful and `Some` only for composefs systems
726729
/// For grub booted systems, this points to `/sysroot/boot`, or to `/boot`
727730
/// if that's a separate boot partition
728-
/// For systemd booted systems, this points to the ESP
731+
/// For systemd booted systems, this points to the ESP, or the XBOOTLDR
732+
/// partition next to it if there is one
729733
pub boot_dir: Option<Dir>,
730734

731735
/// The absolute path of `boot_dir` on composefs systems booted with grub
732736
grub_boot_path: Option<Utf8PathBuf>,
733737

734-
/// The ESP mounted at a tmp location
738+
/// The partition holding the UKIs mounted at a tmp location: the ESP, or
739+
/// with systemd-boot the XBOOTLDR partition next to it if there is one
735740
pub esp: Option<TempMount>,
736741

737742
/// Our runtime state

‎docs/src/bootc-bootloaders.7.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,7 @@ NOTE: none is only supported for the Ostree backend and not for Composefs. It is
3535
Whenever the container image has a UKI, bootc automatically selects the composefs backend during installation. The [prerequisites for sealed images](building/bootc-sealed-images.7.md#prerequisites) describe the currently-supported UKI + systemd-boot configuration. Note that having a UKI does not by itself make an install sealed — that also depends on whether [fs-verity enforcement](bootc-composefs.7.md#overview) is on.
3636

3737
Composefs installs using a traditional `vmlinuz`/`initramfs.img` layout instead of a UKI can enforce fs-verity, but are never sealed, since nothing authenticates the root digest. They can use either `bootupd` (GRUB) or systemd-boot. Under the hood, bootc writes standard BLS boot entries for both UKI and traditional kernels; see the [composefs boot module documentation](https://github.com/bootc-dev/bootc/blob/main/crates/lib/src/bootc_composefs/boot.rs) for details on how entry filenames and sort-keys are chosen to sort correctly on both GRUB and systemd-boot.
38+
39+
### XBOOTLDR partitions
40+
41+
With systemd-boot, if the ESP's disk also has an [Extended Boot Loader Partition](https://uapi-group.org/specifications/specs/boot_loader_specification/#the-partitions) (XBOOTLDR) formatted as VFAT, bootc writes the UKIs, the BLS entries and their kernels and initramfs images there, and only the bootloader goes on the ESP. This is useful when the ESP is too small to hold the UKIs of the booted, staged and rollback deployments, which is common on disks shared with Windows. The partition has to exist when installing; bootc uses it from then on for upgrades, rollbacks and garbage collection.

‎docs/src/bootc-composefs.7.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,8 +142,9 @@ and may change or be removed:
142142
- `--soft-reboot=auto` doesn't fall back to a regular reboot when the new
143143
deployment can't be soft rebooted into; see
144144
[Soft reboots](bootc-upgrades.7.md#soft-reboots).
145-
- Only a single ESP is used (the first one found), and a separate
146-
XBOOTLDR partition is not supported.
145+
- Only a single ESP is used (the first one found). A separate XBOOTLDR
146+
partition is only used with systemd-boot; see
147+
[Bootloaders](bootc-bootloaders.7.md#xbootldr-partitions).
147148
- Rollback with GRUB and UKIs assumes exactly two deployments.
148149
- `bootc internals fsck` doesn't yet comprehensively cover the composefs
149150
backend; see [#2497](https://github.com/bootc-dev/bootc/pull/2497).

‎tmt/plans/integration.fmf‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -367,4 +367,12 @@ execute:
367367
test:
368368
- /tmt/tests/tests/test-60-install-composefs-native
369369
extra-fixme_skip_if_uki: true
370+
371+
/plan-61-composefs-xbootldr:
372+
summary: Test composefs with systemd-boot and an XBOOTLDR partition
373+
discover:
374+
how: fmf
375+
test:
376+
- /tmt/tests/tests/test-61-composefs-xbootldr
377+
extra-skip_if_ostree: true
370378
# END GENERATED PLANS

0 commit comments

Comments
 (0)