Adding upstream version 256.upstream/256

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 138 insertions, 15 deletions

diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml
index 3f0a0c2..c9bbf49 100644
--- a/man/systemd-sysext.xml
+++ b/man/systemd-sysext.xml
@@ -1,9 +1,9 @@
 <?xml version='1.0'?> <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
 
-<refentry id="systemd-sysext"
+<refentry id="systemd-sysext" conditional='ENABLE_SYSEXT'
     xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
@@ -31,7 +31,7 @@
       <arg choice="plain">COMMAND</arg>
     </cmdsynopsis>
 
-    <para><literallayout><filename>systemd-sysext.service</filename></literallayout></para>
+    <para><filename>systemd-sysext.service</filename></para>
 
     <cmdsynopsis>
       <command>systemd-confext</command>
@@ -39,8 +39,7 @@
       <arg choice="plain">COMMAND</arg>
     </cmdsynopsis>
 
-    <para><literallayout><filename>systemd-confext.service</filename></literallayout></para>
-
+    <para><filename>systemd-confext.service</filename></para>
   </refsynopsisdiv>
 
   <refsect1>
@@ -70,8 +69,10 @@
     <filename>/var/</filename> included in a system extension image will <emphasis>not</emphasis> appear in
     the respective hierarchies after activation.</para>
 
-    <para>System extension images are strictly read-only, and the host <filename>/usr/</filename> and
-    <filename>/opt/</filename> hierarchies become read-only too while they are activated.</para>
+    <para>System extension images are strictly read-only by default. On mutable host file systems,
+    <filename>/usr/</filename> and <filename>/opt/</filename> hierarchies become read-only while extensions
+    are merged, unless mutability is enabled. Mutability may be enabled via the <option>--mutable=</option>
+    option; see "Mutability" below for more information.</para>
 
     <para>System extensions are supposed to be purely additive, i.e. they are supposed to include only files
     that do not exist in the underlying basic OS image. However, the underlying mechanism (overlayfs) also
@@ -159,6 +160,11 @@
     same as sysext images. The merged hierarchy will be mounted with <literal>nosuid</literal> and
     (if not disabled via <option>--noexec=false</option>) <literal>noexec</literal>.</para>
 
+    <para>Just like sysexts, confexts are strictly read-only by default. Merging confexts on mutable host
+    file systems will result in <filename>/etc/</filename> becoming read-only. As with sysexts, mutability
+    can be enabled via the <option>--mutable=</option> option. Refer to "Mutability" below for more
+    information.</para>
+
     <para>Confexts are looked for in the directories <filename>/run/confexts/</filename>,
     <filename>/var/lib/confexts/</filename>, <filename>/usr/lib/confexts/</filename> and
     <filename>/usr/local/lib/confexts/</filename>. The first listed directory is not suitable for
@@ -200,11 +206,72 @@
     the underlying host <filename>/usr/</filename> is managed as immutable disk image or is a traditional
     package manager controlled (i.e. writable) tree.</para>
 
-    <para>For the confext case, the OSConfig project aims to perform runtime reconfiguration of OS services.
+    <para>With systemd-confext one can perform runtime reconfiguration of OS services.
     Sometimes, there is a need to swap certain configuration parameter values or restart only a specific
     service without deployment of new code or a complete OS deployment. In other words, we want to be able
     to tie the most frequently configured options to runtime updateable flags that can be changed without a
-    system reboot. This will help reduce servicing times when there is a need for changing the OS configuration.</para></refsect1>
+    system reboot. This will help reduce servicing times when there is a need for changing the OS configuration.
+    It also provides a reliable tool for managing configuration because all old configuration files disappear when
+    the systemd-confext image is removed.</para></refsect1>
+
+  <refsect1>
+    <title>Mutability</title>
+    <para>By default, merging system extensions on mutable host file systems will render <filename>/usr/</filename>
+    and <filename>/opt/</filename> hierarchies read-only. Merging configuration extensions will have the same
+    effect on <filename>/etc/</filename>. Mutable mode allows writes to these locations when extensions are
+    merged.</para>
+
+    <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>enabled</option>: Force mutable mode and automatically create write routing
+      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>
+      <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>
+      <listitem><para><option>ephemeral-import</option>: Force mutable mode like <option>ephemeral</option>
+      above, but instead of ignoring the contents of write routing directories under
+      <filename>/var/lib/extensions.mutable/</filename>, merge them into the host file system, like
+      <option>import</option> does.</para></listitem>
+    </orderedlist>
+    See "Options" below on specifying modes using the <option>--mutable=</option> command line option.</para>
+
+    <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>
+      <member>writes to <filename>/etc/</filename> land in <filename>/var/lib/extensions.mutable/etc/</filename>.</member>
+    </simplelist></para>
+
+    <para>If <filename>usr/</filename>, <filename>opt/</filename>, or <filename>etc/</filename>
+    in <filename>/var/lib/extensions.mutable/</filename> are symlinks, then writes are directed to the
+    symlinks' targets.
+    Consequently, to retain mutability of a host file system, create symlinks
+    <simplelist type="horiz">
+      <member><filename>/var/lib/extensions.mutable/etc/</filename> → <filename>/etc/</filename></member>
+      <member><filename>/var/lib/extensions.mutable/usr/</filename> → <filename>/usr/</filename></member>
+      <member><filename>/var/lib/extensions.mutable/opt/</filename> → <filename>/opt/</filename></member>
+    </simplelist>
+    to route writes back to the original base directory hierarchy.</para>
+
+    <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. 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>
 
   <refsect1>
     <title>Commands</title>
@@ -315,7 +382,62 @@
       </varlistentry>
 
       <varlistentry>
-        <term><option>--noexec=</option><replaceable>BOOL</replaceable></term>
+        <term><option>--mutable=<replaceable>BOOL</replaceable>|<replaceable>auto</replaceable>|<replaceable>import</replaceable></option></term>
+        <listitem><para>Set mutable mode.</para>
+
+        <variablelist>
+          <varlistentry>
+            <term><option>no</option></term>
+            <listitem><para>force immutable mode even with write routing directories present.
+            This is the default.</para>
+            <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><option>auto</option></term>
+            <listitem><para>enable mutable mode individually for <filename>/usr/</filename>,
+            <filename>/opt/</filename>, and <filename>/etc/</filename> if write routing sub-directories
+            or symlinks are present in <filename>/var/lib/extensions.mutable/</filename>; disable otherwise.
+            See "Mutability" above for more information on write routing.</para>
+            <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><option>yes</option></term>
+            <listitem><para>force mutable mode. Write routing directories will be created in
+            <filename>/var/lib/extensions.mutable/</filename> if not present.</para>
+            <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><option>import</option></term>
+            <listitem><para>immutable mode, but with contents of write routing directories in
+            <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>
+
+          <varlistentry>
+            <term><option>ephemeral-import</option></term>
+            <listitem><para>force mutable mode, with contents of write routing directories in
+            <filename>/var/lib/extensions.mutable/</filename> being merged into the host file system, but
+            with the modifications made to 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>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--noexec=<replaceable>BOOL</replaceable></option></term>
 
         <listitem><para>When merging configuration extensions into <filename>/etc/</filename> the
         <literal>MS_NOEXEC</literal> mount flag is used by default. This option can be used to disable
@@ -351,11 +473,12 @@
 
   <refsect1>
     <title>See Also</title>
-    <para>
-      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>
-    </para>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+    </simplelist></para>
   </refsect1>
 
 </refentry>