nsswitch.conf(4) File Formats nsswitch.conf(4)NAMEnsswitch.conf - configuration file for the name service switch
SYNOPSIS
/etc/nsswitch.conf
DESCRIPTION
The operating system uses a number of databases of information about
hosts, ipnodes, users (passwd(4), shadow(4), and user_attr(4)), and
groups. Data for these can come from a variety of sources: hostnames
and host addresses, for example, can be found in /etc/hosts, NIS, NIS+,
LDAP, or DNS. Zero or more sources can be used for each database; the
sources and their lookup order are specified in the /etc/nsswitch.conf
file.
The following databases use the switch file:
Database Used By
aliases sendmail(1M)
auth_attr getauthnam(3SECDB)
automount automount(1M)
bootparams rpc.bootparamd(1M)
ethers ethers(3SOCKET)
group getgrnam(3C)
hosts gethostbyname(3NSL), getad‐
drinfo(3SOCKET). See Interaction with
netconfig.
ipnodes Same as hosts.
netgroup innetgr(3C)
netmasks ifconfig(1M)
networks getnetbyname(3SOCKET)
passwd getpwnam(3C), getspnam(3C), getauuser‐
nam(3BSM), getusernam(3SECDB)
printers lp(1), lpstat(1), cancel(1), lpr(1B),
lpq(1B), lprm(1B), in.lpd(1M), lpad‐
min(1M), lpget(1M), lpset(1M)
prof_attr getprofnam(3SECDB), getexecprof(3SECDB)
project getprojent(3PROJECT), getdefault‐
proj(3PROJECT), inproj(3PROJECT), new‐
task(1), setproject(3PROJECT)
protocols getprotobyname(3SOCKET)
publickey getpublickey(3NSL), secure_rpc(3NSL)
rpc getrpcbyname(3NSL)
services getservbyname(3SOCKET).
See Interaction with netconfig.
user_attr getuserattr(3SECDB)
The following sources can be used:
Source Uses
files /etc/hosts, /etc/passwd,
/etc/inet/ipnodes, /etc/shadow,
/etc/security/auth_attr,
/etc/user_attr
nis NIS(YP)
nisplus NIS+
ldap LDAP
dns Valid only for hosts and ipnodes.
Uses the Internet Domain Name
Service.
compat Valid only for passwd and group.
Implements + and -. See Interac‐
tion with +/- syntax.
user Valid only for printers. Imple‐
ments support for ${HOME}/.print‐
ers.
/etc/inet/ipnodes is a symbolic link to /etc/hosts.
There is an entry in /etc/nsswitch.conf for each database. Typically
these entries are simple, such as protocols: files or networks: files
nisplus. 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:
Status Meaning
SUCCESS Requested database entry was found.
UNAVAIL Source is not configured on this
system or internal failure.
NOTFOUND Source responded "no such entry"
TRYAGAIN Source is busy or not responding,
might respond to retries.
For each status code, two actions are possible:
Action Meaning
continue Try the next source in the list.
return Return now.
Additionally, for TRYAGAIN only, the following actions are possible:
Action Meaning
forever Retry the current source forever.
n Retry the current source n more
times, where n is an integer
between 0 and MAX_INT (that is,
2.14 billion). After n retries
has been exhausted, the TRYAGAIN
action transitions to continue,
until a future request receives a
response, at which time TRYA‐
GAIN=n is restored.
The complete syntax of an entry is:
<entry> ::= <database> ":" [<source> [<criteria>]]*
<criteria> ::= "[" <criterion>+ "]"
<criterion> ::= <status> "=" <action>
<status> ::= "success" | "notfound" | "unavail" | "tryagain"
For every status except TRYAGAIN, the action syntax is:
<action> ::= "return" | "continue"
For the TRYAGAIN status, the action syntax is:
<action> ::= "return" | "continue" | "forever" | <n>
<n> ::= 0...MAX_INT
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 follow‐
ing a # character is also ignored; the # 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.
The library functions contain compiled-in default entries that are used
if the appropriate entry in nsswitch.conf is absent or syntactically
incorrect.
The default criteria for DNS and the NIS server in "DNS-forwarding
mode" is [SUCCESS=return NOTFOUND=continue UNAVAIL=continue TRYA‐
GAIN=3].
The default criteria for all other sources is [SUCCESS=return NOT‐
FOUND=continue UNAVAIL=continue TRYAGAIN=forever].
The default, or explicitly specified, criteria are meaningless follow‐
ing 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.
Interaction with netconfig
In order to ensure that they all return consistent results, gethostby‐
name(3NSL), getaddrinfo(3SOCKET), getservbyname(3SOCKET), and net‐
dir_getbyname(3NSL) functions are all implemented in terms of the same
internal library function. This function obtains the system-wide source
lookup policy for hosts, ipnodes, and services based on the inet family
entries in netconfig(4) and uses the switch entries only if the netcon‐
fig entries have a - (hyphen) in the last column for nametoaddr
libraries. See the section in gethostbyname(3NSL) and getservby‐
name(3SOCKET) for details.
YP-compatibility Mode
The NIS+ server can be run in YP-compatibility mode, where it handles
NIS (YP) requests as well as NIS+ requests. In this case, the clients
get much the same results (except for getspnam(3C)) from the nis source
as from nisplus; however, nisplus is recommended instead of nis.
Interaction with server in DNS-forwarding Mode
The NIS (YP) server can be run in DNS-forwarding mode, where it for‐
wards lookup requests to DNS for host-names and -addresses that do not
exist in its database. In this case, specifying nis as a source for
hosts is sufficient to get DNS lookups; dns need not be specified
explicitly as a source.
In SunOS 5.3 (Solaris 2.3) and compatible versions, the NIS+ server in
NIS/YP-compatibility mode can also be run in DNS-forwarding mode (see
rpc.nisd(1M)). Forwarding is effective only for requests originating
from its YP clients; hosts policy on these clients should be configured
appropriately.
Interaction with Password Aging
When password aging is turned on, only a limited set of possible name
services are permitted for the passwd: database in the /etc/nss‐
witch.conf file:
passwd: files
passwd: files nis
passwd: files nisplus
passwd: files ldap
passwd: compat
passwd_compat: nisplus
passwd_compat: ldap
Any other settings cause the passwd(1) command to fail when it attempts
to change the password after expiration and prevent the user from log‐
ging in. These are the only permitted settings when password aging has
been turned on. Otherwise, you can work around incorrect passwd: lines
by using the -r repository argument to the passwd(1) command and using
passwd -r repository to override the nsswitch.conf settings and specify
in which name service you want to modify your password.
Interaction with +/- syntax
Releases prior to SunOS 5.0 did not have the name service switch but
did allow the user some policy control. In /etc/passwd one could have
entries of the form +user (include the specified user from NIS
passwd.byname), -user (exclude the specified user) and + (include
everything, except excluded users, from NIS passwd.byname). The desired
behavior was often everything in the file followed by everything in
NIS, expressed by a solitary + at the end of /etc/passwd. The switch
provides an alternative for this case (passwd: files nis) that does not
require + entries in /etc/passwd and /etc/shadow (the latter is a new
addition to SunOS 5.0, see shadow(4)).
If this is not sufficient, the NIS/YP compatibility source provides
full +/- semantics. It reads /etc/passwd for getpwnam(3C) functions and
/etc/shadow for getspnam(3C) functions and, if it finds +/- entries,
invokes an appropriate source. By default, the source is nis, but this
can be overridden by specifying nisplus or ldap as the source for the
pseudo-database passwd_compat.
In compat mode, for every /etc/passwd entry, there must be a corre‐
sponding entry in the /etc/shadow file.
The NIS/YP compatibility source also provides full +/- semantics for
group; the relevant pseudo-database is group_compat.
Useful Configurations
The compiled-in default entries for all databases use NIS (YP) as the
enterprise level name service and are identical to those in the default
configuration of this file:
passwd: files nis
group: files nis
hosts: nis [NOTFOUND=return] files
ipnodes: nis [NOTFOUND=return] files
networks: nis [NOTFOUND=return] files
protocols: nis [NOTFOUND=return] files
rpc: nis [NOTFOUND=return] files
ethers: nis [NOTFOUND=return] files
netmasks: nis [NOTFOUND=return] files
bootparams: nis [NOTFOUND=return] files
publickey: nis [NOTFOUND=return] files
netgroup: nis
automount: files nis
aliases: files nis
services: files nis
printers: user files nis nisplus
auth_attr files nis
prof_attr files nis
project files nis
The files source for the ipnodes and hosts databases is identical, as
/etc/inet/ipnodes is a symbolic link to /etc/hosts. Because other
sources for the ipnodes and hosts databases are different, do not
remove the ipnodes line from the /etc/nsswitch.conf file.
The policy nis [NOTFOUND=return] files implies: if nis is UNAVAIL, con‐
tinue on to files, and if nis returns NOTFOUND, return to the caller.
In other words, treat nis as the authoritative source of information
and try files only if nis is down. This, and other policies listed in
the default configuration above, are identical to the hard-wired poli‐
cies in SunOS releases prior to 5.0.
If compatibility with the +/- syntax for passwd and group is required,
simply modify the entries for passwd and group to:
passwd: compat
group: compat
If NIS+ is the enterprise level name service, the default configuration
should be modified to use nisplus instead of nis for every database on
client machines. The file /etc/nsswitch.nisplus contains a sample con‐
figuration that can be copied to /etc/nsswitch.conf to set this policy.
If LDAP is the enterprise level name service, the default configuration
should be modified to use ldap instead of nis for every database on
client machines. The file /etc/nsswitch.ldap contains a sample configu‐
ration that can be copied to /etc/nsswitch.conf to set this policy.
If the use of +/- syntax is desired in conjunction with nisplus, use
the following four entries:
passwd: compat
passwd_compat: nisplus OR ldap
group: compat
group_compat: nisplus OR ldap
In order to get information from the Internet Domain Name Service for
hosts that are not listed in the enterprise level name service, NIS+ or
LDAP, use the following configuration and set up the /etc/resolv.conf
file (see resolv.conf(4) for more details):
hosts: nisplus dns [NOTFOUND=return] files
or
hosts: ldap dns [NOTFOUND=return] files
Enumeration - getXXXent()
Many of the databases have enumeration functions: passwd has getp‐
went(), hosts has gethostent(), and so on. These were reasonable when
the only source was files but often make little sense for hierarchi‐
cally 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 hosts is simply not sup‐
ported by the dns source), inconsistent (if multiple sources are used),
formatted in an unexpected fashion (for a host with a canonical name
and three aliases, the nisplus source returns four hostents, and they
can not be consecutive), or very expensive (enumerating a passwd data‐
base of 5,000 users is probably a bad idea). Furthermore, multiple
threads in the same process using the same reentrant enumeration func‐
tion (getXXXent_r() are supported beginning with SunOS 5.3) share the
same enumeration position; if they interleave calls, they enumerate
disjoint subsets of the same database.
In general, the use of the enumeration functions is deprecated. In the
case of passwd, shadow, and group, it can sometimes be appropriate to
use fgetgrent(), fgetpwent(), and fgetspent() (see getgrnam(3C), getpw‐
nam(3C), and getspnam(3C), respectively), which use only the files
source.
FILES
A source named SSS is implemented by a shared object named nss_SSS.so.1
that resides in /usr/lib.
/etc/nsswitch.conf Configuration file.
/usr/lib/nss_compat.so.1 Implements compat source.
/usr/lib/nss_dns.so.1 Implements dns source.
/usr/lib/nss_files.so.1 Implements files source.
/usr/lib/nss_nis.so.1 Implements nis source.
/usr/lib/nss_nisplus.so.1 Implements nisplus source.
/usr/lib/nss_ldap.so.1 Implements ldap source.
/usr/lib/nss_user.so.1 Implements user source.
/etc/netconfig Configuration file for netdir(3NSL) func‐
tions that redirects hosts/devices policy
to the switch.
/etc/nsswitch.files Sample configuration file that uses files
only.
/etc/nsswitch.nis Sample configuration file that uses files
and nis.
/etc/nsswitch.nisplus Sample configuration file that uses files
and nisplus.
/etc/nsswitch.ldap Sample configuration file that uses files
and ldap.
/etc/nsswitch.dns Sample configuration file that uses files
and dns (but only for hosts).
SEE ALSOldap(1), newtask(1), nis+(1), passwd(1), automount(1M), ifconfig(1M),
rpc.bootparamd(1M), rpc.nisd(1M), sendmail(1M), getauusernam(3BSM)get‐
grnam(3C), getnetgrent(3C), getpwnam(3C), getspnam(3C), gethostby‐
name(3NSL), getpublickey(3NSL), getrpcbyname(3NSL), netdir(3NSL),
secure_rpc(3NSL), getprojent(3PROJECT), getdefaultproj(3PROJECT),
inproj(3PROJECT), setproject(3PROJECT), getauthnam(3SECDB), getex‐
ecprof(3SECDB), getprofnam(3SECDB), getuserattr(3SECDB), getuser‐
nam(3SECDB), ethers(3SOCKET), getaddrinfo(3SOCKET), getnetby‐
name(3SOCKET), getprotobyname(3SOCKET), getservbyname(3SOCKET),
auth_attr(4), hosts(4), netconfig(4), project(4), resolv.conf(4),
user_attr(4), ypfiles(4)NOTES
Within each process that uses nsswitch.conf, the entire file is read
only once; if the file is later changed, the process continues using
the old configuration.
The use of both nis and nisplus as sources for the same database is
strongly discouraged since both the name services are expected to store
similar information and the lookups on the database can yield different
results depending on which name service is operational at the time of
the request. The same applies for using ldap along with nis or nisplus.
Misspelled names of sources and databases are treated as legitimate
names of (most likely nonexistent) sources and databases.
nsswitch.conf does not control the name service configuration for
everything in Solaris.
The following functions do not use the switch: fgetgrent(3C), fgetpro‐
jent(3PROJECT), fgetpwent(3C), fgetspent(3C), getpw(3C), putpwent(3C),
shadow(4).
SunOS 5.10 10 Jan 2011 nsswitch.conf(4)
