man/systemd-sysext.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-sysext"
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-sysext</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-sysext</refentrytitle>
  16     <manvolnum>8</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-sysext</refname>
  21     <refname>systemd-sysext.service</refname>
  22     <refpurpose>Activates System Extension Images</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <cmdsynopsis>
  27       <command>systemd-sysext</command>
  28       <arg choice="opt" rep="repeat">OPTIONS</arg>
  29     </cmdsynopsis>
  30
  31     <para><literallayout><filename>systemd-sysext.service</filename></literallayout></para>
  32
  33   </refsynopsisdiv>
  34
  35   <refsect1>
  36     <title>Description</title>
  37
  38     <para><command>systemd-sysext</command> activates/deactivates system extension images. System extension
  39     images may – dynamically at runtime — extend the <filename>/usr/</filename> and
  40     <filename>/opt/</filename> directory hierarchies with additional files. This is particularly useful on
  41     immutable system images where a <filename>/usr/</filename> and/or <filename>/opt/</filename> hierarchy
  42     residing on a read-only file system shall be extended temporarily at runtime without making any
  43     persistent modifications.</para>
  44
  45     <para>System extension images should contain files and directories similar in fashion to regular
  46     operating system tree. When one or more system extension images are activated, their
  47     <filename>/usr/</filename> and <filename>/opt/</filename> hierarchies are combined via
  48     <literal>overlayfs</literal> with the same hierarchies of the host OS, and the host
  49     <filename>/usr/</filename> and <filename>/opt</filename> overmounted with it ("merging"). When they are
  50     deactivated, the mount point is disassembled — again revealing the unmodified original host version of
  51     the hierarchy ("unmerging"). Merging thus makes the extension's resources suddenly appear below the
  52     <filename>/usr/</filename> and <filename>/opt/</filename> hierarchies as if they were included in the
  53     base OS image itself. Unmerging makes them disappear again, leaving in place only the files that were
  54     shipped with the base OS image itself.</para>
  55
  56     <para>Files and directories contained in the extension images outside of the <filename>/usr/</filename>
  57     and <filename>/opt/</filename> hierarchies are <emphasis>not</emphasis> merged, and hence have no effect
  58     when included in a system extension image. In particular, files in the <filename>/etc/</filename> and
  59     <filename>/var/</filename> included in a system extension image will <emphasis>not</emphasis> appear in
  60     the respective hierarchies after activation.</para>
  61
  62     <para>System extension images are strictly read-only, and the host <filename>/usr/</filename> and
  63     <filename>/opt/</filename> hierarchies become read-only too while they are activated.</para>
  64
  65     <para>System extensions are supposed to be purely additive, i.e. they are supposed to include only files
  66     that do not exist in the underlying basic OS image. However, the underlying mechanism (overlayfs) also
  67     allows removing files, but it is recommended not to make use of this.</para>
  68
  69     <para>System extension images may be provided in the following formats:</para>
  70
  71     <orderedlist>
  72       <listitem><para>Plain directories or btrfs subvolumes containing the OS tree</para></listitem>
  73       <listitem><para>Disk images with a GPT disk label, following the <ulink
  74       url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partition Specification</ulink></para></listitem>
  75       <listitem><para>Disk images lacking a partition table, with a naked Linux file system (e.g. squashfs or ext4)</para></listitem>
  76     </orderedlist>
  77
  78     <para>These image formats are the same ones that
  79     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  80     supports via it's <option>--directory=</option>/<option>--image=</option> switches and those that the
  81     service manager supports via <option>RootDirectory=</option>/<option>RootImage=</option>. Similar to
  82     them they may optionally carry Verity authentication information.</para>
  83
  84     <para>System extensions are automatically looked for in the directories
  85     <filename>/etc/extensions/</filename>, <filename>/run/extensions/</filename>,
  86     <filename>/var/lib/extensions/</filename>, <filename>/usr/lib/extensions/</filename> and
  87     <filename>/usr/local/lib/extensions/</filename>. The first two listed directories are not suitable for
  88     carrying large binary images, however are still useful for carrying symlinks to them. The primary place
  89     for installing system extensions is <filename>/var/lib/extensions/</filename>. Any directories found in
  90     these search directories are considered directory based extension images, any files with the
  91     <filename>.raw</filename> suffix are considered disk image based extension images.</para>
  92
  93     <para>During boot OS extension images are activated automatically, if the
  94     <filename>systemd-sysext.service</filename> is enabled. Note that this service runs only after the
  95     underlying file systems where system extensions are searched are mounted. This means they are not
  96     suitable for shipping resources that are processed by subsystems running in earliest boot. Specifically,
  97     OS extension images are not suitable for shipping system services or
  98     <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  99     definitions. See <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink> for a simple
 100     mechanism for shipping system services in disk images, in a similar fashion to OS extensions. Note the
 101     different isolation on these two mechanisms: while system extension directly extend the underlying OS
 102     image with additional files that appear in a way very similar to as if they were shipped in the OS image
 103     itself and thus imply no security isolation, portable services imply service level sandboxing in one way
 104     or another. The <filename>systemd-sysext.service</filename> service is guaranteed to finish start-up
 105     before <filename>basic.target</filename> is reached; i.e. at the time regular services initialize (those
 106     which do not use <varname>DefaultDependencies=no</varname>), the files and directories system extensions
 107     provide are available in <filename>/usr/</filename> and <filename>/opt/</filename> and may be
 108     accessed.</para>
 109
 110     <para>Note that there is no concept of enabling/disabling installed system extension images: all
 111     installed extension images are automatically activated at boot.</para>
 112
 113     <para>A simple mechanism for version compatibility is enforced: a system extension image must carry a
 114     <filename>/usr/lib/extension-release.d/extension-release.<replaceable>$name</replaceable></filename>
 115     file, which must match its image name, that is compared with the host <filename>os-release</filename>
 116     file: the contained <varname>ID=</varname> fields have to match, as well as the
 117     <varname>SYSEXT_LEVEL=</varname> field (if defined). If the latter is not defined, the
 118     <varname>VERSION_ID=</varname> field has to match instead. System extensions should not ship a
 119     <filename>/usr/lib/os-release</filename> file (as that would be merged into the host
 120     <filename>/usr/</filename> tree, overriding the host OS version data, which is not desirable). The
 121     <filename>extension-release</filename> file follows the same format and semantics, and carries the same
 122     content, as the <filename>os-release</filename> file of the OS, but it describes the resources carried
 123     in the extension image.</para>
 124   </refsect1>
 125
 126   <refsect1>
 127     <title>Uses</title>
 128
 129     <para>The primary use case for system images are immutable environments where debugging and development
 130     tools shall optionally be made available, but not included in the immutable base OS image itself
 131     (e.g. <filename>strace</filename> and <filename>gdb</filename> shall be an optionally installable
 132     addition in order to make debugging/development easier). System extension images should not be
 133     misunderstood as a generic software packaging framework, as no dependency scheme is available: system
 134     extensions should carry all files they need themselves, except for those already shipped in the
 135     underlying host system image. Typically, system extension images are built at the same time as the base
 136     OS image — within the same build system.</para>
 137
 138     <para>Another use case for the system extension concept is temporarily overriding OS supplied resources
 139     with newer ones, for example to install a locally compiled development version of some low-level
 140     component over the immutable OS image without doing a full OS rebuild or modifying the nominally
 141     immutable image. (e.g. "install" a locally built package with <command>DESTDIR=/var/lib/extensions/mytest
 142     make install &amp;&amp; systemd-sysext refresh</command>, making it available in
 143     <filename>/usr/</filename> as if it was installed in the OS image itself.) This case works regardless if
 144     the underlying host <filename>/usr/</filename> is managed as immutable disk image or is a traditional
 145     package manager controlled (i.e. writable) tree.</para>
 146   </refsect1>
 147
 148   <refsect1>
 149     <title>Commands</title>
 150
 151     <para>The following commands are understood:</para>
 152
 153     <variablelist>
 154       <varlistentry>
 155         <term><option>status</option></term>
 156
 157         <listitem><para>When invoked without any command verb, or when <option>status</option> is specified
 158         the current merge status is shown, separately for both <filename>/usr/</filename> and
 159         <filename>/opt/</filename>.</para></listitem>
 160       </varlistentry>
 161
 162       <varlistentry>
 163         <term><option>merge</option></term>
 164         <listitem><para>Merges all currently installed system extension images into
 165         <filename>/usr/</filename> and <filename>/opt/</filename>, by overmounting these hierarchies with an
 166         <literal>overlayfs</literal> file system combining the underlying hierarchies with those included in
 167         the extension images. This command will fail if the hierarchies are already merged.</para></listitem>
 168       </varlistentry>
 169
 170       <varlistentry>
 171         <term><option>unmerge</option></term>
 172         <listitem><para>Unmerges all currently installed system extension images from
 173         <filename>/usr/</filename> and <filename>/opt/</filename>, by unmounting the
 174         <literal>overlayfs</literal> file systems created by <option>merge</option>
 175         prior.</para></listitem>
 176       </varlistentry>
 177
 178       <varlistentry>
 179         <term><option>refresh</option></term>
 180         <listitem><para>A combination of <option>unmerge</option> and <option>merge</option>: if already
 181         mounted the existing <literal>overlayfs</literal> instance is unmounted temporarily, and then
 182         replaced by a new version. This command is useful after installing/removing system extension images,
 183         in order to update the <literal>overlayfs</literal> file system accordingly. If no system extensions
 184         are installed when this command is executed, the equivalent of <option>unmerge</option> is
 185         executed, without establishing any new <literal>overlayfs</literal> instance. Note that currently
 186         there's a brief moment where neither the old nor the new <literal>overlayfs</literal> file system is
 187         mounted. This implies that all resources supplied by a system extension will briefly disappear — even
 188         if it exists continuously during the refresh operation.</para></listitem>
 189       </varlistentry>
 190
 191       <varlistentry>
 192         <term><option>list</option></term>
 193
 194         <listitem><para>A brief list of installed extension images is shown.</para></listitem>
 195       </varlistentry>
 196
 197       <xi:include href="standard-options.xml" xpointer="help" />
 198       <xi:include href="standard-options.xml" xpointer="version" />
 199     </variablelist>
 200   </refsect1>
 201
 202   <refsect1>
 203     <title>Options</title>
 204
 205     <variablelist>
 206       <varlistentry>
 207         <term><option>--root=</option></term>
 208
 209         <listitem><para>Operate relative to the specified root directory, i.e. establish the
 210         <literal>overlayfs</literal> mount not on the top-level host <filename>/usr/</filename> and
 211         <filename>/opt/</filename> hierarchies, but below some specified root directory.</para></listitem>
 212       </varlistentry>
 213
 214       <varlistentry>
 215         <term><option>--force</option></term>
 216
 217         <listitem><para>When merging system extensions into <filename>/usr/</filename> and
 218         <filename>/opt/</filename>, ignore version incompatibilities, i.e. force merging regardless of
 219         whether the version information included in the extension images matches the host or
 220         not.</para></listitem>
 221       </varlistentry>
 222
 223       <xi:include href="standard-options.xml" xpointer="no-pager" />
 224       <xi:include href="standard-options.xml" xpointer="no-legend" />
 225       <xi:include href="standard-options.xml" xpointer="json" />
 226     </variablelist>
 227   </refsect1>
 228
 229   <refsect1>
 230     <title>Exit status</title>
 231
 232     <para>On success, 0 is returned.</para>
 233   </refsect1>
 234
 235   <refsect1>
 236     <title>See Also</title>
 237     <para>
 238       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 239       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 240     </para>
 241   </refsect1>
 242
 243 </refentry>