How to install mod_auth_external.c into Apache:

NOTES:

 * These instructions has been updated for Apache 2.0 based on various second
   hand information.  The author has so far only done limited experimentation
   with Apache 2.0.  Please notify me if you notice any errors or can suggest
   any improvements.

 * 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 2.0.  This version of
   mod_auth_external will not work with Apache 1.3.  Get mod_auth_external
   2.1.x for use with Apache 1.3.

 * There are two ways of installing mod_auth_external. 

     (1) You can statically link it with Apache.  This requires rebuilding
	 Apache in such a way that mod_auth_external will be compiled in. 

     (2) You can make mod_auth_external a dynamically loaded module.  If
	 your Apache has been built to support dynamically loaded modules
	 you can do this without rebuilding Apache, so it is pretty easy.
	 Performance may be slightly worse with this option.  For information
	 on dynamically loaded modules see http://www.apache.org/docs/dso.html

   Instructions for both options are given here.

 * There is also documentation in the README file, in the AUTHENTICATORS file
   and at the front of the mod_auth_external.c source file.  If you find this
   document unclear, reading those may help.


INSTALL METHOD A: Dynamically Linking Mod_auth_external using apxs:
-------------------------------------------------------------------

Step 1:
	Ensure that your Apache server is configured to handle dynamically
	loaded modules.  To check this, run Apache server with the -l command
	flag, like

	       httpd -l

	If mod_so.c is one of the compiled-in modules, then you are ready
	to go.

Step 2:
	Compile the module using the following command in the mod_auth_external
	distribution directory:

		apxs -c mod_auth_external.c

	'Apxs' is the Apache extension tool.  It is part of the standard
	Apache installation.  If you don't have it, then your Apache server
	is probably not set up for handling dynamically loaded modules.
	This should create a file named 'mod_auth_external.so'.

	AIX Note:  For Apache 1.3 on AIX the 'apxs' command compiled
	   mod_auth_external.c into mod_auth_external.o correctly, but
	   generation of the shared library file failed with a message like
	   "No csects or exported symbols have been saved."  We don't know
	   if this still happens with Apache 2.0.  If it does happen, the
	   fix under Apache 1.3 was to create a file in the current
	   directory named mod_auth_external.exp which contained the two
	   lines below:

		 #! mod_auth_external.o
		 external_auth_module 

	   Then run 
	    
		apxs -c mod_auth_external.c -bE:mod_auth_external.exp
 
Step 3:
	Install the module.  Apxs can do this for you too.  Do the following
	command (as root so you can write to Apache's directories and config
	files):

	       apxs -i -a mod_auth_external.la

	This will create mod_auth_external.so and copy it into the proper
	place, and add appropriate AddModule and LoadModule commands to the
	configuration files.  (Actually, it may get the LoadModule command
	wrong.  See below.)

Step 4:
	Go to the CONFIGURATION instructions below.


INSTALL METHOD B: Statically Linking
------------------------------------

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 --with-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 \
	  --with-module=aaa:/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 and "make install" to install it.

Step 4:
	Go to the CONFIGURATION instructions below.


CONFIGURATION:
--------------

There are two parts to doing the configuration.  First you define the
external program and communication method to use in your httpd.conf file,
identifying them with a keyword.  Then you set up specific directories to
use that authenticator, referencing it by keyword.

Step 1:
	If you are using dynamic loading, you'll need to make sure that
	there is a proper "LoadModule" command in the httpd.conf file.
	This should have been put there by 'apxs' but, at least under
	RedHat 6.1, it gets it wrong.  Basically, the 'LoadModule' command
	should look a lot like all the other LoadModule commands.  Something
	like

	    LoadModule external_auth_module modules/mod_auth_external.so

	where the second part is the path from Apache's root directory
	to the location where the module is stored.

	Make sure that apxs didn't put this directive inside any inappropriate
	<IfDefine> directives, as some Redhat versions have done in the past.

	Also, if you previously had mod_auth_external installed and are
	installing a new version, apxs may have put a second LoadModule
	command into httpd.conf.  You only need one.  Get rid of the extra.

Step 2:
	Check you httpd.conf file to see if there is a "ClearModuleList"
	command.  If this exists, then you need to add a command like:

	    AddModule mod_auth_external.c

	somewhere below "ClearModuleList" command (probably somewhere among
	the dozens of other AddModule commands).  If you used 'apxs' to
	install mod_auth_external, then this should already be done, but
	it may again be stashed in an inappropriate <IfDefine>.

	The standard Apache configuration files don't have a "ClearModuleList"
	command and don't need an "AddModule" command.  However the standard
	RedHat configuration files do.

Step 3:
	Add the following line(s) to your server's httpd.conf.
	
	If you are using virtual hosts, put them at the end of the
	appropriate <VirtualHost> block.  The declarations must be *inside*
	the <VirtualHost> block to work for a virtual host.  They are not
	inherited from the primary host to the virtual hosts.  Note that most
	Apache SSL servers are set up as virtual hosts, so you'll probably
	need to put these definitions in the <VirtualHost> block for use with
	an SSL server.
	
	Otherwise, just put them anywhere (just before the Virtual Hosts
	section of the config file might make the most sense).

	For external authentication programs:
	    AddExternalAuth <keyword> <path-to-authenticator>         
	    SetExternalAuthMethod <keyword> <method>

	For HARDCODE functions:
	    AddExternalAuth <keyword> <type>:<path where config file is>
	    SetExternalAuthMethod <keyword> function

	<keyword> is some name you choose.  You can configure multiple
	different external authenticators by using different keywords for
	them.

	<path-to-authenticator> is normally the full path where you installed
	your external authentication program.  If you put it in quotes, you
	can include command-line arguments, but these arguments won't be
	processed by a shell, so you can't use wildcards or I/O redirects
	or anything like that.  If you need shell processing of arguments,
	write an sh-script wrapper for your authenticator, and put the path
	to that here.

	<method> defines how the login and password are passed to the
	external authenticator:
	  environment    get args from environment variables. (default)
	  pipe           read newline-terminated strings from stdin.
	  checkpassword  read null-terminated strings from file descriptor 3.
	  function       internal authenticator called as function.
	Environment is the default for historical reasons, but it may be
	insecure on some versions of Unix.  See the README file.

	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 external authenticators using the checkpassword protocol:

	     AddExternalAuth archive_auth "/bin/checkpassword /bin/true"
	     SetExternalAuthMethod archive_auth checkpassword

	   ** For HARDCODE functions with no configuration file:

	      AddExternalAuth archive_auth RADIUS:
	      SetExternalAuthMethod archive_auth function

	   ** For HARDCODE functions with a configuration file:

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

	AddExternalGroup <keyword> <path-to-authenticator>         

	SetExternalGroupMethod <keyword> <method>

	<keyword> is some name you choose to identify this particular
	group checking method.  The keywords for login authenticators and
	group authenticators are separate name spaces, so it doesn't matter
	if these keywords match any you defined in step 1.

	<method> defines how the login and group names are passed to the
	external authenticator:
	   environment - authenticator gets data from environment variables.
	   pipe - authenticator reads data from standard input.
	Environment is the default.

	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 5:
	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.

	Note that for .htaccess files to work, you must specify "AllowOverride
	AuthConfig" in the httpd.conf file for any directories they appear
	under.  As distributed, Apache sets "AllowOverride None" for most
	directories.  If this is not changed, .htaccess files will be ignored.

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

	   AuthType Basic
	   AuthName <authname>
	   AuthExternal <keyword>
	   require valid-user

       Here <authname> identifies what we are authenticating for - it usually
       appears in the browser's pop-up login windown.  <keyword> matches a
       keyword you defined with AddExternalAuth in step 1.

       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,
       changing it to:

	   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 <groupkeyword>
	   require group <groupname1> <groupname2> ...

       Here <groupkeyword> matches a name you defined with with the 
       AddExternalGroup command in step 2.

       Mod_auth_external is "authoritative" by default.  This means that
       if a login/password are not found to be valid by mod_auth_external,
       then no other authentication methods will be tried, even if you have
       configured them.  If you want login/password pairs that failed
       authentication to be passed only to other authenticators, then you
       should add the directive:

	  AuthExternalAuthoritative off

       Of course, if you haven't configured multiple authenticators for the
       directory, then you can ignore this.

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

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

Step 7:
	Restart Apache, so that all the new configuration commands will be
	loaded.  If you have the apachectl command do:

		apachectl restart

	For Redhat 6.1 which doesn't have apachectl, instead do:

		/etc/rc.d/init.d/httpd restart

Step 8:
	Test your changes/code by trying to view a protected page.
	
	If it doesn't work, check the apache error logs.  Some common
	problems:

	  - Miscellaneous odd behaviors.

	    Did you restart the httpd after the last time you editted the
	    httpd.conf file or recompiled the program?

	  - Apache complains about not recognizing "AddExternalAuth" and
	    other mod_auth_external commands.

	    Either the module didn't get installed (are you running the
	    newly compiled copy of httpd?), or it isn't enabled (you
	    may need the AddModule or LoadModule commands described above).

	  - It displays pages in a protected directory without asking for
	    a login and password.

	    If you are using .htaccess files, does your httpd.conf file
	    say "AllowOverride AuthConfig" for the directory?  Apache is
	    distributed with "AllowOverride None" set on the cgi-bin
	    directory, which will cause .htaccess files to be ignored.

	  - Error log says "Failed (-1)" or "Failed (255)".
	  
	    Mod_auth_external returns -1 (which may appear as 255) if it
	    can't execute the authenticator.  Is the path correct?  Is the
	    authenticator permitted so that whatever user apache runs as can
	    execute it?  Are the directories it is in permitted correctly?
	    It is also possible that the authenticator ran and returned -1.
	    
	  - Error log says "Failed" with some other number after it.
	  
	    The authenticator ran, and exited with the given non-zero return
	    code.  You'll have to check the authenticator to see under what
	    conditions it exits with that return code.
