pam_debug

This module is configured within PAM service files (e.g., /etc/pam.d/sshd).

module_type     control_flag     pam_debug.so     [options]

Example:
auth     sufficient     pam_debug.so     debug
account     required     pam_debug.so     log_pass

module_type: Specifies the interface (e.g., auth, account, password, or session).
control_flag: Dictates the module's behavior within the stack (e.g., requisite, required, sufficient, optional).

debug
    Logs all arguments passed to the PAM module and its return values. This is the most common and comprehensive debugging option.

log_pass
    Logs sensitive information such as user passwords (both new and old, if applicable) if they are passed to the module.
Use with extreme caution due to severe security implications. Never use in production environments.

log_user
    Logs the username involved in the PAM transaction.

log_ruser
    Logs the remote username, if the PAM transaction involves a remote user.

log_rhost
    Logs the remote host name or IP address, if the PAM transaction originates from a remote host.

log_tty
    Logs the name of the TTY (terminal) device associated with the PAM transaction.

log_service
    Logs the service name (e.g., 'sshd', 'login') that invoked the PAM stack.

log_item=item_name
    Logs the value of a specific PAM item (e.g., PAM_USER, PAM_AUTHTOK, PAM_CONV). This option can be specified multiple times to log several items.

pam_debug is a Pluggable Authentication Modules (PAM) module designed for diagnostic purposes. It is not a standalone executable command but rather a component configured within PAM service configuration files, such as those found in /etc/pam.d/.

When included in a PAM stack, pam_debug.so logs detailed information about the PAM calls made to it, including the arguments passed to the module and its return values. This logging capability is invaluable for troubleshooting complex PAM configurations, helping administrators identify why authentication, authorization, or session management might be failing.

It enables a deeper understanding of the flow of control within the PAM stack, allowing users to pinpoint which specific modules are behaving unexpectedly or returning undesired results. The logged information typically goes to the system's syslog, often at the LOG_DEBUG level.

Security Risk: The log_pass option can expose sensitive user passwords in plaintext within system logs. It must never be used in a production environment and only with extreme caution in isolated debugging setups.

Performance Impact: Enabling extensive debug logging can introduce noticeable overhead, potentially slowing down authentication and authorization processes on the system.

Log Volume: Debug logging generates a substantial volume of log entries, which can rapidly consume disk space and make it more challenging to sift through logs for other critical system events.

Temporary Use: pam_debug is strictly intended for temporary troubleshooting. It is crucial to remove or comment out pam_debug entries from PAM configuration files once the issue is resolved to mitigate security risks and performance degradation.

By default, pam_debug logs messages to the system's syslog daemon. These messages are typically sent with the auth facility and a debug priority level. Depending on the system's syslog configuration (e.g., /etc/rsyslog.conf), these logs commonly appear in files like /var/log/auth.log, /var/log/secure, or /var/log/messages.

When employing pam_debug for troubleshooting, consider the following best practices:
1. Limit Scope: Add the pam_debug module to a specific PAM service file (e.g., /etc/pam.d/sshd) rather than a common, system-wide configuration file like system-auth to restrict the volume and scope of logging.
2. Strategic Placement: Position the pam_debug entry strategically within the PAM stack, typically just before or after the modules you suspect are causing issues, to capture relevant information.
3. Immediate Removal: Always remove or comment out the pam_debug module from your PAM configuration files immediately after debugging is complete to prevent security vulnerabilities, performance degradation, and excessive log generation.

The Pluggable Authentication Modules (PAM) framework was originally developed by Sun Microsystems in the mid-1990s to provide a flexible and modular approach to authentication services on Unix-like operating systems. pam_debug.so has been an integral part of the Linux-PAM (an open-source implementation of PAM) suite since its early versions, serving as an essential tool for administrators and developers to diagnose and understand PAM interactions. Its core purpose and usage have remained consistent throughout PAM's evolution, solidifying its role as a fundamental diagnostic component.

pam(8), pam.d(5), syslog(3), pam_unix(8), pam_faillock(8)