BUILD AND INSTALL NOTES
=======================

To build as a DSO:

- If you are using Apache 1.x:
apxs -c -D APACHE1 -lmysqlclient -lm -lz mod_auth_mysql.c

- If you are using Apache 2.x:
apxs -c -D APACHE2 -lmysqlclient -lm -lz mod_auth_mysql.c

If the mysql.h header file cannot be found, add the -I option to specify the
directory where mysql.h can be found.
If the mysqlclient library cannot be found, add the -L option to specify the
directory where libmysqlclient.so can be found.
For example:
apxs -c -D APACHE2 -L/usr/lib/mysql -I/usr/include/mysql -lmysqlclient -lm -lz mod_auth_mysql.c

If you get warnings about "pointer/integer type mismatch" or "makes pointer
from integer without a cast", they can be safely ignored.
(Someday I want to get rid of these warnings though, since they annoy
some folks.)

After building the module, you need to install it to your modules directory.
- If you are using Apache 1.x:
apxs -i mod_auth_mysql.so

- If you are using Apache 2.x:
apxs -i mod_auth_mysql.la

Next, add the following directive to httpd.conf:
LoadModule mysql_auth_module modules/mod_auth_mysql.so

If using Apache 1.x, you may also need to add:
AddModule mod_auth_mysql.c

Finally, restart Apache and see if it starts up without any errors.


USAGE NOTES
===========

By default, this module assumes that each MySQL database has a table
like the following example:

CREATE TABLE user_info (
  user_name CHAR(30) NOT NULL,
  user_passwd CHAR(20) NOT NULL,
  user_group CHAR(10),
    [ any other fields if needed ]
  PRIMARY KEY (user)
)

User_name must be a unique, non-empty field.  Its length is however
long you want it to be.  Password length of 20 follows new-style
crypt() usage; the older crypt uses shorter encrypted passwords.
Any other fields in the named table will be ignored.  The actual
field names are configurable using the parameters listed below.
The defaults are "user_name" and "user_passwd" respectively, for
the user ID and the password, and "user_group" for the group which
is optional.  If you like to store passwords in clear text, set
AuthMySQLCryptedPasswords to Off.  I think this is a bad idea, but
people have requested it.
Note that in addition to standard crypt, MySQL has its own
password-scrambling function (named "password()").
If your passwords are scrambled, set AuthMySQLScrambledPasswords to On.
And due to popular demand, we can also support MD5 digested passwords.
If your passwords are MD5, set AuthMySQLMD5Passwords to On.

In order to limit the number of changes to the code and to enforce
backwards compatability, more than one of AuthMySQLScrambledPasswords,
AuthMySQLMD5Passwords, and  AuthMySQLCryptedPasswords could
both be set to "On" -- if such a situation should arise,
AuthMySQLScrambled will take precedence, followed by AuthMySQLMD5, 
followed by AuthMySQLCrypted. 
** At some future point in time, it might be nice to instead have one
directive named "AuthMySQLPasswordEncoding"
whose value can be 'crypt', 'scramble', 'md5', or 'plain'.


Usage in per-directory access conf file:

 AuthName "MySQL Testing"
 AuthType Basic
 AuthGroupFile /dev/null  # do NOT include this directive if using Apache2!!!
 AuthMySQLHost localhost
 AuthMySQLDB test
 AuthMySQLUserTable user_info
 require valid-user

The following parameters are optional in the config file.  The defaults
values are shown here.

 AuthMySQLUser <no default -- NULL>
 AuthMySQLPassword <no default -- NULL>
 AuthMySQLNameField user_name
 AuthMySQLPasswordField user_passwd
 AuthMySQLCryptedPasswords On
 AuthMySQLScrambledPasswords Off
 AuthMySQLMD5Passwords Off
 AuthMySQLKeepAlive Off
 AuthMySQLAuthoritative On
 AuthMySQLNoPasswd Off
 AuthMySQLGroupField <no default>
 AuthMySQLGroupTable <defaults to value of AuthMySQLUserTable>
 AuthMySQLUserCondition <no default>
 AuthMySQLGroupCondition <no default>

The Host of "localhost" means use the MySQL socket instead of a TCP
connection to the database.  DB is the database name on the server,
and UserTable is the actual table name within that database.

If AuthMySQLAuthoritative is Off, then iff the user is not found in
the database, let other auth modules try to find the user.  Default
is On.

If AuthMySQLKeepAlive is "On", then the server instance will keep
the MySQL server connection open.  In this case, the first time the
connection is made, it will use the current set of Host, User, and
Password settings.  Subsequent changes to these will not affect
this server, so they should all be the same in every htaccess file.
If you need to access multiple MySQL servers for this authorization
scheme from the same web server, then keep this setting "Off" --
this will open a new connection to the server every time it needs
one.  The values of the DB and various tables and fields are always
used from the current htaccess file settings.

If AuthMySQLNoPasswd is "On", then any password the user enters will
be accepted as long as the user exists in the database.  Setting this
also overrides the setting for AuthMySQLPasswordField to be the same
as AuthMySQLNameField (so that the SQL statements still work when there
is no password at all in the database, and to remain backward-compatible
with the default values for these fields.)

For groups, we use the same AuthMySQLNameField as above for the
user ID, and AuthMySQLGroupField to specify the group name.  There
is no default for this parameter.  Leaving it undefined means
groups are not implemented using MySQL tables.  AuthMySQLGroupTable
specifies the table to use to get the group info.  It defaults to
the value of AuthMySQLUserTable.  If you are not using groups, you
do not need a "user_group" field in your database, obviously.

A user can be a member of multiple groups, but in this case the
user id field *cannot* be PRIMARY KEY.  You need to have multiple
rows with the same user ID, one per group to which that ID belongs.
In this case, you MUST put the GroupTable on a separate table from
the user table.  This is to help prevent the user table from having
inconsistent passwords in it.  If each user is only in one group,
then the group field can be in the same table as the password
field.  A group-only table might look like this:

 CREATE TABLE user_group (
   user_name char(50) DEFAULT '' NOT NULL,
   user_group char(20) DEFAULT '' NOT NULL,
   create_date int,
   expire_date int,
   PRIMARY KEY (user_name,user_group)
 );

note that you still need a user table which has the passwords in it.

The optional directives AuthMySQLUserCondition and AuthMySQLGroupCondition
can be used to restrict queries made against the User and Group tables.
The value for each of these should be a string that you want added
to the end of the where-clause when querying each table.
For example, if your user table has an "active" field and you only want
users to be able to login if that field is 1, you could use a directive 
like this:
AuthMySQLUserCondition active=1

More tips on groups...

There are two options to using groups.  You can put the "user_group"
field into the same table as the user database if each user is in only
one group, or you can have a separate table that contains the fields
"user_name" and "user_group" if each user is a member of multiple
groups.

If the user_group field is part of the full user table, the table has
three fields at least: user_name, user_group, user_passwd.  The
user_group field must be "PRIMARY KEY" in the user database containing
a password.  The htaccess file would be this:

AuthName My Authorization
AuthType Basic
AuthGroupFile /dev/null  # do NOT include this directive if using Apache2!!!
AuthMySQLHost localhost
AuthMySQLDB authdata
AuthMySQLUserTable user_info
AuthMySQLGroupField user_group
require group admin

If you have a separate database for groups, the two tables would be

user_info: user_name, user_passwd (user_name must be PRIMARY KEY)
user_group: user_name, user_group (user is not PRIMARY KEY, as we have
	multiple tuples for user_name,user_group to let a user be in
	multiple groups)

and htaccess would have this:

AuthName My Authorzation
AuthType Basic
AuthGroupFile /dev/null  # do NOT include this directive if using Apache2!!!
AuthMySQLHost localhost
AuthMySQLDB authdata
AuthMySQLUserTable user_info

AuthMySQLGroupTable my_groups
AuthMySQLGroupField user_group
require group admin

Assuming that the required group name is "admin".

