Filesystem: Physical /sysroot
By default, bootc uses ostree as a backend, and maps fetched container images to a deployment. The layout of the composefs backend is described below.
stateroot
The underlying ostree CLI and API tooling expose a concept of stateroot, which
is not yet exposed via bootc. The stateroot used by bootc install
is just named default.
The stateroot concept allows having fully separate parallel operating
system installations with fully separate /etc and /var, while
still sharing an underlying root filesystem.
In the future, this functionality will be exposed and used by bootc.
/sysroot mount
When booted, the physical root will be available at /sysroot as a
read-only mount point. With composefs enabled (as recommended in
filesystem, and always with the composefs
backend), the logical root / is a read-only composefs mount of the
deployed image; otherwise it is a bind mount of a deployment directory
under /sysroot/ostree. This is a key aspect of how bootc upgrade
operates: it fetches the updated container image and writes the base
image files (in /sysroot/ostree/repo with the OSTree backend, or in
/sysroot/composefs with the composefs backend).
Beyond that and debugging/introspection, there are few use cases for tooling to operate on the physical root.
bootc-owned container storage
For logically bound images,
bootc maintains a dedicated containers/storage
instance using the overlay backend (the same type of thing that backs /var/lib/containers).
This storage is accessible via a /usr/lib/bootc/storage symbolic link which points into
/sysroot. (Avoid directly referencing the /sysroot target)
At the current time, this storage is not used for the base bootable image. This unified storage issue tracks unification.
Expanding the root filesystem
One notable use case that does need to operate on /sysroot
is expanding the root filesystem.
Disk images are often booted on a disk larger than the image, for example in the cloud, so the root partition and filesystem need to be grown at boot. bootc does not do this itself; the base image (or an image derived from it) needs to include something that does.
Provisioning tools such as cloud-init or Ignition are commonly expected to handle this, but the image based systems below each do it with a dedicated systemd service:
- The Fedora and CentOS Stream bootc base images
ship
bootc-generic-growpart.service, which runs early in boot on virtual machines, grows the root partition withgrowpart, and then grows the filesystem as described below. Despite its name, it is not part of bootc. Only thestandardvariant includes it; theminimalandminimal-plusvariants do not. - Fedora CoreOS grows the root on first boot with
ignition-ostree-growfs.service, which runs in the initramfs after Ignition has set up the disks; see its storage documentation. - Flatcar Container Linux checks on every boot and grows the root when
the disk has grown, with
extend-filesystems.service; see adding disk space.
Your distribution may also have image variants that don't include a solution, such as the minimal variants above. If you build on one of those and need the root grown, add a service like these in your derived image.
Some higher level tools such as e.g. cloud-init may (reasonably)
expect the / mount point to be the physical root. Tools like
this will need to be adjusted to instead detect this and operate
on /sysroot. For example, cloud-init's
growpart
and resizefs
modules find the device from the source of the / mount, which is
composefs when composefs is enabled, so they currently grow neither
the partition nor the filesystem on such a system (see
cloud-init#6293).
Growing the block device
Fundamentally bootc is agnostic to the underlying block device setup.
How to grow the root block device depends on the underlying
storage stack, from basic partitions to LVM. However, a
common tool is the growpart
utility from cloud-init.
Growing the filesystem
The systemd project ships a systemd-growfs
tool and corresponding systemd-growfs@ services. This is
a relatively thin abstraction over detecting the target
root filesystem type and running the underlying tool such as
xfs_growfs.
At the current time, most Linux filesystems require
the target to be mounted writable in order to grow. Hence,
an invocation of systemd-growfs /sysroot or xfs_growfs /sysroot
will need to be further wrapped in a temporary mount namespace.
Using a MountFlags=slave drop-in stanza for systemd-growfs@sysroot.service
is recommended, along with an ExecStartPre=mount -o remount,rw /sysroot.
bootc-generic-growpart.service above uses the same approach, with
MountFlags=slave on its own unit.
Detecting bootc/ostree systems
See the package managers section on "Detecting image based systems".
composefs backend storage
Unlike the ostree backend, which keeps its repository at /ostree/repo, the composefs backend splits its on-disk state across two top-level directories in the physical sysroot:
/composefs: The composefs-rs repository (mode0700), containing:objects/: content-addressed file storage, keyed by SHA-512 fs-verity digest and shared via reflink (FICLONE) where the filesystem supports itimages/: EROFS images describing each deployment's root filesystem metadata, possibly in both formatsstreams/: OCI manifest, config, and layer splitstreams captured during image pullsbootc/storage/: thecontainers-storage:instance backing logically bound images, reflink-shared with the composefs object store
/state/deploy/<deployment-id>/: Persistent per-deployment state, one directory per deployment (see below for how it is named):etc/: a writable copy of the deployment's/etc, bind-mounted onto the booted root's/etcvar: a symlink to the shared/state/os/default/var, bind-mounted onto the booted root's/var<deployment-id>.origin: an INI file recording the image reference, boot type (BLS, UKI, or aboot) and digest, and the OCI manifest digest (the latter is what keeps a deployment's objects alive across garbage collection)
Although composefs-rs supports other fs-verity hash algorithms, bootc currently hardcodes SHA-512 for the repository. This is why EROFS image IDs and object identifiers are 128-character hex strings.
Three kinds of digest show up here and are easy to confuse. The OCI manifest
digest names the pulled container image (see the origin file above). An EROFS
digest names one bootable image under images/ and is what the kernel command
line refers to; a deployment may have one of each format. The deployment ID names the
state directory; it is the digest of the boot image selected when the
deployment was staged.
There is no /ostree/repo; the composefs backend doesn't use the ostree repository at all. A minimal /ostree directory is still created, but only to hold a compatibility symlink (ostree/bootc -> ../composefs/bootc) so that existing tooling expecting /usr/lib/bootc/storage to resolve through ostree/bootc keeps working.
The transient view of a staged deployment lives under
/run/composefs/staged-deployment. Aboot additionally persists pending and
attempted state so an interrupted A/B update can be reconciled after reboot;
see aboot update state.
The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.