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