diff options
authorAndrew G. Morgan <>2001-01-20 23:47:07 +0000
committerAndrew G. Morgan <>2001-01-20 23:47:07 +0000
commit4d9f3d697d885df9a0696fc6fd3e097fd6608f83 (patch)
parent5416534f049a8639c69faaa42db9d1cc47bb775b (diff)
Relevant BUGIDs: 127625
Purpose of commit: documentation Commit summary: --------------- added a note to this man page explaining that we do support a default directory for modules. Also added some text describing the alternative control syntax for pam configuration files.
2 files changed, 109 insertions, 16 deletions
index dec92f0e..4507d587 100644
@@ -35,6 +35,9 @@ Where you should replace XXXXX with a bug-id.
0.74: please submit patches for this section with actual code/doc
+* pam.8 manual page clarified with respect to the default location for
+ finding modules, also added some text describing the [...] control
+ syntax. (Bug 127625 - agmorgan)
* md5.h ia64 fixes for pam_unix and pam_pwdb (Bug 127700 - agmorgan)
* removed requirement for c++ from the configure{.in,} files (Bug
128298 - agmorgan)
diff --git a/doc/man/pam.8 b/doc/man/pam.8
index 68280737..939a0fe9 100644
--- a/doc/man/pam.8
+++ b/doc/man/pam.8
@@ -1,7 +1,7 @@
.\" Hey Emacs! This file is -*- nroff -*- source.
.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996-7 <>
-.TH PAM 8 "1997 Feb 9" "Linux-PAM 0.56" "Linux-PAM Manual"
+.\" Copyright (c) Andrew G. Morgan 1996-7,2001 <>
+.TH PAM 8 "2001 Jan 20" "Linux-PAM 0.74" "Linux-PAM Manual"
Linux-PAM \- Pluggable Authentication Modules for Linux
@@ -197,7 +197,14 @@ The meaning of each of these tokens was explained above.
The third field,
.BR control ", "
indicates the behavior of the PAM-API should the module fail to
-succeed in its authentication task. Valid
+succeed in its authentication task. There are two types of syntax for
+this control field: the simple one has a single simple keyword; the
+more complicated one involves a square-bracketed selection of
+.B value=action
+For the simple (historical) syntax valid
.BR control
values are:
.BR requisite
@@ -224,8 +231,97 @@ only module in the stack associated with this
.BR service "+" type "."
+For the more complicated syntax valid
+.B control
+values have the following form:
+.RB [value1=action1 value2=action2 ...]
+.B valueN
+corresponds to the return code from the function invoked in the module
+for which the line is defined. It is selected from one of these:
+.BR success ;
+.BR open_err ;
+.BR symbol_err ;
+.BR service_err ;
+.BR system_err ;
+.BR buf_err ;
+.BR perm_denied ;
+.BR auth_err ;
+.BR cred_insufficient ;
+.BR authinfo_unavail ;
+.BR user_unknown ;
+.BR maxtries ;
+.BR new_authtok_reqd ;
+.BR acct_expired ;
+.BR session_err ;
+.BR cred_unavail ;
+.BR cred_expired ;
+.BR cred_err ;
+.BR no_module_data ;
+.BR conv_err ;
+.BR authtok_err ;
+.BR authtok_recover_err ;
+.BR authtok_lock_busy ;
+.BR authtok_disable_aging ;
+.BR try_again ;
+.BR ignore ;
+.BR abort ;
+.BR authtok_expired ;
+.BR module_unknown ;
+.BR bad_item "; and"
+.BR default .
+The last of these,
+.BR default ,
+implies 'all
+.BR valueN 's
+not mentioned explicitly. Note, the full list of PAM errors is
+available in /usr/include/security/_pam_types.h . The
+.B actionN
+can be: an unsigned integer,
+.BR J ,
+signifying an action of 'jump over the next J modules in the stack';
+or take one of the following forms:
+.B ignore
+- when used with a stack of modules, the module's return status will
+not contribute to the return code the application obtains;
+.B bad
+- this action indicates that the return code should be thought of as
+indicative of the module failing. If this module is the first in the
+stack to fail, its status value will be used for that of the whole
+.B die
+- equivalent to bad with the side effect of terminating the module
+stack and PAM immediately returning to the application.
+.B ok
+- this tells PAM that the administrator thinks this return code
+should contribute directly to the return code of the full stack of
+modules. In other words, if the former state of the stack would lead
+to a return of
+the module's return code will override this value. Note, if the former
+state of the stack holds some value that is indicative of a modules
+failure, this 'ok' value will not be used to override that value.
+.B done
+- equivalent to ok with the side effect of terminating the module
+stack and PAM immediately returning to the application.
+.B reset
+- clear all memory of the state of the module stack and start again
+with the next stacked module.
.BR module-path
-- this is the full filename of the PAM to be used by the application
+- this is either the full filename of the PAM to be used by the
+application (it begins with a '/'), or a relative pathname from the
+default module location:
+.BR /lib/security/ .
.BR module-arguments
@@ -238,19 +334,13 @@ documented for each individual module.
.BR /etc/pam.d/ " - the"
.BR Linux-PAM
-configuration directory. If this directory is present, the
+configuration directory. Generally, if this directory is present, the
.B /etc/pam.conf
file is ignored.
-.BR /usr/lib/ " - the dynamic library"
+.BR /lib/ " - the dynamic library"
-.BR /usr/lib/security/*.so " - the PAMs
-Note, to conform to the Linux File-system standard, the libraries and
-modules in your system may be located in
-.BR /lib " and " /lib/security
+.BR /lib/security/*.so " - the PAMs
Typically errors generated by the
@@ -261,8 +351,8 @@ system of libraries, will be written to
DCE-RFC 86.0, October 1995.
-Contains additional features, currently under consideration by the
-DCE-RFC committee.
+Contains additional features, but remains backwardly compatible with
+this RFC.
.sp 2
@@ -273,7 +363,7 @@ None known.
The three
.BR Linux-PAM
Guides, for
-.BR "System administrators" ", "
+.BR "system administrators" ", "
.BR "module developers" ", "
.BR "application developers" ". "