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