From: maanyagoenka Date: Fri, 24 Feb 2023 08:42:45 +0000 (+0000) Subject: confext: documentation and man page updates for confext X-Git-Tag: v254-rc1~797^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1f4f1666906e4dbd8126c98068eb2d4f69b879af;p=thirdparty%2Fsystemd.git confext: documentation and man page updates for confext --- diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md index 3ec5573ff95..f29ca9226bb 100644 --- a/docs/ENVIRONMENT.md +++ b/docs/ENVIRONMENT.md @@ -328,7 +328,9 @@ the journal instead of only when logging in debug mode. paths. Only "real" file systems and directories that only contain "real" file systems as submounts should be used. 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. + particular, do not specify the root directory `/` here. Similarly, + `$SYSTEMD_CONFEXT_HIERARCHIES` works for confext images and supports the + systemd-confext multi-call functionality of sysext. `systemd-tmpfiles`: diff --git a/man/os-release.xml b/man/os-release.xml index e74f27b9907..6cc786acf9e 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -442,6 +442,17 @@ + + CONFEXT_LEVEL= + + Semantically the same as SYSEXT_LEVEL= but for confext images. + See /etc/extension-release.d/extension-release.IMAGE + for more information. + + Examples: CONFEXT_LEVEL=2, CONFEXT_LEVEL=15.14. + + + SYSEXT_SCOPE= Takes a space-separated list of one or more of the strings @@ -453,6 +464,12 @@ but not to initrd environments. + + CONFEXT_SCOPE= + + Semantically the same as SYSEXT_SCOPE= but for confext images. + + PORTABLE_PREFIXES= Takes a space-separated list of one or more valid prefix match strings for the diff --git a/man/rules/meson.build b/man/rules/meson.build index 63a68c32110..b6c88db390e 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -1043,7 +1043,10 @@ manpages = [ 'systemd-suspend-then-hibernate.service'], ''], ['systemd-sysctl.service', '8', ['systemd-sysctl'], ''], - ['systemd-sysext', '8', ['systemd-sysext.service'], ''], + ['systemd-sysext', + '8', + ['systemd-confext', 'systemd-confext.service', 'systemd-sysext.service'], + ''], ['systemd-system-update-generator', '8', [], ''], ['systemd-system.conf', '5', diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml index 96e40ddf954..f3a12e0a1c2 100644 --- a/man/systemd-sysext.xml +++ b/man/systemd-sysext.xml @@ -19,6 +19,8 @@ systemd-sysext systemd-sysext.service + systemd-confext + systemd-confext.service Activates System Extension Images @@ -31,6 +33,14 @@ systemd-sysext.service + + systemd-confext + OPTIONS + COMMAND + + + systemd-confext.service + @@ -129,6 +139,29 @@ 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. + + Confexts are looked for in the directories /run/confexts/, + /var/lib/confexts/, /usr/lib/confexts/ and + /usr/local/lib/confexts/. 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/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 xattr), 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. @@ -153,20 +186,25 @@ /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: + 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/. + the current merge status is shown, separately (for both /usr/ and + /opt/ of sysext and for /etc/ of confext). @@ -174,14 +212,15 @@ 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. + 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/, by unmounting the - overlayfs file systems created by + /usr/ and /opt/ for sysext and /etc/, + for confext, by unmounting the overlayfs file systems created by prior. @@ -191,11 +230,11 @@ 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. + 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. @@ -218,16 +257,17 @@ 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. + /opt/ hierarchies for sysext or /etc/ for confext, + but below some specified root directory. When merging system extensions into /usr/ and - /opt/, ignore version incompatibilities, i.e. force merging regardless of - whether the version information included in the extension images matches the host or - not. + /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.