NAME
nsswitch.conf - configuration file for the name-service
switch
SYNOPSIS
/etc/nsswitch.conf
DESCRIPTION
The operating system uses a number of "databases" of infor-
mation about hosts, users (passwd/shadow), groups and so
forth. Data for these can come from a variety of sources:
host-names and -addresses, for example, may be found in
/etc/hosts, NIS, NIS+ or DNS. One or more sources may 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:
Database Used by
aliases sendmail(1M)
automount automount(1M)
bootparams rpc.bootparamd(1M)
ethers ethers(3N)
group getgrnam(3C)
hosts gethostbyname(3N)
(See "Interaction with netconfig"
below)
netgroup innetgr(3N)
netmasks ifconfig(1M)
networks getnetbyname(3N)
passwd getpwnam(3C), getspnam(3C)
protocols getprotobyname(3N)
publickey getpublickey(3N), secure_rpc(3N)
rpc getrpcbyname(3N)
sendmailvars sendmail(1M)
services getservbyname(3N)
(See "Interaction with netconfig"
below)
The following sources may be used:
Source Uses
files /etc/hosts, /etc/passwd, /etc/shadow
and so forth
nis NIS (YP)
nisplus NIS+
dns Valid only for hosts; uses the Internet
Domain Name Service.
compat Valid only for passwd and group; imple-
ments "+" and "-".
(See "Interaction with +/- syntax"
below)
There is an entry in /etc/nsswitch.conf for each database.
Typically these entries will be simple, like "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 will be
tried. A source can return one of the following codes:
Status Meaning
SUCCESS Requested database entry was found
UNAVAIL Source is not responding or corrupted
NOTFOUND Source responded "no such entry"
TRYAGAIN Source is busy, 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
The complete syntax of an entry is
<entry> ::= <database> ":" [<source> [<criteria>]]* <source>
<criteria> ::= "[" <criterion>+ "]"
<criterion> ::= <status> "=" <action>
<status> ::= "success" | "notfound" | "unavail" | "tryagain"
<action> ::= "return" | "continue"
Each entry occupies a single line in the file. Lines that
are blank, or that start with white space character are
ignored. Everything on a line following 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 are to continue on anything except SUC-
CESS; in other words, [SUCCESS=return NOTFOUND=continue
UNAVAIL=continue TRYAGAIN=continue].
The default, or explicitly specified, criteria are meaning-
less following the last source in an entry; and are ignored
since the action is always to return to the caller irrespec-
tive of the status code the source returns.
Interaction with netconfig
In order to ensure that they all return consistent results,
gethostbyname(3N), getservbyname(3N), and
netdir_getbyname(3N) functions are all implemented in terms
of the same internal library function. This function obtains
the system-wide source lookup policy for hosts and services
based on the inet family entries in netconfig(4) and uses
the switch entries only if the netconfig entries have a "-"
in the last column for nametoaddr libraries. See the NOTES
section in gethostbyname(3N) and getservbyname(3N) for
details.
Interaction with NIS+ 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"; how-
ever, "nisplus" is recommended instead of "nis".
Interaction with NIS (YP) server in DNS-forwarding Mode
The NIS (YP) server can be run in "DNS-forwarding mode",
where it forwards 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.
Since SunOS 5.3, the NIS+ server in "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 +/- 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 "compat" source provides full
+/- semantics. It reads /etc/passwd for getpwnam(3C) func-
tions and /etc/shadow for getspnam(3C) functions and, if it
finds +/- entries, invokes an appropriate source. By
default the source is "nis", but this may be overridden by
specifying "nisplus" as the source for the pseudo-database
passwd_compat.
Note that for every /etc/passwd entry, there should be a
corresponding entry in the /etc/shadow file.
The compat 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
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
sendmailvars: files
The policy "nis [NOTFOUND=return] files" implies "if nis is
UNAVAIL, continue 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
policies 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 configuration 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
group: compat
group_compat: nisplus
In order to get information from the Internet Domain Name
Service for hosts that are not listed in the enterprise
level name-service, NIS+, 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
Enumeration -- getXXXent()
Many of the databases have enumeration functions: passwd
has getpwent(), hosts has gethostent(), and so on. These
were reasonable when the only source was files 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 imple-
mentations strive to provide reasonable results, but the
data returned may be incomplete (enumeration for hosts is
simply not supported 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 will return four hostents, and they may
not be consecutive), or very expensive (enumerating a passwd
database of 5000 users is probably a bad idea). Further-
more, multiple threads in the same process using the same
reentrant enumeration function ( getXXXent_r() are supported
beginning with SunOS 5.3) share the same enumeration posi-
tion; if they interleave calls, they will enumerate disjoint
subsets of the same database.
In general the use of the enumeration functions is depre-
cated. In the case of passwd, shadow and group, it may some-
times be appropriate to use fgetgrent(), fgetpwent() and
fgetspent() (see getgrnam(3C), getpwnam(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
/etc/netconfig configuration file for netdir(3N)
functions that redirects
hosts/sevices 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"
SEE ALSO
nis+(1), automount(1M), ifconfig(1M), rpc.bootparamd(1M),
rpc.nisd(1M), sendmail(1M), getgrnam(3C), getpwnam(3C),
getspnam(3C), ethers(3N), gethostbyname(3N),
getnetbyname(3N), getnetgrent(3N), getprotobyname(3N),
getpublickey(3N), getrpcbyname(3N), getservbyname(3N),
netdir(3N), secure_rpc(3N), netconfig(4), resolv.conf(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
will continue using the old configuration.
Programs that use the getXXbyYY() functions cannot be linked
statically since the implementation of these functions
requires dynamic linker functionality to access the shared
objects /usr/lib/nss_SSS.so.1 at run time.
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 may yield different results depend-
ing on which name-service is operational at the time of the
request.
Misspelled names of sources and databases will be treated as
legitimate names of (most likely nonexistent) sources and
databases.
The following functions do not use the switch:
fgetgrent(3C), fgetpwent(3C), fgetspent(3C), getpw(3C),
putpwent(3C).