Copyright (C) 2006 Andrew Ruder <aeruder@ksu.edu>

This software also borrows heavily from pam_mount which is:
Copyright (C) 2003 W. Michael Petullo

pam_sessionrun is a PAM module specifically for running scripts on session start
and end.

= OVERVIEW =========================

This module is aimed at environments wanting to enforce a script being ran at
start and/or end of a session.  This can be used for setting permissions,
mounting volumes, or anything else that you can think of.  Some general
features:

  o A stop and/or a start script can be provided.

  o The script is provided the password and the username of the person logging
    in.  This could be used for caching the person's password for mounting
    volumes, etc.

  o Completely transparent to the user.

= BUILDING =========================

To build, simply type:

    1. ./configure
    2. make
    3. make install

If this doesn't work, make sure you have all the prereqs installed:

    1. PAM libraries (and headers)
    2. A C compiler

Past that, you are on your own, but feel free to email if you run into any
problems.

= USING ============================

To use, simply open the PAM file for the service you are interested in using
(/etc/pam.d/SERVICENAME):

And insert something like:

auth optional pam_sessionrun.so use_first_pass

at the end of the auth section, and at the end of the session section:

session optional pam_sessionrun.so start=/bin/loginscript stop=/bin/logoutscript

You would be best off reading the PAM documentation if you don't understand any
of the above as it is far too detailed to go into here.

Here are the applicable arguments:

Auth section:
  use_first_pass
    Just use the first password
  try_first_pass
    If there is a password already stored, use it
  debug
    Enable debugging output to syslog and stderr.

Session section:
  debug
    Enable debugging output to syslog and stderr.
  start=<script>
    Script to run on session start.
  stop=<script>
    Script to run on session stop.

= SOME DETAILS =====================

And now for the intricate details.  The scripts are called with exactly 1
argument, either "open_session" or "close_session" depending on whether the
script is being called on session start or session stop.  You can use this to
write a single script that handles start and stopping a session.

The environment is modified in two ways.  First, the username of the user is put
into a "USER" environment variable.  Second, the password input by the user is
put into a "PASSWD" environment variable.

The script is called in the same context as the pam module.  Some PAM sessions
are started as root user (in the case of 'login' or 'xdm') and some are not (
'su' ).  This will greatly affect whether you are able to perform some
operations in the script files (mounting).  Use the 'id' or 'whoami' commands to
find out what user your script is really running as.

If a script does not exit normally or exits with a nonzero exit code, the
session open or close will fail for the pam_sessionrun module.  This can have an
affect if you have the pam module listed as 'required' in that particular PAM
stack.  Once again, see the PAM documentation for details on how PAM works.

Have fun,
Andrew Ruder