1.\" $NetBSD: nsswitch.conf.5,v 1.14 1999/03/17 20:19:47 garbled Exp $ 2.\" $FreeBSD$ 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 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 "networks" -offset indent -compact 93.Sy Database Used by 94.It group 95.Xr getgrent 3 96.It hosts 97.Xr gethostbyname 3 98.It networks 99.Xr getnetbyname 3 100.It passwd 101.Xr getpwent 3 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 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. 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 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> ::= 129<database> ":" [<source> [<criteria>]]* 130.It <criteria> ::= 131"[" <criterion>+ "]" 132.It <criterion> ::= 133<status> "=" <action> 134.It <status> ::= 135"success" | "notfound" | "unavail" | "tryagain" 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 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 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 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. 267