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