## containers-storage 1 "August 2024"

## NAME
containers-storage-composefs - Information about composefs and containers/storage

## DESCRIPTION

To enable composefs at a baseline requires the following configuration in `containers-storage.conf`:

```
[storage.options.overlay]
use_composefs = "true"
```

This value must be a "string bool", it cannot be a native TOML boolean.

However at the current time, composefs requires zstd:chunked images, so first
you must be sure that zstd:chunked is enabled.
For more, see [zstd:chunked](containers-storage-zstd-chunked.md).

Additionally, not many images are in zstd:chunked format. In order to bridge this gap,
`convert_images = "true"` can be specified which does a dynamic conversion; this adds
latency to image pulls.

Putting these things together, the following is required (in addition to the above config).

```
[storage.options.pull_options]
convert_images = "true"
```

This value must be a "string bool", it cannot be a native TOML boolean.

## IMPLEMENTATION

As is implied by the setting `use_composefs = "true"`, currently composefs
is implemented as an "option" for the `overlay` driver. Some file formats
remain unchanged and are inherited from the overlay driver, even when
composefs is in use. The primary differences are enumerated below.

The `diff/` directory for each layer is no longer a plain unpacking of the
tarball, but becomes an "object hash directory", where each filename is the
sha256 of its contents. This `diff/` directory is the backing store for a
`composefs-data/composefs.blob` created for each layer which is the composefs
"superblock" containing all the non-regular-file content (i.e. metadata) from
the tarball.

As with `zstd:chunked`, existing layers are scanned for matching objects, and reused
(via hardlink or reflink as configured) if objects with a matching "full sha256" are
found.

There is currently no support for enforced integrity with composefs;
an attempt is made to enable fsverity for the backing files and the composefs file,
but it is not an error if unsupported. There is as of yet no defined mechanism to
verify the fsverity digest of the composefs block before mounting; some work on that is
ongoing.

In order to mount a layer (or a full image, with all of its dependencies), any
layer that has a composefs blob is mounted and included in the "final" overlayfs
stack. This is optional - any layers that are not in "composefs format" but
in the "default overlay" (unpacked) format will be reused as is.

## BUGS

https://github.com/containers/storage/issues?q=is%3Aissue+is%3Aopen+label%3Aarea%2Fcomposefs

## FOOTNOTES
The Containers Storage project is committed to inclusivity, a core value of open source.
The `master` and `slave` mount propagation terminology is used in this repository.
This language is problematic and divisive, and should be changed.
However, these terms are currently used within the Linux kernel and must be used as-is at this time.
When the kernel maintainers rectify this usage, Containers Storage will follow suit immediately.
