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