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