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