nsswitch.conf

- configuration file for the name service switch

Synopsis

svc:/system/name-service/switch

/etc/nsswitch.conf

Description

The operating system uses a number of databases of information about hosts, ipnodes, users (passwd(4), shadow(4), and user_attr(4)), 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 svc:/system/name-service/switch service. For the purposes of backwards compatibility, the /etc/nsswitch.conf file is regenerated from the SMF properties configured in the svc:/system/name-service/switch service. The /etc/nsswitch.conf file is considered obsolete.

The following databases use the switch file:

The following sources can be used:

/etc/inet/ipnodes is a symbolic link to /etc/hosts.

The config property group of the svc:/system/name-service/switch service contains the configuration for the nsswitch.conf file.

The config/default property sets the default property for all nsswitch databases, while the other properties can be used to override the default property if desired.

For instance:

config/default set to "files", and
config/host set to "files dns" defaults all
databases to local files database access, except for the
host database which will search files first and dns second,
if dns access is configured.

The following single-valued properties are supported:

config/default    Default db configuration
config/host       Override for host db
config/password   Override for passwd db
config/group      Override for group db
config/network    Override for network db
config/protocol   Override for protocol db
config/rpc        Override for rpc db
config/ether      Override for ether db
config/netmask    Override for netmask db
config/bootparam  Override for bootparam db
config/publickey  Override for publickey db
config/netgroup   Override for netgroup db
config/automount  Override for automount db
config/alias      Override for alias db
config/service    Override for service db
config/project    Override for project db
config/auth_attr  Override for auth_attr db
config/prof_attr  Override for prof_attr db
config/tnrhtp     Override for tnrhtp db
config/tnrhdb     Override for tnrhdb db

The compat switch source is considered obsolete. It has been replaced with the pam_list(5) module. The compat module can still be enabled with the following properties:

config/enable_passwd_compat    Enable passwd compat
config/enable_group_compat     Enable group compat

Typically the property values are simple, such as "files" "files nis". 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:

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 property is a single valued string. The <source> names are case-sensitive, but <action> and <status> names are case-insensitive.

If an database entry or default is absent, the system defaults to "files" in all situations. Additionally if the name service cache service (svc:/system/name-service-cache) is not enabled, all attemtps access to remote file services can be ignored.

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(4) 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:

passwd:

files

passwd:

files nis

passwd:

files 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

The +/- syntax is considered obsolete. It has been replaced both by the nsswitch configuration and the pam_list(5) module. This syntax will be removed in a future release.

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 can be overridden by specifying ldap as the source for the pseudo-database passwd_compat.

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.

Interaction with Location Profiles

The nsswitch configuration is managed in Location profiles (refer to netcfg(1M) for more information about location profiles). These profiles are either fixed, meaning the network configuration is being managed in the traditional way, or reactive, meaning the network configuration is being managed automatically, reacting to changes in the network environment according to policy rules specified in the profiles.

When a fixed location (there can currently be only one, the DefaultFixed location) is active, changes made to the SMF repository will be applied to the location when it is disabled, and thus will be restored if that location is later re-enabled.

When a reactive location is active, changes should not be applied directly to the SMF repository; these changes will not be preserved in the location profile, and will thus be lost if the location is disabled, or if the system's network configuration, as managed by svc:/network/physical:default and svc:/network/location:default, is refreshed or restarted. Changes should instead be applied to the location itself, using the netcfg(1M) command; this will save the change to the location profile repository, and will also apply it to the SMF repository (if the change is made to the currently active location).

The nsswitch configuration data is stored as the name of a file in the nsswitch.conf format. That name is stored in the nameservices-config-file property of a location profile.

Hard-wired Policies

The compiled-in default entries for all databases is "files".

Useful Configuration Notes

The files source for the ipnodes and hosts databases is identical, as /etc/inet/ipnodes is a symbolic link to /etc/hosts. The host property is used for host lookups.

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

In order to get information from the Internet Domain Name Service for hosts that are not listed in the enterprise level name service LDAP, use the following configuration and set up the /etc/resolv.conf file (see resolv.conf(4) for more details):

hosts:

files dns

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 (for a host with a canonical name and three aliases, a source might return four hostents, and they might 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 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. (Obsolete.)

/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).

See Also

kpasswd(1), newtask(1), passwd(1), automount(1M), ifconfig(1M), mdnsd(1M), netcfg(1M), rpc.bootparamd(1M), sendmail(1M), 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(3C), getexecprof(3C), getprofnam(3C), getuserattr(3C), getusernam(3C), ethers(3SOCKET), getaddrinfo(3SOCKET), getnetbyname(3SOCKET), getprotobyname(3SOCKET), getservbyname(3SOCKET), auth_attr(4), hosts(4), netconfig(4), project(4), resolv.conf(4), user_attr(4), ypfiles(4), ad(5), ldap(5), pam_list(5)

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.

The use of both nis and ldap 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 can yield different results depending on which name service is operational at the time of the request.

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.

nsswitch.conf does not control the name service configuration for everything in Solaris.

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