nsswitch.conf(4)

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, 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 bootparamd(1M)

ethers ethers(3N)

group getgrnam(3C)

hosts gethostbyname(3N)

(See "Interaction with netconfig" below)

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)

netgroup innetgr(3N)

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; implements "+" 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 "#" or with white space, are ignored. The <database> and <source> names are case-sensitive, but <action> and <status> names are case-insensitive.

The library routines 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 SUCCESS; in other words, [SUCCESS=return NOTFOUND=continue UNAVAIL=continue TRYAGAIN=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

The gethostbyname(3N) and getservbyname(3N) routines are implemented in terms of the netdir(3N) routines. Thus they consult netconfig(4), and will only use the switch if the netconfig entries include "switch.so". 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"; 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.

In 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) routines and /etc/shadow for getspnam(3C) routines 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

automount: files nis

aliases: files nis

services: nis [NOTFOUND=return] files

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 policy is similar to the one 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 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 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/switch.so makes netdir(3N) routines use the switch

/etc/netconfig configuration file for netdir(3N) routines that refers to "switch.so"

/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"

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() routines cannot be linked statically since the implementation of these routines 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.

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

The following routines do not use the switch: fgetgrent(3C), fgetpwent(3C), fgetspent(3C), getpw(3C), putpwent(3C).

Sun Microsystems — Last change: 21 July 1993

Museum

Related Articles