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