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: src/share/man/man5/nsswitch.conf.5,v 1.18 2007/10/19 00:16:29 bushman Exp $ 35.\" $DragonFly: src/share/man/man5/nsswitch.conf.5,v 1.1 2003/08/01 04:11:23 rob Exp $ 36.\" 37.Dd January 22, 2007 38.Dt NSSWITCH.CONF 5 39.Os 40.Sh NAME 41.Nm nsswitch.conf 42.Nd name-service switch configuration file 43.Sh DESCRIPTION 44The 45.Nm 46file specifies how the 47.Xr nsdispatch 3 48(name-service switch dispatcher) routines in the C library should operate. 49.Pp 50The configuration file controls how a process looks up various databases 51containing information regarding hosts, users (passwords), groups, etc. 52Each database comes from a source (such as local files, DNS, 53.Tn NIS , 54and cache), and the order to look up the sources is specified in 55.Nm . 56.Pp 57Each entry in 58.Nm 59consists of a database name, and a space separated list of sources. 60Each source can have an optional trailing criterion that determines 61whether the next listed source is used, or the search terminates at 62the current source. 63Each criterion consists of one or more status codes, and actions to 64take if that status code occurs. 65.Ss Sources 66The following sources are implemented: 67.Pp 68.Bl -tag -width Source -compact 69.It Sy Source 70.Sy Description 71.It files 72Local files, such as 73.Pa /etc/hosts , 74and 75.Pa /etc/passwd . 76.It dns 77Internet Domain Name System. 78.Dq hosts 79and 80.Sq networks 81use 82.Sy IN 83class entries, all other databases use 84.Sy HS 85class (Hesiod) entries. 86.It nis 87NIS (formerly YP) 88.It compat 89support 90.Sq +/- 91in the 92.Dq passwd 93and 94.Dq group 95databases. 96If this is present, it must be the only source for that entry. 97.It cache 98makes use of the 99.Xr nscd 8 100daemon. 101.El 102.Ss Databases 103The following databases are used by the following C library functions: 104.Pp 105.Bl -tag -width networks -compact 106.It Sy Database 107.Sy "Used by" 108.It group 109.Xr getgrent 3 , 110.Xr getgrent_r 3 , 111.Xr getgrgid_r 3 , 112.Xr getgrnam_r 3 , 113.Xr setgrent 3 , 114.Xr endgrent 3 115.It hosts 116.Xr getaddrinfo 3 , 117.Xr gethostbyaddr 3 , 118.Xr gethostbyaddr_r 3 , 119.Xr gethostbyname 3 , 120.Xr gethostbyname2 3 , 121.Xr gethostbyname_r 3 , 122.Xr getipnodebyaddr 3 , 123.Xr getipnodebyname 3 124.It networks 125.Xr getnetbyaddr 3 , 126.Xr getnetbyaddr_r 3 , 127.Xr getnetbyname 3 , 128.Xr getnetbyname_r 3 129.It passwd 130.Xr getpwent 3 , 131.Xr getpwent_r 3 , 132.Xr getpwnam_r 3 , 133.Xr getpwuid_r 3 , 134.Xr setpwent 3 , 135.Xr endpwent 3 136.It shells 137.Xr getusershell 3 138.It services 139.Xr getservent 3 140.It rpc 141.Xr getrpcbyname 3 , 142.Xr getrpcbynumber 3 , 143.Xr getrpcent 3 144.It proto 145.Xr getprotobyname 3 146.Xr getprotobynumber 3 , 147.Xr getprotoent 3 148.El 149.Ss Status codes 150The following status codes are available: 151.Pp 152.Bl -tag -width tryagain -compact 153.It Sy Status 154.Sy Description 155.It success 156The requested entry was found. 157.It notfound 158The entry is not present at this source. 159.It tryagain 160The source is busy, and may respond to retries. 161.It unavail 162The source is not responding, or entry is corrupt. 163.El 164.Ss Actions 165For each of the status codes, one of two actions is possible: 166.Pp 167.Bl -tag -width continue -compact 168.It Sy Action 169.Sy Description 170.It continue 171Try the next source 172.It return 173Return with the current result 174.El 175.Ss Format of file 176A 177.Tn BNF 178description of the syntax of 179.Nm 180is: 181.Pp 182.Bl -tag -width <criterion> -compact 183.It <entry> 184::= 185<database> ":" [<source> [<criteria>]]* 186.It <criteria> 187::= 188"[" <criterion>+ "]" 189.It <criterion> 190::= 191<status> "=" <action> 192.It <status> 193::= 194"success" | "notfound" | "unavail" | "tryagain" 195.It <action> 196::= 197"return" | "continue" 198.El 199.Pp 200Each entry starts on a new line in the file. 201A 202.Sq # 203delimits a comment to end of line. 204Blank lines are ignored. 205A 206.Sq \e 207at the end of a line escapes the newline, and causes the next line to 208be a continuation of the current line. 209All entries are case-insensitive. 210.Pp 211The default criteria is to return on 212.Dq success , 213and continue on anything else (i.e, 214.Li "[success=return notfound=continue unavail=continue tryagain=continue]" ) . 215.Ss Cache 216You can enable caching for the particular database by specifying 217.Dq cache 218as the first source in the 219.Xr nsswitch.conf 5 220file. 221You should also enable caching for this database in 222.Xr nscd.conf 5 . 223If for the particular query 224.Dq cache 225source returns success, no further sources are queried. 226On the other hand, if there are no previously cached data, the 227query result will be placed into the cache right after 228all other sources are processed. 229Note, that 230.Dq cache 231requires 232.Xr nscd 8 233daemon to be running. 234.Ss Compat mode: +/- syntax 235In historical multi-source implementations, the 236.Sq + 237and 238.Sq - 239characters are used to specify the importing of user password and 240group information from 241.Tn NIS . 242Although 243.Nm 244provides alternative methods of accessing distributed sources such as 245.Tn NIS , 246specifying a sole source of 247.Dq compat 248will provide the historical behaviour. 249.Pp 250An alternative source for the information accessed via 251.Sq +/- 252can be used by specifying 253.Dq passwd_compat: source . 254.Dq source 255in this case can be 256.Sq dns , 257.Sq nis , 258or 259any other source except for 260.Sq files 261and 262.Sq compat . 263.Ss Notes 264Historically, many of the databases had enumeration functions, often of 265the form 266.Fn getXXXent . 267These made sense when the databases were in local files, but do not make 268sense or have lesser relevance when there are possibly multiple sources, 269each of an unknown size. 270The interfaces are still provided for compatibility, but the source 271may not be able to provide complete entries, or duplicate entries may 272be retrieved if multiple sources that contain similar information are 273specified. 274.Pp 275To ensure compatibility with previous and current implementations, the 276.Dq compat 277source must appear alone for a given database. 278.Ss Default source lists 279If, for any reason, 280.Nm 281does not exist, or it has missing or corrupt entries, 282.Xr nsdispatch 3 283will default to an entry of 284.Dq files 285for the requested database. 286Exceptions are: 287.Pp 288.Bl -tag -width services_compat -compact 289.It Sy Database 290.Sy "Default source list" 291.It group 292compat 293.It group_compat 294nis 295.It hosts 296files dns 297.It passwd 298compat 299.It passwd_compat 300nis 301.It services 302compat 303.It services_compat 304nis 305.El 306.Sh FILES 307.Bl -tag -width /etc/nsswitch.conf -compact 308.It Pa /etc/nsswitch.conf 309The file 310.Nm 311resides in 312.Pa /etc . 313.El 314.Sh EXAMPLES 315To lookup hosts in cache, then in 316.Pa /etc/hosts 317and then from the DNS, and lookup user information from 318.Tn NIS 319then files, use: 320.Pp 321.Bl -tag -width passwd: -compact 322.It hosts: 323cache files dns 324.It passwd: 325nis [notfound=return] files 326.It group: 327nis [notfound=return] files 328.El 329.Pp 330The criteria 331.Dq [notfound=return] 332sets a policy of "if the user is notfound in nis, do not try files." 333This treats nis as the authoritative source of information, except 334when the server is down. 335.Sh NOTES 336If system got compiled with 337.Va WITHOUT_NIS 338you have to remove 339.Sq nis 340entries. 341.Pp 342.Dx Ns 's 343.Lb libc 344provides stubs for compatibility with NSS modules 345written for the 346.Tn GNU 347C Library 348.Nm nsswitch 349interface. 350However, these stubs only support the use of the 351.Dq Li passwd 352and 353.Dq Li group 354databases. 355.Sh SEE ALSO 356.Xr nsdispatch 3 , 357.Xr nscd.conf 5 , 358.Xr resolv.conf 5 , 359.Xr named 8 , 360.Xr nscd 8 , 361.Xr ypbind 8 362.Sh HISTORY 363The 364.Nm 365file format first appeared in 366.Dx 2.1 . 367It was imported from the 368.Fx 369Project, where it appeared first in 370.Fx 5.0 . 371.Sh AUTHORS 372Luke Mewburn 373.Aq lukem@netbsd.org 374wrote this freely distributable name-service switch implementation, 375using ideas from the 376.Tn ULTRIX 377.Xr svc.conf 5 378and 379.Tn Solaris 380.Xr nsswitch.conf 4 381manual pages. 382