1<?xml version='1.0'?> <!--*-nxml-*--> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="nss-systemd" conditional='ENABLE_NSS_SYSTEMD'> 7 8 <refentryinfo> 9 <title>nss-systemd</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>nss-systemd</refentrytitle> 15 <manvolnum>8</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>nss-systemd</refname> 20 <refname>libnss_systemd.so.2</refname> 21 <refpurpose>UNIX user and group name resolution for user/group lookup via Varlink</refpurpose> 22 </refnamediv> 23 24 <refsynopsisdiv> 25 <para><filename>libnss_systemd.so.2</filename></para> 26 </refsynopsisdiv> 27 28 <refsect1> 29 <title>Description</title> 30 31 <para><command>nss-systemd</command> is a plug-in module for the GNU Name Service Switch (NSS) 32 functionality of the GNU C Library (<command>glibc</command>), providing UNIX user and group name 33 resolution for services implementing the <ulink url="https://systemd.io/USER_GROUP_API">User/Group Record 34 Lookup API via Varlink</ulink>, such as the system and service manager 35 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> (for its 36 <varname>DynamicUser=</varname> feature, see 37 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for 38 details), 39 <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, or <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> 40 41 <para>This module also ensures that the root and nobody users and groups (i.e. the users/groups with the UIDs/GIDs 42 0 and 65534) remain resolvable at all times, even if they aren't listed in <filename>/etc/passwd</filename> or 43 <filename>/etc/group</filename>, or if these files are missing.</para> 44 45 <para>This module preferably utilizes 46 <citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> 47 for resolving users and groups, but also works without the service running.</para> 48 49 <para>To activate the NSS module, add <literal>systemd</literal> to the lines starting with 50 <literal>passwd:</literal>, <literal>group:</literal>, <literal>shadow:</literal> and 51 <literal>gshadow:</literal> in <filename>/etc/nsswitch.conf</filename>.</para> 52 53 <para>It is recommended to place <literal>systemd</literal> after the <literal>files</literal> or 54 <literal>compat</literal> entry of the <filename>/etc/nsswitch.conf</filename> lines so that 55 <filename>/etc/passwd</filename>, <filename>/etc/group</filename>, <filename>/etc/shadow</filename> and 56 <filename>/etc/gshadow</filename> based mappings take precedence.</para> 57 </refsect1> 58 59 <refsect1> 60 <title>Static Drop-In JSON User/Group Records</title> 61 62 <para>Besides user/group records acquired via the aforementioned Varlink IPC interfaces and the 63 synthesized root and nobody accounts, this module also makes user and group accounts available to the 64 system that are defined in static drop-in files in the <filename>/etc/userdb/</filename>, 65 <filename>/run/userdb/</filename>, <filename>/run/host/userdb/</filename> and 66 <filename>/usr/lib/userdb/</filename> directories.</para> 67 68 <para>This is a simple mechanism to provide static user and group records via JSON drop-in files. Such 69 user records should be defined in the format described by the <ulink 70 url="https://systemd.io/USER_RECORD">JSON User Records</ulink> specification and be placed in one of the 71 aforementioned directories under a file name composed of the user name suffixed with 72 <filename>.user</filename>, with a world-readable access mode. A symlink named after the user record's 73 UID formatted in decimal and suffixed with <filename>.user</filename> pointing to the primary record file 74 should be created as well, in order to allow both lookups by username and by UID. Privileged user record 75 data (e.g. hashed UNIX passwords) may optionally be provided as well, in a pair of separate companion 76 files with the <filename>.user-privileged</filename> suffix. The data should be stored in a regular file 77 named after the user name, suffixed with <filename>.user-privileged</filename>, and a symlink pointing to 78 it, named after the used numeric UID formatted in decimal with the same suffix. These companion files 79 should not be readable to anyone but root. Example:</para> 80 81 <programlisting>-rw-r--r--. 1 root root 723 May 10 foobar.user 82-rw-------. 1 root root 123 May 10 foobar.user-privileged 83lrwxrwxrwx. 1 root root 19 May 10 4711.user -> foobar.user 84lrwxrwxrwx. 1 root root 19 May 10 4711.user-privileged -> foobar.user-privileged</programlisting> 85 86 <para>Similarly, group records following the format described in <ulink 87 url="https://systemd.io/GROUP_RECORD">JSON Group Record</ulink> may be defined, using the file suffixes 88 <filename>.group</filename> and <filename>.group-privileged</filename>.</para> 89 90 <para>The primary user/group record files (i.e. those with the <filename>.user</filename> and 91 <filename>.group</filename> suffixes) should not contain the <literal>privileged</literal> section as 92 described in the specifications. The privileged user/group record files (i.e. those with the 93 <filename>.user-privileged</filename> and <filename>.group-privileged</filename> suffixes) should 94 contain this section, exclusively.</para> 95 96 <para>Note that static user/group records generally do not override conflicting records in 97 <filename>/etc/passwd</filename> or <filename>/etc/group</filename> or other account databases. In fact, 98 before dropping in these files a reasonable level of care should be taken to avoid user/group name and 99 UID/GID conflicts.</para> 100 </refsect1> 101 102 <refsect1> 103 <title>Configuration in <filename>/etc/nsswitch.conf</filename></title> 104 105 <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables 106 <command>nss-systemd</command> correctly:</para> 107 108 <!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf --> 109 <programlisting>passwd: compat <command>systemd</command> 110group: compat [SUCCESS=merge] <command>systemd</command> 111shadow: compat <command>systemd</command> 112gshadow: files <command>systemd</command> 113 114hosts: mymachines resolve [!UNAVAIL=return] files myhostname dns 115networks: files 116 117protocols: db files 118services: db files 119ethers: db files 120rpc: db files 121 122netgroup: nis</programlisting> 123 124 </refsect1> 125 126 <refsect1> 127 <title>Example: Mappings provided by <filename>systemd-machined.service</filename></title> 128 129 <para>The container <literal>rawhide</literal> is spawned using 130 <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>: 131 </para> 132 133 <programlisting># systemd-nspawn -M rawhide --boot --network-veth --private-users=pick 134Spawning container rawhide on /var/lib/machines/rawhide. 135Selected user namespace base 20119552 and range 65536. 136... 137 138$ machinectl --max-addresses=3 139MACHINE CLASS SERVICE OS VERSION ADDRESSES 140rawhide container systemd-nspawn fedora 30 169.254.40.164 fe80::94aa:3aff:fe7b:d4b9 141 142$ getent passwd vu-rawhide-0 vu-rawhide-81 143vu-rawhide-0:*:20119552:65534:vu-rawhide-0:/:/usr/sbin/nologin 144vu-rawhide-81:*:20119633:65534:vu-rawhide-81:/:/usr/sbin/nologin 145 146$ getent group vg-rawhide-0 vg-rawhide-81 147vg-rawhide-0:*:20119552: 148vg-rawhide-81:*:20119633: 149 150$ ps -o user:15,pid,tty,command -e|grep '^vu-rawhide' 151vu-rawhide-0 692 ? /usr/lib/systemd/systemd 152vu-rawhide-0 731 ? /usr/lib/systemd/systemd-journald 153vu-rawhide-192 734 ? /usr/lib/systemd/systemd-networkd 154vu-rawhide-193 738 ? /usr/lib/systemd/systemd-resolved 155vu-rawhide-0 742 ? /usr/lib/systemd/systemd-logind 156vu-rawhide-81 744 ? /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation --syslog-only 157vu-rawhide-0 746 ? /usr/sbin/sshd -D ... 158vu-rawhide-0 752 ? /usr/lib/systemd/systemd --user 159vu-rawhide-0 753 ? (sd-pam) 160vu-rawhide-0 1628 ? login -- zbyszek 161vu-rawhide-1000 1630 ? /usr/lib/systemd/systemd --user 162vu-rawhide-1000 1631 ? (sd-pam) 163vu-rawhide-1000 1637 pts/8 -zsh 164</programlisting> 165 </refsect1> 166 167 <refsect1> 168 <title>See Also</title> 169 <para> 170 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 171 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 172 <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 173 <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 174 <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 175 <citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 176 <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 177 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 178 <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, 179 <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry> 180 </para> 181 </refsect1> 182 183</refentry> 184