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