From: Lennart Poettering Date: Tue, 12 Jan 2021 13:55:11 +0000 (+0100) Subject: man: add man page for systemd-sysext X-Git-Tag: v248-rc1~298^2~9 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7a87fb611986db0b55dbc045230b5edceef05a87;p=thirdparty%2Fsystemd.git man: add man page for systemd-sysext --- diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md index 47cdff317bf..cfe7784f9ef 100644 --- a/docs/ENVIRONMENT.md +++ b/docs/ENVIRONMENT.md @@ -267,3 +267,15 @@ systemd-firstboot and localectl: * `SYSTEMD_LIST_NON_UTF8_LOCALES=1` – if set non-UTF-8 locales are listed among the installed ones. By default non-UTF-8 locales are suppressed from the selection, since we are living in the 21st century. + +systemd-sysext: + +* `SYSTEMD_SYSEXT_HIERARCHIES` – if set to a colon-separated list of absolute + paths this variable may be used to override which hierarchies to manage with + `systemd-sysext`. By default only `/usr/` and `/opt/` are managed. With this + environment variable this list may be changed, in order to add or remove + directories from this list. This should only reference "real" file systems + and directories that only contain "real" file systems as submounts — do not + specify API file systems such as `/proc/` or `/sys/` here, or hierarchies + that have them as submounts. In particular, do not specify the root directory + `/` here. diff --git a/man/rules/meson.build b/man/rules/meson.build index b8cb96ac22f..38d58307fe0 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -954,6 +954,7 @@ manpages = [ 'systemd-suspend-then-hibernate.service'], ''], ['systemd-sysctl.service', '8', ['systemd-sysctl'], ''], + ['systemd-sysext', '8', ['systemd-sysext.service'], ''], ['systemd-system-update-generator', '8', [], ''], ['systemd-system.conf', '5', diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml new file mode 100644 index 00000000000..14aab94dc93 --- /dev/null +++ b/man/systemd-sysext.xml @@ -0,0 +1,236 @@ + + + + + + + + systemd-sysext + systemd + + + + systemd-sysext + 8 + + + + systemd-sysext + systemd-sysext.service + Activates System Extension Images + + + + + systemd-sysext + OPTIONS + + + systemd-sysext.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 (with the exception of /etc/os-release, + see below). 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 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 Partition Specification + Disk images lacking a partition table, with a naked Linux file system (e.g. squashfs or ext4) + + + These image formats are the same ones that + systemd-nspawn1 + supports via it's / switches and those that the + service manager supports via /. Similar to + them they may optionally carry Verity authentication information. + + System extensions are automatically looked for in the directories + /etc/extensions/, /run/extensions/, + /var/lib/extensions/, /usr/lib/extensions/ and + /usr/local/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. + + 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 are searched are 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 Portable Services 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. + + A simple mechanism for version compatibility is enforced: a system extension image may carry an + /etc/os-release file that is compared with the host os-release + file: the contained ID= fields have to match, as well as the + SYSEXT_LEVEL= field (if defined). If the latter is not defined the + VERSION_ID= field has to match instead. 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). + + + + 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. strace and gdb 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. + + + + Commands + + The following command switches are understood: + + + + + + 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. + + + + + + Unmerges all currently installed system extension images from + /usr/ and /opt/, 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. + + + + + + + When invoked without any command switches, the current merge status is shown, separately for both + /usr/ and /opt/. + + + + Options + + + + + + Operate relative to the specified root directory, i.e. establish the + overlayfs mount not on the top-level host /usr/ and + /opt/ hierarchies, but below some specified root directory. + + + + + + Generate JSON output, instead of human readable tabular output. Takes one of + short, pretty or off in order to control the + output style, or explicitly disabling JSON output. + + + + + + + + Exit status + + On success, 0 is returned. + + + + See Also + + systemd1, + systemd-nspawn1 + + + +