PAM(8) Linux-PAM Manual PAM(8)NAME
Linux-PAM - Pluggable Authentication Modules for Linux
SYNOPSIS
/etc/pam.conf
DESCRIPTION
This manual is intended to offer a quick introduction to
Linux-PAM. For more information the reader is directed to
the Linux-PAM system administrators' guide.
Linux-PAM Is a system of libraries that handle the authen-
tication tasks of applications (services) on the system.
The library provides a stable general interface (Applica-
tion Programming Interface - API) that privilege granting
programs (such as login(1) and su(1)) defer to to perform
standard authentication tasks.
The principal feature of the PAM approach is that the
nature of the authentication is dynamically configurable.
In other words, the system administrator is free to choose
how individual service-providing applications will authen-
ticate users. This dynamic configuration is set by the
contents of the single Linux-PAM configuration file
/etc/pam.conf. Alternatively, the configuration can be
set by individual configuration files located in the
/usr/freeware/etc/pam.d/ directory. The presence of this
directory will cause Linux-PAM to ignore /etc/pam.conf.
From the point of view of the system administrator, for
whom this manual is provided, it is not of primary impor-
tance to understand the internal behavior of the Linux-PAM
library. The important point to recognize is that the
configuration file(s) define the connection between appli-
cations (services) and the pluggable authentication mod-
ules (PAMs) that perform the actual authentication tasks.
Linux-PAM separates the tasks of authentication into four
independent management groups: account management; authen-
tication management; password management; and session man-
agement. (We highlight the abbreviations used for these
groups in the configuration file.)
Simply put, these groups take care of different aspects of
a typical user's request for a restricted service:
account - provide account verification types of service:
has the user's password expired?; is this user permitted
access to the requested service?
authentication - establish the user is who they claim to
be. Typically this is via some challenge-response request
that the user must satisfy: if you are who you claim to be
please enter your password. Not all authentications are
of this type, there exist hardware based authentication
schemes (such as the use of smart-cards and biometric
devices), with suitable modules, these may be substituted
seamlessly for more standard approaches to authentication
- such is the flexibility of Linux-PAM.
password - this group's responsibility is the task of
updating authentication mechanisms. Typically, such ser-
vices are strongly coupled to those of the auth group.
Some authentication mechanisms lend themselves well to
being updated with such a function. Standard UN*X pass-
word-based access is the obvious example: please enter a
replacement password.
session - this group of tasks cover things that should be
done prior to a service being given and after it is with-
drawn. Such tasks include the maintenance of audit trails
and the mounting of the user's home directory. The session
management group is important as it provides both an open-
ing and closing hook for modules to affect the services
available to a user.
The configuration file(s)
When a Linux-PAM aware privilege granting application is
started, it activates its attachment to the PAM-API. This
activation performs a number of tasks, the most important
being the reading of the configuration file(s): /usr/free-
ware/etc/pam.conf. Alternatively, this may be the con-
tents of the /usr/freeware/etc/pam.d/ directory.
These files list the PAMs that will do the authentication
tasks required by this service, and the appropriate behav-
ior of the PAM-API in the event that individual PAMs fail.
The syntax of the /usr/freeware/etc/pam.conf configuration
file is as follows. The file is made up of a list of
rules, each rule is typically placed on a single line, but
may be extended with an escaped end of line: `\<LF>'. Com-
ments are preceded with `#' marks and extend to the next
end of line.
The format of each rule is a space separated collection of
tokens, the first three being case-insensitive:
service type control module-path module-arguments
The syntax of files contained in the /usr/free-
ware/etc/pam.d/ directory, are identical except for the
absence of any service field. In this case, the service is
the name of the file in the /usr/freeware/etc/pam.d/
directory. This filename must be in lower case.
An important feature of Linux-PAM, is that a number of
rules may be stacked to combine the services of a number
of PAMs for a given authentication task.
The service is typically the familiar name of the corre-
sponding application: login and su are good examples. The
service-name, other, is reserved for giving default rules.
Only lines that mention the current service (or in the
absence of such, the other entries) will be associated
with the given service-application.
The type is the management group that the rule corresponds
to. It is used to specify which of the management groups
the subsequent module is to be associated with. Valid
entries are: account; auth; password; and session. The
meaning of each of these tokens was explained above.
The third field, control, indicates the behavior of the
PAM-API should the module fail to succeed in its authenti-
cation task. There are two types of syntax for this con-
trol field: the simple one has a single simple keyword;
the more complicated one involves a square-bracketed
selection of value=action pairs.
For the simple (historical) syntax valid control values
are: requisite - failure of such a PAM results in the
immediate termination of the authentication process;
required - failure of such a PAM will ultimately lead to
the PAM-API returning failure but only after the remaining
stacked modules (for this service and type) have been
invoked; sufficient - success of such a module is enough
to satisfy the authentication requirements of the stack of
modules (if a prior required module has failed the success
of this one is ignored); optional - the success or failure
of this module is only important if it is the only module
in the stack associated with this service+type.
For the more complicated syntax valid control values have
the following form:
[value1=action1value2=action2...]
Where valueN corresponds to the return code from the func-
tion invoked in the module for which the line is defined.
It is selected from one of these: success; open_err; sym-
bol_err; service_err; system_err; buf_err; perm_denied;
auth_err; cred_insufficient; authinfo_unavail;
user_unknown; maxtries; new_authtok_reqd; acct_expired;
session_err; cred_unavail; cred_expired; cred_err; no_mod-
ule_data; conv_err; authtok_err; authtok_recover_err;
authtok_lock_busy; authtok_disable_aging; try_again;
ignore; abort; authtok_expired; module_unknown; bad_item;
and default. The last of these, default, implies 'all
valueN's not mentioned explicitly. Note, the full list of
PAM errors is available in /usr/include/secu-
rity/_pam_types.h . The actionN can be: an unsigned inte-
ger, J, signifying an action of 'jump over the next J mod-
ules in the stack'; or take one of the following forms:
ignore - when used with a stack of modules, the module's
return status will not contribute to the return code the
application obtains;
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 stack.
die - equivalent to bad with the side effect of terminat-
ing the module stack and PAM immediately returning to the
application.
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 for-
mer state of the stack would lead to a return of PAM_SUC-
CESS, 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.
done - equivalent to ok with the side effect of terminat-
ing the module stack and PAM immediately returning to the
application.
reset - clear all memory of the state of the module stack
and start again with the next stacked module.
module-path - 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:
/lib/security/.
module-arguments - these are a space separated list of
tokens that can be used to modify the specific behavior of
the given PAM. Such arguments will be documented for each
individual module.
FILES
/usr/freeware/etc/pam.conf - the configuration file
/usr/freeware/etc/pam.d/ - the Linux-PAM configuration
directory. Generally, if this directory is present, the
/etc/pam.conf file is ignored.
/lib/libpam.so.X - the dynamic library
/lib/security/*.so - the PAMs
ERRORS
Typically errors generated by the Linux-PAM system of
libraries, will be written to syslog(3).
CONFORMING TO
DCE-RFC 86.0, October 1995.
Contains additional features, but remains backwardly com-
patible with this RFC.
BUGS
None known.
SEE ALSO
The three Linux-PAM Guides, for system administrators,
module developers, and application developers.
Linux-PAM 0.74 2001 Jan 20 PAM(8)
