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

To build as a DSO:

- If you are using Apache 1.x:
apxs -c -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


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.

IMPORTANT!  If Apache suffers a segfault on startup with this module included,
but starts fine with the module absent, you are most likely using two different
versions of MySQL libraries.  This can happen if, for instance, you compile 
mod_auth_mysql against MySQL 4.0.20 libraries, but use the precompiled version
of mod_php.so (or compile it yourself with default MySQL options), which uses 
earlier versions of the MySql libraries.  The solution is to recompile all 
modules using MySQL with the same libraries.


Additional Compiler Options
===========================

You can specify the following compile time options with the -D parameter
to set default values for many of the configuration paramters (described under
"Usage Notes" below).  For instance:

apxs -c -D APACHE2 -D HOST=localhost -lmysqlclient -lm -lz mod_auth_mysql.c

Configuration Parameter		Option		Valid Values (1)(2)
-----------------------		------		------------
AuthMySQLHost			HOST		"localhost", host name or ip address
AuthMySQLPort			PORT		integer port number
AuthMySQLSocket			SOCKET		full path name of UNIX socket to use
AuthMySQLUser			USER		MySQL user id
AuthMySQLPassword		PASSWORD	MySQL password
AuthMySQLDB			DB		MySQL database
AuthMySQLPwTable		PWTABLE		MySQL table to use
AuthMySQlNameField		NAMEFIELD	MySQL column name
AuthMySQLPasswordField		PASSWORDFIELD	MySQL column name
AuthMySQLPwEncryption		ENCRYPTION (3)	"none", "crypt", "scrambled", "md5"
AuthMySQLSaltField		SALT		"<none>" or MySQL column name
AuthMySQLKeepAlive		KEEPALIVE	"0", "1"
AuthMySQLAuthoritative		AUTHORITATIVE	"0", "1"
AuthMySQLNoPassword		NOPASSWORD	"0", "1"
AuthMySQLEnable			ENABLE		"0", "1"

Notes:
(1) Values in quotes are valid values.  Do not use the quotes in the compile
    line, i.e.
    WRONG:
	apxs -c -D APACHE2 -D HOST="localhost" ... 
    RIGHT:
	apxs -c -D APACHE2 -D HOST=LOCALHOST
    Other values not in quotes are descriptions of the values to be entered.

(2) For 0 and 1 values, 0 is false and 1 is true

(3) If this option is specified, you will NOT be able to use the following
    (depricated) options in your Apache configuration:
	AuthMySQLCryptedPasswords
	AuthMySQLScrambledPasswords
	AuthMySQLMD5Passwords
    You will be able to the default with the AuthMySQLPwEncryption parameter.
    
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. 

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.

*AuthMySQLEnable On
 AuthMySQLPort <default port in MySQL>
 AuthMySQLSocket <default socket in MySQL>
 AuthMySQLUser <no default -- NULL>
 AuthMySQLPassword <no default -- NULL>
 AuthMySQLNameField user_name
 AuthMySQLPasswordField user_passwd
*AuthMySQLPwEncryption crypt
*AuthMySQLSaltField <none>
 AuthMySQLKeepAlive Off
 AuthMySQLAuthoritative On
 AuthMySQLNoPasswd Off
 AuthMySQLGroupField <no default>
 AuthMySQLGroupTable <defaults to value of AuthMySQLUserTable>
 AuthMySQLUserCondition <no default>
 AuthMySQLGroupCondition <no default>

* denotes a new parameter in this version

AuthMySQLEnable indicates whether or not mod_auth_mysql should attempt to
authorize.  Off means this will not attempt authorization.

AuthMySQLPwEncryption supports the following values:
	none		No encryption
	crypt		Encrypt with the system crypt() function
	scrambled	Encrypt with the MySQL PASSWORD function
	md5		Encrypt with MySQL MD5 function

AuthMySQLSaltField is only used with crypt() encryption.  It can be the 
name of a column in the MySQLUserTable to use as the salt, or the
special string "<none>", in which case the password is encrypted using
itself as the salt.

The following parameters have been depricated and replaced by the single 
parameter AuthMySQLPwEncryption:

 AuthMySQLCryptedPasswords 
 AuthMySQLScrambledPasswords
 AuthMySQLMD5Passwords

These parameters will be removed in a future release. 

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.

Valid values for AuthMySQLPasswordEncryption:
  none:            plaintext passwords
  crypt (default): passwords are encrypted with the crypt() function
  md5:             passwords are hashed with the md5() function
  scrambled:       passwords are scrambled

AuthMySQLSaltField can specify a field to use as the salt to the
encrypt() function (AuthMySQLPasswordEncryption crypt).  It can be
the name of a field in the same table/row as AuthMySQLNameField or 
the special string "<none>" for no encryption.  If <none> is 
specified (or this parameter is not specified), the default is to
encrypt the password against itself.

Note: Encrypting against another field (i.e. user_name) will 
allow the password to be decrypted, posing a possible security
risk.  The default action (encrypting the password against 
itself) cannot be decrypted except by brute force.


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".

If you have user information stored in two (or more) different tables, you can join the tables like this:

AuthName My Authorization
AuthType Basic
AuthGroupFile /dev/null  # do NOT include this directive if using Apache2!!!
AuthMySQLHost localhost
AuthMySQLDB test
AuthMySQLUserTable "user_info, user_status"
AuthMySQLUserCondition = "user_info.user_name = user_status.user_name and user_status.status = 'OK'"
require valid-user


