The composefs project combines several underlying Linux features to provide a very flexible mechanism to support read-only mountable filesystem trees, stacking on top of an underlying "lower" Linux filesystem.
This repository is the primary reference implementation of composefs, written in Rust. It replaces the previous C-based implementation; for background on this transition, see this discussion.
The key technologies composefs uses are:
- overlayfs as the kernel interface
- EROFS for a mountable metadata tree
- fs-verity (optional) from the lower filesystem
composefs does not store any persistent data itself.
The underlying metadata and data files must be stored in a valid
"lower" Linux filesystem — usually a traditional writable persistent
filesystem such as ext4, xfs, or btrfs.
The tagline — "The reliability of disk images, the flexibility of files" — captures the core design philosophy. Disk images have desirable properties: they're efficiently kernel-mountable and explicit about layout, and tools like dm-verity provide robust security. But disk images commonly duplicate storage, are difficult to update incrementally, and are generally inflexible.
composefs provides a similarly high level of reliability, security, and Linux kernel integration, but with the flexibility of files for content — avoiding doubled disk usage, partition table management, and similar headaches.
A key aspect of composefs is its separation of "data" (non-empty regular files) from "metadata" (everything else: directories, symlinks, permissions, ownership, etc.).
composefs produces an EROFS filesystem
image that contains only metadata. The non-empty data files live in a
separate "backing store" directory. The EROFS image includes
trusted.overlay.redirect extended attributes that tell the overlayfs
mount how to find the real underlying files.
The primary use case for composefs is versioned, immutable filesystem trees — container images and bootable host systems — where multiple images may share parts of their storage.
By storing files content-addressed (named by the hash of their content), shared files need to be stored only once on disk yet can appear in multiple mounts. Crucially, these data files are also shared in the page cache, allowing multiple running container images to reliably share memory.
composefs supports fs-verity
validation of content files. The digest of each content file is stored
in the EROFS image via trusted.overlay.metacopy extended attributes,
which overlayfs validates when the file is accessed. This means backing
content cannot be changed (by mistake or by malice) without detection.
You can also enable fs-verity on the image file itself and pass the expected digest as a mount option. This provides full trust of both data and metadata, solving a weakness of fs-verity alone (which can only verify file data, not metadata like permissions, ownership, or directory structure).
For OCI container images, a common approach (used by both Docker and Podman) is to untar each layer separately and use overlayfs to stitch them together. composefs improves on this by storing file content in a content-addressed fashion, allowing sharing between images even when metadata like timestamps or ownership differs.
Combined with approaches like zstd:chunked, this speeds up pulling container images and avoids redundantly creating files that are already present.
Anywhere one wants versioned immutable filesystem trees ("images"), composefs provides compelling advantages. In particular, this project aims to be the successor to OSTree.
OSTree uses a content-addressed object store, but traditionally checks out into a regular directory (using hardlinks), which is then bind-mounted as the rootfs. While OSTree supports enabling fs-verity on files in the store, nothing protects the checkout directories from modification.
composefs replaces this checkout with a directly-mountable image pointing into the object store. We can enable fs-verity on the composefs image and embed its digest in the kernel commandline or a Unified Kernel Image (UKI). Since composefs generation is reproducible, we can verify the generated image is correct by comparing its digest to one in the metadata produced at build time. For more on this, see this tracking issue.
composefs: Core library for composefs operations including filesystem trees, fs-verity support, and repository managementcomposefs-oci: OCI image handling and integration with container registriescomposefs-boot: Boot infrastructure support including UKI (Unified Kernel Image) and BLS (Boot Loader Specification) integrationcomposefs-http: HTTP support for fetching composefs contentcomposefs-fuse: FUSE filesystem implementation
cfsctl: Primary CLI tool for managing composefs repositoriescomposefs-setup-root: Early boot tool for setting up the root filesystem from a composefs image
The examples directory contains working demonstrations of building verified OS images:
- UKI: Unified Kernel Image with embedded composefs digest
- BLS: Traditional kernel/initramfs with Boot Loader Specification entries
- Unified: Streamlined UKI build using in-container measurement
- Unified-SecureBoot: UKI with Secure Boot signing support
Images stored in a composefs repository can be mounted using cfsctl:
cfsctl mount <image-name> /mntThe image can be identified by its fs-verity digest or by a ref/<name> reference.
The C implementation (composefs-c) provides a mount.composefs
helper that supports mount -t composefs syntax directly.
This project is under active development. The repository layout and on-disk formats may still change.
- Live chat: Matrix channel
- Async forums: GitHub Discussions
The C implementation
provides mkcomposefs and mount.composefs and is still packaged in
many distributions. The Go containers/storage
library also has integration with mkcomposefs. These tools continue to
work, but new feature development is happening here.
See LICENSE-APACHE and LICENSE-MIT.
Copyright contributors to composefs, established as composefs a Series of LF Projects, LLC.