diff options
Diffstat (limited to 'man')
-rw-r--r-- | man/os-release.xml | 17 | ||||
-rw-r--r-- | man/rules/meson.build | 5 | ||||
-rw-r--r-- | man/systemd-sysext.xml | 72 |
3 files changed, 77 insertions, 17 deletions
diff --git a/man/os-release.xml b/man/os-release.xml index e74f27b990..6cc786acf9 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -443,6 +443,17 @@ </varlistentry> <varlistentry> + <term><varname>CONFEXT_LEVEL=</varname></term> + + <listitem><para>Semantically the same as <varname>SYSEXT_LEVEL=</varname> but for confext images. + See <filename>/etc/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename> + for more information.</para> + + <para>Examples: <literal>CONFEXT_LEVEL=2</literal>, <literal>CONFEXT_LEVEL=15.14</literal>. + </para></listitem> + </varlistentry> + + <varlistentry> <term><varname>SYSEXT_SCOPE=</varname></term> <listitem><para>Takes a space-separated list of one or more of the strings <literal>system</literal>, <literal>initrd</literal> and <literal>portable</literal>. This field is @@ -454,6 +465,12 @@ </varlistentry> <varlistentry> + <term><varname>CONFEXT_SCOPE=</varname></term> + + <listitem><para>Semantically the same as <varname>SYSEXT_SCOPE=</varname> but for confext images.</para></listitem> + </varlistentry> + + <varlistentry> <term><varname>PORTABLE_PREFIXES=</varname></term> <listitem><para>Takes a space-separated list of one or more valid prefix match strings for the <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services Documentation</ulink> logic. diff --git a/man/rules/meson.build b/man/rules/meson.build index 63a68c3211..b6c88db390 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -1043,7 +1043,10 @@ manpages = [ 'systemd-suspend-then-hibernate.service'], ''], ['systemd-sysctl.service', '8', ['systemd-sysctl'], ''], - ['systemd-sysext', '8', ['systemd-sysext.service'], ''], + ['systemd-sysext', + '8', + ['systemd-confext', 'systemd-confext.service', 'systemd-sysext.service'], + ''], ['systemd-system-update-generator', '8', [], ''], ['systemd-system.conf', '5', 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" /> |