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