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

pam_script.so is a pam module that implements session management.  It runs a
session open script (/etc/security/onsessionopen) and/or a session close
script (/etc/security/onsessionclose) if they exist. Alternatively any other
script can be executed using the options onsessionopen=/path/to/script and
onsessionclose=/path/to/script.

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.  This is needed for some
applications that crash in such a way that they disappear from the display, but
in the background they keep on running, consuming RAM and CPU.  Some of these
can continue running for weeks, accumulating as the same thing happens to
multiple users, slowing down the system, irritating the hell out of everyone
and eventually making it necessary for the system administrator to log in and
kill them (the processes, not the users :-)

I use it myself to kill kdeinit and artsd when users log out of kde.  An
example script is included for doing this.

Installation
============
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

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

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

Create scripts to do your dirty work.  The scripts should be placed in
/etc/security, called onsessionopen and onsessionclose and should be
executable.  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.  These
scripts are optional and one or both may be omitted, although omitting both is
rather pointless.

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 example, if you want to clean up after kde, use
/etc/pam.d/kde.  Simply add this line:

	session	required	pam_script.so

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

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

	session	required	pam_script.so runas=root

You can also use scripts other than onsessionopen and onsessionclose

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


Notes
=====

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

Important: By default, this module does not work with the login service.  To
make it work, you need to edit /etc/login.defs and change

	CLOSE_SESSIONS no

to

	CLOSE_SESSIONS yes

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 4.0.11 (the latest version at the time of this writing).

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.

Thanks to Hanno Hecker for the bug reports and other ideas for improvement.

Thanks to Stef Bon for his contributions.
