| 1 |
'\" t |
| 2 |
.TH "SYSTEMD\-STORAGE\-FS@\&.SERVICE" "8" "" "systemd 261~rc3" "[email protected]" |
| 3 |
.\" ----------------------------------------------------------------- |
| 4 |
.\" * Define some portability stuff |
| 5 |
.\" ----------------------------------------------------------------- |
| 6 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 7 |
.\" http://bugs.debian.org/507673 |
| 8 |
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| 9 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 10 |
.ie \n(.g .ds Aq \(aq |
| 11 |
.el .ds Aq ' |
| 12 |
.\" ----------------------------------------------------------------- |
| 13 |
.\" * set default formatting |
| 14 |
.\" ----------------------------------------------------------------- |
| 15 |
.\" disable hyphenation |
| 16 |
.nh |
| 17 |
.\" disable justification (adjust text to left margin only) |
| 18 |
.ad l |
| 19 |
.\" ----------------------------------------------------------------- |
| 20 |
.\" * MAIN CONTENT STARTS HERE * |
| 21 |
.\" ----------------------------------------------------------------- |
| 22 |
.SH "NAME" |
| 23 |
[email protected], systemd-storage-fs.socket, systemd-storage-fs \- Storage provider exposing regular files and directories as storage volumes |
| 24 |
.SH "SYNOPSIS" |
| 25 |
.PP |
| 26 |
systemd\-storage\-fs@\&.service |
| 27 |
.PP |
| 28 |
systemd\-storage\-fs\&.socket |
| 29 |
.SH "DESCRIPTION" |
| 30 |
.PP |
| 31 |
systemd\-storage\-fs@\&.service |
| 32 |
is a service that implements the |
| 33 |
\fBio\&.systemd\&.StorageProvider\fR |
| 34 |
\m[blue]\fBVarlink\fR\m[]\&\s-2\u[1]\d\s+2 |
| 35 |
interface, exposing regular files and directories in |
| 36 |
/var/lib/storage/*\&.volume |
| 37 |
(if used in system mode) or |
| 38 |
$XDG_STATE_HOME/storage |
| 39 |
(when used in user mode) as storage volumes\&. Acquired volumes are returned to the caller as file descriptors\&. Unlike |
| 40 |
\[email protected]\fR(8), this implementation also supports creating new volumes on demand from a small set of built\-in templates\&. |
| 41 |
.PP |
| 42 |
The service is socket\-activated via |
| 43 |
systemd\-storage\-fs\&.socket\&. In system mode it listens on the AF_UNIX socket |
| 44 |
/run/systemd/io\&.systemd\&.StorageProvider/fs, in user mode on |
| 45 |
$XDG_RUNTIME_DIR/systemd/io\&.systemd\&.StorageProvider/fs\&. See |
| 46 |
\fBstoragectl\fR(1) |
| 47 |
for an enumeration tool\&. |
| 48 |
.PP |
| 49 |
See also |
| 50 |
\[email protected]\fR(8) |
| 51 |
for a complementary implementation that exposes local block devices as storage volumes\&. |
| 52 |
.SH "VOLUMES" |
| 53 |
.PP |
| 54 |
Volumes are stored below the storage directory: |
| 55 |
.sp |
| 56 |
.RS 4 |
| 57 |
.ie n \{\ |
| 58 |
\h'-04'\(bu\h'+03'\c |
| 59 |
.\} |
| 60 |
.el \{\ |
| 61 |
.sp -1 |
| 62 |
.IP \(bu 2.3 |
| 63 |
.\} |
| 64 |
/var/lib/storage/ |
| 65 |
when run in system mode\&. |
| 66 |
.RE |
| 67 |
.sp |
| 68 |
.RS 4 |
| 69 |
.ie n \{\ |
| 70 |
\h'-04'\(bu\h'+03'\c |
| 71 |
.\} |
| 72 |
.el \{\ |
| 73 |
.sp -1 |
| 74 |
.IP \(bu 2.3 |
| 75 |
.\} |
| 76 |
$XDG_STATE_HOME/storage/ |
| 77 |
(typically |
| 78 |
~/\&.local/state/storage/) when run in user mode\&. |
| 79 |
.RE |
| 80 |
.PP |
| 81 |
Each volume on disk is stored as a directory entry with a |
| 82 |
\&.volume |
| 83 |
suffix in the storage directory\&. Entries which are regular files are exposed as volumes of type |
| 84 |
\fBreg\fR; entries which are directories are exposed as volumes of type |
| 85 |
\fBdir\fR\&. Moreover, block device nodes may be symlinked (or bind mounted) into the directory, which are then exposed as volumes of type |
| 86 |
\fBblk\fR\&. |
| 87 |
.PP |
| 88 |
For directory volumes, the root of the file system passed to clients is placed in a subdirectory |
| 89 |
root/ |
| 90 |
of the |
| 91 |
\fINAME\fR\&.volume |
| 92 |
directory\&. The former (and all inodes below it) must be owned by the foreign UID range, the latter by the host\*(Aqs root\&. |
| 93 |
.PP |
| 94 |
When acquiring a volume, symlinks are followed\&. |
| 95 |
.PP |
| 96 |
An administrator is permitted to freely manipulate the volume hierarchy directly as long as the rules described above are followed\&. In particular, it\*(Aqs 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\&. |
| 97 |
.SH "TEMPLATES" |
| 98 |
.PP |
| 99 |
The provider supports creating new volumes automatically when they are acquired\&. The caller may select a |
| 100 |
\fItemplate\fR |
| 101 |
that determines configuration details of the volume to create\&. The following built\-in templates are available: |
| 102 |
.PP |
| 103 |
\fBsparse\-file\fR |
| 104 |
.RS 4 |
| 105 |
Creates a volume backed by a sparsely populated regular file\&. This is the default template when creating a regular file volume\&. (Volume type is |
| 106 |
"reg"\&.) |
| 107 |
.sp |
| 108 |
Added in version 261\&. |
| 109 |
.RE |
| 110 |
.PP |
| 111 |
\fBallocated\-file\fR |
| 112 |
.RS 4 |
| 113 |
Creates a volume backed by a fully allocated regular file\&. (Volume type is |
| 114 |
"reg"\&.) |
| 115 |
.sp |
| 116 |
Added in version 261\&. |
| 117 |
.RE |
| 118 |
.PP |
| 119 |
\fBdirectory\fR |
| 120 |
.RS 4 |
| 121 |
Creates a volume backed by a regular directory\&. (Volume type is |
| 122 |
"dir"\&.) |
| 123 |
.sp |
| 124 |
Added in version 261\&. |
| 125 |
.RE |
| 126 |
.PP |
| 127 |
\fBsubvolume\fR |
| 128 |
.RS 4 |
| 129 |
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 |
| 130 |
"dir"\&.) |
| 131 |
.sp |
| 132 |
Added in version 261\&. |
| 133 |
.RE |
| 134 |
.SH "OPTIONS" |
| 135 |
.PP |
| 136 |
The following command\-line options are understood: |
| 137 |
.PP |
| 138 |
\fB\-\-system\fR |
| 139 |
.RS 4 |
| 140 |
Operate in system mode\&. Volumes are stored below |
| 141 |
/var/lib/storage/\&. This is the default when invoked from |
| 142 |
systemd\-storage\-fs@\&.service |
| 143 |
in the system manager\&. |
| 144 |
.sp |
| 145 |
Added in version 261\&. |
| 146 |
.RE |
| 147 |
.PP |
| 148 |
\fB\-\-user\fR |
| 149 |
.RS 4 |
| 150 |
Operate in user mode\&. Volumes are stored below |
| 151 |
$XDG_STATE_HOME/storage/\&. This is the default when invoked from |
| 152 |
systemd\-storage\-fs@\&.service |
| 153 |
in the user manager\&. |
| 154 |
.sp |
| 155 |
Added in version 261\&. |
| 156 |
.RE |
| 157 |
.PP |
| 158 |
\fB\-h\fR, \fB\-\-help\fR |
| 159 |
.RS 4 |
| 160 |
Print a short help text and exit\&. |
| 161 |
.RE |
| 162 |
.PP |
| 163 |
\fB\-\-version\fR |
| 164 |
.RS 4 |
| 165 |
Print a short version string and exit\&. |
| 166 |
.RE |
| 167 |
.SH "FILES" |
| 168 |
.PP |
| 169 |
/var/lib/storage/, $XDG_STATE_HOME/storage/ |
| 170 |
.RS 4 |
| 171 |
The storage directory used to back the system mode and user mode service instances respectively\&. Each volume is stored as an entry with a |
| 172 |
\&.volume |
| 173 |
suffix below this directory\&. |
| 174 |
.sp |
| 175 |
Added in version 261\&. |
| 176 |
.RE |
| 177 |
.PP |
| 178 |
/run/systemd/io\&.systemd\&.StorageProvider/fs, $XDG_RUNTIME_DIR/systemd/io\&.systemd\&.StorageProvider/fs |
| 179 |
.RS 4 |
| 180 |
AF_UNIX sockets the service listens on, in system and user mode respectively\&. These are the canonical locations for the |
| 181 |
"fs" |
| 182 |
storage provider, and are enumerated by |
| 183 |
\fBstoragectl providers\fR\&. |
| 184 |
.sp |
| 185 |
Added in version 261\&. |
| 186 |
.RE |
| 187 |
.SH "SEE ALSO" |
| 188 |
.PP |
| 189 |
\fBsystemd\fR(1), \fBstoragectl\fR(1), \[email protected]\fR(8) |
| 190 |
.SH "NOTES" |
| 191 |
.IP " 1." 4 |
| 192 |
Varlink |
| 193 |
.RS 4 |
| 194 |
\%https://varlink.org/ |
| 195 |
.RE |