NSS-SYSTEMD(8)

📦
version 259.10 · 16 versions
, in fedora 44

💅 NAME (aka who is she)

okay so bestie, this is nss-systemd and libnss_systemd.so.2 — the UNIX user and group name resolution plug-in for user/group lookup via Varlink. yes that's a lot of words, we'll get there 🫶

✨ SYNOPSIS ✨

libnss_systemd.so.2

that's it. that's the whole synopsis. iconic minimalism 💅

🌸 DESCRIPTION 🌸

so nss-systemd is a plug-in module for the GNU Name Service Switch (NSS) functionality of the GNU C Library (glibc) — say that five times fast, or don't, no pressure 🙈 — and what it does is provide UNIX user and group name resolution for services implementing the User/Group Record Lookup API via Varlink[1]. like, services such as the system and service manager systemd(1) (for its DynamicUser= feature, see systemd.exec(5) for details), systemd-homed.service(8), or systemd-machined.service(8). slay, honestly.

this module also makes sure — like, guarantees — that the root and nobody users and groups (that's the users/groups with the UIDs/GIDs 0 and 65534) stay resolvable at all times, even if they're not listed in /etc/passwd or /etc/group, or if those files are just... missing. gone. not there. 💀 it still finds them. main character energy fr.

also?? it preferably utilizes systemd-userdbd.service(8) for resolving users and groups, but it also works without the service running. lowkey flexible of her.

to activate the NSS module, add "systemd" to the lines starting with "passwd:", "group:", "shadow:" and "gshadow:" in /etc/nsswitch.conf.

highly recommend 💖 putting "systemd" after the "files" entry of the /etc/nsswitch.conf lines, so that the /etc/passwd, /etc/group, /etc/shadow and /etc/gshadow based mappings take precedence. order matters, bestie.

🦋 STATIC DROP-IN JSON USER/GROUP RECORDS 🦋

so besides the user/group records you get via the aforementioned Varlink IPC interfaces, and besides the synthesized root and nobody accounts, this module also makes user and group accounts available to the system that are defined in static drop-in files in the /etc/userdb/, /run/userdb/, /run/host/userdb/ and /usr/lib/userdb/ directories. yes, four directories. she's thorough. 💅

the simple version

this is a simple mechanism to provide static user and group records via JSON drop-in files. ✨

user records should be defined in the format described by the JSON User Records[2] specification, and placed in one of the aforementioned directories under a file name composed of the user name suffixed with .user, with a world-readable access mode. 🌈

you should also create a symlink named after the user record's UID formatted in decimal and suffixed with .user, pointing to the primary record file — that way both lookups by username and by UID work. best of both worlds, we love to see it. 🎀

privileged user record data (e.g. hashed UNIX passwords) may optionally be provided as well, in a pair of separate companion files with the .user-privileged suffix. the data should be stored in a regular file named after the user name, suffixed with .user-privileged, plus a symlink pointing to it, named after the used numeric UID formatted in decimal with the same suffix.

those companion files should not be readable to anyone but root. 🔒 periodt. keep your secrets.

example, because visuals help:

-rw-r--r--. 1 root root  723 May 10 foobar.user
-rw-------. 1 root root  123 May 10 foobar.user-privileged
lrwxrwxrwx. 1 root root   19 May 10 4711.user -> foobar.user
lrwxrwxrwx. 1 root root   19 May 10 4711.user-privileged -> foobar.user-privileged

groups, same vibe

similarly, group records following the format described in JSON Group Record[3] may be defined, using the file suffixes .group and .group-privileged. 💜

the primary user/group record files (i.e. those with the .user and .group suffixes) should not contain the "privileged" section as described in the specifications. the privileged user/group record files (i.e. those with the .user-privileged and .group-privileged suffixes) should contain this section, exclusively. don't mix them, it's giving messy. 🙈

the fifth file type (plot twist)

in addition to the two types of user record files and the two types of group record files, there's a fifth type of file that may be placed in the searched directories: files that indicate membership of users in groups. 👑

specifically, for every pair of user/group where the user shall be a member of a group, a file named "username:groupname.membership" must be created — i.e. the textual UNIX user name, followed by a colon, followed by the textual UNIX group name, suffixed by .membership.

the contents of these files are currently not read, however it is recommended to create them containing an empty JSON object (i.e. "{}"). the mere existence of these files is enough to affect a user/group membership. ✨

heads up: if a program provides user and/or group record files in the searched directories, it must always also create such files — both for primary and auxiliary group memberships. no skipping. 🫶

conflict warning ⚠️

note that static user/group records generally do not override conflicting records in /etc/passwd or /etc/group or other account databases. in fact, before dropping in these files, a reasonable level of care should be taken to avoid user/group name and UID/GID conflicts. like, actually check. be careful. 🥺

the systemd-userdb-load-credentials.service service automatically runs at boot and installs these files from user records passed in via system credentials. see userdbctl(1) and systemd.system-credentials(7) for details. 💖

🧚 CONFIGURATION IN /ETC/NSSWITCH.CONF 🧚

here's an example /etc/nsswitch.conf file that enables nss-systemd correctly — copy-paste responsibly:

passwd:         files systemd
group:          files [SUCCESS=merge] systemd
shadow:         files systemd
gshadow:        files systemd

hosts:          mymachines resolve [!UNAVAIL=return] files myhostname dns
networks:       files

protocols:      db files
services:       db files
ethers:         db files
rpc:            db files

netgroup:       nis

look at her go 😌 the [SUCCESS=merge] on group: is doing so much work, we stan.

🔥 EXAMPLE: MAPPINGS PROVIDED BY SYSTEMD-MACHINED.SERVICE 🔥

okay this is the fun one. the container "rawhide" is spawned using systemd-nspawn(1):

# systemd-nspawn -M rawhide --boot --network-veth --private-users=pick
Spawning container rawhide on /var/lib/machines/rawhide.
Selected user namespace base 20119552 and range 65536.
...

$ machinectl --max-addresses=3
MACHINE CLASS     SERVICE        OS     VERSION ADDRESSES
rawhide container systemd-nspawn fedora 30      169.254.40.164 fe80::94aa:3aff:fe7b:d4b9

$ getent passwd vu-rawhide-0 vu-rawhide-81
vu-rawhide-0:*:20119552:65534:vu-rawhide-0:/:/usr/sbin/nologin
vu-rawhide-81:*:20119633:65534:vu-rawhide-81:/:/usr/sbin/nologin

$ getent group vg-rawhide-0 vg-rawhide-81
vg-rawhide-0:*:20119552:
vg-rawhide-81:*:20119633:

$ ps -o user:15,pid,tty,command -e|grep '^vu-rawhide'
vu-rawhide-0      692 ?        /usr/lib/systemd/systemd
vu-rawhide-0      731 ?        /usr/lib/systemd/systemd-journald
vu-rawhide-192    734 ?        /usr/lib/systemd/systemd-networkd
vu-rawhide-193    738 ?        /usr/lib/systemd/systemd-resolved
vu-rawhide-0      742 ?        /usr/lib/systemd/systemd-logind
vu-rawhide-81     744 ?        /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation --syslog-only
vu-rawhide-0      746 ?        /usr/sbin/sshd -D ...
vu-rawhide-0      752 ?        /usr/lib/systemd/systemd --user
vu-rawhide-0      753 ?        (sd-pam)
vu-rawhide-0     1628 ?        login -- zbyszek
vu-rawhide-1000  1630 ?        /usr/lib/systemd/systemd --user
vu-rawhide-1000  1631 ?        (sd-pam)
vu-rawhide-1000  1637 pts/8    -zsh

like??? the UIDs just work. no cap, this is the whole point of the module and it ate. 👑✨

🎀 SEE ALSO 🎀

systemd(1), systemd.exec(5), nss-resolve(8), nss-myhostname(8), nss-mymachines(8), systemd-userdbd.service(8), systemd-homed.service(8), systemd-machined.service(8), userdbctl(1), systemd.system-credentials(7), nsswitch.conf(5), getent(1)

go read them, they're all bangers. 🌈

⭐ NOTES ⭐

  1. User/Group Record Lookup API via Varlink https://systemd.io/USER_GROUP_API
  2. JSON User Records https://systemd.io/USER_RECORD
  3. JSON Group Record https://systemd.io/GROUP_RECORD

okay that's the whole page bestie!! 💖✨🎀🦋🌸

this little masterpiece ships with systemd 259.10 and lives under the manual name NSS-SYSTEMD(8) — like, that's her whole government name, no nickname needed. go forth and resolve users and groups, you're gonna do amazing 🫶💅👑

📦 where this page comes from