introduce systemd-volatile-usr

man/kernel-command-line.xml

@@ -161,21 +161,26 @@
         <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 values <literal>state</literal> or <literal>overlay</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.
+          the special values <literal>state</literal>, <literal>overlay-root</literal>, or <literal>overlay-usr</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 where 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 read-only, 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. If
-          this setting is set to <literal>overlay</literal> the root file system is set up as
+          this setting is set to <literal>overlay-root</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. For details, see
+          nonetheless with all changes being lost at reboot. If set to <literal>overlay-usr</literal>
+          the <filename>/usr/</filename> directory is set up as <literal>overlayfs</literal> mount combining the original
+          <filename>/usr/</filename> directory with a writable <literal>tmpfs</literal>, so that no modifications are made
+          to the OS image, but the <filename>/usr/</filename> file system may be modified nonetheless with all changes
+          being lost at reboot. 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>

man/systemd-fstab-generator.xml

@@ -234,16 +234,21 @@
         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
+        <para>If this setting is set to <literal>overlay-root</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>If set to <literal>overlay-usr</literal> the <filename>/usr/</filename> directory is set up as
+        <literal>overlayfs</literal> mount combining the read-only <filename>/usr/</filename> directory with a writable
+        <literal>tmpfs</literal>, so that no modifications are made to the OS image, but the <filename>/usr/</filename>
+        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
+        <para>Note that with the exception of <literal>overlay-root</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>

man/systemd-volatile-root.service.xml

@@ -28,19 +28,30 @@
 
   <refsect1>
     <title>Description</title>
+    <para><filename>systemd-volatile-root.service</filename> is a service that works on /sysroot directory.
+    This service runs only in the initrd, before the system transitions to the host's root directory.</para>
+
+    <para> It is influenced by the <literal>systemd.volatile</literal> kernel command line parameter.</para>
+
+    <para> If <literal>systemd.volatile=yes</literal> is specified, the service will replace 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>If <literal>systemd.volatile=overlay-root</literal> is specified, the service will overlay the root
+    directory with an <literal>overlayfs</literal> file system, using the original <filename>/sysroot</filename> as
+    lower layer and a writable <literal>tmpfs</literal> as upper layer.
+    In addition, the original <filename>/usr/</filename> is mounted inside as read-only.
+    All files in the original file system are available, but any changes made directly under the root directory are lost on shutdown, while <filename>/usr/</filename> cannot be modified.</para>
+
+    <para>If <literal>systemd.volatile=overlay-usr</literal> is specified, the service will replace the
+    <filename>/usr/</filename> directory with an <literal>overlayfs</literal> file system,
+    using the original <filename>/usr/</filename> as lower layer and a writable <literal>tmpfs</literal> as upper layer.
+    This way, vendor data from <filename>/usr/</filename> is available as usual, but all new modifications made
+    under the <filename>/usr/</filename> directory are lost at shutdown.</para>
 
-    <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 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>
@@ -51,5 +62,4 @@
       <member><citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
     </simplelist></para>
   </refsect1>
-
 </refentry>

src/fstab-generator/fstab-generator.c

@@ -1370,7 +1370,7 @@ static int add_volatile_root(void) {
         /* Let's add in systemd-remount-volatile.service which will remount the root device to tmpfs if this is
          * requested (or as an overlayfs), leaving only /usr from the root mount inside. */
 
-        if (!IN_SET(arg_volatile_mode, VOLATILE_YES, VOLATILE_OVERLAY))
+        if (!IN_SET(arg_volatile_mode, VOLATILE_YES, VOLATILE_OVERLAY_ROOT, VOLATILE_OVERLAY_USR))
                 return 0;
 
         return generator_add_symlink(arg_dest, SPECIAL_INITRD_ROOT_FS_TARGET, "requires",

src/nspawn/nspawn-mount.c

@@ -1245,7 +1245,7 @@ static int setup_volatile_yes(const char *directory, uid_t uid_shift, const char
         return r;
 }
 
-static int setup_volatile_overlay(const char *directory, uid_t uid_shift, const char *selinux_apifs_context) {
+static int setup_volatile_overlay_root(const char *directory, uid_t uid_shift, const char *selinux_apifs_context) {
         _cleanup_free_ char *buf = NULL, *escaped_directory = NULL, *escaped_upper = NULL, *escaped_work = NULL;
         _cleanup_(rmdir_and_freep) char *template = NULL;
         const char *upper, *work, *options;
@@ -1320,8 +1320,8 @@ int setup_volatile_mode(
         case VOLATILE_STATE:
                 return setup_volatile_state(directory);
 
-        case VOLATILE_OVERLAY:
-                return setup_volatile_overlay(directory, uid_shift, selinux_apifs_context);
+        case VOLATILE_OVERLAY_ROOT:
+                return setup_volatile_overlay_root(directory, uid_shift, selinux_apifs_context);
 
         default:
                 return 0;

src/nspawn/nspawn.c

@@ -1813,7 +1813,7 @@ static const char *timezone_from_path(const char *path) {
 }
 
 static bool etc_writable(void) {
-        return !arg_read_only || IN_SET(arg_volatile_mode, VOLATILE_YES, VOLATILE_OVERLAY);
+        return !arg_read_only || IN_SET(arg_volatile_mode, VOLATILE_YES, VOLATILE_OVERLAY_ROOT);
 }
 
 static int setup_timezone(const char *dest) {

src/shared/volatile-util.c

@@ -3,6 +3,7 @@
 #include "alloc-util.h"
 #include "proc-cmdline.h"
 #include "string-table.h"
+#include "string-util.h"
 #include "volatile-util.h"
 
 int query_volatile_mode(VolatileMode *ret) {
@@ -35,7 +36,18 @@ static const char* const volatile_mode_table[_VOLATILE_MODE_MAX] = {
         [VOLATILE_NO] = "no",
         [VOLATILE_YES] = "yes",
         [VOLATILE_STATE] = "state",
-        [VOLATILE_OVERLAY] = "overlay",
+        [VOLATILE_OVERLAY_ROOT] = "overlay-root",
+        [VOLATILE_OVERLAY_USR] = "overlay-usr",
 };
 
-DEFINE_STRING_TABLE_LOOKUP_WITH_BOOLEAN(volatile_mode, VolatileMode, VOLATILE_YES);
+const char* volatile_mode_to_string(VolatileMode i) {
+        return string_table_lookup_to_string(volatile_mode_table, ELEMENTSOF(volatile_mode_table), i);
+}
+
+VolatileMode volatile_mode_from_string(const char *s) {
+        /* Handle backward compatibility: "overlay" maps to VOLATILE_OVERLAY_ROOT */
+        if (streq_ptr(s, "overlay"))
+                return VOLATILE_OVERLAY_ROOT;
+
+        return (VolatileMode) string_table_lookup_from_string_with_boolean(volatile_mode_table, ELEMENTSOF(volatile_mode_table), s, VOLATILE_YES);
+}

src/shared/volatile-util.h

@@ -7,7 +7,8 @@ typedef enum VolatileMode {
         VOLATILE_NO,
         VOLATILE_YES,
         VOLATILE_STATE,
-        VOLATILE_OVERLAY,
+        VOLATILE_OVERLAY_ROOT,
+        VOLATILE_OVERLAY_USR,
         _VOLATILE_MODE_MAX,
         _VOLATILE_MODE_INVALID = -EINVAL,
 } VolatileMode;