]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (c) 1998, 1999 Thorsten Kukuk (kukuk@vt.uni-paderborn.de) |
79e2fba2 | 2 | .\" Copyright (c) 2011, Mark R. Bannister <cambridge@users.sourceforge.net> |
fea681da | 3 | .\" |
e4a74ca8 | 4 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
fea681da | 5 | .\" |
ab47278f | 6 | .TH NSSWITCH.CONF 5 (date) "Linux man-pages (unreleased)" |
fea681da | 7 | .SH NAME |
79e2fba2 | 8 | nsswitch.conf \- Name Service Switch configuration file |
fea681da | 9 | .SH DESCRIPTION |
7534ecb2 MK |
10 | The Name Service Switch (NSS) configuration file, |
11 | .IR /etc/nsswitch.conf , | |
6c1f939f | 12 | is used by the GNU C Library and certain other applications to determine |
9aa96150 MK |
13 | the sources from which to obtain name-service information in |
14 | a range of categories, | |
79e2fba2 MB |
15 | and in what order. |
16 | Each category of information is identified by a database name. | |
dd3568a1 | 17 | .PP |
79e2fba2 MB |
18 | The file is plain ASCII text, with columns separated by spaces or tab |
19 | characters. | |
9aa96150 | 20 | The first column specifies the database name. |
79e2fba2 | 21 | The remaining columns describe the order of sources to query and a |
9aa96150 | 22 | limited set of actions that can be performed by lookup result. |
dd3568a1 | 23 | .PP |
9aa96150 MK |
24 | The following databases are understood by the GNU C Library: |
25 | .TP 12 | |
fea681da MK |
26 | .B aliases |
27 | Mail aliases, used by | |
79e2fba2 MB |
28 | .BR getaliasent (3) |
29 | and related functions. | |
fea681da MK |
30 | .TP |
31 | .B ethers | |
32 | Ethernet numbers. | |
33 | .TP | |
34 | .B group | |
35 | Groups of users, used by | |
36 | .BR getgrent (3) | |
79e2fba2 | 37 | and related functions. |
fea681da MK |
38 | .TP |
39 | .B hosts | |
40 | Host names and numbers, used by | |
41 | .BR gethostbyname (3) | |
79e2fba2 | 42 | and related functions. |
fea681da | 43 | .TP |
1b0f58cd PS |
44 | .B initgroups |
45 | Supplementary group access list, used by | |
46 | .BR getgrouplist (3) | |
47 | function. | |
48 | .TP | |
fea681da | 49 | .B netgroup |
9aa96150 MK |
50 | Network-wide list of hosts and users, used for access rules. |
51 | C libraries before glibc 2.1 supported netgroups only over NIS. | |
fea681da | 52 | .TP |
7c80e581 | 53 | .B networks |
fea681da MK |
54 | Network names and numbers, used by |
55 | .BR getnetent (3) | |
79e2fba2 | 56 | and related functions. |
fea681da MK |
57 | .TP |
58 | .B passwd | |
59 | User passwords, used by | |
60 | .BR getpwent (3) | |
79e2fba2 | 61 | and related functions. |
fea681da MK |
62 | .TP |
63 | .B protocols | |
64 | Network protocols, used by | |
65 | .BR getprotoent (3) | |
79e2fba2 | 66 | and related functions. |
fea681da MK |
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) | |
79e2fba2 | 74 | and related functions. |
fea681da MK |
75 | .TP |
76 | .B services | |
77 | Network services, used by | |
78 | .BR getservent (3) | |
79e2fba2 | 79 | and related functions. |
fea681da MK |
80 | .TP |
81 | .B shadow | |
82 | Shadow user passwords, used by | |
79e2fba2 MB |
83 | .BR getspnam (3) |
84 | and related functions. | |
dd3568a1 | 85 | .PP |
5e833e27 MK |
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, | |
6c1f939f FW |
90 | .BR sudo (8) |
91 | consults the | |
92 | .B sudoers | |
93 | database. | |
8c39b2dd NF |
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. | |
dd3568a1 | 103 | .PP |
79e2fba2 | 104 | Here is an example |
8478ee02 | 105 | .I /etc/nsswitch.conf |
79e2fba2 | 106 | file: |
a4e45e13 MK |
107 | .PP |
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 | .PP | |
79e2fba2 MB |
123 | The first column is the database name. |
124 | The remaining columns specify: | |
9aa96150 | 125 | .IP * 3 |
10850212 | 126 | One or more service specifications, for example, "files", "db", or "nis". |
9aa96150 | 127 | The order of the services on the line determines the order in which |
79e2fba2 | 128 | those services will be queried, in turn, until a result is found. |
9aa96150 | 129 | .IP * |
79e2fba2 | 130 | Optional actions to perform if a particular result is obtained |
10850212 | 131 | from the preceding service, for example, "[NOTFOUND=return]". |
dd3568a1 | 132 | .PP |
79e2fba2 MB |
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". | |
9aa96150 MK |
141 | For the |
142 | .B hosts | |
143 | database, you can additionally specify "dns". | |
144 | For the | |
145 | .BR passwd , | |
146 | .BR group , | |
147 | and | |
b100ab55 | 148 | .B shadow |
9aa96150 | 149 | databases, you can additionally specify |
79e2fba2 MB |
150 | "compat" (see |
151 | .B "Compatibility mode" | |
152 | below). | |
fea681da | 153 | The version number |
79e2fba2 MB |
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 | |
735334d4 | 157 | further services such as "hesiod", "ldap", "winbind", and "wins". |
dd3568a1 | 158 | .PP |
9aa96150 | 159 | An action may also be specified following a service specification. |
7534ecb2 | 160 | The action modifies the behavior following a result obtained |
9aa96150 | 161 | from the preceding data source. |
79e2fba2 | 162 | Action items take the general form: |
dd3568a1 | 163 | .PP |
9aa96150 MK |
164 | .RS 4 |
165 | .RI [ STATUS = ACTION ] | |
79e2fba2 | 166 | .br |
9aa96150 | 167 | .RI [! STATUS = ACTION ] |
79e2fba2 | 168 | .RE |
dd3568a1 | 169 | .PP |
fea681da | 170 | where |
dd3568a1 | 171 | .PP |
9aa96150 | 172 | .RS 4 |
79e2fba2 MB |
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 | |
a4f6f087 MM |
188 | | |
189 | .B merge | |
79e2fba2 | 190 | .RE |
dd3568a1 | 191 | .PP |
79e2fba2 MB |
192 | The ! negates the test, matching all possible results except the |
193 | one specified. | |
9aa96150 | 194 | The case of the keywords is not significant. |
dd3568a1 | 195 | .PP |
79e2fba2 MB |
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: | |
9aa96150 MK |
200 | .RS 4 |
201 | .TP 12 | |
fea681da | 202 | .B success |
79e2fba2 MB |
203 | No error occurred and the requested entry is returned. |
204 | The default action for this condition is "return". | |
fea681da MK |
205 | .TP |
206 | .B notfound | |
79e2fba2 MB |
207 | The lookup succeeded, but the requested entry was not found. |
208 | The default action for this condition is "continue". | |
fea681da MK |
209 | .TP |
210 | .B unavail | |
c13182ef | 211 | The service is permanently unavailable. |
9aa96150 MK |
212 | This can mean either that the |
213 | required file cannot be read, or, for network services, that the server | |
79e2fba2 MB |
214 | is not available or does not allow queries. |
215 | The default action for this condition is "continue". | |
fea681da MK |
216 | .TP |
217 | .B tryagain | |
c13182ef MK |
218 | The service is temporarily unavailable. |
219 | This could mean a file is | |
220 | locked or a server currently cannot accept more connections. | |
79e2fba2 MB |
221 | The default action for this condition is "continue". |
222 | .RE | |
dd3568a1 | 223 | .PP |
79e2fba2 MB |
224 | The |
225 | .I ACTION | |
226 | value can be one of: | |
9aa96150 MK |
227 | .RS 4 |
228 | .TP 12 | |
79e2fba2 MB |
229 | .B return |
230 | Return a result now. | |
231 | Do not call any further lookup functions. | |
f92c7399 MK |
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. | |
79e2fba2 MB |
240 | .TP |
241 | .B continue | |
242 | Call the next lookup function. | |
a4f6f087 MM |
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. | |
fc69ee44 DD |
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. | |
79e2fba2 MB |
257 | .RE |
258 | .SS Compatibility mode (compat) | |
259 | The NSS "compat" service is similar to "files" except that it | |
85a7acd7 | 260 | additionally permits special entries in corresponding files |
79e2fba2 MB |
261 | for granting users or members of netgroups access to the system. |
262 | The following entries are valid in this mode: | |
9aa96150 | 263 | .RS 4 |
dd3568a1 | 264 | .PP |
85a7acd7 NF |
265 | For |
266 | .B passwd | |
267 | and | |
268 | .B shadow | |
269 | databases: | |
270 | .RS 4 | |
79e2fba2 MB |
271 | .TP 12 |
272 | .BI + user | |
273 | Include the specified | |
274 | .I user | |
85a7acd7 | 275 | from the NIS passwd/shadow map. |
79e2fba2 MB |
276 | .TP |
277 | .BI +@ netgroup | |
278 | Include all users in the given | |
279 | .IR netgroup . | |
280 | .TP | |
281 | .BI \- user | |
282 | Exclude the specified | |
283 | .I user | |
85a7acd7 | 284 | from the NIS passwd/shadow map. |
79e2fba2 MB |
285 | .TP |
286 | .BI \-@ netgroup | |
287 | Exclude all users in the given | |
288 | .IR netgroup . | |
289 | .TP | |
290 | .B + | |
9aa96150 | 291 | Include every user, except previously excluded ones, from the |
85a7acd7 NF |
292 | NIS passwd/shadow map. |
293 | .RE | |
dd3568a1 | 294 | .PP |
85a7acd7 NF |
295 | For |
296 | .B group | |
297 | database: | |
298 | .RS 4 | |
299 | .TP 12 | |
300 | .BI + group | |
301 | Include the specified | |
302 | .I group | |
303 | from the NIS group map. | |
304 | .TP | |
305 | .BI \- group | |
306 | Exclude the specified | |
307 | .I group | |
308 | from the NIS group map. | |
309 | .TP | |
310 | .B + | |
311 | Include every group, except previously excluded ones, from the | |
312 | NIS group map. | |
313 | .RE | |
79e2fba2 | 314 | .RE |
dd3568a1 | 315 | .PP |
20d7c60b | 316 | By default, the source is "nis", but this may be |
85a7acd7 NF |
317 | overridden by specifying any NSS service except "compat" itself |
318 | as the source for the pseudo-databases | |
a5e0a0e4 | 319 | .BR passwd_compat , |
9aa96150 | 320 | .BR group_compat , |
fea681da | 321 | and |
a5e0a0e4 | 322 | .BR shadow_compat . |
fea681da | 323 | .SH FILES |
79e2fba2 MB |
324 | A service named |
325 | .I SERVICE | |
326 | is implemented by a shared object library named | |
327 | .IB libnss_SERVICE.so. X | |
fea681da MK |
328 | that resides in |
329 | .IR /lib . | |
9aa96150 | 330 | .RS 4 |
fea681da MK |
331 | .TP 25 |
332 | .PD 0 | |
8478ee02 | 333 | .I /etc/nsswitch.conf |
79e2fba2 | 334 | NSS configuration file. |
fea681da | 335 | .TP |
79e2fba2 MB |
336 | .IB /lib/libnss_compat.so. X |
337 | implements "compat" source. | |
fea681da | 338 | .TP |
79e2fba2 MB |
339 | .IB /lib/libnss_db.so. X |
340 | implements "db" source. | |
fea681da | 341 | .TP |
79e2fba2 MB |
342 | .IB /lib/libnss_dns.so. X |
343 | implements "dns" source. | |
fea681da | 344 | .TP |
79e2fba2 MB |
345 | .IB /lib/libnss_files.so. X |
346 | implements "files" source. | |
fea681da | 347 | .TP |
79e2fba2 MB |
348 | .IB /lib/libnss_hesiod.so. X |
349 | implements "hesiod" source. | |
fea681da | 350 | .TP |
79e2fba2 MB |
351 | .IB /lib/libnss_nis.so. X |
352 | implements "nis" source. | |
fea681da | 353 | .TP |
79e2fba2 MB |
354 | .IB /lib/libnss_nisplus.so. X |
355 | implements "nisplus" source. | |
f9c3f32a | 356 | .PD |
79e2fba2 | 357 | .RE |
dd3568a1 | 358 | .PP |
2e853683 NF |
359 | The following files are read when "files" source is specified |
360 | for respective databases: | |
361 | .RS 4 | |
362 | .TP 12 | |
363 | .PD 0 | |
364 | .B aliases | |
365 | .I /etc/aliases | |
366 | .TP | |
367 | .B ethers | |
368 | .I /etc/ethers | |
369 | .TP | |
370 | .B group | |
371 | .I /etc/group | |
372 | .TP | |
373 | .B hosts | |
374 | .I /etc/hosts | |
375 | .TP | |
376 | .B initgroups | |
377 | .I /etc/group | |
378 | .TP | |
379 | .B netgroup | |
380 | .I /etc/netgroup | |
381 | .TP | |
382 | .B networks | |
383 | .I /etc/networks | |
384 | .TP | |
385 | .B passwd | |
386 | .I /etc/passwd | |
387 | .TP | |
388 | .B protocols | |
389 | .I /etc/protocols | |
390 | .TP | |
391 | .B publickey | |
392 | .I /etc/publickey | |
393 | .TP | |
394 | .B rpc | |
395 | .I /etc/rpc | |
396 | .TP | |
397 | .B services | |
398 | .I /etc/services | |
399 | .TP | |
400 | .B shadow | |
401 | .I /etc/shadow | |
402 | .PD | |
403 | .RE | |
fea681da MK |
404 | .SH NOTES |
405 | Within each process that uses | |
406 | .BR nsswitch.conf , | |
79e2fba2 MB |
407 | the entire file is read only once. |
408 | If the file is later changed, the | |
fea681da | 409 | process will continue using the old configuration. |
dd3568a1 | 410 | .PP |
9aa96150 | 411 | Traditionally, there was only a single source for service information, |
79e2fba2 | 412 | often in the form of a single configuration |
9aa96150 MK |
413 | file (e.g., \fI/etc/passwd\fP). |
414 | However, as other name services, such as the Network Information | |
79e2fba2 MB |
415 | Service (NIS) and the Domain Name Service (DNS), became popular, |
416 | a method was needed | |
417 | that would be more flexible than fixed search orders coded into | |
418 | the C library. | |
7534ecb2 MK |
419 | The Name Service Switch mechanism, |
420 | which was based on the mechanism used by | |
421 | Sun Microsystems in the Solaris 2 C library, | |
9aa96150 MK |
422 | introduced a cleaner solution to the problem. |
423 | .SH SEE ALSO | |
424 | .BR getent (1), | |
425 | .BR nss (5) |