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