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