README for mod_authnz_fcgi.html

1. Location of reference documentation for the module

   http://emptyhammock.com/hypermanual/mod/mod_authnz_fcgi.html

   This is hosted within the rest of the Apache httpd manual so that 
   hyperlinks to other parts of the manual work and stylesheets are available.

   This location is temporary, until a permanent home is found for the module.

2. Location of source code and other files for the module

   http://emptyhammock.com/downloads/

   Select the latest available package.

   This location is temporary, until a permanent home is found for the module.

3. How to build and install the module

   The included script bld.sh should be sufficient.  It uses apxs (part of the
   Apache httpd install) to build and install the module.  By default it assumes
   that Apache httpd is installed directly under /usr/local.

   If Apache httpd is installed somewhere else, compilation will fail as follows:

     $ ./bld.sh 
     /usr/local/bin/apxs -c mod_authnz_fcgi.c newapis.c
     ./bld.sh: 7: ./bld.sh: /usr/local/bin/apxs: not found

   Invoke it again with the APXS environment variable set to the local of
   the apxs utility in Apache httpd's bin directory:

   (example)

     $ APXS=$HOME/inst/24-64/bin/apxs ./bld.sh 
     /home/trawick/inst/24-64/bin/apxs -c mod_authnz_fcgi.c newapis.c
     /home/trawick/inst/apr15-64/build-1/libtool --silent --mode=compile ...
     /home/trawick/inst/apr15-64/build-1/libtool --silent --mode=compile ...
     /home/trawick/inst/apr15-64/build-1/libtool --silent --mode=link ...


     Run this command to install the module, as root or via sudo if necessary:


     /home/trawick/inst/24-64/bin/apxs -i mod_authnz_fcgi.la


   The last command displayed has to be invoked manually, as root or via
   sudo if the current user does not have permissions to copy files in to
   the Apache httpd modules directory.

4. Web server configuration

   You need to become familar with Apache httpd authentication and
   authorization configuration, described at

   http://emptyhammock.com/hypermanual/howto/auth.html

   But instead of using file-based authentication in the sample configurations
   there, you'll be specifying your FastCGI-based provider(s).

   Then proceed to the mod_authnz_fcgi reference page:

   http://emptyhammock.com/hypermanual/mod/mod_authnz_fcgi.html

5. Testing and Debugging

   If practical, perform initial configuration testing with the FastCGI
   application used only for authentication and/or authorization (instead
   of handling the request itself), unless you have successfully used
   mod_proxy_fcgi already.

   Increase logging for mod_authnz_fcgi as high as you can (possibly trace8).
   See http://emptyhammock.com/hypermanual/mod/mod_authnz_fcgi.html#logging
   for notes about logging by this module.  The key issue is the presence
   of sensitive data in the logs.  Test users should be used if at all
   possible.

6. Reporting problems

   Contact me at trawick@gmail.com.  Please reproduce the problem with
   the simplest scenario possible, and send me your web server configuration
   as well as the portions of the access and error logs covering the time
   of the test.  Be sure to obliterate any sensitive data in the log files.
