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