share/man/man5/nsswitch.conf.5

   1 .\"     $NetBSD: nsswitch.conf.5,v 1.14 1999/03/17 20:19:47 garbled Exp $
   2 .\"     $FreeBSD$
   3 .\"
   4 .\"  Copyright (c) 1997, 1998, 1999 The NetBSD Foundation, Inc.
   5 .\"  All rights reserved.
   6 .\"
   7 .\"  This code is derived from software contributed to The NetBSD Foundation
   8 .\"  by Luke Mewburn.
   9 .\"
  10 .\"  Redistribution and use in source and binary forms, with or without
  11 .\"  modification, are permitted provided that the following conditions
  12 .\"  are met:
  13 .\"  1. Redistributions of source code must retain the above copyright
  14 .\"     notice, this list of conditions and the following disclaimer.
  15 .\"  2. Redistributions in binary form must reproduce the above copyright
  16 .\"     notice, this list of conditions and the following disclaimer in the
  17 .\"     documentation and/or other materials provided with the distribution.
  18 .\"  3. All advertising materials mentioning features or use of this software
  19 .\"     must display the following acknowledgement:
  20 .\"     This product includes software developed by Luke Mewburn.
  21 .\"  4. The name of the author may not be used to endorse or promote products
  22 .\"     derived from this software without specific prior written permission.
  23 .\"
  24 .\"  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  25 .\"  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  26 .\"  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  27 .\"  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  28 .\"  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  29 .\"  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
  30 .\"  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  31 .\"  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
  32 .\"  TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
  33 .\"  USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34 .\"
  35 .Dd June 21, 2004
  36 .Dt NSSWITCH.CONF 5
  37 .Os
  38 .Sh NAME
  39 .Nm nsswitch.conf
  40 .Nd name-service switch configuration file
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 file specifies how the
  45 .Xr nsdispatch 3
  46 (name-service switch dispatcher) routines in the C library should operate.
  47 .Pp
  48 The configuration file controls how a process looks up various databases
  49 containing information regarding hosts, users (passwords), groups, etc.
  50 Each database comes from a source (such as local files, DNS, and
  51 .Tn NIS ) ,
  52 and the order to look up the sources is specified in
  53 .Nm .
  54 .Pp
  55 Each entry in
  56 .Nm
  57 consists of a database name, and a space separated list of sources.
  58 Each source can have an optional trailing criterion that determines
  59 whether the next listed source is used, or the search terminates at
  60 the current source.
  61 Each criterion consists of one or more status codes, and actions to
  62 take if that status code occurs.
  63 .Ss Sources
  64 The following sources are implemented:
  65 .Pp
  66 .Bl -tag -width Source -compact
  67 .It Sy Source
  68 .Sy Description
  69 .It files
  70 Local files, such as
  71 .Pa /etc/hosts ,
  72 and
  73 .Pa /etc/passwd .
  74 .It dns
  75 Internet Domain Name System.
  76 .Dq hosts
  77 and
  78 .Sq networks
  79 use
  80 .Sy IN
  81 class entries, all other databases use
  82 .Sy HS
  83 class (Hesiod) entries.
  84 .It nis
  85 NIS (formerly YP)
  86 .It compat
  87 support
  88 .Sq +/-
  89 in the
  90 .Dq passwd
  91 and
  92 .Dq group
  93 databases.
  94 If this is present, it must be the only source for that entry.
  95 .El
  96 .Ss Databases
  97 The following databases are used by the following C library functions:
  98 .Pp
  99 .Bl -tag -width networks -compact
 100 .It Sy Database
 101 .Sy "Used by"
 102 .It group
 103 .Xr getgrent 3
 104 .It hosts
 105 .Xr gethostbyname 3
 106 .It networks
 107 .Xr getnetbyname 3
 108 .It passwd
 109 .Xr getpwent 3
 110 .It shells
 111 .Xr getusershell 3
 112 .El
 113 .Ss Status codes
 114 The following status codes are available:
 115 .Pp
 116 .Bl -tag -width tryagain -compact
 117 .It Sy Status
 118 .Sy Description
 119 .It success
 120 The requested entry was found.
 121 .It notfound
 122 The entry is not present at this source.
 123 .It tryagain
 124 The source is busy, and may respond to retries.
 125 .It unavail
 126 The source is not responding, or entry is corrupt.
 127 .El
 128 .Ss Actions
 129 For each of the status codes, one of two actions is possible:
 130 .Pp
 131 .Bl -tag -width continue -compact
 132 .It Sy Action
 133 .Sy Description
 134 .It continue
 135 Try the next source
 136 .It return
 137 Return with the current result
 138 .El
 139 .Ss Format of file
 140 A
 141 .Tn BNF
 142 description of the syntax of
 143 .Nm
 144 is:
 145 .Pp
 146 .Bl -tag -width <criterion> -compact
 147 .It <entry>
 148 ::=
 149 <database> ":" [<source> [<criteria>]]*
 150 .It <criteria>
 151 ::=
 152 "[" <criterion>+ "]"
 153 .It <criterion>
 154 ::=
 155 <status> "=" <action>
 156 .It <status>
 157 ::=
 158 "success" | "notfound" | "unavail" | "tryagain"
 159 .It <action>
 160 ::=
 161 "return" | "continue"
 162 .El
 163 .Pp
 164 Each entry starts on a new line in the file.
 165 A
 166 .Sq #
 167 delimits a comment to end of line.
 168 Blank lines are ignored.
 169 A
 170 .Sq \e
 171 at the end of a line escapes the newline, and causes the next line to
 172 be a continuation of the current line.
 173 All entries are case-insensitive.
 174 .Pp
 175 The default criteria is to return on
 176 .Dq success ,
 177 and continue on anything else (i.e,
 178 .Li "[success=return notfound=continue unavail=continue tryagain=continue]" ) .
 179 .Ss Compat mode: +/- syntax
 180 In historical multi-source implementations, the
 181 .Sq +
 182 and
 183 .Sq -
 184 characters are used to specify the importing of user password and
 185 group information from
 186 .Tn NIS .
 187 Although
 188 .Nm
 189 provides alternative methods of accessing distributed sources such as
 190 .Tn NIS ,
 191 specifying a sole source of
 192 .Dq compat
 193 will provide the historical behaviour.
 194 .Pp
 195 An alternative source for the information accessed via
 196 .Sq +/-
 197 can be used by specifying
 198 .Dq passwd_compat: source .
 199 .Dq source
 200 in this case can be
 201 .Sq dns ,
 202 .Sq nis ,
 203 or
 204 any other source except for
 205 .Sq files
 206 and
 207 .Sq compat .
 208 .Ss Notes
 209 Historically, many of the databases had enumeration functions, often of
 210 the form
 211 .Fn getXXXent .
 212 These made sense when the databases were in local files, but don't make
 213 sense or have lesser relevance when there are possibly multiple sources,
 214 each of an unknown size.
 215 The interfaces are still provided for compatibility, but the source
 216 may not be able to provide complete entries, or duplicate entries may
 217 be retrieved if multiple sources that contain similar information are
 218 specified.
 219 .Pp
 220 To ensure compatibility with previous and current implementations, the
 221 .Dq compat
 222 source must appear alone for a given database.
 223 .Ss Default source lists
 224 If, for any reason,
 225 .Nm
 226 doesn't exist, or it has missing or corrupt entries,
 227 .Xr nsdispatch 3
 228 will default to an entry of
 229 .Dq files
 230 for the requested database.
 231 Exceptions are:
 232 .Pp
 233 .Bl -tag -width passwd_compat -compact
 234 .It Sy Database
 235 .Sy "Default source list"
 236 .It group
 237 compat
 238 .It group_compat
 239 nis
 240 .It hosts
 241 files dns
 242 .It passwd
 243 compat
 244 .It passwd_compat
 245 nis
 246 .El
 247 .Sh FILES
 248 .Bl -tag -width /etc/nsswitch.conf -compact
 249 .It Pa /etc/nsswitch.conf
 250 The file
 251 .Nm
 252 resides in
 253 .Pa /etc .
 254 .El
 255 .Sh EXAMPLES
 256 To lookup hosts in
 257 .Pa /etc/hosts
 258 and then from the DNS, and lookup user information from
 259 .Tn NIS
 260 then files, use:
 261 .Pp
 262 .Bl -tag -width passwd: -compact
 263 .It hosts:
 264 files dns
 265 .It passwd:
 266 nis [notfound=return] files
 267 .It group:
 268 nis [notfound=return] files
 269 .El
 270 .Pp
 271 The criteria
 272 .Dq [notfound=return]
 273 sets a policy of "if the user is notfound in nis, don't try files."
 274 This treats nis as the authoritative source of information, except
 275 when the server is down.
 276 .Sh SEE ALSO
 277 .Xr nsdispatch 3 ,
 278 .Xr resolv.conf 5 ,
 279 .Xr named 8 ,
 280 .Xr ypbind 8
 281 .Sh HISTORY
 282 The
 283 .Nm
 284 file format first appeared in
 285 .Fx 5.0 .
 286 It was imported from the
 287 .Nx
 288 Project, where it appeared first in
 289 .Nx 1.4 .
 290 .Sh AUTHORS
 291 Luke Mewburn
 292 .Aq lukem@netbsd.org
 293 wrote this freely distributable name-service switch implementation,
 294 using ideas from the
 295 .Tn ULTRIX
 296 .Xr svc.conf 5
 297 and
 298 .Tn Solaris
 299 .Xr nsswitch.conf 4
 300 manual pages.