2009-09-30 dgc@uchicago.edu

pam_provision.so is a PAM module to assist in automatic account
provisioning.  It assumes that some kind of functioning POSIX account
information is available through the name service switch: nss_files,
nss_ldap, whatever.  If you can provide the account information,
pam_provision can do whatever is necessary on the local system to
make the account function.  This could be as minor as creating a home
directory, or it could involve other elements of session management.
Pam_provision's only job is to call the program you tell it to.  This
provisioner program can be a shell script or a program in any other
language.  An example provisioner written in Python is included with
this distribution.

pam_provision.so was developed on and for Solaris, but it might very
well work for Linux or other PAM platforms as well.

Basic use is like one of the following:

other account required pam_provision.so.1 exec=/tmp/provision.py %u %s %m
sshd-kbdint account required pam_provision.so.1 exec=/tmp/provision.py %u %m
sshd-kbdint session required pam_provision.so.1 exec=/tmp/provision.py %u %m

The module should reside in the default location for PAM modules if you
do not give path information.  If you do not want to install there,
provide the full path to the module.  On Solaris (at least) PAM modules
must be owned by root and NOT writable by non-root users.

Your particular environment decides the service name. "sshd-kbdint" is
used for keyboard authentication under OpenSSH, but "login" is used for
local logins.  If you do not know what service to use, try "other" and
watch your logs to see what service is identified by a login attempt.
You may need to configure syslog to record LOG_DEBUG messages.

pam_provision.so can be used as an ACCOUNT module or as a SESSION
module.  ACCOUNT modules are called once after authentication succeeds,
and are presumed to authorize the login.  When running as an ACCOUNT
module, pam_provision.so executes as the root user.

SESSION modules run after the login is authorized, and are responsible
for initializing any session state.  SESSION runs once to open the
session, and once to close the session (presumably at logout).  It
runs under the user's privilege.

At present two parameters are supported:
	log=[syslog facility name]
	exec=[path to script]

The "exec=" parameter MUST be the last option, since it implies
extra arguments to the provisioner script.  Those arguments are
expanded as follows:

%u   authenticating user
%s   service user has authenticated under (login, sshd-kbdint, etc)
%m   pam module class (account, session-open, session-close)
%h   host name being authenticated to
%r   remote host being logged in from (for applicable services)
%%   percent sign

With these expansions, you can write a script that can be used both for
an ACCOUNT module and for a SESSION module, if you need both superuser
provisioning and user initialization.

If this scripts exits with status 0, it will be considered to have
succeeded.  PAM_SUCCESS will be returned, and login will proceed.  If
the script returns nonzero, login will be blocked.

pam_provision.so collects output from this script and sends it to syslog.
LOG_AUTH is used by default, but you could change this to any other
facility using the log= parameter: for example, log=local3.