`/etc/nsswitch.conf`

Name-service switch configuration file

Description:

The nsswitch.conf file specifies how the nsdispatch() (name-service switch dispatcher) routines in the socket library should operate.

The configuration file controls how a process looks up various databases containing information regarding hosts and networks. Each database comes from a source (such as local files, and DNS ), and the order to look up the sources is specified in nsswitch.conf.

Each entry in nsswitch.conf consists of a database name, and a space-separated list of sources. Each source can have an optional trailing criterion that determines whether the next listed source is used, or the search terminates at the current source. Each criterion consists of one or more status codes, and actions to take if that status code occurs.

Sources

The following sources are implemented:

files: Local files, such as /etc/hosts.
dns: Internet Domain Name System. The hosts and networks databases use IN class entries.

Databases

The following databases are used by the following C library functions:

Database	Used by
`hosts`	getaddrinfo(), gethostbyaddr(), gethostbyname(), and getnameinfo()
`networks`	getnetbyaddr(), getnetbyname()

Status codes

The following status codes are available:

success: The requested entry was found.
notfound: The entry isn't present at this source.
tryagain: The source is busy, and may respond to retries.
unavail: The source isn't responding, or the entry is corrupt.

Actions

For each of the status codes, one of two actions is possible:

continue: Try the next source.
return: Return with the current result.

Format of the file

A BNF description of the syntax of nsswitch.conf is:

<entry>        ::= <database> ":" [<source> [<criteria>]]*
<criteria>     ::= "[" <criterion>+ "]"
<criterion>    ::= <status> "=" <action>
<status>       ::= "success" | "notfound" | "unavail" | "tryagain"
<action>       ::= "return" | "continue"

Each entry starts on a new line in the file. A number sign (#) delimits a comment to the end of the line. Blank lines are ignored. A backslash (\) at the end of a line escapes the newline, and causes the next line to be a continuation of the current line. All entries are case-insensitive.

The default criteria is to return on success, and continue on anything else (i.e. [success=return notfound=continue unavail=continue tryagain=continue]).

Historically, many of the databases had enumeration functions, often of the form getXXXent(). These made sense when the databases were in local files, but don't make sense or have lesser relevance when there are possibly multiple sources, each of an unknown size. The interfaces are still provided for compatibility, but the source may not be able to provide complete entries, or duplicate entries may be retrieved if multiple sources that contain similar information are specified.

If, for any reason, nsswitch.conf doesn't exist, or it has missing or corrupt entries, nsdispatch() will default to an entry of files for the network database, and files dns for the hosts database.

Luke Mewburn wrote this freely distributable name-service switch implementation, using ideas from the ULTRIX svc.conf and Solaris nsswitch.conf manual pages.

Examples:

To look up hosts in /etc/hosts and then from the DNS, use:

hosts:     files dns