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 and shadow), 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 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 file:
The following sources may be used:
There is an entry in /etc/nsswitch.conf for each database. Typically these entries will be 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 will be tried. A source can return one of the following codes:
For each status code, two actions are possible:
Additionally, for TRYAGAIN only, the following actions are possible:
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" (and DNS server not responding or busy) is [SUCCESS=return NOTFOUND=continue UNAVAIL=continue TRYAGAIN=continue].
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), getipnodebyname(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(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(3NSL)
and getservbyname(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 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.
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/nsswitch.conf file:
passwd:
files
passwd:
files nis
passwd:
files nisplus
passwd:
files ldap
passwd:
compat
passwd_compat:
nisplus
passwd_compat:
ldap
Any other settings will cause the passwd(1) command to fail when it attempts to change the password after expiration and will prevent 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(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 may be overridden by specifying "nisplus" or "ldap" 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 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
sendmailvars:
files
printers:
user files nis nisplus xfn
auth_attr
files nis
prof_attr
files nis
project
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." 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 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.
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 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 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 will 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 may 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_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.
/usr/lib/nss_xfn.so.1
Implements "xfn" 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.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 ALSO
ldap(1), newtask(1), nis+(1), passwd(1), automount(1M), ifconfig(1M), rpc.bootparamd(1M), rpc.nisd(1M), sendmail(1M), getauusernam(3BSM)getgrnam(3C), getnetgrent(3C), getpwnam(3C), getspnam(3C), gethostbyname(3NSL), getpublickey(3NSL), getrpcbyname(3NSL), netdir(3NSL), secure_rpc(3NSL), getprojent(3PROJECT), getdefaultproj(3PROJECT), inproj(3PROJECT), setproject(3PROJECT), getauthnam(3SECDB), getexecprof(3SECDB), getprofnam(3SECDB), getusernam(3SECDB), ethers(3SOCKET), getipnodebyname(3SOCKET), getnetbyname(3SOCKET), getprotobyname(3SOCKET), getservbyname(3SOCKET), netconfig(4), project(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 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 will be 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(4).