composefs: The reliability of disk images, the flexibility of files

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.

How it works

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.

Use cases

Container images

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.

Bootable host systems

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.

Components

Core libraries

• composefs: Core library for composefs operations including filesystem trees, fs-verity support, and repository management
• composefs-oci: OCI image handling and integration with container registries
• composefs-boot: Boot infrastructure support including UKI (Unified Kernel Image) and BLS (Boot Loader Specification) integration
• composefs-http: HTTP support for fetching composefs content
• composefs-fuse: FUSE filesystem implementation

Command-line tools

• cfsctl: Primary CLI tool for managing composefs repositories
• composefs-setup-root: Early boot tool for setting up the root filesystem from a composefs image

Examples

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

Mounting

Images stored in a composefs repository can be mounted using cfsctl:

cfsctl mount <image-name> /mnt

The 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.

Documentation

• API and design documentation
• Examples README

Status

This project is under active development. The repository layout and on-disk formats may still change.

Community

• Live chat: Matrix channel
• Async forums: GitHub Discussions

Governance

composefs is a Cloud Native Computing Foundation (CNCF) Sandbox project and adheres to the CNCF Community Code of Conduct.

See GOVERNANCE.md for how the project is run, MAINTAINERS.md for the current maintainers, and SECURITY.md for how to report a vulnerability.

Badges

composefs-c

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.

License

See LICENSE for details.

Copyright

Copyright contributors to composefs, established as composefs a Series of LF Projects, LLC.