| blob | 2ded02bc0b103fcb08eb4a151b5402e130ca4d30 |
1 .\" $NetBSD: nsswitch.conf.5,v 1.14 1999/03/17 20:19:47 garbled Exp $
2 .\"
3 .\" Copyright (c) 1997, 1998, 1999 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Luke Mewburn.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. All advertising materials mentioning features or use of this software
18 .\" must display the following acknowledgement:
19 .\" This product includes software developed by Luke Mewburn.
20 .\" 4. The name of the author may not be used to endorse or promote products
21 .\" derived from this software without specific prior written permission.
22 .\"
23 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
24 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
25 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
26 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
27 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
28 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
29 .\" OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
30 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
31 .\" TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
32 .\" USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 .\"
34 .\" $FreeBSD$
35 .\"
36 .Dd January 22, 2007
37 .Dt NSSWITCH.CONF 5
38 .Os
39 .Sh NAME
40 .Nm nsswitch.conf
41 .Nd name-service switch configuration file
42 .Sh DESCRIPTION
43 The
44 .Nm
45 file specifies how the
46 .Xr nsdispatch 3
47 (name-service switch dispatcher) routines in the C library should operate.
48 .Pp
49 The configuration file controls how a process looks up various databases
50 containing information regarding hosts, users (passwords), groups, etc.
51 Each database comes from a source (such as local files, DNS,
52 .Tn NIS ,
53 and cache), and the order to look up the sources is specified in
54 .Nm .
55 .Pp
56 Each entry in
57 .Nm
58 consists of a database name, and a space separated list of sources.
59 Each source can have an optional trailing criterion that determines
60 whether the next listed source is used, or the search terminates at
61 the current source.
62 Each criterion consists of one or more status codes, and actions to
63 take if that status code occurs.
64 .Ss Sources
65 The following sources are implemented:
66 .Pp
67 .Bl -tag -width Source -compact
68 .It Sy Source
69 .Sy Description
70 .It files
71 Local files, such as
72 .Pa /etc/hosts ,
73 and
74 .Pa /etc/passwd .
75 .It dns
76 Internet Domain Name System.
77 .Dq hosts
78 and
79 .Sq networks
80 use
81 .Sy IN
82 class entries, all other databases use
83 .Sy HS
84 class (Hesiod) entries.
85 .It nis
86 NIS (formerly YP)
87 .It compat
88 support
89 .Sq +/-
90 in the
91 .Dq passwd
92 and
93 .Dq group
94 databases.
95 If this is present, it must be the only source for that entry.
96 .It cache
97 makes use of the
98 .Xr nscd 8
99 daemon.
100 .El
101 .Ss Databases
102 The following databases are used by the following C library functions:
103 .Pp
104 .Bl -tag -width networks -compact
105 .It Sy Database
106 .Sy "Used by"
107 .It group
108 .Xr getgrent 3 ,
109 .Xr getgrent_r 3 ,
110 .Xr getgrgid_r 3 ,
111 .Xr getgrnam_r 3 ,
112 .Xr setgrent 3 ,
113 .Xr endgrent 3
114 .It hosts
115 .Xr getaddrinfo 3 ,
116 .Xr gethostbyaddr 3 ,
117 .Xr gethostbyaddr_r 3 ,
118 .Xr gethostbyname 3 ,
119 .Xr gethostbyname2 3 ,
120 .Xr gethostbyname_r 3 ,
121 .Xr getipnodebyaddr 3 ,
122 .Xr getipnodebyname 3
123 .It networks
124 .Xr getnetbyaddr 3 ,
125 .Xr getnetbyaddr_r 3 ,
126 .Xr getnetbyname 3 ,
127 .Xr getnetbyname_r 3
128 .It passwd
129 .Xr getpwent 3 ,
130 .Xr getpwent_r 3 ,
131 .Xr getpwnam_r 3 ,
132 .Xr getpwuid_r 3 ,
133 .Xr setpwent 3 ,
134 .Xr endpwent 3
135 .It shells
136 .Xr getusershell 3
137 .It services
138 .Xr getservent 3
139 .It rpc
140 .Xr getrpcbyname 3 ,
141 .Xr getrpcbynumber 3 ,
142 .Xr getrpcent 3
143 .It proto
144 .Xr getprotobyname 3
145 .Xr getprotobynumber 3 ,
146 .Xr getprotoent 3
147 .El
148 .Ss Status codes
149 The following status codes are available:
150 .Pp
151 .Bl -tag -width tryagain -compact
152 .It Sy Status
153 .Sy Description
154 .It success
155 The requested entry was found.
156 .It notfound
157 The entry is not present at this source.
158 .It tryagain
159 The source is busy, and may respond to retries.
160 .It unavail
161 The source is not responding, or entry is corrupt.
162 .El
163 .Ss Actions
164 For each of the status codes, one of two actions is possible:
165 .Pp
166 .Bl -tag -width continue -compact
167 .It Sy Action
168 .Sy Description
169 .It continue
170 Try the next source
171 .It return
172 Return with the current result
173 .El
174 .Ss Format of file
175 A
176 .Tn BNF
177 description of the syntax of
178 .Nm
179 is:
180 .Pp
181 .Bl -tag -width <criterion> -compact
182 .It <entry>
183 ::=
184 <database> ":" [<source> [<criteria>]]*
185 .It <criteria>
186 ::=
187 "[" <criterion>+ "]"
188 .It <criterion>
189 ::=
190 <status> "=" <action>
191 .It <status>
192 ::=
193 "success" | "notfound" | "unavail" | "tryagain"
194 .It <action>
195 ::=
196 "return" | "continue"
197 .El
198 .Pp
199 Each entry starts on a new line in the file.
200 A
201 .Sq #
202 delimits a comment to end of line.
203 Blank lines are ignored.
204 A
205 .Sq \e
206 at the end of a line escapes the newline, and causes the next line to
207 be a continuation of the current line.
208 All entries are case-insensitive.
209 .Pp
210 The default criteria is to return on
211 .Dq success ,
212 and continue on anything else (i.e,
213 .Li "[success=return notfound=continue unavail=continue tryagain=continue]" ) .
214 .Ss Cache
215 You can enable caching for the particular database by specifying
216 .Dq cache
217 as the first source in the
218 .Xr nsswitch.conf 5
219 file.
220 You should also enable caching for this database in
221 .Xr nscd.conf 5 .
222 If for the particular query
223 .Dq cache
224 source returns success, no further sources are queried.
225 On the other hand, if there are no previously cached data, the
226 query result will be placed into the cache right after
227 all other sources are processed.
228 Note, that
229 .Dq cache
230 requires
231 .Xr nscd 8
232 daemon to be running.
233 .Ss Compat mode: +/- syntax
234 In historical multi-source implementations, the
235 .Sq +
236 and
237 .Sq -
238 characters are used to specify the importing of user password and
239 group information from
240 .Tn NIS .
241 Although
242 .Nm
243 provides alternative methods of accessing distributed sources such as
244 .Tn NIS ,
245 specifying a sole source of
246 .Dq compat
247 will provide the historical behaviour.
248 .Pp
249 An alternative source for the information accessed via
250 .Sq +/-
251 can be used by specifying
252 .Dq passwd_compat: source .
253 .Dq source
254 in this case can be
255 .Sq dns ,
256 .Sq nis ,
257 or
258 any other source except for
259 .Sq files
260 and
261 .Sq compat .
262 .Ss Notes
263 Historically, many of the databases had enumeration functions, often of
264 the form
265 .Fn getXXXent .
266 These made sense when the databases were in local files, but do not make
267 sense or have lesser relevance when there are possibly multiple sources,
268 each of an unknown size.
269 The interfaces are still provided for compatibility, but the source
270 may not be able to provide complete entries, or duplicate entries may
271 be retrieved if multiple sources that contain similar information are
272 specified.
273 .Pp
274 To ensure compatibility with previous and current implementations, the
275 .Dq compat
276 source must appear alone for a given database.
277 .Ss Default source lists
278 If, for any reason,
279 .Nm
280 does not exist, or it has missing or corrupt entries,
281 .Xr nsdispatch 3
282 will default to an entry of
283 .Dq files
284 for the requested database.
285 Exceptions are:
286 .Pp
287 .Bl -tag -width services_compat -compact
288 .It Sy Database
289 .Sy "Default source list"
290 .It group
291 compat
292 .It group_compat
293 nis
294 .It hosts
295 files dns
296 .It passwd
297 compat
298 .It passwd_compat
299 nis
300 .It services
301 compat
302 .It services_compat
303 nis
304 .El
305 .Sh FILES
306 .Bl -tag -width /etc/nsswitch.conf -compact
307 .It Pa /etc/nsswitch.conf
308 The file
309 .Nm
310 resides in
311 .Pa /etc .
312 .El
313 .Sh EXAMPLES
314 To lookup hosts in cache, then in
315 .Pa /etc/hosts
316 and then from the DNS, and lookup user information from
317 .Tn NIS
318 then files, use:
319 .Pp
320 .Bl -tag -width passwd: -compact
321 .It hosts:
322 cache files dns
323 .It passwd:
324 nis [notfound=return] files
325 .It group:
326 nis [notfound=return] files
327 .El
328 .Pp
329 The criteria
330 .Dq [notfound=return]
331 sets a policy of "if the user is notfound in nis, do not try files."
332 This treats nis as the authoritative source of information, except
333 when the server is down.
334 .Sh NOTES
335 If system got compiled with
336 .Va WITHOUT_NIS
337 you have to remove
338 .Sq nis
339 entries.
340 .Pp
341 .Fx Ns 's
342 .Lb libc
343 provides stubs for compatibility with NSS modules
344 written for the
345 .Tn GNU
346 C Library
347 .Nm nsswitch
348 interface.
349 However, these stubs only support the use of the
350 .Dq Li passwd
351 and
352 .Dq Li group
353 databases.
354 .Sh SEE ALSO
355 .Xr nsdispatch 3 ,
356 .Xr nscd.conf 5 ,
357 .Xr resolv.conf 5 ,
358 .Xr nscd 8 ,
359 .Xr named 8 ,
360 .Xr ypbind 8
361 .Sh HISTORY
362 The
363 .Nm
364 file format first appeared in
365 .Fx 5.0 .
366 It was imported from the
367 .Nx
368 Project, where it appeared first in
369 .Nx 1.4 .
370 .Sh AUTHORS
371 Luke Mewburn
372 .Aq lukem@netbsd.org
373 wrote this freely distributable name-service switch implementation,
374 using ideas from the
375 .Tn ULTRIX
376 .Xr svc.conf 5
377 and
378 .Tn Solaris
379 .Xr nsswitch.conf 4
380 manual pages.