path: root/usr/src/man/man5/nsswitch.conf.5

'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH NSSWITCH.CONF 5 "Mar 6, 2017"
.SH NAME
nsswitch.conf \- configuration file for the name service switch
.SH SYNOPSIS
.LP
.nf
\fB/etc/nsswitch.conf\fR
.fi

.SH DESCRIPTION
.LP
The operating system uses a number of databases of information about hosts,
ipnodes, users (\fBpasswd\fR(5), \fBshadow\fR(5), and \fBuser_attr\fR(5)), and
groups. Data for these can come from a variety of sources: hostnames and host
addresses, for example, can be found in \fB/etc/hosts\fR, \fBNIS\fR,
\fBLDAP\fR, \fBDNS\fR or Multicast \fBDNS\fR. Zero or more sources
can be used for each database; the sources and their lookup order are specified
in the \fB/etc/nsswitch.conf\fR file.
.sp
.LP
The following databases use the \fBswitch\fR file:
.sp

.sp
.TS
c c
l l .
Database	Used By
\fBaliases\fR	\fBsendmail\fR(8)
\fBauth_attr\fR	\fBgetauthnam\fR(3SECDB)
\fBautomount\fR	\fBautomount\fR(8)
\fBbootparams\fR	\fBrpc.bootparamd\fR(8)
\fBethers\fR	\fBethers\fR(3SOCKET)
\fBgroup\fR	\fBgetgrnam\fR(3C)
\fBhosts\fR	T{
\fBgethostbyname\fR(3NSL), \fBgetaddrinfo\fR(3SOCKET). See \fBInteraction with netconfig\fR.
T}
\fBipnodes\fR	Same as \fBhosts\fR.
\fBnetgroup\fR	\fBinnetgr\fR(3C)
\fBnetmasks\fR	\fBifconfig\fR(8)
\fBnetworks\fR	\fBgetnetbyname\fR(3SOCKET)
\fBpasswd\fR	T{
\fBgetpwnam\fR(3C),
\fBgetspnam\fR(3C),
\fBgetusernam\fR(3SECDB)
T}
\fBprinters\fR	T{
\fBlp\fR(1),
\fBlpstat\fR(1),
\fBcancel\fR(1),
\fBlpr\fR(1B),
\fBlpq\fR(1B),
\fBlprm\fR(1B),
\fBin.lpd\fR(8),
\fBlpadmin\fR(8),
\fBlpget\fR(8),
\fBlpset\fR(8)
T}
\fBprof_attr\fR	\fBgetprofnam\fR(3SECDB),
\fBgetexecprof\fR(3SECDB)
\fBproject\fR	T{
\fBgetprojent\fR(3PROJECT),
\fBgetdefaultproj\fR(3PROJECT),
\fBinproj\fR(3PROJECT),
\fBnewtask\fR(1),
\fBsetproject\fR(3PROJECT)
T}
\fBprotocols\fR	\fBgetprotobyname\fR(3SOCKET)
\fBpublickey\fR	\fBgetpublickey\fR(3NSL),
\fBsecure_rpc\fR(3NSL)
\fBrpc\fR	\fBgetrpcbyname\fR(3NSL)
\fBservices\fR	\fBgetservbyname\fR(3SOCKET).
	See \fBInteraction with netconfig\fR.
\fBuser_attr\fR	\fBgetuserattr\fR(3SECDB)
.TE

.sp
.LP
The following sources can be used:
.sp

.sp
.TS
c c
l l .
Source	Uses
\fBfiles\fR	T{
\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
T}
\fBnis\fR	\fBNIS\fR(\fBYP\fR)
\fBldap\fR	\fBLDAP\fR
\fBad\fR	Active Directory
\fBdns\fR	T{
Valid only for hosts and ipnodes. Uses the Internet Domain Name Service.
T}
\fBmdns\fR	T{
Valid only for hosts and ipnodes. Uses the Multicast Domain Name Service.
T}
\fBcompat\fR	T{
Valid only for \fBpasswd\fR and \fBgroup\fR. Implements \fB+\fR and \fB-.\fR See \fBInteraction with +/- syntax\fR.
T}
\fBuser\fR	T{
Valid only for printers. Implements support for \fB${HOME}/.printers\fR.
T}
.TE

.sp
.LP
Note that \fB/etc/inet/ipnodes\fR is a symbolic link to \fB/etc/hosts\fR.
.sp
.LP
There is an entry in \fB/etc/nsswitch.conf\fR for each database. Typically
these entries are simple, such as \fBprotocols: files\fR. However, when
multiple sources are specified, it is sometimes necessary to define precisely
the circumstances under which each source is tried. A source can return one
of the following codes:
.sp

.sp
.TS
c c
l l .
Status	Meaning
\fBSUCCESS\fR	Requested database entry was found.
\fBUNAVAIL\fR	T{
Source is not configured on this system or internal failure.
T}
\fBNOTFOUND\fR	Source responded "\fBno such entry\fR"
\fBTRYAGAIN\fR	T{
Source is busy or not responding, might respond to retries.
T}
.TE

.sp
.LP
For each status code, two actions are possible:
.sp

.sp
.TS
c c
l l .
Action	Meaning
\fBcontinue\fR	Try the next source in the list.
\fBreturn\fR	Return now.
.TE

.sp
.LP
Additionally, for \fBTRYAGAIN\fR only, the following actions are possible:
.sp

.sp
.TS
c c
l l .
Action	Meaning
\fBforever\fR	Retry the current source forever.
\fIn\fR	T{
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.
T}
.TE

.sp
.LP
The complete syntax of an entry is:
.sp
.in +2
.nf
<entry>     ::= <database> ":" [<source> [<criteria>]]*
<criteria>  ::= "[" <criterion>+ "]"
<criterion> ::= <status> "=" <action>
<status>    ::= "success" | "notfound" | "unavail" | "tryagain"
.fi
.in -2

.sp
.LP
For every status except \fBTRYAGAIN\fR, the action syntax is:
.sp
.in +2
.nf
<action>    ::= "return"  | "continue"
.fi
.in -2

.sp
.LP
For the \fBTRYAGAIN\fR status, the action syntax is:
.sp
.in +2
.nf
<action>    ::= "return"  | "continue" | "forever" | <n>
<n>         ::= 0...MAX_INT
.fi
.in -2

.sp
.LP
Each entry occupies a single line in the file. Lines that are blank, or that
start with white space, are ignored. Everything on a line following a \fB#\fR
character is also ignored; the \fB#\fR character can begin anywhere in a line,
to be used to begin comments. The <database> and <source> names are
case-sensitive, but <action> and <status> names are case-insensitive.
.sp
.LP
The library functions contain compiled-in default entries that are used if the
appropriate entry in \fBnsswitch.conf\fR is absent or syntactically incorrect.
.sp
.LP
The default criteria for \fBDNS\fR and the \fBNIS\fR server in "DNS-forwarding
mode" is [\fBSUCCESS\fR=return \fBNOTFOUND\fR=continue \fBUNAVAIL\fR=continue
\fBTRYAGAIN\fR=3].
.sp
.LP
The default criteria for all other sources is [\fBSUCCESS\fR=return
\fBNOTFOUND\fR=continue \fBUNAVAIL\fR=continue \fBTRYAGAIN\fR=forever].
.sp
.LP
The default, or explicitly specified, criteria are meaningless following the
last source in an entry; and they are ignored, since the action is always to
return to the caller irrespective of the status code the source returns.
.SS "Interaction with \fBnetconfig\fR"
.LP
In order to ensure that they all return consistent results,
\fBgethostbyname\fR(3NSL), \fBgetaddrinfo\fR(3SOCKET),
\fBgetservbyname\fR(3SOCKET), and \fBnetdir_getbyname\fR(3NSL) functions are
all implemented in terms of the same internal library function. This function
obtains the system-wide source lookup policy for \fBhosts\fR, \fBipnodes\fR,
and \fBservices\fR based on the \fBinet\fR family entries in \fBnetconfig\fR(5)
and uses the switch entries only if the \fBnetconfig\fR entries have a \fB-\fR
(hyphen) in the last column for \fBnametoaddr\fR libraries. See the Notes
section in \fBgethostbyname\fR(3NSL) and \fBgetservbyname\fR(3SOCKET) for
details.
.SS "Interaction with server in DNS-forwarding Mode"
.LP
The \fBNIS\fR (\fBYP\fR) server can be run in DNS-forwarding mode, where it
forwards lookup requests to \fBDNS\fR for host-names and -addresses that do not
exist in its database. In this case, specifying \fBnis\fR as a source for
\fBhosts\fR is sufficient to get \fBDNS\fR lookups; \fBdns\fR need not be
specified explicitly as a source.
.SS "Interaction with Password Aging"
.LP
When password aging is turned on, only a limited set of possible name services
are permitted for the \fBpasswd\fR: database in the \fB/etc/nsswitch.conf\fR
file:
.sp
.ne 2
.na
\fBpasswd:\fR
.ad
.RS 18n
files
.RE

.sp
.ne 2
.na
\fBpasswd:\fR
.ad
.RS 18n
files nis
.RE

.sp
.ne 2
.na
\fBpasswd:\fR
.ad
.RS 18n
files ldap
.RE

.sp
.ne 2
.na
\fBpasswd:\fR
.ad
.RS 18n
compat
.RE

.sp
.ne 2
.na
\fBpasswd_compat:\fR
.ad
.RS 18n
ldap
.RE

.sp
.LP
You can add the \fBad\fR keyword to any of the \fBpasswd\fR configurations
listed above. However, you cannot use the \fBpasswd\fR command to change the
password of an Active Directory (AD) user. If the \fBad\fR keyword is found in
the \fBpasswd\fR entry during a password update operation, it is ignored. To
update the password of an AD user, use the \fBkpasswd\fR(1) command.
.sp
.LP
Any other settings causes the \fBpasswd\fR(1) command to fail when it attempts
to change the password after expiration and prevents the user from logging in.
These are the \fBonly\fR permitted settings when password aging has been turned
on. Otherwise, you can work around incorrect \fBpasswd\fR: lines by using the
\fB-r repository\fR argument to the \fBpasswd\fR(1) command and using \fBpasswd
-r repository\fR to override the \fBnsswitch.conf\fR settings and specify in
which name service you want to modify your password.
.SS "Interaction with +/- syntax"
.LP
Releases prior to SunOS 5.0 did not have the name service switch but did allow
the user some policy control. In \fB/etc/passwd\fR one could have entries of
the form \fI+user\fR (include the specified user from \fBNIS\fR passwd.byname),
\fI-user\fR (exclude the specified user) and \fB+\fR (include everything,
except excluded users, from \fBNIS\fR passwd.byname). The desired behavior was
often \fBeverything in the file followed by everything in NIS\fR, expressed by
a solitary \fB+\fR at the end of \fB/etc/passwd\fR. The switch provides an
alternative for this case (\fBpasswd: files nis\fR) that does not require
\fB+\fR entries in \fB/etc/passwd\fR and \fB/etc/shadow\fR (the latter is a new
addition to SunOS 5.0, see \fBshadow\fR(5)).
.sp
.LP
If this is not sufficient, the \fBNIS/YP\fR compatibility source provides full
+/- semantics. It reads \fB/etc/passwd\fR for \fBgetpwnam\fR(3C) functions and
\fB/etc/shadow\fR for \fBgetspnam\fR(3C) functions and, if it finds +/-
entries, invokes an appropriate source. By default, the source is \fBnis\fR,
but this can be overridden by specifying \fBldap\fR as the
source for the pseudo-database \fBpasswd_compat\fR.
.sp
.LP
Note that in compat mode, for every \fB/etc/passwd\fR entry, there must be a
corresponding entry in the \fB/etc/shadow\fR file.
.sp
.LP
The NIS/YP compatibility source also provides full +/- semantics for
\fBgroup\fR; the relevant pseudo-database is \fBgroup_compat\fR.
.SS "Useful Configurations"
.LP
The compiled-in default entries for all databases use \fBNIS (YP)\fR as the
enterprise level name service and are identical to those in the default
configuration of this file:
.sp
.ne 2
.na
\fBpasswd:\fR
.ad
.RS 15n
files nis
.RE

.sp
.ne 2
.na
\fBgroup:\fR
.ad
.RS 15n
files nis
.RE

.sp
.ne 2
.na
\fBhosts:\fR
.ad
.RS 15n
nis [NOTFOUND=return] files
.RE

.sp
.ne 2
.na
\fBipnodes:\fR
.ad
.RS 15n
nis [NOTFOUND=return] files
.RE

.sp
.ne 2
.na
\fBnetworks:\fR
.ad
.RS 15n
nis [NOTFOUND=return] files
.RE

.sp
.ne 2
.na
\fBprotocols:\fR
.ad
.RS 15n
nis [NOTFOUND=return] files
.RE

.sp
.ne 2
.na
\fBrpc:\fR
.ad
.RS 15n
nis [NOTFOUND=return] files
.RE

.sp
.ne 2
.na
\fBethers:\fR
.ad
.RS 15n
nis [NOTFOUND=return] files
.RE

.sp
.ne 2
.na
\fBnetmasks:\fR
.ad
.RS 15n
nis [NOTFOUND=return] files
.RE

.sp
.ne 2
.na
\fBbootparams:\fR
.ad
.RS 15n
nis [NOTFOUND=return] files
.RE

.sp
.ne 2
.na
\fBpublickey:\fR
.ad
.RS 15n
nis [NOTFOUND=return] files
.RE

.sp
.ne 2
.na
\fBnetgroup:\fR
.ad
.RS 15n
nis
.RE

.sp
.ne 2
.na
\fBautomount:\fR
.ad
.RS 15n
files nis
.RE

.sp
.ne 2
.na
\fBaliases:\fR
.ad
.RS 15n
files nis
.RE

.sp
.ne 2
.na
\fBservices:\fR
.ad
.RS 15n
files nis
.RE

.sp
.ne 2
.na
\fBprinters:\fR
.ad
.RS 15n
user files nis
.RE

.sp
.ne 2
.na
\fBauth_attr\fR
.ad
.RS 15n
files nis
.RE

.sp
.ne 2
.na
\fBprof_attr\fR
.ad
.RS 15n
files nis
.RE

.sp
.ne 2
.na
\fBproject\fR
.ad
.RS 15n
files nis
.RE

.sp
.LP
Note that the \fBfiles\fR source for the \fBipnodes\fR and \fBhosts\fR
databases is identical, as \fB/etc/inet/ipnodes\fR is a symbolic link to
\fB/etc/hosts\fR. Because other sources for the \fBipnodes\fR and \fBhosts\fR
databases are different, do not remove the \fBipnodes\fR line from the
\fB/etc/nsswitch.conf\fR file.
.sp
.LP
The policy \fBnis [NOTFOUND=return] files\fR implies: if \fBnis\fR is
\fBUNAVAIL\fR, continue on to \fBfiles\fR, and if \fBnis\fR returns
\fBNOTFOUND\fR, return to the caller. In other words, treat \fBnis\fR as the
authoritative source of information and try \fBfiles\fR only if \fBnis\fR is
down. This, and other policies listed in the default configuration above, are
identical to the hard-wired policies in SunOS releases prior to 5.0.
.sp
.LP
If compatibility with the +/- syntax for \fBpasswd\fR and \fBgroup\fR is
required, simply modify the entries for \fBpasswd\fR and \fBgroup\fR to:
.sp
.ne 2
.na
\fBpasswd:\fR
.ad
.RS 11n
compat
.RE

.sp
.ne 2
.na
\fBgroup:\fR
.ad
.RS 11n
compat
.RE

.sp
.LP
If \fBLDAP\fR is the enterprise level name service, the default configuration
should be modified to use \fBldap\fR instead of \fBnis\fR for every database on
client machines. The file \fB/etc/nsswitch.ldap\fR contains a sample
configuration that can be copied to \fB/etc/nsswitch.conf\fR to set this
policy.
.sp
.LP
When using Active Directory, \fBdns\fR is required to perform hosts resolution.
.sp
.LP
If the use of +/- syntax is desired in conjunction with \fBLDAP\fR, use the
following four entries:
.sp
.ne 2
.na
\fBpasswd:\fR
.ad
.RS 18n
compat
.RE

.sp
.ne 2
.na
\fBpasswd_compat:\fR
.ad
.RS 18n
ldap
.RE

.sp
.ne 2
.na
\fBgroup:\fR
.ad
.RS 18n
compat
.RE

.sp
.ne 2
.na
\fBgroup_compat:\fR
.ad
.RS 18n
ldap
.RE

.sp
.LP
In order to get information from the Internet Domain Name Service for hosts
that are not listed in the enterprise level name service, such as
\fBLDAP\fR, use the following configuration and set up the
\fB/etc/resolv.conf\fR file (see \fBresolv.conf\fR(5) for more details):
.sp
.ne 2
.na
\fBhosts:\fR
.ad
.RS 10n
ldap dns [NOTFOUND=return] files
.RE

.SS "Enumeration - \fBgetXXXent()\fR"
.LP
Many of the databases have enumeration functions: \fBpasswd\fR has
\fBgetpwent()\fR, \fBhosts\fR has \fBgethostent()\fR, and so on. These were
reasonable when the only source was \fBfiles\fR but often make little sense for
hierarchically structured sources that contain large numbers of entries, much
less for multiple sources. The interfaces are still provided and the
implementations strive to provide reasonable results, but the data returned can
be incomplete (enumeration for \fBhosts\fR is simply not supported by the
\fBdns\fR source), inconsistent (if multiple sources are used), formatted in an
unexpected fashion,
or very expensive (enumerating a \fBpasswd\fR database of 5,000 users is
probably a bad idea). Furthermore, multiple threads in the same process using
the same reentrant enumeration function (\fBgetXXXent_r()\fR are supported
beginning with SunOS 5.3) share the same enumeration position; if they
interleave calls, they enumerate disjoint subsets of the same database.
.sp
.LP
In general, the use of the enumeration functions is deprecated. In the case of
\fBpasswd\fR, \fBshadow\fR, and \fBgroup\fR, it might sometimes be appropriate
to use \fBfgetgrent()\fR, \fBfgetpwent()\fR, and \fBfgetspent()\fR (see
\fBgetgrnam\fR(3C), \fBgetpwnam\fR(3C), and \fBgetspnam\fR(3C), respectively),
which use only the \fBfiles\fR source.
.SH FILES
.LP
A source named SSS is implemented by a shared object named \fBnss_SSS.so.1\fR
that resides in \fB/usr/lib\fR.
.sp
.ne 2
.na
\fB\fB/etc/nsswitch.conf\fR\fR
.ad
.RS 29n
Configuration file.
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/nss_compat.so.1\fR\fR
.ad
.RS 29n
Implements \fBcompat\fR source.
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/nss_dns.so.1\fR\fR
.ad
.RS 29n
Implements \fBdns\fR source.
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/nss_files.so.1\fR\fR
.ad
.RS 29n
Implements \fBfiles\fR source.
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/nss_mdns.so.1\fR\fR
.ad
.RS 29n
Implements \fBmdns\fR source.
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/nss_nis.so.1\fR\fR
.ad
.RS 29n
Implements \fBnis\fR source.
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/nss_ldap.so.1\fR\fR
.ad
.RS 29n
Implements \fBldap\fR source.
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/nss_ad.so.1\fR\fR
.ad
.RS 29n
Implements ad source.
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/nss_user.so.1\fR\fR
.ad
.RS 29n
Implements \fBuser\fR source.
.RE

.sp
.ne 2
.na
\fB\fB/etc/netconfig\fR\fR
.ad
.RS 29n
Configuration file for \fBnetdir\fR(3NSL) functions that redirects
hosts/devices policy to the switch.
.RE

.sp
.ne 2
.na
\fB\fB/etc/nsswitch.files\fR\fR
.ad
.RS 29n
Sample configuration file that uses \fBfiles\fR only.
.RE

.sp
.ne 2
.na
\fB\fB/etc/nsswitch.nis\fR\fR
.ad
.RS 29n
Sample configuration file that uses \fBfiles\fR and \fBnis\fR.
.RE

.sp
.ne 2
.na
\fB\fB/etc/nsswitch.ldap\fR\fR
.ad
.RS 29n
Sample configuration file that uses \fBfiles\fR and \fBldap\fR.
.RE

.sp
.ne 2
.na
\fB\fB/etc/nsswitch.ad\fR\fR
.ad
.RS 29n
Sample configuration file that uses \fBfiles\fR and \fBad\fR.
.RE

.sp
.ne 2
.na
\fB\fB/etc/nsswitch.dns\fR\fR
.ad
.RS 29n
Sample configuration file that uses \fBfiles\fR, \fBdns\fR and \fBmdns\fR
(\fBdns\fR and \fBmdns\fR only for hosts).
.RE

.SH SEE ALSO
.LP
.BR kpasswd (1),
.BR ldap (1),
.BR newtask (1),
.BR passwd (1),
.BR getgrnam (3C),
.BR getnetgrent (3C),
.BR getpwnam (3C),
.BR getspnam (3C),
.BR gethostbyname (3NSL),
.BR getpublickey (3NSL),
.BR getrpcbyname (3NSL),
.BR netdir (3NSL),
.BR secure_rpc (3NSL),
.BR getdefaultproj (3PROJECT),
.BR getprojent (3PROJECT),
.BR inproj (3PROJECT),
.BR setproject (3PROJECT),
.BR getauthnam (3SECDB),
.BR getexecprof (3SECDB),
.BR getprofnam (3SECDB),
.BR getuserattr (3SECDB),
.BR getusernam (3SECDB),
.BR ethers (3SOCKET),
.BR getaddrinfo (3SOCKET),
.BR getnetbyname (3SOCKET),
.BR getprotobyname (3SOCKET),
.BR getservbyname (3SOCKET),
.BR auth_attr (5),
.BR hosts (5),
.BR netconfig (5),
.BR project (5),
.BR resolv.conf (5),
.BR user_attr (5),
.BR ypfiles (5),
.BR ad (7),
.BR automount (8),
.BR ifconfig (8),
.BR mdnsd (8),
.BR rpc.bootparamd (8),
.BR sendmail (8)
.SH NOTES
.LP
Within each process that uses \fBnsswitch.conf\fR, the entire file is read only
once; if the file is later changed, the process continues using the old
configuration.
.sp
.LP
Do not use the \fBldap\fR and \fBad\fR keywords together when the Solaris LDAP
client uses schema mapping to talk to Active Directory.
.sp
.LP
Misspelled names of sources and databases are treated as legitimate names of
(most likely nonexistent) sources and databases.
.sp
.LP
The following functions do \fBnot\fR use the switch: \fBfgetgrent\fR(3C),
\fBfgetprojent\fR(3PROJECT), \fBfgetpwent\fR(3C), \fBfgetspent\fR(3C),
\fBgetpw\fR(3C), \fBputpwent\fR(3C), \fBshadow\fR(5).