Debian Codegraph @

upstream/debian-unstable/man5/nsswitch.conf.5

raw
1 .\" Copyright 2011, Mark R. Bannister <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH nsswitch.conf 5 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 nsswitch.conf \- Name Service Switch configuration file
9 .SH DESCRIPTION
10 The Name Service Switch (NSS) configuration file,
11 .IR /etc/nsswitch.conf ,
12 is used by the GNU C Library and certain other applications to determine
13 the sources from which to obtain name-service information in
14 a range of categories,
15 and in what order.
16 Each category of information is identified by a database name.
17 .P
18 The file is plain ASCII text, with columns separated by spaces or tab
19 characters.
20 The first column specifies the database name.
21 The remaining columns describe the order of sources to query and a
22 limited set of actions that can be performed by lookup result.
23 .P
24 The following databases are understood by the GNU C Library:
25 .TP 12
26 .B aliases
27 Mail aliases, used by
28 .BR getaliasent (3)
29 and related functions.
30 .TP
31 .B ethers
32 Ethernet numbers.
33 .TP
34 .B group
35 Groups of users, used by
36 .BR getgrent (3)
37 and related functions.
38 .TP
39 .B hosts
40 Host names and numbers, used by
41 .BR gethostbyname (3)
42 and related functions.
43 .TP
44 .B initgroups
45 Supplementary group access list, used by
46 .BR getgrouplist (3)
47 function.
48 .TP
49 .B netgroup
50 Network-wide list of hosts and users, used for access rules.
51 C libraries before glibc 2.1 supported netgroups only over NIS.
52 .TP
53 .B networks
54 Network names and numbers, used by
55 .BR getnetent (3)
56 and related functions.
57 .TP
58 .B passwd
59 User passwords, used by
60 .BR getpwent (3)
61 and related functions.
62 .TP
63 .B protocols
64 Network protocols, used by
65 .BR getprotoent (3)
66 and related functions.
67 .TP
68 .B publickey
69 Public and secret keys for Secure_RPC used by NFS and NIS+.
70 .TP
71 .B rpc
72 Remote procedure call names and numbers, used by
73 .BR getrpcbyname (3)
74 and related functions.
75 .TP
76 .B services
77 Network services, used by
78 .BR getservent (3)
79 and related functions.
80 .TP
81 .B shadow
82 Shadow user passwords, used by
83 .BR getspnam (3)
84 and related functions.
85 .P
86 The GNU C Library ignores databases with unknown names.
87 Some applications use this to implement special handling for their own
88 databases.
89 For example,
90 .BR sudo (8)
91 consults the
92 .B sudoers
93 database.
94 Delegation of subordinate user/group IDs
95 can be configured using the
96 .B subid
97 database.
98 Refer to
99 .BR subuid (5)
100 and
101 .BR subgid (5)
102 for more details.
103 .P
104 Here is an example
105 .I /etc/nsswitch.conf
106 file:
107 .P
108 .in +4n
109 .EX
110 passwd: compat
111 group: compat
112 shadow: compat
113 \&
114 hosts: dns [!UNAVAIL=return] files
115 networks: nis [NOTFOUND=return] files
116 ethers: nis [NOTFOUND=return] files
117 protocols: nis [NOTFOUND=return] files
118 rpc: nis [NOTFOUND=return] files
119 services: nis [NOTFOUND=return] files
120 .EE
121 .in
122 .P
123 The first column is the database name.
124 The remaining columns specify:
125 .IP \[bu] 3
126 One or more service specifications, for example, "files", "db", or "nis".
127 The order of the services on the line determines the order in which
128 those services will be queried, in turn, until a result is found.
129 .IP \[bu]
130 Optional actions to perform if a particular result is obtained
131 from the preceding service, for example, "[NOTFOUND=return]".
132 .P
133 The service specifications supported on your system depend on the
134 presence of shared libraries, and are therefore extensible.
135 Libraries called
136 .IB /lib/libnss_SERVICE.so. X
137 will provide the named
138 .IR SERVICE .
139 On a standard installation, you can use
140 "files", "db", "nis", and "nisplus".
141 For the
142 .B hosts
143 database, you can additionally specify "dns".
144 For the
145 .BR passwd ,
146 .BR group ,
147 and
148 .B shadow
149 databases, you can additionally specify
150 "compat" (see
151 .B "Compatibility mode"
152 below).
153 The version number
154 .B X
155 may be 1 for glibc 2.0, or 2 for glibc 2.1 and later.
156 On systems with additional libraries installed, you may have access to
157 further services such as "hesiod", "ldap", "winbind", and "wins".
158 .P
159 An action may also be specified following a service specification.
160 The action modifies the behavior following a result obtained
161 from the preceding data source.
162 Action items take the general form:
163 .P
164 .RS 4
165 .RI [ STATUS = ACTION ]
166 .br
167 .RI [! STATUS = ACTION ]
168 .RE
169 .P
170 where
171 .P
172 .RS 4
173 .I STATUS
174 =>
175 .B success
176 |
177 .B notfound
178 |
179 .B unavail
180 |
181 .B tryagain
182 .br
183 .I ACTION
184 =>
185 .B return
186 |
187 .B continue
188 |
189 .B merge
190 .RE
191 .P
192 The ! negates the test, matching all possible results except the
193 one specified.
194 The case of the keywords is not significant.
195 .P
196 The
197 .I STATUS
198 value is matched against the result of the lookup function called by
199 the preceding service specification, and can be one of:
200 .RS 4
201 .TP 12
202 .B success
203 No error occurred and the requested entry is returned.
204 The default action for this condition is "return".
205 .TP
206 .B notfound
207 The lookup succeeded, but the requested entry was not found.
208 The default action for this condition is "continue".
209 .TP
210 .B unavail
211 The service is permanently unavailable.
212 This can mean either that the
213 required file cannot be read, or, for network services, that the server
214 is not available or does not allow queries.
215 The default action for this condition is "continue".
216 .TP
217 .B tryagain
218 The service is temporarily unavailable.
219 This could mean a file is
220 locked or a server currently cannot accept more connections.
221 The default action for this condition is "continue".
222 .RE
223 .P
224 The
225 .I ACTION
226 value can be one of:
227 .RS 4
228 .TP 12
229 .B return
230 Return a result now.
231 Do not call any further lookup functions.
232 However, for compatibility reasons, if this is the selected action for the
233 .B group
234 database and the
235 .B notfound
236 status, and the configuration file does not contain the
237 .B initgroups
238 line, the next lookup function is always called,
239 without affecting the search result.
240 .TP
241 .B continue
242 Call the next lookup function.
243 .TP
244 .B merge
245 .I [SUCCESS=merge]
246 is used between two database entries.
247 When a group is located in the first of the two group entries,
248 processing will continue on to the next one.
249 If the group is also found in the next entry (and the group name and GID
250 are an exact match), the member list of the second entry will be added
251 to the group object to be returned.
252 Available since glibc 2.24.
253 Note that merging will not be done for
254 .BR getgrent (3)
255 nor will duplicate members be pruned when they occur in both entries
256 being merged.
257 .RE
258 .SS Compatibility mode (compat)
259 The NSS "compat" service is similar to "files" except that it
260 additionally permits special entries in corresponding files
261 for granting users or members of netgroups access to the system.
262 The following entries are valid in this mode:
263 .RS 4
264 .P
265 For
266 .B passwd
267 and
268 .B shadow
269 databases:
270 .RS 4
271 .TP 12
272 .BI + user
273 Include the specified
274 .I user
275 from the NIS passwd/shadow map.
276 .TP
277 .BI + user::::::
278 Include the specified
279 .I user
280 from the NIS passwd map, but override with non-empty passwd fields.
281 .TP
282 .BI +@ netgroup
283 Include all users in the given
284 .IR netgroup .
285 .TP
286 .BI \- user
287 Exclude the specified
288 .I user
289 from the NIS passwd/shadow map.
290 .TP
291 .BI \-@ netgroup
292 Exclude all users in the given
293 .IR netgroup .
294 .TP
295 .B +
296 Include every user, except previously excluded ones, from the
297 NIS passwd/shadow map.
298 .RE
299 .P
300 For
301 .B group
302 database:
303 .RS 4
304 .TP 12
305 .BI + group
306 Include the specified
307 .I group
308 from the NIS group map.
309 .TP
310 .BI \- group
311 Exclude the specified
312 .I group
313 from the NIS group map.
314 .TP
315 .B +
316 Include every group, except previously excluded ones, from the
317 NIS group map.
318 .RE
319 .RE
320 .P
321 By default, the source is "nis", but this may be
322 overridden by specifying any NSS service except "compat" itself
323 as the source for the pseudo-databases
324 .BR passwd_compat ,
325 .BR group_compat ,
326 and
327 .BR shadow_compat .
328 .SH FILES
329 A service named
330 .I SERVICE
331 is implemented by a shared object library named
332 .IB libnss_SERVICE.so. X
333 that resides in
334 .IR /lib .
335 .RS 4
336 .TP 25
337 .PD 0
338 .I /etc/nsswitch.conf
339 NSS configuration file.
340 .TP
341 .IB /lib/libnss_compat.so. X
342 implements "compat" source.
343 .TP
344 .IB /lib/libnss_db.so. X
345 implements "db" source.
346 .TP
347 .IB /lib/libnss_dns.so. X
348 implements "dns" source.
349 .TP
350 .IB /lib/libnss_files.so. X
351 implements "files" source.
352 .TP
353 .IB /lib/libnss_hesiod.so. X
354 implements "hesiod" source.
355 .TP
356 .IB /lib/libnss_nis.so. X
357 implements "nis" source.
358 .TP
359 .IB /lib/libnss_nisplus.so. X
360 implements "nisplus" source.
361 .PD
362 .RE
363 .P
364 The following files are read when "files" source is specified
365 for respective databases:
366 .RS 4
367 .TP 12
368 .PD 0
369 .B aliases
370 .I /etc/aliases
371 .TP
372 .B ethers
373 .I /etc/ethers
374 .TP
375 .B group
376 .I /etc/group
377 .TP
378 .B hosts
379 .I /etc/hosts
380 .TP
381 .B initgroups
382 .I /etc/group
383 .TP
384 .B netgroup
385 .I /etc/netgroup
386 .TP
387 .B networks
388 .I /etc/networks
389 .TP
390 .B passwd
391 .I /etc/passwd
392 .TP
393 .B protocols
394 .I /etc/protocols
395 .TP
396 .B publickey
397 .I /etc/publickey
398 .TP
399 .B rpc
400 .I /etc/rpc
401 .TP
402 .B services
403 .I /etc/services
404 .TP
405 .B shadow
406 .I /etc/shadow
407 .PD
408 .RE
409 .SH NOTES
410 Starting with glibc 2.33,
411 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=12459
412 .B nsswitch.conf
413 is automatically reloaded if the file is changed.
414 In earlier versions, the entire file was read only once within each process.
415 If the file was later changed,
416 the process would continue using the old configuration.
417 .P
418 Traditionally, there was only a single source for service information,
419 often in the form of a single configuration
420 file (e.g.,
421 .IR /etc/passwd ).
422 However, as other name services, such as the Network Information
423 Service (NIS) and the Domain Name Service (DNS), became popular,
424 a method was needed
425 that would be more flexible than fixed search orders coded into
426 the C library.
427 The Name Service Switch mechanism,
428 which was based on the mechanism used by
429 Sun Microsystems in the Solaris 2 C library,
430 introduced a cleaner solution to the problem.
431 .SH SEE ALSO
432 .BR getent (1),
433 .BR nss (5)