docs: Add (not installed) man pages for composefs and zstd:chunked

These aren't installed yet so they'll just live in the git repository
but hopefully we can expand them and use them as a central reference
point for "how do I do (zstd:chunked)|(composefs)". We have copies
of that kind of instruction in other downstream places but
I think here makes the most sense.

Signed-off-by: Colin Walters <walters@verbum.org>
This commit is contained in:
Colin Walters 2024-08-04 11:42:27 -04:00
parent 39d469c34c
commit 0b440b9b56
2 changed files with 81 additions and 0 deletions

View File

@ -0,0 +1,38 @@
## 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"
```
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).
```
pull_options = {enable_partial_images = "true", use_hard_links = "false", ostree_repos="", convert_images = "true"}
```
## 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.

View File

@ -0,0 +1,43 @@
## containers-storage 1 "August 2024"
## NAME
containers-storage-zstd-chunked - Information about zstd:chunked
## DESCRIPTION
The traditional format for container image layers is [application/vnd.oci.image.layer.v1.tar+gzip](https://github.com/opencontainers/image-spec/blob/main/layer.md#gzip-media-types).
More recently, the standard was augmented with zstd: [application/vnd.oci.image.layer.v1.tar+zstd](https://github.com/opencontainers/image-spec/blob/main/layer.md#zstd-media-types)
which is a more modern and efficient compression format.
`zstd:chunked` is a variant of the `application/vnd.oci.image.layer.v1.tar+zstd` media type that
uses zstd [skippable frames](https://github.com/facebook/zstd/blob/dev/doc/zstd_compression_format.md#skippable-frames)
to include additional metadata (especially a "table of contents") that includes the SHA-256 and offsets of individual chunks of files.
Additionally chunks are compressed separately. This allows a client to dynamically fetch only content which
it doesn't already have using HTTP range requests.
To enable zstd:chunked requires the following changes to `containers-storage.conf`:
```
pull_options = {enable_partial_images = "true", use_hard_links = "false", ostree_repos=""}
```
This option may or may not be enabled by default in your distribution/operating system.
## INTERNALS
At the current time the format is not officially standardized or documented beyond
the comments and code in the reference implementation. At the current time
the file with the most information is [pkg/chunked/internal/compression.go](https://github.com/containers/storage/blob/39d469c34c96db67062e25954bc9d18f2bf6dae3/pkg/chunked/internal/compression.go).
The above is a permanent link for stability, but be sure to check to see if there are newer changes too.
## BUGS
- https://github.com/containers/storage/issues?q=is%3Aissue+label%3Aarea%2Fzstd%3Achunked+is%3Aopen
## 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.