From ea29a87f23cf4c4207d74216238ffba318b29b98 Mon Sep 17 00:00:00 2001 From: Thilo Fromm Date: Fri, 16 Feb 2024 19:29:12 +0100 Subject: [PATCH] man/systemd-sysext.xml: document mutable extensions Signed-off-by: Thilo Fromm --- man/systemd-sysext.xml | 99 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 97 insertions(+), 2 deletions(-) diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml index d32804409b9..ea1af001a79 100644 --- a/man/systemd-sysext.xml +++ b/man/systemd-sysext.xml @@ -69,8 +69,10 @@ /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 extension images are strictly read-only by default. On mutable host file systems, + /usr/ and /opt/ hierarchies become read-only while extensions + are merged, unless mutability is enabled. Mutability may be enabled via the + option; see "Mutability" below for more information. 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 @@ -158,6 +160,11 @@ same as sysext images. The merged hierarchy will be mounted with nosuid and (if not disabled via ) noexec. + Just like sysexts, confexts are strictly read-only by default. Merging confexts on mutable host + file systems will result in /etc/ becoming read-only. As with sysexts, mutability + can be enabled via the option. Refer to "Mutability" below for more + information. + 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 @@ -205,6 +212,55 @@ 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. + + Mutability + By default, merging system extensions on mutable host file systems will render /usr/ + and /opt/ hierarchies read-only. Merging configuration extensions will have the same + effect on /etc/. Mutable mode allows writes to these locations when extensions are + merged. + + The following modes are supported: + + : Force immutable mode even if write routing + directories exist below /var/lib/extensions.mutable/. + This is the default. + : Automatic mode. Mutability is disabled by default + and only enabled if a corresponding write routing directory exists below + /var/lib/extensions.mutable/. + : Force mutable mode and automatically create write routing + directories below /var/lib/extensions.mutable/ when required. + : Force immutable mode like above, but + merge the contents of directories below /var/lib/extensions.mutable/ into the host + file system. + + See "Options" below on specifying modes using the command line option. + + Mutable mode routes writes to subdirectories in /var/lib/extensions.mutable/. + + Writes to /usr/ are directed to /var/lib/extensions.mutable/usr/, + writes to /opt/ are directed to /var/lib/extensions.mutable/opt/, and + writes to /etc/ land in /var/lib/extensions.mutable/etc/. + + + If usr/, opt/, or etc/ + in /var/lib/extensions.mutable/ are symlinks, then writes are directed to the + symlinks' targets. + Consequently, to retain mutability of a host file system, create symlinks + + /var/lib/extensions.mutable/etc/ → /etc/ + /var/lib/extensions.mutable/usr/ → /usr/ + /var/lib/extensions.mutable/opt/ → /opt/ + + to route writes back to the original base directory hierarchy. + + Alternatively, a temporary file system may be mounted to + /var/lib/extensions.mutable/, or symlinks in + /var/lib/extensions.mutable/ may point to sub-directories on a temporary + file system (e.g. below /tmp/) to only allow ephemeral changes. + + + + Commands @@ -313,6 +369,45 @@ + + BOOL|auto|import + Set mutable mode. + + + + + force immutable mode even with write routing directories present. + This is the default. + + + + + + enable mutable mode individually for /usr/, + /opt/, and /etc/ if write routing sub-directories + or symlinks are present in /var/lib/extensions.mutable/; disable otherwise. + See "Mutability" above for more information on write routing. + + + + + + force mutable mode. Write routing directories will be created in + /var/lib/extensions.mutable/ if not present. + + + + + + immutable mode, but with contents of write routing directories in + /var/lib/extensions.mutable/ also merged into the host file system. + + + + + + + BOOL -- 2.47.3