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 December 25, 2013 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 setnetgrent 3 , 152.Xr innetgr 3 153.El 154.Ss Status codes 155The following status codes are available: 156.Pp 157.Bl -tag -width tryagain -compact 158.It Sy Status 159.Sy Description 160.It success 161The requested entry was found. 162.It notfound 163The entry is not present at this source. 164.It tryagain 165The source is busy, and may respond to retries. 166.It unavail 167The source is not responding, or entry is corrupt. 168.El 169.Ss Actions 170For each of the status codes, one of two actions is possible: 171.Pp 172.Bl -tag -width continue -compact 173.It Sy Action 174.Sy Description 175.It continue 176Try the next source 177.It return 178Return with the current result 179.El 180.Ss Format of file 181A 182.Tn BNF 183description of the syntax of 184.Nm 185is: 186.Pp 187.Bl -tag -width <criterion> -compact 188.It <entry> 189::= 190<database> ":" [<source> [<criteria>]]* 191.It <criteria> 192::= 193"[" <criterion>+ "]" 194.It <criterion> 195::= 196<status> "=" <action> 197.It <status> 198::= 199"success" | "notfound" | "unavail" | "tryagain" 200.It <action> 201::= 202"return" | "continue" 203.El 204.Pp 205Each entry starts on a new line in the file. 206A 207.Sq # 208delimits a comment to end of line. 209Blank lines are ignored. 210A 211.Sq \e 212at the end of a line escapes the newline, and causes the next line to 213be a continuation of the current line. 214All entries are case-insensitive. 215.Pp 216The default criteria is to return on 217.Dq success , 218and continue on anything else (i.e, 219.Li "[success=return notfound=continue unavail=continue tryagain=continue]" ) . 220.Ss Cache 221You can enable caching for the particular database by specifying 222.Dq cache 223as the first source in the 224.Xr nsswitch.conf 5 225file. 226You should also enable caching for this database in 227.Xr nscd.conf 5 . 228If for the particular query 229.Dq cache 230source returns success, no further sources are queried. 231On the other hand, if there are no previously cached data, the 232query result will be placed into the cache right after 233all other sources are processed. 234Note, that 235.Dq cache 236requires 237.Xr nscd 8 238daemon to be running. 239.Ss Compat mode: +/- syntax 240In historical multi-source implementations, the 241.Sq + 242and 243.Sq - 244characters are used to specify the importing of user password and 245group information from 246.Tn NIS . 247Although 248.Nm 249provides alternative methods of accessing distributed sources such as 250.Tn NIS , 251specifying a sole source of 252.Dq compat 253will provide the historical behaviour. 254.Pp 255An alternative source for the information accessed via 256.Sq +/- 257can be used by specifying 258.Dq passwd_compat: source . 259.Dq source 260in this case can be 261.Sq dns , 262.Sq nis , 263or 264any other source except for 265.Sq files 266and 267.Sq compat . 268.Ss Notes 269Historically, many of the databases had enumeration functions, often of 270the form 271.Fn getXXXent . 272These made sense when the databases were in local files, but do not make 273sense or have lesser relevance when there are possibly multiple sources, 274each of an unknown size. 275The interfaces are still provided for compatibility, but the source 276may not be able to provide complete entries, or duplicate entries may 277be retrieved if multiple sources that contain similar information are 278specified. 279.Pp 280To ensure compatibility with previous and current implementations, the 281.Dq compat 282source must appear alone for a given database. 283.Ss Default source lists 284If, for any reason, 285.Nm 286does not exist, or it has missing or corrupt entries, 287.Xr nsdispatch 3 288will default to an entry of 289.Dq files 290for the requested database. 291Exceptions are: 292.Pp 293.Bl -tag -width services_compat -compact 294.It Sy Database 295.Sy "Default source list" 296.It group 297compat 298.It group_compat 299nis 300.It hosts 301files dns 302.It passwd 303compat 304.It passwd_compat 305nis 306.It services 307compat 308.It services_compat 309nis 310.El 311.Sh FILES 312.Bl -tag -width /etc/nsswitch.conf -compact 313.It Pa /etc/nsswitch.conf 314The file 315.Nm 316resides in 317.Pa /etc . 318.El 319.Sh EXAMPLES 320To lookup hosts in cache, then in 321.Pa /etc/hosts 322and then from the DNS, and lookup user information from 323.Tn NIS 324then files, use: 325.Pp 326.Bl -tag -width passwd: -compact 327.It hosts: 328cache files 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 341If system got compiled with 342.Va WITHOUT_NIS 343you have to remove 344.Sq nis 345entries. 346.Pp 347.Fx Ns 's 348.Lb libc 349provides stubs for compatibility with NSS modules 350written for the 351.Tn GNU 352C Library 353.Nm nsswitch 354interface. 355However, these stubs only support the use of the 356.Dq Li passwd 357and 358.Dq Li group 359databases. 360.Sh SEE ALSO 361.Xr nsdispatch 3 , 362.Xr nscd.conf 5 , 363.Xr resolv.conf 5 , 364.Xr nscd 8 , 365.Xr ypbind 8 366.Sh HISTORY 367The 368.Nm 369file format first appeared in 370.Fx 5.0 . 371It was imported from the 372.Nx 373Project, where it appeared first in 374.Nx 1.4 . 375.Sh AUTHORS 376.An Luke Mewburn Aq Mt lukem@netbsd.org 377wrote this freely distributable name-service switch implementation, 378using ideas from the 379.Tn ULTRIX 380.Xr svc.conf 5 381and 382.Tn Solaris 383.Xr nsswitch.conf 4 384manual pages. 385