# ComposeFS Integration in apt-layer ## TLDR - Quick Reference ### Basic Commands **Create a ComposeFS image:** ```sh mkcomposefs --digest-store= ``` **Mount a ComposeFS image:** ```sh mount -t composefs -o basedir= # or directly: mount.composefs -o basedir= ``` **Unmount:** ```sh umount ``` **Inspect an image:** ```sh composefs-info ls # List files composefs-info objects # List backing files composefs-info missing-objects --basedir= # Check integrity composefs-info dump # Full metadata dump ``` ### Quick Example ```sh # 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](https://ostreedev.github.io/ostree/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 --digest-store=` | | `composefs-info` | Inspect and manage images | `composefs-info [ls\|objects\|missing-objects\|dump] ` | | `mount.composefs` | Mount images (helper for `mount -t composefs`) | `mount.composefs -o basedir=` | **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: ```sh mkcomposefs --digest-store= ``` - ``: Directory containing the root filesystem to layer - ``: Output ComposeFS image (typically ends with `.composefs`). This file contains the image metadata (an EROFS image file) - `--digest-store=`: This option specifies a directory where `mkcomposefs` will copy (or reflink) regular files larger than 64 bytes from ``. These files are content-addressed (named after their `fsverity` digest) and form the "backing store" for the ComposeFS image. This directory is then referenced as the `basedir` during 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: ```sh mount.composefs -o basedir=[,basedir=...] ``` Using the standard `mount` command (which relies on `mount.composefs` as a helper): ```sh mount -t composefs -o basedir=[,basedir=...] ``` - ``: Path to the ComposeFS image file (metadata) - ``: Where to mount the filesystem - `-o basedir=`: This option is crucial. It points to the directory (or multiple colon-separated directories) containing the content-addressed backing files created with `--digest-store` during image creation. This provides the underlying content for the ComposeFS image **Optional `mount.composefs` options:** - `digest=DIGEST`: Validates the image file against a specified `fs-verity` digest for integrity - `verity`: Ensures all files in the image and base directories have matching `fs-verity` digests. Requires kernel 6.6rc1+ - `idmap=PATH`: Specifies a user namespace for ID mapping - `upperdir`/`workdir`: Allows for a writable overlay on top of the read-only ComposeFS image, similar to `overlayfs` ### 3. Unmounting ```sh umount ``` ### 4. Listing and Removing Images - **Listing:** apt-layer lists ComposeFS images by scanning for `.composefs` files in its workspace. Additionally, `apt-layer` can use `composefs-info ls ` to inspect the contents of an image, or `composefs-info missing-objects --basedir=` to verify the integrity of the object store. For advanced scenarios, `composefs-info dump` can provide a textual representation of the image's metadata (as defined by `composefs-dump(5)`), which can also be used as input for `mkcomposefs --from-file` - **Removing:** apt-layer removes images by deleting the corresponding `.composefs` file and cleaning up the associated content-addressed files in the `--digest-store` directory. This cleanup typically involves checking `composefs-info objects` to identify files that are no longer referenced by any active images before removal --- ## Integration Notes - **Specific Tools:** While there isn't a single monolithic `composefs` CLI, specialized commands like `composefs-info` exist for introspection, and `mount.composefs` is the dedicated helper for mounting (callable directly or via `mount -t composefs`) - **Dependencies:** apt-layer requires `mkcomposefs`, `composefs-info`, `mount.composefs` (which might be part of the `composefs` package), `mksquashfs`, and `unsquashfs` for ComposeFS support - **Fallback:** If `mkcomposefs` (and potentially `mount.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 --- ## References - [ComposeFS Upstream Documentation](https://ostreedev.github.io/ostree/composefs/) - [ComposeFS GitHub Repository](https://github.com/containers/composefs) - [ComposeFS Blog Post by Alexander Larsson](https://blogs.gnome.org/alexl/2022/06/02/using-composefs-in-ostree/) - [`mkcomposefs(1)` man page](https://www.mankier.com/1/mkcomposefs) - [`mount.composefs(1)` man page](https://www.mankier.com/1/mount.composefs) - [`composefs-info(1)` man page](https://www.mankier.com/1/composefs-info) - [`composefs-dump(5)` man page](https://www.mankier.com/5/composefs-dump)