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: src/share/man/man5/nsswitch.conf.5,v 1.18 2007/10/19 00:16:29 bushman Exp $
  35 .\" $DragonFly: src/share/man/man5/nsswitch.conf.5,v 1.1 2003/08/01 04:11:23 rob Exp $
  36 .\"
  37 .Dd January 22, 2007
  38 .Dt NSSWITCH.CONF 5
  39 .Os
  40 .Sh NAME
  41 .Nm nsswitch.conf
  42 .Nd name-service switch configuration file
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 file specifies how the
  47 .Xr nsdispatch 3
  48 (name-service switch dispatcher) routines in the C library should operate.
  49 .Pp
  50 The configuration file controls how a process looks up various databases
  51 containing information regarding hosts, users (passwords), groups, etc.
  52 Each database comes from a source (such as local files, DNS,
  53 .Tn NIS ,
  54 and cache), and the order to look up the sources is specified in
  55 .Nm .
  56 .Pp
  57 Each entry in
  58 .Nm
  59 consists of a database name, and a space separated list of sources.
  60 Each source can have an optional trailing criterion that determines
  61 whether the next listed source is used, or the search terminates at
  62 the current source.
  63 Each criterion consists of one or more status codes, and actions to
  64 take if that status code occurs.
  65 .Ss Sources
  66 The following sources are implemented:
  67 .Pp
  68 .Bl -tag -width Source -compact
  69 .It Sy Source
  70 .Sy Description
  71 .It files
  72 Local files, such as
  73 .Pa /etc/hosts ,
  74 and
  75 .Pa /etc/passwd .
  76 .It dns
  77 Internet Domain Name System.
  78 .Dq hosts
  79 and
  80 .Sq networks
  81 use
  82 .Sy IN
  83 class entries, all other databases use
  84 .Sy HS
  85 class (Hesiod) entries.
  86 .It nis
  87 NIS (formerly YP)
  88 .It compat
  89 support
  90 .Sq +/-
  91 in the
  92 .Dq passwd
  93 and
  94 .Dq group
  95 databases.
  96 If this is present, it must be the only source for that entry.
  97 .It cache
  98 makes use of the
  99 .Xr nscd 8
 100 daemon.
 101 .El
 102 .Ss Databases
 103 The following databases are used by the following C library functions:
 104 .Pp
 105 .Bl -tag -width networks -compact
 106 .It Sy Database
 107 .Sy "Used by"
 108 .It group
 109 .Xr getgrent 3 ,
 110 .Xr getgrent_r 3 ,
 111 .Xr getgrgid_r 3 ,
 112 .Xr getgrnam_r 3 ,
 113 .Xr setgrent 3 ,
 114 .Xr endgrent 3
 115 .It hosts
 116 .Xr getaddrinfo 3 ,
 117 .Xr gethostbyaddr 3 ,
 118 .Xr gethostbyaddr_r 3 ,
 119 .Xr gethostbyname 3 ,
 120 .Xr gethostbyname2 3 ,
 121 .Xr gethostbyname_r 3 ,
 122 .Xr getipnodebyaddr 3 ,
 123 .Xr getipnodebyname 3
 124 .It networks
 125 .Xr getnetbyaddr 3 ,
 126 .Xr getnetbyaddr_r 3 ,
 127 .Xr getnetbyname 3 ,
 128 .Xr getnetbyname_r 3
 129 .It passwd
 130 .Xr getpwent 3 ,
 131 .Xr getpwent_r 3 ,
 132 .Xr getpwnam_r 3 ,
 133 .Xr getpwuid_r 3 ,
 134 .Xr setpwent 3 ,
 135 .Xr endpwent 3
 136 .It shells
 137 .Xr getusershell 3
 138 .It services
 139 .Xr getservent 3
 140 .It rpc
 141 .Xr getrpcbyname 3 ,
 142 .Xr getrpcbynumber 3 ,
 143 .Xr getrpcent 3
 144 .It proto
 145 .Xr getprotobyname 3
 146 .Xr getprotobynumber 3 ,
 147 .Xr getprotoent 3
 148 .El
 149 .Ss Status codes
 150 The following status codes are available:
 151 .Pp
 152 .Bl -tag -width tryagain -compact
 153 .It Sy Status
 154 .Sy Description
 155 .It success
 156 The requested entry was found.
 157 .It notfound
 158 The entry is not present at this source.
 159 .It tryagain
 160 The source is busy, and may respond to retries.
 161 .It unavail
 162 The source is not responding, or entry is corrupt.
 163 .El
 164 .Ss Actions
 165 For each of the status codes, one of two actions is possible:
 166 .Pp
 167 .Bl -tag -width continue -compact
 168 .It Sy Action
 169 .Sy Description
 170 .It continue
 171 Try the next source
 172 .It return
 173 Return with the current result
 174 .El
 175 .Ss Format of file
 176 A
 177 .Tn BNF
 178 description of the syntax of
 179 .Nm
 180 is:
 181 .Pp
 182 .Bl -tag -width <criterion> -compact
 183 .It <entry>
 184 ::=
 185 <database> ":" [<source> [<criteria>]]*
 186 .It <criteria>
 187 ::=
 188 "[" <criterion>+ "]"
 189 .It <criterion>
 190 ::=
 191 <status> "=" <action>
 192 .It <status>
 193 ::=
 194 "success" | "notfound" | "unavail" | "tryagain"
 195 .It <action>
 196 ::=
 197 "return" | "continue"
 198 .El
 199 .Pp
 200 Each entry starts on a new line in the file.
 201 A
 202 .Sq #
 203 delimits a comment to end of line.
 204 Blank lines are ignored.
 205 A
 206 .Sq \e
 207 at the end of a line escapes the newline, and causes the next line to
 208 be a continuation of the current line.
 209 All entries are case-insensitive.
 210 .Pp
 211 The default criteria is to return on
 212 .Dq success ,
 213 and continue on anything else (i.e,
 214 .Li "[success=return notfound=continue unavail=continue tryagain=continue]" ) .
 215 .Ss Cache
 216 You can enable caching for the particular database by specifying
 217 .Dq cache
 218 as the first source in the
 219 .Xr nsswitch.conf 5
 220 file.
 221 You should also enable caching for this database in
 222 .Xr nscd.conf 5 .
 223 If for the particular query
 224 .Dq cache
 225 source returns success, no further sources are queried.
 226 On the other hand, if there are no previously cached data, the
 227 query result will be placed into the cache right after
 228 all other sources are processed.
 229 Note, that
 230 .Dq cache
 231 requires
 232 .Xr nscd 8
 233 daemon to be running.
 234 .Ss Compat mode: +/- syntax
 235 In historical multi-source implementations, the
 236 .Sq +
 237 and
 238 .Sq -
 239 characters are used to specify the importing of user password and
 240 group information from
 241 .Tn NIS .
 242 Although
 243 .Nm
 244 provides alternative methods of accessing distributed sources such as
 245 .Tn NIS ,
 246 specifying a sole source of
 247 .Dq compat
 248 will provide the historical behaviour.
 249 .Pp
 250 An alternative source for the information accessed via
 251 .Sq +/-
 252 can be used by specifying
 253 .Dq passwd_compat: source .
 254 .Dq source
 255 in this case can be
 256 .Sq dns ,
 257 .Sq nis ,
 258 or
 259 any other source except for
 260 .Sq files
 261 and
 262 .Sq compat .
 263 .Ss Notes
 264 Historically, many of the databases had enumeration functions, often of
 265 the form
 266 .Fn getXXXent .
 267 These made sense when the databases were in local files, but do not make
 268 sense or have lesser relevance when there are possibly multiple sources,
 269 each of an unknown size.
 270 The interfaces are still provided for compatibility, but the source
 271 may not be able to provide complete entries, or duplicate entries may
 272 be retrieved if multiple sources that contain similar information are
 273 specified.
 274 .Pp
 275 To ensure compatibility with previous and current implementations, the
 276 .Dq compat
 277 source must appear alone for a given database.
 278 .Ss Default source lists
 279 If, for any reason,
 280 .Nm
 281 does not exist, or it has missing or corrupt entries,
 282 .Xr nsdispatch 3
 283 will default to an entry of
 284 .Dq files
 285 for the requested database.
 286 Exceptions are:
 287 .Pp
 288 .Bl -tag -width services_compat -compact
 289 .It Sy Database
 290 .Sy "Default source list"
 291 .It group
 292 compat
 293 .It group_compat
 294 nis
 295 .It hosts
 296 files dns
 297 .It passwd
 298 compat
 299 .It passwd_compat
 300 nis
 301 .It services
 302 compat
 303 .It services_compat
 304 nis
 305 .El
 306 .Sh FILES
 307 .Bl -tag -width /etc/nsswitch.conf -compact
 308 .It Pa /etc/nsswitch.conf
 309 The file
 310 .Nm
 311 resides in
 312 .Pa /etc .
 313 .El
 314 .Sh EXAMPLES
 315 To lookup hosts in cache, then in
 316 .Pa /etc/hosts
 317 and then from the DNS, and lookup user information from
 318 .Tn NIS
 319 then files, use:
 320 .Pp
 321 .Bl -tag -width passwd: -compact
 322 .It hosts:
 323 cache files dns
 324 .It passwd:
 325 nis [notfound=return] files
 326 .It group:
 327 nis [notfound=return] files
 328 .El
 329 .Pp
 330 The criteria
 331 .Dq [notfound=return]
 332 sets a policy of "if the user is notfound in nis, do not try files."
 333 This treats nis as the authoritative source of information, except
 334 when the server is down.
 335 .Sh NOTES
 336 If system got compiled with
 337 .Va WITHOUT_NIS
 338 you have to remove
 339 .Sq nis
 340 entries.
 341 .Pp
 342 .Dx Ns 's
 343 .Lb libc
 344 provides stubs for compatibility with NSS modules
 345 written for the
 346 .Tn GNU
 347 C Library
 348 .Nm nsswitch
 349 interface.
 350 However, these stubs only support the use of the
 351 .Dq Li passwd
 352 and
 353 .Dq Li group
 354 databases.
 355 .Sh SEE ALSO
 356 .Xr nsdispatch 3 ,
 357 .Xr nscd.conf 5 ,
 358 .Xr resolv.conf 5 ,
 359 .Xr nscd 8 ,
 360 .Xr named 8 ,
 361 .Xr ypbind 8
 362 .Sh HISTORY
 363 The
 364 .Nm
 365 file format first appeared in
 366 .Dx 2.1 .
 367 It was imported from the
 368 .Fx
 369 Project, where it appeared first in
 370 .Fx 5.0 .
 371 .Sh AUTHORS
 372 Luke Mewburn
 373 .Aq lukem@netbsd.org
 374 wrote this freely distributable name-service switch implementation,
 375 using ideas from the
 376 .Tn ULTRIX
 377 .Xr svc.conf 5
 378 and
 379 .Tn Solaris
 380 .Xr nsswitch.conf 4
 381 manual pages.