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(); 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/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-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 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