doc: clarify at which point user/group name resolution needs to work (#8884)

Prompted by the discussions on:

https://bugs.freedesktop.org/show_bug.cgi?id=106339

diff --git a/doc/UIDS-GIDS.md b/doc/UIDS-GIDS.md
index e19cc88162378b40c935639daa69c9f64923b8cc..c380bbe140a92da00615e5a7cdd2913588c047ff 100644 (file)
--- a/doc/UIDS-GIDS.md
+++ b/doc/UIDS-GIDS.md
@@ -241,3 +241,38 @@ really unused. It just means that these ranges have no well-established
 pre-defined purposes between Linux, generic low-level distributions and
 `systemd`. There might very well be other packages that allocate from these
 ranges.
+
+## Notes on resolvability of user and group names
+
+User names, UIDs, group names and GIDs don't have to be resolvable using NSS
+(i.e. getpwuid() and getpwnam() and friends) all the time. However, systemd
+makes the following requirements:
+
+System users generally have to be resolvable during early boot already. This
+means they should not be provided by any networked service (as those usually
+become available during late boot only), except if a local cache is kept that
+makes them available during early boot too (i.e. before networking is
+up). Specifically, system users need to be resolvable at least before
+`systemd-udevd.service` and `systemd-tmpfiles.service` are started, as both
+need to resolve system users — but note that there might be more services
+requiring full resolvability of system users than just these two.
+
+Regular users do not need to be resolvable during early boot, it is sufficient
+if they become resolvable during late boot. Specifically, regular users need to
+be resolvable at the point in time the `nss-user-lookup.target` unit is
+reached. This target unit is generally used as synchronization point between
+providers of the user database and consumers of it. Services that require that
+the user database is fully available (for example, the login service
+`systemd-logind.service`) are ordered *after* it, while services that provide
+parts of the user database (for example an LDAP user database client) are
+ordered *before* it. Note that `nss-user-lookup.target` is a *passive* unit: in
+order to minimize synchronization points on systems that don't need it the unit
+is pulled into the initial transaction only if there's at least one service
+that really needs it, and that means only if there's a service providing the
+local user database somehow through IPC or suchlike. Or in other words: if you
+hack on some networked user database project, then make sure you order your
+service `Before=nss-user-lookup.target` and that you pull it in with
+`Wants=nss-user-lookup.target`. However, if you hack on some project that needs
+the user database to be up in full, then order your service
+`After=nss-user-lookup.target`, but do *not* pull it in via a `Wants=`
+dependency.

diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index 4f96c3c4e68470aee16700a1005b431c9487f067..b6ac433f9c8789c1f07106eb759c4caa2ce72556 100644 (file)
--- a/man/systemd.special.xml
+++ b/man/systemd.special.xml
@@ -866,31 +866,24 @@
       <varlistentry>
         <term><filename>nss-lookup.target</filename></term>
         <listitem>
-          <para>A target that should be used as synchronization point
-          for all host/network name service lookups. Note that this is
-          independent of user/group name lookups for which
-          <filename>nss-user-lookup.target</filename> should be used.
-          All services for which the availability of full host/network
-          name resolution is essential should be ordered after this
-          target, but not pull it in. systemd automatically adds
-          dependencies of type <varname>After=</varname> for this
-          target unit to all SysV init script service units with an
-          LSB header referring to the <literal>$named</literal>
-          facility.</para>
+          <para>A target that should be used as synchronization point for all host/network name service lookups. Note
+          that this is independent of UNIX user/group name lookups for which <filename>nss-user-lookup.target</filename>
+          should be used.  All services for which the availability of full host/network name resolution is essential
+          should be ordered after this target, but not pull it in. systemd automatically adds dependencies of type
+          <varname>After=</varname> for this target unit to all SysV init script service units with an LSB header
+          referring to the <literal>$named</literal> facility.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
         <term><filename>nss-user-lookup.target</filename></term>
         <listitem>
-          <para>A target that should be used as synchronization point
-          for all user/group name service lookups. Note that this is
-          independent of host/network name lookups for which
-          <filename>nss-lookup.target</filename> should be used. All
-          services for which the availability of the full user/group
-          database is essential should be ordered after this target,
-          but not pull it in. Note that system users are always
-          resolvable, and hence do not require any special ordering
-          against this target.</para>
+          <para>A target that should be used as synchronization point for all regular UNIX user/group name service
+          lookups. Note that this is independent of host/network name lookups for which
+          <filename>nss-lookup.target</filename> should be used. All services for which the availability of the full
+          user/group database is essential should be ordered after this target, but not pull it in. All services which
+          provide parts of the user/group database should be ordered before this target, and pull it in. Note that this
+          unit is only relevant for regular users and groups — system users and groups are required to be resolvable
+          during earliest boot already, and hence do not need any special ordering against this target.</para>
         </listitem>
       </varlistentry>
       <varlistentry>