share/man/man5/nsswitch.conf.5

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