PAM Configuration File Format

Module Interface

Four types of PAM module interface are currently available. Each of these corresponds to a different aspect of the authorization process:

• auth - This module interface authenticates use. For example, it requests 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 has expired or if a user is allowed to log in at a particular time of day.
• password - This module interface is used for changing user 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 available.

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 interface.

Stacking Module Interfaces

Module interface directives can be stacked, or placed upon one another, so that multiple modules are used together for one purpose. If a module's control flag uses the "sufficient" or "requisite" value (refer to "Control Flag" for more information on these flags), then the order in which the modules are listed is important to the authentication process.

Stacking makes it easy for an administrator to require specific conditions to exist before allowing the user to authenticate. For example, the reboot command normally uses several stacked modules, as seen in its PAM configuration file:

~]# cat /etc/pam.d/reboot
#%PAM-1.0
auth sufficient pam_rootok.so
auth required pam_console.so
#auth include system-auth
account required pam_permit.so

• The first line is a comment and is not processed.

• auth sufficient pam_rootok.so - This line uses the pam_rootok.so module to check whether the current user is root, by verifying that their UID is 0. If this test succeeds, no other modules are consulted and the command is executed. If this test fails, the next module is consulted.
• auth required pam_console.so - This line uses the pam_console.so module to attempt to authenticate the user. If this user is already logged in at the console, pam_console.so checks whether there is a file in the /etc/security/console.apps/ directory with the same name as the service name (reboot). If such a file exists, authentication succeeds and control is passed to the next module.
• #auth include system-auth - This line is commented and is not processed.
• account required pam_permit.so - This line uses the pam_permit.so module to allow the root user or anyone logged in at the console to reboot the system.

Control Flag

All PAM modules generate a success or failure result when called. Control flags tell PAM what do with the result. Modules can be stacked in a particular order, and the control flags determine 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 the test fails at this point, the user is not notified until the results of all module tests that reference that interface are complete.

• requisite - The module result must be successful for authentication to continue. However, if a test fails at this point, the user is notified immediately with a message reflecting the first failed required or requisite module test.
• sufficient - The module result is ignored if it fails. However, if the result of a module flagged sufficient is successful and no previous modules flagged required 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 no other modules reference the interface.

The order in which required modules are called is not critical. Only the sufficient and requisite control flags cause order to become important.

A newer control flag syntax that allows for more precise control is now available for PAM.

The pam.d man page, and the PAM documentation, located in the /usr/share/doc/pam-<version-number>/ directory, where <version-number> is the version number for PAM on your system, describe this newer syntax in detail.

Module Name

The module name provides PAM with the name of the pluggable module containing the specified module interface. In older versions of Community Enterprise Linux, the full path to the module was provided in the PAM configuration file. However, since the advent of multilib systems, which store 64-bit PAM modules in 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.

Module Arguments

PAM uses arguments to pass information to a pluggable module during authentication for some modules.

For example, the pam_userdb.so module uses information 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 requested service.

The following is a typical pam_userdb.so line in a PAM configuration. The <path-to-file> is the full path to the Berkeley DB database file:

auth required pam_userdb.so db=<path-to-file>

Invalid arguments are generally ignored and do not otherwise affect the success or failure of the PAM module. Some modules, however, may fail on invalid arguments. Most modules report errors to the /var/log/secure file.