1.\" Copyright 1995, 1996 Luke Mewburn <lm@werj.com.au>. All rights reserved. 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 3. All advertising materials mentioning features or use of this software 12.\" must display the following acknowledgement: 13.\" This product includes software developed by Luke Mewburn. 14.\" 4. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 22.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 23.\" OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 24.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR 25.\" TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE 26.\" USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd March 12, 1996 29.Dt NSSWITCH.CONF 5 30.Os "NetBSD 1.1" 31.Sh NAME 32.Nm nsswitch.conf 33.Nd name-service switch configuration file 34.Sh DESCRIPTION 35The 36.Nm 37file specifies how the 38.Xr nsdispatch 3 39(name-service switch dispatcher) routines in the C library should operate. 40.Pp 41The configuration file controls how a process looks up various databases 42containing information regarding hosts, users (passwords), groups, 43netgroups, etc. 44Each database comes from a source (such as local files, DNS, NIS, and 45NIS+), and the order to look up the sources is specified in 46.Nm nsswitch.conf . 47.Pp 48If, for any reason, if the file doesn't exist, or has missing or corrupt 49entries, 50.Xr nsdispatch 3 51will default to an entry of 52.Va files 53for the requested database. 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 supported: 65.Bl -column "nisplus" -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 73uses 74.Sy IN 75class entries, all other databases use 76.Sy HS 77class (Hesiod) entries. 78.It nis NIS (formally YP) 79.It nisplus NIS+ (not implemented yet by 80.Bx . 81However, the functionality is available in the name-service switch routines) 82.It compat support 83.Sq +/- 84in the 85.Dq passwd 86and 87.Dq group 88databases. 89If this is present, it must be the only source for that entry. 90.El 91.Ss Databases 92The following databases are used by the following C library functions: 93.Bl -column "netgroup" -offset indent -compact 94.Sy Database Used by 95.It group 96.Xr getpwent 3 97.It hosts 98.Xr gethostbyname 3 , 99.Xr gethostbyaddr 3 100.It netgroup 101.Xr getnetgrent 3 102.It passwd 103.Xr getpwent 3 104.It shells 105.Xr getusershell 3 106.El 107.Ss Status codes 108The following status codes are available: 109.Bl -column "tryagain" -offset indent -compact 110.Sy Status Description 111.It success The requested entry was found. 112.It notfound The entry is not present at this source. 113.It unavail The source is not responding, or entry is corrupt. 114.It tryagain The source is busy, and may respond to retries. 115.El 116.Ss Actions 117For each of the status codes, one of two actions is possible: 118.Bl -column "continue" -offset indent -compact 119.Sy Action Description 120.It continue Try the next source 121.It return Return with the current result 122.El 123.Ss Format of file 124A 125.Tn BNF 126(Backus-Naur Form) description of the syntax of 127.Nm 128is: 129.Bl -column "<criterion>" -offset indent 130.It <entry> ::= 131<database> ":" [<source> [<criteria>]]* <source> 132.It <criteria> ::= 133"[" <criterion>+ "]" 134.It <criterion> ::= 135<status> "=" <action> 136.It <status> ::= 137"success" | "notfound" | "unavail" | "tryagain" 138.It <action> ::= 139"return" | "continue" 140.El 141.Pp 142Each entry starts on a new line in the file. 143A 144.Sq # 145delimits a comment to end of line. 146Blank lines are ignored. 147A 148.Sq \e 149at the end of a line escapes the newline, and causes the next line to 150be a continuation of the current line. 151All entries are case-insensitive. 152.Pp 153The default criteria is to return on 154.Dq success , 155and continue on anything else (i.e, 156.Li [success=return notfound=continue unavail=continue tryagain=continue] 157). 158.Ss Compat mode: +/- syntax 159In historical multi-source implementations, the 160.Sq + 161and 162.Sq - 163characters are used to signify the importing of user password and 164group information from NIS. 165Although 166.Nm nsswitch.conf 167provides alternative methods of accessing distributed sources such as 168NIS, specifying 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 181.Sq nisplus . 182.Ss Notes 183Historically, many of the databases had enumeration functions, often of 184the form 185.Fn getXXXent . 186These made sense when the databases were in local files, but don't make 187sense or have lesser relevance when there are possibly multiple sources, 188each of an unknown size. 189The interfaces are still provided for compatibility, but the source 190may not be able to provide complete entries, or duplicate entries may 191be retreived if multiple sources that contain similar information are 192specified. 193.Pp 194To ensure compatibility with previous and current implementations, the 195.Dq compat 196source must appear alone for a given database. 197.Sh FILES 198.Bl -tag -width /etc/nsswitch.conf -compact 199.It Pa /etc/nsswitch.conf 200The file 201.Nm 202resides in 203.Pa /etc . 204.El 205.Sh EXAMPLES 206To lookup hosts in 207.Pa /etc/hosts 208and then from the DNS, and lookup user information from NIS then files, use: 209.Bl -column "passwd:" -offset indent 210.It hosts: files dns 211.It passwd: nis [notfound=return] files 212.It group: nis [notfound=return] files 213.El 214The criteria 215.Dq [notfound=return] 216sets a policy of "if the user is notfound in nis, don't try files." 217This treats nis as the authoritive source of information, except 218when the server is down. 219.Pp 220If the older-style "+/-" syntax for 221.Pa /etc/passwd 222is required, use: 223.Bl -column "passwd:" -offset indent 224.It passwd: compat 225.It group: compat 226.El 227.Sh SEE ALSO 228.Xr nsdispatch 3 , 229.Xr resolv.conf 5 , 230.Xr named 8 , 231.Xr ypbind 8 232.Sh AUTHORS 233Luke Mewburn 234.Aq lm@werj.com.au 235wrote this freely distributable name-service switch implementation, 236using ideas from the 237.Tn ULTRIX 238.Xr svc.conf 5 239and 240.Tn SOLARIS 241.Xr nsswitch.conf 4 242manual pages. 243