22.7.1 Configuring Pluggable Authentication Modules

Each PAM configuration file contains a list (stack) of calls to authentication modules. For example, the following is the content of the login configuration file:

auth [user_unknown=ignore success=ok ignore=ignore default=bad] pam_securetty.so
auth       include      system-auth
account    required     pam_nologin.so
account    include      system-auth
password   include      system-auth
# pam_selinux.so close should be the first session rule
session    required     pam_selinux.so close
session    required     pam_loginuid.so
session    optional     pam_console.so
# pam_selinux.so open should only be followed by sessions to be executed in the user context
session    required     pam_selinux.so open
session    required     pam_namespace.so
session    optional     pam_keyinit.so force revoke
session    include      system-auth
-session   optional     pam_ck_connector.so

Comments in the file start with a # character. The remaining lines each define an operation type, a control flag, the name of a module such as pam_rootok.so or the name of an included configuration file such as system-auth, and any arguments to the module. PAM provides authentication modules as 32 and 64-bit shared libraries in /lib/security and /lib64/security respectively.

For a particular operation type, PAM reads the stack from top to bottom and calls the modules listed in the configuration file. Each module generates a success or failure result when called.

The following operation types are defined for use:


The module tests whether a user is authenticated or authorized to use a service or application. For example, the module might request and verify a password. Such modules can also set credentials, such as a group membership or a Kerberos ticket.


The module tests whether an authenticated user is allowed access to a service or application. For example, the module might check if a user account has expired or if a user is allowed to use a service at a given time.


The module handles updates to an authentication token.


The module configures and manages user sessions, performing tasks such as mounting or unmounting a user's home directory.

If the operation type is preceded with a dash (-), PAM does not add an create a system log entry if the module is missing.

With the exception of include, the control flags tell PAM what to do with the result of running a module. The following control flags are defined for use:


The module is required for authentication if it is the only module listed for a service.


The module must succeed for access to be granted. PAM continues to execute the remaining modules in the stack whether the module succeeds or fails. PAM does not immediately inform the user of the failure.


The module must succeed for access to be granted. If the module succeeds, PAM continues to execute the remaining modules in the stack. However, if the module fails, PAM notifies the user immediately and does not continue to execute the remaining modules in the stack.


If the module succeeds, PAM does not process any remaining modules of the same operation type. If the module fails, PAM processes the remaining modules of the same operation type to determine overall success or failure.

The control flag field can also define one or more rules that specify the action that PAM should take depending on the value that a module returns. Each rule takes the form value=action, and the rules are enclosed in square brackets, for example:

[user_unknown=ignore success=ok ignore=ignore default=bad]

If the result returned by a module matches a value, PAM uses the corresponding action, or, if there is no match, it uses the default action.

The include flag specifies that PAM must also consult the PAM configuration file specified as the argument.

Most authentication modules and PAM configuration files have their own manual pages. In addition, the /usr/share/doc/pam-version directory contains the PAM System Administrator’s Guide (html/Linux-PAM_SAG.html or Linux-PAM_SAG.txt) and a copy of the PAM standard (rfc86.0.txt).

For more information, see the pam(8) manual page. In addition, each PAM module has its own manual page, for example pam_unix(8).