How to install mod_authz_unixgroup.c into Apache:

NOTES:

 * Different versions of Apache require different versions of
   mod_authz_unixgroup:

     Apache 2.2.x    requires    mod_authz_unixgroup 1.0.x
     Apache 2.4.x    requires    mod_authz_unixgroup 1.1.0 or later

 * 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 -lbsd

	* Build using just POSIX group interfaces:
	  	apxs -c mod_authz_unixgroup.c -DUSE_POSIX_GRP
	  NOTE that some group providers (e.g sssd) can optionally omit gr_mem
	  in struct grp which will break POSIX API (in addition to being slower)

	* '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 extremely simple to use. Presumably you already are
setting up some kind of authentication in a .htaccess file or in a
<Directory> block in the httpd.conf file. You'll just need to change the
"Require" directive there to something like:

    Require unix-group admin
or
    Require unix-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 unix-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:

    Require unix-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.

Changes from Previous Versions:
-------------------------------

NOTE: New in 1.2.x, builds across all platforms now *REQUIRE* libbsd or the
equivalent bsd-standard group function support. This was necessary to fix
compatibility issues with modern auth providers such as sssd. See CHANGES
and PR #55 for details.

Previous versions of mod_authz_unixgroup needed a 'AuthzUnixgroup on' to
tell Apache that the "Require file-group" directive was supposed to be
handled by mod_authz_unixgroup. Now we have a distinct directive,
"Require unix-file-group" instead, so the 'AuthzUnixgroup' is no longer
needed and no longer exists.

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
returning 403 error instead of a 401 error.  Older versions of
mod_authz_unixgroup had a directive called 'AuthnzUnixgroupError' that did
this, but in Apache 2.4 that is replaced with a new standard Apache directive:

    AuthzUnixgroupAuthoritative off

There also used to be an 'AuthzUnixgroupAuthoritative' directive which is
also gone, since the whole concept of authoritativeness no longer applies
to access control providers in Apache 2.4.
