SYSTEMD.MSTACK(7)

💖 SYSTEMD.MSTACK 💖

okay so bestie, we're talking about systemd.mstack — mount stacks, but make them self-descriptive. it's giving organized. it's giving main character. let's get into it 🫶

---

✨ NAME ✨

systemd.mstack — mount stacks living in self descriptive directories 🌸

---

🎀 DESCRIPTION 🎀

So. Directories with the .mstack/ suffix? They can encode 'mount stacks' for assembling OS mount hierarchies out of bind mounts and overlay mounts. Where do you use them? Two places, periodt:

• systemd-nspawn(1)'s --mstack= switch
• the service manager's RootMStack= setting for services

A .mstack/ directory can hold all kinds of files and subdirectories, and each one effects one layer of an "overlayfs" mount, or a bind mount. The name of the file or subdirectory is what tells you how it gets used in the mount hierarchy. Specifically, these names are defined:

1. A layer@id/ directory gets turned into a layer of an overlayfs mount. The "id" identifier defines the order of the layers: a version sort runs, the first entry is the bottom layer in the "overlayfs" stack, and the last entry becomes the highest layer — precisely, the highest "lowerdir" — in the "overlayfs" stack. 💅
2. Similar vibes: a layer@id.raw regular file gets mounted as a DDI, and that resulting mount gets turned into an overlayfs layer, following the exact same sorting rules.
3. An rw directory becomes a writable layer at the very top of the "overlayfs" stack. A subdirectory data of it becomes the "upperdir", and a subdirectory work becomes the "workdir". Heads up bestie: those two subdirectories do not need to be created explicitly — they get created automatically on first use if they're missing. no cap ✨
4. A bind@location/ directory gets bind mounted to the mount point indicated by the location identifier, in read-write fashion. The location is encoded via the same escaping logic used for naming ".mount" units, i.e. slashes become dashes.
5. Similar: a bind@location.raw file gets mounted as a DDI, and the resulting mount gets bind mounted to the specified location.
6. A robind@location/ is treated very similar to bind@location/, but the resulting bind mount is read-only.
7. Similar: robind@location.raw creates a read-only bind mount from a DDI.
8. If a root/ subdirectory exists, it's used as root of the resulting mount hierarchy, and only the usr/ subtree of the overlayfs mount will be bound to usr/ in the hierarchy.

🫶 note note note: each of the entry types above may be a symbolic link pointing to a directory or image file, instead of a directory or image file itself. yes really.

On each listed file or subdirectory type, the systemd.v(7) functionality may be used — that's your automatic selection of versioned resources. iconic.

And to process or mount .mstack/ directories straight from the command line? Use the systemd-mstack(1) tool. 🌈

---

🦋 EXAMPLES 🦋

Example one: this .mstack/ consists of two read-only overlayfs layers as DDI, plus one writable directory on top. The read-only layers are symlinked:

1. foobar.mstack/layer@0.raw → ../base.raw
2. foobar.mstack/layer@1.raw → ../app.raw
3. foobar.mstack/rw/

Example two: this .mstack/ consists of a read-only DDI mounted to "/usr/" and a writable root:

1. waldo.mstack/layer@0.raw → ../vendor.raw
2. waldo.mstack/root/

Example three: this .mstack/ consists of a read-only DDI mounted as root, but a writable /var/ mounted on top:

1. quux.mstack/layer@0.raw → ../myapp1.raw
2. quux.mstack/bind:var → ../myapp1-var/

---

⭐ SEE ALSO ⭐

systemd(1), systemd-mstack(1), systemd-nspawn(1), systemd.exec(5), systemd.v(7), systemd-vpick(1)

---

and that's the whole page bestie 💜 this was systemd 262.1, SYSTEMD.MSTACK(7) — go build a mount stack, you're literally the moment 👑🎀