NOTE: CentOS Enterprise Linux is built from the Red Hat Enterprise Linux source code. Other than logo and name changes CentOS Enterprise Linux is compatible with the equivalent Red Hat version. This document applies equally to both Red Hat and CentOS Enterprise Linux.
Each PAM configuration file contains a group of directives
formatted as follows:
<module interface> <control flag> <module name> <module arguments>
Each of these elements are explained in the subsequent
There are four types of PAM module interfaces which correlate to
different aspects of the authorization process:
auth — This module interface
authenticates use. For example, it asks for and verifies the
validity of a password. Modules with this interface can also set
credentials, such as group memberships or Kerberos tickets.
account — This module interface
verifies that access is allowed. For example, it may check if a
user account is expired or is allowed to log in at a particular
time of day.
password — This module interface
sets and verifies passwords.
session — This module interface
configures and manages user sessions. Modules with this interface
can also perform additional tasks that are needed to allow access,
like mounting a user's home directory and making the user's mailbox
An individual module can provide any or all module interfaces.
For instance, pam_unix.so provides all
four module interfaces.
In a PAM configuration file, the module interface is the first
field defined. For example, a typical line in a configuration may
look like this:
auth required pam_unix.so
This instructs PAM to use the pam_unix.so module's auth
Module interface directives can be stacked, or placed upon one another, so that
multiple modules are used together for one purpose. For this
reason, the order in which the modules are listed is very important
to the authentication process.
Stacking makes it very easy for an administrator to require
specific conditions to exist before allowing the user to
authenticate. For example, rlogin normally
uses five stacked auth modules, as seen in
its PAM configuration file:
auth required pam_nologin.so
auth required pam_securetty.so
auth required pam_env.so
auth sufficient pam_rhosts_auth.so
auth required pam_stack.so service=system-auth
Before someone is allowed to use rlogin, PAM verifies that the /etc/nologin file does not exist, that they are not
trying to log in remotely as a root user over a network connection,
and that any environmental variables can be loaded. Then, if a
successful rhosts authentication is
performed, the connection is allowed. If the rhosts authentication fails, then standard password
authentication is performed.
All PAM modules generate a success or failure result when
called. Control flags tell PAM what do with the result. Since
modules can be stacked in a particular order, control flags decide
how important the success or failure of a particular module is to
the overall goal of authenticating the user to the service.
There are four predefined control flags:
required — The module result must
be successful for authentication to continue. If a required module result fails, the user is not
notified until results on all modules referencing that interface
requisite — The module result
must be successful for authentication to continue. However, if a
requisite module result fails, the user is
notified immediately with a message reflecting the first failed
sufficient — The module result is
ignored if it fails. However, if a sufficient flagged module result is successful
and no required
flagged modules above it have failed, then no other results are
required and the user is authenticated to the service.
optional — The module result is
ignored. A module flagged as optional only
becomes necessary for successful authentication when there are no
other modules referencing the interface.
The order in which required modules are
called is not critical. The sufficient and
requisite control flags cause order to
A newer control flag syntax which allows for more precise
control is now available for PAM. Please see the PAM documentation
located in the /usr/share/doc/pam-<version-number>/ directory for
information on this new syntax (where <version-number> is the version number
The module name provides PAM the name of the pluggable module
containing the specified module interface. Under older versions of
Red Hat Enterprise Linux, the full path to the module was provided
within the PAM configuration file, such as /lib/security/pam_stack.so. However, since the
advent of multilib systems, which store 64-bit PAM modules within
the /lib64/security/ directory, the
directory name is omitted because the application is linked to the
appropriate version of libpam, which can
locate the correct version of the module.
PAM uses arguments to pass information to a pluggable module
during authentication for some modules.
For example, the pam_userdb.so module
uses secrets stored in a Berkeley DB file to authenticate the user.
Berkeley DB is an open source database system embedded in many
applications. The module takes a db
argument so that Berkeley DB knows which database to use for the
A typical pam_userdb.so line within a
PAM configuration file looks like this:
auth required pam_userdb.so db=<path-to-file>
In the previous example, replace <path-to-file> with the full path to the
Berkeley DB database file.
Invalid arguments are ignored and do not otherwise affect the
success or failure of the PAM module. However, most modules report
errors to the /var/log/messages file.