SYSTEMD-ST...@.SERVICE(8)

💾 SYSTEMD-ST...@.SERVICE — the girlies' guide to systemd-storage-fs ✨

okay so bestie, you know systemd-storage-fs@.service? That's the manual we're reading, and honestly? It's giving storage provider realness. Let's go 💅

---

🌸 NAME 🌸

systemd-storage-fs@.service, systemd-storage-fs.socket, systemd-storage-fs — literally a storage provider that exposes your regular files and directories as storage volumes. no cap, that's the whole vibe.

---

📜 SYNOPSIS 📜

systemd-storage-fs@.service

systemd-storage-fs.socket

---

💖 DESCRIPTION 💖

So systemd-storage-fs@.service is a service that implements the io.systemd.StorageProvider Varlink[1] interface. What does that even mean? It means it's out here exposing regular files and directories in /var/lib/storage/*.volume (if you're running it in system mode) or $XDG_STATE_HOME/storage (if you're in user mode) as storage volumes. The acquired volumes get handed back to whoever asked for them as file descriptors. 🎁

And here's the thing that makes it different from systemd-storage-block@.service(8) — this implementation also supports creating brand new volumes on demand, from a small set of built-in templates. it's giving ✨main character✨ energy, truly.

The service is socket-activated via systemd-storage-fs.socket. In system mode it listens on the AF_UNIX socket /run/systemd/io.systemd.StorageProvider/fs, and in user mode it's on $XDG_RUNTIME_DIR/systemd/io.systemd.StorageProvider/fs. If you want an enumeration tool (iykyk), go look at storagectl(1).

Also pls check out systemd-storage-block@.service(8) — that's the complementary implementation that exposes local block devices as storage volumes. besties, not rivals 🫶

---

📂 VOLUMES 📂

Volumes live below the storage directory, which is:

• /var/lib/storage/ when run in system mode.
• $XDG_STATE_HOME/storage/ (typically ~/.local/state/storage/) when run in user mode.

Every volume on disk is stored as a directory entry with a .volume suffix inside the storage directory. Here's the breakdown bestie:

• Entries that are regular files → exposed as volumes of type reg.
• Entries that are directories → exposed as volumes of type dir.
• And plot twist: block device nodes may be symlinked (or bind mounted) into the directory, and those get exposed as volumes of type blk. 🔥

For directory volumes, the root of the file system that gets passed to clients lives in a subdirectory root/ of the NAME.volume directory. The way that works: the former (and literally all inodes below it) must be owned by the foreign UID range, and the latter must be owned by the host's root. yes, that's the rule, we don't make them 🌸

When acquiring a volume, symlinks are followed. no surprises there.

An administrator is permitted to freely manipulate the volume hierarchy directly, as long as the rules above are followed. In particular, it's permitted to copy, mount or symlink arbitrary external resources (doesn't matter if directory, regular file or block) into the volume directory, so they show up as additional volumes. it's giving "decorate your own room" 🎀

---

🧚 TEMPLATES 🧚

The provider supports creating new volumes automatically when they're acquired. The caller may select a template that determines the configuration details of the volume being created. These are the built-in templates available:

sparse-file

Creates a volume backed by a sparsely populated regular file. This is the default template when creating a regular file volume. (Volume type is "reg".)

Added in version 261.

allocated-file

Creates a volume backed by a fully allocated regular file. (Volume type is "reg".)

Added in version 261.

directory

Creates a volume backed by a regular directory. (Volume type is "dir".)

Added in version 261.

subvolume

Creates a btrfs subvolume as backing inode (falling back to a regular directory if the storage directory is not on btrfs). This is the default template when creating a directory volume. (Volume type is "dir".)

Added in version 261.

---

⚙️ OPTIONS ⚙️

These are the command-line options it understands, bestie:

• --system — Operate in system mode. Volumes are stored below /var/lib/storage/. This is the default when invoked from systemd-storage-fs@.service in the system manager.

Added in version 261.

• --user — Operate in user mode. Volumes are stored below $XDG_STATE_HOME/storage/. This is the default when invoked from systemd-storage-fs@.service in the user manager.

Added in version 261.

• -h, --help — Print a short help text and exit.
• --version — Print a short version string and exit.

---

🗂️ FILES 🗂️

• /var/lib/storage/, $XDG_STATE_HOME/storage/ — The storage directory used to back the system mode and user mode service instances respectively. Each volume is stored as an entry with a .volume suffix below this directory.

Added in version 261.

• /run/systemd/io.systemd.StorageProvider/fs, $XDG_RUNTIME_DIR/systemd/io.systemd.StorageProvider/fs — AF_UNIX sockets the service listens on, in system and user mode respectively. These are the canonical locations for the "fs" storage provider, and are enumerated by storagectl providers.

Added in version 261.

---

👀 SEE ALSO 👀

systemd(1), storagectl(1), systemd-storage-block@.service(8)

---

📝 NOTES 📝

1. Varlink https://varlink.org/

---

and that's the whole page, bestie. go forth and expose some volumes 💅🦋

slay — this was systemd 262.1, manual page SYSTEMD-ST...@.SERVICE(8). periodt. 💖✨