Instructions for inserting this module into the httpd:

*** 1. Move the source file into the Apache source directory.

*** 2. In the `Configuration' file, add the line

	Module cookie_mysql_access_module    mod_auth_cookie_mysql.o

also, make sure that the EXTRA_LFLAGS variable includes 

	-L/data/mysql/lib

or whatever the name is of the directory that contains `libmysqlclient.a'. 

Make sure that the EXTRA_LIBS variable includes 
	-lmysqlclient

Make sure that the EXTRA_INCLUDES variable includes 
	-I/data/mysql/include

or whatever the path is to the file `mysql.h'.

*** 3. Run `Configure'

*** 4. Run `make'.

You should have a new `httpd' now.  Kill the old one and start the new
one.  

*** 5. Install `nph-get_password.cgi' in some appropriate place and
       make sure it runs OK.

*** 6. Use `mysqladmin' to create a mysql database to contain the file
       of acceptable usernames and passwords, if one doesn't exist
       already.  Let's suppose that this database is called
       `DATABASE'.


*** 7. Use `mysql' to create a table in DATABASE to hold the cookies.
       Let's suppose that this table is called `TABLE'.
       The table should have three fields:
		username
		password
		identity

       The module works like this: It looks at the cookies sent by the
       browser, which have the form `username=password'.  It looks in
       the database for records with `username' in the username field.
       If it finds more than one, it aborts. [See note 1].  It it
       finds none, it tries the next cookie.  If it finds exactly one,
       it compares the corresponding `password' field from TABLE with
       the password from the cookie.  [See note 2].  If they match, it
       tells the httpd that the user's identity is the corresponding
       `identity'; that will be the value that the server will use for
       checking access permissions and the value that it will put in
       the server log.  You could make the `identity' and `username'
       fields the same if you wanted to.
		
       The file MySCHEMA shows a sample of how to build the table.

*** 8. Copy the `sample_htaccess file into the directory you want to
       protect; name it `.htaccess'.

       Adjust the `ErrorDocument' line to have the appropriate URL for
       the `get_password' program.  The `Source' part of the URL tells
       `get_password' where the user came from so that `get_password'
       can send them back afterwards; it should be the URL path to the
       secret directory.

       Adjust Cookie_MyMSQLhost to name the host that the MySQL server
       resides on.  Adjust Cookie_MyMSQLcookie_database to name the
       database where the cookie table lives.  Adjust
       Cookie_MyMSQLcookie_databasetable to name the table.

       Adjust Cookie_MyMSQLcookie_namefield to the name of the field
       that will hold the usernames.  Adjust
       Cookie_MyMSQLcookie_valuefield to the name of field with the
       passwords.  Adjust Cookie_MyMSQLcookie_uidfield to the name of
       the field with the identities; you might want this to be the
       same as the namefield, if the usernames that people use to log
       in with are the same as the ones that the server will use
       internally.  

       Turn on Cookie_EncryptedCookies only if the passwords will be
       encrypted in the database.  The sample I sent doesn't do this;
       I recommend against it.

       Cookie_MustGive controls what happens when a user with no
       cookie at all tries to get into the directory.  If it's on,
       they will get `access denied'.  If it's off, the server will
       ask the other modules whether the user should be allowed or
       not.  If this is the only module you are using to provide
       authentication for a particular directory, you should turn this
       option on, because if the module tries to pass the buck to
       other modues, and there are none, the server will yield a `500
       server error'. 

       Cookie_Authorative similarly controls what happens when a user
       with no valid cookies tries to get into the directory.  

       Finally, adjust the `require' line to list the identities (as
       listed in the uid field) that are allowed into the directory.
       `require valid-user' allows anyone in as long as they have some
       identity.

*** 9. Try it out.

       Email me if you have any problems.

       The demo is on http://www.plover.com/cm/ if you want to try it
       on my machine; all the files I'm using are exactly the same as
       the ones I sent.

Mark-Jason Dominus
Plover Systems
mjd@plover.com