Scroll to navigation

SYSTEMD-STORAGE-FS@.SERVICE(8) systemd-storage-fs@.service SYSTEMD-STORAGE-FS@.SERVICE(8)

NAME

systemd-storage-fs@.service, systemd-storage-fs.socket, systemd-storage-fs - Storage provider exposing regular files and directories as storage volumes

SYNOPSIS

systemd-storage-fs@.service

systemd-storage-fs.socket

DESCRIPTION

systemd-storage-fs@.service is a service that implements the io.systemd.StorageProvider Varlink[1] 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

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 directory. The former (and all inodes below it) must be owned by the foreign UID range, the latter by the host's root.

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.

TEMPLATES

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".)

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

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.

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/
systemd 261~rc4