fstab-generator: add support for volatile boots

This adds support for a new kernel command line option "systemd.volatile=" that
provides the same functionality that systemd-nspawn's --volatile= switch
provides, but for host systems (i.e. systems booting with a kernel).

It takes the same parameter and has the same effect.

In order to implement systemd.volatile=yes a new service
systemd-volatile-root.service is introduced that only runs in the initrd and
rearranges the root directory as needed to become a tmpfs instance. Note that
systemd.volatile=state is implemented different: it simply generates a
var.mount unit file that is part of the normal boot and has no effect on the
initrd execution.

The way this is implemented ensures that other explicit configuration for /var
can always override the effect of these options.  Specifically, the var.mount
unit is generated in the "late" generator directory, so that it only is in
effect if nothing else overrides it.

4 files changed, 154 insertions, 9 deletions

diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml
index 78e45e66a9..7e1d408ded 100644
--- a/man/kernel-command-line.xml
+++ b/man/kernel-command-line.xml
@@ -125,6 +125,28 @@
       </varlistentry>
 
       <varlistentry>
+        <term><varname>systemd.volatile=</varname></term>
+        <listitem>
+          <para>This parameter controls whether the system shall boot up in volatile mode. Takes a boolean argument, or
+          the special value <literal>state</literal>. If false (the default), normal boot mode is selected, the root
+          directory and <filename>/var</filename> are mounted as specified on the kernel command line or
+          <filename>/etc/fstab</filename>, or otherwise configured. If true, full state-less boot mode is selected. In
+          this case the root directory is mounted as volatile memory file system (<literal>tmpfs</literal>), and only
+          <filename>/usr</filename> is mounted from the file system configured as root device, in read-only mode. This
+          enables fully state-less boots were the vendor-supplied OS is used as shipped, with only default
+          configuration and no stored state in effect, as <filename>/etc</filename> and <filename>/var</filename> (as
+          well as all other resources shipped in the root file system) are reset at boot and lost on shutdown. If this
+          setting is set to <literal>state</literal> the root file system is mounted as usual, however
+          <filename>/var</filename> is mounted as a volatile memory file system (<literal>tmpfs</literal>), so that the
+          system boots up with the normal configuration applied, but all state reset at boot and lost at shutdown. For details,
+          see
+          <citerefentry><refentrytitle>systemd-volatile-root.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+          and
+          <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><varname>quiet</varname></term>
         <listitem>
           <para>Parameter understood by both the kernel and the system
@@ -382,6 +404,7 @@
         <citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
         <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
         <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+        <citerefentry><refentrytitle>systemd-volatile-root.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
         <citerefentry><refentrytitle>systemd-modules-load.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
         <citerefentry><refentrytitle>systemd-backlight@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
         <citerefentry><refentrytitle>systemd-rfkill.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
diff --git a/man/systemd-fstab-generator.xml b/man/systemd-fstab-generator.xml
index a971cb3675..5f37e9193e 100644
--- a/man/systemd-fstab-generator.xml
+++ b/man/systemd-fstab-generator.xml
@@ -89,12 +89,13 @@
 
         <listitem><para>Takes a boolean argument. Defaults to
         <literal>yes</literal>. If <literal>no</literal>, causes the
-        generator to ignore any mounts or swaps configured in
+        generator to ignore any mounts or swap devices configured in
         <filename>/etc/fstab</filename>. <varname>rd.fstab=</varname>
-        is honored only by initial RAM disk (initrd) while
+        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>
 
@@ -102,6 +103,7 @@
         initrd. <varname>root=</varname> is honored by the
         initrd.</para></listitem>
       </varlistentry>
+
       <varlistentry>
         <term><varname>rootfstype=</varname></term>
 
@@ -109,6 +111,7 @@
         passed to the mount command. <varname>rootfstype=</varname> is
         honored by the initrd.</para></listitem>
       </varlistentry>
+
       <varlistentry>
         <term><varname>rootflags=</varname></term>
 
@@ -116,6 +119,7 @@
         use. <varname>rootflags=</varname> is honored by the
         initrd.</para></listitem>
       </varlistentry>
+
       <varlistentry>
         <term><varname>mount.usr=</varname></term>
 
@@ -133,6 +137,7 @@
         <para><varname>mount.usr=</varname> is honored by the initrd.
         </para></listitem>
       </varlistentry>
+
       <varlistentry>
         <term><varname>mount.usrfstype=</varname></term>
 
@@ -150,6 +155,7 @@
         <para><varname>mount.usrfstype=</varname> is honored by the
         initrd.</para></listitem>
       </varlistentry>
+
       <varlistentry>
         <term><varname>mount.usrflags=</varname></term>
 
@@ -166,6 +172,39 @@
         <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>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 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>
+      </varlistentry>
     </variablelist>
   </refsect1>
 
@@ -176,7 +215,8 @@
       <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-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>
     </para>
   </refsect1>
 
diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml
index 2bc81ea1aa..f6b3f57fc7 100644
--- a/man/systemd-nspawn.xml
+++ b/man/systemd-nspawn.xml
@@ -939,12 +939,15 @@
         <option>no</option> (the default), the whole OS tree is made
         available writable.</para>
 
-        <para>Note that setting this to <option>yes</option> or
-        <option>state</option> will only work correctly with
-        operating systems in the container that can boot up with only
-        <filename>/usr</filename> mounted, and are able to populate
-        <filename>/var</filename> automatically, as
-        needed.</para></listitem>
+        <para>This option provides similar functionality for containers as the <literal>systemd.volatile=</literal>
+        kernel command line switch provides for host systems. See
+        <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+        details.</para>
+
+        <para>Note that enabling this setting will only work correctly with operating systems in the container that can
+        boot up with only <filename>/usr</filename> mounted, and are able to automatically populate
+        <filename>/var</filename>, and also <filename>/etc</filename> in case of
+        <literal>--volatile=yes</literal>.</para></listitem>
       </varlistentry>
 
       <varlistentry>
diff --git a/man/systemd-volatile-root.service.xml b/man/systemd-volatile-root.service.xml
new file mode 100644
index 0000000000..b90a3261fa
--- /dev/null
+++ b/man/systemd-volatile-root.service.xml
@@ -0,0 +1,79 @@
+<?xml version="1.0"?>
+<!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!--
+  This file is part of systemd.
+
+  Copyright 2016 Lennart Poettering
+
+  systemd is free software; you can redistribute it and/or modify it
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or
+  (at your option) any later version.
+
+  systemd is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public License
+  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+<refentry id="systemd-volatile-root.service">
+
+  <refentryinfo>
+    <title>systemd-volatile-root.service</title>
+    <productname>systemd</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd-volatile-root.service</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd-volatile-root.service</refname>
+    <refname>systemd-volatile-root</refname>
+    <refpurpose>Make the root file system volatile</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename>systemd-volatile-root.service</filename></para>
+    <para><filename>/usr/lib/systemd/systemd-volatile-root</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><filename>systemd-volatile-root.service</filename> is a service that replaces the root directory with a
+    volatile memory file system (<literal>tmpfs</literal>), mounting the original (non-volatile)
+    <filename>/usr</filename> inside it read-only. This way, vendor data from <filename>/usr</filename> is available as
+    usual, but all configuration data in <filename>/etc</filename>, all state data in <filename>/var</filename> and all
+    other resources stored directly under the root directory are reset on boot and lost at shutdown, enabling fully
+    stateless systems.</para>
+
+    <para>This service is only enabled if full volatile mode is selected, for example by specifying
+    <literal>systemd.volatile=yes</literal> on the kernel command line. This service runs only in the initial RAM disk
+    ("initrd"), before the system transitions to the host's root directory. Note that this service is not used if
+    <literal>systemd.volatile=state</literal> is used, as in that mode the root directory is non-volatile.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>