diff options
Diffstat (limited to 'man/systemd-sysext.xml')
| -rw-r--r-- | man/systemd-sysext.xml | 361 |
1 files changed, 361 insertions, 0 deletions
diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml new file mode 100644 index 0000000..7607693 --- /dev/null +++ b/man/systemd-sysext.xml @@ -0,0 +1,361 @@ +<?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"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="systemd-sysext" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-sysext</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-sysext</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <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> + + <refsynopsisdiv> + <cmdsynopsis> + <command>systemd-sysext</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="plain">COMMAND</arg> + </cmdsynopsis> + + <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> + <title>Description</title> + + <para><command>systemd-sysext</command> activates/deactivates system extension images. System extension + images may – dynamically at runtime — extend the <filename>/usr/</filename> and + <filename>/opt/</filename> directory hierarchies with additional files. This is particularly useful on + immutable system images where a <filename>/usr/</filename> and/or <filename>/opt/</filename> hierarchy + residing on a read-only file system shall be extended temporarily at runtime without making any + persistent modifications.</para> + + <para>System extension images should contain files and directories similar in fashion to regular + operating system tree. When one or more system extension images are activated, their + <filename>/usr/</filename> and <filename>/opt/</filename> hierarchies are combined via + <literal>overlayfs</literal> with the same hierarchies of the host OS, and the host + <filename>/usr/</filename> and <filename>/opt/</filename> overmounted with it ("merging"). When they are + deactivated, the mount point is disassembled — again revealing the unmodified original host version of + the hierarchy ("unmerging"). Merging thus makes the extension's resources suddenly appear below the + <filename>/usr/</filename> and <filename>/opt/</filename> hierarchies as if they were included in the + base OS image itself. Unmerging makes them disappear again, leaving in place only the files that were + shipped with the base OS image itself.</para> + + <para>Files and directories contained in the extension images outside of the <filename>/usr/</filename> + and <filename>/opt/</filename> hierarchies are <emphasis>not</emphasis> merged, and hence have no effect + when included in a system extension image. In particular, files in the <filename>/etc/</filename> and + <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 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 + allows overlaying or removing files, but it is recommended not to make use of this.</para> + + <para>System extension images may be provided in the following formats:</para> + + <orderedlist> + <listitem><para>Plain directories or btrfs subvolumes containing the OS tree</para></listitem> + <listitem><para>Disk images with a GPT disk label, following the <ulink + url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink></para></listitem> + <listitem><para>Disk images lacking a partition table, with a naked Linux file system (e.g. erofs, + squashfs or ext4)</para></listitem> + </orderedlist> + + <para>These image formats are the same ones that + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + supports via its <option>--directory=</option>/<option>--image=</option> switches and those that the + service manager supports via <option>RootDirectory=</option>/<option>RootImage=</option>. Similar to + them they may optionally carry Verity authentication information.</para> + + <para>System extensions are searched for in the directories + <filename>/etc/extensions/</filename>, <filename>/run/extensions/</filename> and + <filename>/var/lib/extensions/</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/extensions/</filename>. Any directories found in + these search directories are considered directory based extension images; any files with the + <filename>.raw</filename> suffix are considered disk image based extension images. When invoked in the + initrd, the additional directory <filename>/.extra/sysext/</filename> is included in the directories that + are searched for extension images. Note however, that by default a tighter image policy applies to images + found there, though, see below. This directory is populated by + <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> with + extension images found in the system's EFI System Partition.</para> + + <para>During boot OS extension images are activated automatically, if the + <filename>systemd-sysext.service</filename> is enabled. Note that this service runs only after the + underlying file systems where system extensions may be located have been mounted. This means they are not + suitable for shipping resources that are processed by subsystems running in earliest boot. Specifically, + OS extension images are not suitable for shipping system services or + <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry> + definitions. See the <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink> page + for a simple mechanism for shipping system services in disk images, in a similar fashion to OS + extensions. Note the different isolation on these two mechanisms: while system extension directly extend + the underlying OS image with additional files that appear in a way very similar to as if they were + shipped in the OS image itself and thus imply no security isolation, portable services imply service + level sandboxing in one way or another. The <filename>systemd-sysext.service</filename> service is + guaranteed to finish start-up before <filename>basic.target</filename> is reached; i.e. at the time + regular services initialize (those which do not use <varname>DefaultDependencies=no</varname>), the files + and directories system extensions provide are available in <filename>/usr/</filename> and + <filename>/opt/</filename> and may be accessed.</para> + + <para>Note that there is no concept of enabling/disabling installed system extension images: all + installed extension images are automatically activated at boot. However, you can place an empty directory + named like the extension (no <filename>.raw</filename>) in <filename>/etc/extensions/</filename> to "mask" + an extension with the same name in a system folder with lower precedence.</para> + + <para>A simple mechanism for version compatibility is enforced: a system extension image must carry a + <filename>/usr/lib/extension-release.d/extension-release.<replaceable>NAME</replaceable></filename> + file, which must match its image name, that is compared with the host <filename>os-release</filename> + file: the contained <varname>ID=</varname> fields have to match unless <literal>_any</literal> is set + for the extension. If the extension <varname>ID=</varname> is not <literal>_any</literal>, the + <varname>SYSEXT_LEVEL=</varname> field (if defined) has to match. If the latter is not defined, the + <varname>VERSION_ID=</varname> field has to match instead. If the extension defines the + <varname>ARCHITECTURE=</varname> field and the value is not <literal>_any</literal> it has to match the kernel's + architecture reported by <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> + but the used architecture identifiers are the same as for <varname>ConditionArchitecture=</varname> + described in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + <varname>EXTENSION_RELOAD_MANAGER=</varname> can be set to 1 if the extension requires a service manager reload after application + of the extension. Note that the for the reasons mentioned earlier: + <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink> remain + the recommended way to ship system services. + + System extensions should not ship a <filename>/usr/lib/os-release</filename> file (as that would be merged + into the host <filename>/usr/</filename> tree, overriding the host OS version data, which is not desirable). + 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. The merged hierarchy will be mounted with <literal>nosuid</literal> and + (if not disabled via <option>--noexec=false</option>) <literal>noexec</literal>.</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 + carrying large binary images, however is still useful for carrying symlinks to them. The primary place + for installing configuration 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 + the <varname>user.extension-release.strict</varname> + <citerefentry project='man-pages'><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry>), + 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> + <title>Uses</title> + + <para>The primary use case for system images are immutable environments where debugging and development + tools shall optionally be made available, but not included in the immutable base OS image itself (e.g. + <citerefentry project='man-pages'><refentrytitle>strace</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and + <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry> + shall be an optionally installable addition in order to make debugging/development easier). System + extension images should not be misunderstood as a generic software packaging framework, as no dependency + scheme is available: system extensions should carry all files they need themselves, except for those + already shipped in the underlying host system image. Typically, system extension images are built at the + same time as the base OS image — within the same build system.</para> + + <para>Another use case for the system extension concept is temporarily overriding OS supplied resources + with newer ones, for example to install a locally compiled development version of some low-level + component over the immutable OS image without doing a full OS rebuild or modifying the nominally + immutable image. (e.g. "install" a locally built package with <command>DESTDIR=/var/lib/extensions/mytest + make install && systemd-sysext refresh</command>, making it available in + <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> + + <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 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> of sysext and for <filename>/etc/</filename> of confext).</para> + + <xi:include href="version-info.xml" xpointer="v248"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>merge</option></term> + <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. For confext, the merge + happens into the <filename>/etc/</filename> directory instead.</para> + + <xi:include href="version-info.xml" xpointer="v248"/></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> for sysext and <filename>/etc/</filename>, + for confext, by unmounting the <literal>overlayfs</literal> file systems created by <option>merge</option> + prior.</para> + + <xi:include href="version-info.xml" xpointer="v248"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>refresh</option></term> + <listitem><para>A combination of <option>unmerge</option> and <option>merge</option>: if already + 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> + + <xi:include href="version-info.xml" xpointer="v248"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>list</option></term> + + <listitem><para>A brief list of installed extension images is shown.</para> + + <xi:include href="version-info.xml" xpointer="v248"/></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + </refsect1> + + <refsect1> + <title>Options</title> + + <variablelist> + <varlistentry> + <term><option>--root=</option></term> + + <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 for sysext or <filename>/etc/</filename> for confext, + but below some specified root directory.</para> + + <xi:include href="version-info.xml" xpointer="v248"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--force</option></term> + + <listitem><para>When merging system extensions into <filename>/usr/</filename> and + <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> + + <xi:include href="version-info.xml" xpointer="v248"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--image-policy=<replaceable>policy</replaceable></option></term> + + <listitem><para>Takes an image policy string as argument, as per + <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The + policy is enforced when operating on system extension disk images. If not specified defaults to + <literal>root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent</literal> + for system extensions, i.e. only the root and <filename>/usr/</filename> file systems in the image + are used. For configuration extensions defaults to + <literal>root=verity+signed+encrypted+unprotected+absent</literal>. When run in the initrd and + operating on a system extension image stored in the <filename>/.extra/sysext/</filename> directory a + slightly stricter policy is used by default: <literal>root=signed+absent:usr=signed+absent</literal>, + see above for details.</para> + + <xi:include href="version-info.xml" xpointer="v254"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--noexec=</option><replaceable>BOOL</replaceable></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 + it.</para> + + <xi:include href="version-info.xml" xpointer="v254"/></listitem> + </varlistentry> + + <varlistentry> + <term><option>--no-reload</option></term> + + <listitem> + <para>When used with <command>merge</command>, + <command>unmerge</command> or <command>refresh</command>, do not reload daemon + after executing the changes even if an extension that is applied requires a reload via the + <varname>EXTENSION_RELOAD_MANAGER=</varname> set to 1.</para> + + <xi:include href="version-info.xml" xpointer="v255"/> + </listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="no-pager" /> + <xi:include href="standard-options.xml" xpointer="no-legend" /> + <xi:include href="standard-options.xml" xpointer="json" /> + </variablelist> + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>On success, 0 is returned.</para> + </refsect1> + + <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> + </refsect1> + +</refentry> |