share/man/man5/nsswitch.conf.5

   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 May 20, 2006
  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,
  52 .Tn NIS ,
  53 and cache), 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 .It cache
  97 makes use of the
  98 .Xr cached 8
  99 daemon.
 100 .El
 101 .Ss Databases
 102 The 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 .It hosts
 110 .Xr gethostbyname 3
 111 .It networks
 112 .Xr getnetbyname 3
 113 .It passwd
 114 .Xr getpwent 3
 115 .It shells
 116 .Xr getusershell 3
 117 .It services
 118 .Xr getservent 3
 119 .It rpc
 120 .Xr getrpcent 3
 121 .It proto
 122 .Xr getprotobyname 3
 123 .El
 124 .Ss Status codes
 125 The following status codes are available:
 126 .Pp
 127 .Bl -tag -width tryagain -compact
 128 .It Sy Status
 129 .Sy Description
 130 .It success
 131 The requested entry was found.
 132 .It notfound
 133 The entry is not present at this source.
 134 .It tryagain
 135 The source is busy, and may respond to retries.
 136 .It unavail
 137 The source is not responding, or entry is corrupt.
 138 .El
 139 .Ss Actions
 140 For each of the status codes, one of two actions is possible:
 141 .Pp
 142 .Bl -tag -width continue -compact
 143 .It Sy Action
 144 .Sy Description
 145 .It continue
 146 Try the next source
 147 .It return
 148 Return with the current result
 149 .El
 150 .Ss Format of file
 151 A
 152 .Tn BNF
 153 description of the syntax of
 154 .Nm
 155 is:
 156 .Pp
 157 .Bl -tag -width <criterion> -compact
 158 .It <entry>
 159 ::=
 160 <database> ":" [<source> [<criteria>]]*
 161 .It <criteria>
 162 ::=
 163 "[" <criterion>+ "]"
 164 .It <criterion>
 165 ::=
 166 <status> "=" <action>
 167 .It <status>
 168 ::=
 169 "success" | "notfound" | "unavail" | "tryagain"
 170 .It <action>
 171 ::=
 172 "return" | "continue"
 173 .El
 174 .Pp
 175 Each entry starts on a new line in the file.
 176 A
 177 .Sq #
 178 delimits a comment to end of line.
 179 Blank lines are ignored.
 180 A
 181 .Sq \e
 182 at the end of a line escapes the newline, and causes the next line to
 183 be a continuation of the current line.
 184 All entries are case-insensitive.
 185 .Pp
 186 The default criteria is to return on
 187 .Dq success ,
 188 and continue on anything else (i.e,
 189 .Li "[success=return notfound=continue unavail=continue tryagain=continue]" ) .
 190 .Ss Cache
 191 You can enable caching for the particular database by specifying
 192 .Dq cache
 193 as the first source in the
 194 .Xr nsswitch.conf 5
 195 file.
 196 You should also enable caching for this database in
 197 .Xr cached.conf 5 .
 198 If for the particular query
 199 .Dq cache
 200 source returns success, no further sources are queried.
 201 On the other hand, if there are no previously cached data, the
 202 query result will be placed into the cache right after
 203 all other sources are processed.
 204 Note, that
 205 .Dq cache
 206 requires
 207 .Xr cached 8
 208 daemon to be running.
 209 .Ss Compat mode: +/- syntax
 210 In historical multi-source implementations, the
 211 .Sq +
 212 and
 213 .Sq -
 214 characters are used to specify the importing of user password and
 215 group information from
 216 .Tn NIS .
 217 Although
 218 .Nm
 219 provides alternative methods of accessing distributed sources such as
 220 .Tn NIS ,
 221 specifying a sole source of
 222 .Dq compat
 223 will provide the historical behaviour.
 224 .Pp
 225 An alternative source for the information accessed via
 226 .Sq +/-
 227 can be used by specifying
 228 .Dq passwd_compat: source .
 229 .Dq source
 230 in this case can be
 231 .Sq dns ,
 232 .Sq nis ,
 233 or
 234 any other source except for
 235 .Sq files
 236 and
 237 .Sq compat .
 238 .Ss Notes
 239 Historically, many of the databases had enumeration functions, often of
 240 the form
 241 .Fn getXXXent .
 242 These made sense when the databases were in local files, but do not make
 243 sense or have lesser relevance when there are possibly multiple sources,
 244 each of an unknown size.
 245 The interfaces are still provided for compatibility, but the source
 246 may not be able to provide complete entries, or duplicate entries may
 247 be retrieved if multiple sources that contain similar information are
 248 specified.
 249 .Pp
 250 To ensure compatibility with previous and current implementations, the
 251 .Dq compat
 252 source must appear alone for a given database.
 253 .Ss Default source lists
 254 If, for any reason,
 255 .Nm
 256 does not exist, or it has missing or corrupt entries,
 257 .Xr nsdispatch 3
 258 will default to an entry of
 259 .Dq files
 260 for the requested database.
 261 Exceptions are:
 262 .Pp
 263 .Bl -tag -width services_compat -compact
 264 .It Sy Database
 265 .Sy "Default source list"
 266 .It group
 267 compat
 268 .It group_compat
 269 nis
 270 .It hosts
 271 files dns
 272 .It passwd
 273 compat
 274 .It passwd_compat
 275 nis
 276 .It services
 277 compat
 278 .It services_compat
 279 nis
 280 .El
 281 .Sh FILES
 282 .Bl -tag -width /etc/nsswitch.conf -compact
 283 .It Pa /etc/nsswitch.conf
 284 The file
 285 .Nm
 286 resides in
 287 .Pa /etc .
 288 .El
 289 .Sh EXAMPLES
 290 To lookup hosts in cache, then in
 291 .Pa /etc/hosts
 292 and then from the DNS, and lookup user information from
 293 .Tn NIS
 294 then files, use:
 295 .Pp
 296 .Bl -tag -width passwd: -compact
 297 .It hosts:
 298 cache files dns
 299 .It passwd:
 300 nis [notfound=return] files
 301 .It group:
 302 nis [notfound=return] files
 303 .El
 304 .Pp
 305 The criteria
 306 .Dq [notfound=return]
 307 sets a policy of "if the user is notfound in nis, do not try files."
 308 This treats nis as the authoritative source of information, except
 309 when the server is down.
 310 .Sh NOTES
 311 If system got compiled with
 312 .Va WITHOUT_NIS
 313 you have to remove
 314 .Sq nis
 315 entries.
 316 .Sh SEE ALSO
 317 .Xr nsdispatch 3 ,
 318 .Xr cached.conf 5 ,
 319 .Xr resolv.conf 5 ,
 320 .Xr cached 8 ,
 321 .Xr named 8 ,
 322 .Xr ypbind 8
 323 .Sh HISTORY
 324 The
 325 .Nm
 326 file format first appeared in
 327 .Fx 5.0 .
 328 It was imported from the
 329 .Nx
 330 Project, where it appeared first in
 331 .Nx 1.4 .
 332 .Sh AUTHORS
 333 Luke Mewburn
 334 .Aq lukem@netbsd.org
 335 wrote this freely distributable name-service switch implementation,
 336 using ideas from the
 337 .Tn ULTRIX
 338 .Xr svc.conf 5
 339 and
 340 .Tn Solaris
 341 .Xr nsswitch.conf 4
 342 manual pages.