diff options
Diffstat (limited to 'upstream/debian-unstable/man8/systemd-sysext.8')
| -rw-r--r-- | upstream/debian-unstable/man8/systemd-sysext.8 | 228 |
1 files changed, 214 insertions, 14 deletions
diff --git a/upstream/debian-unstable/man8/systemd-sysext.8 b/upstream/debian-unstable/man8/systemd-sysext.8 index 949afe88..f60d4cae 100644 --- a/upstream/debian-unstable/man8/systemd-sysext.8 +++ b/upstream/debian-unstable/man8/systemd-sysext.8 @@ -1,5 +1,5 @@ '\" t -.TH "SYSTEMD\-SYSEXT" "8" "" "systemd 255" "systemd-sysext" +.TH "SYSTEMD\-SYSEXT" "8" "" "systemd 256~rc3" "systemd-sysext" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- @@ -25,15 +25,11 @@ systemd-sysext, systemd-sysext.service, systemd-confext, systemd-confext.service .HP \w'\fBsystemd\-sysext\fR\ 'u \fBsystemd\-sysext\fR [OPTIONS...] COMMAND .PP -.nf systemd\-sysext\&.service -.fi .HP \w'\fBsystemd\-confext\fR\ 'u \fBsystemd\-confext\fR [OPTIONS...] COMMAND .PP -.nf systemd\-confext\&.service -.fi .SH "DESCRIPTION" .PP \fBsystemd\-sysext\fR @@ -77,11 +73,13 @@ included in a system extension image will \fInot\fR appear in the respective hierarchies after activation\&. .PP -System extension images are strictly read\-only, and the host +System extension images are strictly read\-only by default\&. On mutable host file systems, /usr/ and /opt/ -hierarchies become read\-only too while they are activated\&. +hierarchies become read\-only while extensions are merged, unless mutability is enabled\&. Mutability may be enabled via the +\fB\-\-mutable=\fR +option; see "Mutability" below for more information\&. .PP 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\&. .PP @@ -189,7 +187,7 @@ but the used architecture identifiers are the same as for described in \fBsystemd.unit\fR(5)\&. \fIEXTENSION_RELOAD_MANAGER=\fR -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: +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: \m[blue]\fBPortable Services\fR\m[]\&\s-2\u[2]\d\s+2 remain the recommended way to ship system services\&. System extensions should not ship a /usr/lib/os\-release @@ -221,6 +219,12 @@ and (if not disabled via \fB\-\-noexec=false\fR) "noexec"\&. .PP +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 +\fB\-\-mutable=\fR +option\&. Refer to "Mutability" below for more information\&. +.PP Confexts are looked for in the directories /run/confexts/, /var/lib/confexts/, @@ -254,7 +258,143 @@ as if it was installed in the OS image itself\&.) This case works regardless if /usr/ is managed as immutable disk image or is a traditional package manager controlled (i\&.e\&. writable) tree\&. .PP -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\&. +With systemd\-confext 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 systemd\-confext image is removed\&. +.SH "MUTABILITY" +.PP +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\&. +.PP +The following modes are supported: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +\fBdisabled\fR: Force immutable mode even if write routing directories exist below +/var/lib/extensions\&.mutable/\&. This is the default\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +\fBauto\fR: Automatic mode\&. Mutability is disabled by default and only enabled if a corresponding write routing directory exists below +/var/lib/extensions\&.mutable/\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +\fBenabled\fR: Force mutable mode and automatically create write routing directories below +/var/lib/extensions\&.mutable/ +when required\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +\fBimport\fR: Force immutable mode like +\fBdisabled\fR +above, but merge the contents of directories below +/var/lib/extensions\&.mutable/ +into the host file system\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 5." 4.2 +.\} +\fBephemeral\fR: Force mutable mode like +\fBenabled\fR +above, but instead of using write routing directory below +/var/lib/extensions\&.mutable/, +\fBsystemd\-sysext\fR +will use empty ephemeral directories\&. This means that the modifications made in the merged hierarchies will be gone when the hierarchies are unmerged\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 6." 4.2 +.\} +\fBephemeral\-import\fR: Force mutable mode like +\fBephemeral\fR +above, but instead of ignoring the contents of write routing directories under +/var/lib/extensions\&.mutable/, merge them into the host file system, like +\fBimport\fR +does\&. +.RE +.sp +See "Options" below on specifying modes using the +\fB\-\-mutable=\fR +command line option\&. +.PP +With exception of the ephemeral mode, the mutable mode routes writes to subdirectories in +/var/lib/extensions\&.mutable/\&. +.RS 4 +Writes to /usr/ are directed to /var/lib/extensions\&.mutable/usr/ +.RE +.RS 4 +writes to /opt/ are directed to /var/lib/extensions\&.mutable/opt/, and +.RE +.RS 4 +writes to /etc/ land in /var/lib/extensions\&.mutable/etc/\&. +.RE +.PP +If +usr/, +opt/, or +etc/ +in +/var/lib/extensions\&.mutable/ +are symlinks, then writes are directed to the symlinks\*(Aq targets\&. Consequently, to retain mutability of a host file system, create symlinks +.RS 4 +/var/lib/extensions\&.mutable/etc/ → /etc/ +.RE +.RS 4 +/var/lib/extensions\&.mutable/usr/ → /usr/ +.RE +.RS 4 +/var/lib/extensions\&.mutable/opt/ → /opt/ +.RE +to route writes back to the original base directory hierarchy\&. +.PP +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\&. Note that this is not the same as ephemeral mode, because the temporary file system will still exist after unmerging\&. +.PP +Added in version 256\&. .SH "COMMANDS" .PP The following commands are understood by both the sysext and confext concepts: @@ -386,7 +526,69 @@ directory a slightly stricter policy is used by default: Added in version 254\&. .RE .PP -\fB\-\-noexec=\fR\fIBOOL\fR +\fB\-\-mutable=\fR\fB\fIBOOL\fR\fR\fB|\fR\fB\fIauto\fR\fR\fB|\fR\fB\fIimport\fR\fR +.RS 4 +Set mutable mode\&. +.PP +\fBno\fR +.RS 4 +force immutable mode even with write routing directories present\&. This is the default\&. +.sp +Added in version 256\&. +.RE +.PP +\fBauto\fR +.RS 4 +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\&. +.sp +Added in version 256\&. +.RE +.PP +\fByes\fR +.RS 4 +force mutable mode\&. Write routing directories will be created in +/var/lib/extensions\&.mutable/ +if not present\&. +.sp +Added in version 256\&. +.RE +.PP +\fBimport\fR +.RS 4 +immutable mode, but with contents of write routing directories in +/var/lib/extensions\&.mutable/ +also merged into the host file system\&. +.sp +Added in version 256\&. +.RE +.PP +\fBephemeral\fR +.RS 4 +force mutable mode, but with contents of write routing directories in +/var/lib/extensions\&.mutable/ +being ignored, and modifications of the host file system being discarded after unmerge\&. +.sp +Added in version 256\&. +.RE +.PP +\fBephemeral\-import\fR +.RS 4 +force mutable mode, with contents of write routing directories in +/var/lib/extensions\&.mutable/ +being merged into the host file system, but with the modifications made to the host file system being discarded after unmerge\&. +.sp +Added in version 256\&. +.RE +.sp +Added in version 256\&. +.RE +.PP +\fB\-\-noexec=\fR\fB\fIBOOL\fR\fR .RS 4 When merging configuration extensions into /etc/ @@ -420,7 +622,7 @@ Do not pipe output into a pager\&. Do not print the legend, i\&.e\&. column headers and the footer with hints\&. .RE .PP -\fB\-\-json=\fR\fIMODE\fR +\fB\-\-json=\fR\fB\fIMODE\fR\fR .RS 4 Shows output formatted as JSON\&. Expects one of "short" @@ -435,9 +637,7 @@ Shows output formatted as JSON\&. Expects one of On success, 0 is returned\&. .SH "SEE ALSO" .PP -\fBsystemd\fR(1), -\fBsystemd-nspawn\fR(1), -\fBsystemd-stub\fR(7) +\fBsystemd\fR(1), \fBsystemd-nspawn\fR(1), \fBsystemd-stub\fR(7), \fBimportctl\fR(1) .SH "NOTES" .IP " 1." 4 Discoverable Partitions Specification |