confext: documentation and man page updates for confext

1 files changed, 56 insertions, 16 deletions

diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml
index 96e40ddf95..f3a12e0a1c 100644
--- a/man/systemd-sysext.xml
+++ b/man/systemd-sysext.xml
@@ -19,6 +19,8 @@
   <refnamediv>
     <refname>systemd-sysext</refname>
     <refname>systemd-sysext.service</refname>
+    <refname>systemd-confext</refname>
+    <refname>systemd-confext.service</refname>
     <refpurpose>Activates System Extension Images</refpurpose>
   </refnamediv>
 
@@ -31,6 +33,14 @@
 
     <para><literallayout><filename>systemd-sysext.service</filename></literallayout></para>
 
+    <cmdsynopsis>
+      <command>systemd-confext</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+      <arg choice="plain">COMMAND</arg>
+    </cmdsynopsis>
+
+    <para><literallayout><filename>systemd-confext.service</filename></literallayout></para>
+
   </refsynopsisdiv>
 
   <refsect1>
@@ -129,6 +139,29 @@
     The <filename>extension-release</filename> file follows the same format and semantics, and carries the same
     content, as the <filename>os-release</filename> file of the OS, but it describes the resources carried
     in the extension image.</para>
+
+    <para>The <command>systemd-confext</command> concept follows the same principle as the
+    <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    functionality but instead of working on <filename>/usr</filename> and <filename>/opt</filename>,
+    <command>confext</command> will extend only <filename>/etc</filename>. Files and directories contained
+    in the confext images outside of the <filename>/etc/</filename> hierarchy are <emphasis>not</emphasis>
+    merged, and hence have no effect when included in the image. Formats for these images are of the
+    same as sysext images.</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 two listed directories are not suitable for
+    carrying large binary images, however are still useful for carrying symlinks to them. The primary place
+    for installing system extensions is <filename>/var/lib/confexts/</filename>. Any directories found in
+    these search directories are considered directory based confext images, any files with the
+    <filename>.raw</filename> suffix are considered disk image based confext images.</para>
+
+    <para>Again, just like sysext images, the confext images will contain a
+    <filename>/etc/extension-release.d/extension-release.<replaceable>$name</replaceable></filename>
+    file, which must match the image name (with the usual escape hatch of xattr), and again with content
+    being one or more of <varname>ID=</varname>, <varname>VERSION_ID=</varname>, and
+    <varname>CONFEXT_LEVEL</varname>. Confext images will then be checked and matched against the
+    base OS layer.</para>
   </refsect1>
 
   <refsect1>
@@ -153,20 +186,25 @@
     <filename>/usr/</filename> as if it was installed in the OS image itself.) This case works regardless if
     the underlying host <filename>/usr/</filename> is managed as immutable disk image or is a traditional
     package manager controlled (i.e. writable) tree.</para>
-  </refsect1>
+
+    <para>For the confext case, the OSConfig project aims to 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>
 
   <refsect1>
     <title>Commands</title>
 
-    <para>The following commands are understood:</para>
+    <para>The following commands are understood by both the sysext and confext concepts:</para>
 
     <variablelist>
       <varlistentry>
         <term><option>status</option></term>
 
         <listitem><para>When invoked without any command verb, or when <option>status</option> is specified
-        the current merge status is shown, separately for both <filename>/usr/</filename> and
-        <filename>/opt/</filename>.</para></listitem>
+        the current merge status is shown, separately (for both <filename>/usr/</filename> and
+        <filename>/opt/</filename> of sysext and for <filename>/etc/</filename> of confext).</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -174,14 +212,15 @@
         <listitem><para>Merges all currently installed system extension images into
         <filename>/usr/</filename> and <filename>/opt/</filename>, by overmounting these hierarchies with an
         <literal>overlayfs</literal> file system combining the underlying hierarchies with those included in
-        the extension images. This command will fail if the hierarchies are already merged.</para></listitem>
+        the extension images. This command will fail if the hierarchies are already merged. For confext, the merge
+        happens into the <filename>/etc/</filename> directory instead.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><option>unmerge</option></term>
         <listitem><para>Unmerges all currently installed system extension images from
-        <filename>/usr/</filename> and <filename>/opt/</filename>, by unmounting the
-        <literal>overlayfs</literal> file systems created by <option>merge</option>
+        <filename>/usr/</filename> and <filename>/opt/</filename> for sysext and <filename>/etc/</filename>,
+        for confext, by unmounting the <literal>overlayfs</literal> file systems created by <option>merge</option>
         prior.</para></listitem>
       </varlistentry>
 
@@ -191,11 +230,11 @@
         mounted the existing <literal>overlayfs</literal> instance is unmounted temporarily, and then
         replaced by a new version. This command is useful after installing/removing system extension images,
         in order to update the <literal>overlayfs</literal> file system accordingly. If no system extensions
-        are installed when this command is executed, the equivalent of <option>unmerge</option> is
-        executed, without establishing any new <literal>overlayfs</literal> instance. Note that currently
-        there's a brief moment where neither the old nor the new <literal>overlayfs</literal> file system is
-        mounted. This implies that all resources supplied by a system extension will briefly disappear — even
-        if it exists continuously during the refresh operation.</para></listitem>
+        are installed when this command is executed, the equivalent of <option>unmerge</option> is executed,
+        without establishing any new <literal>overlayfs</literal> instance.
+        Note that currently there's a brief moment where neither the old nor the new <literal>overlayfs</literal>
+        file system is mounted. This implies that all resources supplied by a system extension will briefly
+        disappear — even if it exists continuously during the refresh operation.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -218,16 +257,17 @@
 
         <listitem><para>Operate relative to the specified root directory, i.e. establish the
         <literal>overlayfs</literal> mount not on the top-level host <filename>/usr/</filename> and
-        <filename>/opt/</filename> hierarchies, but below some specified root directory.</para></listitem>
+        <filename>/opt/</filename> hierarchies for sysext or <filename>/etc/</filename> for confext,
+        but below some specified root directory.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><option>--force</option></term>
 
         <listitem><para>When merging system extensions into <filename>/usr/</filename> and
-        <filename>/opt/</filename>, ignore version incompatibilities, i.e. force merging regardless of
-        whether the version information included in the extension images matches the host or
-        not.</para></listitem>
+        <filename>/opt/</filename> for sysext and <filename>/etc/</filename> for confext,
+        ignore version incompatibilities, i.e. force merging regardless of
+        whether the version information included in the images matches the host or not.</para></listitem>
       </varlistentry>
 
       <xi:include href="standard-options.xml" xpointer="no-pager" />