Merge pull request #21167 from poettering/various-doc-tweaks

Four documentation tweaks

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.

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.
     </para>
+
+    <para>Communication between <command>nss-resolve</command> and
+    <filename>systemd-resolved.service</filename> takes place via the
+    <filename>/run/systemd/resolve/io.systemd.Resolve</filename> <constant>AF_UNIX</constant> socket.</para>
   </refsect1>
 
   <refsect1>

man/sd_listen_fds.xml

@@ -45,14 +45,24 @@
   <refsect1>
     <title>Description</title>
 
-    <para><function>sd_listen_fds()</function> 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. <constant>SD_LISTEN_FDS_START</constant>), the remaining
-    descriptors follow at 4, 5, 6, …, if any.</para>
+    <para><function>sd_listen_fds()</function> 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. <constant>SD_LISTEN_FDS_START</constant>), the
+    remaining descriptors follow at 4, 5, 6, …, if any.</para>
+
+    <para>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 <varname>Accept=yes</varname> 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 <citerefentry
+    project='man-pages'><refentrytitle>shutdown</refentrytitle><manvolnum>2</manvolnum></citerefentry> 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.</para>
 
     <para>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

man/systemctl.xml

@@ -65,6 +65,13 @@
             that are shown are additionally filtered by <option>--type=</option> and <option>--state=</option> if those
             options are specified.</para>
 
+            <para>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 <filename>foo@.service</filename>
+            will never be shown in this list — unless instantiated, e.g. as
+            <filename>foo@bar.service</filename>. Use <command>list-unit-files</command> (see below) for
+            listing installed unit template files.</para>
+
             <para>Produces output similar to
             <programlisting>  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'.
-            </programlisting>
-            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.</para>
+To show all installed unit files use 'systemctl list-unit-files'.</programlisting></para>
+
+            <para>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.</para>
 
             <para>The LOAD column shows the load state, one of <constant>loaded</constant>,
             <constant>not-found</constant>, <constant>bad-setting</constant>, <constant>error</constant>,
@@ -694,10 +701,13 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
           <term><command>list-unit-files</command> <optional><replaceable>PATTERN…</replaceable></optional></term>
 
           <listitem>
-            <para>List unit files installed on the system, in combination with their enablement state (as reported by
-            <command>is-enabled</command>). If one or more <replaceable>PATTERN</replaceable>s are specified, only unit
-            files whose name matches one of them are shown (patterns matching unit file system paths are not
-            supported).</para>
+            <para>List unit files installed on the system, in combination with their enablement state (as
+            reported by <command>is-enabled</command>). If one or more <replaceable>PATTERN</replaceable>s
+            are specified, only unit files whose name matches one of them are shown (patterns matching unit
+            file system paths are not supported).</para>
+
+            <para>Unlike <command>list-units</command> this command will list template units in addition to
+            explicitly instantiated units.</para>
           </listitem>
         </varlistentry>