shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-01-10 05:18:17 +03:00
Code

confext: documentation and man page updates for confext

Browse Source
This commit is contained in:
maanyagoenka 2023-02-24 08:42:45 +00:00
parent f7700ea599
commit 1f4f166690
4 changed files with 80 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/ENVIRONMENT.md
View File

@ -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`:

17
man/os-release.xml
View File

@ -442,6 +442,17 @@
</para></listitem>
</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
@ -453,6 +464,12 @@
but not to initrd environments.</para></listitem>
</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

5
man/rules/meson.build
View File

@ -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',

72
man/systemd-sysext.xml
View File

@ -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" />