1 files changed, 266 insertions, 0 deletions
diff --git a/share/man/man5/nsswitch.conf.5 b/share/man/man5/nsswitch.conf.5
new file mode 100644
index 0000000..ca281c8
--- /dev/null
+++ b/share/man/man5/nsswitch.conf.5
@@ -0,0 +1,266 @@
+.\"	$NetBSD: nsswitch.conf.5,v 1.14 1999/03/17 20:19:47 garbled Exp $
+.\"	$FreeBSD$
+.\"
+.\"  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.
+.\"  3. All advertising materials mentioning features or use of this software
+.\"     must display the following acknowledgement:
+.\"  	This product includes software developed by Luke Mewburn.
+.\"  4. The name of the author may not be used to endorse or promote products
+.\"     derived from this software without specific prior written permission.
+.\"  
+.\"  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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 January 22, 1998
+.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, 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 "compat" -offset indent -compact
+.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
+.Sq networks
+use
+.Sy IN
+class entries, all other databases use
+.Sy HS
+class (Hesiod) entries.
+.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 "networks" -offset indent -compact
+.Sy Database	Used by
+.It group	
+.Xr getgrent 3
+.It hosts	
+.Xr gethostbyname 3
+.It networks	
+.Xr getnetbyname 3
+.It passwd	
+.Xr getpwent 3
+.It shells	
+.Xr getusershell 3
+.El
+.Ss Status codes
+The following status codes are available:
+.Bl -column "tryagain" -offset indent -compact
+.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
+.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 "<criterion>" -offset indent
+.It <entry>	::=
+<database> ":" [<source> [<criteria>]]*
+.It <criteria>	::=
+"[" <criterion>+ "]"
+.It <criterion>	::=
+<status> "=" <action>
+.It <status>	::=
+"success" | "notfound" | "unavail" | "tryagain"
+.It <action>	::=
+"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 "dns files" -offset indent
+.Sy Database	Default source list
+.It group	compat
+.It group_compat	nis
+.It hosts	dns files
+.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 authoritive source of information, except
+when the server is down.
+.Sh SEE ALSO
+.Xr nsdispatch 3 ,
+.Xr resolv.conf 5 ,
+.Xr named 8 ,
+.Xr ypbind 8
+.Sh HISTORY
+The
+.Nm
+file format first appeared in
+.Fx 4.1 .
+It was imported from the
+.Nx
+Project, where it appeared first in
+.Nx 1.4 .
+.Sh AUTHORS
+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.