Use pam_warn to Trace PAM Requests Without Changing Authentication

You will finish with a safe way to add pam_warn to a PAM stack so that it records the service, terminal, user, remote user and remote host presented by that request. The module always returns PAM_IGNORE, so its own result does not grant or deny access. This guide uses libpam-modules version 1.5.3-5ubuntu5.7 on the local Ubuntu system.

Allow about fifteen minutes, plus time to arrange a maintenance window if you must edit a live authentication stack. You need a shell, the libpam-modules package and a PAM-aware service. The inspection commands are ordinary user commands. Editing files under /etc/pam.d/ requires elevated privileges and can lock users out if the surrounding stack is damaged.

1. Confirm the installed module

Start by checking the package and the shared object. This does not change PAM configuration:

$ dpkg-query -W -f='${Package} ${Version}\n' libpam-modules:amd64
libpam-modules:amd64 1.5.3-5ubuntu5.7
$ test -r /usr/lib/x86_64-linux-gnu/security/pam_warn.so
$ printf 'module is readable: %s\n' "$?"
module is readable: 0

The directory is architecture-specific. Do not copy the path above into a script that must run on several architectures without checking the package's installed file list:

$ dpkg -L libpam-modules:amd64 | grep '/pam_warn\.so$'
/usr/lib/x86_64-linux-gnu/security/pam_warn.so

2. Choose the PAM stack you need to observe

PAM modules are called from a service stack. A service-specific file such as /etc/pam.d/sshd observes SSH requests, while a file named other supplies fallback entries when a service has no dedicated configuration. The module itself supports all four PAM module types: auth, account, password and session.

Inspect the relevant file before changing it:

$ sudo sed -n '1,220p' /etc/pam.d/SERVICE_NAME

Replace SERVICE_NAME with the real file name, such as sshd. sudo is elevated because PAM files can contain security policy. Keep a second administrative session open when working on a remote machine.

Do not assume that a line in one stack observes every login. A request can use a different service file, and a module type is selected by the operation being performed. Record the exact service and type you intend to investigate before editing.

3. Add a diagnostic line at the correct module type

The basic configuration line has four fields: module type, control flag, module path and optional arguments. pam_warn accepts no options, so leave the final field out:

# Diagnostic entry for the chosen PAM operation
auth     optional     pam_warn.so

Use account, password or session instead of auth when that is the operation you need to observe. The manpage's example uses required pam_warn.so alongside pam_deny.so in fallback stacks. That makes the denial policy explicit, but it is not a reason to copy that complete example into a working system.

optional is a readable choice for a diagnostic-only entry because the module returns PAM_IGNORE and does not make the authentication decision. The stack's other modules still decide the request. Do not add arbitrary options such as a log file or facility: this module recognises no options and sends its information to syslog.

4. Make the smallest safe file edit

Back up the exact file before editing it. This is the first state-changing step and needs elevated privileges:

$ sudo cp --preserve=mode,ownership,timestamps /etc/pam.d/SERVICE_NAME /etc/pam.d/SERVICE_NAME.before-pam-warn
$ sudoedit /etc/pam.d/SERVICE_NAME

Insert one line for the module type selected in step 2. Preserve the existing order, indentation and control flags. Do not replace the whole file with the small example above. Save, then inspect the resulting entry:

$ sudo grep -nE '^[[:space:]]*(auth|account|password|session)[[:space:]]+.*pam_warn\.so([[:space:]]|$)' /etc/pam.d/SERVICE_NAME
12:auth     optional     pam_warn.so

$ sudo cp --preserve=mode,ownership,timestamps /etc/pam.d/SERVICE_NAME.before-pam-warn /etc/pam.d/SERVICE_NAME

That command overwrites the edited file with the backup, so check the two paths carefully before pressing Enter. Remove the backup only after testing and only if your normal change-control process permits it.

5. Trigger the selected PAM operation carefully

Use the least disruptive test that exercises the chosen stack. For an SSH stack, make a second connection from a separate terminal rather than closing your current session. For a session stack, log in with a disposable test account if your environment provides one. For an authentication stack, use a known-good account and expect the normal service prompt.

Do not repeatedly test an unknown password or use a production account merely to produce a log entry. Account lockout policy, multi-factor prompts and remote access controls still apply. pam_warn does not bypass them.

The module's documented result is PAM_IGNORE. This means the module declines to influence the result; it does not mean that the whole PAM request succeeded. A later pam_deny, an invalid password or another required module can still reject it.

6. Find the diagnostic record

pam_warn writes the service, terminal, user, remote user and remote host to the system logger. The exact destination and message prefix depend on your syslog or journal configuration, so query the local logging system rather than assuming a file name:

$ sudo journalctl --since '10 minutes ago' --no-pager | grep -i pam_warn

If your host does not use a journal, inspect the configured syslog destination through your normal logging tools. The useful record should identify the values that were available as standard PAM items. An unset item can be absent or represented according to the logger and service; the module does not probe for missing values.

7. Remove the diagnostic entry when finished

Logging account and connection context can expose sensitive operational information. Remove the temporary line after the investigation unless a reviewed monitoring design requires it:

$ sudoedit /etc/pam.d/SERVICE_NAME
$ sudo grep -n 'pam_warn\.so' /etc/pam.d/SERVICE_NAME || echo 'pam_warn entry removed'

Keep the backup only as long as your change process requires. If you need to undo the entire edit, use the recovery command from step 4, then repeat the same safe connection test to confirm that the original stack still works.