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"
8 nsswitch.conf \- configuration file for the name service switch
12 \fB/etc/nsswitch.conf\fR
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.
26 The following databases use the \fBswitch\fR file:
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)
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)
48 \fBgetpwnam\fR(3C), \fBgetspnam\fR(3C), \fBgetusernam\fR(3SECDB)
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)
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)
67 The following sources can be used:
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)
80 \fBad\fR Active Directory
82 Valid only for hosts and ipnodes. Uses the Internet Domain Name Service.
85 Valid only for hosts and ipnodes. Uses the Multicast Domain Name Service.
88 Valid only for \fBpasswd\fR and \fBgroup\fR. Implements \fB+\fR and \fB-.\fR See \fBInteraction with +/- syntax\fR.
91 Valid only for printers. Implements support for \fB${HOME}/.printers\fR.
97 Note that \fB/etc/inet/ipnodes\fR is a symbolic link to \fB/etc/hosts\fR.
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:
112 \fBSUCCESS\fR Requested database entry was found.
114 Source is not configured on this system or internal failure.
116 \fBNOTFOUND\fR Source responded "\fBno such entry\fR"
118 Source is busy or not responding, might respond to retries.
124 For each status code, two actions are possible:
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:
146 \fBforever\fR Retry the current source forever.
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:
158 <entry> ::= <database> ":" [<source> [<criteria>]]*
159 <criteria> ::= "[" <criterion>+ "]"
160 <criterion> ::= <status> "=" <action>
161 <status> ::= "success" | "notfound" | "unavail" | "tryagain"
167 For every status except \fBTRYAGAIN\fR, the action syntax is:
171 <action> ::= "return" | "continue"
177 For the \fBTRYAGAIN\fR status, the action syntax is:
181 <action> ::= "return" | "continue" | "forever" | <n>
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
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
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
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:
353 nis [NOTFOUND=return] files
362 nis [NOTFOUND=return] files
371 nis [NOTFOUND=return] files
380 nis [NOTFOUND=return] files
389 nis [NOTFOUND=return] files
398 nis [NOTFOUND=return] files
407 nis [NOTFOUND=return] files
416 nis [NOTFOUND=return] files
425 nis [NOTFOUND=return] files
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:
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
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:
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):
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
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.
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.
632 \fB\fB/etc/nsswitch.conf\fR\fR
641 \fB\fB/usr/lib/nss_compat.so.1\fR\fR
644 Implements \fBcompat\fR source.
650 \fB\fB/usr/lib/nss_dns.so.1\fR\fR
653 Implements \fBdns\fR source.
659 \fB\fB/usr/lib/nss_files.so.1\fR\fR
662 Implements \fBfiles\fR source.
668 \fB\fB/usr/lib/nss_mdns.so.1\fR\fR
671 Implements \fBmdns\fR source.
677 \fB\fB/usr/lib/nss_nis.so.1\fR\fR
680 Implements \fBnis\fR source.
686 \fB\fB/usr/lib/nss_ldap.so.1\fR\fR
689 Implements \fBldap\fR source.
695 \fB\fB/usr/lib/nss_ad.so.1\fR\fR
698 Implements ad source.
704 \fB\fB/usr/lib/nss_user.so.1\fR\fR
707 Implements \fBuser\fR source.
713 \fB\fB/etc/netconfig\fR\fR
716 Configuration file for \fBnetdir\fR(3NSL) functions that redirects
717 hosts/devices policy to the switch.
723 \fB\fB/etc/nsswitch.files\fR\fR
726 Sample configuration file that uses \fBfiles\fR only.
732 \fB\fB/etc/nsswitch.nis\fR\fR
735 Sample configuration file that uses \fBfiles\fR and \fBnis\fR.
741 \fB\fB/etc/nsswitch.ldap\fR\fR
744 Sample configuration file that uses \fBfiles\fR and \fBldap\fR.
750 \fB\fB/etc/nsswitch.ad\fR\fR
753 Sample configuration file that uses \fBfiles\fR and \fBad\fR.
759 \fB\fB/etc/nsswitch.dns\fR\fR
762 Sample configuration file that uses \fBfiles\fR, \fBdns\fR and \fBmdns\fR
763 (\fBdns\fR and \fBmdns\fR only for hosts).
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)
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
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).