1SYSTEMD-SYSEXT(8)               systemd-sysext               SYSTEMD-SYSEXT(8)
2
3
4

NAME

6       systemd-sysext, systemd-sysext.service - Activates System Extension
7       Images
8

SYNOPSIS

10       systemd-sysext [OPTIONS...]
11
12       systemd-sysext.service
13

DESCRIPTION

15       systemd-sysext activates/deactivates system extension images. System
16       extension images may – dynamically at runtime — extend the /usr/ and
17       /opt/ directory hierarchies with additional files. This is particularly
18       useful on immutable system images where a /usr/ and/or /opt/ hierarchy
19       residing on a read-only file system shall be extended temporarily at
20       runtime without making any persistent modifications.
21
22       System extension images should contain files and directories similar in
23       fashion to regular operating system tree. When one or more system
24       extension images are activated, their /usr/ and /opt/ hierarchies are
25       combined via "overlayfs" with the same hierarchies of the host OS, and
26       the host /usr/ and /opt/ overmounted with it ("merging"). When they are
27       deactivated, the mount point is disassembled — again revealing the
28       unmodified original host version of the hierarchy ("unmerging").
29       Merging thus makes the extension's resources suddenly appear below the
30       /usr/ and /opt/ hierarchies as if they were included in the base OS
31       image itself. Unmerging makes them disappear again, leaving in place
32       only the files that were shipped with the base OS image itself.
33
34       Files and directories contained in the extension images outside of the
35       /usr/ and /opt/ hierarchies are not merged, and hence have no effect
36       when included in a system extension image. In particular, files in the
37       /etc/ and /var/ included in a system extension image will not appear in
38       the respective hierarchies after activation.
39
40       System extension images are strictly read-only, and the host /usr/ and
41       /opt/ hierarchies become read-only too while they are activated.
42
43       System extensions are supposed to be purely additive, i.e. they are
44       supposed to include only files that do not exist in the underlying
45       basic OS image. However, the underlying mechanism (overlayfs) also
46       allows removing files, but it is recommended not to make use of this.
47
48       System extension images may be provided in the following formats:
49
50        1. Plain directories or btrfs subvolumes containing the OS tree
51
52        2. Disk images with a GPT disk label, following the Discoverable
53           Partitions Specification[1]
54
55        3. Disk images lacking a partition table, with a naked Linux file
56           system (e.g. squashfs or ext4)
57
58       These image formats are the same ones that systemd-nspawn(1) supports
59       via it's --directory=/--image= switches and those that the service
60       manager supports via RootDirectory=/RootImage=. Similar to them they
61       may optionally carry Verity authentication information.
62
63       System extensions are automatically looked for in the directories
64       /etc/extensions/, /run/extensions/, /var/lib/extensions/,
65       /usr/lib/extensions/ and /usr/local/lib/extensions/. The first two
66       listed directories are not suitable for carrying large binary images,
67       however are still useful for carrying symlinks to them. The primary
68       place for installing system extensions is /var/lib/extensions/. Any
69       directories found in these search directories are considered directory
70       based extension images, any files with the .raw suffix are considered
71       disk image based extension images.
72
73       During boot OS extension images are activated automatically, if the
74       systemd-sysext.service is enabled. Note that this service runs only
75       after the underlying file systems where system extensions may be
76       located have been mounted. This means they are not suitable for
77       shipping resources that are processed by subsystems running in earliest
78       boot. Specifically, OS extension images are not suitable for shipping
79       system services or systemd-sysusers(8) definitions. See Portable
80       Services[2] for a simple mechanism for shipping system services in disk
81       images, in a similar fashion to OS extensions. Note the different
82       isolation on these two mechanisms: while system extension directly
83       extend the underlying OS image with additional files that appear in a
84       way very similar to as if they were shipped in the OS image itself and
85       thus imply no security isolation, portable services imply service level
86       sandboxing in one way or another. The systemd-sysext.service service is
87       guaranteed to finish start-up before basic.target is reached; i.e. at
88       the time regular services initialize (those which do not use
89       DefaultDependencies=no), the files and directories system extensions
90       provide are available in /usr/ and /opt/ and may be accessed.
91
92       Note that there is no concept of enabling/disabling installed system
93       extension images: all installed extension images are automatically
94       activated at boot.
95
96       A simple mechanism for version compatibility is enforced: a system
97       extension image must carry a
98       /usr/lib/extension-release.d/extension-release.$name file, which must
99       match its image name, that is compared with the host os-release file:
100       the contained ID= fields have to match, as well as the SYSEXT_LEVEL=
101       field (if defined). If the latter is not defined, the VERSION_ID= field
102       has to match instead. System extensions should not ship a
103       /usr/lib/os-release file (as that would be merged into the host /usr/
104       tree, overriding the host OS version data, which is not desirable). The
105       extension-release file follows the same format and semantics, and
106       carries the same content, as the os-release file of the OS, but it
107       describes the resources carried in the extension image.
108

USES

110       The primary use case for system images are immutable environments where
111       debugging and development tools shall optionally be made available, but
112       not included in the immutable base OS image itself (e.g.  strace(1) and
113       gdb(1) shall be an optionally installable addition in order to make
114       debugging/development easier). System extension images should not be
115       misunderstood as a generic software packaging framework, as no
116       dependency scheme is available: system extensions should carry all
117       files they need themselves, except for those already shipped in the
118       underlying host system image. Typically, system extension images are
119       built at the same time as the base OS image — within the same build
120       system.
121
122       Another use case for the system extension concept is temporarily
123       overriding OS supplied resources with newer ones, for example to
124       install a locally compiled development version of some low-level
125       component over the immutable OS image without doing a full OS rebuild
126       or modifying the nominally immutable image. (e.g. "install" a locally
127       built package with DESTDIR=/var/lib/extensions/mytest make install &&
128       systemd-sysext refresh, making it available in /usr/ as if it was
129       installed in the OS image itself.) This case works regardless if the
130       underlying host /usr/ is managed as immutable disk image or is a
131       traditional package manager controlled (i.e. writable) tree.
132

COMMANDS

134       The following commands are understood:
135
136       status
137           When invoked without any command verb, or when status is specified
138           the current merge status is shown, separately for both /usr/ and
139           /opt/.
140
141       merge
142           Merges all currently installed system extension images into /usr/
143           and /opt/, by overmounting these hierarchies with an "overlayfs"
144           file system combining the underlying hierarchies with those
145           included in the extension images. This command will fail if the
146           hierarchies are already merged.
147
148       unmerge
149           Unmerges all currently installed system extension images from /usr/
150           and /opt/, by unmounting the "overlayfs" file systems created by
151           merge prior.
152
153       refresh
154           A combination of unmerge and merge: if already mounted the existing
155           "overlayfs" instance is unmounted temporarily, and then replaced by
156           a new version. This command is useful after installing/removing
157           system extension images, in order to update the "overlayfs" file
158           system accordingly. If no system extensions are installed when this
159           command is executed, the equivalent of unmerge is executed, without
160           establishing any new "overlayfs" instance. Note that currently
161           there's a brief moment where neither the old nor the new
162           "overlayfs" file system is mounted. This implies that all resources
163           supplied by a system extension will briefly disappear — even if it
164           exists continuously during the refresh operation.
165
166       list
167           A brief list of installed extension images is shown.
168
169       -h, --help
170           Print a short help text and exit.
171
172       --version
173           Print a short version string and exit.
174

OPTIONS

176       --root=
177           Operate relative to the specified root directory, i.e. establish
178           the "overlayfs" mount not on the top-level host /usr/ and /opt/
179           hierarchies, but below some specified root directory.
180
181       --force
182           When merging system extensions into /usr/ and /opt/, ignore version
183           incompatibilities, i.e. force merging regardless of whether the
184           version information included in the extension images matches the
185           host or not.
186
187       --no-pager
188           Do not pipe output into a pager.
189
190       --no-legend
191           Do not print the legend, i.e. column headers and the footer with
192           hints.
193
194       --json=MODE
195           Shows output formatted as JSON. Expects one of "short" (for the
196           shortest possible output without any redundant whitespace or line
197           breaks), "pretty" (for a pretty version of the same, with
198           indentation and line breaks) or "off" (to turn off JSON output, the
199           default).
200

EXIT STATUS

202       On success, 0 is returned.
203

SEE ALSO

205       systemd(1), systemd-nspawn(1)
206

NOTES

208        1. Discoverable Partitions Specification
209           https://systemd.io/DISCOVERABLE_PARTITIONS
210
211        2. Portable Services
212           https://systemd.io/PORTABLE_SERVICES
213
214
215
216systemd 250                                                  SYSTEMD-SYSEXT(8)
Impressum