Up to now we recommended to use TARGET.upholds/ symlinks to start units
when an extension is loaded. However, this has some drawbacks. First,
for services that should not be tried to be started all the time we have
to resort to hiding them through a target that gets uphold and then
uses regular .wants/ for the actual service. Second, we actually leak
services on extension unload even if the unit has disappeared with the
extension. Third, to affect a service through a drop-in or a config
change from a confext/sysext and that service is already running, we
need a way to restart/reload it instead of just starting it.
Similar to EXTENSION_RELOAD_MANAGER=1, add a EXTENSION_RESTART_UNITS=
and a EXTENSION_RELOAD_OR_RESTART_UNITS= setting to the
extension-release metadata file, carrying a whitespace-separated list
of units to restart/reload on merge/refresh/unmerge after the daemon
reload. Also detect when the unit has vanished which is normally the
case when the unit was part of the unmerged extension, and stop it
explicitly to prevent it leaking. When the extension itself ships the
binary it should use EXTENSION_RESTART_UNITS= to make sure the new
binary is picked up. Since starting through this setting does not work
when the extension is mounted from the initrd, extensions should still
ship at least a .wants/ symlink to start at boot but can also continue
to ship a .upholds/ symlink for backwards compatibility without any
drawback and still benefit from the unit stopping triggered by the new
setting. While there are cases where one could want to set
EXTENSION_RESTART_UNITS= without requiring a daemon reload (e.g., an
env var file change instead of a unit drop-in), we now do an implicit
daemon reload when we have to restart units so that we know we work on
the right state and we spare users remembering to set this setting in
addition to prevent running into this issue.
While it is possible to disable sysext/confext merging in the main system
with 'systemctl disable', sysext/confext are always merged in the initrd,
both by systemd-{sys,conf}ext-initrd.service and by
systemd-{sys,conf}ext-sysroot.service and especially the latter can be
unexpected. Provide kernel cmdline options systemd.{sys,conf}ext=0 and
rd.systemd.{sys,conf}ext=0 covering all options.
The new services are used to activate system and configuration extensions
for the main system from the initrd, this allows to overcome the limitation
that sysext/confext cannot be used to update the resources which are required
in the earliest boot of the system (before systemd-sysext/systemd-confext
start).
When the extensions for the final system are already set up from the
initrd we should avoid disrupting the boot process with the remount
(which currently isn't atomic) and the daemon reload for
systemd-confext and systemd-sysext. Similarly, when sysupdate ran and
updated extensions it's best to avoid the remount and daemon reload if
no changes are found.
To do this, encode the current extension state in more detail than
before where only the names of the extensions where encoded in the
overlay mount. This can also be used to provide more details about the
extension origin in "systemd-sysext status (--json=)". During the
refresh add a check whether the old state matches the new state and in
this case skip the refresh unless the user provides a flag to always
refresh. Besides the extension name and the resolved path the best
method for identification is the verity hash but that is not available
for plain image files or directories. Therefore, also include data to
check for file/directory replacements. The creation/modification times
are not always real on reproducible images or extracted archive content.
The file handle together with the unique mount ID is the next best
identifier we can use when we have no verity hash. Fall back to an inode
when we get no handle. With the creation/modification time and the path
this should be good enough. Using a unique mount ID is important (with
a fallback to the regular non-unique mount ID) instead of st_dev because
st_dev gets reused too easily, e.g., by a loop device mount and the
mount ID helps to catch this. For the mount ID to be valid it has to be
resolved before we enter the new mount namespace. Thus, it gets provided
by the image dissect logic and handed over to the sysext subprocess
which runs in a new mount namespace.
Luckily, we can rule out online modification of directories or image
files because this is anyway not well supported with overlay mounts, so
we don't do a file checksum nor do we recurse into a directory to look
for the most recently touched files. But, as said, with the
always-refresh flag one can force a reload.
Add sysext.conf, which similar to other configs like coredump, will be
searched in:
/{etc run usr/lib}/systemd/{sysext/confext}.conf
but also
/{etc run usr/lib}/systemd/{sysext/confext}.conf.d/*
This config is an alternative to command line options, especially useful
if we want to extend the service units without modifying them.
ephemeral/ephemeral-import are described as possible '--mutable' options but
not present in the list. Note, "systemd-sysext --help" lists them correctly.
In the initrd we want to run as early as possible, before
any of the filesystems are set up, so that users can use
sysexts to customize kernel modules, firmware, etc. But
in the root fs it needs to run after /var/ has been set
up. Split the unit, and have an initrd-specific one that
runs very early.
In the initrd we want to run as early as possible, before
any of the filesystems are set up, so that users can use
confexts to customize fstab/veritytab/crypttab/etc. But
in the root fs it needs to run after /var/ has been set
up. Split the unit, and have an initrd-specific one that
runs very early.
Some ambiguity (e.g., same-named man pages in multiple volumes)
makes it impossible to fully automate this, but the following
Python snippet (run inside the man/ directory of the systemd repo)
helped to generate the sed command lines (which were subsequently
manually reviewed, run and the false positives reverted):
from pathlib import Path
import lxml
from lxml import etree as ET
man2vol: dict[str, str] = {}
man2citerefs: dict[str, list] = {}
for file in Path(".").glob("*.xml"):
tree = ET.parse(file, lxml.etree.XMLParser(recover=True))
meta = tree.find("refmeta")
if meta is not None:
title = meta.findtext("refentrytitle")
if title is not None:
vol = meta.findtext("manvolnum")
if vol is not None:
man2vol[title] = vol
citerefs = list(tree.iter("citerefentry"))
if citerefs:
man2citerefs[title] = citerefs
for man, refs in man2citerefs.items():
for ref in refs:
title = ref.findtext("refentrytitle")
if title is not None:
has = ref.findtext("manvolnum")
try:
should_have = man2vol[title]
except KeyError: # Non-systemd man page reference? Ignore.
continue
if has != should_have:
print(
f"sed -i '\\|<citerefentry><refentrytitle>{title}"
f"</refentrytitle><manvolnum>{has}</manvolnum>"
f"</citerefentry>|s|<manvolnum>{has}</manvolnum>|"
f"<manvolnum>{should_have}</manvolnum>|' {man}.xml"
)
The systemd-confext use case description was mentioning an OSConfig
project which won't say much to users. Also, it's good to call out that
systemd-confext provides a reliable way to manage configuration because
in contrast to other tools it will remove all old configuration files.
This also replaces the Fedora download example with another one from
Ubuntu, since Fedora's images these days no longer qualify as DDIs, they
have no distinctive partition type UUIDs set for multiple of their
partitions, hence the images cannot be booted. A bit sad. Let's provide
a command that just works in its place.
With <para><filename>…</filename></para>, we get a separate "paragraph" for
each line, i.e. entries separated by empty lines. This uses up a lot of space
and was only done because docbook makes it hard to insert a newline. In some
other places, <literallayout> was used, but then we cannot indent the source
text (because the whitespace would end up in the final page). We can get the
desired result with <simplelist>.
With <simplelist> the items are indented in roff output, but not in html
output. In some places this looks better then no indentation, and in others it
would probably be better to have no indent. But this is a minor issue and we
cannot control that.
(I didn't convert all spots. There's a bunch of other man pages which have two
lines, e.g. an executable and service file, and it doesn't matter there so
much.)
<ulinks> contents are used to generate a SEE ALSO section at the
bottom of a man page, so we need to include the title, without additional
words, in the content.
This tries to add information about when each option was added. It goes
back to version 183.
The version info is included from a separate file to allow generating it,
which would allow more control on the formatting of the final output.
This metadata (EXTENSION_RELOAD_MANAGER) can be set to "1" to reload the manager
when merging/refreshing/unmerging a system extension image. This can be useful in case the sysext
image provides systemd units that need to be loaded.
With `--no-reload`, one can deactivate the EXTENSION_RELOAD_MANAGER metadata interpretation.
Signed-off-by: Mathieu Tortuyaux <mtortuyaux@microsoft.com>
Confexts should not contain code, so mount confexts with noexec.
We cannot mount invidial extensions as noexec, as the overlay ignores
it and bypasses it, we need to use the flag on the whole overlay for
it to be effective.
But given there are legacy scripts still shipped in /etc, allow to
override it with --noexec=false.
sysexts are meant to extend /usr. All extension images and directories are opened and merged in a
single, read-only overlayfs layer, mounted on /usr.
So far, we had fallback storage directories in /usr/lib/extensions and /usr/local/lib/extensions.
This is problematic for three reasons.
Firstly, technically, for directory-based extensions the kernel will reject
creating such an overlay, as there is a recursion problem. It actively
validates that a lowerdir is not a child of another lowerdir, and fails with
-ELOOP if it is. So having a sysext /usr/lib/extensions/myextdir/ would result
in an overlayfs config lowerdir=/usr/lib/extensions/myextdir/usr/:/usr which is
not allowed, as indicated by Christian the kernel performs this check:
/*
* Check if this layer root is a descendant of:
* - another layer of this overlayfs instance
* - upper/work dir of any overlayfs instance
*/
<...>
/* Walk back ancestors to root (inclusive) looking for traps */
while (!err && parent != next) {
if (is_lower && ovl_lookup_trap_inode(sb, parent)) {
err = -ELOOP;
pr_err("overlapping %s path\n", name);
Secondly, there's a confusing aspect to this recursive storage. If you
have /usr/lib/extensions/myext.raw which contains /usr/lib/extensions/mynested.raw
'systemd-sysext merge' will only pick up the first one, but both will appear in
the merged root under /usr/lib/extensions/. So you have two extension images, both
appear in your merged filesystem, but only one is actually in use.
Finally, there's a conceptual aspect: the idea behind sysexts and hermetic /usr
is that the /usr tree is not modified locally, but owned by the vendor. Dropping
extensions in /usr thus goes contrary to this foundational concept.
Fixes#25780.
> Man page: crypttab.5
> Issue 1: Missing fullstop
> Issue 2: I<cipher=>, I<hash=>, I<size=> → B<cipher=>, B<hash=>, B<size=>
>
> "Force LUKS mode\\&. When this mode is used, the following options are "
> "ignored since they are provided by the LUKS header on the device: "
> "I<cipher=>, I<hash=>, I<size=>"
Seems OK to me. The full stop is there and has been for at least a few years. And we use <option> for the markup, which is appropriate here.
> Man page: crypttab.5
> Issue 1: Missing fullstop
> Issue 2: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-size=>, I<size=> → B<cipher=>, B<hash=>, B<keyfile-offset=>, B<keyfile-size=>, B<size=>
>
> "Use TrueCrypt encryption mode\\&. When this mode is used, the following "
> "options are ignored since they are provided by the TrueCrypt header on the "
> "device or do not apply: I<cipher=>, I<hash=>, I<keyfile-offset=>, I<keyfile-"
> "size=>, I<size=>"
Same.
> Man page: journalctl.1
> Issue 1: make be → may be
Fixed.
> Issue 2: below\\&. → below:
Fixed.
> Man page: journalctl.1
> Issue: Colon at the end?
>
> "The following commands are understood\\&. If none is specified the default "
> "is to display journal records\\&."
> msgstr ""
> "Die folgenden Befehle werden verstanden\\&. Falls keiner festgelegt ist, ist "
> "die Anzeige von Journal-Datensätzen die Vorgabe\\&."
This is a bit awkward, but I'm not sure how to fix it.
> Man page: kernel-install.8
> Issue: methods a fallback → methods fallback
It was correct, but I added a comma to make the sense clearer.
> Man page: loader.conf.5
> Issue 1: secure boot variables → Secure Boot variables
> Issue 2: one → one for (multiple times)
>
> "Supported secure boot variables are one database for authorized images, one "
> "key exchange key (KEK) and one platform key (PK)\\&. For more information, "
> "refer to the \\m[blue]B<UEFI specification>\\m[]\\&\\s-2\\u[2]\\d\\s+2, "
> "under Secure Boot and Driver Signing\\&. Another resource that describe the "
> "interplay of the different variables is the \\m[blue]B<EDK2 "
> "documentation>\\m[]\\&\\s-2\\u[3]\\d\\s+2\\&."
"one of" would sound strange. "One this and one that" is OK.
> Man page: loader.conf.5
> Issue: systemd-boot → B<systemd-boot>(7)
Fixed.
> Man page: logind.conf.5
> Issue: systemd-logind → B<systemd-logind>(8)
We use <filename>systemd-logind</> on subsequent references… I think that's good enough.
> Man page: nss-myhostname.8
> Issue: B<getent> → B<getent>(1)
Fixed.
> Man page: nss-resolve.8
> Issue: B<systemd-resolved> → B<systemd-resolved>(8)
The first reference does this, subsequent are shorter.
> Man page: os-release.5
> Issue: Portable Services → Portable Services Documentation?
Updated.
> Man page: pam_systemd_home.8
> Issue: auth and account use "reason", while session and password do not?
Reworded.
> Man page: portablectl.1
> Issue: In systemd-portabled.service(8): Portable Services Documentation
Updated.
> Man page: repart.d.5
> Issue: The partition → the partition
Fixed.
> Man page: repart.d.5
> Issue: B<systemd-repart> → B<systemd-repart>(8)
The first reference does this. I also change this one, because it's pretty far down in the text.
> Man page: systemd.1
> Issue: kernel command line twice?
>
> "Takes a boolean argument\\&. If false disables importing credentials from "
> "the kernel command line, qemu_fw_cfg subsystem or the kernel command line\\&."
Apparently this was fixed already.
> Man page: systemd-boot.7
> Issue: enrollement → enrollment
Fixed.
> Man page: systemd-cryptenroll.1
> Issue: multiple cases: any specified → the specified
Reworded.
> Man page: systemd-cryptenroll.1
> Issue: If this this → If this
Fixed tree-wide.
> Man page: systemd-cryptsetup-generator.8
> Issue: and the initrd → and in the initrd
"Is honoured by the initrd" is OK, because we often speak about the initrd as a single unit. But in the same paragraph we also used "in the initrd", which makes the other use look sloppy. I changed it to "in the initrd" everywhere in that file.
> Man page: systemd.directives.7
> Issue: Why are these two quoted (but not others)?
>
> "B<\\*(Aqh\\*(Aq>"
>
> B<\\*(Aqs\\*(Aq>"
>
> "B<\\*(Aqy\\*(Aq>"
This is autogenerated from files… We use slightly different markup in different files, and it's just too hard to make it consistent. We gave up on this.
> Man page: systemd.exec.5
> Issue 1: B<at>(1p) → B<at>(1)
> Issue 2: B<crontab>(1p) → B<crontab>(1)
Fixed.
> Man page: systemd.exec.5
> Issue: B<select()> → B<select>(2)
Fixed.
> Man page: systemd.exec.5
> Issue: qemu → B<qemu>(1)
The man page doesn't seem to be in any of the canonical places on the web.
I added a link to online docs.
> Man page: systemd.exec.5
> Issue: variable → variables
Seems to be fixed already.
> Man page: systemd-integritysetup-generator.8
> Issue: systemd-integritysetup-generator → B<systemd-integritysetup-generator>
I changed <filename> to <command>.
> Man page: systemd-integritysetup-generator.8
> Issue: superfluous comma at the end
Already fixed.
> Man page: systemd-measure.1
> Issue: (see B<--pcr-bank=>) below → (see B<--pcr-bank=> below)
Reworded.
> Man page: systemd-measure.1
> Issue: =PATH> → =>I<PATH>
Fixed.
> Man page: systemd-measure.1.po
> Issue: B<--bank=DIGEST> → B<--bank=>I<DIGEST>
Fixed.
> Man page: systemd.netdev.5
> Issue: os the → on the
Appears to have been fixed already.
> Man page: systemd.netdev.5
> Issue: Onboard → On-board (as in previous string)
Updated.
> Man page: systemd.network.5
> Issue: B<systemd-networkd> -> B<systemd-networkd>(8)
First reference does this, subsequent do not.
> Man page: systemd.network.5
> Issue: B<netlabelctl> → B<netlabelctl>(8)
First reference does this, subsequent do not.
> Man page: systemd.network.5
> Issue: Missing verb (aquired? configured?) in the half sentence starting with "or by a "
I dropped the comma.
> Man page: systemd-nspawn.1
> Issue: All host users outside of that range → All other host users
Reworded.
> # FIXME no effect → no effect\\&.
> #. type: Plain text
> #: archlinux debian-unstable fedora-rawhide mageia-cauldron opensuse-tumbleweed
> msgid ""
> "Whichever ID mapping option is used, the same mapping will be used for users "
> "and groups IDs\\&. If B<rootidmap> is used, the group owning the bind "
> "mounted directory will have no effect"
A period is added. Not sure if there's some other issue.
> Man page: systemd-oomd.service.8
> Issue: B<systemd> → B<systemd>(1)
Done.
> Man page: systemd.path.5
> Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5)
> Issue 2: This section does not (yet?) exist
Fixed.
> Man page: systemd-pcrphase.service.8
> Issue 1: indicate phases into TPM2 PCR 11 ??
> Issue 2: Colon at the end of the paragraph?
Fixed.
> Man page: systemd-pcrphase.service.8
> Issue: final boot phase → final shutdown phase?
Updated.
> Man page: systemd-pcrphase.service.8
> Issue: for the the → for the
Fixed tree-wide.
> Man page: systemd-portabled.service.8
> Issue: In systemd-portabled.service(8): Portable Services Documentation
Updated.
> Man page: systemd-pstore.service.8
> Issue: Here and the following paragraphs: . → \\&. // Upstream: What does this comment mean? // You normally write \\&. for a full dot (full stop etc.); here you write only "." (i.e. a plain dot).
>
> "and we look up \"localhost\", nss-dns will send the following queries to "
> "systemd-resolved listening on 127.0.0.53:53: first \"localhost.foobar.com\", "
> "then \"localhost.barbar.com\", and finally \"localhost\". If (hopefully) the "
> "first two queries fail, systemd-resolved will synthesize an answer for the "
> "third query."
Looks all OK to me.
> Man page: systemd.resource-control.5
> Issue: Missing closing bracket after link to Control Groups version 1
Fixed.
> Man page: systemd-sysext.8
> Issue: In systemd-portabled.service(8): Portable Services Documentation
Updated.
> Man page: systemd.timer.5
> Issue 1: B<systemd.exec>(1) → B<systemd.exec>(5)
> Issue 2: This section does not (yet?) exist
Fixed.
> Man page: systemd.unit.5
> Issue: that is → that are
Fixed.
> Man page: systemd-veritysetup-generator.8
> Issue: systemd-veritysetup-generator → B<systemd-veritysetup-generator>
>
> "systemd-veritysetup-generator implements B<systemd.generator>(7)\\&."
>
> "systemd-veritysetup-generator understands the following kernel command line "
> "parameters:"
Updated.
> Man page: systemd-volatile-root.service.8
> Issue: initrdyes → Initrd
Fixed.
> Man page: sysupdate.d.5
> Issue: : → \\&. (As above in TRANSFER)
Updated.
> Man page: sysupdate.d.5
> Issue: some → certain
Updated.
> Man page: sysupdate.d.5
> Issue 1: i\\&.e\\& → I\\&.e\\&
Fixed.
> Issue 2: the image → the system
"image" seems correct.
> Man page: tmpfiles.d.5
> Issue: systemd-tmpfiles → B<systemd-tmpfiles>(8)
Updated.
So, i think "erofs" is probably the better, more modern alternative to
"squashfs". Many of the benefits don't matter too much to us I guess,
but there's one thing that stands out: erofs has a UUID in the
superblock, squashfs has not. Having an UUID in the superblock matters
if the file systems are used in an overlayfs stack, as overlayfs uses
the UUIDs to robustly and persistently reference inodes on layers in
case of metadata copy-up.
Since we probably want to allow such uses in overlayfs as emplyoed by
sysext (and the future syscfg) we probably should ramp up our erofs game
early on. Hence let's natively support erofs, test it, and in fact
mention it in the docs before squashfs even.
While I had tested that a symlink to /dev/null works to "mask" a sysext
I must have gotten something wrong and thus the instructions in
519c2f0d6b don't work. What works,
at least at the moment, is to instead have an empty directory with the
extension name under /etc/extensions/.
Correct the info in the man page and add a test for it.
When an extension image has binaries they should match the host
architecture. Currently there is no way to specify this requirement.
Introduce an ARCHITECTURE field in the extension's release file that
may be set to prevent loading on the wrong host architecture.
Since this new field is introduced late, we don't want to make
specifying it mandatory as it would break existing sysext images.
See https://github.com/systemd/systemd/issues/24061
A sysext image that merely contains static binaries has no dependency
on the host distribution and should be able to be used anywhere.
Support the special '_any' value for the ID field in the extension to
opt-out of ID and VERSION_ID/SYSEXT_LEVEL matching.
See https://github.com/systemd/systemd/issues/24061
A read-only /usr may ship a sysext image by default and the user wants
to opt out. Currently it's not clear how to do this.
Document that a /dev/null symlink in /etc/extensions/ works to "mask" a
sysext image in a folder with lower precedence.
While overlaying files with a sysext can be useful, it may lead to
unexpected problems depending on when a process got started and which
version of the file it gets.
Call out that overlaying files is possible but don't recommend to make
use of it.
There is some inconsistency, partially caused by the awkward naming
of the docs/ pages. But let's be consistent and use the "official" title.
If we ever change plural↔singular, we should use the same form everywhere.
Kai Lüke
Vitaly Kuznetsov
Luca Boccassi
Kai Lueke
Lennart Poettering
Pascal Bachor
Emanuele Giuseppe Esposito
Jan Engelhardt
Yu Watanabe
Štěpán Němec
Sam Leonard
Krzesimir Nowak
cunshunxia
Thilo Fromm
David Tardon
Zbigniew Jędrzejewski-Szmek
Abderrahim Kitouni
Mathieu Tortuyaux
Antonio Alvarez Feijoo
Luca Boccassi
maanyagoenka
Javkhlanbayar Khongorzul