mkcomposefs(1)(composefs)

💖 mkcomposefs — composefs manual, section 1 ✨

okay so bestie, gather round, because we're talking about mkcomposefs from the composefs project and honestly? it's giving main character energy in the container world. this is the section 1 manual page, so it's a command, and it's a whole vibe. let's go 💅

---

🌸 NAME 🌸

mkcomposefs — create a composefs filesystem image ✨

---

🎀 SYNOPSIS 🎀

mkcomposefs SOURCE IMAGE

like that's literally it, two little args, so simple, so clean 🫶

---

🦋 DESCRIPTION 🦋

so here's the lore: the composefs project uses an EROFS image file to store metadata, plus one or more separate directories holding content-addressed backing data for regular files. two things, working together, iconic honestly.

mkcomposefs constructs the mountable "composefs image" using the source as input. it can also create the backing store directory. typically the source is a directory, but with --from-file it can also be a file. versatile queen 👑

---

✨ OPTIONS ✨

okay so first, the ground rules:

the provided SOURCEDIR argument must be a directory, and its entire contents will be read recursively (all of it, no skipping, we're thorough 💖). the provided IMAGE argument will be a mountable composefs image.

and mkcomposefs accepts the following options:

• --digest-store=PATH — this path will become a composefs "object store". regular files larger than 64 bytes in the SOURCEDIR will be copied (reflinked if possible, bestie we love a reflink) into this target directory, named after their fsverity digest. small files get inlined into the image metadata instead. if possible, the added files will have fs-verity enabled. you should pass this directory to the basedir option when you mount the image. iykyk 💅
• --print-digest — print the fsverity digest of the composefs metadata file 🔍
• --print-digest-only — print the fsverity digest of the composefs metadata file, but don't write the image. if this is passed, the IMAGE argument should be left out. no image, just vibes and a digest ✨
• --use-epoch — use a zero time (unix epoch) as the modification time for all files. time is fake, set it to zero 🕰️
• --skip-devices — don't add device nodes to the image 🚫
• --skip-xattrs — don't add xattrs to files in the image 🚫
• --user-xattrs — only add xattrs with the "user." prefix to files in the image. picky but valid 👑
• --from-file — the source is a file in the composefs-dump(5) format. if the specified file is "-", the data is read from stdin. pipe it in, queen 🌈
• --version — the base version to use for the image format
• --max-version — if this specifies a version higher than --version, then the actual image format version used will be adjusted upwards if that is beneficial for the image, up to the max version. so like, it can level up but only if it's worth it 💅
• --threads=count — number of threads to be used to calculate the file digests and copy. default thread count is the number of processors when --threads is not specified. go parallel or go home 🔥

---

🧚 FORMAT VERSIONING 🧚

composefs images are binary reproduceable, meaning that for a given input the result is always the same, giving the same digest of the image. this is important because the digest is used to validate the image — even if the image was re-created rather than transferred as-is. fr fr, the digest is the whole point.

but sometimes the format needs to change, like when a new type of file is introduced or a bug gets fixed. that's handled by introducing a format version.

specifying the version happens with two options: the base version (--version) and the max version (--max-version). when building an image, mkcomposefs tries to keep the image format as low as possible, but if some particular requested feature isn't available with the base feature, and it is accessible in the max version, then the version used will be increased. this lets them introduce new features and fix bugs in a later version and migrate to that using max versions, while still keeping the digests identical for unaffected images. no cap 🫶

if you need 100% binary reproducibility over time, specify the same version and a max version each time.

format version history:

• 0 — initial version
• 1 — supports overlay whiteout files in the image (added in 1.0.3)

the default if no version arguments are specified is version 0 and max version 1.

---

🛡️ SANDBOXING RECOMMENDATIONS 🛡️

this tool essentially just processes an input directory or text file and writes a file. it does not require any privileges at all. literally zero. so if you're invoking this as part of an otherwise privileged process (like, say, a container runtime), we recommend dropping privileges before invoking mkcomposefs. stay safe bestie 🙈

especially if you're using --from-file, you can run this as an unprivileged uid that has no writable filesystem access at all except to a passed file descriptor. for example, you can pass a writable file descriptor for the desired target file as fd 3, and run:

mkcomposefs --from-file - /proc/self/fd/3

to effectively use mkcomposefs as part of a pipeline. so clever, so iconic ✨

an example simple sandboxing starting from root is:

setpriv --nnp --reuid nobody -- mkcomposefs ....

another is to use:

systemd-run -P DynamicUser=yes -P ProtectSystem=strict

yet another (especially if your code is already part of a container runtime) is to use that runtime's existing functionality (seccomp, unsharing user namespace, mounting a restricted subset of the rootfs, etc. — yes the original sentence just ends there, no closing paren, and honestly? we respect it 💀).

---

💜 SEE ALSO 💜

• composefs-info(1)
• mount.composefs(1)
• composefs-dump(5)

composefs upstream ⟨https://github.com/containers/composefs⟩ 🌈

---

and that's the whole page bestie, every flag, every version, every sandboxing tip, all of it, preserved and slaying 💖

okay so final sign-off moment: this page lives under the composefs manual, in the User commands corner, and it's mkcomposefs(1)(composefs) — that's the title, the section, and the family all in one, periodt. go make some images, ily 🫶✨💅