nsswitch.conf - configuration file for the name-service switch
The operating system uses a number of "databases" of information about
hosts, users (passwd), 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
passwd getpwnam(), getspnam()
publickey getpublickey(), secure_rpc()
The following sources may be used:
files /etc/hosts, /etc/passwd, and so forth
nis NIS (YP)
dns Valid only for hosts; uses the Internet Domain
compat Valid only for passwd and group; implements "+"
(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
Hewlett-Packard Company - 1 - HP-UX Release 11i: November 2000
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:
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
The default criteria are to continue on anything except SUCCESS; in
other words, [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
The default, or explicitly specified, criteria are meaningless
following the last source in an entry; and 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 based on
the inet family of entries, gethostbyname(), getservbyname(), and
netdir_getbyname() functions are all implemented in terms of the same
internal switch library functions. These functions obtain the system-
wide source lookup policy for hosts and services based on the inet
family entries in netconfig(). For services and hosts only the "-" in
the last column, which represents nametoaddr libraries, is supported.
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
Hewlett-Packard Company - 2 - HP-UX Release 11i: November 2000
clients get much the same results from the "nis" source as from
"nisplus"; however, "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.
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 HP-UX 10.30 did not have the name-service switch
support for passwd and group 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
If this is not sufficient, the "compat" source provides full +/-
semantics. It reads /etc/passwd for getpwnam() 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.
The compat source also provides full +/- semantics for group; the
relevant pseudo-database is group_compat.
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
publickey: nis [NOTFOUND=return] files
automount: files nis
Hewlett-Packard Company - 3 - HP-UX Release 11i: November 2000
aliases: files nis
services: files nis
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."
If compatibility with the +/- syntax for passwd and group is required,
simply modify the entries for passwd and group to:
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:
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 resolver(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 implementations 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).
Furthermore, multiple threads in the same process using the same
reentrant enumeration function (getXXXent_r() are supported) share the
Hewlett-Packard Company - 4 - HP-UX Release 11i: November 2000
same enumeration position; if they interleave calls, they will
enumerate disjoint subsets of the same database.
In general the use of the enumeration functions is deprecated. In the
case of passwd, and group, it may sometimes be appropriate to use
fgetgrent(), fgetpwent(), and fgetspent() (see getgrent(3C), and
getpwent(3C), respectively), which use only the files source.
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.sl.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 depending 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(),
fgetpwent(), fgetspent(), getpw(), and putpwent().
Applications linked with libc.1 will display different default actions
for NOTFOUND and TRYAGAIN. Applications linked with libc.1 will have
the switch search terminate if the Name Service returns a result of
NOTFOUND or TRYAGAIN.
This will be an issue for exisiting nsswitch.conf files that specify
name service lookup criteria that contains no <criterion> between
Example: hosts: dns files
For applications linked with libc.1, the fallback to files will only
occur if DNS returns UNAVAIL. For all other applications, the
fallback to files will occur unless DNS returns SUCCESS.
For applications linked with libc.1 and other applications to have the
same behavior, a <criterion> must be specified between <source>.
For libc.1 behavior:
Hewlett-Packard Company - 5 - HP-UX Release 11i: November 2000
hosts: dns [NOTFOUND=return TRYAGAIN=return] files
For the default system behavior:
hosts: dns [NOTFOUND=continue TRYAGAIN=continue] files
nsswitch.conf was developed by Sun Microsystems, Inc.
A source named SSS is implemented by a shared object named nss_SSS.1
that resides in /usr/lib.
/etc/nsswitch.conf configuration file
/usr/lib/nss_compat.1 implements "compat" source
/usr/lib/nss_dns.1 implements "dns" source
/usr/lib/nss_files.1 implements "files" source
/usr/lib/nss_nis.1 implements "nis" source
/usr/lib/nss_nisplus.1 implements "nisplus" source
/etc/netconfig configuration file for netdir()
functions that redirects
hosts/services policy to the
/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"
nis+(1), automount(1M), rpc.nisd(1M), sendmail(1M), getgrent(3C),
getpwent(3C), gethostent(3N), getnetent(3N), getnetgrent(3C),
getprotoent(3N), getpublickey(3N), getrpcent(3C), getservent(3N),
netdir(3N), secure_rpc(3N), netconfig(4), resolver(4), ypfiles(4).
Hewlett-Packard Company - 6 - HP-UX Release 11i: November 2000