man/systemd-mount.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   Copyright 2016 Lennart Poettering
   9 -->
  10
  11 <refentry id="systemd-mount"
  12           xmlns:xi="http://www.w3.org/2001/XInclude">
  13
  14   <refentryinfo>
  15     <title>systemd-mount</title>
  16     <productname>systemd</productname>
  17
  18     <authorgroup>
  19       <author>
  20         <contrib>Developer</contrib>
  21         <firstname>Lennart</firstname>
  22         <surname>Poettering</surname>
  23         <email>lennart@poettering.net</email>
  24       </author>
  25     </authorgroup>
  26   </refentryinfo>
  27
  28   <refmeta>
  29     <refentrytitle>systemd-mount</refentrytitle>
  30     <manvolnum>1</manvolnum>
  31   </refmeta>
  32
  33   <refnamediv>
  34     <refname>systemd-mount</refname>
  35     <refname>systemd-umount</refname>
  36     <refpurpose>Establish and destroy transient mount or auto-mount points</refpurpose>
  37   </refnamediv>
  38
  39   <refsynopsisdiv>
  40     <cmdsynopsis>
  41       <command>systemd-mount</command>
  42       <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg>
  43       <arg choice="plain"><replaceable>WHAT</replaceable></arg>
  44       <arg choice="opt"><replaceable>WHERE</replaceable></arg>
  45     </cmdsynopsis>
  46     <cmdsynopsis>
  47       <command>systemd-mount</command>
  48       <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg>
  49       <arg choice="plain"><option>--list</option></arg>
  50     </cmdsynopsis>
  51     <cmdsynopsis>
  52       <command>systemd-mount</command>
  53       <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg>
  54       <arg choice="plain"><option>--umount</option></arg>
  55       <arg choice="plain" rep="repeat"><replaceable>WHAT|WHERE</replaceable></arg>
  56     </cmdsynopsis>
  57   </refsynopsisdiv>
  58
  59   <refsect1>
  60     <title>Description</title>
  61
  62     <para><command>systemd-mount</command> may be used to create and start a transient <filename>.mount</filename> or
  63     <filename>.automount</filename> unit of the file system <replaceable>WHAT</replaceable> on the mount point
  64     <replaceable>WHERE</replaceable>.</para>
  65
  66     <para>In many ways, <command>systemd-mount</command> is similar to the lower-level
  67     <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> command, however instead
  68     of executing the mount operation directly and immediately, <command>systemd-mount</command> schedules it through
  69     the service manager job queue, so that it may pull in further dependencies (such as parent mounts, or a file system
  70     checker to execute a priori), and may make use of the auto-mounting logic.</para>
  71
  72     <para>The command takes either one or two arguments. If only one argument is specified it should refer to a block
  73     device or regular file containing a file system (e.g. <literal>/dev/sdb1</literal> or
  74     <literal>/path/to/disk.img</literal>). If it is a block device, which is then probed for a label and other
  75     metadata, and is mounted to a directory whose name is generated from the label. In this mode the block device must
  76     exist at the time of invocation of the command, so that it may be probed. If the device is found to be a removable
  77     block device (e.g. a USB stick) an automount point instead of a regular mount point is created (i.e. the
  78     <option>--automount=</option> option is implied, see below).</para>
  79
  80     <para>If two arguments are specified the first indicates the mount source (the <replaceable>WHAT</replaceable>) and
  81     the second indicates the path to mount it on (the <replaceable>WHERE</replaceable>). In this mode no probing of the
  82     source is attempted, and a backing device node doesn't have to exist yet. However, if this mode is combined with
  83     <option>--discover</option>, device node probing for additional metadata is enabled, and – much like in the
  84     single-argument case discussed above – the specified device has to exist at the time of invocation of the
  85     command.</para>
  86
  87     <para>Use the <option>--list</option> command to show a terse table of all local, known block devices with file
  88     systems that may be mounted with this command.</para>
  89
  90     <para><command>systemd-umount</command> can be used to unmount a mount or automount point. It is the same
  91     as <command>systemd-mount</command> <option>--umount</option>.</para>
  92   </refsect1>
  93
  94   <refsect1>
  95     <title>Options</title>
  96
  97     <para>The following options are understood:</para>
  98
  99     <variablelist>
 100
 101       <varlistentry>
 102         <term><option>--no-block</option></term>
 103
 104         <listitem>
 105           <para>Do not synchronously wait for the requested operation to finish. If this is not specified, the job will
 106           be verified, enqueued and <command>systemd-mount</command> will wait until the mount or automount unit's
 107           start-up is completed. By passing this argument, it is only verified and enqueued.</para>
 108         </listitem>
 109       </varlistentry>
 110
 111       <xi:include href="standard-options.xml" xpointer="no-pager"/>
 112       <xi:include href="standard-options.xml" xpointer="no-ask-password"/>
 113
 114       <varlistentry>
 115         <term><option>--quiet</option></term>
 116         <term><option>-q</option></term>
 117
 118         <listitem><para>Suppresses additional informational output while running.</para></listitem>
 119       </varlistentry>
 120
 121       <varlistentry>
 122         <term><option>--discover</option></term>
 123
 124         <listitem><para>Enable probing of the mount source. This switch is implied if a single argument is specified on
 125         the command line. If passed, additional metadata is read from the device to enhance the unit to create. For
 126         example, a descriptive string for the transient units is generated from the file system label and device
 127         model. Moreover if a removable block device (e.g. USB stick) is detected an automount unit instead of a regular
 128         mount unit is created, with a short idle time-out, in order to ensure the file-system is placed in a clean
 129         state quickly after each access.</para></listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term><option>--type=</option></term>
 134         <term><option>-t</option></term>
 135
 136         <listitem><para>Specifies the file system type to mount (e.g. <literal>vfat</literal>, <literal>ext4</literal>,
 137         …). If omitted (or set to <literal>auto</literal>) the file system is determined automatically.</para></listitem>
 138       </varlistentry>
 139
 140       <varlistentry>
 141         <term><option>--options=</option></term>
 142         <term><option>-o</option></term>
 143
 144         <listitem><para>Additional mount options for the mount point.</para></listitem>
 145       </varlistentry>
 146
 147       <varlistentry>
 148         <term><option>--owner=<replaceable>USER</replaceable></option></term>
 149
 150         <listitem><para>Let the specified user <replaceable>USER</replaceable> own the mounted file system.
 151         This is done by appending <option>uid=</option> and <option>gid=</option> options to the list
 152         of mount options. Only certain file systems support this option.</para></listitem>
 153       </varlistentry>
 154
 155       <varlistentry>
 156         <term><option>--fsck=</option></term>
 157
 158         <listitem><para>Takes a boolean argument, defaults to on. Controls whether to run a file system check
 159         immediately before the mount operation. In the automount case (see <option>--automount=</option> below) the
 160         check will be run the moment the first access to the device is made, which might slightly delay the
 161         access.</para></listitem>
 162       </varlistentry>
 163
 164       <varlistentry>
 165         <term><option>--description=</option></term>
 166
 167         <listitem><para>Provide a description for the mount or automount unit. See <varname>Description=</varname> in
 168         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 169         </para></listitem>
 170       </varlistentry>
 171
 172       <varlistentry>
 173         <term><option>--property=</option></term>
 174         <term><option>-p</option></term>
 175
 176         <listitem><para>Sets a unit property for the mount unit that is created. This takes an assignment in the same
 177         format as <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 178         <command>set-property</command> command.</para>
 179         </listitem>
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term><option>--automount=</option></term>
 184
 185         <listitem><para>Takes a boolean argument. Controls whether to create an automount point or a regular mount
 186         point. If true an automount point is created that is backed by the actual file system at the time of first
 187         access. If false a plain mount point is created that is backed by the actual file system immediately. Automount
 188         points have the benefit that the file system stays unmounted and hence in clean state until it is first
 189         accessed. In automount mode the <option>--timeout-idle-sec=</option> switch (see below) may be used to ensure
 190         the mount point is unmounted automatically after the last access and an idle period passed.</para>
 191
 192         <para>If this switch is not specified it defaults to false. If not specified and <option>--discover</option> is
 193         used (or only a single argument passed, which implies <option>--discover</option>, see above), and the file
 194         system block device is detected to be removable, it is set to true, in order to increase the chance that the
 195         file system is in a fully clean state if the device is unplugged abruptly.</para></listitem>
 196       </varlistentry>
 197
 198       <varlistentry>
 199         <term><option>-A</option></term>
 200
 201         <listitem><para>Equivalent to <option>--automount=yes</option>.</para></listitem>
 202       </varlistentry>
 203
 204       <varlistentry>
 205         <term><option>--timeout-idle-sec=</option></term>
 206
 207         <listitem><para>Takes a time value that controls the idle timeout in automount mode. If set to
 208         <literal>infinity</literal> (the default) no automatic unmounts are done. Otherwise the file system backing the
 209         automount point is detached after the last access and the idle timeout passed. See
 210         <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on
 211         the time syntax supported. This option has no effect if only a regular mount is established, and automounting
 212         is not used.</para>
 213
 214         <para>Note that if <option>--discover</option> is used (or only a single argument passed, which implies
 215         <option>--discover</option>, see above), and the file system block device is detected to be removable,
 216         <option>--timeout-idle-sec=1s</option> is implied.</para></listitem>
 217       </varlistentry>
 218
 219       <varlistentry>
 220         <term><option>--automount-property=</option></term>
 221
 222         <listitem><para>Similar to <option>--property=</option>, but applies additional properties to the automount
 223         unit created, instead of the mount unit.</para></listitem>
 224       </varlistentry>
 225
 226       <varlistentry>
 227         <term><option>--bind-device=</option></term>
 228
 229         <listitem><para>Takes a boolean argument, defaults to off. This option only has an effect in automount mode,
 230         and controls whether the automount unit shall be bound to the backing device's lifetime. If enabled, the
 231         automount point will be removed automatically when the backing device vanishes. If disabled the automount point
 232         stays around, and subsequent accesses will block until backing device is replugged. This option has no effect
 233         in case of non-device mounts, such as network or virtual file system mounts.</para>
 234
 235         <para>Note that if <option>--discover</option> is used (or only a single argument passed, which implies
 236         <option>--discover</option>, see above), and the file system block device is detected to be removable, this
 237         option is implied.</para></listitem>
 238       </varlistentry>
 239
 240       <varlistentry>
 241         <term><option>--list</option></term>
 242
 243         <listitem><para>Instead of establishing a mount or automount point, print a terse list of block devices
 244         containing file systems that may be mounted with <literal>systemd-mount</literal>, along with useful metadata
 245         such as labels, etc.</para></listitem>
 246       </varlistentry>
 247
 248       <varlistentry>
 249         <term><option>-u</option></term>
 250         <term><option>--umount</option></term>
 251
 252         <listitem><para>Stop the mount and automount units corresponding to the specified mount points
 253         <replaceable>WHERE</replaceable> or the devices <replaceable>WHAT</replaceable>.
 254         <command>systemd-mount</command> with this option or <command>systemd-umount</command> can take multiple arguments
 255         which can be mount points, devices, <filename>/etc/fstab</filename> style node names, or backing files
 256         corresponding to loop devices, like
 257         <command>systemd-mount --umount /path/to/umount /dev/sda1 UUID=xxxxxx-xxxx LABEL=xxxxx /path/to/disk.img</command>.
 258         Note that when <option>-H</option> or <option>-M</option> is specified, only absolute paths to mount points are
 259         supported.</para></listitem>
 260       </varlistentry>
 261
 262       <varlistentry>
 263         <term><option>-G</option></term>
 264         <term><option>--collect</option></term>
 265
 266         <listitem><para>Unload the transient unit after it completed, even if it failed. Normally, without this option,
 267         all mount units that mount and failed are kept in memory until the user explicitly resets their failure state with
 268         <command>systemctl reset-failed</command> or an equivalent command. On the other hand, units that stopped
 269         successfully are unloaded immediately. If this option is turned on the "garbage collection" of units is more
 270         aggressive, and unloads units regardless if they exited successfully or failed. This option is a shortcut for
 271         <command>--property=CollectMode=inactive-or-failed</command>, see the explanation for
 272         <varname>CollectMode=</varname> in
 273         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for further
 274         information.</para></listitem>
 275       </varlistentry>
 276
 277       <xi:include href="user-system-options.xml" xpointer="user" />
 278       <xi:include href="user-system-options.xml" xpointer="system" />
 279       <xi:include href="user-system-options.xml" xpointer="host" />
 280       <xi:include href="user-system-options.xml" xpointer="machine" />
 281
 282       <xi:include href="standard-options.xml" xpointer="help" />
 283       <xi:include href="standard-options.xml" xpointer="version" />
 284     </variablelist>
 285
 286   </refsect1>
 287
 288   <refsect1>
 289     <title>Exit status</title>
 290
 291     <para>On success, 0 is returned, a non-zero failure
 292     code otherwise.</para>
 293   </refsect1>
 294
 295   <refsect1>
 296     <title>The udev Database</title>
 297
 298     <para>If <option>--discover</option> is used, <command>systemd-mount</command> honors a couple of additional udev
 299     properties of block devices:</para>
 300
 301     <variablelist class='udev-directives'>
 302       <varlistentry>
 303         <term><varname>SYSTEMD_MOUNT_OPTIONS=</varname></term>
 304
 305         <listitem><para>The mount options to use, if <option>--options=</option> is not used.</para></listitem>
 306       </varlistentry>
 307
 308       <varlistentry>
 309         <term><varname>SYSTEMD_MOUNT_WHERE=</varname></term>
 310
 311         <listitem><para>The file system path to place the mount point at, instead of the automatically generated
 312         one.</para></listitem>
 313       </varlistentry>
 314     </variablelist>
 315   </refsect1>
 316
 317   <refsect1>
 318     <title>See Also</title>
 319     <para>
 320       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 321       <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 322       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 323       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 324       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 325       <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 326       <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 327     </para>
 328   </refsect1>
 329
 330 </refentry>