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