man/systemd-fstab-generator.xml - systemd - Git at Google

 <?xml version="1.0"?>
 <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
 <refentry id="systemd-fstab-generator">

   <refentryinfo>
     <title>systemd-fstab-generator</title>
     <productname>systemd</productname>
   </refentryinfo>

   <refmeta>
     <refentrytitle>systemd-fstab-generator</refentrytitle>
     <manvolnum>8</manvolnum>
   </refmeta>

   <refnamediv>
     <refname>systemd-fstab-generator</refname>
     <refpurpose>Unit generator for /etc/fstab</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
     <para><filename>/usr/lib/systemd/system-generators/systemd-fstab-generator</filename></para>
   </refsynopsisdiv>

   <refsect1>
     <title>Description</title>

     <para><filename>systemd-fstab-generator</filename> is a generator
     that translates <filename>/etc/fstab</filename> (see
     <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     for details) into native systemd units early at boot and when
     configuration of the system manager is reloaded. This will
     instantiate mount and swap units as necessary.</para>

     <para>The <varname>passno</varname> field is treated like a simple
     boolean, and the ordering information is discarded. However, if
     the root file system is checked, it is checked before all the
     other file systems.</para>

     <para>See
     <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     and
     <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     for more information about special <filename>/etc/fstab</filename>
     mount options this generator understands.</para>

     <para>One special topic is handling of symbolic links.  Historical init
     implementations supported symlinks in <filename>/etc/fstab</filename>.
     Because mount units will refuse mounts where the target is a symbolic link,
     this generator will resolve any symlinks as far as possible when processing
     <filename>/etc/fstab</filename> in order to enhance backwards compatibility.
     If a symlink target does not exist at the time that this generator runs, it
     is assumed that the symlink target is the final target of the mount.</para>

     <para><filename>systemd-fstab-generator</filename> implements
     <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
   </refsect1>

   <refsect1>
     <title>Kernel Command Line</title>

     <para><filename>systemd-fstab-generator</filename> understands the
     following kernel command line parameters:</para>

     <variablelist class='kernel-commandline-options'>

       <varlistentry>
         <term><varname>fstab=</varname></term>
         <term><varname>rd.fstab=</varname></term>

         <listitem><para>Takes a boolean argument. Defaults to
         <literal>yes</literal>. If <literal>no</literal>, causes the
         generator to ignore any mounts or swap devices configured in
         <filename>/etc/fstab</filename>. <varname>rd.fstab=</varname>
         is honored only by the initial RAM disk (initrd) while
         <varname>fstab=</varname> is honored by both the main system
         and the initrd.</para></listitem>
       </varlistentry>

       <varlistentry>
         <term><varname>root=</varname></term>

         <listitem><para>Configures the operating system's root filesystem to mount when running in the
         initrd. This accepts a device node path (usually <filename>/dev/disk/by-uuid/…</filename> or
         <filename>/dev/disk/by-label/…</filename> or similar), or the special values <literal>gpt-auto</literal>
         and <literal>tmpfs</literal>.</para>

         <para>Use <literal>gpt-auto</literal> to explicitly request automatic root file system discovery via
         <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>

         <para>Use <literal>tmpfs</literal> in order to mount a <citerefentry
         project='man-pages'><refentrytitle>tmpfs</refentrytitle><manvolnum>5</manvolnum></citerefentry> file
         system as root file system of the OS. This is useful in combination with
         <varname>mount.usr=</varname> (see below) in order to combine a volatile root file system with a
         separate, immutable <filename>/usr/</filename> file system. Also see
         <varname>systemd.volatile=</varname> below.</para></listitem>
       </varlistentry>

       <varlistentry>
         <term><varname>rootfstype=</varname></term>

         <listitem><para>Takes the root filesystem type that will be
         passed to the mount command. <varname>rootfstype=</varname> is
         honored by the initrd.</para></listitem>
       </varlistentry>

       <varlistentry>
         <term><varname>rootflags=</varname></term>

         <listitem><para>Takes the root filesystem mount options to use. <varname>rootflags=</varname> is
         honored by the initrd.</para>

         <para>Note that unlike most kernel command line options this setting does not override settings made
         in configuration files (specifically: the mount option string in
         <filename>/etc/fstab</filename>). See
         <citerefentry><refentrytitle>systemd-remount-fs.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
       </varlistentry>

       <varlistentry>
         <term><varname>mount.usr=</varname></term>

         <listitem><para>Takes the <filename>/usr/</filename> filesystem
         to be mounted by the initrd. If
         <varname>mount.usrfstype=</varname> or
         <varname>mount.usrflags=</varname> is set, then
         <varname>mount.usr=</varname> will default to the value set in
         <varname>root=</varname>.</para>

         <para>Otherwise, this parameter defaults to the
         <filename>/usr/</filename> entry found in
         <filename>/etc/fstab</filename> on the root filesystem.</para>

         <para><varname>mount.usr=</varname> is honored by the initrd.
         </para></listitem>
       </varlistentry>

       <varlistentry>
         <term><varname>mount.usrfstype=</varname></term>

         <listitem><para>Takes the <filename>/usr/</filename> filesystem
         type that will be passed to the mount command. If
         <varname>mount.usr=</varname> or
         <varname>mount.usrflags=</varname> is set, then
         <varname>mount.usrfstype=</varname> will default to the value
         set in <varname>rootfstype=</varname>.</para>

         <para>Otherwise, this value will be read from the
         <filename>/usr/</filename> entry in
         <filename>/etc/fstab</filename> on the root filesystem.</para>

         <para><varname>mount.usrfstype=</varname> is honored by the
         initrd.</para></listitem>
       </varlistentry>

       <varlistentry>
         <term><varname>mount.usrflags=</varname></term>

         <listitem><para>Takes the <filename>/usr/</filename> filesystem
         mount options to use. If <varname>mount.usr=</varname> or
         <varname>mount.usrfstype=</varname> is set, then
         <varname>mount.usrflags=</varname> will default to the value
         set in <varname>rootflags=</varname>.</para>

         <para>Otherwise, this value will be read from the
         <filename>/usr/</filename> entry in
         <filename>/etc/fstab</filename> on the root filesystem.</para>

         <para><varname>mount.usrflags=</varname> is honored by the
         initrd.</para></listitem>
       </varlistentry>

       <varlistentry>
         <term><varname>systemd.volatile=</varname></term>

         <listitem><para>Controls whether the system shall boot up in volatile mode. Takes a boolean argument or the
         special value <option>state</option>.</para>

         <para>If false (the default), this generator makes no changes to the mount tree and the system is booted up in
         normal mode.</para>

         <para>If true the generator ensures
         <citerefentry><refentrytitle>systemd-volatile-root.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
         is run as part of the initial RAM disk ("initrd"). This service changes the mount table before transitioning to
         the host system, so that a volatile memory file system (<literal>tmpfs</literal>) is used as root directory,
         with only <filename>/usr/</filename> mounted into it from the configured root file system, in read-only
         mode. This way the system operates in fully stateless mode, with all configuration and state reset at boot and
         lost at shutdown, as <filename>/etc/</filename> and <filename>/var/</filename> will be served from the (initially
         unpopulated) volatile memory file system.</para>

         <para>If set to <option>state</option> the generator will leave the root directory mount point unaltered,
         however will mount a <literal>tmpfs</literal> file system to <filename>/var/</filename>. In this mode the normal
         system configuration (i.e. the contents of <literal>/etc/</literal>) is in effect (and may be modified during
         system runtime), however the system state (i.e. the contents of <literal>/var/</literal>) is reset at boot and
         lost at shutdown.</para>

         <para>If this setting is set to <literal>overlay</literal> the root file system is set up as
         <literal>overlayfs</literal> mount combining the read-only root directory with a writable
         <literal>tmpfs</literal>, so that no modifications are made to disk, but the file system may be modified
         nonetheless with all changes being lost at reboot.</para>

         <para>Note that in none of these modes the root directory, <filename>/etc/</filename>, <filename>/var/</filename>
         or any other resources stored in the root file system are physically removed. It's thus safe to boot a system
         that is normally operated in non-volatile mode temporarily into volatile mode, without losing data.</para>

         <para>Note that with the exception of <literal>overlay</literal> mode, enabling this setting will
         only work correctly on operating systems that can boot up with only <filename>/usr/</filename>
         mounted, and are able to automatically populate <filename>/etc/</filename>, and also
         <filename>/var/</filename> in case of <literal>systemd.volatile=yes</literal>.</para>

         <para>Also see <varname>root=tmpfs</varname> above, for a method to combine a
         <literal>tmpfs</literal> file system with a regular <filename>/usr/</filename> file system (as
         configured via <varname>mount.usr=</varname>). The main distinction between
         <varname>systemd.volatile=yes</varname>, and <varname>root=tmpfs</varname> in combination
         <varname>mount.usr=</varname> is that the former operates on top of a regular root file system and
         temporarily obstructs the files and directories above its <filename>/usr/</filename> subdirectory,
         while the latter does not hide any files, but simply mounts a unpopulated tmpfs as root file system
         and combines it with a user picked <filename>/usr/</filename> file system.</para></listitem>
       </varlistentry>

       <varlistentry>
         <term><varname>systemd.swap</varname></term>

         <listitem><para>Takes a boolean argument or enables the option if specified
         without an argument. If disabled, causes the generator to ignore
         any swap devices configured in <filename>/etc/fstab</filename>.
         Defaults to enabled.</para></listitem>
       </varlistentry>
     </variablelist>
   </refsect1>

   <refsect1>
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>
     </para>
   </refsect1>

 </refentry>
	<?xml version="1.0"?>
	<!---nxml--->
	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
	<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
	<refentry id="systemd-fstab-generator">

	<refentryinfo>
	<title>systemd-fstab-generator</title>
	<productname>systemd</productname>
	</refentryinfo>

	<refmeta>
	<refentrytitle>systemd-fstab-generator</refentrytitle>
	<manvolnum>8</manvolnum>
	</refmeta>

	<refnamediv>
	<refname>systemd-fstab-generator</refname>
	<refpurpose>Unit generator for /etc/fstab</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
	<para><filename>/usr/lib/systemd/system-generators/systemd-fstab-generator</filename></para>
	</refsynopsisdiv>

	<refsect1>
	<title>Description</title>

	<para><filename>systemd-fstab-generator</filename> is a generator
	that translates <filename>/etc/fstab</filename> (see
	<citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	for details) into native systemd units early at boot and when
	configuration of the system manager is reloaded. This will
	instantiate mount and swap units as necessary.</para>

	<para>The <varname>passno</varname> field is treated like a simple
	boolean, and the ordering information is discarded. However, if
	the root file system is checked, it is checked before all the
	other file systems.</para>

	<para>See
	<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	and
	<citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	for more information about special <filename>/etc/fstab</filename>
	mount options this generator understands.</para>

	<para>One special topic is handling of symbolic links. Historical init
	implementations supported symlinks in <filename>/etc/fstab</filename>.
	Because mount units will refuse mounts where the target is a symbolic link,
	this generator will resolve any symlinks as far as possible when processing
	<filename>/etc/fstab</filename> in order to enhance backwards compatibility.
	If a symlink target does not exist at the time that this generator runs, it
	is assumed that the symlink target is the final target of the mount.</para>

	<para><filename>systemd-fstab-generator</filename> implements
	<citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
	</refsect1>

	<refsect1>
	<title>Kernel Command Line</title>

	<para><filename>systemd-fstab-generator</filename> understands the
	following kernel command line parameters:</para>

	<variablelist class='kernel-commandline-options'>

	<varlistentry>
	<term><varname>fstab=</varname></term>
	<term><varname>rd.fstab=</varname></term>

	<listitem><para>Takes a boolean argument. Defaults to
	<literal>yes</literal>. If <literal>no</literal>, causes the
	generator to ignore any mounts or swap devices configured in
	<filename>/etc/fstab</filename>. <varname>rd.fstab=</varname>
	is honored only by the initial RAM disk (initrd) while
	<varname>fstab=</varname> is honored by both the main system
	and the initrd.</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><varname>root=</varname></term>

	<listitem><para>Configures the operating system's root filesystem to mount when running in the
	initrd. This accepts a device node path (usually <filename>/dev/disk/by-uuid/…</filename> or
	<filename>/dev/disk/by-label/…</filename> or similar), or the special values <literal>gpt-auto</literal>
	and <literal>tmpfs</literal>.</para>

	<para>Use <literal>gpt-auto</literal> to explicitly request automatic root file system discovery via
	<citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>

	<para>Use <literal>tmpfs</literal> in order to mount a <citerefentry
	project='man-pages'><refentrytitle>tmpfs</refentrytitle><manvolnum>5</manvolnum></citerefentry> file
	system as root file system of the OS. This is useful in combination with
	<varname>mount.usr=</varname> (see below) in order to combine a volatile root file system with a
	separate, immutable <filename>/usr/</filename> file system. Also see
	<varname>systemd.volatile=</varname> below.</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><varname>rootfstype=</varname></term>

	<listitem><para>Takes the root filesystem type that will be
	passed to the mount command. <varname>rootfstype=</varname> is
	honored by the initrd.</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><varname>rootflags=</varname></term>

	<listitem><para>Takes the root filesystem mount options to use. <varname>rootflags=</varname> is
	honored by the initrd.</para>

	<para>Note that unlike most kernel command line options this setting does not override settings made
	in configuration files (specifically: the mount option string in
	<filename>/etc/fstab</filename>). See
	<citerefentry><refentrytitle>systemd-remount-fs.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><varname>mount.usr=</varname></term>

	<listitem><para>Takes the <filename>/usr/</filename> filesystem
	to be mounted by the initrd. If
	<varname>mount.usrfstype=</varname> or
	<varname>mount.usrflags=</varname> is set, then
	<varname>mount.usr=</varname> will default to the value set in
	<varname>root=</varname>.</para>

	<para>Otherwise, this parameter defaults to the
	<filename>/usr/</filename> entry found in
	<filename>/etc/fstab</filename> on the root filesystem.</para>

	<para><varname>mount.usr=</varname> is honored by the initrd.
	</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><varname>mount.usrfstype=</varname></term>

	<listitem><para>Takes the <filename>/usr/</filename> filesystem
	type that will be passed to the mount command. If
	<varname>mount.usr=</varname> or
	<varname>mount.usrflags=</varname> is set, then
	<varname>mount.usrfstype=</varname> will default to the value
	set in <varname>rootfstype=</varname>.</para>

	<para>Otherwise, this value will be read from the
	<filename>/usr/</filename> entry in
	<filename>/etc/fstab</filename> on the root filesystem.</para>

	<para><varname>mount.usrfstype=</varname> is honored by the
	initrd.</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><varname>mount.usrflags=</varname></term>

	<listitem><para>Takes the <filename>/usr/</filename> filesystem
	mount options to use. If <varname>mount.usr=</varname> or
	<varname>mount.usrfstype=</varname> is set, then
	<varname>mount.usrflags=</varname> will default to the value
	set in <varname>rootflags=</varname>.</para>

	<para>Otherwise, this value will be read from the
	<filename>/usr/</filename> entry in
	<filename>/etc/fstab</filename> on the root filesystem.</para>

	<para><varname>mount.usrflags=</varname> is honored by the
	initrd.</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><varname>systemd.volatile=</varname></term>

	<listitem><para>Controls whether the system shall boot up in volatile mode. Takes a boolean argument or the
	special value <option>state</option>.</para>

	<para>If false (the default), this generator makes no changes to the mount tree and the system is booted up in
	normal mode.</para>

	<para>If true the generator ensures
	<citerefentry><refentrytitle>systemd-volatile-root.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
	is run as part of the initial RAM disk ("initrd"). This service changes the mount table before transitioning to
	the host system, so that a volatile memory file system (<literal>tmpfs</literal>) is used as root directory,
	with only <filename>/usr/</filename> mounted into it from the configured root file system, in read-only
	mode. This way the system operates in fully stateless mode, with all configuration and state reset at boot and
	lost at shutdown, as <filename>/etc/</filename> and <filename>/var/</filename> will be served from the (initially
	unpopulated) volatile memory file system.</para>

	<para>If set to <option>state</option> the generator will leave the root directory mount point unaltered,
	however will mount a <literal>tmpfs</literal> file system to <filename>/var/</filename>. In this mode the normal
	system configuration (i.e. the contents of <literal>/etc/</literal>) is in effect (and may be modified during
	system runtime), however the system state (i.e. the contents of <literal>/var/</literal>) is reset at boot and
	lost at shutdown.</para>

	<para>If this setting is set to <literal>overlay</literal> the root file system is set up as
	<literal>overlayfs</literal> mount combining the read-only root directory with a writable
	<literal>tmpfs</literal>, so that no modifications are made to disk, but the file system may be modified
	nonetheless with all changes being lost at reboot.</para>

	<para>Note that in none of these modes the root directory, <filename>/etc/</filename>, <filename>/var/</filename>
	or any other resources stored in the root file system are physically removed. It's thus safe to boot a system
	that is normally operated in non-volatile mode temporarily into volatile mode, without losing data.</para>

	<para>Note that with the exception of <literal>overlay</literal> mode, enabling this setting will
	only work correctly on operating systems that can boot up with only <filename>/usr/</filename>
	mounted, and are able to automatically populate <filename>/etc/</filename>, and also
	<filename>/var/</filename> in case of <literal>systemd.volatile=yes</literal>.</para>

	<para>Also see <varname>root=tmpfs</varname> above, for a method to combine a
	<literal>tmpfs</literal> file system with a regular <filename>/usr/</filename> file system (as
	configured via <varname>mount.usr=</varname>). The main distinction between
	<varname>systemd.volatile=yes</varname>, and <varname>root=tmpfs</varname> in combination
	<varname>mount.usr=</varname> is that the former operates on top of a regular root file system and
	temporarily obstructs the files and directories above its <filename>/usr/</filename> subdirectory,
	while the latter does not hide any files, but simply mounts a unpopulated tmpfs as root file system
	and combines it with a user picked <filename>/usr/</filename> file system.</para></listitem>
	</varlistentry>

	<varlistentry>
	<term><varname>systemd.swap</varname></term>

	<listitem><para>Takes a boolean argument or enables the option if specified
	without an argument. If disabled, causes the generator to ignore
	any swap devices configured in <filename>/etc/fstab</filename>.
	Defaults to enabled.</para></listitem>
	</varlistentry>
	</variablelist>
	</refsect1>

	<refsect1>
	<title>See Also</title>
	<para>
	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	<citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
	<citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>
	</para>
	</refsect1>

	</refentry>