]>
Commit | Line | Data |
---|---|---|
7a87fb61 LP |
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> | |
1f4f1666 | 22 | <refname>systemd-confext</refname> |
23 | <refname>systemd-confext.service</refname> | |
7a87fb61 LP |
24 | <refpurpose>Activates System Extension Images</refpurpose> |
25 | </refnamediv> | |
26 | ||
27 | <refsynopsisdiv> | |
28 | <cmdsynopsis> | |
29 | <command>systemd-sysext</command> | |
30 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
782e41ab | 31 | <arg choice="plain">COMMAND</arg> |
7a87fb61 LP |
32 | </cmdsynopsis> |
33 | ||
73e97bb0 | 34 | <para><filename>systemd-sysext.service</filename></para> |
7a87fb61 | 35 | |
1f4f1666 | 36 | <cmdsynopsis> |
37 | <command>systemd-confext</command> | |
38 | <arg choice="opt" rep="repeat">OPTIONS</arg> | |
39 | <arg choice="plain">COMMAND</arg> | |
40 | </cmdsynopsis> | |
41 | ||
73e97bb0 | 42 | <para><filename>systemd-confext.service</filename></para> |
7a87fb61 LP |
43 | </refsynopsisdiv> |
44 | ||
45 | <refsect1> | |
46 | <title>Description</title> | |
47 | ||
48 | <para><command>systemd-sysext</command> activates/deactivates system extension images. System extension | |
49 | images may – dynamically at runtime — extend the <filename>/usr/</filename> and | |
50 | <filename>/opt/</filename> directory hierarchies with additional files. This is particularly useful on | |
51 | immutable system images where a <filename>/usr/</filename> and/or <filename>/opt/</filename> hierarchy | |
52 | residing on a read-only file system shall be extended temporarily at runtime without making any | |
53 | persistent modifications.</para> | |
54 | ||
55 | <para>System extension images should contain files and directories similar in fashion to regular | |
56 | operating system tree. When one or more system extension images are activated, their | |
57 | <filename>/usr/</filename> and <filename>/opt/</filename> hierarchies are combined via | |
58 | <literal>overlayfs</literal> with the same hierarchies of the host OS, and the host | |
be0d27ee | 59 | <filename>/usr/</filename> and <filename>/opt/</filename> overmounted with it ("merging"). When they are |
7a87fb61 LP |
60 | deactivated, the mount point is disassembled — again revealing the unmodified original host version of |
61 | the hierarchy ("unmerging"). Merging thus makes the extension's resources suddenly appear below the | |
62 | <filename>/usr/</filename> and <filename>/opt/</filename> hierarchies as if they were included in the | |
63 | base OS image itself. Unmerging makes them disappear again, leaving in place only the files that were | |
64 | shipped with the base OS image itself.</para> | |
65 | ||
66 | <para>Files and directories contained in the extension images outside of the <filename>/usr/</filename> | |
67 | and <filename>/opt/</filename> hierarchies are <emphasis>not</emphasis> merged, and hence have no effect | |
60bb6caa LB |
68 | when included in a system extension image. In particular, files in the <filename>/etc/</filename> and |
69 | <filename>/var/</filename> included in a system extension image will <emphasis>not</emphasis> appear in | |
70 | the respective hierarchies after activation.</para> | |
7a87fb61 LP |
71 | |
72 | <para>System extension images are strictly read-only, and the host <filename>/usr/</filename> and | |
73 | <filename>/opt/</filename> hierarchies become read-only too while they are activated.</para> | |
74 | ||
75 | <para>System extensions are supposed to be purely additive, i.e. they are supposed to include only files | |
76 | that do not exist in the underlying basic OS image. However, the underlying mechanism (overlayfs) also | |
566e4b3a | 77 | allows overlaying or removing files, but it is recommended not to make use of this.</para> |
7a87fb61 LP |
78 | |
79 | <para>System extension images may be provided in the following formats:</para> | |
80 | ||
81 | <orderedlist> | |
82 | <listitem><para>Plain directories or btrfs subvolumes containing the OS tree</para></listitem> | |
83 | <listitem><para>Disk images with a GPT disk label, following the <ulink | |
db811444 | 84 | url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink></para></listitem> |
09e917ea LP |
85 | <listitem><para>Disk images lacking a partition table, with a naked Linux file system (e.g. erofs, |
86 | squashfs or ext4)</para></listitem> | |
7a87fb61 LP |
87 | </orderedlist> |
88 | ||
89 | <para>These image formats are the same ones that | |
90 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
01ae74c8 | 91 | supports via its <option>--directory=</option>/<option>--image=</option> switches and those that the |
7a87fb61 LP |
92 | service manager supports via <option>RootDirectory=</option>/<option>RootImage=</option>. Similar to |
93 | them they may optionally carry Verity authentication information.</para> | |
94 | ||
0d6e0ade | 95 | <para>System extensions are searched for in the directories |
de862276 LB |
96 | <filename>/etc/extensions/</filename>, <filename>/run/extensions/</filename> and |
97 | <filename>/var/lib/extensions/</filename>. The first two listed directories are not suitable for | |
7a87fb61 LP |
98 | carrying large binary images, however are still useful for carrying symlinks to them. The primary place |
99 | for installing system extensions is <filename>/var/lib/extensions/</filename>. Any directories found in | |
0d6e0ade | 100 | these search directories are considered directory based extension images; any files with the |
9ea81191 LP |
101 | <filename>.raw</filename> suffix are considered disk image based extension images. When invoked in the |
102 | initrd, the additional directory <filename>/.extra/sysext/</filename> is included in the directories that | |
103 | are searched for extension images. Note however, that by default a tighter image policy applies to images | |
104 | found there, though, see below. This directory is populated by | |
105 | <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> with | |
106 | extension images found in the system's EFI System Partition.</para> | |
7a87fb61 LP |
107 | |
108 | <para>During boot OS extension images are activated automatically, if the | |
109 | <filename>systemd-sysext.service</filename> is enabled. Note that this service runs only after the | |
6a15846d | 110 | underlying file systems where system extensions may be located have been mounted. This means they are not |
7a87fb61 LP |
111 | suitable for shipping resources that are processed by subsystems running in earliest boot. Specifically, |
112 | OS extension images are not suitable for shipping system services or | |
113 | <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
de6d05d7 | 114 | definitions. See the <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink> page |
8b9f0921 ZJS |
115 | for a simple mechanism for shipping system services in disk images, in a similar fashion to OS |
116 | extensions. Note the different isolation on these two mechanisms: while system extension directly extend | |
117 | the underlying OS image with additional files that appear in a way very similar to as if they were | |
118 | shipped in the OS image itself and thus imply no security isolation, portable services imply service | |
119 | level sandboxing in one way or another. The <filename>systemd-sysext.service</filename> service is | |
120 | guaranteed to finish start-up before <filename>basic.target</filename> is reached; i.e. at the time | |
121 | regular services initialize (those which do not use <varname>DefaultDependencies=no</varname>), the files | |
122 | and directories system extensions provide are available in <filename>/usr/</filename> and | |
123 | <filename>/opt/</filename> and may be accessed.</para> | |
7a87fb61 LP |
124 | |
125 | <para>Note that there is no concept of enabling/disabling installed system extension images: all | |
1abe15fe KL |
126 | installed extension images are automatically activated at boot. However, you can place an empty directory |
127 | named like the extension (no <filename>.raw</filename>) in <filename>/etc/extensions/</filename> to "mask" | |
128 | an extension with the same name in a system folder with lower precedence.</para> | |
7a87fb61 | 129 | |
60bb6caa | 130 | <para>A simple mechanism for version compatibility is enforced: a system extension image must carry a |
bf63dadb | 131 | <filename>/usr/lib/extension-release.d/extension-release.<replaceable>NAME</replaceable></filename> |
60bb6caa | 132 | file, which must match its image name, that is compared with the host <filename>os-release</filename> |
ab4d43c5 KL |
133 | file: the contained <varname>ID=</varname> fields have to match unless <literal>_any</literal> is set |
134 | for the extension. If the extension <varname>ID=</varname> is not <literal>_any</literal>, the | |
135 | <varname>SYSEXT_LEVEL=</varname> field (if defined) has to match. If the latter is not defined, the | |
16c1ca0d KL |
136 | <varname>VERSION_ID=</varname> field has to match instead. If the extension defines the |
137 | <varname>ARCHITECTURE=</varname> field and the value is not <literal>_any</literal> it has to match the kernel's | |
138 | architecture reported by <citerefentry><refentrytitle>uname</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
139 | but the used architecture identifiers are the same as for <varname>ConditionArchitecture=</varname> | |
140 | described in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. | |
41712cd1 MT |
141 | <varname>EXTENSION_RELOAD_MANAGER=</varname> can be set to 1 if the extension requires a service manager reload after application |
142 | of the extension. Note that the for the reasons mentioned earlier: | |
143 | <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink> remain | |
144 | the recommended way to ship system services. | |
145 | ||
16c1ca0d KL |
146 | System extensions should not ship a <filename>/usr/lib/os-release</filename> file (as that would be merged |
147 | into the host <filename>/usr/</filename> tree, overriding the host OS version data, which is not desirable). | |
148 | The <filename>extension-release</filename> file follows the same format and semantics, and carries the same | |
60bb6caa LB |
149 | content, as the <filename>os-release</filename> file of the OS, but it describes the resources carried |
150 | in the extension image.</para> | |
1f4f1666 | 151 | |
152 | <para>The <command>systemd-confext</command> concept follows the same principle as the | |
153 | <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
154 | functionality but instead of working on <filename>/usr</filename> and <filename>/opt</filename>, | |
155 | <command>confext</command> will extend only <filename>/etc</filename>. Files and directories contained | |
156 | in the confext images outside of the <filename>/etc/</filename> hierarchy are <emphasis>not</emphasis> | |
157 | merged, and hence have no effect when included in the image. Formats for these images are of the | |
0607a9f9 LB |
158 | same as sysext images. The merged hierarchy will be mounted with <literal>nosuid</literal> and |
159 | (if not disabled via <option>--noexec=false</option>) <literal>noexec</literal>.</para> | |
1f4f1666 | 160 | |
161 | <para>Confexts are looked for in the directories <filename>/run/confexts/</filename>, | |
162 | <filename>/var/lib/confexts/</filename>, <filename>/usr/lib/confexts/</filename> and | |
79567763 AAF |
163 | <filename>/usr/local/lib/confexts/</filename>. The first listed directory is not suitable for |
164 | carrying large binary images, however is still useful for carrying symlinks to them. The primary place | |
165 | for installing configuration extensions is <filename>/var/lib/confexts/</filename>. Any directories found | |
166 | in these search directories are considered directory based confext images; any files with the | |
1f4f1666 | 167 | <filename>.raw</filename> suffix are considered disk image based confext images.</para> |
168 | ||
169 | <para>Again, just like sysext images, the confext images will contain a | |
bf63dadb ZJS |
170 | <filename>/etc/extension-release.d/extension-release.<replaceable>NAME</replaceable></filename> |
171 | file, which must match the image name (with the usual escape hatch of | |
172 | the <varname>user.extension-release.strict</varname> | |
173 | <citerefentry project='man-pages'><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry>), | |
174 | and again with content being one or more of <varname>ID=</varname>, <varname>VERSION_ID=</varname>, and | |
175 | <varname>CONFEXT_LEVEL</varname>. Confext images will then be checked and matched against the base OS | |
176 | layer.</para> | |
7a87fb61 LP |
177 | </refsect1> |
178 | ||
179 | <refsect1> | |
180 | <title>Uses</title> | |
181 | ||
182 | <para>The primary use case for system images are immutable environments where debugging and development | |
be0d27ee ZJS |
183 | tools shall optionally be made available, but not included in the immutable base OS image itself (e.g. |
184 | <citerefentry project='man-pages'><refentrytitle>strace</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
185 | and | |
186 | <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
187 | shall be an optionally installable addition in order to make debugging/development easier). System | |
188 | extension images should not be misunderstood as a generic software packaging framework, as no dependency | |
189 | scheme is available: system extensions should carry all files they need themselves, except for those | |
190 | already shipped in the underlying host system image. Typically, system extension images are built at the | |
191 | same time as the base OS image — within the same build system.</para> | |
7a87fb61 LP |
192 | |
193 | <para>Another use case for the system extension concept is temporarily overriding OS supplied resources | |
194 | with newer ones, for example to install a locally compiled development version of some low-level | |
195 | component over the immutable OS image without doing a full OS rebuild or modifying the nominally | |
196 | immutable image. (e.g. "install" a locally built package with <command>DESTDIR=/var/lib/extensions/mytest | |
301265ea | 197 | make install && systemd-sysext refresh</command>, making it available in |
7a87fb61 LP |
198 | <filename>/usr/</filename> as if it was installed in the OS image itself.) This case works regardless if |
199 | the underlying host <filename>/usr/</filename> is managed as immutable disk image or is a traditional | |
200 | package manager controlled (i.e. writable) tree.</para> | |
1f4f1666 | 201 | |
202 | <para>For the confext case, the OSConfig project aims to perform runtime reconfiguration of OS services. | |
203 | Sometimes, there is a need to swap certain configuration parameter values or restart only a specific | |
204 | service without deployment of new code or a complete OS deployment. In other words, we want to be able | |
205 | to tie the most frequently configured options to runtime updateable flags that can be changed without a | |
206 | system reboot. This will help reduce servicing times when there is a need for changing the OS configuration.</para></refsect1> | |
7a87fb61 LP |
207 | |
208 | <refsect1> | |
209 | <title>Commands</title> | |
210 | ||
1f4f1666 | 211 | <para>The following commands are understood by both the sysext and confext concepts:</para> |
7a87fb61 LP |
212 | |
213 | <variablelist> | |
214 | <varlistentry> | |
301265ea LP |
215 | <term><option>status</option></term> |
216 | ||
217 | <listitem><para>When invoked without any command verb, or when <option>status</option> is specified | |
1f4f1666 | 218 | the current merge status is shown, separately (for both <filename>/usr/</filename> and |
ec07c3c8 AK |
219 | <filename>/opt/</filename> of sysext and for <filename>/etc/</filename> of confext).</para> |
220 | ||
221 | <xi:include href="version-info.xml" xpointer="v248"/></listitem> | |
301265ea LP |
222 | </varlistentry> |
223 | ||
224 | <varlistentry> | |
225 | <term><option>merge</option></term> | |
7a87fb61 LP |
226 | <listitem><para>Merges all currently installed system extension images into |
227 | <filename>/usr/</filename> and <filename>/opt/</filename>, by overmounting these hierarchies with an | |
228 | <literal>overlayfs</literal> file system combining the underlying hierarchies with those included in | |
1f4f1666 | 229 | the extension images. This command will fail if the hierarchies are already merged. For confext, the merge |
ec07c3c8 AK |
230 | happens into the <filename>/etc/</filename> directory instead.</para> |
231 | ||
232 | <xi:include href="version-info.xml" xpointer="v248"/></listitem> | |
7a87fb61 LP |
233 | </varlistentry> |
234 | ||
235 | <varlistentry> | |
301265ea | 236 | <term><option>unmerge</option></term> |
7a87fb61 | 237 | <listitem><para>Unmerges all currently installed system extension images from |
1f4f1666 | 238 | <filename>/usr/</filename> and <filename>/opt/</filename> for sysext and <filename>/etc/</filename>, |
239 | for confext, by unmounting the <literal>overlayfs</literal> file systems created by <option>merge</option> | |
ec07c3c8 AK |
240 | prior.</para> |
241 | ||
242 | <xi:include href="version-info.xml" xpointer="v248"/></listitem> | |
7a87fb61 LP |
243 | </varlistentry> |
244 | ||
245 | <varlistentry> | |
301265ea LP |
246 | <term><option>refresh</option></term> |
247 | <listitem><para>A combination of <option>unmerge</option> and <option>merge</option>: if already | |
7a87fb61 LP |
248 | mounted the existing <literal>overlayfs</literal> instance is unmounted temporarily, and then |
249 | replaced by a new version. This command is useful after installing/removing system extension images, | |
250 | in order to update the <literal>overlayfs</literal> file system accordingly. If no system extensions | |
1f4f1666 | 251 | are installed when this command is executed, the equivalent of <option>unmerge</option> is executed, |
252 | without establishing any new <literal>overlayfs</literal> instance. | |
253 | Note that currently there's a brief moment where neither the old nor the new <literal>overlayfs</literal> | |
254 | file system is mounted. This implies that all resources supplied by a system extension will briefly | |
ec07c3c8 AK |
255 | disappear — even if it exists continuously during the refresh operation.</para> |
256 | ||
257 | <xi:include href="version-info.xml" xpointer="v248"/></listitem> | |
7a87fb61 LP |
258 | </varlistentry> |
259 | ||
260 | <varlistentry> | |
301265ea | 261 | <term><option>list</option></term> |
7a87fb61 | 262 | |
ec07c3c8 AK |
263 | <listitem><para>A brief list of installed extension images is shown.</para> |
264 | ||
265 | <xi:include href="version-info.xml" xpointer="v248"/></listitem> | |
7a87fb61 LP |
266 | </varlistentry> |
267 | ||
268 | <xi:include href="standard-options.xml" xpointer="help" /> | |
269 | <xi:include href="standard-options.xml" xpointer="version" /> | |
270 | </variablelist> | |
7a87fb61 LP |
271 | </refsect1> |
272 | ||
273 | <refsect1> | |
274 | <title>Options</title> | |
275 | ||
276 | <variablelist> | |
277 | <varlistentry> | |
278 | <term><option>--root=</option></term> | |
279 | ||
280 | <listitem><para>Operate relative to the specified root directory, i.e. establish the | |
281 | <literal>overlayfs</literal> mount not on the top-level host <filename>/usr/</filename> and | |
1f4f1666 | 282 | <filename>/opt/</filename> hierarchies for sysext or <filename>/etc/</filename> for confext, |
ec07c3c8 AK |
283 | but below some specified root directory.</para> |
284 | ||
285 | <xi:include href="version-info.xml" xpointer="v248"/></listitem> | |
7a87fb61 LP |
286 | </varlistentry> |
287 | ||
301265ea LP |
288 | <varlistentry> |
289 | <term><option>--force</option></term> | |
290 | ||
291 | <listitem><para>When merging system extensions into <filename>/usr/</filename> and | |
1f4f1666 | 292 | <filename>/opt/</filename> for sysext and <filename>/etc/</filename> for confext, |
293 | ignore version incompatibilities, i.e. force merging regardless of | |
ec07c3c8 AK |
294 | whether the version information included in the images matches the host or not.</para> |
295 | ||
296 | <xi:include href="version-info.xml" xpointer="v248"/></listitem> | |
301265ea LP |
297 | </varlistentry> |
298 | ||
9ea81191 LP |
299 | <varlistentry> |
300 | <term><option>--image-policy=<replaceable>policy</replaceable></option></term> | |
301 | ||
302 | <listitem><para>Takes an image policy string as argument, as per | |
303 | <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The | |
304 | policy is enforced when operating on system extension disk images. If not specified defaults to | |
4f25844a LP |
305 | <literal>root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent</literal> |
306 | for system extensions, i.e. only the root and <filename>/usr/</filename> file systems in the image | |
307 | are used. For configuration extensions defaults to | |
308 | <literal>root=verity+signed+encrypted+unprotected+absent</literal>. When run in the initrd and | |
309 | operating on a system extension image stored in the <filename>/.extra/sysext/</filename> directory a | |
310 | slightly stricter policy is used by default: <literal>root=signed+absent:usr=signed+absent</literal>, | |
ec07c3c8 AK |
311 | see above for details.</para> |
312 | ||
313 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
9ea81191 LP |
314 | </varlistentry> |
315 | ||
0607a9f9 LB |
316 | <varlistentry> |
317 | <term><option>--noexec=</option><replaceable>BOOL</replaceable></term> | |
318 | ||
319 | <listitem><para>When merging configuration extensions into <filename>/etc/</filename> the | |
320 | <literal>MS_NOEXEC</literal> mount flag is used by default. This option can be used to disable | |
ec07c3c8 AK |
321 | it.</para> |
322 | ||
323 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
0607a9f9 LB |
324 | </varlistentry> |
325 | ||
41712cd1 MT |
326 | <varlistentry> |
327 | <term><option>--no-reload</option></term> | |
328 | ||
329 | <listitem> | |
330 | <para>When used with <command>merge</command>, | |
331 | <command>unmerge</command> or <command>refresh</command>, do not reload daemon | |
332 | after executing the changes even if an extension that is applied requires a reload via the | |
333 | <varname>EXTENSION_RELOAD_MANAGER=</varname> set to 1.</para> | |
ec07c3c8 AK |
334 | |
335 | <xi:include href="version-info.xml" xpointer="v255"/> | |
41712cd1 MT |
336 | </listitem> |
337 | </varlistentry> | |
338 | ||
7a87fb61 | 339 | <xi:include href="standard-options.xml" xpointer="no-pager" /> |
16a36b56 | 340 | <xi:include href="standard-options.xml" xpointer="no-legend" /> |
8d0d1a30 | 341 | <xi:include href="standard-options.xml" xpointer="json" /> |
7a87fb61 LP |
342 | </variablelist> |
343 | </refsect1> | |
344 | ||
345 | <refsect1> | |
346 | <title>Exit status</title> | |
347 | ||
348 | <para>On success, 0 is returned.</para> | |
349 | </refsect1> | |
350 | ||
351 | <refsect1> | |
352 | <title>See Also</title> | |
353 | <para> | |
354 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
9ea81191 LP |
355 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
356 | <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
7a87fb61 LP |
357 | </para> |
358 | </refsect1> | |
359 | ||
360 | </refentry> |