1.\" $NetBSD: nsswitch.conf.5,v 1.14 1999/03/17 20:19:47 garbled Exp $
| 1.\" $NetBSD: nsswitch.conf.5,v 1.14 1999/03/17 20:19:47 garbled Exp $
|
2.\" $FreeBSD: head/share/man/man5/nsswitch.conf.5 68962 2000-11-20 18:41:33Z ru $
| 2.\" $FreeBSD: head/share/man/man5/nsswitch.conf.5 70466 2000-12-29 09:18:45Z ru $
|
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.\"
35.Dd January 22, 1998
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.Bl -column "compat" -offset indent -compact
| 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.\"
35.Dd January 22, 1998
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.Bl -column "compat" -offset indent -compact
|
66.Sy Source Description
67.It files Local files, such as
| 66.It Sy "Source Description
67.It "files Local files, such as"
|
68.Pa /etc/hosts ,
69and
70.Pa /etc/passwd .
| 68.Pa /etc/hosts ,
69and
70.Pa /etc/passwd .
|
71.It dns Internet Domain Name System.
| 71.It "dns Internet Domain Name System."
|
72.Dq hosts
73and
74.Sq networks
75use
76.Sy IN
77class entries, all other databases use
78.Sy HS
79class (Hesiod) entries.
| 72.Dq hosts
73and
74.Sq networks
75use
76.Sy IN
77class entries, all other databases use
78.Sy HS
79class (Hesiod) entries.
|
80.It nis NIS (formerly YP)
81.It compat support
| 80.It "nis NIS (formerly YP)"
81.It "compat support"
|
82.Sq +/-
83in the
84.Dq passwd
85and
86.Dq group
87databases.
88If this is present, it must be the only source for that entry.
89.El
90.Ss Databases
91The following databases are used by the following C library functions:
92.Bl -column "networks" -offset indent -compact
| 82.Sq +/-
83in the
84.Dq passwd
85and
86.Dq group
87databases.
88If this is present, it must be the only source for that entry.
89.El
90.Ss Databases
91The following databases are used by the following C library functions:
92.Bl -column "networks" -offset indent -compact
|
93.Sy Database Used by
94.It group
| 93.It Sy "Database Used by"
94.It "group "
|
95.Xr getgrent 3
| 95.Xr getgrent 3
|
96.It hosts
| 96.It "hosts "
|
97.Xr gethostbyname 3
| 97.Xr gethostbyname 3
|
98.It networks
| 98.It "networks "
|
99.Xr getnetbyname 3
| 99.Xr getnetbyname 3
|
100.It passwd
| 100.It "passwd "
|
101.Xr getpwent 3
| 101.Xr getpwent 3
|
102.It shells
| 102.It "shells "
|
103.Xr getusershell 3
104.El
105.Ss Status codes
106The following status codes are available:
107.Bl -column "tryagain" -offset indent -compact
| 103.Xr getusershell 3
104.El
105.Ss Status codes
106The following status codes are available:
107.Bl -column "tryagain" -offset indent -compact
|
108.Sy Status Description
109.It success The requested entry was found.
110.It notfound The entry is not present at this source.
111.It tryagain The source is busy, and may respond to retries.
112.It unavail The source is not responding, or entry is corrupt.
| 108.It Sy "Status Description"
109.It "success The requested entry was found."
110.It "notfound The entry is not present at this source."
111.It "tryagain The source is busy, and may respond to retries."
112.It "unavail The source is not responding, or entry is corrupt."
|
113.El
114.Ss Actions
115For each of the status codes, one of two actions is possible:
116.Bl -column "continue" -offset indent -compact
| 113.El
114.Ss Actions
115For each of the status codes, one of two actions is possible:
116.Bl -column "continue" -offset indent -compact
|
117.Sy Action Description
118.It continue Try the next source
119.It return Return with the current result
| 117.It Sy "Action Description"
118.It "continue Try the next source"
119.It "return Return with the current result"
|
120.El
121.Ss Format of file
122A
123.Tn BNF
124description of the syntax of
125.Nm
126is:
127.Bl -column "<criterion>" -offset indent
| 120.El
121.Ss Format of file
122A
123.Tn BNF
124description of the syntax of
125.Nm
126is:
127.Bl -column "<criterion>" -offset indent
|
128.It <entry> ::=
| 128.It "<entry> ::="
|
129<database> ":" [<source> [<criteria>]]*
| 129<database> ":" [<source> [<criteria>]]*
|
130.It <criteria> ::=
| 130.It "<criteria> ::="
|
131"[" <criterion>+ "]"
| 131"[" <criterion>+ "]"
|
132.It <criterion> ::=
| 132.It "<criterion> ::="
|
133<status> "=" <action>
| 133<status> "=" <action>
|
134.It <status> ::=
| 134.It "<status> ::="
|
135"success" | "notfound" | "unavail" | "tryagain"
| 135"success" | "notfound" | "unavail" | "tryagain"
|
136.It <action> ::=
| 136.It "<action> ::="
|
137"return" | "continue"
138.El
139.Pp
140Each entry starts on a new line in the file.
141A
142.Sq #
143delimits a comment to end of line.
144Blank lines are ignored.
145A
146.Sq \e
147at the end of a line escapes the newline, and causes the next line to
148be a continuation of the current line.
149All entries are case-insensitive.
150.Pp
151The default criteria is to return on
152.Dq success ,
153and continue on anything else (i.e,
154.Li [success=return notfound=continue unavail=continue tryagain=continue]
155).
156.Ss Compat mode: +/- syntax
157In historical multi-source implementations, the
158.Sq +
159and
160.Sq -
161characters are used to specify the importing of user password and
162group information from
163.Tn NIS .
164Although
165.Nm
166provides alternative methods of accessing distributed sources such as
167.Tn NIS ,
168specifying a sole source of
169.Dq compat
170will provide the historical behaviour.
171.Pp
172An alternative source for the information accessed via
173.Sq +/-
174can be used by specifying
175.Dq passwd_compat: source .
176.Dq source
177in this case can be
178.Sq dns ,
179.Sq nis ,
180or
181any other source except for
182.Sq files
183and
184.Sq compat .
185.Ss Notes
186Historically, many of the databases had enumeration functions, often of
187the form
188.Fn getXXXent .
189These made sense when the databases were in local files, but don't make
190sense or have lesser relevance when there are possibly multiple sources,
191each of an unknown size.
192The interfaces are still provided for compatibility, but the source
193may not be able to provide complete entries, or duplicate entries may
194be retrieved if multiple sources that contain similar information are
195specified.
196.Pp
197To ensure compatibility with previous and current implementations, the
198.Dq compat
199source must appear alone for a given database.
200.Ss Default source lists
201If, for any reason,
202.Nm
203doesn't exist, or it has missing or corrupt entries,
204.Xr nsdispatch 3
205will default to an entry of
206.Dq files
207for the requested database.
208Exceptions are:
209.Bl -column passwd_compat "dns files" -offset indent
| 137"return" | "continue"
138.El
139.Pp
140Each entry starts on a new line in the file.
141A
142.Sq #
143delimits a comment to end of line.
144Blank lines are ignored.
145A
146.Sq \e
147at the end of a line escapes the newline, and causes the next line to
148be a continuation of the current line.
149All entries are case-insensitive.
150.Pp
151The default criteria is to return on
152.Dq success ,
153and continue on anything else (i.e,
154.Li [success=return notfound=continue unavail=continue tryagain=continue]
155).
156.Ss Compat mode: +/- syntax
157In historical multi-source implementations, the
158.Sq +
159and
160.Sq -
161characters are used to specify the importing of user password and
162group information from
163.Tn NIS .
164Although
165.Nm
166provides alternative methods of accessing distributed sources such as
167.Tn NIS ,
168specifying a sole source of
169.Dq compat
170will provide the historical behaviour.
171.Pp
172An alternative source for the information accessed via
173.Sq +/-
174can be used by specifying
175.Dq passwd_compat: source .
176.Dq source
177in this case can be
178.Sq dns ,
179.Sq nis ,
180or
181any other source except for
182.Sq files
183and
184.Sq compat .
185.Ss Notes
186Historically, many of the databases had enumeration functions, often of
187the form
188.Fn getXXXent .
189These made sense when the databases were in local files, but don't make
190sense or have lesser relevance when there are possibly multiple sources,
191each of an unknown size.
192The interfaces are still provided for compatibility, but the source
193may not be able to provide complete entries, or duplicate entries may
194be retrieved if multiple sources that contain similar information are
195specified.
196.Pp
197To ensure compatibility with previous and current implementations, the
198.Dq compat
199source must appear alone for a given database.
200.Ss Default source lists
201If, for any reason,
202.Nm
203doesn't exist, or it has missing or corrupt entries,
204.Xr nsdispatch 3
205will default to an entry of
206.Dq files
207for the requested database.
208Exceptions are:
209.Bl -column passwd_compat "dns files" -offset indent
|
210.Sy Database Default source list
211.It group compat
212.It group_compat nis
213.It hosts dns files
214.It passwd compat
215.It passwd_compat nis
| 210.It Sy "Database Default source list"
211.It "group compat"
212.It "group_compat nis"
213.It "hosts dns files"
214.It "passwd compat"
215.It "passwd_compat nis"
|
216.El
217.Sh FILES
218.Bl -tag -width /etc/nsswitch.conf -compact
219.It Pa /etc/nsswitch.conf
220The file
221.Nm
222resides in
223.Pa /etc .
224.El
225.Sh EXAMPLES
226To lookup hosts in
227.Pa /etc/hosts
228and then from the DNS, and lookup user information from
229.Tn NIS
230then files, use:
231.Bl -column "passwd:" -offset indent
| 216.El
217.Sh FILES
218.Bl -tag -width /etc/nsswitch.conf -compact
219.It Pa /etc/nsswitch.conf
220The file
221.Nm
222resides in
223.Pa /etc .
224.El
225.Sh EXAMPLES
226To lookup hosts in
227.Pa /etc/hosts
228and then from the DNS, and lookup user information from
229.Tn NIS
230then files, use:
231.Bl -column "passwd:" -offset indent
|
232.It hosts: files dns
233.It passwd: nis [notfound=return] files
234.It group: nis [notfound=return] files
| 232.It "hosts: files dns"
233.It "passwd: nis [notfound=return] files"
234.It "group: nis [notfound=return] files"
|
235.El
236.Pp
237The criteria
238.Dq [notfound=return]
239sets a policy of "if the user is notfound in nis, don't try files."
240This treats nis as the authoritive source of information, except
241when the server is down.
242.Sh SEE ALSO
243.Xr nsdispatch 3 ,
244.Xr resolv.conf 5 ,
245.Xr named 8 ,
246.Xr ypbind 8
247.Sh HISTORY
248The
249.Nm
250file format first appeared in
251.Fx 4.1 .
252It was imported from the
253.Nx
254Project, where it appeared first in
255.Nx 1.4 .
256.Sh AUTHORS
257Luke Mewburn
258.Aq lukem@netbsd.org
259wrote this freely distributable name-service switch implementation,
260using ideas from the
261.Tn ULTRIX
262.Xr svc.conf 5
263and
264.Tn Solaris
265.Xr nsswitch.conf 4
266manual pages.
| 235.El
236.Pp
237The criteria
238.Dq [notfound=return]
239sets a policy of "if the user is notfound in nis, don't try files."
240This treats nis as the authoritive source of information, except
241when the server is down.
242.Sh SEE ALSO
243.Xr nsdispatch 3 ,
244.Xr resolv.conf 5 ,
245.Xr named 8 ,
246.Xr ypbind 8
247.Sh HISTORY
248The
249.Nm
250file format first appeared in
251.Fx 4.1 .
252It was imported from the
253.Nx
254Project, where it appeared first in
255.Nx 1.4 .
256.Sh AUTHORS
257Luke Mewburn
258.Aq lukem@netbsd.org
259wrote this freely distributable name-service switch implementation,
260using ideas from the
261.Tn ULTRIX
262.Xr svc.conf 5
263and
264.Tn Solaris
265.Xr nsswitch.conf 4
266manual pages.
|