Go to main content

man pages section 5: File Formats

Exit Print View

Updated: Wednesday, July 27, 2022

nsswitch.conf (5)


nsswitch.conf - configuration file for the name service switch




The operating system uses a number of databases of information about hosts, services, 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 SMF properties of the svc:/system/name-service/switch service. For the purposes of backward compatibility, the /etc/nsswitch.conf file is regenerated from the configuration in the svc:/system/name-service/switch service. The /etc/nsswitch.conf file is considered obsolete.

The following databases use the switch configuration:

Used By
getaddrinfo(3C), getnameinfo(3C), gethostent(3C). See Interaction with netconfig.
See Interaction with netconfig.

In the above table, the Database column shows the form used in the /etc/nsswitch.conf file, while the Property column shows the form used in the SMF configuration properties. The ipnodes database used for mapping hostnames to IPv6 addresses in prior releases of Solaris is no longer used. Instead the hosts database is used for both IPv4 and IPv6 addresses. Lookups of user_attr entries currently use the sources specified for the password database.

The following sources can be used:

/etc/hosts, /etc/passwd, /etc/shadow, /etc/security/auth_attr, /etc/user_attr
NIS (YP). See nis(7) and ypfiles(5).
LDAP. See ldap(7).
Active Directory. See ad(7).
Valid only for hosts. Uses the Internet Domain Name Service.
Valid only for hosts. Uses the Multicast Domain Name Service.

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, if config/default is set to "files", and config/host is set to "files dns", then all nsswitch databases default to local files database access, except for the host database which will search files first and DNS second.

The following single-valued properties are supported:

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

Typically the property values are simple lists of sources, such as "files" or "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 status codes:

Requested database entry was found.
Source is not configured on this system or internal failure.
Source responded “no such entry
Source is busy or not responding, might respond to retries.

For each status code, the following actions are possible:

Try the next source in the list.
Return now.

Additionally, for TRYAGAIN only, the following actions are possible:

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

If a 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 attempts to access remote file services may fail or return incomplete results.

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, the getaddrinfo(3C), gethostbyname(3C), getservbyname(3C), and netdir_getbyname(3C) functions are all implemented in terms of the same internal library function. This function obtains the system-wide source lookup policy for hosts 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(3C) and getservbyname(3C) 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 supported and must follow those rules:

  • password configuration must have 1, 2, or 3 entries

  • First password entry must be files

  • password entries other than files, nis and ldap are ignored and skipped during password update. (It is necessary to use a source-specific tool to update a password in such database).

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 password configurations 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.

Hard-wired Policies

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

Useful Configuration Notes

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

It is strongly advised that dns always be used to perform host lookups. This is especially true when ldap is being used for name service lookups. The use of ldap for host lookups is not recommended. Adding ldap to hosts will likely prevent authentication to the LDAP server while using TLS. In order to get information from the Internet Domain Name Service for hosts set the config/host property to "files dns", and set up the /etc/resolv.conf file (see resolv.conf(5) for more details).

Enumeration - getXXXent()

Many of the databases have enumeration functions: password has getpwent(), host 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 host 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 password 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 Solaris 2.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.


Example 1 Displaying current switch configuration

This command displays the existing configuration of the name service switch. It shows the use of the files and ldap sources for automount maps and information about users and groups, the use of the files and dns sources for host name and address lookup, the use of just the ldap source for netgroups, and the default of files for all other databases.

example% svccfg -s name-service/switch listprop config
config                     application
config/automount           astring     "files ldap"
config/default             astring     files
config/group               astring     "files ldap"
config/host                astring     "files dns"
config/netgroup            astring     ldap
config/password            astring     "files ldap"
Example 2 Changing switch configuration

This command sets host name and address lookup to use the files source first to search the /etc/hosts and then the dns source to query the name servers specified in resolv.conf(5) for information not found in the hosts file.

example% svccfg -s name-service/switch
svc:/system/name-service/switch> setprop config/host = astring: "files dns"
svc:/system/name-service/switch> select system/name-service/switch:default
svc:/system/name-service/switch:default> refresh
svc:/system/name-service/switch:default> validate
svc:/system/name-service/switch:default> quit

For the full set of commands needed to configure and enable DNS usage, see Configuring a DNS Client in Configuring and Managing Network Components in Oracle Solaris 11.4.


A source named SSS is implemented by a shared object named nss_SSS.so.1 that resides in /usr/lib as a 32-bit shared object, and in /usr/lib/64 as a 64-bit shared object.


Configuration file. (Obsolete.)


Implements dns source.


Implements files source.


Implements mdns source.


Implements nis source.


Implements ldap source.


Implements ad source.


Configuration file for netdir(3C) functions that redirects hosts/devices policy to the switch.


Sample configuration file that uses files only.


Sample configuration file that uses files and nis.


Sample configuration file that uses files and ldap.


Sample configuration file that uses files and ad.


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

See Also

kpasswd(1), newtask(1), passwd(1), ethers(3C), getaddrinfo(3C), getauthnam(3C), getexecprof(3C), getgrnam(3C), gethostbyname(3C), getnetbyname(3C), getnetgrent(3C), getprofnam(3C), getprotobyname(3C), getpublickey(3C), getpwnam(3C), getrpcbyname(3C), getservbyname(3C), getspnam(3C), getuserattr(3C), getusernam(3C), netdir(3C), secure_rpc(3C), getdefaultproj(3PROJECT), getprojent(3PROJECT), inproj(3PROJECT), setproject(3PROJECT), auth_attr(5), hosts(5), netconfig(5), project(5), resolv.conf(5), user_attr(5), ypfiles(5), ad(7), ldap(7), nis(7), pam_list(7), automount(8), getent(8), ipadm(8), mdnsd(8), nscd(8), nscfg(8), rpc.bootparamd(8), sendmail(8), svccfg(8)

Chapter 4, Administering Naming and Directory Services on an Oracle Solaris System in Configuring and Managing Network Components in Oracle Solaris 11.4


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 Oracle 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 non-existent) sources and databases.

The compat backend and the use of '+' or '-' interactions in the password and group files is no longer supported.

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

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

To lookup entries in a database from the command line following the switch configuration, use the getent(8) command. Name service client commands such as delv(1), dig(1), nslookup(1), ldaplist(1), and ypmatch(1) bypass the switch configuration and look solely in their respective name service.