Add nsswitch support.
[dragonfly.git] / share / man / man5 / nsswitch.conf.5
index 3230b4f..bf828d0 100644 (file)
@@ -1,39 +1,40 @@
 .\"    $NetBSD: nsswitch.conf.5,v 1.14 1999/03/17 20:19:47 garbled Exp $
-.\"    $FreeBSD: src/share/man/man5/nsswitch.conf.5,v 1.8 2002/12/12 22:22:51 trhodes Exp $
-.\"    $DragonFly: src/share/man/man5/nsswitch.conf.5,v 1.1 2003/08/01 04:11:23 rob Exp $
 .\"
-.\"  Copyright (c) 1997, 1998, 1999 The NetBSD Foundation, Inc.
-.\"  All rights reserved.
+.\" 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.
+.\" 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.
+.\" 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.
+.\" 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
+.\" $FreeBSD: src/share/man/man5/nsswitch.conf.5,v 1.18 2007/10/19 00:16:29 bushman Exp $
+.\" $DragonFly: src/share/man/man5/nsswitch.conf.5,v 1.1 2003/08/01 04:11:23 rob Exp $
+.\"
+.Dd January 22, 2007
 .Dt NSSWITCH.CONF 5
 .Os
 .Sh NAME
@@ -48,9 +49,9 @@ file specifies how the
 .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
+Each database comes from a source (such as local files, DNS,
+.Tn NIS ,
+and cache), and the order to look up the sources is specified in
 .Nm .
 .Pp
 Each entry in
@@ -93,6 +94,10 @@ and
 .Dq group
 databases.
 If this is present, it must be the only source for that entry.
+.It cache
+makes use of the
+.Xr nscd 8
+daemon.
 .El
 .Ss Databases
 The following databases are used by the following C library functions:
@@ -101,15 +106,45 @@ The following databases are used by the following C library functions:
 .It Sy Database
 .Sy "Used by"
 .It group
-.Xr getgrent 3
+.Xr getgrent 3 ,
+.Xr getgrent_r 3 ,
+.Xr getgrgid_r 3 ,
+.Xr getgrnam_r 3 ,
+.Xr setgrent 3 ,
+.Xr endgrent 3
 .It hosts
-.Xr gethostbyname 3
+.Xr getaddrinfo 3 ,
+.Xr gethostbyaddr 3 ,
+.Xr gethostbyaddr_r 3 ,
+.Xr gethostbyname 3 ,
+.Xr gethostbyname2 3 ,
+.Xr gethostbyname_r 3 ,
+.Xr getipnodebyaddr 3 ,
+.Xr getipnodebyname 3
 .It networks
-.Xr getnetbyname 3
+.Xr getnetbyaddr 3 ,
+.Xr getnetbyaddr_r 3 ,
+.Xr getnetbyname 3 ,
+.Xr getnetbyname_r 3
 .It passwd
-.Xr getpwent 3
+.Xr getpwent 3 ,
+.Xr getpwent_r 3 ,
+.Xr getpwnam_r 3 ,
+.Xr getpwuid_r 3 ,
+.Xr setpwent 3 ,
+.Xr endpwent 3
 .It shells
 .Xr getusershell 3
+.It services
+.Xr getservent 3
+.It rpc
+.Xr getrpcbyname 3 ,
+.Xr getrpcbynumber 3 ,
+.Xr getrpcent 3
+.It proto
+.Xr getprotobyname 3
+.Xr getprotobynumber 3 ,
+.Xr getprotoent 3
 .El
 .Ss Status codes
 The following status codes are available:
@@ -177,6 +212,25 @@ 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 Cache
+You can enable caching for the particular database by specifying
+.Dq cache
+as the first source in the
+.Xr nsswitch.conf 5
+file.
+You should also enable caching for this database in
+.Xr nscd.conf 5 .
+If for the particular query
+.Dq cache
+source returns success, no further sources are queried.
+On the other hand, if there are no previously cached data, the
+query result will be placed into the cache right after
+all other sources are processed.
+Note, that
+.Dq cache
+requires
+.Xr nscd 8
+daemon to be running.
 .Ss Compat mode: +/- syntax
 In historical multi-source implementations, the
 .Sq +
@@ -210,7 +264,7 @@ and
 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
+These made sense when the databases were in local files, but do not 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
@@ -224,14 +278,14 @@ source must appear alone for a given database.
 .Ss Default source lists
 If, for any reason,
 .Nm
-doesn't exist, or it has missing or corrupt entries,
+does not 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:
 .Pp
-.Bl -tag -width passwd_compat -compact
+.Bl -tag -width services_compat -compact
 .It Sy Database
 .Sy "Default source list"
 .It group
@@ -239,11 +293,15 @@ compat
 .It group_compat
 nis
 .It hosts
-dns files
+files dns
 .It passwd
 compat
 .It passwd_compat
 nis
+.It services
+compat
+.It services_compat
+nis
 .El
 .Sh FILES
 .Bl -tag -width /etc/nsswitch.conf -compact
@@ -254,7 +312,7 @@ resides in
 .Pa /etc .
 .El
 .Sh EXAMPLES
-To lookup hosts in
+To lookup hosts in cache, then in
 .Pa /etc/hosts
 and then from the DNS, and lookup user information from
 .Tn NIS
@@ -262,7 +320,7 @@ then files, use:
 .Pp
 .Bl -tag -width passwd: -compact
 .It hosts:
-files dns
+cache files dns
 .It passwd:
 nis [notfound=return] files
 .It group:
@@ -271,23 +329,45 @@ nis [notfound=return] files
 .Pp
 The criteria
 .Dq [notfound=return]
-sets a policy of "if the user is notfound in nis, don't try files."
+sets a policy of "if the user is notfound in nis, do not try files."
 This treats nis as the authoritative source of information, except
 when the server is down.
+.Sh NOTES
+If system got compiled with
+.Va WITHOUT_NIS
+you have to remove
+.Sq nis
+entries.
+.Pp
+.Dx Ns 's
+.Lb libc
+provides stubs for compatibility with NSS modules
+written for the
+.Tn GNU
+C Library
+.Nm nsswitch
+interface.
+However, these stubs only support the use of the
+.Dq Li passwd
+and
+.Dq Li group
+databases.
 .Sh SEE ALSO
 .Xr nsdispatch 3 ,
+.Xr nscd.conf 5 ,
 .Xr resolv.conf 5 ,
+.Xr nscd 8 ,
 .Xr named 8 ,
 .Xr ypbind 8
 .Sh HISTORY
 The
 .Nm
 file format first appeared in
-.Fx 5.0 .
+.Dx 2.1 .
 It was imported from the
-.Nx
+.Fx
 Project, where it appeared first in
-.Nx 1.4 .
+.Fx 5.0 .
 .Sh AUTHORS
 Luke Mewburn
 .Aq lukem@netbsd.org