Tribblix: manual page: nsswitch.conf.5

NSSWITCH.CONF(5) File Formats and Configurations NSSWITCH.CONF(5)

NAME

nsswitch.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(5), shadow(5), and user_attr(5)), 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,
LDAP, DNS or Multicast 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(8)
auth_attr getauthnam(3SECDB)
automount automount(8)
bootparams rpc.bootparamd(8)
ethers ethers(3SOCKET)
group getgrnam(3C)
hosts gethostbyname(3NSL),
getaddrinfo(3SOCKET). See
Interaction with netconfig.
ipnodes Same as hosts.
netgroup innetgr(3C)
netmasks ifconfig(8)
networks getnetbyname(3SOCKET)
passwd getpwnam(3C), getspnam(3C),
getusernam(3SECDB)
printers lp(1), lpstat(1), cancel(1),
lpr(1B), lpq(1B), lprm(1B),
in.lpd(8), lpadmin(8),
lpget(8), lpset(8)
prof_attr getprofnam(3SECDB),
getexecprof(3SECDB)
project getprojent(3PROJECT),
getdefaultproj(3PROJECT),
inproj(3PROJECT), newtask(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)
ldap LDAP
ad Active Directory
dns Valid only for hosts and
ipnodes. Uses the
Internet Domain Name
Service.
mdns Valid only for hosts and
ipnodes. Uses the
Multicast Domain Name
Service.
compat Valid only for passwd and
group. Implements + and
-. See Interaction with
+/- syntax.
user Valid only for printers.
Implements support for
${HOME}/.printers.

Note that /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. 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
TRYAGAIN=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
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 for DNS and the NIS server in "DNS-forwarding
mode" is [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
TRYAGAIN=3].

The default criteria for all other sources is [SUCCESS=return
NOTFOUND=continue UNAVAIL=continue TRYAGAIN=forever].

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.

Interaction with netconfig

In order to ensure that they all return consistent results,
gethostbyname(3NSL), getaddrinfo(3SOCKET), getservbyname(3SOCKET),
and netdir_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(5) and uses the switch entries
only if the netconfig entries have a - (hyphen) in the last column
for nametoaddr libraries. See the Notes section in
gethostbyname(3NSL) and getservbyname(3SOCKET) for details.

Interaction with 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.

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/nsswitch.conf file:

passwd:
files

passwd:
files nis

passwd:
files ldap

passwd:
compat

passwd_compat:
ldap

You can add the ad keyword to any of the passwd configurations listed
above. However, you cannot use the passwd command to change the
password of an Active Directory (AD) user. If the ad keyword is found
in the passwd entry during a password update operation, it is
ignored. To update the password of an AD user, use the kpasswd(1)
command.

Any other settings causes the passwd(1) command to fail when it
attempts to change the password after expiration and prevents the
user from logging 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(5)).

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 ldap as the source for
the pseudo-database passwd_compat.

Note that in compat mode, for every /etc/passwd entry, there must be
a corresponding 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

auth_attr
files nis

prof_attr
files nis

project
files nis

Note that 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,
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 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 configuration that can be copied to /etc/nsswitch.conf to set
this policy.

When using Active Directory, dns is required to perform hosts
resolution.

If the use of +/- syntax is desired in conjunction with LDAP, use the
following four entries:

passwd:
compat

passwd_compat:
ldap

group:
compat

group_compat:
ldap

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 LDAP, use the following configuration and set up the
/etc/resolv.conf file (see resolv.conf(5) for more details):

hosts:
ldap 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 can be incomplete (enumeration for
hosts is simply not supported by the dns source), inconsistent (if
multiple sources are used), formatted in an unexpected fashion, or
very expensive (enumerating a passwd database of 5,000 users is
probably a bad idea). Furthermore, 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
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 might sometimes 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_mdns.so.1
Implements mdns source.

/usr/lib/nss_nis.so.1
Implements nis source.

/usr/lib/nss_ldap.so.1
Implements ldap source.

/usr/lib/nss_ad.so.1
Implements ad source.

/usr/lib/nss_user.so.1
Implements user source.

/etc/netconfig
Configuration file for netdir(3NSL)
functions 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.ldap
Sample configuration file that uses
files and ldap.

/etc/nsswitch.ad
Sample configuration file that uses
files and ad.

/etc/nsswitch.dns
Sample configuration file that uses
files, dns and mdns (dns and mdns only
for hosts).

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.

Do not use the ldap and ad keywords together when the Solaris LDAP
client uses schema mapping to talk to Active Directory.

Misspelled names of sources and databases are treated as legitimate
names of (most likely nonexistent) sources and databases.

The following functions do not use the switch: fgetgrent(3C),
fgetprojent(3PROJECT), fgetpwent(3C), fgetspent(3C), getpw(3C),
putpwent(3C), shadow(5).

March 6, 2017 NSSWITCH.CONF(5)