systemd-storage-fs@.service, systemd-storage-fs.socket, systemd-storage-fs — Storage provider exposing regular files and directories as storage volumes
systemd-storage-fs@.service
systemd-storage-fs.socket
systemd-storage-fs@.service is a service that implements the
io.systemd.StorageProvider Varlink
interface, exposing regular files and directories in /var/lib/storage/*.volume (if
used in system mode) or $XDG_STATE_HOME/storage (when used in user mode) as storage
volumes. Acquired volumes are returned to the caller as file descriptors. Unlike
systemd-storage-block@.service(8),
this implementation also supports creating new volumes on demand from a small set of built-in
templates.
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, in user
mode on $XDG_RUNTIME_DIR/systemd/io.systemd.StorageProvider/fs. See
storagectl(1) for an
enumeration tool.
See also systemd-storage-block@.service(8) for a complementary implementation that exposes local block devices as storage volumes.
Volumes are stored below the storage directory:
/var/lib/storage/ when run in system mode.
$XDG_STATE_HOME/storage/ (typically
~/.local/state/storage/) when run in user mode.
Each volume on disk is stored as a directory entry with a .volume suffix in
the storage directory. Entries which are regular files are exposed as volumes of type
reg; entries which are directories are exposed as volumes of type
dir. Moreover, block device nodes may be symlinked (or bind mounted) into the
directory, which are then exposed as volumes of type blk.
For directory volumes, the root of the file system passed to clients is placed in a subdirectory
root/ of the NAME.volume
When acquiring a volume, symlinks are followed.
An administrator is permitted to freely manipulate the volume hierarchy directly as long as the rules described above are followed. In particular, it's permitted to copy, mount or symlink arbitrary external resources (regardless if directory, regular file or block) into the volume directory, so that they are exposed as additional volumes.
The provider supports creating new volumes automatically when they are acquired. The caller may select a template that determines configuration details of the volume to create. The following built-in templates are 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".)
allocated-file¶Creates a volume backed by a fully allocated regular file. (Volume type is
"reg".)
directory¶Creates a volume backed by a regular directory. (Volume type is
"dir".)
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".)
The following command-line options are understood:
--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.
--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.
-h, --help¶--version¶/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.
/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.