70 lines
3.0 KiB
Markdown
70 lines
3.0 KiB
Markdown
## 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.
|