libpam-afs-session for Debian
-----------------------------

When you initially install this package, you will have the option to
choose to automatically configure your PAM configuration to include it.
If you do so, a standard set of PAM options will be used that will work
for most users.  If those options do not work for you or if you can't use
automatic PAM configuration for some reason (such as another PAM module
that doesn't support it), see below.

If you only need AFS integration for regular interactive logins, adding:

    session  required  pam_afs_session.so

to /etc/pam.d/common-session is sufficient.  Note that you will need to
have already configured a Kerberos PAM module; see the documentation of,
for instance, libpam-krb5 or libpam-heimdal for more information.

This configuration will only obtain tokens for interactive sessions,
however; if you also want to obtain tokens for scp and similar
non-interactive logins, you will also need to modify
/etc/pam.d/common-auth to contain something like this:

    auth     sufficient                pam_unix.so nullok_secure
    auth     [success=ok default=die]  pam_krb5.so use_first_pass
    auth     [default=done]            pam_afs_session.so

See the PAM documentation (in the libpam-doc Debian package, for example)
for more information about the extended [] configuration and the possible
options.  The above recipe checks local Unix passwords first and then
falls back on Kerberos authentication; if you want to try Kerberos first,
instead use:

    auth     [success=ok default=1]  pam_krb5.so
    auth     [default=done]          pam_afs_session.so
    auth     required                pam_unix.so try_first_pass nullok_secure

Be very careful to never put this module in the auth stack marked as
sufficient or as a final required module.  pam_afs_session.so implements
only a stub for user authentication and is included in the auth stack
solely so that it is called on pam_setcred.  If you mark this module as
sufficient, it will allow any user to log in without a password.

See /usr/share/doc/libpam-afs-session/examples for example Debian PAM
configuration files.

For Debian, this module is built with Kerberos support so that it can read
configuration options from /etc/krb5.conf and so that the kdestroy option
is supported.  It is built without Heimdal libkafs support and therefore
always runs an external aklog program to obtain tokens.  Unless the path
is modified with the program option, the default aklog binary to run is
/usr/bin/aklog (so Heimdal afslog users will want to set the program
option).

Please be aware that proper creation and use of PAGs requires a Linux
kernel built with keyring support.  The standard Debian kernel has keyring
support and Linux includes keyring support by default, but if you have a
custom kernel, you may need to explicitly enable it.

If you are using this module in a vserver guest, you have to expose the
/proc interface used by the OpenAFS cache manager in order for the module
to detect AFS, create a PAG, and remove tokens.  Running:

    setattr --~hide /proc/fs/
    setattr --~hide /proc/fs/openafs
    setattr --~hide /proc/fs/openafs/afs_ioctl

on the host system reportedly makes the necessary files available to
vserver guests.

For more information, see the pam_afs_session man page.

 -- Russ Allbery <rra@debian.org>, Wed, 29 Dec 2010 15:25:06 -0800
