Debian Codegraph @

upstream/debian-unstable/man8/nss-systemd.8

raw
1 '\" t
2 .TH "NSS\-SYSTEMD" "8" "" "systemd 261~rc3" "nss-systemd"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 nss-systemd, libnss_systemd.so.2 \- UNIX user and group name resolution for user/group lookup via Varlink
24 .SH "SYNOPSIS"
25 .PP
26 libnss_systemd\&.so\&.2
27 .SH "DESCRIPTION"
28 .PP
29 \fBnss\-systemd\fR
30 is a plug\-in module for the GNU Name Service Switch (NSS) functionality of the GNU C Library (\fBglibc\fR), providing UNIX user and group name resolution for services implementing the
31 \m[blue]\fBUser/Group Record Lookup API via Varlink\fR\m[]\&\s-2\u[1]\d\s+2, such as the system and service manager
32 \fBsystemd\fR(1)
33 (for its
34 \fIDynamicUser=\fR
35 feature, see
36 \fBsystemd.exec\fR(5)
37 for details),
38 \fBsystemd-homed.service\fR(8), or
39 \fBsystemd-machined.service\fR(8)\&.
40 .PP
41 This module also ensures that the root and nobody users and groups (i\&.e\&. the users/groups with the UIDs/GIDs 0 and 65534) remain resolvable at all times, even if they are not listed in
42 /etc/passwd
43 or
44 /etc/group, or if these files are missing\&.
45 .PP
46 This module preferably utilizes
47 \fBsystemd-userdbd.service\fR(8)
48 for resolving users and groups, but also works without the service running\&.
49 .PP
50 To activate the NSS module, add
51 "systemd"
52 to the lines starting with
53 "passwd:",
54 "group:",
55 "shadow:"
56 and
57 "gshadow:"
58 in
59 /etc/nsswitch\&.conf\&.
60 .PP
61 It is recommended to place
62 "systemd"
63 after the
64 "files"
65 entry of the
66 /etc/nsswitch\&.conf
67 lines so that
68 /etc/passwd,
69 /etc/group,
70 /etc/shadow
71 and
72 /etc/gshadow
73 based mappings take precedence\&.
74 .SH "STATIC DROP\-IN JSON USER/GROUP RECORDS"
75 .PP
76 Besides user/group records acquired via the aforementioned Varlink IPC interfaces and 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
77 /etc/userdb/,
78 /run/userdb/,
79 /run/host/userdb/
80 and
81 /usr/lib/userdb/
82 directories\&.
83 .PP
84 This is a simple mechanism to provide static user and group records via JSON drop\-in files\&. Such user records should be defined in the format described by the
85 \m[blue]\fBJSON User Records\fR\m[]\&\s-2\u[2]\d\s+2
86 specification and be placed in one of the aforementioned directories under a file name composed of the user name suffixed with
87 \&.user, with a world\-readable access mode\&. A symlink named after the user record\*(Aqs UID formatted in decimal and suffixed with
88 \&.user
89 pointing to the primary record file should be created as well, in order to allow both lookups by username and by UID\&. Privileged user record data (e\&.g\&. hashed UNIX passwords) may optionally be provided as well, in a pair of separate companion files with the
90 \&.user\-privileged
91 suffix\&. The data should be stored in a regular file named after the user name, suffixed with
92 \&.user\-privileged, and a symlink pointing to it, named after the used numeric UID formatted in decimal with the same suffix\&. These companion files should not be readable to anyone but root\&. Example:
93 .sp
94 .if n \{\
95 .RS 4
96 .\}
97 .nf
98 \-rw\-r\-\-r\-\-\&. 1 root root 723 May 10 foobar\&.user
99 \-rw\-\-\-\-\-\-\-\&. 1 root root 123 May 10 foobar\&.user\-privileged
100 lrwxrwxrwx\&. 1 root root 19 May 10 4711\&.user \-> foobar\&.user
101 lrwxrwxrwx\&. 1 root root 19 May 10 4711\&.user\-privileged \-> foobar\&.user\-privileged
102 .fi
103 .if n \{\
104 .RE
105 .\}
106 .PP
107 Similarly, group records following the format described in
108 \m[blue]\fBJSON Group Record\fR\m[]\&\s-2\u[3]\d\s+2
109 may be defined, using the file suffixes
110 \&.group
111 and
112 \&.group\-privileged\&.
113 .PP
114 The primary user/group record files (i\&.e\&. those with the
115 \&.user
116 and
117 \&.group
118 suffixes) should not contain the
119 "privileged"
120 section as described in the specifications\&. The privileged user/group record files (i\&.e\&. those with the
121 \&.user\-privileged
122 and
123 \&.group\-privileged
124 suffixes) should contain this section, exclusively\&.
125 .PP
126 In addition to the two types of user record files and the two types of group record files there\*(Aqs 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
127 "\fIusername\fR:\fIgroupname\fR\&.membership"
128 must be created, i\&.e\&. the textual UNIX user name, followed by a colon, followed by the textual UNIX group name, suffixed by
129 "\&.membership"\&. The contents of these files are currently not read, however it is recommended to create them containing an empty JSON object (i\&.e\&.
130 "{}")\&. The mere existence of these files is enough to affect a user/group membership\&. 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\&.
131 .PP
132 Note that static user/group records generally do not override conflicting records in
133 /etc/passwd
134 or
135 /etc/group
136 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\&.
137 .PP
138 The
139 systemd\-userdb\-load\-credentials\&.service
140 service automatically runs at boot and installs these files from user records passed in via system credentials\&. See
141 \fBuserdbctl\fR(1)
142 and
143 \fBsystemd.system-credentials\fR(7)
144 for details\&.
145 .SH "CONFIGURATION IN /ETC/NSSWITCH\&.CONF"
146 .PP
147 Here is an example
148 /etc/nsswitch\&.conf
149 file that enables
150 \fBnss\-systemd\fR
151 correctly:
152 .sp
153 .if n \{\
154 .RS 4
155 .\}
156 .nf
157 passwd: files \fBsystemd\fR
158 group: files \fB[SUCCESS=merge] systemd\fR
159 shadow: files \fBsystemd\fR
160 gshadow: files \fBsystemd\fR
161
162 hosts: mymachines resolve [!UNAVAIL=return] files myhostname dns
163 networks: files
164
165 protocols: db files
166 services: db files
167 ethers: db files
168 rpc: db files
169
170 netgroup: nis
171 .fi
172 .if n \{\
173 .RE
174 .\}
175 .SH "EXAMPLE: MAPPINGS PROVIDED BY SYSTEMD\-MACHINED\&.SERVICE"
176 .PP
177 The container
178 "rawhide"
179 is spawned using
180 \fBsystemd-nspawn\fR(1):
181 .sp
182 .if n \{\
183 .RS 4
184 .\}
185 .nf
186 # systemd\-nspawn \-M rawhide \-\-boot \-\-network\-veth \-\-private\-users=pick
187 Spawning container rawhide on /var/lib/machines/rawhide\&.
188 Selected user namespace base 20119552 and range 65536\&.
189 \&.\&.\&.
190
191 $ machinectl \-\-max\-addresses=3
192 MACHINE CLASS SERVICE OS VERSION ADDRESSES
193 rawhide container systemd\-nspawn fedora 30 169\&.254\&.40\&.164 fe80::94aa:3aff:fe7b:d4b9
194
195 $ getent passwd vu\-rawhide\-0 vu\-rawhide\-81
196 vu\-rawhide\-0:*:20119552:65534:vu\-rawhide\-0:/:/usr/sbin/nologin
197 vu\-rawhide\-81:*:20119633:65534:vu\-rawhide\-81:/:/usr/sbin/nologin
198
199 $ getent group vg\-rawhide\-0 vg\-rawhide\-81
200 vg\-rawhide\-0:*:20119552:
201 vg\-rawhide\-81:*:20119633:
202
203 $ ps \-o user:15,pid,tty,command \-e|grep \*(Aq^vu\-rawhide\*(Aq
204 vu\-rawhide\-0 692 ? /usr/lib/systemd/systemd
205 vu\-rawhide\-0 731 ? /usr/lib/systemd/systemd\-journald
206 vu\-rawhide\-192 734 ? /usr/lib/systemd/systemd\-networkd
207 vu\-rawhide\-193 738 ? /usr/lib/systemd/systemd\-resolved
208 vu\-rawhide\-0 742 ? /usr/lib/systemd/systemd\-logind
209 vu\-rawhide\-81 744 ? /usr/bin/dbus\-daemon \-\-system \-\-address=systemd: \-\-nofork \-\-nopidfile \-\-systemd\-activation \-\-syslog\-only
210 vu\-rawhide\-0 746 ? /usr/sbin/sshd \-D \&.\&.\&.
211 vu\-rawhide\-0 752 ? /usr/lib/systemd/systemd \-\-user
212 vu\-rawhide\-0 753 ? (sd\-pam)
213 vu\-rawhide\-0 1628 ? login \-\- zbyszek
214 vu\-rawhide\-1000 1630 ? /usr/lib/systemd/systemd \-\-user
215 vu\-rawhide\-1000 1631 ? (sd\-pam)
216 vu\-rawhide\-1000 1637 pts/8 \-zsh
217 .fi
218 .if n \{\
219 .RE
220 .\}
221 .SH "SEE ALSO"
222 .PP
223 \fBsystemd\fR(1), \fBsystemd.exec\fR(5), \fBnss-resolve\fR(8), \fBnss-myhostname\fR(8), \fBnss-mymachines\fR(8), \fBsystemd-userdbd.service\fR(8), \fBsystemd-homed.service\fR(8), \fBsystemd-machined.service\fR(8), \fBuserdbctl\fR(1), \fBsystemd.system-credentials\fR(7), \fBnsswitch.conf\fR(5), \fBgetent\fR(1)
224 .SH "NOTES"
225 .IP " 1." 4
226 User/Group Record Lookup API via Varlink
227 .RS 4
228 \%https://systemd.io/USER_GROUP_API
229 .RE
230 .IP " 2." 4
231 JSON User Records
232 .RS 4
233 \%https://systemd.io/USER_RECORD
234 .RE
235 .IP " 3." 4
236 JSON Group Record
237 .RS 4
238 \%https://systemd.io/GROUP_RECORD
239 .RE