.TH pam_per_user 5 "Aug 2005" "Feep Networks" "Authentication"
.SH NAME
pam_per_user \- PAM module for calling per-user authentication mechanisms
.SH SYNOPSIS
.B /usr/local/lib/security/pam_per_user.so.1
.SH DESCRIPTION
.B pam_per_user
is a shared library which gets dynamically loaded into the PAM
framework.  It allows the selection of authentication mechanism
on a per-user basis for PAM-aware applications.

The
.B pam_per_user
module reads a map file to determine what mechanism to use for
the user being authenticated.  The map file consists of lines of
the following format:
.IP
[type=]key : service_name
.PP
Text beginning with a '#' is ignored through the next newline.
Blank lines and incomplete lines are also ignored.

The optional
.I type
field indicates what type of match should be done against
.IR key .
Supported types are:
.TP
.I USER
Perform a simple string comparison of the
.I key
and the user.
.IP
If
.I key
is "*", then the entry will be used as a fallback match.  In other words,
.B pam_per_user
will save this entry and continue reading the map file.  If a later entry
matches, that match will be returned.  However, if no other entries match,
the fallback entry will be used.  This allows a default mechanism to be
selected for users which are not explicitly listed.
.TP
.I GROUP
Checks to see whether the user is a member of group
.IR key .
.PP
If no
.I type
field is specified for a given entry, the default type is
.IR USER .

Once the map file has been read,
.B pam_per_user
creates a new PAM handle using the resulting service name.  The
requested PAM function is then called and the value is returned to
the caller.  This recursive use of PAM is transparent to the calling
application.

The following special tokens can be specified in the map file instead of
a PAM service name.  They cause
.B pam_per_user
to return an immediate result without recursively calling PAM:
.TP
.B @FAIL
Causes
.B pam_per_user
to return
.BR PAM_AUTH_ERR .
.TP
.B @SUCCEED
Causes
.B pam_per_user
to return
.BR PAM_SUCCESS .
.TP
.B @IGNORE
Causes
.B pam_per_user
to return
.BR PAM_IGNORE .
.SH OPTIONS
The
.B pam_per_user
module accepts an optional argument which sets the name of the external
file that will be read.  If no filename is not specified,
.I /etc/pam_per_user.map
will be read.
.SH EXAMPLE
Say that you want to use the
.B pam_pseudo
module to allow users to
.B su
to a special pseudo-user account called
.IR foo ,
you want to prevent people from
.BR su ing
to
.IR root ,
and you want members of the "wheel" group to authenticate via radius, but
you do not want to modify the behavior for other accounts.  To do this,
create the file
.I /etc/pam_per_user.map
with the following content:
.IP
foo : su-pseudo
.br
root : @FAIL
.br
GROUP=wheel : radius
.br
* : su-default
.PP
Then, rename the
.B su
entries in
.I /etc/pam.conf
to
.B su-default
and add the following new entries:
.IP
su auth required /usr/local/lib/security/pam_per_user.so.1
.br
su-pseudo auth required /usr/local/lib/security/pam_pseudo.so.1
.br
radius auth require /usr/local/lib/security/pam_radius_auth.so.1
.PP
.SH NOTES
Because 
.B pam_per_user
creates a new PAM handle to authenticate the user with an alternate
service name, it is possible to create an infinite loop by recursively
calling
.BR pam_per_user .
No checking is done to prevent this from happening, so the administrator
must take care to avoid it.
.SH FILES
.I /etc/pam_per_user.map
.br
.I /etc/pam.conf
.SH SEE ALSO
.BR pam (3),
.BR pam.conf (4)
.SH AUTHOR
Mark D. Roth <roth@feep.net>