mirror of https://github.com/mkerrisk/man-pages
nsswitch.conf.5: Significant rewrites and improvements
This patch applies to nsswitch.conf.5 in man-pages-3.36. My changes almost completely rewrite large sections of the man page. They are needed to add clarity, correct grammar, reduce confusion, and bring up-to-date with the latest glibc. I have checked the man page against the nss source code in glibc 2.14.90. Historical notes are demoted to the footer. The rewrite makes the man page much clearer to understand, more authoratitive, and easier to read. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Mark R Bannister
Michael Kerrisk
parent
b76a964b20
commit
79e2fba2d9
|
|
@ -1,4 +1,5 @@
|
||||||
.\" Copyright (c) 1998, 1999 Thorsten Kukuk (kukuk@vt.uni-paderborn.de)
|
.\" Copyright (c) 1998, 1999 Thorsten Kukuk (kukuk@vt.uni-paderborn.de)
|
||||||
|
.\" Copyright (c) 2011, Mark R. Bannister <cambridge@users.sourceforge.net>
|
||||||
.\"
|
.\"
|
||||||
.\" This is free documentation; you can redistribute it and/or
|
.\" This is free documentation; you can redistribute it and/or
|
||||||
.\" modify it under the terms of the GNU General Public License as
|
.\" modify it under the terms of the GNU General Public License as
|
||||||
|
|
@ -20,39 +21,32 @@
|
||||||
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
||||||
.\" USA.
|
.\" USA.
|
||||||
.\"
|
.\"
|
||||||
.\" This manual page based on the GNU C Library info pages.
|
.TH NSSWITCH.CONF 5 2011-10-13 "Linux" "Linux Programmer's Manual"
|
||||||
.\" FIXME ? The use of quotes on this page is inconsistent with the
|
|
||||||
.\" rest of man-pages.
|
|
||||||
.\"
|
|
||||||
.TH NSSWITCH.CONF 5 1999-01-17 "Linux" "Linux Programmer's Manual"
|
|
||||||
.SH NAME
|
.SH NAME
|
||||||
nsswitch.conf \- System Databases and Name Service Switch configuration file
|
nsswitch.conf \- Name Service Switch configuration file
|
||||||
.SH DESCRIPTION
|
.SH DESCRIPTION
|
||||||
Various functions in the C Library need to be configured to work
|
The
|
||||||
correctly in the local environment.
|
|
||||||
Traditionally, this was done by
|
|
||||||
using files (e.g., \fI/etc/passwd\fP), but other nameservices (like the
|
|
||||||
Network Information Service (NIS) and the Domain Name Service (DNS))
|
|
||||||
became popular, and were hacked into the C library, usually with a fixed
|
|
||||||
search order.
|
|
||||||
.LP
|
|
||||||
The Linux libc5 with NYS support and the GNU C Library 2.x (libc.so.6)
|
|
||||||
contain a cleaner solution of this problem.
|
|
||||||
It is designed after a method
|
|
||||||
used by Sun Microsystems in the C library of Solaris 2.
|
|
||||||
We follow their
|
|
||||||
name and call this scheme "Name Service Switch" (NSS).
|
|
||||||
The sources for
|
|
||||||
the "databases" and their lookup order are specified in the
|
|
||||||
.I /etc/nsswitch.conf
|
.I /etc/nsswitch.conf
|
||||||
file.
|
file is a configuration file used by the GNU C Library to determine from
|
||||||
|
what sources to obtain name service information in a range of categories,
|
||||||
|
and in what order.
|
||||||
|
Each category of information is identified by a database name.
|
||||||
.LP
|
.LP
|
||||||
The following databases are available in the NSS:
|
The file is plain ASCII text, with columns separated by spaces or tab
|
||||||
.TP
|
characters.
|
||||||
|
The first column defines the database name.
|
||||||
|
The remaining columns describe the order of sources to query and a
|
||||||
|
limited
|
||||||
|
set of actions that can be performed by lookup result.
|
||||||
|
.LP
|
||||||
|
The following databases are made available by the standard
|
||||||
|
GNU C Library:
|
||||||
|
.RS 3
|
||||||
|
.TP 10
|
||||||
.B aliases
|
.B aliases
|
||||||
Mail aliases, used by
|
Mail aliases, used by
|
||||||
.BR sendmail (8).
|
.BR getaliasent (3)
|
||||||
Presently ignored.
|
and related functions.
|
||||||
.TP
|
.TP
|
||||||
.B ethers
|
.B ethers
|
||||||
Ethernet numbers.
|
Ethernet numbers.
|
||||||
|
|
@ -60,31 +54,31 @@ Ethernet numbers.
|
||||||
.B group
|
.B group
|
||||||
Groups of users, used by
|
Groups of users, used by
|
||||||
.BR getgrent (3)
|
.BR getgrent (3)
|
||||||
functions.
|
and related functions.
|
||||||
.TP
|
.TP
|
||||||
.B hosts
|
.B hosts
|
||||||
Host names and numbers, used by
|
Host names and numbers, used by
|
||||||
.BR gethostbyname (3)
|
.BR gethostbyname (3)
|
||||||
and similar functions.
|
and related functions.
|
||||||
.TP
|
.TP
|
||||||
.B netgroup
|
.B netgroup
|
||||||
Network wide list of hosts and users, used for access rules.
|
Network wide list of hosts and users, used for access rules.
|
||||||
C libraries before glibc 2.1 only support netgroups over NIS.
|
C libraries before glibc 2.1 only supported netgroups over NIS.
|
||||||
.TP
|
.TP
|
||||||
.B networks
|
.B networks
|
||||||
Network names and numbers, used by
|
Network names and numbers, used by
|
||||||
.BR getnetent (3)
|
.BR getnetent (3)
|
||||||
functions.
|
and related functions.
|
||||||
.TP
|
.TP
|
||||||
.B passwd
|
.B passwd
|
||||||
User passwords, used by
|
User passwords, used by
|
||||||
.BR getpwent (3)
|
.BR getpwent (3)
|
||||||
functions.
|
and related functions.
|
||||||
.TP
|
.TP
|
||||||
.B protocols
|
.B protocols
|
||||||
Network protocols, used by
|
Network protocols, used by
|
||||||
.BR getprotoent (3)
|
.BR getprotoent (3)
|
||||||
functions.
|
and related functions.
|
||||||
.TP
|
.TP
|
||||||
.B publickey
|
.B publickey
|
||||||
Public and secret keys for Secure_RPC used by NFS and NIS+.
|
Public and secret keys for Secure_RPC used by NFS and NIS+.
|
||||||
|
|
@ -92,23 +86,24 @@ Public and secret keys for Secure_RPC used by NFS and NIS+.
|
||||||
.B rpc
|
.B rpc
|
||||||
Remote procedure call names and numbers, used by
|
Remote procedure call names and numbers, used by
|
||||||
.BR getrpcbyname (3)
|
.BR getrpcbyname (3)
|
||||||
and similar functions.
|
and related functions.
|
||||||
.TP
|
.TP
|
||||||
.B services
|
.B services
|
||||||
Network services, used by
|
Network services, used by
|
||||||
.BR getservent (3)
|
.BR getservent (3)
|
||||||
functions.
|
and related functions.
|
||||||
.TP
|
.TP
|
||||||
.B shadow
|
.B shadow
|
||||||
Shadow user passwords, used by
|
Shadow user passwords, used by
|
||||||
.BR getspnam (3).
|
.BR getspnam (3)
|
||||||
|
and related functions.
|
||||||
|
.RE
|
||||||
.LP
|
.LP
|
||||||
An example
|
Here is an example
|
||||||
.I /etc/nsswitch.conf
|
.I /etc/nsswitch.conf
|
||||||
(namely, the default used when
|
file:
|
||||||
.I /etc/nsswitch.conf
|
.LP
|
||||||
is missing):
|
.RS 3
|
||||||
.sp 1n
|
|
||||||
.PD 0
|
.PD 0
|
||||||
.TP 16
|
.TP 16
|
||||||
passwd:
|
passwd:
|
||||||
|
|
@ -139,147 +134,216 @@ nis [NOTFOUND=return] files
|
||||||
services:
|
services:
|
||||||
nis [NOTFOUND=return] files
|
nis [NOTFOUND=return] files
|
||||||
.PD
|
.PD
|
||||||
|
.RE
|
||||||
.LP
|
.LP
|
||||||
The first column is the database.
|
The first column is the database name.
|
||||||
The rest of the line specifies how the lookup process works.
|
The remaining columns specify:
|
||||||
You can specify the way it works for each database individually.
|
.RS 3
|
||||||
.LP
|
.TP 3
|
||||||
The configuration specification for each database can contain two
|
o
|
||||||
different items:
|
One or more service specifications e.g. "files", "db", or "nis".
|
||||||
.PD 0
|
The order the services appear on the line determine the order in which
|
||||||
|
those services will be queried, in turn, until a result is found.
|
||||||
.TP
|
.TP
|
||||||
* The service specification like `files', `db', or `nis'.
|
o
|
||||||
.TP
|
Optional actions to perform if a particular result is obtained
|
||||||
* The reaction on lookup result like `[NOTFOUND=return]'.
|
from the preceding service, e.g. "[NOTFOUND=return]".
|
||||||
.PD
|
.RE
|
||||||
.LP
|
.LP
|
||||||
For libc5 with NYS, the allowed service specifications are `files', `nis',
|
The service specifications supported on your system depend on the
|
||||||
and `nisplus'.
|
presence of shared libraries, and are therefore extensible.
|
||||||
For hosts, you could specify `dns' as extra service, for
|
Libraries called
|
||||||
passwd and group `compat', but not for shadow.
|
.IB /lib/libnss_SERVICE.so. X
|
||||||
.LP
|
will provide the named
|
||||||
For glibc, you must have a file called
|
.IR SERVICE .
|
||||||
.BI /lib/libnss_SERVICE.so. X
|
On a standard installation, you can use
|
||||||
for every SERVICE you are using.
|
"files", "db", "nis", and "nisplus".
|
||||||
On a standard installation, you could use
|
For the hosts database, you can additionally specify "dns".
|
||||||
`files', `db', `nis', and `nisplus'.
|
For the passwd, group, and shadow databases, you can additionally specify
|
||||||
For hosts, you could specify `dns' as
|
"compat" (see
|
||||||
extra service, for passwd, group, and shadow `compat'.
|
.B "Compatibility mode"
|
||||||
These services will not
|
below).
|
||||||
be used by libc5 with NYS.
|
|
||||||
The version number
|
The version number
|
||||||
.I X
|
.B X
|
||||||
is 1 for glibc 2.0 and 2 for glibc 2.1.
|
may be 1 for glibc 2.0, or 2 for glibc 2.1 and later.
|
||||||
|
On systems with additional libraries installed, you may have access to
|
||||||
|
further services such as "hesiod", "ldap", "winbind" and "wins".
|
||||||
.LP
|
.LP
|
||||||
The second item in the specification gives the user much finer
|
An action may also be specified following a service specification, that
|
||||||
control on the lookup process.
|
modifies behaviour following a result obtained from the preceding data
|
||||||
Action items are placed between two
|
source.
|
||||||
service names and are written within brackets.
|
Action items take the general form:
|
||||||
The general form is
|
|
||||||
.LP
|
.LP
|
||||||
`[' ( `!'? STATUS `=' ACTION )+ `]'
|
.RS 3
|
||||||
|
[
|
||||||
|
.I STATUS
|
||||||
|
=
|
||||||
|
.I ACTION
|
||||||
|
]
|
||||||
|
.br
|
||||||
|
[ !
|
||||||
|
.I STATUS
|
||||||
|
=
|
||||||
|
.I ACTION
|
||||||
|
]
|
||||||
|
.RE
|
||||||
.LP
|
.LP
|
||||||
where
|
where
|
||||||
.sp 1n
|
|
||||||
.PD 0
|
|
||||||
.TP
|
|
||||||
STATUS => success | notfound | unavail | tryagain
|
|
||||||
.TP
|
|
||||||
ACTION => return | continue
|
|
||||||
.PD
|
|
||||||
.LP
|
.LP
|
||||||
The case of the keywords is insignificant.
|
.RS 3
|
||||||
The STATUS values are
|
.I STATUS
|
||||||
the results of a call to a lookup function of a specific service.
|
=>
|
||||||
They mean:
|
|
||||||
.TP
|
|
||||||
.B success
|
.B success
|
||||||
No error occurred and the wanted entry is returned.
|
|
|
||||||
The default
|
.B notfound
|
||||||
action for this is `return'.
|
|
|
||||||
|
.B unavail
|
||||||
|
|
|
||||||
|
.B tryagain
|
||||||
|
.br
|
||||||
|
.I ACTION
|
||||||
|
=>
|
||||||
|
.B return
|
||||||
|
|
|
||||||
|
.B continue
|
||||||
|
.RE
|
||||||
|
.LP
|
||||||
|
The ! negates the test, matching all possible results except the
|
||||||
|
one specified.
|
||||||
|
The case of the keywords is insignificant.
|
||||||
|
.LP
|
||||||
|
The
|
||||||
|
.I STATUS
|
||||||
|
value is matched against the result of the lookup function called by
|
||||||
|
the preceding service specification, and can be one of:
|
||||||
|
.RS 3
|
||||||
|
.TP 10
|
||||||
|
.B success
|
||||||
|
No error occurred and the requested entry is returned.
|
||||||
|
The default action for this condition is "return".
|
||||||
.TP
|
.TP
|
||||||
.B notfound
|
.B notfound
|
||||||
The lookup process succeeded, but the needed value was not found.
|
The lookup succeeded, but the requested entry was not found.
|
||||||
The default action is `continue'.
|
The default action for this condition is "continue".
|
||||||
.TP
|
.TP
|
||||||
.B unavail
|
.B unavail
|
||||||
The service is permanently unavailable.
|
The service is permanently unavailable.
|
||||||
This can either mean the
|
This can either mean the
|
||||||
needed file is not available, or, for DNS, the server is not
|
required file cannot be read, or, for network services, the server
|
||||||
available or does not allow queries.
|
is not available or does not allow queries.
|
||||||
The default action is
|
The default action for this condition is "continue".
|
||||||
`continue'.
|
|
||||||
.TP
|
.TP
|
||||||
.B tryagain
|
.B tryagain
|
||||||
The service is temporarily unavailable.
|
The service is temporarily unavailable.
|
||||||
This could mean a file is
|
This could mean a file is
|
||||||
locked or a server currently cannot accept more connections.
|
locked or a server currently cannot accept more connections.
|
||||||
The default action is `continue'.
|
The default action for this condition is "continue".
|
||||||
.SS Interaction with +/\- syntax (compat mode)
|
.RE
|
||||||
Linux libc5 without NYS does not have the name service switch but does
|
.LP
|
||||||
allow the user some policy control.
|
The
|
||||||
In
|
.I ACTION
|
||||||
|
value can be one of:
|
||||||
|
.RS 3
|
||||||
|
.TP 10
|
||||||
|
.B return
|
||||||
|
Return a result now.
|
||||||
|
Do not call any further lookup functions.
|
||||||
|
.TP
|
||||||
|
.B continue
|
||||||
|
Call the next lookup function.
|
||||||
|
.RE
|
||||||
|
.SS Compatibility mode (compat)
|
||||||
|
The NSS "compat" service is similar to "files" except that it
|
||||||
|
additionally permits special entries in
|
||||||
.I /etc/passwd
|
.I /etc/passwd
|
||||||
you could have entries of the form +user or +@netgroup
|
for granting users or members of netgroups access to the system.
|
||||||
(include the specified user from the NIS passwd map),
|
The following entries are valid in this mode:
|
||||||
\-user or \-@netgroup (exclude the specified user),
|
.RS 3
|
||||||
and + (include every user, except the excluded ones, from the NIS
|
.TP 12
|
||||||
passwd map).
|
.BI + user
|
||||||
Since most people only put a + at the end of
|
Include the specified
|
||||||
.I /etc/passwd
|
.I user
|
||||||
to include everything from NIS, the switch provides a faster
|
from the NIS passwd map.
|
||||||
alternative for this case (`passwd: files nis') which doesn't
|
.TP
|
||||||
require the single + entry in
|
.BI +@ netgroup
|
||||||
.IR /etc/passwd ,
|
Include all users in the given
|
||||||
.IR /etc/group ,
|
.IR netgroup .
|
||||||
and
|
.TP
|
||||||
.IR /etc/shadow .
|
.BI \- user
|
||||||
If this is not sufficient, the NSS `compat' service provides full
|
Exclude the specified
|
||||||
+/\- semantics.
|
.I user
|
||||||
By default, the source is `nis', but this may be
|
from the NIS passwd map.
|
||||||
overridden by specifying `nisplus' as source for the pseudo-databases
|
.TP
|
||||||
|
.BI \-@ netgroup
|
||||||
|
Exclude all users in the given
|
||||||
|
.IR netgroup .
|
||||||
|
.TP
|
||||||
|
.B +
|
||||||
|
Include every user, except previously excluded ones, in the
|
||||||
|
NIS passwd map.
|
||||||
|
.RE
|
||||||
|
.LP
|
||||||
|
By default the source is "nis", but this may be
|
||||||
|
overridden by specifying "nisplus" as source for the pseudo-databases
|
||||||
.BR passwd_compat ,
|
.BR passwd_compat ,
|
||||||
.B group_compat
|
.B group_compat
|
||||||
and
|
and
|
||||||
.BR shadow_compat .
|
.BR shadow_compat .
|
||||||
These pseudo-databases are only available in GNU C Library.
|
|
||||||
.SH FILES
|
.SH FILES
|
||||||
A service named SERVICE is implemented by a shared object library named
|
A service named
|
||||||
.BI libnss_SERVICE.so. X
|
.I SERVICE
|
||||||
|
is implemented by a shared object library named
|
||||||
|
.IB libnss_SERVICE.so. X
|
||||||
that resides in
|
that resides in
|
||||||
.IR /lib .
|
.IR /lib .
|
||||||
|
.RS 3
|
||||||
.TP 25
|
.TP 25
|
||||||
.PD 0
|
.PD 0
|
||||||
.I /etc/nsswitch.conf
|
.I /etc/nsswitch.conf
|
||||||
configuration file
|
NSS configuration file.
|
||||||
.TP
|
.TP
|
||||||
.BI /lib/libnss_compat.so. X
|
.IB /lib/libnss_compat.so. X
|
||||||
implements `compat' source for glibc2
|
implements "compat" source.
|
||||||
.TP
|
.TP
|
||||||
.BI /lib/libnss_db.so. X
|
.IB /lib/libnss_db.so. X
|
||||||
implements `db' source for glibc2
|
implements "db" source.
|
||||||
.TP
|
.TP
|
||||||
.BI /lib/libnss_dns.so. X
|
.IB /lib/libnss_dns.so. X
|
||||||
implements `dns' source for glibc2
|
implements "dns" source.
|
||||||
.TP
|
.TP
|
||||||
.BI /lib/libnss_files.so. X
|
.IB /lib/libnss_files.so. X
|
||||||
implements `files' source for glibc2
|
implements "files" source.
|
||||||
.TP
|
.TP
|
||||||
.BI /lib/libnss_hesiod.so. X
|
.IB /lib/libnss_hesiod.so. X
|
||||||
implements `hesiod' source for glibc2
|
implements "hesiod" source.
|
||||||
.TP
|
.TP
|
||||||
.BI /lib/libnss_nis.so. X
|
.IB /lib/libnss_nis.so. X
|
||||||
implements `nis' source for glibc2
|
implements "nis" source.
|
||||||
.TP
|
.TP
|
||||||
.I /lib/libnss_nisplus.so.2
|
.IB /lib/libnss_nisplus.so. X
|
||||||
implements `nisplus' source for glibc 2.1
|
implements "nisplus" source.
|
||||||
.PD
|
.PD
|
||||||
|
.RE
|
||||||
|
.SH SEE ALSO
|
||||||
|
.BR getent (1),
|
||||||
|
.BR nss (5).
|
||||||
.SH NOTES
|
.SH NOTES
|
||||||
Within each process that uses
|
Within each process that uses
|
||||||
.BR nsswitch.conf ,
|
.BR nsswitch.conf ,
|
||||||
the entire file is read only once; if the file is later changed, the
|
the entire file is read only once.
|
||||||
|
If the file is later changed, the
|
||||||
process will continue using the old configuration.
|
process will continue using the old configuration.
|
||||||
.LP
|
.LP
|
||||||
With Solaris, it isn't possible to link programs using the NSS Service
|
Traditionally there was only a single source for service information,
|
||||||
statically.
|
often in the form of a single configuration
|
||||||
With Linux, this is no problem.
|
file (e.g. \fI/etc/passwd\fP).
|
||||||
|
However, as other nameservices, like the Network Information
|
||||||
|
Service (NIS) and the Domain Name Service (DNS), became popular,
|
||||||
|
a method was needed
|
||||||
|
that would be more flexible than fixed search orders coded into
|
||||||
|
the C library.
|
||||||
|
.LP
|
||||||
|
The Linux libc5 with NYS support and the GNU C Library 2.x (libc.so.6)
|
||||||
|
introduced a cleaner solution to the problem, based on the
|
||||||
|
.B "Name Service Switch"
|
||||||
|
mechanism used by Sun Microsystems in the Solaris 2 C library.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue