1.\" $NetBSD: nsswitch.conf.5,v 1.14 1999/03/17 20:19:47 garbled 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.\" $FreeBSD$ 35.\" 36.Dd June 21, 2004 37.Dt NSSWITCH.CONF 5 38.Os 39.Sh NAME 40.Nm nsswitch.conf 41.Nd name-service switch configuration file 42.Sh DESCRIPTION 43The 44.Nm 45file specifies how the 46.Xr nsdispatch 3 47(name-service switch dispatcher) routines in the C library should operate. 48.Pp 49The configuration file controls how a process looks up various databases 50containing information regarding hosts, users (passwords), groups, etc. 51Each database comes from a source (such as local files, DNS, and 52.Tn NIS ) , 53and the order to look up the sources is specified in 54.Nm . 55.Pp 56Each entry in 57.Nm 58consists of a database name, and a space separated list of sources. 59Each source can have an optional trailing criterion that determines 60whether the next listed source is used, or the search terminates at 61the current source. 62Each criterion consists of one or more status codes, and actions to 63take if that status code occurs. 64.Ss Sources 65The following sources are implemented: 66.Pp 67.Bl -tag -width Source -compact 68.It Sy Source 69.Sy Description 70.It files 71Local files, such as 72.Pa /etc/hosts , 73and 74.Pa /etc/passwd . 75.It dns 76Internet Domain Name System. 77.Dq hosts 78and 79.Sq networks 80use 81.Sy IN 82class entries, all other databases use 83.Sy HS 84class (Hesiod) entries. 85.It nis 86NIS (formerly YP) 87.It compat 88support 89.Sq +/- 90in the 91.Dq passwd 92and 93.Dq group 94databases. 95If this is present, it must be the only source for that entry. 96.El 97.Ss Databases 98The following databases are used by the following C library functions: 99.Pp 100.Bl -tag -width networks -compact 101.It Sy Database 102.Sy "Used by" 103.It group 104.Xr getgrent 3 105.It hosts 106.Xr gethostbyname 3 107.It networks 108.Xr getnetbyname 3 109.It passwd 110.Xr getpwent 3 111.It shells 112.Xr getusershell 3 113.El 114.Ss Status codes 115The following status codes are available: 116.Pp 117.Bl -tag -width tryagain -compact 118.It Sy Status 119.Sy Description 120.It success 121The requested entry was found. 122.It notfound 123The entry is not present at this source. 124.It tryagain 125The source is busy, and may respond to retries. 126.It unavail 127The source is not responding, or entry is corrupt. 128.El 129.Ss Actions 130For each of the status codes, one of two actions is possible: 131.Pp 132.Bl -tag -width continue -compact 133.It Sy Action 134.Sy Description 135.It continue 136Try the next source 137.It return 138Return with the current result 139.El 140.Ss Format of file 141A 142.Tn BNF 143description of the syntax of 144.Nm 145is: 146.Pp 147.Bl -tag -width <criterion> -compact 148.It <entry> 149::= 150<database> ":" [<source> [<criteria>]]* 151.It <criteria> 152::= 153"[" <criterion>+ "]" 154.It <criterion> 155::= 156<status> "=" <action> 157.It <status> 158::= 159"success" | "notfound" | "unavail" | "tryagain" 160.It <action> 161::= 162"return" | "continue" 163.El 164.Pp 165Each entry starts on a new line in the file. 166A 167.Sq # 168delimits a comment to end of line. 169Blank lines are ignored. 170A 171.Sq \e 172at the end of a line escapes the newline, and causes the next line to 173be a continuation of the current line. 174All entries are case-insensitive. 175.Pp 176The default criteria is to return on 177.Dq success , 178and continue on anything else (i.e, 179.Li "[success=return notfound=continue unavail=continue tryagain=continue]" ) . 180.Ss Compat mode: +/- syntax 181In historical multi-source implementations, the 182.Sq + 183and 184.Sq - 185characters are used to specify the importing of user password and 186group information from 187.Tn NIS . 188Although 189.Nm 190provides alternative methods of accessing distributed sources such as 191.Tn NIS , 192specifying a sole source of 193.Dq compat 194will provide the historical behaviour. 195.Pp 196An alternative source for the information accessed via 197.Sq +/- 198can be used by specifying 199.Dq passwd_compat: source . 200.Dq source 201in this case can be 202.Sq dns , 203.Sq nis , 204or 205any other source except for 206.Sq files 207and 208.Sq compat . 209.Ss Notes 210Historically, many of the databases had enumeration functions, often of 211the form 212.Fn getXXXent . 213These made sense when the databases were in local files, but do not make 214sense or have lesser relevance when there are possibly multiple sources, 215each of an unknown size. 216The interfaces are still provided for compatibility, but the source 217may not be able to provide complete entries, or duplicate entries may 218be retrieved if multiple sources that contain similar information are 219specified. 220.Pp 221To ensure compatibility with previous and current implementations, the 222.Dq compat 223source must appear alone for a given database. 224.Ss Default source lists 225If, for any reason, 226.Nm 227does not exist, or it has missing or corrupt entries, 228.Xr nsdispatch 3 229will default to an entry of 230.Dq files 231for the requested database. 232Exceptions are: 233.Pp 234.Bl -tag -width passwd_compat -compact 235.It Sy Database 236.Sy "Default source list" 237.It group 238compat 239.It group_compat 240nis 241.It hosts 242files dns 243.It passwd 244compat 245.It passwd_compat 246nis 247.El 248.Sh FILES 249.Bl -tag -width /etc/nsswitch.conf -compact 250.It Pa /etc/nsswitch.conf 251The file 252.Nm 253resides in 254.Pa /etc . 255.El 256.Sh EXAMPLES 257To lookup hosts in 258.Pa /etc/hosts 259and then from the DNS, and lookup user information from 260.Tn NIS 261then files, use: 262.Pp 263.Bl -tag -width passwd: -compact 264.It hosts: 265files dns 266.It passwd: 267nis [notfound=return] files 268.It group: 269nis [notfound=return] files 270.El 271.Pp 272The criteria 273.Dq [notfound=return] 274sets a policy of "if the user is notfound in nis, do not try files." 275This treats nis as the authoritative source of information, except 276when the server is down. 277.Sh SEE ALSO 278.Xr nsdispatch 3 , 279.Xr resolv.conf 5 , 280.Xr named 8 , 281.Xr ypbind 8 282.Sh HISTORY 283The 284.Nm 285file format first appeared in 286.Fx 5.0 . 287It was imported from the 288.Nx 289Project, where it appeared first in 290.Nx 1.4 . 291.Sh AUTHORS 292Luke Mewburn 293.Aq lukem@netbsd.org 294wrote this freely distributable name-service switch implementation, 295using ideas from the 296.Tn ULTRIX 297.Xr svc.conf 5 298and 299.Tn Solaris 300.Xr nsswitch.conf 4 301manual pages. 302