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