From 55944e5e40b1be2afc4855d8d2baf4b73d1876b5 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 10 Apr 2024 22:49:52 +0200 Subject: Adding upstream version 255.4. Signed-off-by: Daniel Baumann --- man/systemd-sysext.xml | 361 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 361 insertions(+) create mode 100644 man/systemd-sysext.xml (limited to 'man/systemd-sysext.xml') 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 @@ + + + + + + + + systemd-sysext + systemd + + + + systemd-sysext + 8 + + + + systemd-sysext + systemd-sysext.service + systemd-confext + systemd-confext.service + Activates System Extension Images + + + + + systemd-sysext + OPTIONS + COMMAND + + + systemd-sysext.service + + + systemd-confext + OPTIONS + COMMAND + + + systemd-confext.service + + + + + Description + + systemd-sysext activates/deactivates system extension images. System extension + images may – dynamically at runtime — extend the /usr/ and + /opt/ directory hierarchies with additional files. This is particularly useful on + immutable system images where a /usr/ and/or /opt/ hierarchy + residing on a read-only file system shall be extended temporarily at runtime without making any + persistent modifications. + + 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 + /usr/ and /opt/ hierarchies are combined via + overlayfs with the same hierarchies of the host OS, and the host + /usr/ and /opt/ 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 + /usr/ and /opt/ 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. + + Files and directories contained in the extension images outside of the /usr/ + and /opt/ hierarchies are not merged, and hence have no effect + when included in a system extension image. In particular, files in the /etc/ and + /var/ included in a system extension image will not appear in + the respective hierarchies after activation. + + System extension images are strictly read-only, and the host /usr/ and + /opt/ hierarchies become read-only too while they are activated. + + 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. + + System extension images may be provided in the following formats: + + + Plain directories or btrfs subvolumes containing the OS tree + Disk images with a GPT disk label, following the Discoverable Partitions Specification + Disk images lacking a partition table, with a naked Linux file system (e.g. erofs, + squashfs or ext4) + + + These image formats are the same ones that + systemd-nspawn1 + supports via its / switches and those that the + service manager supports via /. Similar to + them they may optionally carry Verity authentication information. + + System extensions are searched for in the directories + /etc/extensions/, /run/extensions/ and + /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 /var/lib/extensions/. Any directories found in + these search directories are considered directory based extension images; any files with the + .raw suffix are considered disk image based extension images. When invoked in the + initrd, the additional directory /.extra/sysext/ 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 + systemd-stub7 with + extension images found in the system's EFI System Partition. + + During boot OS extension images are activated automatically, if the + systemd-sysext.service 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 + systemd-sysusers8 + definitions. See the Portable Services 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 systemd-sysext.service service is + guaranteed to finish start-up before basic.target is reached; i.e. at the time + regular services initialize (those which do not use DefaultDependencies=no), the files + and directories system extensions provide are available in /usr/ and + /opt/ and may be accessed. + + 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 .raw) in /etc/extensions/ to "mask" + an extension with the same name in a system folder with lower precedence. + + A simple mechanism for version compatibility is enforced: a system extension image must carry a + /usr/lib/extension-release.d/extension-release.NAME + file, which must match its image name, that is compared with the host os-release + file: the contained ID= fields have to match unless _any is set + for the extension. If the extension ID= is not _any, the + SYSEXT_LEVEL= field (if defined) has to match. If the latter is not defined, the + VERSION_ID= field has to match instead. If the extension defines the + ARCHITECTURE= field and the value is not _any it has to match the kernel's + architecture reported by uname2 + but the used architecture identifiers are the same as for ConditionArchitecture= + described in systemd.unit5. + EXTENSION_RELOAD_MANAGER= 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: + Portable Services remain + the recommended way to ship system services. + + System extensions should not ship a /usr/lib/os-release file (as that would be merged + into the host /usr/ tree, overriding the host OS version data, which is not desirable). + The extension-release file follows the same format and semantics, and carries the same + content, as the os-release file of the OS, but it describes the resources carried + in the extension image. + + The systemd-confext concept follows the same principle as the + systemd-sysext1 + functionality but instead of working on /usr and /opt, + confext will extend only /etc. Files and directories contained + in the confext images outside of the /etc/ hierarchy are not + 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 nosuid and + (if not disabled via ) noexec. + + Confexts are looked for in the directories /run/confexts/, + /var/lib/confexts/, /usr/lib/confexts/ and + /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 /var/lib/confexts/. Any directories found + in these search directories are considered directory based confext images; any files with the + .raw suffix are considered disk image based confext images. + + Again, just like sysext images, the confext images will contain a + /etc/extension-release.d/extension-release.NAME + file, which must match the image name (with the usual escape hatch of + the user.extension-release.strict + xattr7), + and again with content being one or more of ID=, VERSION_ID=, and + CONFEXT_LEVEL. Confext images will then be checked and matched against the base OS + layer. + + + + Uses + + 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. + strace1 + and + gdb1 + 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. + + 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 DESTDIR=/var/lib/extensions/mytest + make install && systemd-sysext refresh, making it available in + /usr/ as if it was installed in the OS image itself.) This case works regardless if + the underlying host /usr/ is managed as immutable disk image or is a traditional + package manager controlled (i.e. writable) tree. + + 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. + + + Commands + + The following commands are understood by both the sysext and confext concepts: + + + + + + When invoked without any command verb, or when is specified + the current merge status is shown, separately (for both /usr/ and + /opt/ of sysext and for /etc/ of confext). + + + + + + + Merges all currently installed system extension images into + /usr/ and /opt/, by overmounting these hierarchies with an + overlayfs 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 /etc/ directory instead. + + + + + + + Unmerges all currently installed system extension images from + /usr/ and /opt/ for sysext and /etc/, + for confext, by unmounting the overlayfs file systems created by + prior. + + + + + + + A combination of and : if already + mounted the existing overlayfs 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 overlayfs file system accordingly. If no system extensions + are installed when this command is executed, the equivalent of is executed, + without establishing any new overlayfs instance. + Note that currently there's a brief moment where neither the old nor the new overlayfs + 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. + + + + + + + + A brief list of installed extension images is shown. + + + + + + + + + + + Options + + + + + + Operate relative to the specified root directory, i.e. establish the + overlayfs mount not on the top-level host /usr/ and + /opt/ hierarchies for sysext or /etc/ for confext, + but below some specified root directory. + + + + + + + + When merging system extensions into /usr/ and + /opt/ for sysext and /etc/ for confext, + ignore version incompatibilities, i.e. force merging regardless of + whether the version information included in the images matches the host or not. + + + + + + + + Takes an image policy string as argument, as per + systemd.image-policy7. The + policy is enforced when operating on system extension disk images. If not specified defaults to + root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent + for system extensions, i.e. only the root and /usr/ file systems in the image + are used. For configuration extensions defaults to + root=verity+signed+encrypted+unprotected+absent. When run in the initrd and + operating on a system extension image stored in the /.extra/sysext/ directory a + slightly stricter policy is used by default: root=signed+absent:usr=signed+absent, + see above for details. + + + + + + BOOL + + When merging configuration extensions into /etc/ the + MS_NOEXEC mount flag is used by default. This option can be used to disable + it. + + + + + + + + + When used with merge, + unmerge or refresh, do not reload daemon + after executing the changes even if an extension that is applied requires a reload via the + EXTENSION_RELOAD_MANAGER= set to 1. + + + + + + + + + + + + + Exit status + + On success, 0 is returned. + + + + See Also + + systemd1, + systemd-nspawn1, + systemd-stub7 + + + + -- cgit v1.2.3