From bf613f7acc32ceddc063377c8e2fe958d4380656 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 7 May 2018 14:49:16 +0200 Subject: [PATCH] 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 --- doc/UIDS-GIDS.md | 35 +++++++++++++++++++++++++++++++++++ man/systemd.special.xml | 33 +++++++++++++-------------------- 2 files changed, 48 insertions(+), 20 deletions(-) diff --git a/doc/UIDS-GIDS.md b/doc/UIDS-GIDS.md index e19cc88162..c380bbe140 100644 --- 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 4f96c3c4e6..b6ac433f9c 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -866,31 +866,24 @@ nss-lookup.target - 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 - nss-user-lookup.target 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 After= for this - target unit to all SysV init script service units with an - LSB header referring to the $named - facility. + 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 nss-user-lookup.target + 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 + After= for this target unit to all SysV init script service units with an LSB header + referring to the $named facility. nss-user-lookup.target - 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 - nss-lookup.target 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. + 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 + nss-lookup.target 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.