SYSTEMD-MSTACK(1)

✨ SYSTEMD-MSTACK ✨

okay bestie, buckle up, this is the systemd-mstack manual page (you'll also see it filed under SYSTEMD-MSTACK(1), iykyk) 💖

---

🎀 NAME 🎀

systemd-mstack, mount.mstack — Mstack Discoverable Disk Images (DDIs)

---

🌸 SYNOPSIS 🌸

systemd-mstack [OPTIONS...] IMAGE

systemd-mstack [OPTIONS...] [--mount] IMAGE PATH

systemd-mstack [OPTIONS...] [--umount] PATH

---

🦋 DESCRIPTION 🦋

so systemd-mstack is literally the tool for peeking at and playing with .mstack/ mount stack directories, exactly as described in systemd.mstack(7). she does three things, and she does them well:

1. Show you the general mount stack info, including every single "overlayfs" layer and bind mount that's described in there. 👀
2. Mount a mount stack to a local directory.
3. Unmount a mount stack from a local directory.

and here's the cute part — the systemd-mstack command can also be invoked as mount.mstack, and when you do that, she implements the mount(8) "external helper" interface. meaning mount stack directories that are compatible with systemd-mstack can be mounted directly by mount and fstab(5). the deets are down below, don't worry. 💅

also!! in place of the image path you can specify a .v/ versioned directory, see systemd.v(7) for the details. 🌈

---

👑 COMMANDS 👑

if you don't pass any of the command switches listed below, the mount stack you named just gets opened and she shows you the general info about it, including a list of all the defined layers. lowkey the default is a whole vibe check.

• --mount, -m — mount the specified mount stack to the specified directory.

to unmount a mount stack directory that was mounted like this, use the --umount operation.

ngl this functionality is also available in mount(8) via a command like mount -t mstack mystack.mstack targetdir/, and in fstab(5) too. details below, bestie.

Added in version 260.

• -M — this is a shortcut for --mount --mkdir. ✨

Added in version 260.

• --umount, -u — unmount a mount stack from the specified directory. this command expects one argument: a directory where the mount stack was mounted.

all mounted mounts will be recursively unmounted. every last one. she's thorough. 💀

Added in version 260.

• -U — this is a shortcut for --umount --rmdir.

Added in version 260.

• -h, --help — print a short help text and exit. the classic.
• --version — print a short version string and exit.

---

💖 OPTIONS 💖

here's what she understands, queen:

• --read-only, -r — operate in read-only mode. by default, --mount will establish writable mount points. if you specify this option, they get established in read-only mode instead. no cap.

Added in version 260.

• --mkdir — if combined with --mount, the directory you're mounting the mount stack to gets created if it's missing. but heads up: that directory is not automatically removed when the mount stack is unmounted again. 🙈

Added in version 260.

• --rmdir — if combined with --umount, the specified directory where the mount stack is mounted gets removed after unmounting it.

Added in version 260.

• --image-policy= policy — takes an image policy string as argument, as per systemd.image-policy(7). the policy is enforced when operating on the disk image specified via --image=, see above. if not specified, it defaults to the "*" policy, i.e. all recognized file systems in the image are used.
• --image-filter= filter — takes an image filter string as argument, as per systemd.image-filter(7). the filter is taken into consideration when operating on the disk image specified via --image=, see above. if not specified, no filtering is applied. clean. ✨
• --no-pager — do not pipe output into a pager.
• --no-legend — do not print the legend, i.e. column headers and the footer with hints. bye bye clutter 🫶
• --json= MODE — shows output formatted as JSON. expects one of "short" (for the shortest possible output without any redundant whitespace or line breaks), "pretty" (for a pretty version of the same, with indentation and line breaks) or "off" (to turn off JSON output, the default).

---

⭐ EXIT STATUS ⭐

on success, 0 is returned, a non-zero failure code otherwise. periodt.

---

🌟 INVOCATION AS /SBIN/MOUNT.MSTACK 🌟

the systemd-mstack executable may be symlinked to /sbin/mount.mstack. if she's invoked through that, she implements mount(8)'s "external helper" interface for the (pseudo) file system type "mstack". which means conformant mount stack directories may be mounted directly via

# mount -t mstack mystack.mstack targetdir/

in a fashion mostly equivalent to:

# systemd-mstack --mount mystack.mstack targetdir/

⚠️ note that since a single mount stack may contain multiple mount points, it should later be unmounted with umount -R targetdir/, for recursive operation. do not forget the -R, bestie, i am begging 😭

this functionality is particularly useful to mount mount stacks automatically at boot via simple /etc/fstab entries. for example:

/path/to/mystack.nspawn /images/mystack/ mstack defaults 0 0

when invoked this way, the mount options "ro" and "rw" map to the corresponding options listed above (i.e. --read-only). iconic behavior honestly 👑

---

🧚 SEE ALSO 🧚

systemd(1), systemd.mstack(7), systemd-nspawn(1), systemd.exec(5), mount(8), umount(8)

---

and that's the whole thing, bestie!! this page came to you from systemd 262.1 — SYSTEMD-MSTACK(1), dated as ever — so go forth and mount responsibly 💜💅🎀