From: Krzesimir Nowak <knowak@microsoft.com>
Date: Wed, 28 Feb 2024 08:42:25 +0000 (+0100)
Subject: man: Document sysext ephemeral mode
X-Git-Tag: v256-rc1~405^2~7
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=504bdf08b52364913d00339316c0efca821354ee;p=thirdparty%2Fsystemd.git

man: Document sysext ephemeral mode
---

diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml
index e0867964118..df5dcafbd16 100644
--- a/man/systemd-sysext.xml
+++ b/man/systemd-sysext.xml
@@ -221,21 +221,26 @@
 
     <para>The following modes are supported:
     <orderedlist>
-      <listitem><para><option>disabled</option>: Force immutable mode even if write routing
-        directories exist below <filename>/var/lib/extensions.mutable/</filename>.
-        This is the default.</para></listitem>
-      <listitem><para><option>auto</option>: Automatic mode. Mutability is disabled by default
-        and only enabled if a corresponding write routing directory exists below
-        <filename>/var/lib/extensions.mutable/</filename>.</para></listitem>
+      <listitem><para><option>disabled</option>: Force immutable mode even if write routing directories exist
+      below <filename>/var/lib/extensions.mutable/</filename>. This is the default.</para></listitem>
+      <listitem><para><option>auto</option>: Automatic mode. Mutability is disabled by default and only
+      enabled if a corresponding write routing directory exists below
+      <filename>/var/lib/extensions.mutable/</filename>.</para></listitem>
       <listitem><para><option>enabled</option>: Force mutable mode and automatically create write routing
-        directories below <filename>/var/lib/extensions.mutable/</filename> when required.</para></listitem>
+      directories below <filename>/var/lib/extensions.mutable/</filename> when required.</para></listitem>
       <listitem><para><option>import</option>: Force immutable mode like <option>disabled</option> above, but
-        merge the contents of directories below <filename>/var/lib/extensions.mutable/</filename> into the host
-        file system.</para></listitem>
+      merge the contents of directories below <filename>/var/lib/extensions.mutable/</filename> into the host
+      file system.</para></listitem>
+      <listitem><para><option>ephemeral</option>: Force mutable mode like <option>enabled</option> above, but
+      instead of using write routing directory below <filename>/var/lib/extensions.mutable/</filename>,
+      <command>systemd-sysext</command> will use empty ephemeral directories. This means that the
+      modifications made in the merged hierarchies will be gone when the hierarchies are
+      unmerged.</para></listitem>
     </orderedlist>
     See "Options" below on specifying modes using the <option>--mutable=</option> command line option.</para>
 
-    <para>Mutable mode routes writes to subdirectories in <filename>/var/lib/extensions.mutable/</filename>.
+    <para>With exception of the ephemeral mode, the mutable mode routes writes to subdirectories in
+    <filename>/var/lib/extensions.mutable/</filename>.
     <simplelist type="horiz">
       <member>Writes to <filename>/usr/</filename> are directed to <filename>/var/lib/extensions.mutable/usr/</filename></member>,
       <member>writes to <filename>/opt/</filename> are directed to <filename>/var/lib/extensions.mutable/opt/</filename>, and</member>
@@ -253,10 +258,11 @@
     </simplelist>
     to route writes back to the original base directory hierarchy.</para>
 
-    <para> Alternatively, a temporary file system may be mounted to
+    <para>Alternatively, a temporary file system may be mounted to
     <filename>/var/lib/extensions.mutable/</filename>, or symlinks in
-    <filename>/var/lib/extensions.mutable/</filename> may point to sub-directories on a temporary
-    file system (e.g. below <filename>/tmp/</filename>) to only allow ephemeral changes.</para>
+    <filename>/var/lib/extensions.mutable/</filename> may point to sub-directories on a temporary file system
+    (e.g. below <filename>/tmp/</filename>) to only allow ephemeral changes. Note that this is not the same
+    as ephemeral mode, because the temporary file system will still exist after unmerging.</para>
 
     <xi:include href="version-info.xml" xpointer="v256"/>
   </refsect1>
@@ -403,6 +409,14 @@
             <filename>/var/lib/extensions.mutable/</filename> also merged into the host file system.</para>
             <xi:include href="version-info.xml" xpointer="v256"/></listitem>
           </varlistentry>
+
+          <varlistentry>
+            <term><option>ephemeral</option></term>
+            <listitem><para>force mutable mode, but with contents of write routing directories in
+            <filename>/var/lib/extensions.mutable/</filename> being ignored, and modifications of the host
+            file system being discarded after unmerge.</para>
+            <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+          </varlistentry>
         </variablelist>
 
         <xi:include href="version-info.xml" xpointer="v256"/></listitem>