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