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