pam_exec

auth | account | password | session [success=N default=ignore] pam_exec.so [options] /path/to/command [arguments...]

debug
    Logs debug information to syslog.

expose_authtok
    SECURITY WARNING: Exposes the user's authentication token (e.g., password) via the PAM_AUTHTOK environment variable to the executed command. Use with extreme caution.

expose_account
    Exposes the account management status via the PAM_ACCT_MGMT environment variable.

log
    Logs the command's standard output and standard error to syslog.

quiet
    Suppresses error messages if the executed command fails.

seteuid
    SECURITY WARNING: Executes the command with the effective UID of the authenticating user (or root if the user isn't known yet). This can be a security risk if the script is not properly secured.

type=[auth|account|session|password]
    Specifies the PAM management group for which the command should run. If omitted, the module runs for its current context.

stdout
    Redirects the command's standard output to syslog.

stderr
    Redirects the command's standard error to syslog.

shell
    Executes the specified command via /bin/sh -c, enabling shell features like pipes, redirections, and variables.

return=[N]
    If the command returns 0 (success), the module returns the specified PAM error code N.

return_on_non_zero
    If the command returns a non-zero exit code, the module returns a PAM error appropriate for its module type (e.g., PAM_AUTH_ERR for auth).

fail_on_non_zero
    Similar to return_on_non_zero, but explicitly causes the PAM stack to fail if the command returns a non-zero exit code.

env=[VAR=VAL]
    Adds an additional environment variable to the command's execution environment. Can be specified multiple times.

env_file=/path/to/file
    Loads additional environment variables from the specified file. Each line should be in VAR=VAL format.

uid=[UID]
    Executes the command as the specified user ID.

gid=[GID]
    Executes the command as the specified group ID.

pam_exec is a versatile Pluggable Authentication Module (PAM) that allows the execution of arbitrary external commands or scripts during various stages of the PAM authentication process.

It provides a powerful mechanism for system administrators to integrate custom logic, checks, or actions into the authentication workflow. This can include tasks like logging successful or failed login attempts to a database, performing additional pre-login validation (e.g., IP-based restrictions), or setting up specific user environments post-login.

The module can be configured to run a command during the auth, account, session, or password PAM management group, passing relevant PAM environment variables to the executed script. The return status of the executed command can then be used to influence the overall PAM stack's outcome, making it an essential tool for extending system security and management capabilities.

Security Implications: Options like expose_authtok and seteuid can introduce significant security vulnerabilities if the executed scripts are not extremely carefully written and secured. Avoid exposing sensitive information or granting unnecessary privileges.

Performance Overhead: Executing external commands adds latency to the authentication process. Scripts should be efficient and avoid lengthy operations.

Error Handling: Scripts should be robust and handle potential errors gracefully. Unexpected script failures can lead to authentication issues or system instability.

Absolute Path: The command path must be an absolute path; relative paths are not supported and can lead to security risks if not strictly controlled.

Environment Limitations: The command runs in a minimal environment; relying on system-wide PATH or complex environment setups might lead to unexpected behavior.

When pam_exec runs a command, it populates several PAM-related environment variables for the executed script's use. These commonly include:
- PAM_USER: The username attempting to authenticate.
- PAM_SERVICE: The PAM service name (e.g., "login", "sshd").
- PAM_TTY: The terminal device name, if available.
- PAM_RHOST: The remote hostname, if applicable.
- PAM_TYPE: The PAM module type currently being processed (e.g., "auth", "session").
- PAM_AUTHTOK: (Only if expose_authtok is used) The authentication token (e.g., password).
- PAM_ACCT_MGMT: (Only if expose_account is used) Indicates the account management status.

The exit status of the command executed by pam_exec is crucial. By default, a zero (0) exit status usually indicates success to pam_exec, which then typically results in PAM_SUCCESS for the module. A non-zero exit status signals an error. The return, return_on_non_zero, and fail_on_non_zero options provide fine-grained control over how the command's exit status translates into a PAM module return code, allowing administrators to dictate how external script success or failure impacts the overall authentication process.

PAM (Pluggable Authentication Modules) originated in the mid-1990s as a flexible framework to separate authentication policy from application code. Linux-PAM adopted this concept and has been a standard component of Linux systems for decades. pam_exec was developed as an integral part of Linux-PAM to provide a general-purpose mechanism for custom integration and extensibility, offering administrators a powerful hook into the authentication flow without modifying core PAM or service code. Its design emphasizes flexibility and control over the execution environment.

pam(8), pam.conf(5), pam.d(5), login(1), sshd(8), sudo(8)