142 lines
6.9 KiB
Markdown
142 lines
6.9 KiB
Markdown
# ComposeFS Integration in apt-layer
|
|
|
|
## TLDR - Quick Reference
|
|
|
|
### Basic Commands
|
|
|
|
**Create a ComposeFS image:**
|
|
```sh
|
|
mkcomposefs <source-dir> <output.img> --digest-store=<object-store-dir>
|
|
```
|
|
|
|
**Mount a ComposeFS image:**
|
|
```sh
|
|
mount -t composefs -o basedir=<object-store-dir> <output.img> <mountpoint>
|
|
# or directly:
|
|
mount.composefs <output.img> <mountpoint> -o basedir=<object-store-dir>
|
|
```
|
|
|
|
**Unmount:**
|
|
```sh
|
|
umount <mountpoint>
|
|
```
|
|
|
|
**Inspect an image:**
|
|
```sh
|
|
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
|
|
```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 <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:
|
|
|
|
```sh
|
|
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 where `mkcomposefs` will copy (or reflink) regular files larger than 64 bytes from `<rootfs-dir>`. 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 <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):
|
|
|
|
```sh
|
|
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-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 <mountpoint>
|
|
```
|
|
|
|
### 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 <image.composefs>` to inspect the contents of an image, or `composefs-info missing-objects <image.composefs> --basedir=<object-store-dir>` 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)
|