8322 nl: misleading-indentation
[unleashed/tickless.git] / usr / src / man / man4 / nsswitch.conf.4
blobea46118b9d34836aa5bf2d0ea605893f92089636
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH NSSWITCH.CONF 4 "Mar 6, 2017"
7 .SH NAME
8 nsswitch.conf \- configuration file for the name service switch
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/etc/nsswitch.conf\fR
13 .fi
15 .SH DESCRIPTION
16 .LP
17 The operating system uses a number of databases of information about hosts,
18 ipnodes, users (\fBpasswd\fR(4), \fBshadow\fR(4), and \fBuser_attr\fR(4)), and
19 groups. Data for these can come from a variety of sources: hostnames and host
20 addresses, for example, can be found in \fB/etc/hosts\fR, \fBNIS\fR,
21 \fBLDAP\fR, \fBDNS\fR or Multicast \fBDNS\fR. Zero or more sources
22 can be used for each database; the sources and their lookup order are specified
23 in the \fB/etc/nsswitch.conf\fR file.
24 .sp
25 .LP
26 The following databases use the \fBswitch\fR file:
27 .sp
29 .sp
30 .TS
31 c c
32 l l .
33 Database        Used By
34 \fBaliases\fR   \fBsendmail\fR(1M)
35 \fBauth_attr\fR \fBgetauthnam\fR(3SECDB)
36 \fBautomount\fR \fBautomount\fR(1M)
37 \fBbootparams\fR        \fBrpc.bootparamd\fR(1M)
38 \fBethers\fR    \fBethers\fR(3SOCKET)
39 \fBgroup\fR     \fBgetgrnam\fR(3C)
40 \fBhosts\fR     T{
41 \fBgethostbyname\fR(3NSL), \fBgetaddrinfo\fR(3SOCKET). See \fBInteraction with netconfig\fR.
43 \fBipnodes\fR   Same as \fBhosts\fR.
44 \fBnetgroup\fR  \fBinnetgr\fR(3C)
45 \fBnetmasks\fR  \fBifconfig\fR(1M)
46 \fBnetworks\fR  \fBgetnetbyname\fR(3SOCKET)
47 \fBpasswd\fR    T{
48 \fBgetpwnam\fR(3C), \fBgetspnam\fR(3C), \fBgetusernam\fR(3SECDB)
50 \fBprinters\fR  T{
51 \fBlp\fR(1), \fBlpstat\fR(1), \fBcancel\fR(1), \fBlpr\fR(1B), \fBlpq\fR(1B), \fBlprm\fR(1B), \fBin.lpd\fR(1M), \fBlpadmin\fR(1M), \fBlpget\fR(1M), \fBlpset\fR(1M)
53 \fBprof_attr\fR \fBgetprofnam\fR(3SECDB), \fBgetexecprof\fR(3SECDB)
54 \fBproject\fR   T{
55 \fBgetprojent\fR(3PROJECT), \fBgetdefaultproj\fR(3PROJECT), \fBinproj\fR(3PROJECT), \fBnewtask\fR(1), \fBsetproject\fR(3PROJECT)
57 \fBprotocols\fR \fBgetprotobyname\fR(3SOCKET)
58 \fBpublickey\fR \fBgetpublickey\fR(3NSL), \fBsecure_rpc\fR(3NSL)
59 \fBrpc\fR       \fBgetrpcbyname\fR(3NSL)
60 \fBservices\fR  \fBgetservbyname\fR(3SOCKET).
61         See \fBInteraction with netconfig\fR.
62 \fBuser_attr\fR \fBgetuserattr\fR(3SECDB)
63 .TE
65 .sp
66 .LP
67 The following sources can be used:
68 .sp
70 .sp
71 .TS
72 c c
73 l l .
74 Source  Uses
75 \fBfiles\fR     T{
76 \fB/etc/hosts\fR, \fB/etc/passwd\fR, \fB/etc/inet/ipnodes\fR, \fB/etc/shadow\fR, \fB/etc/security/auth_attr\fR, \fB/etc/user_attr\fR
78 \fBnis\fR       \fBNIS\fR(\fBYP\fR)
79 \fBldap\fR      \fBLDAP\fR
80 \fBad\fR        Active Directory
81 \fBdns\fR       T{
82 Valid only for hosts and ipnodes. Uses the Internet Domain Name Service.
84 \fBmdns\fR      T{
85 Valid only for hosts and ipnodes. Uses the Multicast Domain Name Service.
87 \fBcompat\fR    T{
88 Valid only for \fBpasswd\fR and \fBgroup\fR. Implements \fB+\fR and \fB-.\fR See \fBInteraction with +/- syntax\fR.
90 \fBuser\fR      T{
91 Valid only for printers. Implements support for \fB${HOME}/.printers\fR.
93 .TE
95 .sp
96 .LP
97 Note that \fB/etc/inet/ipnodes\fR is a symbolic link to \fB/etc/hosts\fR.
98 .sp
99 .LP
100 There is an entry in \fB/etc/nsswitch.conf\fR for each database. Typically
101 these entries are simple, such as \fBprotocols: files\fR. However, when
102 multiple sources are specified, it is sometimes necessary to define precisely
103 the circumstances under which each source is tried. A source can return one
104 of the following codes:
109 c c
110 l l .
111 Status  Meaning
112 \fBSUCCESS\fR   Requested database entry was found.
113 \fBUNAVAIL\fR   T{
114 Source is not configured on this system or internal failure.
116 \fBNOTFOUND\fR  Source responded "\fBno such entry\fR"
117 \fBTRYAGAIN\fR  T{
118 Source is busy or not responding, might respond to retries.
124 For each status code, two actions are possible:
129 c c
130 l l .
131 Action  Meaning
132 \fBcontinue\fR  Try the next source in the list.
133 \fBreturn\fR    Return now.
138 Additionally, for \fBTRYAGAIN\fR only, the following actions are possible:
143 c c
144 l l .
145 Action  Meaning
146 \fBforever\fR   Retry the current source forever.
147 \fIn\fR T{
148 Retry the current source \fIn\fR more times, where \fIn\fR is an integer between \fB0\fR and \fBMAX_INT\fR (that is, 2.14 billion). After \fIn\fR retries has been exhausted, the \fBTRYAGAIN\fR action transitions to \fBcontinue\fR, until a future request receives a response, at which time \fBTRYAGAIN\fR=\fIn\fR is restored.
154 The complete syntax of an entry is:
156 .in +2
158 <entry>     ::= <database> ":" [<source> [<criteria>]]*
159 <criteria>  ::= "[" <criterion>+ "]"
160 <criterion> ::= <status> "=" <action>
161 <status>    ::= "success" | "notfound" | "unavail" | "tryagain"
163 .in -2
167 For every status except \fBTRYAGAIN\fR, the action syntax is:
169 .in +2
171 <action>    ::= "return"  | "continue"
173 .in -2
177 For the \fBTRYAGAIN\fR status, the action syntax is:
179 .in +2
181 <action>    ::= "return"  | "continue" | "forever" | <n>
182 <n>         ::= 0...MAX_INT
184 .in -2
188 Each entry occupies a single line in the file. Lines that are blank, or that
189 start with white space, are ignored. Everything on a line following a \fB#\fR
190 character is also ignored; the \fB#\fR character can begin anywhere in a line,
191 to be used to begin comments. The <database> and <source> names are
192 case-sensitive, but <action> and <status> names are case-insensitive.
195 The library functions contain compiled-in default entries that are used if the
196 appropriate entry in \fBnsswitch.conf\fR is absent or syntactically incorrect.
199 The default criteria for \fBDNS\fR and the \fBNIS\fR server in "DNS-forwarding
200 mode" is [\fBSUCCESS\fR=return \fBNOTFOUND\fR=continue \fBUNAVAIL\fR=continue
201 \fBTRYAGAIN\fR=3].
204 The default criteria for all other sources is [\fBSUCCESS\fR=return
205 \fBNOTFOUND\fR=continue \fBUNAVAIL\fR=continue \fBTRYAGAIN\fR=forever].
208 The default, or explicitly specified, criteria are meaningless following the
209 last source in an entry; and they are ignored, since the action is always to
210 return to the caller irrespective of the status code the source returns.
211 .SS "Interaction with \fBnetconfig\fR"
213 In order to ensure that they all return consistent results,
214 \fBgethostbyname\fR(3NSL), \fBgetaddrinfo\fR(3SOCKET),
215 \fBgetservbyname\fR(3SOCKET), and \fBnetdir_getbyname\fR(3NSL) functions are
216 all implemented in terms of the same internal library function. This function
217 obtains the system-wide source lookup policy for \fBhosts\fR, \fBipnodes\fR,
218 and \fBservices\fR based on the \fBinet\fR family entries in \fBnetconfig\fR(4)
219 and uses the switch entries only if the \fBnetconfig\fR entries have a \fB-\fR
220 (hyphen) in the last column for \fBnametoaddr\fR libraries. See the Notes
221 section in \fBgethostbyname\fR(3NSL) and \fBgetservbyname\fR(3SOCKET) for
222 details.
223 .SS "Interaction with server in DNS-forwarding Mode"
225 The \fBNIS\fR (\fBYP\fR) server can be run in DNS-forwarding mode, where it
226 forwards lookup requests to \fBDNS\fR for host-names and -addresses that do not
227 exist in its database. In this case, specifying \fBnis\fR as a source for
228 \fBhosts\fR is sufficient to get \fBDNS\fR lookups; \fBdns\fR need not be
229 specified explicitly as a source.
230 .SS "Interaction with Password Aging"
232 When password aging is turned on, only a limited set of possible name services
233 are permitted for the \fBpasswd\fR: database in the \fB/etc/nsswitch.conf\fR
234 file:
236 .ne 2
238 \fBpasswd:\fR
240 .RS 18n
241 files
245 .ne 2
247 \fBpasswd:\fR
249 .RS 18n
250 files nis
254 .ne 2
256 \fBpasswd:\fR
258 .RS 18n
259 files ldap
263 .ne 2
265 \fBpasswd:\fR
267 .RS 18n
268 compat
272 .ne 2
274 \fBpasswd_compat:\fR
276 .RS 18n
277 ldap
282 You can add the \fBad\fR keyword to any of the \fBpasswd\fR configurations
283 listed above. However, you cannot use the \fBpasswd\fR command to change the
284 password of an Active Directory (AD) user. If the \fBad\fR keyword is found in
285 the \fBpasswd\fR entry during a password update operation, it is ignored. To
286 update the password of an AD user, use the \fBkpasswd\fR(1) command.
289 Any other settings causes the \fBpasswd\fR(1) command to fail when it attempts
290 to change the password after expiration and prevents the user from logging in.
291 These are the \fBonly\fR permitted settings when password aging has been turned
292 on. Otherwise, you can work around incorrect \fBpasswd\fR: lines by using the
293 \fB-r repository\fR argument to the \fBpasswd\fR(1) command and using \fBpasswd
294 -r repository\fR to override the \fBnsswitch.conf\fR settings and specify in
295 which name service you want to modify your password.
296 .SS "Interaction with +/- syntax"
298 Releases prior to SunOS 5.0 did not have the name service switch but did allow
299 the user some policy control. In \fB/etc/passwd\fR one could have entries of
300 the form \fI+user\fR (include the specified user from \fBNIS\fR passwd.byname),
301 \fI-user\fR (exclude the specified user) and \fB+\fR (include everything,
302 except excluded users, from \fBNIS\fR passwd.byname). The desired behavior was
303 often \fBeverything in the file followed by everything in NIS\fR, expressed by
304 a solitary \fB+\fR at the end of \fB/etc/passwd\fR. The switch provides an
305 alternative for this case (\fBpasswd: files nis\fR) that does not require
306 \fB+\fR entries in \fB/etc/passwd\fR and \fB/etc/shadow\fR (the latter is a new
307 addition to SunOS 5.0, see \fBshadow\fR(4)).
310 If this is not sufficient, the \fBNIS/YP\fR compatibility source provides full
311 +/- semantics. It reads \fB/etc/passwd\fR for \fBgetpwnam\fR(3C) functions and
312 \fB/etc/shadow\fR for \fBgetspnam\fR(3C) functions and, if it finds +/-
313 entries, invokes an appropriate source. By default, the source is \fBnis\fR,
314 but this can be overridden by specifying \fBldap\fR as the
315 source for the pseudo-database \fBpasswd_compat\fR.
318 Note that in compat mode, for every \fB/etc/passwd\fR entry, there must be a
319 corresponding entry in the \fB/etc/shadow\fR file.
322 The NIS/YP compatibility source also provides full +/- semantics for
323 \fBgroup\fR; the relevant pseudo-database is \fBgroup_compat\fR.
324 .SS "Useful Configurations"
326 The compiled-in default entries for all databases use \fBNIS (YP)\fR as the
327 enterprise level name service and are identical to those in the default
328 configuration of this file:
330 .ne 2
332 \fBpasswd:\fR
334 .RS 15n
335 files nis
339 .ne 2
341 \fBgroup:\fR
343 .RS 15n
344 files nis
348 .ne 2
350 \fBhosts:\fR
352 .RS 15n
353 nis [NOTFOUND=return] files
357 .ne 2
359 \fBipnodes:\fR
361 .RS 15n
362 nis [NOTFOUND=return] files
366 .ne 2
368 \fBnetworks:\fR
370 .RS 15n
371 nis [NOTFOUND=return] files
375 .ne 2
377 \fBprotocols:\fR
379 .RS 15n
380 nis [NOTFOUND=return] files
384 .ne 2
386 \fBrpc:\fR
388 .RS 15n
389 nis [NOTFOUND=return] files
393 .ne 2
395 \fBethers:\fR
397 .RS 15n
398 nis [NOTFOUND=return] files
402 .ne 2
404 \fBnetmasks:\fR
406 .RS 15n
407 nis [NOTFOUND=return] files
411 .ne 2
413 \fBbootparams:\fR
415 .RS 15n
416 nis [NOTFOUND=return] files
420 .ne 2
422 \fBpublickey:\fR
424 .RS 15n
425 nis [NOTFOUND=return] files
429 .ne 2
431 \fBnetgroup:\fR
433 .RS 15n
438 .ne 2
440 \fBautomount:\fR
442 .RS 15n
443 files nis
447 .ne 2
449 \fBaliases:\fR
451 .RS 15n
452 files nis
456 .ne 2
458 \fBservices:\fR
460 .RS 15n
461 files nis
465 .ne 2
467 \fBprinters:\fR
469 .RS 15n
470 user files nis
474 .ne 2
476 \fBauth_attr\fR
478 .RS 15n
479 files nis
483 .ne 2
485 \fBprof_attr\fR
487 .RS 15n
488 files nis
492 .ne 2
494 \fBproject\fR
496 .RS 15n
497 files nis
502 Note that the \fBfiles\fR source for the \fBipnodes\fR and \fBhosts\fR
503 databases is identical, as \fB/etc/inet/ipnodes\fR is a symbolic link to
504 \fB/etc/hosts\fR. Because other sources for the \fBipnodes\fR and \fBhosts\fR
505 databases are different, do not remove the \fBipnodes\fR line from the
506 \fB/etc/nsswitch.conf\fR file.
509 The policy \fBnis [NOTFOUND=return] files\fR implies: if \fBnis\fR is
510 \fBUNAVAIL\fR, continue on to \fBfiles\fR, and if \fBnis\fR returns
511 \fBNOTFOUND\fR, return to the caller. In other words, treat \fBnis\fR as the
512 authoritative source of information and try \fBfiles\fR only if \fBnis\fR is
513 down. This, and other policies listed in the default configuration above, are
514 identical to the hard-wired policies in SunOS releases prior to 5.0.
517 If compatibility with the +/- syntax for \fBpasswd\fR and \fBgroup\fR is
518 required, simply modify the entries for \fBpasswd\fR and \fBgroup\fR to:
520 .ne 2
522 \fBpasswd:\fR
524 .RS 11n
525 compat
529 .ne 2
531 \fBgroup:\fR
533 .RS 11n
534 compat
539 If \fBLDAP\fR is the enterprise level name service, the default configuration
540 should be modified to use \fBldap\fR instead of \fBnis\fR for every database on
541 client machines. The file \fB/etc/nsswitch.ldap\fR contains a sample
542 configuration that can be copied to \fB/etc/nsswitch.conf\fR to set this
543 policy.
546 When using Active Directory, \fBdns\fR is required to perform hosts resolution.
549 If the use of +/- syntax is desired in conjunction with \fBLDAP\fR, use the
550 following four entries:
552 .ne 2
554 \fBpasswd:\fR
556 .RS 18n
557 compat
561 .ne 2
563 \fBpasswd_compat:\fR
565 .RS 18n
566 ldap
570 .ne 2
572 \fBgroup:\fR
574 .RS 18n
575 compat
579 .ne 2
581 \fBgroup_compat:\fR
583 .RS 18n
584 ldap
589 In order to get information from the Internet Domain Name Service for hosts
590 that are not listed in the enterprise level name service, such as
591 \fBLDAP\fR, use the following configuration and set up the
592 \fB/etc/resolv.conf\fR file (see \fBresolv.conf\fR(4) for more details):
594 .ne 2
596 \fBhosts:\fR
598 .RS 10n
599 ldap dns [NOTFOUND=return] files
602 .SS "Enumeration - \fBgetXXXent()\fR"
604 Many of the databases have enumeration functions: \fBpasswd\fR has
605 \fBgetpwent()\fR, \fBhosts\fR has \fBgethostent()\fR, and so on. These were
606 reasonable when the only source was \fBfiles\fR but often make little sense for
607 hierarchically structured sources that contain large numbers of entries, much
608 less for multiple sources. The interfaces are still provided and the
609 implementations strive to provide reasonable results, but the data returned can
610 be incomplete (enumeration for \fBhosts\fR is simply not supported by the
611 \fBdns\fR source), inconsistent (if multiple sources are used), formatted in an
612 unexpected fashion,
613 or very expensive (enumerating a \fBpasswd\fR database of 5,000 users is
614 probably a bad idea). Furthermore, multiple threads in the same process using
615 the same reentrant enumeration function (\fBgetXXXent_r()\fR are supported
616 beginning with SunOS 5.3) share the same enumeration position; if they
617 interleave calls, they enumerate disjoint subsets of the same database.
620 In general, the use of the enumeration functions is deprecated. In the case of
621 \fBpasswd\fR, \fBshadow\fR, and \fBgroup\fR, it might sometimes be appropriate
622 to use \fBfgetgrent()\fR, \fBfgetpwent()\fR, and \fBfgetspent()\fR (see
623 \fBgetgrnam\fR(3C), \fBgetpwnam\fR(3C), and \fBgetspnam\fR(3C), respectively),
624 which use only the \fBfiles\fR source.
625 .SH FILES
627 A source named SSS is implemented by a shared object named \fBnss_SSS.so.1\fR
628 that resides in \fB/usr/lib\fR.
630 .ne 2
632 \fB\fB/etc/nsswitch.conf\fR\fR
634 .RS 29n
635 Configuration file.
639 .ne 2
641 \fB\fB/usr/lib/nss_compat.so.1\fR\fR
643 .RS 29n
644 Implements \fBcompat\fR source.
648 .ne 2
650 \fB\fB/usr/lib/nss_dns.so.1\fR\fR
652 .RS 29n
653 Implements \fBdns\fR source.
657 .ne 2
659 \fB\fB/usr/lib/nss_files.so.1\fR\fR
661 .RS 29n
662 Implements \fBfiles\fR source.
666 .ne 2
668 \fB\fB/usr/lib/nss_mdns.so.1\fR\fR
670 .RS 29n
671 Implements \fBmdns\fR source.
675 .ne 2
677 \fB\fB/usr/lib/nss_nis.so.1\fR\fR
679 .RS 29n
680 Implements \fBnis\fR source.
684 .ne 2
686 \fB\fB/usr/lib/nss_ldap.so.1\fR\fR
688 .RS 29n
689 Implements \fBldap\fR source.
693 .ne 2
695 \fB\fB/usr/lib/nss_ad.so.1\fR\fR
697 .RS 29n
698 Implements ad source.
702 .ne 2
704 \fB\fB/usr/lib/nss_user.so.1\fR\fR
706 .RS 29n
707 Implements \fBuser\fR source.
711 .ne 2
713 \fB\fB/etc/netconfig\fR\fR
715 .RS 29n
716 Configuration file for \fBnetdir\fR(3NSL) functions that redirects
717 hosts/devices policy to the switch.
721 .ne 2
723 \fB\fB/etc/nsswitch.files\fR\fR
725 .RS 29n
726 Sample configuration file that uses \fBfiles\fR only.
730 .ne 2
732 \fB\fB/etc/nsswitch.nis\fR\fR
734 .RS 29n
735 Sample configuration file that uses \fBfiles\fR and \fBnis\fR.
739 .ne 2
741 \fB\fB/etc/nsswitch.ldap\fR\fR
743 .RS 29n
744 Sample configuration file that uses \fBfiles\fR and \fBldap\fR.
748 .ne 2
750 \fB\fB/etc/nsswitch.ad\fR\fR
752 .RS 29n
753 Sample configuration file that uses \fBfiles\fR and \fBad\fR.
757 .ne 2
759 \fB\fB/etc/nsswitch.dns\fR\fR
761 .RS 29n
762 Sample configuration file that uses \fBfiles\fR, \fBdns\fR and \fBmdns\fR
763 (\fBdns\fR and \fBmdns\fR only for hosts).
766 .SH SEE ALSO
768 \fBkpasswd\fR(1), \fBldap\fR(1), \fBnewtask\fR(1),
769 \fBpasswd\fR(1), \fBautomount\fR(1M), \fBifconfig\fR(1M), \fBmdnsd\fR(1M),
770 \fBrpc.bootparamd\fR(1M), \fBsendmail\fR(1M),
771 \fBgetgrnam\fR(3C), \fBgetnetgrent\fR(3C),
772 \fBgetpwnam\fR(3C), \fBgetspnam\fR(3C), \fBgethostbyname\fR(3NSL),
773 \fBgetpublickey\fR(3NSL), \fBgetrpcbyname\fR(3NSL), \fBnetdir\fR(3NSL),
774 \fBsecure_rpc\fR(3NSL), \fBgetprojent\fR(3PROJECT),
775 \fBgetdefaultproj\fR(3PROJECT), \fBinproj\fR(3PROJECT),
776 \fBsetproject\fR(3PROJECT), \fBgetauthnam\fR(3SECDB),
777 \fBgetexecprof\fR(3SECDB), \fBgetprofnam\fR(3SECDB), \fBgetuserattr\fR(3SECDB),
778 \fBgetusernam\fR(3SECDB), \fBethers\fR(3SOCKET), \fBgetaddrinfo\fR(3SOCKET),
779 \fBgetnetbyname\fR(3SOCKET), \fBgetprotobyname\fR(3SOCKET),
780 \fBgetservbyname\fR(3SOCKET), \fBauth_attr\fR(4), \fBhosts\fR(4),
781 \fBnetconfig\fR(4), \fBproject\fR(4), \fBresolv.conf\fR(4), \fBuser_attr\fR(4),
782 \fBypfiles\fR(4), \fBad\fR(5)
783 .SH NOTES
785 Within each process that uses \fBnsswitch.conf\fR, the entire file is read only
786 once; if the file is later changed, the process continues using the old
787 configuration.
790 Do not use the \fBldap\fR and \fBad\fR keywords together when the Solaris LDAP
791 client uses schema mapping to talk to Active Directory.
794 Misspelled names of sources and databases are treated as legitimate names of
795 (most likely nonexistent) sources and databases.
798 The following functions do \fBnot\fR use the switch: \fBfgetgrent\fR(3C),
799 \fBfgetprojent\fR(3PROJECT), \fBfgetpwent\fR(3C), \fBfgetspent\fR(3C),
800 \fBgetpw\fR(3C), \fBputpwent\fR(3C), \fBshadow\fR(4).