Each line in a PAM configuration file contains a maximum of four columns:

<Type of module> <Control flag> <Module path> <Options>
  

PAM modules are processed as stacks. Different types of modules have different purposes, for example, one module checks the password, another one verifies the location from which the system is accessed, and yet another one reads user-specific settings. PAM knows about four different types of modules:

The second column contains control flags to influence the behavior of the modules started:

The module path does not need to be specified explicitly, as long as the module is located in the default directory /lib/security (for all 64-bit platforms supported by SUSE Linux Enterprise®, the directory is /lib64/security). The fourth column may contain an option for the given module, such as debug (enables debugging) or nullok (allows the use of empty passwords).

To show how the theory behind PAM works, consider the PAM configuration of sshd as a practical example:

#%PAM-1.0
auth     include        common-auth
auth     required       pam_nologin.so
account  include        common-account
password include        common-password
session  include        common-session
# Enable the following line to get resmgr support for
# ssh sessions (see /usr/share/doc/packages/resmgr/README.SuSE)
#session  optional      pam_resmgr.so fake_ttyname

The typical PAM configuration of an application (sshd, in this case) contains four include statements referring to the configuration files of four module types: common-auth, common-account, common-password, and common-session. These four files hold the default configuration for each module type. By including them instead of calling each module separately for each PAM application, automatically get an updated PAM configuration if the administrator changes the defaults. In former times, you had to adjust all configuration files manually for all applications when changes to PAM occurred or a new application was installed. Now the PAM configuration is made with central configuration files and all changes are automatically inherited by the PAM configuration of each service.

The first include file (common-auth) calls two modules of the auth type: pam_env and pam_unix2. See Example 27.2, “Default Configuration for the auth Section”.

auth    required        pam_env.so
auth    required        pam_unix2.so

The first one, pam_env, loads the file /etc/security/pam_env.conf to set the environment variables as specified in this file. This can be used to set the DISPLAY variable to the correct value, because the pam_env module knows about the location from which the login is taking place. The second one, pam_unix2, checks the user's login and password against /etc/passwd and /etc/shadow.

After the modules specified in common-auth have been successfully called, a third module called pam_nologin checks whether the file /etc/nologin exists. If it does, no user other than root may log in. The whole stack of auth modules is processed before sshd gets any feedback about whether the login has succeeded. Given that all modules of the stack have the required control flag, they must all be processed successfully before sshd receives a message about the positive result. If one of the modules is not successful, the entire module stack is still processed and only then is sshd notified about the negative result.

As soon as all modules of the auth type have been successfully processed, another include statement is processed, in this case, that in Example 27.3, “Default Configuration for the account Section”. common-account contains just one module, pam_unix2. If pam_unix2 returns the result that the user exists, sshd receives a message announcing this success and the next stack of modules (password) is processed, shown in Example 27.4, “Default Configuration for the password Section”.

account required        pam_unix2.so

password required       pam_pwcheck.so  nullok
password required       pam_unix2.so    nullok use_first_pass use_authtok
#password required      pam_make.so     /var/yp

Again, the PAM configuration of sshd involves just an include statement referring to the default configuration for password modules located in common-password. These modules must successfully be completed (control flag required) whenever the application requests the change of an authentication token. Changing a password or another authentication token requires a security check. This is achieved with the pam_pwcheck module. The pam_unix2 module used afterwards carries over any old and new passwords from pam_pwcheck, so the user does not need to authenticate again. This also makes it impossible to circumvent the checks carried out by pam_pwcheck. The modules of the password type should be used wherever the preceding modules of the account or the auth type are configured to complain about an expired password.

session required        pam_limits.so
session required        pam_unix2.so
session optional        pam_umask.so

As the final step, the modules of the session type, bundled in the common-session file are called to configure the session according to the settings for the user in question. Although pam_unix2 is processed again, it has no practical consequences due to its none option specified in the respective configuration file of this module, pam_unix2.conf. The pam_limits module loads the file /etc/security/limits.conf, which may define limits on the use of certain system resources. The session modules are called a second time when the user logs out.

Some of the PAM modules are configurable. The corresponding configuration files are located in /etc/security. This section briefly describes the configuration files relevant to the sshd example—pam_unix2.conf, pam_env.conf, pam_pwcheck.conf, and limits.conf.

auth:   nullok
account:
password:       nullok
session:        none

VARIABLE  [DEFAULT=[value]]  [OVERRIDE=[value]]

REMOTEHOST     DEFAULT=localhost OVERRIDE=@{PAM_RHOST}
DISPLAY        DEFAULT=${REMOTEHOST}:0.0 OVERRIDE=${DISPLAY}

password:    nullok

In the directory /usr/share/doc/packages/pam of your installed system, find the following additional documentation: