From e3de69bfaf1fd303e9b05a12060646caf0fb1d16 Mon Sep 17 00:00:00 2001 From: Joseph Marrero Date: Fri, 6 Nov 2026 17:08:25 +0000 Subject: [PATCH 1/3] initramfs: Explain how to recover a strict boot without fs-verity bootc 1.16.0 through 1.16.14 could install with a strict composefs= argument onto an ext4 filesystem made without -O verity (to-filesystem or to-existing-root onto a filesystem another tool created). Those systems booted only because the repository metadata turned enforcement off. Now that a strict command line always requires fs-verity, their next deployment stops in the initramfs with just "fs-verity is not supported by filesystem", which doesn't tell the user that the system is fine and how to get it booting again. When the command line is strict and the filesystem can't do fs-verity at all, say what happened and list the ways out: the previous deployment, adding '?' to the entry (giving up enforcement), or a reinstall onto a filesystem with fs-verity. Generated-by: AI Signed-off-by: Joseph Marrero Corchado --- crates/initramfs/src/lib.rs | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/crates/initramfs/src/lib.rs b/crates/initramfs/src/lib.rs index e8aedbb37b..7c9af14d78 100644 --- a/crates/initramfs/src/lib.rs +++ b/crates/initramfs/src/lib.rs @@ -23,7 +23,7 @@ use rustix::{ use serde::Deserialize; use composefs::{ - fsverity::{FsVerityHashValue, Sha512HashValue}, + fsverity::{CompareVerityError, FsVerityHashValue, MeasureVerityError, Sha512HashValue}, mount::{FsHandle, MountOptions}, mountcompat::{overlayfs_set_fd, overlayfs_set_lower_and_data_fds, prepare_mount}, repository::{ImageNotFound, IntegrityPolicy, Repository, VerityState}, @@ -349,6 +349,25 @@ fn open_root_fs(path: &Path) -> Result { Ok(rootfs) } +/// Shown when a strict `composefs=` boot finds a root filesystem without +/// fs-verity support, e.g. ext4 made without `-O verity` by another tool. +const STRICT_BOOT_WITHOUT_FSVERITY_HELP: &str = "This boot entry requires fs-verity \ +(its composefs= argument has no '?'), but the root filesystem does not support it (for \ +example ext4 created without '-O verity'). To boot, select the previous deployment in \ +the boot menu, or add '?' right after 'composefs=' (or 'composefs.digest=') in this \ +entry's kernel command line, which boots without fs-verity enforcement. To enforce \ +fs-verity, reinstall onto a filesystem with fs-verity enabled"; + +/// Whether `error` comes from a filesystem that cannot do fs-verity at all. +fn is_fsverity_unsupported(error: &anyhow::Error) -> bool { + matches!( + error.downcast_ref::(), + Some(CompareVerityError::Measure( + MeasureVerityError::FilesystemNotSupported + )) + ) +} + /// Prepares a floating mount for composefs and returns the fd /// /// # Arguments @@ -380,7 +399,15 @@ pub fn mount_composefs_image( }; repo.set_integrity_policy(IntegrityPolicy::Explicit(verity))?; // mount_digest only ever looks at images/, never at named refs. - let rootfs = repo.mount_digest(&digest, &MountOptions::default())?; + let rootfs = repo + .mount_digest(&digest, &MountOptions::default()) + .map_err(|error| { + if !allow_missing_fsverity && is_fsverity_unsupported(&error) { + error.context(STRICT_BOOT_WITHOUT_FSVERITY_HELP) + } else { + error + } + })?; set_mount_readonly(&rootfs)?; @@ -721,6 +748,12 @@ mod tests { ), "{error:#}" ); + // Only a filesystem without fs-verity support gets the recovery hint. + assert_eq!( + format!("{error:#}").contains(STRICT_BOOT_WITHOUT_FSVERITY_HELP), + is_fsverity_unsupported(&error), + "{error:#}" + ); let missing = Sha512HashValue::EMPTY.to_hex(); let error = mount_composefs_image(&sysroot, &missing, false).unwrap_err(); From d59d618d8a051c5f624afcc298d38ad31b8f8091 Mon Sep 17 00:00:00 2001 From: Joseph Marrero Date: Sat, 7 Nov 2026 13:20:23 +0000 Subject: [PATCH 2/3] docs: Explain strict composefs= and recovering a boot without fs-verity The composefs docs still described fs-verity enforcement as something only a UKI could relax, and didn't say that the kernel command line alone now decides it. Since a strict composefs= argument always requires fs-verity, systems that bootc 1.16.0 through 1.16.14 installed onto ext4 without -O verity stop booting on their next deployment. The new initramfs error points at the recovery options; the docs now say who is affected, how to check before upgrading, and how to recover, using the same wording as the error. The bootc-root-setup.service(5) and installation pages get the matching small corrections. Generated-by: AI Signed-off-by: Joseph Marrero Corchado --- docs/src/bootc-composefs.7.md | 79 ++++++++++++++++++++-- docs/src/bootc-installation.7.md | 7 +- docs/src/man/bootc-root-setup.service.5.md | 8 ++- 3 files changed, 81 insertions(+), 13 deletions(-) diff --git a/docs/src/bootc-composefs.7.md b/docs/src/bootc-composefs.7.md index 1dc1902e15..848ddf6fbe 100644 --- a/docs/src/bootc-composefs.7.md +++ b/docs/src/bootc-composefs.7.md @@ -5,7 +5,9 @@ and the composefs backend uses [composefs-rs](https://github.com/composefs/compo instead of ostree to store and manage deployments. Both are supported and covered by the project's [stability guarantees](https://github.com/bootc-dev/bootc/blob/main/RELEASES.md#stability-guarantees). In particular, the project is committed to upgrading every composefs system -installed since bootc 1.16.0 in place. +installed since bootc 1.16.0 in place. Some installs made by bootc 1.16.0 +through 1.16.14 need a one-time change to their boot entry first; see +[Strict boot entries without fs-verity](#strict-boot-entries-without-fs-verity). The composefs backend is required for [sealed images](building/bootc-sealed-images.7.md), and the image determines which backend `bootc install` uses; see @@ -16,12 +18,20 @@ on-disk layout is described in [Filesystem: sysroot](bootc-sysroot.7.md#composef The composefs backend has two independent integrity controls: -- **fs-verity enforcement.** By default every object in the composefs - repository must have fs-verity enabled, and the root filesystem is only - mounted if its digest matches the one on the kernel command line. Building a - UKI with `--allow-missing-verity` adds a `?` marker to that argument, which - makes fs-verity optional (for filesystems such as XFS that lack it). Both UKI - and traditional kernel/initramfs installs can enforce fs-verity. +- **fs-verity enforcement.** A strict `composefs=` (or + `composefs.digest=`) kernel argument requires fs-verity: every object of the + booted image must have fs-verity enabled, and the root filesystem is only + mounted if its digest matches the one on the kernel command line. The kernel + command line alone decides this, whatever the repository's metadata + (`meta.json`) says. A `?` marker right after the `=`, as in + `composefs=?`, makes fs-verity optional (for filesystems such as XFS + that lack it), though a digest that can be measured must still match. + For a traditional kernel, `bootc install` adds the marker on XFS or with + `--allow-missing-verity`; a UKI gets it when built with + `bootc container ukify --allow-missing-verity`. Both UKI and + traditional kernel/initramfs installs can enforce fs-verity. See + [Strict boot entries without fs-verity](#strict-boot-entries-without-fs-verity) + if a strict entry stops booting after an upgrade. - **Boot authentication.** In a *sealed* deployment fs-verity is enforced and the expected root digest is embedded in a UKI signed for Secure Boot, so firmware authenticates the digest and the digest authenticates the root @@ -29,6 +39,61 @@ The composefs backend has two independent integrity controls: unsigned UKI still has fs-verity checked at mount time, but nothing authenticates the digest itself. +## Strict boot entries without fs-verity + +Earlier versions of bootc's initramfs did not enforce fs-verity for a strict +entry when the repository had been created without it. bootc 1.16.0 through +1.16.14 could install a strict entry that way, with +`bootc install to-filesystem` or `to-existing-root` (including +`system-reinstall-bootc`) onto ext4 created without `-O verity` by another +tool, for example Anaconda or a cloud image. Those systems booted without +fs-verity. The first deployment whose initramfs enforces it stops in +`bootc-root-setup.service` with an error saying that the boot entry requires +fs-verity but the root filesystem does not support it. + +Other installs are not affected: XFS installs get the `?` marker; +`install to-disk`, image-builder and bootc-image-builder create ext4 with +fs-verity; btrfs installs have fs-verity on the image and its objects; other +bootc versions refuse a strict install onto ext4 without fs-verity; and the +ostree backend is not involved. To check a system before upgrading, run +this script as root (`/sysroot/composefs` is mode 0700): + +```sh +#!/bin/sh +args=$(tr ' ' '\n' /dev/null | cut -d' ' -f1 | grep -q V; then echo "unaffected: strict, and the image has fs-verity"; exit 0; fi + echo "AFFECTED: strict $arg but $img has no fs-verity ($(findmnt -no FSTYPE /sysroot) root)"; exit 1 +done +echo "unknown: no composefs image found for $args"; exit 2 +``` + +If it prints AFFECTED, add `?` right after `composefs=` (or +`composefs.digest=`) in the booted entry, reboot, then upgrade; upgrades copy +the marker into the new entry. For systemd-boot the entries are +`/boot/loader/entries/*.conf` on the ESP; for GRUB with `/boot` on the root +filesystem they are `/sysroot/boot/loader/entries/*.conf`. These are usually +mounted read-only; see +[Kernel arguments](building/bootc-kernel-arguments.7.md#kernel-arguments-injected-at-installation-time) +for how to edit them. This gives up fs-verity enforcement, which these systems +never had. + +If the new deployment already stopped, select the previous deployment in the +boot menu (press a key while systemd-boot starts, or Shift, Esc or F4 for +GRUB); it boots with its own initramfs, and nothing falls back automatically. +Then add `?` to the new entry's file and reboot. From the GRUB editor, adding +`?` lasts for one boot. A UKI's command line is inside the UKI, so the marker +can't be added to it: select the previous UKI, then upgrade to an image whose +UKI is built with `bootc container ukify --allow-missing-verity`. + +To enforce fs-verity instead, reinstall onto a filesystem with +fs-verity enabled, such as ext4 created with `-O verity`. Turning the ext4 +feature on afterwards doesn't by itself give the objects already stored +fs-verity. + ## EROFS formats composefs-rs can encode the EROFS image for a root filesystem in two formats, diff --git a/docs/src/bootc-installation.7.md b/docs/src/bootc-installation.7.md index f143ab5102..5055347162 100644 --- a/docs/src/bootc-installation.7.md +++ b/docs/src/bootc-installation.7.md @@ -155,9 +155,10 @@ root. That module is not enabled by default: the reference enables it, and other base images need to as well; see [bootc-root-setup.service(5)](man/bootc-root-setup.service.5.md). -On a root filesystem without fs-verity support (such as XFS), fs-verity is -made optional automatically for a traditional kernel install; -`--allow-missing-verity` does this explicitly. +On XFS, which lacks fs-verity, fs-verity is made optional automatically for +a traditional kernel install; `--allow-missing-verity` does this explicitly. +On ext4, fs-verity is required, so with `to-filesystem` or `to-existing-root` +the filesystem must have been created with `-O verity` (`to-disk` does this). ## More advanced installation with `to-filesystem` diff --git a/docs/src/man/bootc-root-setup.service.5.md b/docs/src/man/bootc-root-setup.service.5.md index d711968d3b..1ec14e3008 100644 --- a/docs/src/man/bootc-root-setup.service.5.md +++ b/docs/src/man/bootc-root-setup.service.5.md @@ -6,15 +6,17 @@ bootc-root-setup.service A oneshot systemd service that runs in the initramfs to set up the root filesystem when the composefs backend is active. It is gated on the -`composefs=` kernel command line argument and on +`composefs=` or `composefs.digest=` kernel command line argument and on `ConditionPathExists=/etc/initrd-release`, so it only runs inside an initramfs. The service is ordered after `sysroot.mount` and before `initrd-root-fs.target`. It performs the following steps: 1. Opens the composefs repository at `/sysroot/composefs`. -2. Mounts the EROFS image identified by the `composefs=` kernel - argument, with fs-verity verification. +2. Mounts the EROFS image `images/` named by the `composefs=` + or `composefs.digest=` kernel argument. fs-verity is required unless the + digest is preceded by `?`, whatever the repository metadata says; see + **bootc-composefs(7)**. 3. Optionally wraps the root in a transient tmpfs overlay (see `root.transient` in **bootc-setup-root-conf.toml(5)**). 4. Bind-mounts or overlays `/etc` and `/var` from the per-deployment state From a1bb3ad02d3ff5596c2e630d8f2117639314fd36 Mon Sep 17 00:00:00 2001 From: Joseph Marrero Date: Sat, 7 Nov 2026 13:51:27 +0000 Subject: [PATCH 3/3] install: Say what --allow-missing-verity does and doesn't cover The help said the flag makes fs-verity optional "in case the filesystem doesn't support it", which reads as a way to install onto any filesystem. It isn't: bootc picks the provisional repository's policy from the filesystem type, so on ext4 the repository starts out strict and the install fails writing meta.json when the filesystem was made without -O verity, flag or not. What the flag actually changes is the boot policy (the '?' marker) and the recorded repository policy, and an image with a UKI ignores it in favor of its own command line. That ext4 case has failed since 9ccd87dd (v1.17.0) started choosing the policy before inspecting the image; 1.16 created the repository relaxed when the flag was given. Whether the code should honor the flag there again is a separate question; this documents what it does today. Generated-by: AI Signed-off-by: Joseph Marrero Corchado --- crates/lib/src/install.rs | 9 +++++++-- docs/src/man/bootc-install-to-disk.8.md | 2 +- docs/src/man/bootc-install-to-existing-root.8.md | 2 +- docs/src/man/bootc-install-to-filesystem.8.md | 2 +- 4 files changed, 10 insertions(+), 5 deletions(-) diff --git a/crates/lib/src/install.rs b/crates/lib/src/install.rs index 00d642f862..d2ec8a8f21 100644 --- a/crates/lib/src/install.rs +++ b/crates/lib/src/install.rs @@ -424,8 +424,13 @@ pub(crate) struct InstallComposefsOpts { #[serde(default)] pub(crate) composefs_backend: bool, - /// Make fs-verity validation optional in case the filesystem doesn't support it - /// (composefs backend only) + /// Make fs-verity optional: add the `?` marker to the composefs kernel argument + /// (`composefs.digest=?...` or `composefs=?...`) and don't require fs-verity in the + /// repository (composefs backend only). Installing onto ext4 created without `-O verity` + /// still fails; use ext4 with `-O verity`, or XFS. + /// + /// This is the default on XFS. For an image with a UKI or an aboot image, the command line + /// built into it decides instead (see `bootc container ukify --allow-missing-verity`). #[clap(long, default_value_t)] #[serde(default)] pub(crate) allow_missing_verity: bool, diff --git a/docs/src/man/bootc-install-to-disk.8.md b/docs/src/man/bootc-install-to-disk.8.md index c05eecc829..0d59dc4244 100644 --- a/docs/src/man/bootc-install-to-disk.8.md +++ b/docs/src/man/bootc-install-to-disk.8.md @@ -193,7 +193,7 @@ set `discoverable-partitions = true` in their install configuration **--allow-missing-verity** - Make fs-verity validation optional in case the filesystem doesn't support it (composefs backend only) + Make fs-verity optional: add the `?` marker to the composefs kernel argument (`composefs.digest=?...` or `composefs=?...`) and don't require fs-verity in the repository (composefs backend only). Installing onto ext4 created without `-O verity` still fails; use ext4 with `-O verity`, or XFS Default: false diff --git a/docs/src/man/bootc-install-to-existing-root.8.md b/docs/src/man/bootc-install-to-existing-root.8.md index d9694977c9..ff70594221 100644 --- a/docs/src/man/bootc-install-to-existing-root.8.md +++ b/docs/src/man/bootc-install-to-existing-root.8.md @@ -224,7 +224,7 @@ of migrating the fstab entries. See the "Injecting kernel arguments" section abo **--allow-missing-verity** - Make fs-verity validation optional in case the filesystem doesn't support it (composefs backend only) + Make fs-verity optional: add the `?` marker to the composefs kernel argument (`composefs.digest=?...` or `composefs=?...`) and don't require fs-verity in the repository (composefs backend only). Installing onto ext4 created without `-O verity` still fails; use ext4 with `-O verity`, or XFS Default: false diff --git a/docs/src/man/bootc-install-to-filesystem.8.md b/docs/src/man/bootc-install-to-filesystem.8.md index 1e9aa736bd..e476808a17 100644 --- a/docs/src/man/bootc-install-to-filesystem.8.md +++ b/docs/src/man/bootc-install-to-filesystem.8.md @@ -133,7 +133,7 @@ is currently expected to be empty by default. **--allow-missing-verity** - Make fs-verity validation optional in case the filesystem doesn't support it (composefs backend only) + Make fs-verity optional: add the `?` marker to the composefs kernel argument (`composefs.digest=?...` or `composefs=?...`) and don't require fs-verity in the repository (composefs backend only). Installing onto ext4 created without `-O verity` still fails; use ext4 with `-O verity`, or XFS Default: false