Debian Codegraph @

upstream/debian-unstable/man1/systemd-mount.1

raw
1 '\" t
2 .TH "SYSTEMD\-MOUNT" "1" "" "systemd 261~rc3" "systemd-mount"
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 systemd-mount, systemd-umount \- Establish and destroy transient mount or auto\-mount points
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-mount\fR\ 'u
26 \fBsystemd\-mount\fR [\fIOPTIONS\fR...] \fIWHAT\fR [\fIWHERE\fR]
27 .HP \w'\fBsystemd\-mount\fR\ 'u
28 \fBsystemd\-mount\fR [\fIOPTIONS\fR...] \fB\-\-tmpfs\fR [\fINAME\fR] \fIWHERE\fR
29 .HP \w'\fBsystemd\-mount\fR\ 'u
30 \fBsystemd\-mount\fR [\fIOPTIONS\fR...] \fB\-\-list\fR
31 .HP \w'\fBsystemd\-mount\fR\ 'u
32 \fBsystemd\-mount\fR [\fIOPTIONS\fR...] \fB\-\-umount\fR \fIWHAT|WHERE\fR...
33 .SH "DESCRIPTION"
34 .PP
35 \fBsystemd\-mount\fR
36 may be used to create and start a transient
37 \&.mount
38 or
39 \&.automount
40 unit of the file system
41 \fIWHAT\fR
42 on the mount point
43 \fIWHERE\fR\&.
44 .PP
45 In many ways,
46 \fBsystemd\-mount\fR
47 is similar to the lower\-level
48 \fBmount\fR(8)
49 command, however instead of executing the mount operation directly and immediately,
50 \fBsystemd\-mount\fR
51 schedules it through the service manager job queue, so that it may pull in further dependencies (such as parent mounts, or a file system checker to execute a priori), and may make use of the auto\-mounting logic\&.
52 .PP
53 The command takes either one or two arguments\&. If only one argument is specified it should refer to a block device or regular file containing a file system (e\&.g\&.
54 "/dev/sdb1"
55 or
56 "/path/to/disk\&.img")\&. The block device or image file is then probed for a file system label and other metadata, and is mounted to a directory below
57 /run/media/system/
58 whose name is generated from the file system label\&. In this mode the block device or image file must exist at the time of invocation of the command, so that it may be probed\&. If the device is found to be a removable block device (e\&.g\&. a USB stick), an automount point is created instead of a regular mount point (i\&.e\&. the
59 \fB\-\-automount=\fR
60 option is implied, see below)\&. If the option
61 \fB\-\-tmpfs\fR
62 is specified, then the argument is interpreted as the path where the new temporary file system shall be mounted\&.
63 .PP
64 If two arguments are specified, the first indicates the mount source (the
65 \fIWHAT\fR) and the second indicates the path to mount it on (the
66 \fIWHERE\fR)\&. In this mode no probing of the source is attempted, and a backing device node does not have to exist\&. However, if this mode is combined with
67 \fB\-\-discover\fR, device node probing for additional metadata is enabled, and \(en much like in the single\-argument case discussed above \(en the specified device has to exist at the time of invocation of the command\&.
68 .PP
69 Use the
70 \fB\-\-list\fR
71 command to show a terse table of all local, known block devices with file systems that may be mounted with this command\&.
72 .PP
73 \fBsystemd\-umount\fR
74 can be used to unmount a mount or automount point\&. It is the same as
75 \fBsystemd\-mount\fR
76 \fB\-\-umount\fR\&.
77 .SH "OPTIONS"
78 .PP
79 The following options are understood:
80 .PP
81 \fB\-\-no\-block\fR
82 .RS 4
83 Do not synchronously wait for the requested operation to finish\&. If this is not specified, the job will be verified, enqueued and
84 \fBsystemd\-mount\fR
85 will wait until the mount or automount unit\*(Aqs start\-up is completed\&. By passing this argument, it is only verified and enqueued\&.
86 .sp
87 Added in version 232\&.
88 .RE
89 .PP
90 \fB\-l\fR, \fB\-\-full\fR
91 .RS 4
92 Do not ellipsize the output when
93 \fB\-\-list\fR
94 is specified\&.
95 .sp
96 Added in version 245\&.
97 .RE
98 .PP
99 \fB\-\-no\-pager\fR
100 .RS 4
101 Do not pipe output into a pager\&.
102 .RE
103 .PP
104 \fB\-\-no\-legend\fR
105 .RS 4
106 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
107 .RE
108 .PP
109 \fB\-\-no\-ask\-password\fR
110 .RS 4
111 Do not query the user for authentication for privileged operations\&.
112 .RE
113 .PP
114 \fB\-\-json=\fR\fB\fIMODE\fR\fR
115 .RS 4
116 Shows output formatted as JSON\&. Expects one of
117 "short"
118 (for the shortest possible output without any redundant whitespace or line breaks),
119 "pretty"
120 (for a pretty version of the same, with indentation and line breaks) or
121 "off"
122 (to turn off JSON output, the default)\&.
123 .RE
124 .PP
125 \fB\-\-quiet\fR, \fB\-q\fR
126 .RS 4
127 Suppresses additional informational output while running\&.
128 .sp
129 Added in version 232\&.
130 .RE
131 .PP
132 \fB\-\-discover\fR
133 .RS 4
134 Enable probing of the mount source\&. This switch is implied if a single argument is specified on the command line\&. If passed, additional metadata is read from the device to enhance the unit to create\&. For example, a descriptive string for the transient units is generated from the file system label and device model\&. Moreover, if a removable block device (e\&.g\&. USB stick) is detected an automount unit instead of a regular mount unit is created, with a short idle timeout, in order to ensure the file\-system is placed in a clean state quickly after each access\&.
135 .sp
136 Added in version 232\&.
137 .RE
138 .PP
139 \fB\-\-type=\fR, \fB\-t\fR
140 .RS 4
141 Specifies the file system type to mount (e\&.g\&.
142 "vfat"
143 or
144 "ext4")\&. If omitted or set to
145 "auto", the file system type is determined automatically\&.
146 .sp
147 Added in version 232\&.
148 .RE
149 .PP
150 \fB\-\-options=\fR, \fB\-o\fR
151 .RS 4
152 Additional mount options for the mount point\&.
153 .sp
154 Added in version 232\&.
155 .RE
156 .PP
157 \fB\-\-owner=\fR\fB\fIUSER\fR\fR
158 .RS 4
159 Let the specified user
160 \fIUSER\fR
161 own the mounted file system\&. This is done by appending
162 \fBuid=\fR
163 and
164 \fBgid=\fR
165 options to the list of mount options\&. Only certain file systems support this option\&.
166 .sp
167 Added in version 237\&.
168 .RE
169 .PP
170 \fB\-\-fsck=\fR
171 .RS 4
172 Takes a boolean argument, defaults to on\&. Controls whether to run a file system check immediately before the mount operation\&. In the automount case (see
173 \fB\-\-automount=\fR
174 below) the check will be run the moment the first access to the device is made, which might slightly delay the access\&.
175 .sp
176 Added in version 232\&.
177 .RE
178 .PP
179 \fB\-\-description=\fR
180 .RS 4
181 Provide a description for the mount or automount unit\&. See
182 \fIDescription=\fR
183 in
184 \fBsystemd.unit\fR(5)\&.
185 .sp
186 Added in version 232\&.
187 .RE
188 .PP
189 \fB\-\-property=\fR, \fB\-p\fR
190 .RS 4
191 Sets a unit property for the mount unit that is created\&. This takes an assignment in the same format as
192 \fBsystemctl\fR(1)\*(Aqs
193 \fBset\-property\fR
194 command\&.
195 .sp
196 Added in version 232\&.
197 .RE
198 .PP
199 \fB\-\-automount=\fR
200 .RS 4
201 Takes a boolean argument\&. Controls whether to create an automount point or a regular mount point\&. If true an automount point is created that is backed by the actual file system at the time of first access\&. If false a plain mount point is created that is backed by the actual file system immediately\&. Automount points have the benefit that the file system stays unmounted and hence in clean state until it is first accessed\&. In automount mode the
202 \fB\-\-timeout\-idle\-sec=\fR
203 switch (see below) may be used to ensure the mount point is unmounted automatically after the last access and an idle period passed\&.
204 .sp
205 If this switch is not specified, it defaults to false\&. If not specified and
206 \fB\-\-discover\fR
207 is used (or only a single argument passed, which implies
208 \fB\-\-discover\fR, see above), and the file system block device is detected to be removable, it is set to true, in order to increase the chance that the file system is in a fully clean state if the device is unplugged abruptly\&.
209 .sp
210 Added in version 232\&.
211 .RE
212 .PP
213 \fB\-A\fR
214 .RS 4
215 Equivalent to
216 \fB\-\-automount=yes\fR\&.
217 .sp
218 Added in version 232\&.
219 .RE
220 .PP
221 \fB\-\-timeout\-idle\-sec=\fR
222 .RS 4
223 Takes a time value that controls the idle timeout in automount mode\&. If set to
224 "infinity"
225 (the default) no automatic unmounts are done\&. Otherwise, the file system backing the automount point is detached after the last access and the idle timeout passed\&. See
226 \fBsystemd.time\fR(7)
227 for details on the time syntax supported\&. This option has no effect if only a regular mount is established, and automounting is not used\&.
228 .sp
229 Note that if
230 \fB\-\-discover\fR
231 is used (or only a single argument passed, which implies
232 \fB\-\-discover\fR, see above), and the file system block device is detected to be removable,
233 \fB\-\-timeout\-idle\-sec=1s\fR
234 is implied\&.
235 .sp
236 Added in version 232\&.
237 .RE
238 .PP
239 \fB\-\-automount\-property=\fR
240 .RS 4
241 Similar to
242 \fB\-\-property=\fR, but applies additional properties to the automount unit created, instead of the mount unit\&.
243 .sp
244 Added in version 232\&.
245 .RE
246 .PP
247 \fB\-\-bind\-device\fR
248 .RS 4
249 Controls whether the generated mount/automount unit shall be bound to the backing device\*(Aqs lifetime\&. This setting is especially useful in automount mode\&. If set, the units will be stopped automatically when the backing device vanishes\&. By default, the automount unit stays around, and subsequent accesses will block until backing device is replugged\&. This option has no effect in case of non\-device mounts, such as network or virtual file system mounts\&.
250 .sp
251 If
252 \fB\-\-discover\fR
253 is used (or only a single argument passed, which implies
254 \fB\-\-discover\fR, see above), and the file system block device is detected to be removable, this option is implied\&.
255 .sp
256 Note that mount units by default gain a
257 \fIRequires=\fR
258 dependency on the backing device\&. This behavior can be controlled via
259 \fBx\-systemd\&.device\-bound=\fR
260 mount option, see
261 \fBsystemd.mount\fR(5)
262 for details\&. In particular,
263 \fBx\-systemd\&.device\-bound=no\fR
264 takes precedence over this option, which suppresses device dependencies both in the generated mount units and what\*(Aqs implied by service manager\&.
265 .sp
266 Added in version 232\&.
267 .RE
268 .PP
269 \fB\-\-list\fR
270 .RS 4
271 Instead of establishing a mount or automount point, print a terse list of block devices containing file systems that may be mounted with
272 "systemd\-mount", along with useful metadata such as labels, etc\&.
273 .sp
274 Added in version 232\&.
275 .RE
276 .PP
277 \fB\-u\fR, \fB\-\-umount\fR
278 .RS 4
279 Stop the mount and automount units corresponding to the specified mount points
280 \fIWHERE\fR
281 or the devices
282 \fIWHAT\fR\&.
283 \fBsystemd\-mount\fR
284 with this option or
285 \fBsystemd\-umount\fR
286 can take multiple arguments which can be mount points, devices,
287 /etc/fstab
288 style node names, or backing files corresponding to loop devices, like
289 \fBsystemd\-mount \-\-umount /path/to/umount /dev/sda1 UUID=xxxxxx\-xxxx LABEL=xxxxx /path/to/disk\&.img\fR\&. Note that when
290 \fB\-H\fR
291 or
292 \fB\-M\fR
293 is specified, only absolute paths to mount points are supported\&.
294 .sp
295 Added in version 233\&.
296 .RE
297 .PP
298 \fB\-G\fR, \fB\-\-collect\fR
299 .RS 4
300 Unload the transient unit after it completed, even if it failed\&. Normally, without this option, all mount units that mount and failed are kept in memory until the user explicitly resets their failure state with
301 \fBsystemctl reset\-failed\fR
302 or an equivalent command\&. On the other hand, units that stopped successfully are unloaded immediately\&. If this option is turned on the "garbage collection" of units is more aggressive, and unloads units regardless of whether they exited successfully or failed\&. This option is a shortcut for
303 \fB\-\-property=CollectMode=inactive\-or\-failed\fR, see the explanation for
304 \fICollectMode=\fR
305 in
306 \fBsystemd.unit\fR(5)
307 for further information\&.
308 .sp
309 Added in version 236\&.
310 .RE
311 .PP
312 \fB\-T\fR, \fB\-\-tmpfs\fR
313 .RS 4
314 Create and mount a new
315 \fBtmpfs\fR
316 file system on
317 \fIWHERE\fR, with an optional
318 \fINAME\fR
319 that defaults to
320 "tmpfs"\&.
321 .sp
322 The file system is mounted with the top\-level directory mode determined by the
323 \fBumask\fR(2)
324 setting of the caller, i\&.e\&.
325 \fBrwxrwxrwx\fR
326 masked by the umask of the caller\&. This matches what
327 \fBmkdir\fR(1)
328 does, but is different from the kernel default of
329 "rwxrwxrwxt", i\&.e\&. a world\-writable directory with the sticky bit set\&.
330 .sp
331 Added in version 255\&.
332 .RE
333 .PP
334 \fB\-\-canonicalize=\fR
335 .RS 4
336 Controls whether the specified path shall be canonicalized on the client side before requesting the operation or not\&. Takes a boolean parameter, defaults to true\&. Note that for non\-local operation (i\&.e\&. when
337 \fB\-\-machine=\fR
338 or \-\-\fB\-\-host=\fR
339 are used) canonicalization is implicitly turned off\&.
340 .sp
341 Canonicalization of path entails resolving of symlinks,
342 "\&.\&."
343 path elements and
344 \fILABEL=\fR/\fIUUID=\fR
345 style device node expansion\&. If canonicalization is disabled and the path contains a symlink element,
346 "\&.\&.", or a
347 \fILABEL=\fR/\fIUUID=\fR/\&... expansion the operation will fail\&.
348 .sp
349 Added in version 258\&.
350 .RE
351 .PP
352 \fB\-\-user\fR
353 .RS 4
354 Talk to the service manager of the calling user, rather than the service manager of the system\&.
355 .RE
356 .PP
357 \fB\-\-system\fR
358 .RS 4
359 Talk to the service manager of the system\&. This is the implied default\&.
360 .RE
361 .PP
362 \fB\-H\fR, \fB\-\-host=\fR
363 .RS 4
364 Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
365 "@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
366 ":", and then a container name, separated by
367 "/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
368 \fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
369 .RE
370 .PP
371 \fB\-M\fR, \fB\-\-machine=\fR
372 .RS 4
373 Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
374 "@"
375 character\&. If the special string
376 "\&.host"
377 is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
378 "\-\-user \-\-machine=lennart@\&.host")\&. If the
379 "@"
380 syntax is not used, the connection is made as root user\&. If the
381 "@"
382 syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
383 "\&.host"
384 are implied\&.
385 .RE
386 .PP
387 \fB\-h\fR, \fB\-\-help\fR
388 .RS 4
389 Print a short help text and exit\&.
390 .RE
391 .PP
392 \fB\-\-version\fR
393 .RS 4
394 Print a short version string and exit\&.
395 .RE
396 .SH "EXIT STATUS"
397 .PP
398 On success, 0 is returned, a non\-zero failure code otherwise\&.
399 .SH "THE UDEV DATABASE"
400 .PP
401 If
402 \fB\-\-discover\fR
403 is used,
404 \fBsystemd\-mount\fR
405 honors a couple of additional udev properties of block devices:
406 .PP
407 \fISYSTEMD_MOUNT_OPTIONS=\fR
408 .RS 4
409 The mount options to use, if
410 \fB\-\-options=\fR
411 is not used\&.
412 .sp
413 Added in version 232\&.
414 .RE
415 .PP
416 \fISYSTEMD_MOUNT_WHERE=\fR
417 .RS 4
418 The file system path to place the mount point at, instead of the automatically generated one\&.
419 .sp
420 Added in version 232\&.
421 .RE
422 .SH "EXAMPLE"
423 .PP
424 Use a udev rule like the following to automatically mount all USB storage plugged in:
425 .sp
426 .if n \{\
427 .RS 4
428 .\}
429 .nf
430 ACTION=="add", SUBSYSTEMS=="usb", SUBSYSTEM=="block", ENV{ID_FS_USAGE}=="filesystem", \e
431 RUN{program}+="/usr/bin/systemd\-mount \-\-no\-block \-\-automount=yes \-\-collect $devnode"
432 .fi
433 .if n \{\
434 .RE
435 .\}
436 .SH "SEE ALSO"
437 .PP
438 \fBsystemd\fR(1), \fBmount\fR(8), \fBsystemctl\fR(1), \fBsystemd.unit\fR(5), \fBsystemd.mount\fR(5), \fBsystemd.automount\fR(5), \fBsystemd-run\fR(1)