pamexec

Execute a shell command on each image in a Netpbm file

$ pamexec [command] [path/to/image.pam]

$ pamexec [command] [path/to/image.pam] [[-c|-check]]

pamexec [options] [PAM_service_name] [target_user] command [command_arguments...]

-t target_user
    Sets the target user for the command to be executed. If not specified, the command runs as the user established by PAM or the current user.

-u current_user
    (Deprecated) Sets the current user. Use the `PAM_USER` environment variable instead.

-e VAR=VAL
    Adds or overwrites an environment variable for the executed command. Can be specified multiple times.

-f
    Sets the `PAM_FD` environment variable, indicating a file descriptor to be used by the command.

-s
    Sets the `PAM_SERVICE` environment variable based on the PAM service name.

-d
    Dumps the environment variables that would be passed to the executed command to stderr. Useful for debugging.

-l
    Logs the environment variables to syslog (AUTH facility, INFO priority).

-v
    Enables verbose output, printing additional diagnostic messages to stderr.

-q
    Enables quiet mode, suppressing all output except errors.

-h
    Displays a help message and exits.

-V
    Displays version information and exits.

-n
    No-op mode. Performs a dry run without actually executing the command. Useful for testing environment setup.

-r
    Causes pamexec to return the exit status of the executed command. By default, it always returns 0 unless there's an internal error.

-c config_file
    Reads additional configuration from the specified file. Typically used for environment variables.

-i input_file
    Redirects the standard input of the executed command from `input_file`.

-o output_file
    Redirects the standard output of the executed command to `output_file`.

-E
    Preserves the existing environment variables, rather than starting with a clean environment. Newly set variables take precedence.

-P
    Processes arguments of the form `key=value` as environment variables for the command.

-X
    Sets the `PAM_XAUTHTOKEN` environment variable, typically related to X Window System authentication.

-Z
    Sets the `PAM_SELINUX_CONTEXT` environment variable, used in SELinux environments.

-R
    Sets the `PAM_REMOTE_HOST` environment variable, indicating the remote host from which the session originated.

-T
    Sets the `PAM_TTY` environment variable, indicating the terminal associated with the session.

The pamexec command is a specialized utility program primarily designed to be invoked by PAM (Pluggable Authentication Modules) services, particularly through the pam_exec.so module. Its core function is to execute an external command under specific environmental conditions and user contexts determined by PAM.

It allows the PAM module to perform actions such as setting up a user's environment, running session-specific scripts, or logging events, all while potentially changing the effective user ID and manipulating environment variables. This makes it a powerful tool for system administrators to integrate custom scripts or programs into the authentication and session management flow, ensuring that these actions are performed with the correct privileges and within the PAM-defined context. It is not typically invoked directly by end-users but rather as part of the system's authentication and authorization process.

Incorrect usage of pamexec, particularly when invoked from PAM configuration files, can lead to security vulnerabilities or system instability. Care should be taken to ensure that commands executed by pamexec are secure, do not introduce unintended side effects, and are run with the principle of least privilege. Environment variable manipulation can be complex, and unexpected interactions might occur if not carefully managed. Always test changes to PAM configurations in a controlled environment.

While pamexec can theoretically be run directly, its primary and intended use is as an external command invoked by the pam_exec.so PAM module within `pam.d` configuration files (e.g., `/etc/pam.d/login`, `/etc/pam.d/sshd`). This allows system administrators to run custom scripts or programs at various stages of the PAM authentication, account, session, or password management process, such as setting up a user's home directory after first login, logging session starts, or enforcing custom policies based on real-time conditions.

The pamexec utility is part of the Pluggable Authentication Modules (PAM) framework, which was originally developed by Sun Microsystems in the mid-1990s and later adopted by the OpenGroup as a standard. pamexec emerged as a helper program within this framework, specifically designed to facilitate the execution of external commands by PAM modules like pam_exec.so. Its development is tied to the evolution of PAM itself, aiming to provide a flexible and extensible way for system administrators to customize authentication and session management behaviors through external scripts and programs.

pam(8), pam_exec(8), login(1), su(1), sudo(8)