README

   1 ______________________________________________________________________________
   2 INTRO
   3
   4 mod_waklog is an Apache module that provides aklog-like semantics
   5 for the web.  mod_waklog will acquire (and store in the kernel) an
   6 AFS credential when a connection is opened, use the credential for
   7 the duration of the connection, and will remove the credential when
   8 the connection is closed.
   9
  10 mod_waklog allows you to permit directories using AFS ACLs, and access
  11 them via a web browser.  An ACL of "umweb:servers rl" is required for
  12 each mod_waklog-protected directory.
  13
  14 mod_waklog allows scripts to run as you.  Programs which use AFS
  15 credentials to authenticate themselves do so as you.
  16
  17 mod_waklog often is used with mod_cosign, and uses the cosign-provided
  18 krbtgt to acquire an AFS credential; this extends single signon to AFS
  19 via the web.
  20
  21 ______________________________________________________________________________
  22 CONFIGURATION
  23
  24 Mod_waklog understands these directives.  Of these, only WaklogAFSCell
  25 is mandatory:
  26
  27 WaklogAFSCell
  28
  29   Use the supplied AFS cell (required)
  30
  31 WaklogEnabled
  32
  33   Enable waklog on a server, location, or directory basis
  34
  35 WaklogDefaultPrincipal
  36
  37   Set the default principal that the server runs as; this principal
  38   must have "l" access to every path that is served, regardless of
  39   user credentials or WaklogLocationPrincipal directives.
  40
  41 WaklogLocationPrincipal
  42
  43   Set the principal on a <Location>-specific basis
  44
  45 WaklogDisableTokenCache (NOT YET IMPLEMENTED)
  46
  47   Ignore the token cache (<Location>-specific).  This is useful for
  48   scripts that need kerberos tickets; for example, a perl script that
  49   uses kerberos authentication to contact a database.  By supplying a
  50   WaklogLocationPrincipal directive, mod_waklog can obtain the tickets
  51   and tokens for the principal, but by not using the token cache the
  52   script is assured that it will have tickets when it runs.
  53
  54 WaklogUseUserTokens
  55
  56   Use the requesting user tokens (from webauth)
  57
  58 ______________________________________________________________________________
  59 PHASES
  60
  61 Apache processes a request in multiple phases.
  62
  63 mod_waklog runs at phase 0 to acquire credentials via a keytab, and
  64 runs at phase 2 to remove the credentials.
  65
  66 mod_waklog runs at phase 7 to acquire credentials of whatever krbtgt
  67 is referenced via KRB5CCNAME (e.g., set by mod_cosign).
  68
  69 mod_waklog runs at connection termination to remove the credentials
  70 it acquired at phase 0 or phase 7.
  71
  72 Apache calls stat() between phase 1 and phase 2 to determine if it
  73 has access to the directory; if it doesn't have read access at that
  74 point, it won't try to read it again, even if later phases would
  75 acquire credentials which would allow it to do so.  mod_waklog
  76 acquires an afs credential for a principal in the pts group
  77 umweb:servers at phase 0, and removes this credential at phase 2;
  78 directories permitted "umweb:servers rl" will allow the stat() call
  79 to succeed.
  80
  81 ______________________________________________________________________________
  82 BUILD
  83
  84 make
  85
  86 Be sure the paths to apxs, include files, and libraries are correct.
  87
  88 If you compiled Apache 2 with large file support, be sure to have:
  89
  90    #define _LARGEFILE64_SOURCE
  91
  92 in mod_waklog.c.  If you run make and receive many errors about apr_off_t
  93 being undefined, you may need to add or comment out the above line.
  94
  95
  96 ______________________________________________________________________________
  97 INSTALL
  98
  99 Copy the mod_waklog.so to somewhere Apache can read and execute it.
 100
 101 Add the following lines to your httpd.conf file:
 102
 103     LoadModule waklog_module        /path/to/mod_waklog.so
 104
 105     <IfModule mod_waklog.c>
 106         WaklogProtected                 On
 107     </IfModule>
 108