From 7ea5e82f6ac78704f1554be9040b84bac75c2ec1 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 28 Oct 2021 10:45:02 +0200 Subject: [PATCH 1/4] man: clarify the situation of unit templates regarding "systemctl list-units" + "systemctl list-unit-files" Fixes: #21075 --- man/systemctl.xml | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/man/systemctl.xml b/man/systemctl.xml index 5a133dea75..b6be21ed87 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -65,6 +65,13 @@ that are shown are additionally filtered by and if those options are specified. + Note that this command does not show unit templates, but only instances of unit + templates. Units templates that aren't instantiated are not runnable, and will thus never show up + in the output of this command. Specifically this means that foo@.service + will never be shown in this list — unless instantiated, e.g. as + foo@bar.service. Use list-unit-files (see below) for + listing installed unit template files. + Produces output similar to UNIT LOAD ACTIVE SUB DESCRIPTION sys-module-fuse.device loaded active plugged /sys/module/fuse @@ -81,11 +88,11 @@ ACTIVE = The high-level unit activation state, i.e. generalization of SUB. SUB = The low-level unit activation state, values depend on unit type. 123 loaded units listed. Pass --all to see loaded but inactive units, too. -To show all installed unit files use 'systemctl list-unit-files'. - - The header and the last unit of a given type are underlined if the - terminal supports that. A colored dot is shown next to services which - were masked, not found, or otherwise failed. +To show all installed unit files use 'systemctl list-unit-files'. + + The header and the last unit of a given type are underlined if the terminal supports + that. A colored dot is shown next to services which were masked, not found, or otherwise + failed. The LOAD column shows the load state, one of loaded, not-found, bad-setting, error, @@ -694,10 +701,13 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err list-unit-files PATTERN… - List unit files installed on the system, in combination with their enablement state (as reported by - is-enabled). If one or more PATTERNs are specified, only unit - files whose name matches one of them are shown (patterns matching unit file system paths are not - supported). + List unit files installed on the system, in combination with their enablement state (as + reported by is-enabled). If one or more PATTERNs + are specified, only unit files whose name matches one of them are shown (patterns matching unit + file system paths are not supported). + + Unlike list-units this command will list template units in addition to + explicitly instantiated units. From c04358ce84c5122f78b5a37e9e60ac951580c698 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 28 Oct 2021 10:51:12 +0200 Subject: [PATCH 2/4] docs: document $PASSWORD in ENVIRONMENT.md Fixes: #20955 --- docs/ENVIRONMENT.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md index 5e6685215b..565a2e46bd 100644 --- a/docs/ENVIRONMENT.md +++ b/docs/ENVIRONMENT.md @@ -386,3 +386,18 @@ disk images with `--image=` or similar: whether to use the libcryptsetup "token" plugin module logic even when activating via FIDO2, PKCS#11, TPM2, i.e. mechanisms natively supported by `systemd-cryptsetup`. Defaults to enabled. + +Various tools that read passwords from the TTY, such as `systemd-cryptenroll` +and `homectl`: + +* `$PASSWORD` — takes a string: the literal password to use. If this + environment variable is set it is used as password instead of prompting the + user interactively. This exists primarily for debugging and testing + purposes. Do not use this for production code paths, since environment + variables are typically inherited down the process tree without restrictions + and should thus not be used for secrets. + +* `$NEWPASSWORD` — similar to `$PASSWORD` above, but is used when both a + current and a future password are required, for example if the password is to + be changed. In that case `$PASSWORD` shall carry the current (i.e. old) + password and `$NEWPASSWORD` the new. From 1d697549887d68953058049fcd833fa93a74402a Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 28 Oct 2021 10:53:55 +0200 Subject: [PATCH 3/4] man: document how nss-resolve and systemd-resolved communicate Fixes: #20925 --- man/nss-resolve.xml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/man/nss-resolve.xml b/man/nss-resolve.xml index 81f9fdae8c..b56ac5c129 100644 --- a/man/nss-resolve.xml +++ b/man/nss-resolve.xml @@ -58,6 +58,10 @@ hostnames. If you rely on that lookup being provided by DNS, you might want to order things differently. + + Communication between nss-resolve and + systemd-resolved.service takes place via the + /run/systemd/resolve/io.systemd.Resolve AF_UNIX socket. From c896eb7ad65f4dbe968fdf01fa51e9ef4d2d11ed Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 28 Oct 2021 11:05:22 +0200 Subject: [PATCH 4/4] man: document that daemons can close fds they receive via sd_listen_fds() if they like Fixes: #18872 --- man/sd_listen_fds.xml | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml index 9ddd129aae..a71c291adf 100644 --- a/man/sd_listen_fds.xml +++ b/man/sd_listen_fds.xml @@ -45,14 +45,24 @@ Description - sd_listen_fds() may be invoked by a - daemon to check for file descriptors passed by the service manager as - part of the socket-based activation logic. It returns the number - of received file descriptors. If no file descriptors have been - received, zero is returned. The first file descriptor may be found - at file descriptor number 3 - (i.e. SD_LISTEN_FDS_START), the remaining - descriptors follow at 4, 5, 6, …, if any. + sd_listen_fds() may be invoked by a daemon to check for file descriptors + passed by the service manager as part of the socket-based activation logic. It returns the number of + received file descriptors. If no file descriptors have been received, zero is returned. The first file + descriptor may be found at file descriptor number 3 (i.e. SD_LISTEN_FDS_START), the + remaining descriptors follow at 4, 5, 6, …, if any. + + The file descriptors passed this way may be closed at will by the processes receiving them: it's up + to the processes themselves to close them after use or whether to leave them open until the process exits + (in which case the kernel closes them automatically). Note that the file descriptors received by daemons + are duplicates of the file descriptors the service manager originally allocated and bound and of which it + continously keeps a copy (except if Accept=yes is used). This means any socket option + changes and other changes made to the sockets will visible to the service manager too. Most importanly + this means it's generally not a good idea to invoke shutdown2 on + such sockets, since it will shut down communication on the file descriptor the service manager holds for + the same socket, too. Also note that if a daemon is restarted (and its associated sockets are not) it + will receive file descriptors to the very same sockets as the earlier invocations, thus all socket + options applied then will still apply. If a daemon receives more than one file descriptor, they will be passed in the same order as configured in the systemd socket unit file (see