Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 35 additions & 2 deletions crates/initramfs/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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},
Expand Down Expand Up @@ -349,6 +349,25 @@ fn open_root_fs(path: &Path) -> Result<OwnedFd> {
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::<CompareVerityError>(),
Some(CompareVerityError::Measure(
MeasureVerityError::FilesystemNotSupported
))
)
}

/// Prepares a floating mount for composefs and returns the fd
///
/// # Arguments
Expand Down Expand Up @@ -380,7 +399,15 @@ pub fn mount_composefs_image(
};
repo.set_integrity_policy(IntegrityPolicy::Explicit(verity))?;
// mount_digest only ever looks at images/<digest>, 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)?;

Expand Down Expand Up @@ -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();
Expand Down
9 changes: 7 additions & 2 deletions crates/lib/src/install.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
79 changes: 72 additions & 7 deletions docs/src/bootc-composefs.7.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -16,19 +18,82 @@ 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=<digest>` (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=?<digest>`, 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
filesystem. A BLS entry or an
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' </proc/cmdline | grep -E '^composefs(\.digest)?=') || { echo "unaffected: not booted with composefs"; exit 0; }
for arg in $args; do
val=${arg#*=}
case $val in \?*) echo "unaffected: '?' set, fs-verity is optional"; exit 0;; esac
img=$(readlink -e /sysroot/composefs/images/${val##*:}) || continue
if lsattr "$img" 2>/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,
Expand Down
7 changes: 4 additions & 3 deletions docs/src/bootc-installation.7.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down
2 changes: 1 addition & 1 deletion docs/src/man/bootc-install-to-disk.8.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/src/man/bootc-install-to-existing-root.8.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/src/man/bootc-install-to-filesystem.8.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
8 changes: 5 additions & 3 deletions docs/src/man/bootc-root-setup.service.5.md
Original file line number Diff line number Diff line change
Expand Up @@ -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=<digest>` kernel
argument, with fs-verity verification.
2. Mounts the EROFS image `images/<digest>` named by the `composefs=<digest>`
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
Expand Down
Loading