Debian Codegraph @

upstream/debian-unstable/man8/[email protected]

raw
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