README

README 

PAM-script has been written by Jeroen Nijhof <jeroen@jeroennijhof.nl>
with packaging and some modifications by R.K. Owen <rkowen@nersc.gov>.

Description:
	PAM-script allows you to execute scripts during authorization,
	passwd changes, or session opening or closing.

	So if you need extra work done after login you can use this pam
	module to execute a session script.

Options to pam_script.so:
	onerr=(success|fail) - default behavior if the module can not find
	or execute the various pam-scripts.  The default is 'fail'.

	dir=/some/path - where to find the pam-scripts listed below.

	All options are passed on to the script commandlines and those not
	intercepted by PAM may be used to modify the script behavior.

Module-type and Scripts:
	auth:		pam_script_auth		- username/password handshake
	account:	pam_script_acct		- non-auth account management
	passwd:		pam_script_passwd	- changing a password
	session:	pam_script_ses_open	- actions performed before and
			pam_script_ses_close	  after a session

	All the scripts will be passed several environment variables:
	  PAM_USER, PAM_RUSER, PAM_RHOST, PAM_SERVICE, PAM_AUTHTOK,
	  PAM_OLDAUTHTOK, PAM_TTY, and PAM_TYPE referring to the module-type.
	Whether the variable has a non-null value or not depends on the
	context.

Pam.conf example:

	--- start pam.conf ---
	ssh auth	required	pam_script.so
	ssh session	required	pam_script.so
	ssh passwd	required	pam_script.so
	--- end pam.conf ---

or as an extra step (here pam_script.so is optional because this application
does some extra logging and doesn't want access denied if there is a problem):

	--- start pam.conf ---
	ssh auth	required	pam_unix.so
	ssh auth	optional	pam_script.so
	ssh session	required	pam_unix.so
	ssh session	optional	pam_script.so
	ssh passwd	required	pam_unix.so
	ssh passwd	optional	pam_script.so
	--- end pam.conf ---

This example application has the pam_script_auth script check a database
and return non-zero if the user should not be granted access.  If the
script does not exist or is not executable at all levels (chmod a+x)
then deny access.
	ssh auth	required	pam_unix.so
	ssh auth	required	pam_script.so onerr=fail

Debugging:
Get the pamtest.c program from the pam-dotfile distribution and it can be
used to step through the module.

Examples:
Look at the README.examples file, which may be located under
/usr/share/doc/libpam-script/ for a Debian derived distribution.

Problem/BUGS report:
If you find any bugs or problems just mail me
	Jeroen Nijhof <jeroen@jeroennijhof.nl>