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