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