[src/trunk]: src Add a pam.conf(5) manual page.

[thorpej <thorpej%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/74a9a22f7d6f
branches:  trunk
changeset: 574620:74a9a22f7d6f
user:      thorpej <thorpej%NetBSD.org@localhost>
date:      Mon Mar 07 02:26:31 2005 +0000

description:
Add a pam.conf(5) manual page.

diffstat:

 distrib/sets/lists/man/mi |    4 +-
 share/man/man5/Makefile   |    4 +-
 share/man/man5/pam.conf.5 |  200 ++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 205 insertions(+), 3 deletions(-)

diffs (247 lines):

diff -r 80558a299f21 -r 74a9a22f7d6f distrib/sets/lists/man/mi
--- a/distrib/sets/lists/man/mi Sun Mar 06 23:40:41 2005 +0000
+++ b/distrib/sets/lists/man/mi Mon Mar 07 02:26:31 2005 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.765 2005/03/02 02:56:24 thorpej Exp $
+# $NetBSD: mi,v 1.766 2005/03/07 02:26:31 thorpej Exp $
 ./etc/mtree/set.man                            man-sys-root
 ./usr/share/info/am-utils.info                 man-amd-info            info
 ./usr/share/info/as.info                       man-computil-info       bfd,info
@@ -1491,6 +1491,7 @@
 ./usr/share/man/cat5/newsyslog.conf.0          man-sysutil-catman      .cat
 ./usr/share/man/cat5/nsswitch.conf.0           man-net-catman          .cat
 ./usr/share/man/cat5/openssl.cnf.0             man-crypto-catman       crypto,.cat
+./usr/share/man/cat5/pam.conf.0                        man-sys-catman          .cat
 ./usr/share/man/cat5/passwd.0                  man-sys-catman          .cat
 ./usr/share/man/cat5/passwd.conf.0             man-sys-catman          .cat
 ./usr/share/man/cat5/pcfs.0                    man-obsolete            obsolete
@@ -3691,6 +3692,7 @@
 ./usr/share/man/man5/newsyslog.conf.5          man-sysutil-man         .man
 ./usr/share/man/man5/nsswitch.conf.5           man-net-man             .man
 ./usr/share/man/man5/openssl.cnf.5             man-crypto-man          crypto,.man
+./usr/share/man/man5/pam.conf.5                        man-sys-man             .man
 ./usr/share/man/man5/passwd.5                  man-sys-man             .man
 ./usr/share/man/man5/passwd.conf.5             man-sys-man             .man
 ./usr/share/man/man5/pcfs.5                    man-obsolete            obsolete
diff -r 80558a299f21 -r 74a9a22f7d6f share/man/man5/Makefile
--- a/share/man/man5/Makefile   Sun Mar 06 23:40:41 2005 +0000
+++ b/share/man/man5/Makefile   Mon Mar 07 02:26:31 2005 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.53 2004/11/14 11:26:45 yamt Exp $
+#      $NetBSD: Makefile,v 1.54 2005/03/07 02:26:32 thorpej Exp $
 #      @(#)Makefile    8.1 (Berkeley) 6/5/93
 
 # missing: dump.5 plot.5
@@ -9,7 +9,7 @@
        ipsec.conf.5 ld.so.conf.5 link.5 lkm.conf.5 locale.alias.5 \
        locate.conf.5 login.conf.5 mixerctl.conf.5 mk.conf.5 monthly.conf.5 \
        motd.5 netconfig.5 netgroup.5 networks.5 \
-       nsswitch.conf.5 passwd.5 passwd.conf.5 phones.5 \
+       nsswitch.conf.5 pam.conf.5 passwd.5 passwd.conf.5 phones.5 \
        printcap.5 protocols.5 ranlib.5 rc.conf.5 remote.5 \
        resolv.conf.5 route.conf.5 rpc.5 \
        security.conf.5 services.5 shells.5 \
diff -r 80558a299f21 -r 74a9a22f7d6f share/man/man5/pam.conf.5
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man5/pam.conf.5 Mon Mar 07 02:26:31 2005 +0000
@@ -0,0 +1,200 @@
+.\"    $NetBSD: pam.conf.5,v 1.1 2005/03/07 02:26:31 thorpej Exp $
+.\"
+.\" Copyright (c) 2005 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Jason R. Thorpe.
+.\"
+.\" 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 the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" 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 March 6, 2005
+.Dt PAM.CONF 5
+.Os
+.Sh NAME
+.Nm pam.conf
+.Nd Pluggable Authentication Modules configuration file
+.Sh DESCRIPTION
+The
+.Nm
+file specifies how Pluggable Authentication Modules
+.Pq PAM
+should operate.
+For an overfiew of the Pluggable Authentication Modules framework, see
+.Xr pam 8 .
+.Pp
+PAM may be configured using a single
+.Pa /etc/pam.conf
+configuration file or by using multiple configuration files, one for each
+PAM-aware service, located in the
+.Pa /etc/pam.d/
+directory.
+If
+.Pa /etc/pam.d/
+exists,
+.Pa /etc/pam.conf
+will be ignored.
+.Pa /etc/pam.d/
+is the preferred method for configuring PAM.
+.Pp
+PAM's configuration is based on
+.Dq stacking
+different modules together to form a processing chain for the task.
+A standard PAM configuration stanza is structured as follows:
+.Bd -offset indent
+.Op Ar service-name
+.Ar module-type
+.Ar control-flag
+.Ar module-name
+.Op Ar options
+.Ed
+.Pp
+.Ar service-name
+is used only
+.Pq and is mandatory
+in
+.Pa /etc/pam.conf .
+It specifies the PAM-aware service whose PAM behavior is being configured.
+When
+.Pa /etc/pam.d/
+is used, the name of the configuration file specifies the service.
+.Pp
+.Ar module-type
+specifies which of the four classes of PAM module functionality is being
+configured.
+These four classes are
+.Em account
+.Pq account management ,
+.Em auth
+.Pq authentication ,
+.Em password
+.Pq password management ,
+and
+.Em session
+.Pq session management .
+.Pp
+.Ar control-flag
+speficies the behavior of the processing chain upon success or failure
+of the PAM module's authentication task.
+The following are valid values for
+.Ar control-flag :
+.Bl -tag -width sufficient
+.It requisite
+If the module returns success, continue to execute the processing chain.
+If the module fails, immediately return the error code from the first
+.Sq required
+failure.
+.It required
+If the module returns success, continue to execute the processing chain.
+If the module fails, record as a
+.Sq required
+failure and continue to execute the processing chain.
+If there are any
+.Sq required
+failures in the processing chain, the chain will ultimately return
+failure.
+.It optional
+If the module returns success, continue to execute the processing chain.
+If the module fails, record as an
+.Sq optional
+failure and continue to execute the processing chain.
+.It sufficient
+If the module returns success and there have been no recorded
+.Sq required
+failures, immediately return success without calling any subsequent
+modules in the processing chain.
+If the module fails, return as an
+.Sq optional
+failure and continue to execute the processing chain.
+.El
+.Pp
+.Ar module-name
+specifies the module to execute for this stanza.
+This is either an absolute path name or a path name relative to the
+default module location:
+.Pa /usr/lib/security .
+.Pp
+.Ar options
+are additional options that may be specified for the module.
+Refer to the individual modules' docuementation for more information
+on available options.
+.Pp
+In addition to the standard configuration stanza format, there an additional
+stanza format availble when
+.Pa /etc/pam.d/
+is in use:
+.Bd -offset indent
+.Ar module-type
+include
+.Ar service-name
+.Ed
+.Pp
+This stanza format provides a simple inheritance model for processing
+chains.
+.Sh FILES
+.Bl -tag -width /etc/pam.conf -compact
+.It Pa /etc/pam.conf
+monolithic PAM configuration file
+.It Pa /etc/pam.d/
+PAM service configuration file directory
+.El
+.Sh EXAMPLES
+The following
+.Em auth
+processing chain for the
+.Dq login
+service
+.Po
+located in
+.Pa /etc/pam.d/login
+.Pc
+performs the following tasks: allows the login if the old user
+and new user are the same, verifies that logins are not disabled using
+the
+.Pa /var/run/nologin
+file, allows Kerberos 5 password authentication, and requires standard
+.Ux
+password authentication if Kerberos 5 failed:
+.Bd -literal
+auth   sufficient      pam_self.so
+auth   required        pam_nologin.so
+auth   sufficient      pam_krb5.so
+auth   required        pam_unix.so
+.Ed
+.Sh SEE ALSO
+.Xr login 1 ,
+.Xr passwd 1 ,
+.Xr su 1 ,
+.Xr pam 3 ,
+.Xr pam 8
+.Sh HISTORY
+The
+.Nm
+file format first appeared in
+.Nx 3.0 .