How to install mod_authz_unixgroup.c into Apache:

NOTES:

 * There are two ways of installing mod_authz_unixgroup. 

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

     (2) You can make mod_authz_unixgroup 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.  If you find this document
   unclear, reading that may help.


INSTALL METHOD A: Dynamically Linking Mod_authz_unixgroup 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_authz_unixgroup distribution directory:

		apxs -c mod_authz_unixgroup.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_authz_unixgroup.so'.

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_authz_unixgroup.la

	This will create mod_authz_unixgroup.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_authz_unixgroup.c file in this
	distribution.  For example, if you have unpacked this distribution
	in /usr/local/src/mod_authz_unixgroup 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_authz_unixgroup/mod_authz_unixgroup.c

	This will copy the mod_authz_unixgroup.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:
--------------

Mod_authz_unixgroup is pretty simple to use.  First, you need to enable it
for whatever directory you want to use it in, by inserting the following
directive either in a .htaccess file in the directory or a <Directory> block
in the httpd.conf file:

    AuthzUnixgroup on

Second, you will need a require directive like

    Require group admin
or
    Require group students teachers staff

Obviously this only makes sense in a directory where you are doing
authentication.  This could be any kind of authentication, but it makes
most sense if you are using it in combination with authentication out of
the unix password file, perhaps using mod_auth_external together with
pwauth, or mod_auth_shadow.  The "Require group" directive will then
cause mod_authz_unixgroup to check if the user is in one of the groups
listed, and reject the authentication if they are not.  A user is considered
to be in a group if either (1) the group is the user's primary group
identified by it's gid number in /etc/passwd, or (2) the group is listed
in /etc/group and the user id is listed as a member of that group.

If you are authenticating out of something other than the unix password
database, then this can be used, but the effect is a bit odd.  To pass
the "Require group" test, there must (1) exist a unix account with the same
name as the account the user authenticated in, and (2) that unix account must
be in one of the unix groups listed on the Require line.

It is also possible to list groups by gid number instead of name, like

    Require group 10

would be equivalent to "Require group admin" if the gid listed for the group
admin in /etc/group is 10.

If mod_authz_owner is enabled in your httpd, then that will work with
mod_authz_unixgroup to check access based on file groups.  For example if
we do:

    AuthzUnixgroup on
    Require file-group

Then a user will be able to access a file if and only if that file is owned
by a group of which the user is a member.

Normally, when an access check fails, mod_authz_unixgroup will return a
HTTP 401 error.  This will typically cause the browser to pop up a message
saying "Authentication Failed" and then the browser will ask for a new login
name.  In some cases this is not the desired behavior.  If you are using the
"Require file-group" directive, you may not want to log the user off every time
he hits a file he doesn't have access to.  Maybe you'd rather just show a
"Permission denied message" and not log him off.  You could do that by
directing mod_authz_unixgroup to return a 403 error instead of a 401 error.
You can do this with the following directive:

    AuthnzUnixgroupError 403

By default, mod_authz_unixgroup is authoritative.  If you want to use more
than one group checker, like mod_authz_unixgroup together with
mod_authz_groupfile or mod_authz_dbm, then you'll want to make them non-
authoritative, so that if one fails, the other will be tried.  You can
make mod_authz_unixgroup non-authoritative by saying:

   AuthzUnixgroupAuthoritative off