266 lines
7.6 KiB
Groff
266 lines
7.6 KiB
Groff
.\" $NetBSD: nsswitch.conf.5,v 1.22 2003/02/14 15:20:20 grant 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.
|
|
.\" 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 December 27, 1999
|
|
.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 "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 "netgroup" -offset indent -compact
|
|
.Sy Database Used by
|
|
.It group
|
|
.Xr getgrent 3
|
|
.It hosts
|
|
.Xr gethostbyname 3
|
|
.It netgroup
|
|
.Xr getnetgrent 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 "\*[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
|
|
.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 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.
|