6.9 KiB
ComposeFS Integration in apt-layer
TLDR - Quick Reference
Basic Commands
Create a ComposeFS image:
mkcomposefs <source-dir> <output.img> --digest-store=<object-store-dir>
Mount a ComposeFS image:
mount -t composefs -o basedir=<object-store-dir> <output.img> <mountpoint>
# or directly:
mount.composefs <output.img> <mountpoint> -o basedir=<object-store-dir>
Unmount:
umount <mountpoint>
Inspect an image:
composefs-info ls <image.composefs> # List files
composefs-info objects <image.composefs> # List backing files
composefs-info missing-objects <image.composefs> --basedir=<dir> # Check integrity
composefs-info dump <image.composefs> # Full metadata dump
Quick Example
# Create image with object store
mkcomposefs /path/to/rootfs myimage.composefs --digest-store=/path/to/objects
# Mount the image
mount -t composefs -o basedir=/path/to/objects myimage.composefs /mnt/composefs
# List contents
composefs-info ls myimage.composefs
# Unmount
umount /mnt/composefs
Note: In apt-layer, images are typically stored in /var/lib/apt-layer/images/ with object stores in the same directory. The above example uses generic paths for clarity.
Overview
apt-layer uses ComposeFS as its backend for atomic, deduplicated, and efficient filesystem layering—mirroring the approach used by rpm-ostree and Fedora Silverblue. ComposeFS is a Linux filesystem and image format designed for fast, space-efficient, and content-addressed deployment of system images.
Key Tools: The ComposeFS project provides a suite of tools including mkcomposefs for image creation, composefs-info for inspecting images, and mount.composefs for mounting. mount.composefs can be called directly or used by the standard mount -t composefs command.
Commands
The composefs package provides the following tools:
| Command | Purpose | Usage |
|---|---|---|
mkcomposefs |
Create ComposeFS images | mkcomposefs <source> <image> --digest-store=<dir> |
composefs-info |
Inspect and manage images | composefs-info [ls|objects|missing-objects|dump] <image> |
mount.composefs |
Mount images (helper for mount -t composefs) |
mount.composefs <image> <mountpoint> -o basedir=<dir> |
Important: There is no composefs executable. The package name is composefs, but the actual tools are mkcomposefs, composefs-info, and mount.composefs.
ComposeFS Workflow in apt-layer
1. Image Creation
To create a ComposeFS image from a directory tree:
mkcomposefs <rootfs-dir> <output.img> --digest-store=<object-store-dir>
<rootfs-dir>: Directory containing the root filesystem to layer<output.img>: Output ComposeFS image (typically ends with.composefs). This file contains the image metadata (an EROFS image file)--digest-store=<object-store-dir>: This option specifies a directory wheremkcomposefswill copy (or reflink) regular files larger than 64 bytes from<rootfs-dir>. These files are content-addressed (named after theirfsveritydigest) and form the "backing store" for the ComposeFS image. This directory is then referenced as thebasedirduring mounting
2. Mounting a ComposeFS Image
To mount a ComposeFS image, apt-layer can either call mount.composefs directly or rely on the kernel's mount -t composefs interface, which will invoke mount.composefs as a helper.
Using mount.composefs directly:
mount.composefs <output.img> <mountpoint> -o basedir=<object-store-dir>[,basedir=<another-object-store-dir>...]
Using the standard mount command (which relies on mount.composefs as a helper):
mount -t composefs -o basedir=<object-store-dir>[,basedir=<another-object-store-dir>...] <output.img> <mountpoint>
<output.img>: Path to the ComposeFS image file (metadata)<mountpoint>: Where to mount the filesystem-o basedir=<object-store-dir>: This option is crucial. It points to the directory (or multiple colon-separated directories) containing the content-addressed backing files created with--digest-storeduring image creation. This provides the underlying content for the ComposeFS image
Optional mount.composefs options:
digest=DIGEST: Validates the image file against a specifiedfs-veritydigest for integrityverity: Ensures all files in the image and base directories have matchingfs-veritydigests. Requires kernel 6.6rc1+idmap=PATH: Specifies a user namespace for ID mappingupperdir/workdir: Allows for a writable overlay on top of the read-only ComposeFS image, similar tooverlayfs
3. Unmounting
umount <mountpoint>
4. Listing and Removing Images
- Listing: apt-layer lists ComposeFS images by scanning for
.composefsfiles in its workspace. Additionally,apt-layercan usecomposefs-info ls <image.composefs>to inspect the contents of an image, orcomposefs-info missing-objects <image.composefs> --basedir=<object-store-dir>to verify the integrity of the object store. For advanced scenarios,composefs-info dumpcan provide a textual representation of the image's metadata (as defined bycomposefs-dump(5)), which can also be used as input formkcomposefs --from-file - Removing: apt-layer removes images by deleting the corresponding
.composefsfile and cleaning up the associated content-addressed files in the--digest-storedirectory. This cleanup typically involves checkingcomposefs-info objectsto identify files that are no longer referenced by any active images before removal
Integration Notes
- Specific Tools: While there isn't a single monolithic
composefsCLI, specialized commands likecomposefs-infoexist for introspection, andmount.composefsis the dedicated helper for mounting (callable directly or viamount -t composefs) - Dependencies: apt-layer requires
mkcomposefs,composefs-info,mount.composefs(which might be part of thecomposefspackage),mksquashfs, andunsquashfsfor ComposeFS support - Fallback: If
mkcomposefs(and potentiallymount.composefs) is not available, apt-layer can fall back to a shell script alternative (for development/testing only) - Compatibility: This approach matches rpm-ostree and Fedora Silverblue's use of ComposeFS for system layering