composefs is a Linux filesystem technology created by Alexander Larsson and Giuseppe Scrivano at Red Hat that provides cryptographically verified, read-only filesystem trees with opportunistic file-level sharing across images. Its motivating problem is a gap that neither dm-verity nor plain overlayfs fills cleanly: dm-verity provides strong integrity over a whole block device but requires a self-contained disk image and cannot share files between images; overlayfs allows layered, shared filesystems but protects only file contents (via fs-verity) and not the directory structure or metadata — an attacker who can manipulate a file’s name, permissions, or position in the tree is not caught. composefs closes that gap by separately protecting content and metadata, then composing them at mount time.
Architecturally, a composefs image is a small, read-only EROFS filesystem that stores only metadata — filenames, permissions, xattrs, symlinks, and, for regular files, the expected fs-verity SHA-256 digest of the content rather than the content itself. File data lives separately in a content-addressed object store (a flat directory of files named by their content hash), which is passed to the mount as a basedir. At mount time, the kernel uses overlayfs to compose the EROFS metadata layer over the object store, producing a fully populated directory tree; when a file is read, overlayfs enforces that the backing object’s fs-verity digest matches what the metadata image recorded. The EROFS image itself can be fs-verity-verified at mount time by passing its expected digest, giving a complete chain: a single digest commits the metadata, the metadata commits every file’s content, and the kernel enforces both on every access. composefs requires no new kernel modules; it is built entirely from overlayfs (with the verity option added in kernel 6.6), EROFS, and fs-verity.
The primary consumers are OSTree-based systems and container runtimes. OSTree uses composefs to mount OS trees directly from its content-addressed object store rather than checking out files into a regular directory, replacing hardlink-based checkout with a verified, zero-copy mount. Container runtimes using the zstd:chunked image format can similarly compose container image layers from a shared object store, so files present in multiple images are stored once on disk and verified independently in each mount. The practical effect is that a composefs-mounted root filesystem or container image is as tamper-evident as a dm-verity image — any modification to content or structure causes an I/O error on access — while remaining as storage-efficient and incrementally updatable as a regular file tree. It is central to the verified boot story for bootc and image-based Linux systems where the running OS tree must be attested as unmodified.