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