.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH PAM-SCRIPT 7 "August 22, 2007"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
pam-script \- a PAM module that can invoke scripts within the PAM stack.

.SH SYNOPSIS
.B pam-script.so
.RI [ onerr=(success|fail) ][ dir=/some/path/ ]

.SH DESCRIPTION
.B pam-script
allows you to execute scripts during authorization,
passwd changes, and on session opening or closing.

.PP
Such scripts can perform necessary tasks or influence the outcome of
the PAM stack.  For example, if the following entry was included
in
.I pam.conf
  sshd	auth	required	pam_script

then if the script,
.IR pam_script_auth ,
exits with a non-zero value this would cause the user to be
denied SSH access to the machine.

.PP
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invode bold face and italics,
.\" respectively.
.SH OPTIONS
A summary of options is included below.
.TP
.B onerr=(success|fail)
the default behavior if the module can not find or execute the script.
The default is to fail if the option is not given.
.TP
.B dir=/some/path/
where to find the pam-scripts to invoke for each of the various
module-types as described below.
The default is dir=/usr/share/libpam-script if not given.

List of scripts
.TP
.B pam_script_auth
Executed under
.I "auth"
which handles the authentication stage of establishing the user via some
challenge-response (i.e. username/password)
.TP
.B pam_script_acct
invoked under
.I "account"
module-type for non-authentication based account management.
.TP
.B pam_script_passwd
invoked under
.I "passwd"
for changing the password tokens.
.TP
.B pam_script_ses_open
invoked when a
.I "session"
is first opened.
.TP
.B pam_script_ses_close
run after a
.I "session"
is first closed.

All the scripts will be passed several environment variables:
PAM_USER, PAM_RUSER, PAM_RHOST, PAM_SERVICE, PAM_AUTHTOK, PAM_TTY,
and PAM_TYPE referring to the module-type.
The pam_script.so arguments in the pam.conf will be passed on the command line,
which can be used to modify the script behavior.

.SH FILES
.B /lib/security/pam_script.so
- the PAM module
.br
.B /usr/share/libpam-script
- where the scripts should be placed by default

.SH VERSION
pam-script 1.1.8

.SH SEE ALSO
.BR PAM (7)
and the PAM "The System Administrators' Guide"
.SH AUTHOR
.nf
pam-script was written by Jeroen Nijhof <jeroen@jeroennijhof.nl>
with some additions and modifications by R.K. Owen, Ph.D. <rkowen@nersc.gov>.
.PP
This manual page was written by R.K. Owen <rkowen@nersc.gov>,
for the Debian project (but may be used by others).