Simplified pam.conf Configuration File

The pam.conf file contains a listing of services. Each service is paired with a corresponding service module. When a service is requested, its associated module is invoked. Each entry may be a maximum of 256 characters, including the end of line, and has the following format:

service_name module_type control_flag module_path options

The following is an example of a pam.conf configuration file with support for authentication, account management, session management and password management modules (See the pam.conf file that is shipped with your system for the contents of this file):

login   auth requisite          pam_authtok_get.so.1
login   auth required           pam_dhkeys.so.1
login   auth required           pam_unix_auth.so.1
login   auth required           pam_dial_auth.so.1
other   account requisite       pam_roles.so.1
other   account required        pam_unix_account.so.1
other   session required        pam_unix_session.so.1
other   password required       pam_dhkeys.so.1
other   password requisite      pam_authtok_get.so.1
other   password requisite      pam_authtok_check.so.1
other   password required       pam_authtok_store.so.1

service_name denotes the service (for example, login, dtlogin, or rlogin).

The keyword, "other," indicates the module that all other applications which have not been specified should use. The "other" keyword can also be used if all services of the same module_type have the same requirements.

In the example, since all of the services use the same session module, they could have been replaced by a single other line.

module_type denotes the service module type: authentication (auth), account management (account), session management (session), or password management (password).

The control_flag field determines the behavior of stacking.

The module_path field specifies the relative pathname to a shared library object, or an included PAM configuration file, which implements the service functionality. If the pathname is not absolute, shared library objects are assumed to be relative to /usr/lib/security/$ISA/, and included PAM configuration files are assumed to be relative to /usr/lib/security/.

The ISA token is replaced by an implementation defined directory name which defines the path relative to the calling program's instruction set architecture.

The options field is used by the PAM framework layer to pass module specific options to the modules. It is up to the module to parse and interpret the options.

This field can be used by the modules to turn on debugging or to pass any module specific parameters such as a TIMEOUT value. The options supported by the modules are documented in their respective manual pages.

Integrating Multiple Authentication Services With Stacking

When a service_name of the same module_type is defined more than once, the service is said to be stacked. Each module referenced in the module_path for that service is then processed in the order that it occurs in the configuration file. The control_flag field specifies the continuation and failure semantics of the modules, and can contain one of the following values:

binding

include

optional

required

requisite

sufficient

If the PAM stack runs to completion, that is, neither a requisite module failed, nor a binding or sufficient module success stops it, success is returned if no required modules failed and at least one required, requisite, optional module succeeded. If no module succeeded and a required or binding module failed, the first of those errors is returned. If no required or binding module failed and an optional module failed, the first of the option module errors is returned. If no module in the stack succeeded or failed, that is, all modules returned an ignore status, a default error based on module type, for example, "User account expired," is returned.

All errors in pam.conf entries are logged to syslog as LOG_AUTH | LOG_ERR errors. The use of a service with an error noted in the pam.conf entry for that service will fail. The system administrator will need to correct the noted errors before that service may be used. If no services are available or the pam.conf file is missing, the system administrator may enter system maintenance mode to correct or restore the file.

The following is a sample configuration file that stacks the su, login, and rlogin services.

su     auth required       pam_inhouse.so.1
su     auth requisite      pam_authtok_get.so.1
su     auth required       pam_dhkeys.so.1
su     auth required       pam_unix_auth.so.1
login   auth requisite     pam_authtok_get.so.1
login   auth required      pam_dhkeys.so.1
login   auth required      pam_unix_auth.so.1
login   auth required      pam_dial_auth.so.1
login   auth optional      pam_inhouse.so.1
rlogin  auth sufficient    pam_rhosts_auth.so.1
rlogin  auth requisite     pam_authtok_get.so.1
rlogin  auth required      pam_dhkeys.so.1
rlogin  auth required      pam_unix_auth.so.1

In the case of su, the user is authenticated by the inhouse and authtok_get, dhkeys, and unix_auth authentication modules. Because the inhouse and the other authentication modules are required and requisite, respectively, an error is returned back to the application if any module fails. In addition, if the requisite authentication (pam_authtok_get authentication) fails, the other authentication modules are never invoked, and the error is returned immediately back to the application.

In the case of login, the required keyword for control_flag requires that the user be allowed to login only if the user is authenticated by all the service modules. If pam_unix_auth authentication fails, control continues to proceed down the stack, and the inhouse authentication module is invoked. inhouse authentication is optional by virtue of the optional keyword in the control_flag field. The user can still log in even if inhouse authentication fails, assuming the modules stacked above succeeded.

In the case of rlogin, the sufficient keyword for control_flag specifies that if the rhosts authentication check succeeds, then PAM should return success to rlogin and rlogin should not prompt the user for a password. The other authentication modules, which are in the stack, will only be invoked if the rhosts check fails. This gives the system administrator the flexibility to determine if rhosts alone is sufficient enough to authenticate a remote user.

Some modules return PAM_IGNORE in certain situations. In these cases the PAM framework ignores the entire entry in pam.conf regardless of whether or not it is binding, requisite, required, optional, or sufficient.

Utilities and Files

The specific service names and module types for each service should be documented in the man page for that service. For instance, the sshd(8) man page lists all of the PAM service names and module types for the sshd command.

The PAM configuration file does not dictate either the name or the location of the service specific modules. The convention, however, is the following:

pam_module_name.so.x

/etc/pam.conf

/usr/lib/$ISA/libpam.so.1