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