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.
composefs separates metadata (directories, permissions, xattrs) from data (file content). An EROFS image carries only the metadata; data files live in a content-addressed backing store, shared across images and in the Linux page cache. Optional fs-verity provides end-to-end integrity verification of both data and metadata. For design details, see the crate documentation.
composefs improves on the traditional per-layer overlayfs model for OCI container images by storing file content in a content-addressed store, enabling sharing between images and faster pulls via zstd:chunked.
composefs aims to succeed OSTree by replacing hardlink checkouts with directly-mountable images backed by a shared object store. Combined with fs-verity and a digest embedded in the kernel commandline or a UKI, this provides cryptographic verification of the entire filesystem tree. See this tracking issue for background.
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.