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 May 20, 2006 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, 52.Tn NIS , 53and cache), and 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.It cache 97makes use of the 98.Xr cached 8 99daemon. 100.El 101.Ss Databases 102The following databases are used by the following C library functions: 103.Pp 104.Bl -tag -width networks -compact 105.It Sy Database 106.Sy "Used by" 107.It group 108.Xr getgrent 3 109.It hosts 110.Xr gethostbyname 3 111.It networks 112.Xr getnetbyname 3 113.It passwd 114.Xr getpwent 3 115.It shells 116.Xr getusershell 3 117.It services 118.Xr getservent 3 119.It rpc 120.Xr getrpcent 3 121.It proto 122.Xr getprotobyname 3 123.El 124.Ss Status codes 125The following status codes are available: 126.Pp 127.Bl -tag -width tryagain -compact 128.It Sy Status 129.Sy Description 130.It success 131The requested entry was found. 132.It notfound 133The entry is not present at this source. 134.It tryagain 135The source is busy, and may respond to retries. 136.It unavail 137The source is not responding, or entry is corrupt. 138.El 139.Ss Actions 140For each of the status codes, one of two actions is possible: 141.Pp 142.Bl -tag -width continue -compact 143.It Sy Action 144.Sy Description 145.It continue 146Try the next source 147.It return 148Return with the current result 149.El 150.Ss Format of file 151A 152.Tn BNF 153description of the syntax of 154.Nm 155is: 156.Pp 157.Bl -tag -width <criterion> -compact 158.It <entry> 159::= 160<database> ":" [<source> [<criteria>]]* 161.It <criteria> 162::= 163"[" <criterion>+ "]" 164.It <criterion> 165::= 166<status> "=" <action> 167.It <status> 168::= 169"success" | "notfound" | "unavail" | "tryagain" 170.It <action> 171::= 172"return" | "continue" 173.El 174.Pp 175Each entry starts on a new line in the file. 176A 177.Sq # 178delimits a comment to end of line. 179Blank lines are ignored. 180A 181.Sq \e 182at the end of a line escapes the newline, and causes the next line to 183be a continuation of the current line. 184All entries are case-insensitive. 185.Pp 186The default criteria is to return on 187.Dq success , 188and continue on anything else (i.e, 189.Li "[success=return notfound=continue unavail=continue tryagain=continue]" ) . 190.Ss Cache 191You can enable caching for the particular database by specifying 192.Dq cache 193as the first source in the 194.Xr nsswitch.conf 5 195file. 196You should also enable caching for this database in 197.Xr cached.conf 5 . 198If for the particular query 199.Dq cache 200source returns success, no further sources are queried. 201On the other hand, if there are no previously cached data, the 202query result will be placed into the cache right after 203all other sources are processed. 204Note, that 205.Dq cache 206requires 207.Xr cached 8 208daemon to be running. 209.Ss Compat mode: +/- syntax 210In historical multi-source implementations, the 211.Sq + 212and 213.Sq - 214characters are used to specify the importing of user password and 215group information from 216.Tn NIS . 217Although 218.Nm 219provides alternative methods of accessing distributed sources such as 220.Tn NIS , 221specifying a sole source of 222.Dq compat 223will provide the historical behaviour. 224.Pp 225An alternative source for the information accessed via 226.Sq +/- 227can be used by specifying 228.Dq passwd_compat: source . 229.Dq source 230in this case can be 231.Sq dns , 232.Sq nis , 233or 234any other source except for 235.Sq files 236and 237.Sq compat . 238.Ss Notes 239Historically, many of the databases had enumeration functions, often of 240the form 241.Fn getXXXent . 242These made sense when the databases were in local files, but do not make 243sense or have lesser relevance when there are possibly multiple sources, 244each of an unknown size. 245The interfaces are still provided for compatibility, but the source 246may not be able to provide complete entries, or duplicate entries may 247be retrieved if multiple sources that contain similar information are 248specified. 249.Pp 250To ensure compatibility with previous and current implementations, the 251.Dq compat 252source must appear alone for a given database. 253.Ss Default source lists 254If, for any reason, 255.Nm 256does not exist, or it has missing or corrupt entries, 257.Xr nsdispatch 3 258will default to an entry of 259.Dq files 260for the requested database. 261Exceptions are: 262.Pp 263.Bl -tag -width services_compat -compact 264.It Sy Database 265.Sy "Default source list" 266.It group 267compat 268.It group_compat 269nis 270.It hosts 271files dns 272.It passwd 273compat 274.It passwd_compat 275nis 276.It services 277compat 278.It services_compat 279nis 280.El 281.Sh FILES 282.Bl -tag -width /etc/nsswitch.conf -compact 283.It Pa /etc/nsswitch.conf 284The file 285.Nm 286resides in 287.Pa /etc . 288.El 289.Sh EXAMPLES 290To lookup hosts in cache, then in 291.Pa /etc/hosts 292and then from the DNS, and lookup user information from 293.Tn NIS 294then files, use: 295.Pp 296.Bl -tag -width passwd: -compact 297.It hosts: 298cache files dns 299.It passwd: 300nis [notfound=return] files 301.It group: 302nis [notfound=return] files 303.El 304.Pp 305The criteria 306.Dq [notfound=return] 307sets a policy of "if the user is notfound in nis, do not try files." 308This treats nis as the authoritative source of information, except 309when the server is down. 310.Sh NOTES 311If system got compiled with 312.Va WITHOUT_NIS 313you have to remove 314.Sq nis 315entries. 316.Sh SEE ALSO 317.Xr nsdispatch 3 , 318.Xr cached.conf 5 , 319.Xr resolv.conf 5 , 320.Xr cached 8 , 321.Xr named 8 , 322.Xr ypbind 8 323.Sh HISTORY 324The 325.Nm 326file format first appeared in 327.Fx 5.0 . 328It was imported from the 329.Nx 330Project, where it appeared first in 331.Nx 1.4 . 332.Sh AUTHORS 333Luke Mewburn 334.Aq lukem@netbsd.org 335wrote this freely distributable name-service switch implementation, 336using ideas from the 337.Tn ULTRIX 338.Xr svc.conf 5 339and 340.Tn Solaris 341.Xr nsswitch.conf 4 342manual pages. 343