fstab-generator: add new root=tmpfs option

It's useful to be able to combine a regular /usr/ file system with a
tmpfs as root, for an OS that boots up in volatile mode on every single
boot.  Let's add explicit support for this via root=tmpfs.

Note the relationship to the existing systemd.volatile= option:

1. The kernel command line "root=/dev/… systemd.volatile=yes" will mount
   the specified root fs, and then hide everything at the top by
   overmounting it with a tmpfs, except for the /usr subtree.

2. The kernel command line "root=tmpfs mount.usr=/dev/…" otoh will mount
   a toot fs at the top (just like the case above), but will then mount
   the top-level dir of the fs specified in mount.usr= directly below
   it.

Or to say this differently: in the first case /usr/ from the physical
storage fs is going to become /usr/ of the hierarchy ultimately booted,
while in the second case / from the physical storage fs is going to
become /usr of the hierarchy booted.

Philosophically I figure systemd.volatile= is more an option for
"one-off" boots, while root=tmpfs is something to have as default mode
of operation for suitable images.

This is currently hard to test reasonably, since Dracut refuses to
accept root=tmpfs. This needs to be addressed separately though.

1 files changed, 28 insertions, 7 deletions

diff --git a/man/systemd-fstab-generator.xml b/man/systemd-fstab-generator.xml
index ec8f5c988e..3c5a5cc50a 100644
--- a/man/systemd-fstab-generator.xml
+++ b/man/systemd-fstab-generator.xml
@@ -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>
@@ -193,10 +204,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 +238,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>