pam_debug

pam_debug [debug=] [file=] [format=] [options]

debug=
    Sets the debug level. Higher levels provide more verbose output. Common levels are typically 0 (no debugging) to 3 (highest level of detail).

file=
    Specifies the file to which debug messages should be written. If not specified, messages are sent to syslog.

format=
    Sets the output format. The format can be `syslog` or `text`. The default is `syslog`.

The `pam_debug` command is not a standalone executable, but a PAM (Pluggable Authentication Modules) module. Its purpose is to facilitate debugging PAM configurations and module interactions. When enabled within a PAM configuration file, `pam_debug` logs detailed information about the PAM process, including the module called, the service name, the user involved, and the return codes from PAM calls. The output is typically directed to the system log or a designated file, allowing administrators to trace the authentication process and diagnose any problems that may arise. It offers configurable output options via parameters to tailor the debugging to focus on the relevant information. Using `pam_debug` strategically can drastically reduce troubleshooting time when faced with complex authentication issues.

Excessive debugging can generate large log files and potentially impact system performance. Use with caution in production environments. Remember to disable or reduce the debug level once troubleshooting is complete.

To enable debugging for the `sshd` service, add the following line to `/etc/pam.d/sshd`:
auth required pam_debug.so debug=3 file=/var/log/sshd_debug.log

This will log detailed authentication information to `/var/log/sshd_debug.log`. Remember to restart the service for the changes to take effect.

The output of `pam_debug` includes the PAM function called (e.g., `pam_authenticate`, `pam_acct_mgmt`), the return code, the service name, and the user involved. A return code of `PAM_SUCCESS` indicates success, while other codes indicate specific errors.

For example:
pam_debug(sshd:auth): [pam_authenticate]
indicates the authentication function was called by sshd. Examine the full log entry for clues about the cause of any failures.

The `pam_debug` module was developed as part of the PAM framework to provide a simple way to track and understand PAM's operation. Its usage increased significantly with the adoption of PAM as the primary authentication system in many Linux distributions. It helps developers and sysadmins understand PAM module interactions.

pam(8), syslog(3), authconfig(8)