NAME

       AFS::PAG - Perl bindings for AFS PAG manipulation

SYNOPSIS

           use AFS::PAG qw(hasafs setpag unlog);

           if (hasafs()) {
               setpag();
               system('aklog') == 0
                 or die "cannot get tokens\n";
               do_afs_things();
               unlog();
           }

DESCRIPTION

       AFS is a distributed file system allowing cross-platform sharing of files among multiple
       computers.  It associates client credentials (called AFS tokens) with a Process
       Authentication Group, or PAG.  AFS::PAG makes available in Perl the PAG manipulation
       functions provided by the libkafs or libkopenafs libraries.

       With the functions provided by this module, a Perl program can detect whether AFS is
       available on the local system (hasafs()) and whether it is currently running inside a PAG
       (haspag()).  It can also create a new PAG and put the current process in it (setpag()) and
       remove any AFS tokens in the current PAG (unlog()).

       Note that this module doesn't provide a direct way to obtain new AFS tokens.  Programs
       that need AFS tokens should normally obtain Kerberos tickets (via whatever means) and then
       run the program aklog, which comes with most AFS distributions.  This program will create
       AFS tokens from the current Kerberos ticket cache and store them in the current PAG.  To
       isolate those credentials from the rest of the system, call setpag() before running aklog.

FUNCTIONS

       This module provides the following functions, none of which are exported by default:

       hasafs()
           Returns true if the local host is running an AFS client and false otherwise.

       haspag()
           Returns true if the current process is running inside a PAG and false otherwise.  AFS
           tokens obtained outside of a PAG are visible to any process on the system outside of a
           PAG running as the same UID.  AFS tokens obtained inside a PAG are visible to any
           process in the same PAG, regardless of UID.

       setpag()
           Creates a new, empty PAG and put the current process in it.  This should normally be
           called before obtaining new AFS tokens to isolate those tokens from other processes on
           the system.  Returns true on success and throws an exception on failure.

       unlog()
           Deletes all AFS tokens in the current PAG, similar to the action of kdestroy on a
           Kerberos ticket cache.  Returns true on success and throws an exception on failure.

DIAGNOSTICS

       PAG creation failed: %s
           setpag() failed.  The end of the error message will be a translation of the system
           call error number.

       Token deletion failed: %s
           unlog() failed.  The end of the error message will be a translation of the system call
           error number.

RESTRICTIONS

       This module currently doesn't provide the k_pioctl() or pioctl() function to make lower-
       level AFS system calls.  It also doesn't provide the libkafs functions to obtain AFS
       tokens from Kerberos tickets directly without using an external ticket cache.  This
       prevents use of internal Kerberos ticket caches (such as memory caches), since the
       Kerberos tickets used to generate AFS tokens have to be visible to an external aklog
       program.

AUTHOR

       Russ Allbery <rra@cpan.org>

SEE ALSO

       aklog(1)

       The current version of this module is always available from its web site at
       <http://www.eyrie.org/~eagle/software/afs-pag/>.