man/systemd-fstab-generator.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!--
   5   SPDX-License-Identifier: LGPL-2.1+
   6
   7   This file is part of systemd.
   8
   9   Copyright 2012 Lennart Poettering
  10
  11   systemd is free software; you can redistribute it and/or modify it
  12   under the terms of the GNU Lesser General Public License as published by
  13   the Free Software Foundation; either version 2.1 of the License, or
  14   (at your option) any later version.
  15
  16   systemd is distributed in the hope that it will be useful, but
  17   WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19   Lesser General Public License for more details.
  20
  21   You should have received a copy of the GNU Lesser General Public License
  22   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  23 -->
  24 <refentry id="systemd-fstab-generator">
  25
  26   <refentryinfo>
  27     <title>systemd-fstab-generator</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Lennart</firstname>
  34         <surname>Poettering</surname>
  35         <email>lennart@poettering.net</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>systemd-fstab-generator</refentrytitle>
  42     <manvolnum>8</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>systemd-fstab-generator</refname>
  47     <refpurpose>Unit generator for /etc/fstab</refpurpose>
  48   </refnamediv>
  49
  50   <refsynopsisdiv>
  51     <para><filename>/usr/lib/systemd/system-generators/systemd-fstab-generator</filename></para>
  52   </refsynopsisdiv>
  53
  54   <refsect1>
  55     <title>Description</title>
  56
  57     <para><filename>systemd-fstab-generator</filename> is a generator
  58     that translates <filename>/etc/fstab</filename> (see
  59     <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  60     for details) into native systemd units early at boot and when
  61     configuration of the system manager is reloaded. This will
  62     instantiate mount and swap units as necessary.</para>
  63
  64     <para>The <varname>passno</varname> field is treated like a simple
  65     boolean, and the ordering information is discarded. However, if
  66     the root file system is checked, it is checked before all the
  67     other file systems.</para>
  68
  69     <para>See
  70     <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  71     and
  72     <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  73     for more information about special <filename>/etc/fstab</filename>
  74     mount options this generator understands.</para>
  75
  76     <para>One special topic is handling of symbolic links.  Historical init
  77     implementations supported symlinks in <filename>/etc/fstab</filename>.
  78     Because mount units will refuse mounts where the target is a symbolic link,
  79     this generator will resolve any symlinks as far as possible when processing
  80     <filename>/etc/fstab</filename> in order to enhance backwards compatibility.
  81     If a symlink target does not exist at the time that this generator runs, it
  82     is assumed that the symlink target is the final target of the mount.</para>
  83
  84     <para><filename>systemd-fstab-generator</filename> implements
  85     <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
  86   </refsect1>
  87
  88   <refsect1>
  89     <title>Kernel Command Line</title>
  90
  91     <para><filename>systemd-fstab-generator</filename> understands the
  92     following kernel command line parameters:</para>
  93
  94     <variablelist class='kernel-commandline-options'>
  95
  96       <varlistentry>
  97         <term><varname>fstab=</varname></term>
  98         <term><varname>rd.fstab=</varname></term>
  99
 100         <listitem><para>Takes a boolean argument. Defaults to
 101         <literal>yes</literal>. If <literal>no</literal>, causes the
 102         generator to ignore any mounts or swap devices configured in
 103         <filename>/etc/fstab</filename>. <varname>rd.fstab=</varname>
 104         is honored only by the initial RAM disk (initrd) while
 105         <varname>fstab=</varname> is honored by both the main system
 106         and the initrd.</para></listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term><varname>root=</varname></term>
 111
 112         <listitem><para>Takes the root filesystem to mount in the
 113         initrd. <varname>root=</varname> is honored by the
 114         initrd.</para></listitem>
 115       </varlistentry>
 116
 117       <varlistentry>
 118         <term><varname>rootfstype=</varname></term>
 119
 120         <listitem><para>Takes the root filesystem type that will be
 121         passed to the mount command. <varname>rootfstype=</varname> is
 122         honored by the initrd.</para></listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term><varname>rootflags=</varname></term>
 127
 128         <listitem><para>Takes the root filesystem mount options to
 129         use. <varname>rootflags=</varname> is honored by the
 130         initrd.</para></listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term><varname>mount.usr=</varname></term>
 135
 136         <listitem><para>Takes the <filename>/usr</filename> filesystem
 137         to be mounted by the initrd. If
 138         <varname>mount.usrfstype=</varname> or
 139         <varname>mount.usrflags=</varname> is set, then
 140         <varname>mount.usr=</varname> will default to the value set in
 141         <varname>root=</varname>.</para>
 142
 143         <para>Otherwise, this parameter defaults to the
 144         <filename>/usr</filename> entry found in
 145         <filename>/etc/fstab</filename> on the root filesystem.</para>
 146
 147         <para><varname>mount.usr=</varname> is honored by the initrd.
 148         </para></listitem>
 149       </varlistentry>
 150
 151       <varlistentry>
 152         <term><varname>mount.usrfstype=</varname></term>
 153
 154         <listitem><para>Takes the <filename>/usr</filename> filesystem
 155         type that will be passed to the mount command. If
 156         <varname>mount.usr=</varname> or
 157         <varname>mount.usrflags=</varname> is set, then
 158         <varname>mount.usrfstype=</varname> will default to the value
 159         set in <varname>rootfstype=</varname>.</para>
 160
 161         <para>Otherwise, this value will be read from the
 162         <filename>/usr</filename> entry in
 163         <filename>/etc/fstab</filename> on the root filesystem.</para>
 164
 165         <para><varname>mount.usrfstype=</varname> is honored by the
 166         initrd.</para></listitem>
 167       </varlistentry>
 168
 169       <varlistentry>
 170         <term><varname>mount.usrflags=</varname></term>
 171
 172         <listitem><para>Takes the <filename>/usr</filename> filesystem
 173         mount options to use. If <varname>mount.usr=</varname> or
 174         <varname>mount.usrfstype=</varname> is set, then
 175         <varname>mount.usrflags=</varname> will default to the value
 176         set in <varname>rootflags=</varname>.</para>
 177
 178         <para>Otherwise, this value will be read from the
 179         <filename>/usr</filename> entry in
 180         <filename>/etc/fstab</filename> on the root filesystem.</para>
 181
 182         <para><varname>mount.usrflags=</varname> is honored by the
 183         initrd.</para></listitem>
 184       </varlistentry>
 185
 186       <varlistentry>
 187         <term><varname>systemd.volatile=</varname></term>
 188
 189         <listitem><para>Controls whether the system shall boot up in volatile mode. Takes a boolean argument or the
 190         special value <option>state</option>.</para>
 191
 192         <para>If false (the default), this generator makes no changes to the mount tree and the system is booted up in
 193         normal mode.</para>
 194
 195         <para>If true the generator ensures
 196         <citerefentry><refentrytitle>systemd-volatile-root.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 197         is run as part of the initial RAM disk ("initrd"). This service changes the mount table before transitioning to
 198         the host system, so that a volatile memory file system (<literal>tmpfs</literal>) is used as root directory,
 199         with only <filename>/usr</filename> mounted into it from the configured root file system, in read-only
 200         mode. This way the system operates in fully stateless mode, with all configuration and state reset at boot and
 201         lost at shutdown, as <filename>/etc</filename> and <filename>/var</filename> will be served from the (initially
 202         unpopulated) volatile memory file system.</para>
 203
 204         <para>If set to <option>state</option> the generator will leave the root
 205         directory mount point unaltered, however will mount a <literal>tmpfs</literal> file system to
 206         <filename>/var</filename>. In this mode the normal system configuration (i.e. the contents of
 207         <literal>/etc</literal>) is in effect (and may be modified during system runtime), however the system state
 208         (i.e. the contents of <literal>/var</literal>) is reset at boot and lost at shutdown.</para>
 209
 210         <para>Note that in none of these modes the root directory, <filename>/etc</filename>, <filename>/var</filename>
 211         or any other resources stored in the root file system are physically removed. It's thus safe to boot a system
 212         that is normally operated in non-volatile mode temporarily into volatile mode, without losing data.</para>
 213
 214         <para>Note that enabling this setting will only work correctly on operating systems that can boot up with only
 215         <filename>/usr</filename> mounted, and are able to automatically populate <filename>/etc</filename>, and also
 216         <filename>/var</filename> in case of <literal>systemd.volatile=yes</literal>.</para></listitem>
 217       </varlistentry>
 218     </variablelist>
 219   </refsect1>
 220
 221   <refsect1>
 222     <title>See Also</title>
 223     <para>
 224       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 225       <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 226       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 227       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 228       <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 229       <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 230     </para>
 231   </refsect1>
 232
 233 </refentry>