--- /dev/null
+.\" $NetBSD: nsswitch.conf.5,v 1.28 2009/10/25 01:30:48 wiz Exp $
+.\"
+.\" Copyright (c) 1997, 1998, 1999 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Luke Mewburn.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd October 25, 2009
+.Dt NSSWITCH.CONF 5
+.Os
+.Sh NAME
+.Nm nsswitch.conf
+.Nd name-service switch configuration file
+.Sh DESCRIPTION
+The
+.Nm
+file specifies how the
+.Xr nsdispatch 3
+(name-service switch dispatcher) routines in the C library should operate.
+.Pp
+The configuration file controls how a process looks up various databases
+containing information regarding hosts, users (passwords), groups,
+netgroups, etc.
+Each database comes from a source (such as local files, DNS, and
+.Tn NIS ) ,
+and the order to look up the sources is specified in
+.Nm nsswitch.conf .
+.Pp
+Each entry in
+.Nm
+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.
+.Ss Sources
+The following sources are implemented:
+.Bl -column "multicast_dns" -offset indent -compact
+.It Sy Source Description
+.It files Local files, such as
+.Pa /etc/hosts ,
+and
+.Pa /etc/passwd .
+.It dns Internet Domain Name System.
+.Dq hosts
+and
+.Dq networks
+use
+.Sy IN
+class entries, all other databases use
+.Sy HS
+class (Hesiod) entries.
+.It mdnsd Use
+.Xr mdnsd 8
+for
+.Dq hosts
+lookups, acting as both a system-wide cache for normal unicast DNS
+as well as providing multicast DNS
+.Dq ( zeroconf )
+lookups.
+.It multicast_dns Use
+.Xr mdnsd 8
+only for multicast DNS
+.Dq hosts
+lookups.
+This would normally be used in conjunction with
+.Dq dns ,
+which would then provide unicast DNS resolver functions.
+.It nis NIS (formerly YP)
+.It compat support
+.Sq +/-
+in the
+.Dq passwd
+and
+.Dq group
+databases.
+If this is present, it must be the only source for that entry.
+.El
+.Ss Databases
+The following databases are used by the following C library functions:
+.Bl -column "netgroup" -offset indent -compact
+.It Sy Database Used by
+.It group Ta Xr getgrent 3
+.It hosts Ta Xr gethostbyname 3
+.It netgroup Ta Xr getnetgrent 3
+.It networks Ta Xr getnetbyname 3
+.It passwd Ta Xr getpwent 3
+.It shells Ta Xr getusershell 3
+.El
+.Ss Status codes
+The following status codes are available:
+.Bl -column "tryagain" -offset indent -compact
+.It Sy Status Description
+.It success The requested entry was found.
+.It notfound The entry is not present at this source.
+.It tryagain The source is busy, and may respond to retries.
+.It unavail The source is not responding, or entry is corrupt.
+.El
+.Ss Actions
+For each of the status codes, one of two actions is possible:
+.Bl -column "continue" -offset indent -compact
+.It Sy Action Description
+.It continue Try the next source
+.It return Return with the current result
+.El
+.Ss Format of file
+A
+.Tn BNF
+description of the syntax of
+.Nm
+is:
+.Bl -column "\*[Lt]criterion\*[Gt]" -offset indent
+.It \*[Lt]entry\*[Gt] ::=
+\*[Lt]database\*[Gt] ":" [\*[Lt]source\*[Gt] [\*[Lt]criteria\*[Gt]]]*
+.It \*[Lt]criteria\*[Gt] ::=
+"[" \*[Lt]criterion\*[Gt]+ "]"
+.It \*[Lt]criterion\*[Gt] ::=
+\*[Lt]status\*[Gt] "=" \*[Lt]action\*[Gt]
+.It \*[Lt]status\*[Gt] ::=
+"success" | "notfound" | "unavail" | "tryagain"
+.It \*[Lt]action\*[Gt] ::=
+"return" | "continue"
+.El
+.Pp
+Each entry starts on a new line in the file.
+A
+.Sq #
+delimits a comment to end of line.
+Blank lines are ignored.
+A
+.Sq \e
+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.
+.Pp
+The default criteria is to return on
+.Dq success ,
+and continue on anything else (i.e,
+.Li [success=return notfound=continue unavail=continue tryagain=continue]
+).
+.Ss Compat mode: +/- syntax
+In historical multi-source implementations, the
+.Sq +
+and
+.Sq -
+characters are used to specify the importing of user password and
+group information from
+.Tn NIS .
+Although
+.Nm
+provides alternative methods of accessing distributed sources such as
+.Tn NIS ,
+specifying a sole source of
+.Dq compat
+will provide the historical behaviour.
+.Pp
+An alternative source for the information accessed via
+.Sq +/-
+can be used by specifying
+.Dq passwd_compat: source .
+.Dq source
+in this case can be
+.Sq dns ,
+.Sq nis ,
+or
+any other source except for
+.Sq files
+and
+.Sq compat .
+.Ss Notes
+Historically, many of the databases had enumeration functions, often of
+the form
+.Fn 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.
+.Pp
+To ensure compatibility with previous and current implementations, the
+.Dq compat
+source must appear alone for a given database.
+.Ss Default source lists
+If, for any reason,
+.Nm nsswitch.conf
+doesn't exist, or it has missing or corrupt entries,
+.Xr nsdispatch 3
+will default to an entry of
+.Dq files
+for the requested database.
+Exceptions are:
+.Bl -column passwd_compat "files dns" -offset indent
+.It Sy Database Default source list
+.It group compat
+.It group_compat nis
+.It hosts files dns
+.It netgroup files [notfound=return] nis
+.It passwd compat
+.It passwd_compat nis
+.El
+.Sh FILES
+.Bl -tag -width /etc/nsswitch.conf -compact
+.It Pa /etc/nsswitch.conf
+The file
+.Nm
+resides in
+.Pa /etc .
+.El
+.Sh EXAMPLES
+To lookup hosts in
+.Pa /etc/hosts
+and then from the DNS, and lookup user information from
+.Tn NIS
+then files, use:
+.Bl -column "passwd:" -offset indent
+.It hosts: files dns
+.It passwd: nis [notfound=return] files
+.It group: nis [notfound=return] files
+.El
+.Pp
+The criteria
+.Dq [notfound=return]
+sets a policy of "if the user is notfound in nis, don't try files."
+This treats nis as the authoritative source of information, except
+when the server is down.
+.Sh SEE ALSO
+.Xr getent 1 ,
+.Xr nsdispatch 3 ,
+.Xr resolv.conf 5 ,
+.Xr named 8 ,
+.Xr ypbind 8
+.Sh HISTORY
+The
+.Nm
+file format first appeared in
+.Nx 1.4 .
+.Sh AUTHORS
+.An Luke Mewburn
+.Aq lukem@NetBSD.org
+wrote this freely distributable name-service switch implementation,
+using ideas from the
+.Tn ULTRIX
+.Xr svc.conf 5
+and
+.Tn Solaris
+.Xr nsswitch.conf 4
+manual pages.