Debian Codegraph @

upstream/debian-unstable/man8/systemd-sysext.8

raw
1 '\" t
2 .TH "SYSTEMD\-SYSEXT" "8" "" "systemd 261~rc3" "systemd-sysext"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-sysext, systemd-sysext.service, systemd-sysext-initrd.service, systemd-sysext-sysroot.service, systemd-confext, systemd-confext.service, systemd-confext-initrd.service, systemd-confext-sysroot.service \- Activates System Extension Images
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-sysext\fR\ 'u
26 \fBsystemd\-sysext\fR [OPTIONS...] COMMAND
27 .PP
28 systemd\-sysext\&.service
29 .HP \w'\fBsystemd\-confext\fR\ 'u
30 \fBsystemd\-confext\fR [OPTIONS...] COMMAND
31 .PP
32 systemd\-confext\&.service
33 .SH "DESCRIPTION"
34 .PP
35 \fBsystemd\-sysext\fR
36 activates/deactivates system extension images\&. System extension images may \(en dynamically at runtime \(em extend the
37 /usr/
38 and
39 /opt/
40 directory hierarchies with additional files\&. This is particularly useful on immutable system images where a
41 /usr/
42 and/or
43 /opt/
44 hierarchy residing on a read\-only file system shall be extended temporarily at runtime without making any persistent modifications\&.
45 .PP
46 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
47 /usr/
48 and
49 /opt/
50 hierarchies are combined via
51 "overlayfs"
52 with the same hierarchies of the host OS, and the host
53 /usr/
54 and
55 /opt/
56 overmounted with it ("merging")\&. When they are deactivated, the mount point is disassembled \(em again revealing the unmodified original host version of the hierarchy ("unmerging")\&. Merging thus makes the extension\*(Aqs resources suddenly appear below the
57 /usr/
58 and
59 /opt/
60 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\&.
61 .PP
62 Files and directories contained in the extension images outside of the
63 /usr/
64 and
65 /opt/
66 hierarchies are
67 \fInot\fR
68 merged, and hence have no effect when included in a system extension image\&. In particular, files in the
69 /etc/
70 and
71 /var/
72 included in a system extension image will
73 \fInot\fR
74 appear in the respective hierarchies after activation\&.
75 .PP
76 System extension images are strictly read\-only by default\&. On mutable host file systems,
77 /usr/
78 and
79 /opt/
80 hierarchies become read\-only while extensions are merged, unless mutability is enabled\&. Mutability may be enabled via the
81 \fB\-\-mutable=\fR
82 option and the
83 \fIMutable=\fR
84 option in the configuration file; see "Mutability" below for more information\&.
85 .PP
86 Various command options can be configured globally via configuration files\&. See
87 \fBsysext.conf\fR(5)
88 for details\&.
89 .PP
90 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\&.
91 .PP
92 System extension images may be provided in the following formats:
93 .sp
94 .RS 4
95 .ie n \{\
96 \h'-04' 1.\h'+01'\c
97 .\}
98 .el \{\
99 .sp -1
100 .IP " 1." 4.2
101 .\}
102 Plain directories or btrfs subvolumes containing the OS tree
103 .RE
104 .sp
105 .RS 4
106 .ie n \{\
107 \h'-04' 2.\h'+01'\c
108 .\}
109 .el \{\
110 .sp -1
111 .IP " 2." 4.2
112 .\}
113 Disk images with a GPT disk label, following the
114 \m[blue]\fBUAPI\&.2 Discoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2
115 .RE
116 .sp
117 .RS 4
118 .ie n \{\
119 \h'-04' 3.\h'+01'\c
120 .\}
121 .el \{\
122 .sp -1
123 .IP " 3." 4.2
124 .\}
125 Disk images lacking a partition table, with a naked Linux file system (e\&.g\&. erofs, squashfs or ext4)
126 .RE
127 .PP
128 These image formats are the same ones that
129 \fBsystemd-nspawn\fR(1)
130 supports via its
131 \fB\-\-directory=\fR/\fB\-\-image=\fR
132 switches and those that the service manager supports via
133 \fBRootDirectory=\fR/\fBRootImage=\fR\&. Similar to them they may optionally carry Verity authentication information\&.
134 .PP
135 System extensions are searched for in the directories
136 /etc/extensions/,
137 /run/extensions/
138 and
139 /var/lib/extensions/\&. 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
140 /var/lib/extensions/\&. Any directories found in these search directories are considered directory based extension images; any files with the
141 \&.raw
142 suffix are considered disk image based extension images\&. When invoked in the initrd, the additional directory
143 /\&.extra/sysext/
144 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
145 \fBsystemd-stub\fR(7)
146 with extension images found in the system\*(Aqs EFI System Partition\&.
147 .PP
148 During boot, system and configuration extension images are activated automatically if the
149 systemd\-sysext\&.service
150 and
151 systemd\-confext\&.service
152 services are enabled\&. Note that these services run only after the underlying file systems where system and configuration extensions may be located have been mounted\&. To make it possible to ship resources that are processed by subsystems running in the earliest boot stages (for example, system services or
153 \fBsystemd-sysusers\fR(8)
154 definitions), the
155 systemd\-sysext\-sysroot\&.service
156 and
157 systemd\-confext\-sysroot\&.service
158 initrd services are provided\&. Currently, these services cannot be used to merge system extensions from
159 /sysroot/var/lib/extensions/
160 and configuration extensions from
161 /sysroot/var/lib/confexts/
162 when the
163 /var/
164 partition is split off\&. These extensions are later merged by the
165 systemd\-sysext\&.service
166 and
167 systemd\-confext\&.service
168 services during the main OS boot process\&.
169 .PP
170 Also, see the
171 \m[blue]\fBPortable Services\fR\m[]\&\s-2\u[2]\d\s+2
172 page for a simple mechanism for shipping system services in disk images, in a similar fashion to OS extensions\&. Note the differences in isolation between these two mechanisms: while system extensions directly extend the underlying OS image with additional files that appear 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\&.
173 .PP
174 The
175 systemd\-sysext\&.service
176 and
177 systemd\-confext\&.service
178 services are guaranteed to finish start\-up before
179 basic\&.target
180 is reached; i\&.e\&., by the time regular services initialize (those which do not use
181 \fIDefaultDependencies=no\fR), the files and directories provided by system and configuration extensions are available in
182 /usr/,
183 /opt/, and
184 /etc/
185 and may be accessed\&.
186 .PP
187 System and configuration extensions can also be used to extend the initrd, and the
188 systemd\-sysext\-initrd\&.service
189 and
190 systemd\-confext\-initrd\&.service
191 initrd services are provided\&. Note that some limitations apply: resources that are used in the earliest boot stages of the initrd (e\&.g\&. system services) cannot be updated\&.
192 .PP
193 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
194 \&.raw) in
195 /etc/extensions/
196 to "mask" an extension with the same name in a system folder with lower precedence\&. It is also possible to disable automatic merging altogether using the
197 \fIrd\&.systemd\&.sysext=\fR,
198 \fIrd\&.systemd\&.confext=\fR,
199 \fIsystemd\&.sysext=\fR, and
200 \fIsystemd\&.confext=\fR
201 kernel command line options\&. Note that
202 systemd\-sysext\-sysroot\&.service
203 and
204 systemd\-confext\-sysroot\&.service
205 are controlled by the
206 \fIsystemd\&.sysext=\fR
207 and
208 \fIsystemd\&.confext=\fR
209 options, as these services merge system and configuration extensions for the main system, not for the initrd\&.
210 .PP
211 A simple mechanism for version compatibility is enforced: a system extension image must carry a
212 /usr/lib/extension\-release\&.d/extension\-release\&.\fINAME\fR
213 file, which must match its image name, that is compared with the host
214 os\-release
215 file: the contained
216 \fIID=\fR
217 fields have to match unless
218 "_any"
219 is set for the extension\&. If the extension
220 \fIID=\fR
221 is not
222 "_any", the
223 \fISYSEXT_LEVEL=\fR
224 field (if defined) has to match\&. If the latter is not defined, the
225 \fIVERSION_ID=\fR
226 field has to match instead\&. If the extension defines the
227 \fIARCHITECTURE=\fR
228 field and the value is not
229 "_any"
230 it has to match the kernel\*(Aqs architecture reported by
231 \fBuname\fR(2)
232 but the used architecture identifiers are the same as for
233 \fIConditionArchitecture=\fR
234 described in
235 \fBsystemd.unit\fR(5)\&.
236 \fIEXTENSION_RELOAD_MANAGER=\fR
237 can be set to 1 if the extension requires a service manager reload after application of the extension\&. Note that for the reasons mentioned earlier,
238 \m[blue]\fBPortable Services\fR\m[]\&\s-2\u[2]\d\s+2
239 remain the recommended way to ship system services\&. System extensions should not ship a
240 /usr/lib/os\-release
241 file (as that would be merged into the host
242 /usr/
243 tree, overriding the host OS version data, which is not desirable)\&. The
244 extension\-release
245 file follows the same format and semantics, and carries the same content, as the
246 os\-release
247 file of the OS, but it describes the resources carried in the extension image\&.
248 .PP
249 The
250 \fBsystemd\-confext\fR
251 concept follows the same principle as the
252 \fBsystemd-sysext\fR(8)
253 functionality but instead of working on
254 /usr
255 and
256 /opt,
257 \fBconfext\fR
258 will extend only
259 /etc\&. Files and directories contained in the confext images outside of the
260 /etc/
261 hierarchy are
262 \fInot\fR
263 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
264 "nosuid"
265 and (if not disabled via
266 \fB\-\-noexec=false\fR)
267 "noexec"\&.
268 .PP
269 Just like sysexts, confexts are strictly read\-only by default\&. Merging confexts on mutable host file systems will result in
270 /etc/
271 becoming read\-only\&. As with sysexts, mutability can be enabled via the
272 \fB\-\-mutable=\fR
273 option\&. Refer to "Mutability" below for more information\&.
274 .PP
275 Confexts are looked for in the directories
276 /run/confexts/,
277 /var/lib/confexts/,
278 /usr/lib/confexts/
279 and
280 /usr/local/lib/confexts/\&. 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
281 /var/lib/confexts/\&. Any directories found in these search directories are considered directory based confext images; any files with the
282 \&.raw
283 suffix are considered disk image based confext images\&.
284 .PP
285 Again, just like sysext images, the confext images will contain a
286 /etc/extension\-release\&.d/extension\-release\&.\fINAME\fR
287 file, which must match the image name (with the usual escape hatch of the
288 \fIuser\&.extension\-release\&.strict\fR
289 \fBxattr\fR(7)), and again with content being one or more of
290 \fIID=\fR,
291 \fIVERSION_ID=\fR, and
292 \fICONFEXT_LEVEL\fR\&. Confext images will then be checked and matched against the base OS layer\&.
293 .SH "USES"
294 .PP
295 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\&.
296 \fBstrace\fR(1)
297 and
298 \fBgdb\fR(1)
299 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 \(em within the same build system\&.
300 .PP
301 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
302 \fBDESTDIR=/var/lib/extensions/mytest make install && systemd\-sysext refresh\fR, making it available in
303 /usr/
304 as if it was installed in the OS image itself\&.) This case works regardless of whether the underlying host
305 /usr/
306 is managed as immutable disk image or is a traditional package manager controlled (i\&.e\&. writable) tree\&.
307 .PP
308 With
309 \fBsystemd\-confext\fR
310 one can 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\&. It also provides a reliable tool for managing configuration because all old configuration files disappear when the
311 \fBsystemd\-confext\fR
312 image is removed\&.
313 .SH "MUTABILITY"
314 .PP
315 By default, merging system extensions on mutable host file systems will render
316 /usr/
317 and
318 /opt/
319 hierarchies read\-only\&. Merging configuration extensions will have the same effect on
320 /etc/\&. Mutable mode allows writes to these locations when extensions are merged\&.
321 .PP
322 The following modes are supported:
323 .sp
324 .RS 4
325 .ie n \{\
326 \h'-04' 1.\h'+01'\c
327 .\}
328 .el \{\
329 .sp -1
330 .IP " 1." 4.2
331 .\}
332 \fBdisabled\fR: Force immutable mode even if write routing directories exist below
333 /var/lib/extensions\&.mutable/\&. This is the default\&.
334 .RE
335 .sp
336 .RS 4
337 .ie n \{\
338 \h'-04' 2.\h'+01'\c
339 .\}
340 .el \{\
341 .sp -1
342 .IP " 2." 4.2
343 .\}
344 \fBauto\fR: Automatic mode\&. Mutability is disabled by default and only enabled if a corresponding write routing directory exists below
345 /var/lib/extensions\&.mutable/\&.
346 .RE
347 .sp
348 .RS 4
349 .ie n \{\
350 \h'-04' 3.\h'+01'\c
351 .\}
352 .el \{\
353 .sp -1
354 .IP " 3." 4.2
355 .\}
356 \fBenabled\fR: Force mutable mode and automatically create write routing directories below
357 /var/lib/extensions\&.mutable/
358 when required\&.
359 .RE
360 .sp
361 .RS 4
362 .ie n \{\
363 \h'-04' 4.\h'+01'\c
364 .\}
365 .el \{\
366 .sp -1
367 .IP " 4." 4.2
368 .\}
369 \fBimport\fR: Force immutable mode like
370 \fBdisabled\fR
371 above, but merge the contents of directories below
372 /var/lib/extensions\&.mutable/
373 into the host file system\&.
374 .RE
375 .sp
376 .RS 4
377 .ie n \{\
378 \h'-04' 5.\h'+01'\c
379 .\}
380 .el \{\
381 .sp -1
382 .IP " 5." 4.2
383 .\}
384 \fBephemeral\fR: Force mutable mode like
385 \fBenabled\fR
386 above, but instead of using write routing directory below
387 /var/lib/extensions\&.mutable/,
388 \fBsystemd\-sysext\fR
389 will use empty ephemeral directories\&. This means that the modifications made in the merged hierarchies will be gone when the hierarchies are unmerged\&.
390 .RE
391 .sp
392 .RS 4
393 .ie n \{\
394 \h'-04' 6.\h'+01'\c
395 .\}
396 .el \{\
397 .sp -1
398 .IP " 6." 4.2
399 .\}
400 \fBephemeral\-import\fR: Force mutable mode like
401 \fBephemeral\fR
402 above, but instead of ignoring the contents of write routing directories under
403 /var/lib/extensions\&.mutable/, merge them into the host file system, like
404 \fBimport\fR
405 does\&.
406 .RE
407 .sp
408 See "Options" below on specifying modes using the
409 \fB\-\-mutable=\fR
410 command line option\&.
411 .PP
412 With exception of the ephemeral mode, the mutable mode routes writes to subdirectories in
413 /var/lib/extensions\&.mutable/\&.
414 .RS 4
415 Writes to /usr/ are directed to /var/lib/extensions\&.mutable/usr/
416 .RE
417 .RS 4
418 writes to /opt/ are directed to /var/lib/extensions\&.mutable/opt/, and
419 .RE
420 .RS 4
421 writes to /etc/ land in /var/lib/extensions\&.mutable/etc/\&.
422 .RE
423 .PP
424 If
425 usr/,
426 opt/, or
427 etc/
428 in
429 /var/lib/extensions\&.mutable/
430 are symlinks, then writes are directed to the symlinks\*(Aq targets\&. Consequently, to retain mutability of a host file system, create symlinks
431 .RS 4
432 /var/lib/extensions\&.mutable/etc/ → /etc/
433 .RE
434 .RS 4
435 /var/lib/extensions\&.mutable/usr/ → /usr/
436 .RE
437 .RS 4
438 /var/lib/extensions\&.mutable/opt/ → /opt/
439 .RE
440 to route writes back to the original base directory hierarchy\&.
441 .PP
442 Alternatively, a temporary file system may be mounted to
443 /var/lib/extensions\&.mutable/, or symlinks in
444 /var/lib/extensions\&.mutable/
445 may point to sub\-directories on a temporary file system (e\&.g\&. below
446 /tmp/) to only allow ephemeral changes\&. Note that this is not the same as ephemeral mode, because the temporary file system will still exist after unmerging\&.
447 .PP
448 Added in version 256\&.
449 .SH "COMMANDS"
450 .PP
451 The following commands are understood by both the sysext and confext concepts:
452 .PP
453 \fBstatus\fR
454 .RS 4
455 When invoked without any command verb, or when
456 \fBstatus\fR
457 is specified the current merge status is shown, separately (for both
458 /usr/
459 and
460 /opt/
461 of sysext and for
462 /etc/
463 of confext)\&.
464 .sp
465 Added in version 248\&.
466 .RE
467 .PP
468 \fBmerge\fR
469 .RS 4
470 Merges all currently installed system extension images into
471 /usr/
472 and
473 /opt/, by overmounting these hierarchies with an
474 "overlayfs"
475 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
476 /etc/
477 directory instead\&.
478 .sp
479 Added in version 248\&.
480 .RE
481 .PP
482 \fBunmerge\fR
483 .RS 4
484 Unmerges all currently installed system extension images from
485 /usr/
486 and
487 /opt/
488 for sysext and
489 /etc/, for confext, by unmounting the
490 "overlayfs"
491 file systems created by
492 \fBmerge\fR
493 prior\&.
494 .sp
495 Added in version 248\&.
496 .RE
497 .PP
498 \fBrefresh\fR
499 .RS 4
500 A combination of
501 \fBunmerge\fR
502 and
503 \fBmerge\fR: if already mounted the existing
504 "overlayfs"
505 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
506 "overlayfs"
507 file system accordingly\&. If no system extensions are installed when this command is executed, the equivalent of
508 \fBunmerge\fR
509 is executed, without establishing any new
510 "overlayfs"
511 instance\&. Note that currently there\*(Aqs a brief moment where neither the old nor the new
512 "overlayfs"
513 file system is mounted\&. This implies that all resources supplied by a system extension will briefly disappear \(em even if it exists continuously during the refresh operation\&.
514 .sp
515 Added in version 248\&.
516 .RE
517 .PP
518 \fBlist\fR
519 .RS 4
520 A brief list of installed extension images is shown\&.
521 .sp
522 Added in version 248\&.
523 .RE
524 .PP
525 \fB\-h\fR, \fB\-\-help\fR
526 .RS 4
527 Print a short help text and exit\&.
528 .RE
529 .PP
530 \fB\-\-version\fR
531 .RS 4
532 Print a short version string and exit\&.
533 .RE
534 .SH "OPTIONS"
535 .PP
536 \fB\-\-root=\fR
537 .RS 4
538 Operate relative to the specified root directory, i\&.e\&. establish the
539 "overlayfs"
540 mount not on the top\-level host
541 /usr/
542 and
543 /opt/
544 hierarchies for sysext or
545 /etc/
546 for confext, but below some specified root directory\&.
547 .sp
548 Added in version 248\&.
549 .RE
550 .PP
551 \fB\-\-force\fR
552 .RS 4
553 When merging system extensions into
554 /usr/
555 and
556 /opt/
557 for sysext and
558 /etc/
559 for confext, ignore version incompatibilities, i\&.e\&. force merging regardless of whether the version information included in the images matches the host or not\&.
560 .sp
561 Added in version 248\&.
562 .RE
563 .PP
564 \fB\-\-always\-refresh=yes|no\fR
565 .RS 4
566 When refreshing system extensions on
567 /usr/
568 and
569 /opt/
570 for sysext and
571 /etc/
572 for confext, ignore when the existing merged extensions already match what would be merged\&. By default the refresh is skipped when no changes are found\&. Note that changes done to an extension directory while it\*(Aqs merged are ignored without this flag (unless another extension got changed)\&. Note that changing the contents while merged is also undefined behavior in overlayfs\&.
573 .sp
574 Added in version 260\&.
575 .RE
576 .PP
577 \fB\-\-image\-policy=\fR\fB\fIpolicy\fR\fR
578 .RS 4
579 Takes an image policy string as argument, as per
580 \fBsystemd.image-policy\fR(7)\&. The policy is enforced when operating on system extension disk images\&. If not specified, defaults to
581 "root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent"
582 for system extensions, i\&.e\&. only the root and
583 /usr/
584 file systems in the image are used\&. For configuration extensions defaults to
585 "root=verity+signed+encrypted+unprotected+absent"\&. When run in the initrd and operating on a system extension image stored in the
586 /\&.extra/sysext/
587 directory a slightly stricter policy is used by default:
588 "root=signed+absent:usr=signed+absent", see above for details\&.
589 .sp
590 Added in version 254\&.
591 .RE
592 .PP
593 \fB\-\-mutable=\fR\fB\fIBOOL\fR\fR\fB|\fR\fB\fIauto\fR\fR\fB|\fR\fB\fIimport\fR\fR\fB|\fR\fB\fIephemeral\fR\fR\fB|\fR\fB\fIephemeral\-import\fR\fR\fB|\fR\fB\fIhelp\fR\fR
594 .RS 4
595 Set mutable mode\&. The special value
596 "help"
597 will list the known values\&.
598 .PP
599 \fBno\fR
600 .RS 4
601 force immutable mode even with write routing directories present\&. This is the default\&.
602 .sp
603 Added in version 256\&.
604 .RE
605 .PP
606 \fBauto\fR
607 .RS 4
608 enable mutable mode individually for
609 /usr/,
610 /opt/, and
611 /etc/
612 if write routing sub\-directories or symlinks are present in
613 /var/lib/extensions\&.mutable/; disable otherwise\&. See "Mutability" above for more information on write routing\&.
614 .sp
615 Added in version 256\&.
616 .RE
617 .PP
618 \fByes\fR
619 .RS 4
620 force mutable mode\&. Write routing directories will be created in
621 /var/lib/extensions\&.mutable/
622 if not present\&.
623 .sp
624 Added in version 256\&.
625 .RE
626 .PP
627 \fBimport\fR
628 .RS 4
629 immutable mode, but with contents of write routing directories in
630 /var/lib/extensions\&.mutable/
631 also merged into the host file system\&.
632 .sp
633 Added in version 256\&.
634 .RE
635 .PP
636 \fBephemeral\fR
637 .RS 4
638 force mutable mode, but with contents of write routing directories in
639 /var/lib/extensions\&.mutable/
640 being ignored, and modifications of the host file system being discarded after unmerge\&.
641 .sp
642 Added in version 256\&.
643 .RE
644 .PP
645 \fBephemeral\-import\fR
646 .RS 4
647 force mutable mode, with contents of write routing directories in
648 /var/lib/extensions\&.mutable/
649 being merged into the host file system, but with the modifications made to the host file system being discarded after unmerge\&.
650 .sp
651 Added in version 256\&.
652 .RE
653 .PP
654 \fBhelp\fR
655 .RS 4
656 list known values and exit immediately\&.
657 .sp
658 Added in version 259\&.
659 .RE
660 .sp
661 Added in version 256\&.
662 .RE
663 .PP
664 \fB\-\-noexec=\fR\fB\fIBOOL\fR\fR
665 .RS 4
666 When merging configuration extensions into
667 /etc/
668 the
669 "MS_NOEXEC"
670 mount flag is used by default\&. This option can be used to disable it\&.
671 .sp
672 Added in version 254\&.
673 .RE
674 .PP
675 \fB\-\-no\-reload\fR
676 .RS 4
677 When used with
678 \fBmerge\fR,
679 \fBunmerge\fR
680 or
681 \fBrefresh\fR, do not reload daemon after executing the changes even if an extension that is applied requires a reload via the
682 \fIEXTENSION_RELOAD_MANAGER=\fR
683 set to 1\&.
684 .sp
685 Added in version 255\&.
686 .RE
687 .PP
688 \fB\-\-no\-pager\fR
689 .RS 4
690 Do not pipe output into a pager\&.
691 .RE
692 .PP
693 \fB\-\-no\-legend\fR
694 .RS 4
695 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
696 .RE
697 .PP
698 \fB\-\-json=\fR\fB\fIMODE\fR\fR
699 .RS 4
700 Shows output formatted as JSON\&. Expects one of
701 "short"
702 (for the shortest possible output without any redundant whitespace or line breaks),
703 "pretty"
704 (for a pretty version of the same, with indentation and line breaks) or
705 "off"
706 (to turn off JSON output, the default)\&.
707 .RE
708 .SH "EXIT STATUS"
709 .PP
710 On success, 0 is returned\&.
711 .SH "SEE ALSO"
712 .PP
713 \fBsystemd\fR(1), \fBsysext.conf\fR(5), \fBsystemd-nspawn\fR(1), \fBsystemd-stub\fR(7), \fBimportctl\fR(1)
714 .SH "NOTES"
715 .IP " 1." 4
716 UAPI.2 Discoverable Partitions Specification
717 .RS 4
718 \%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
719 .RE
720 .IP " 2." 4
721 Portable Services
722 .RS 4
723 \%https://systemd.io/PORTABLE_SERVICES
724 .RE