How to install mod_auth_external.c into the Apache source tree.

NOTES:

 * If you want to use the HARDCODE function option follow the instructions
   in the INSTALL.HARDCODE file in this directory before following these
   instructions.

 * These instructions are for Apache version 1.3.  I don't know if this version
   of mod_auth_external is still compatible with older versions of Apache.

 * There are two methods of building Apache, the APACI method and the manual
   method.  Instructions for both are given here.  The configuration 


Building with APACI:
----------------------

Step 1:
        Read the instructions on how to configure the Apache server in the
        INSTALL file provided with the Apache source.

Step 2:
        When you run the ./configure script, include an --add-module flag,
        giving the full pathname to the mod_auth_external.c file in this
        distribution.  For example, if you have unpacked this distribution
        in /usr/local/src/mod_auth_external and are building Apache for
        installation in /usr/local/apache, you might do:

        ./configure --prefix=/usr/local/apache \
              --add-module=/usr/local/src/mod_auth_external/mod_auth_external.c

        This will copy the mod_auth_external.c file into the correct place in
        the Apache source tree and set things up to link it in.

Step 3:
	Type "make" to compile apache.


Building manually:
--------------------

Step 1:
	Read the instructions on how to configure the Apache server in the
	src/INSTALL file provided with the Apache source.

Step 2:
	Copy the mod_auth_external.c file from this distribution into the
	src/modules/extra subdirectory of the Apache source tree.

Step 3:
	Add the following line to the Apache 'Configuration' file:

	   AddModule modules/extra/mod_auth_external.c 

Step 4:
	Run "./Configure" and "./make" in the src directory to configure and
	compile apache.


Configuring for External Authentication:
----------------------------------------

Step 1:
	Add the following line(s) at the bottom of your server's httpd.conf.

        AddExternalAuth <keyword> <path-to-authenticator>         
	   (or)
	AddExternalAuth <keyword> <type>:<path where config file is>

        SetExternalAuthMethod <keyword> <method>

	<method> is one of the following: 
           environment - pass in environment variables (default - fully tested)
           function - handle as an internal function   (fully tested)
           pipe - pass values via stdin                (fully tested)

	Examples:

	  ** For external authentication programs using environment variables:

	     AddExternalAuth archive_auth /usr/local/bin/authcheck
	     SetExternalAuthMethod archive_auth environment

	  ** For external authentication programs using a pipe:

	     AddExternalAuth archive_auth /usr/local/bin/authcheck
	     SetExternalAuthMethod archive_auth pipe

   	   ** For HARDCODE functions with no file it looks like:

	      AddExternalAuth archive_auth RADIUS:
	      SetExternalAuthMethod archive_auth function

	   ** For HARDCODE extensions -WITH- a file it looks like:

	      AddExternalAuth archive_auth RADIUS:/usr/local/raddb
	      SetExternalAuthMethod archive_auth function
	   
Step 2:
	If you want to use an external program to do group checking, add the 
	following line(s) at the bottom of your server's httpd.conf.

        AddExternalGroup <keyword> <path-to-authenticator>         

        SetExternalGroupMethod <keyword> <method>

	<method> is one of the following: 
           environment - pass in environment variables (default - fully tested)
           pipe - pass values via stdin                (fully tested)

	Examples:

	  ** For external group check programs using environment variables:

	     AddExternalGroup archive_group /usr/local/bin/groupcheck
	     SetExternalGroupMethod archive_group environment

	  ** For external authentication programs using a pipe:

	     AddExternalGroup archive_group /usr/local/bin/authcheck
	     SetExternalGroupMethod archive_group pipe

Step 3:
	For any directory you want to protect, you need either a
	.htaccess file in the directory or a <Directory> block for the
	directory in your httpd.conf file.

        For normal user authentication, the following directives should be in
        the .htaccess file or <Directory> block:

	   AuthType Basic
	   AuthName <name you call this type of authentication>
	   AuthExternal <keyword>
	   require valid-user

       If you only want some users to have access to the directory, as opposed
       to all valid users, you can list the users on the "require" line:

           require user <username1> <username2> ...

       If you want to use the external group check program to allow only
       users in a given group to have access, you could do:

	   AuthType Basic
	   AuthName <name you call this type of authentication>
	   AuthExternal <keyword>
	   GroupExternal <keyword>
	   AuthGroupFile /dev/null
           require group <groupname1> <groupname2> ...

       See the Apache manual pages on AuthType, AuthName, require, and
       AuthGroupFile for more information.

Step 4:
	Install your external authentication program in the location named
	by the pathname on your AddExternalAuth directive.

Step 5:
	Test your changes/code by trying to view a protected page.
