man: document that systemd-fstab-generator actually cares about roothash=/usrhash...

[thirdparty/systemd.git] / man / systemd-fstab-generator.xml

diff --git a/man/systemd-fstab-generator.xml b/man/systemd-fstab-generator.xml
index e842f3f9bc84e1a6b47a953ecbe87c9e3936b341..21fa85da7d847af2d22a6ee2947bd22464c4a6f1 100644 (file)
--- a/man/systemd-fstab-generator.xml
+++ b/man/systemd-fstab-generator.xml
@@ -2,7 +2,7 @@
 <!--*-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+ -->
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
 <refentry id="systemd-fstab-generator">
 
   <refentryinfo>
@@ -82,9 +82,20 @@
       <varlistentry>
         <term><varname>root=</varname></term>
 
-        <listitem><para>Takes the root filesystem to mount in the
-        initrd. <varname>root=</varname> is honored by the
-        initrd.</para></listitem>
+        <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>
@@ -160,6 +171,18 @@
         initrd.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><varname>roothash=</varname></term>
+        <term><varname>usrhash=</varname></term>
+
+        <listitem><para>These options are primarily read by
+        <citerefentry><refentrytitle>systemd-veritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. When
+        set this indicates that the root file system (or <filename>/usr/</filename>) shall be mounted from
+        Verity volumes with the specified hashes. If these kernel command line options are set the root (or
+        <filename>/usr/</filename>) file system is thus mounted from a device mapper volume
+        <filename>/dev/mapper/root</filename> (or <filename>/dev/mapper/usr</filename>).</para></listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><varname>systemd.volatile=</varname></term>
 
@@ -193,10 +216,19 @@
         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></listitem>
+        <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>
@@ -218,6 +250,7 @@
       <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>