# 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. --- ## Package Structure ### Debian/Ubuntu Packages ComposeFS is packaged in Debian/Ubuntu as three separate packages: #### 1. `composefs` (Main Tools Package) **Purpose:** Userspace tools for ComposeFS operations **Contains:** - `/usr/bin/mkcomposefs` - Create ComposeFS images - `/usr/bin/composefs-info` - Inspect and manage images - `/usr/bin/mount.composefs` - Mount helper for `mount -t composefs` - `/usr/share/man/man1/` - Manual pages for all tools - `/usr/share/doc/composefs/` - Documentation #### 2. `libcomposefs1` (Runtime Library) **Purpose:** Runtime shared library for ComposeFS **Contains:** - `/usr/lib/x86_64-linux-gnu/libcomposefs.so.1` - Runtime library - `/usr/lib/x86_64-linux-gnu/libcomposefs.so.1.4.0` - Library version - **Dependencies:** `glibc`, `libgcc`, `openssl-libs` #### 3. `libcomposefs-dev` (Development Package) **Purpose:** Development headers and pkg-config files **Contains:** - `/usr/include/libcomposefs/` - Header files - `/usr/lib/x86_64-linux-gnu/libcomposefs.so` - Development symlink - `/usr/lib/x86_64-linux-gnu/pkgconfig/composefs.pc` - pkg-config file - **Dependencies:** `libcomposefs1 (= ${binary:Version})` ### Fedora/RHEL Packages ComposeFS is packaged in Fedora/RHEL as three separate packages: #### 1. `composefs` (Main Tools Package) **Purpose:** Userspace tools for ComposeFS operations **Contains:** Same tools as Debian package #### 2. `composefs-libs` (Runtime Library) **Purpose:** Runtime shared library for ComposeFS **Contains:** Same library as Debian `libcomposefs1` #### 3. `composefs-devel` (Development Package) **Purpose:** Development headers and pkg-config files **Contains:** Same development files as Debian `libcomposefs-dev` ### Installation Commands **Debian/Ubuntu:** ```sh sudo apt install -y composefs libcomposefs1 ``` **Fedora/RHEL:** ```sh sudo dnf install -y composefs composefs-libs ``` **For development (optional):** ```sh # Debian/Ubuntu sudo apt install -y libcomposefs-dev # Fedora/RHEL sudo dnf install -y composefs-devel ``` ### Build Dependencies The ComposeFS source package requires the following build dependencies: **Debian Build Dependencies:** - `debhelper-compat (= 13)` - `fsverity` - File system verity support - `fuse3` - FUSE filesystem support - `go-md2man` - Markdown to man page converter - `libcap2-bin` - Capability utilities - `libfuse3-dev` - FUSE development headers - `libssl-dev` - OpenSSL development headers - `meson` - Build system - `pkgconf` - Package configuration **Build System:** ComposeFS uses the Meson build system for compilation and packaging. ### Source Package Information - **Repository:** [salsa.debian.org/debian/composefs](https://salsa.debian.org/debian/composefs) - **Maintainer:** Roland Hieber - **Uploaders:** Dylan Aïssi - **Homepage:** [github.com/containers/composefs](https://github.com/containers/composefs) - **License:** BSD 2-Clause "Simplified" License --- ## 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 - **Package Structure:** apt-layer supports the official ComposeFS packages from both Debian (`composefs`, `libcomposefs1`) and Fedora (`composefs`, `composefs-libs`) repositories - **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` (from the `composefs` package), `mksquashfs`, and `unsquashfs` for ComposeFS support - **Distribution Detection:** apt-layer automatically detects the distribution and provides appropriate installation commands for ComposeFS packages - **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)