containers-storage(1)

📦
version 1.63.0 · 3 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay bestie, welcome to containers-storage-composefs — the lil info page that spills all the tea about composefs and containers/storage. yes this is the containers-storage(1) manual, we're just vibing in the composefs corner of it. 🦋

✨ DESCRIPTION ✨

so to turn on composefs at a baseline</>, you need this in containers-storage.conf:

[storage.options.overlay]
use_composefs = "true"
⚠️ bestie listen — that value has to be a "string bool". it literally cannot be a native TOML boolean. put quotes on it, or it's not gonna work. 💅

but okay, plot twist: at the current time composefs requires zstd:chunked images. so first you gotta make sure zstd:chunked is actually enabled. for more on that, go peek at zstd:chunked ⟨containers-storage-zstd-chunked.md⟩. 🌸

and also — not many images are in zstd:chunked format rn. 😭 to bridge that gap, you can set convert_images = "true" which does a dynamic conversion. fair warning tho: this adds latency to image pulls. it's giving "worth it but at what cost". 🫶

so putting all of this together, here's what's required (on top of the config above):

[storage.options.pull_options]
convert_images = "true"
⚠️ and again — this value must be a "string bool". not a native TOML boolean. quotes. always quotes. 👑

🔥 IMPLEMENTATION 🔥

as is implied by that use_composefs = "true" setting, composefs is currently 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. let's get into it. ⭐

  • the diff/ directory for each layer is no longer a plain unpacking of the tarball — it 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. recycling queen behavior, honestly. ♻️
  • 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. and 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. no forced glow-up. 💅

💀 BUGS 💀

found a problem? take it here bestie, the maintainers wanna hear it:

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. periodt. 🫶

okay that's the whole page, bestie, you're officially composefs-literate ✨💖 this was the containers-storage(1) manual, and it was last touched August 2024. go forth and configure responsibly. 🎀🦋

📦 where this page comes from