diff options
| -rw-r--r-- | docs/ENVIRONMENT.md | 4 | ||||
| -rw-r--r-- | man/os-release.xml | 17 | ||||
| -rw-r--r-- | man/rules/meson.build | 5 | ||||
| -rw-r--r-- | man/systemd-sysext.xml | 72 |
4 files changed, 80 insertions, 18 deletions
diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md index 3ec5573ff9..f29ca9226b 100644 --- a/docs/ENVIRONMENT.md +++ b/docs/ENVIRONMENT.md @@ -328,7 +328,9 @@ the journal instead of only when logging in debug mode. paths. Only "real" file systems and directories that only contain "real" file systems as submounts should be used. Do not specify API file systems such as `/proc/` or `/sys/` here, or hierarchies that have them as submounts. In - particular, do not specify the root directory `/` here. + particular, do not specify the root directory `/` here. Similarly, + `$SYSTEMD_CONFEXT_HIERARCHIES` works for confext images and supports the + systemd-confext multi-call functionality of sysext. `systemd-tmpfiles`: 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" /> |