Red Hat Enterprise Linux Diagnostics and Troubleshooting
Pluggable Authentication Modules (PAM) provide a common interface for applications to authenticate users. Applications call the libpam library to authenticate users with one or more PAM modules. Administrators can use the pluggable aspect of PAM to choose how individual applications authenticate users.
Modules provide different authentication mechanisms. For example, the pam_unix module authenticates users with their passwords. Alternatively, the pam_group module authenticates users with their group memberships.
PAM-enabled applications store configuration files in the /etc/pam.d/ directory. The libpam library uses configuration files to determine which modules to implement. Generally, configuration files share the same name as their corresponding application. For example, the /etc/pam.d/sshd file applies to the sshd service.
Rules in PAM configuration files determine how PAM handles failed authentication checks.
Rules in PAM configuration files use the following format:
type control module-path [module-arguments]
The
typefield is the management group. Possible values includeaccount,auth,password, andsession.The
controlfield determines how PAM handles a failed authentication. Possible values includerequired,requisite,sufficient,optional,include, andsubstack.The
module-pathfield is the absolute or relative path to the module. By default, modules are expected in the/lib64/security/directory.The
module-argumentsfield is a space-delimited list of arguments for the specified module. Not all modules require arguments.
Note
The range of PAM configuration file choices is beyond the scope of this course. Consult the pam man page for more information.
PAM applies the rules in configuration files, in order, from top to bottom.
Consider the /etc/pam.d/sshd configuration file:
#%PAM-1.0 auth substack password-auth auth include postlogin account required pam_sepermit.so account required pam_nologin.so account include password-auth password include password-auth session required pam_selinux.so close session required pam_loginuid.so session required pam_selinux.so open env_params session required pam_namespace.so session optional pam_keyinit.so force revoke session optional pam_motd.so session include password-auth session include postlogin
Many configuration files, including /etc/pam.d/sshd, incorporate rules from other files with the substack or include control values. In the previous output, the password-auth configuration file provides password authentication for users who log in with SSH.
Note
As an administrator, avoid manually editing PAM configuration files. Instead, use the authselect tool to configure system identity and authentication sources by selecting a specific PAM profile.
By default, PAM sends events to the /var/log/secure file. Alternatively, PAM-related entries might appear in application-specific log files.
[root@host ~]# tail /var/log/secure | grep pam
Nov 4 12:47:09 server sshd[1455]: pam_unix(sshd:auth): check pass; user unknown
Nov 4 12:47:09 server sshd[1455]: pam_unix(sshd:auth): authentication failureMany modules support the debug argument to generate more verbose logs.
auth sufficient pam_unix.so debug
The pam_echo module prints messages and helps to determine which modules are causing authentication issues.
auth required pam_env.so auth optional pam_echo.so "Passed pam_env!" auth sufficient pam_unix.so auth optional pam_echo.so "Passed pam_unix!"
Administrators can use the pam_debug module to manually set a pass or fail response. This module is useful to troubleshoot how certain configurations affect the authentication process.
auth sufficient pam_debug.so auth=success cred=success
The authselect command modifies PAM configuration files with profiles. A profile is a set of PAM configuration files that use a specific authentication scheme. For example, the sssd (System Security Services Daemon) profile incorporates the pam_sss module in the /etc/pam.d/system-auth file.
The authselect select command configures a profile. The --backup option backs up the current PAM configuration files.
[root@host ~]# authselect select sssd --backup pamfiles.bakThe backup-restore subcommand restores a backup.
[root@host ~]# authselect backup-restore /var/lib/authselect/backups/pamfiles.bakThe authselect command does not modify application-specific PAM files. Instead, it modifies general-purpose files including /etc/pam.d/system-auth and /etc/pam.d/password-auth. Restore application-specific PAM configuration files by reinstalling the application.
[root@host ~]#cat /etc/pam.d/sshd# Accidently deleted the contents! [root@host ~]#yum reinstall openssh-server...output omitted... [root@host ~]#cat /etc/pam.d/sshd#%PAM-1.0 auth substack password-auth auth include postlogin account required pam_sepermit.so account required pam_nologin.so account include password-auth password include password-auth ...output omitted...
References
pam(8), pam.d(5), and authselect(8) man pages.
