14.3. PAM Configuration File Format

Each PAM configuration file contains a group of directives formatted as follows:

<module interface>  <control flag>   <module path>   <module arguments>

Each of these elements are explained in the following sections.

14.3.1. Module Interface

There are four types of PAM module interfaces which correlate to different aspects of the authorization process:

NoteNote
 

An individual module can provide any or all module interfaces. For instance, pam_unix.so provides all four 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  /lib/security/pam_unix.so

This instructs PAM to use the pam_unix.so module's auth interface.

14.3.1.1. Stacking Modules

Module interface directives can be stacked, or placed upon one another, so that multiple modules are used together for a 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     /lib/security/pam_nologin.so
auth       required     /lib/security/pam_securetty.so
auth       required     /lib/security/pam_env.so
auth       sufficient   /lib/security/pam_rhosts_auth.so
auth       required     /lib/security/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 an unencrypted 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 a standard password authentication is performed.

14.3.2. Control Flag

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:

ImportantImportant
 

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

A newer control flag syntax which allows for more precise control is now available for PAM. Please see the PAM docs located in the /usr/share/doc/pam-<version-number>/ directory for information on this new syntax (where <version-number> is the version number for PAM).

14.3.3. Module Path

Module paths tell PAM where to find the pluggable module to be used with the module interface specified. Usually, it is provided as the full path to the module, such as /lib/security/pam_stack.so. However, if the full path is not given, then the module indicated is assumed to be in the /lib/security/ directory, the default location for PAM modules.

14.3.4. 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 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 requested service.

A typical pam_userdb.so line within a PAM configuration file looks like this:

auth      required  /lib/security/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 will report an error to the /var/log/messages file.