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
===========

GROUP INSTRUCTIONS HAVE BEEN REMOVED, Group Features are not available in
this release...

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,
    [ 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.  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
 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
 AuthMySQLUserCondition <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.)

The optional directives AuthMySQLUserCondition can be used to restrict
queries made against the User 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
