README for pam_script.so
========================

pam_script.so is a pam module that implements session and/or authentication
management.  If used as a session module, it runs a script at login and logout.
If used as an authentication module, it runs a script at authentication time.
If the script returns non-zero, the module returns a failure.

By default, pam_script runs scripts stored in /etc/security.  These scripts are
called onsessionopen, onsessionclose and onauth, and they are run at the start
of the session, end of the session or at authentication time respectively.

Alternatively any other script can be executed using the options
onsessionopen=/path/to/script, onsessionclose=/path/to/script or
onauth=/path/to/script.

If one of the default files do not exist, pam_script will ignore this and
return success.  If you specifically specify a script to execute, a
non-executable, unreadable or non-existant file is regarded as an error.

By default the user under which these scripts are executed is the user to whom
access was granted by the login procedure. Sometimes this is inapproriate, so
the user can be overidden using the directive runas=<user>.

Reason for writing pam_script
=============================
I wrote pam_script for a colleague (ie fellow sysadmin).  He uses pam_script to
kill jobs of users when they log out of X, and to unmount floppy drives.  This
is needed for some applications that crash in such a way that they disappear
from the display, yet continue running in the background, consuming RAM and
CPU.  Some of these can continue running for weeks, accumulating as the same
thing happens to different users, slowing down the system, irritating the hell
out of everyone and eventually making it necessary for the system administrator
to kill them (the processes, not the users :-)

Support for executing a script on authentication was added later as many
applications do not implement sessions.

Installation
============

Dependencies
------------
You need to install the pam development files on your distro, otherwise
building will fail. On debian you need to install libpam-dev or
libpam0g-dev.  On RPM based distros you need to install pam-devel.

Compilation
-----------

Extract the tarball, replace x, y and z with current version number:

	tar zxvf pam_script-x.y.z.tar.gz

Change into the directory

	cd pam_script-x.y.z

Now type "make":

	make

Installation
------------

Become root and copy pam_script.so to /lib/security:

	su
	(type root password)
	cp pam_script.so /lib/security

Configuration
=============

If you want to use the session management features, create the scripts
/etc/security/onsessionopen and /etc/security/onsessionclose and be sure to
make them executable.  If your application does not implement session
management and you are forced to use auth, use /etc/security/onauth instead.
There is no session closing equivalent for auth.

For all scripts, the username of the user who logged in/out is passed as the
first parameter, and the service name is passed as the second parameter.

All default scripts are optional and may be omitted, although omitting all of
them is rather pointless.

After creating and testing the required scripts, you need to configure pam.
If your system uses pam_stack and you want to use pam_script for all services,
edit /etc/pam.d/system-auth.  If your system does not use pam_stack, edit
/etc/pam.d/service where service is replaced by the whatever you're preparing
for/cleaning up after.  

For session management, simply add this line:

	session	required	pam_script.so

If you need to use authentication instead, use this line:

	auth	required	pam_script.so

For more information, consult the documentation at
http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam.html

Other options
=============

runas
-----
By default, the script is executed with the permissions of the user logging
in or out.  You can specify a different user with the runas option:

	session	required	pam_script.so runas=root

Use this option with care!

onsessionopen, onsessionclose and onauth
----------------------------------------
You can use scripts other than the default onsessionopen, onsessionclose and
onauth stored in /etc/security:

	session  required pam_script.so onsessionopen="/do/this.sh" onsessionclose="/do/that.sh"
	auth     required pam_script.so onauth="/do/signin.sh"

expose
------
Pam_script can also expose certain details to your script.  For the moment,
this includes exposing the authentication token (AUTHTOK), the path to your
kerberos ticket cache (KRB5CCNAME), and the host you are logging in from
(PAM_RHOST).


Notes
=====

login does not close sessions by default
----------------------------------------

Older versions of login does not close sessions by default.  To make it work,
you need to edit /etc/login.defs and set

	CLOSE_SESSIONS yes

This option is unfortunately not documented, it is only briefly mentioned in
the shadow Changelog.  Debian patches it into their default configuration file,
but it is still commented out.  Session closing became the default in shadow
4.0.12, so this only affects older versions of shadow.

Known issues
------------

Version 4.0.4 of shadow is buggy.  It is impossible to use pam_script to run a
onsessionclose script as another user on this version.  Either downgrade to
4.0.3 or upgrade to version 4.0.11 or later.

Credits
=======
Thanks to the excellent work done by Jacob Rief, pam_script is almost an
entirely different beast now.  Version 0.1.1 was almost entirely his work.

Bug reports and suggestions:
	Hanno Hecker
	Stef Bon
	Julian Briggs
	Luigi Iotti