pam.conf(4)
NAME
pam.conf - configuration file for pluggable authentication
modules
SYNOPSIS
/etc/pam.conf
DESCRIPTION
pam.conf is the configuration file for the Pluggable Authen-
tication Module architecture, or PAM. 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 authentica-
tion 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.
Simplified pam.conf Configuration File
The pam.conf file contains a listing of services. Each ser-
vice 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 the 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_projects.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, dtlo-
gin, or rlogin). The keyword, other, indicates the module
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 ses-
sion 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 which implements the service func-
tionality. If the pathname is not absolute, it is assumed to
be relative to /usr/lib/security/$ISA/.
The ISA token is replaced by an implementation defined
directory name which defines the path relative to the cal-
ling 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. It can also be used to support unified login. 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 pro-
cessed 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.
optional
If the service module returns success, record the suc-
cess, 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 suc-
cess, 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 suc-
cess, 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, record this failure
unless a previous required service module failed. If a
previous required service module failed, then return
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.
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, or 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.
If any entry in pam.conf is incorrect, or if a module does
not exist or cannot be opened, then all PAM services fail
and users are not be permitted access to the system. An
error is logged through syslog(3C) at the LOG_CRIT level. To
fix incorrect entries in pam.conf, a system administrator
can boot the system in maintenance mode (single user) to
edit the file.
The following is a sample configuration file that stacks the
su, login, and rlogin services.
su auth requisite 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 required 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 requisite and required, respectively, an error
is returned back to the application if any module fails. In
addition, if the requisite authentication (inhouse authenti-
cation) fails, the other authentication modules is 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 authtok_get
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 requisite,
required, optional or sufficient.
Utilities and Files
The following is a list of the utilities that use PAM:
login, passwd, su, rlogind, rshd, telnetd, ftpd, rpc.rexd,
uucpd, init, sac, cron, ppp, dtsession, ssh and ttymon.
The utility dtlogin also uses PAM. dtlogin is the login ser-
vice utility for the Common Desktop Environment (CDE).
The PAM configuration file does not dictate either the name
or the location of the service specific modules. The conven-
tion, 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
Configuration file.
/usr/lib/$ISA/libpam.so.1
File that implements the PAM framework library.
EXAMPLES
Example 1: A Sample pam.conf Configuration File
The following is a sample pam.conf configuration file.
Lines that begin with the # symbol are treated as comments,
and therefore ignored.
# PAM configuration
#
# Unless explicitly defined, all services use the modules
# defined in the "other" section.
#
# Modules are defined with relative pathnames, i.e., they are
# relative to /usr/lib/security/$ISA. Absolute path names, as
# present in this file in previous releases are still acceptable.
#
# Authentication management
#
# login service (explicit because of pam_dial_auth)
#
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
#
# rlogin service (explicit because of pam_rhost_auth)
#
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
#
# rsh service (explicit because of pam_rhost_auth)
# and pam_unix_auth for meaningful pam_setcred)
#
rsh auth sufficient pam_rhosts_auth.so.1
rsh auth required pam_unix_auth.so.1
#
# ppp service (explicit because of pam_dial_auth)
#
ppp auth requisite pam_authtok_get.so.1
ppp auth required pam_dhkeys.so.1
ppp auth required pam_unix_auth.so.1
ppp auth required pam_dial_auth.so.1
#
# Default definitions for Authentication management
# Used when service name is not explicitly mentioned for authenctication
#
other auth requisite pam_authtok_get.so.1
other auth required pam_dhkeys.so.1
other auth required pam_unix_auth.so.1
#
# passwd command (explicit because of a different authentication module)
#
passwd auth required pam_passwd_auth.so.1
#
# cron service (explicit because of non-usage of pam_roles.so.1)
#
cron account required pam_projects.so.1
cron account required pam_unix_account.so.1
#
# Default definition for Account management
# Used when service name is not explicitly mentioned for account management
#
other account requisite pam_roles.so.1
other account required pam_projects.so.1
other account required pam_unix_account.so.1
#
# Default definition for Session management
# Used when service name is not explicitly mentioned for session management
#
other session required pam_unix_session.so.1
#
# Default definition for Password management
# Used when service name is not explicitly mentioned for password management
#
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
#
# Support for Kerberos V5 authentication (uncomment to use Kerberos)
#
#rlogin auth optional pam_krb5.so.1 try_first_pass
#login auth optional pam_krb5.so.1 try_first_pass
#other auth optional pam_krb5.so.1 try_first_pass
#cron account optional pam_krb5.so.1
#other account optional pam_krb5.so.1
#other session optional pam_krb5.so.1
#other password optional pam_krb5.so.1 try_first_pass
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT Level | MT-Safe with exceptions |
|_____________________________|_____________________________|
SEE ALSO
login(1), passwd(1), in.ftpd(1M), in.rlogind(1M),
in.rshd(1M), in.telnetd(1M), in.uucpd(1M), init(1M),
rpc.rexd(1M), sac(1M), ttymon(1M), su(1M), pam(3PAM),
syslog(3C), libpam(3LIB), attributes(5), environ(5),
pam_authtok_check(5), pam_authtok_get(5),
pam_authtok_store(5), pam_dhkeys(5), pam_passwd_auth(5),
pam_unix(5), pam_unix_account(5), pam_unix_auth(5),
pam_unix_session(5)
NOTES
The pam_unix(5) module might not be supported in a future
release. Similar functionality is provided by
pam_authtok_check(5), pam_authtok_get(5),
pam_authtok_store(5), pam_dhkeys(5), pam_passwd_auth(5),
pam_unix_account(5), pam_unix_auth(5), and
pam_unix_session(5).
Man(1) output converted with
man2html