Go to main content

man pages section 5: File Formats

Exit Print View

Updated: Thursday, June 13, 2019
 
 

pam.d(5)

Name

pam.conf, pam.d - configuration file for pluggable authentication modules

Synopsis

/etc/pam.conf
/etc/pam.d/service

Description

pam.conf is the traditional configuration file for the Pluggable Authentication Module architecture, or PAM. Per-service policy files in /etc/pam.d/ provide an alternate and preferred configuration mechanism for PAM.

The PAM library (libpam(3LIB)) looks for the PAM configuration in the following files in the order listed:

  1. /etc/pam.conf for the current PAM service name

  2. /etc/pam.d/service for the current PAM service name

  3. /etc/pam.conf for the PAM service name of “other”

  4. /etc/pam.d/other

A PAM module provides functionality for one or more of four possible services: authentication, account management, session management, and password management.

authentication service module

Provides functionality to authenticate a user and set up user credentials.

account management module

Provides functionality to determine if the current user's account is valid. This includes checking for password and account expiration, as well as verifying access hour restrictions.

session management module

Provides functionality to set up and terminate login sessions.

password management module

Provides functionality to change a user's authentication token or password.

Each of the four service modules can be implemented as a shared library object which can be referenced in the pam.conf configuration file or a per-service PAM configuration file in /etc/pam.d/.

PAM Configuration File Syntax

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 must be one of the following two formats:

service_name module_type control_flag module_path options
service_name module_type include path-to-included-PAM-configuration

The per-service policy files in /etc/pam.d/ have almost the same syntax as pam.conf; however they contain only four fields rather than the five in pam.conf: the service_name field is not present. The service_name is instead taken from the name of the policy file in /etc/pam.d/. The two allowed formats for entries in the per-service policy files are:

module_type control_flag module_path options
module_type include path-to-included-PAM-configuration

The PAM configuration file included using the include mechanism can be in any of the four formats listed above.

In both types of PAM policy files blank lines and lines beginning with a '#' sign are ignored.

The following is an example of a pam.conf configuration file with support for authentication, account management, session management and password management modules:

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

The equivalent PAM configuration in /etc/pam.d/ would be the following entries in /etc/pam.d/login:

auth requisite	       pam_authtok_get.so.1
auth required	       pam_dhkeys.so.1
auth required	       pam_unix_auth.so.1
auth required	       pam_dial_auth.so.1

and the following entries in /etc/pam.d/other:

account requisite       pam_roles.so.1
account required	    pam_unix_account.so.1

session required	    pam_unix_session.so.1

password	required       pam_dhkeys.so.1
password	requisite      pam_authtok_get.so.1
password	requisite      pam_authtok_check.so.1
password	required       pam_authtok_store.so.1

service_name denotes the service (for example, login, gdm, 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.

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

If the service module returns success and no preceding required modules returned failures, immediately return success without calling any subsequent modules. If a failure is returned, treat the failure as a required module failure, and continue to process the PAM stack.

definitive

If the service module returns success and no preceding required modules return failures, immediately return success without calling any subsequent modules. If a failure is returned, immediately return the first non-optional failure value recorded without calling any subsequent modules. That is, return this failure unless a previous required service module failed. If a previous required service module failed, then return the first of those values.

include

Process the lines from the PAM configuration file that is specified in the module_path at this point in the PAM stack. The ``other'' keyword is used if the specified service_name is not found. 32 levels of included PAM configuration files are supported. Any options are ignored.

optional

If the service module returns success, record the success, and continue to process the PAM stack. If a failure is returned, and it is the first optional module failure, save the failure code as an optional failure. Continue to process the PAM stack.

required

If the service module returns success, record the success, and continue to process the PAM stack. If a failure is returned, and it is the first required failure, save the failure code as a required failure. Continue to process the PAM stack.

requisite

If the service module returns success, record the success, and continue to process the PAM stack. If a failure is returned, immediately return the first non-optional failure value recorded without calling any subsequent modules. That is, return this failure unless a previous required service module failed. If a previous required service module failed, then returns the first of those values.

sufficient

If the service module return success and no preceding required modules returned failures, immediately return success without calling any subsequent modules. If a failure is returned, treat the failure as an optional module failure, and continue to process the PAM stack.

Stacked PAM services results are returned as follows:

  • If a requisite, binding, sufficient, or definitive module causes processing to complete early, that result is returned.

  • Otherwise, if a required module fails, the first such failure is returned.

  • Otherwise, if any module succeeds, success is returned.

  • Otherwise, if an optional module fails, the first such failure is returned.

  • Otherwise, a default error based on module type is returned.

All errors in pam.conf entries or the per-service policy files in /etc/pam.d/ 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 any noted errors before the configured PAM configuration may be used. If no applicable services are found in the pam.conf file or the per-service /etc/pam.d/ files, the system administrator may enter system maintenance mode to correct or restore the PAM configuration.

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

The equivalent PAM configuration in /etc/pam.d/ would be the following entries in /etc/pam.d/su:

auth required	   pam_inhouse.so.1
auth requisite	   pam_authtok_get.so.1
auth required     pam_dhkeys.so.1
auth required     pam_unix_auth.so.1

the following entries in /etc/pam.d/login:

auth requisite    pam_authtok_get.so.1
auth required     pam_dhkeys.so.1
auth required     pam_unix_auth.so.1
auth required     pam_dial_auth.so.1
auth optional     pam_inhouse.so.1

and the following entries in /etc/pam.d/rlogin:

auth sufficient   pam_rhosts_auth.so.1
auth requisite    pam_authtok_get.so.1
auth required     pam_dhkeys.so.1
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, definitive, 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

File that implements various function of specific authentication services. As the relative pathname specified, /usr/lib/security/$ISA is prepended to it.

/etc/pam.conf

Traditional PAM configuration file

/etc/pam.d/service

Alternate PAM configuration files

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

File that implements the PAM framework library

Examples

Example 1 Using the include control flag

The following example collects the common Unix modules into a single file to be included as needed in the example of a pam.conf file. The common Unix module file is named unix_common and consists of:

OTHER   auth requisite          pam_authtok_get.so.1
OTHER   auth required           pam_dhkeys.so.1
OTHER   auth required           pam_unix_auth.so.1
OTHER   auth required           pam_unix_cred.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

The pam.conf file consists of:

# Authentication management
#
# login service (explicit because of pam_dial_auth)
#
login   auth include            unix_common
login   auth required           pam_dial_auth.so.1
#
# rlogin service (explicit because of pam_rhost_auth)
#
rlogin  auth sufficient         pam_rhosts_auth.so.1
rlogin  auth include            unix_common
#
# Default definitions for Authentication management
# Used when service name is not explicitly mentioned
#
OTHER   auth include            unix_common
#
# Default definition for Account management
# Used when service name is not explicitly mentioned
#
OTHER   account include	     unix_common
#
# Default definition for Session management
# Used when service name is not explicitly mentioned
#
OTHER   session include         unix_common
#
# Default definition for  Password management
# Used when service name is not explicitly mentioned
#
OTHER   password include        unix_common

The equivalent PAM configuration in /etc/pam.d/ would be the following entries in /etc/pam.d/login:

# Authentication        management
#
# login service (explicit because of pam_dial_auth)
#
auth include           unix_common
auth required          pam_dial_auth.so.1

the following entries in /etc/pam.d/rlogin:

#
# rlogin        service (explicit because of pam_rhost_auth)
#
auth sufficient        pam_rhosts_auth.so.1
auth include           unix_common

and the following entries in /etc/pam.d/OTHER:

#
# Default definitions for Authentication        management
# Used when service name        is not explicitly mentioned
#
auth include           unix_common
#
# Default definition for        Account management
# Used when service name        is not explicitly mentioned
#
account include      unix_common
#
# Default definition for        Session management
# Used when service name        is not explicitly mentioned
#
session include        unix_common
#
# Default definition for         Password management
# Used when service name        is not explicitly mentioned
#
password        include        unix_common

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
See Below.

The format is Committed. The contents has no stability attributes.

See Also

login(1), passwd(1), syslog(3C), libpam(3LIB), pam(3PAM), attributes(7), environ(7), pam_authtok_check(7), pam_authtok_get(7), pam_authtok_store(7), pam_dhkeys(7), pam_krb5(7), pam_passwd_auth(7), pam_unix_account(7), pam_unix_auth(7), pam_unix_session(7), in.rlogind(8), in.rshd(8), in.telnetd(8), in.uucpd(8), init(8), rpc.rexd(8), su(8), ttymon(8)

Chapter 1, Using Pluggable Authentication Modules in Managing Authentication in Oracle Solaris 11.4