$Id: INSTALL,v 1.8 2002/05/14 21:47:14 helios Exp $


Requirements
============

* I run a Red Hat 6.2 system, but these instructions should easily
  adapt to any modern distro.

* Apache 1.2 or 1.3 installed.  (I run 1.3.22 and it works fine). 
  You should have already successfully compiled Apache and know what
  you're doing there.  In fact, you should already have any other
  modules and add-ons like mod_ssl or PHP configured and installed
  before you start this process.

* The MySQL development headers.  (I run MySQL-devel-3.23.44-1.i386.rpm).  

* MySQL >= 3.23.15 configured, installed and running on either
  localhost or an accessible networked machine.  You should already
  have a basic understanding of MySQL and how it functions.

* Again, basic administrative skills with Apache and MySQL.  I try to
  make things as easy as possible in this README, but its purpose is
  not to be an administrative tutorial.

* Additionally, if you want to be able to log SSL information such as
  keysize or cipher, you need OpenSSL and glibc-devel installed.  Both
  are available as RPMs.


Do I want a DSO?
================
You need to know the answer to this question before you proceed.  The
answer is pretty straightforward:  what have you done in the past?  If
you like all your Apache modules to be dynamic, then you should keep
doing that.  If you're more of an old-school type and prefer to compile
the modules right into apache, do that.  Both methods work equally
well.


Installation (as an Apache DSO)
===============================

For folks interested in using this module as an Apache DSO:

0) Perform all the following steps as root so that you have install
   privs, etc.

1) Unpack the archive into a working directory.

   # tar zxf mod_log_sql.tar.gz -C /usr/local/src
   # cd /usr/local/src/mod_log_sql

2) Edit Makefile and make any adjustments for your system.  These are
   fully explained in the Makefile.

3) Instruct apxs to compile and install the module as a DSO.  You need
   to know two things before you run apxs:
   - The location of the apxs binary, find using 'locate apxs'
   - The location of your MySQL libraries, find using 'locate libmysqlclient'

   FORMAT:
   # <path>/apxs -i -c -L/path/to/mysqllibs -lmysqlclient -lz mod_log_sql.c

   EXAMPLE:
   # /usr/sbin/apxs -i -c -L/usr/lib/mysql -lmysqlclient -lz mod_log_sql.c

   You should see something like this:

	gcc -fpic -DSHARED_MODULE -I/usr/local/Apache/include -c mod_log_sql.c
	ld -Bshareable -o mod_log_sql.so mod_log_sql.o
	cp mod_log_sql.so <your path to Apache libexec>/mod_log_sql.so
	chmod 755 <your path to Apache libexec>/mod_log_sql.so
	[activating module blah in /path/to/apache/etc/httpd.conf]

4) Add the following stanzas to your httpd.conf file.  Put the second stanza
   somewhere after the ClearModuleList directive.

	<IfDefine HAVE_LOG_MYSQL>
	   LoadModule mysql_log_module modules/mod_log_sql.so
	</IfDefine>


	<IfDefine HAVE_LOG_MYSQL>
	   AddModule mod_log_sql.c
	</IfDefine>


5) Now go to step (9) in the instructions below to configure httpd.conf...


Installation (as a static module compiled into httpd)
=====================================================

[This is what I do, FYI.]

0) Perform all the following steps as root so that you have install
   privs, etc.

1) Unpack the archive into a working directory.

   # tar zxf mod_log_sql.tar.gz -C /usr/local/src
   # cd /usr/local/src/mod_log_sql

2) Examine the DEFINEs at the top of mod_log_sql.c and alter any that 
   you choose.  Edit Makefile and make any adjustments for your system.  
   These are fully explained in the Makefile.

3) # make all 
   (You should receive NO warnings or errors of any kind. 
   If you see messages like this: "mod_log_sql.c:69: httpd.h: No such
   file or directory" then you do not have your CFLAGS correctly
   pointing to the right include directory.)

4) # make install

5) Change to your Apache source dir.

   # cd /usr/local/src/apache-1.3.22/src

6) Re-make your httpd binary as follows.

   6a) Edit Configuration.apaci as follows...

       * Append the following string to the EXTRA_LIBS= line. (/usr/lib/mysql is where your libmysqlclient.a file lives):
       -L/usr/lib/mysql -lmysqlclient -lm -lz

       * Find the mod_log_config.o line, and add this line immediately after it:
	  AddModule modules/sql/mod_log_sql.o

   6b) # cp Configuration.apaci Configuration

   6c) # ./Configure

   6d) # make

   6e) # strip httpd

7) Test your new apache binary:

   # ./httpd -l

   You should see something like:

	Compiled-in modules:
	  http_core.c
	  mod_log_sql.c    <-- That's the line you're looking for.
	  mod_env.c
	  mod_log_config.c
	  mod_mime.c
	  mod_negotiation.c
       ...etc...

8) Install your httpd binary.  Copy it over your old httpd binary,
   wherever it lives.  You can and should rename your old httpd first so
   that you can easily revert to that working version in case of bugs or
   whatever.
 
   # /etc/rc.d/init.d/httpd stop
   # cp -f ./httpd /usr/local/Apache/bin/

9) Configure your apache daemon to log to your database.  Here's a very
   basic set of config lines to start you off.  Full documentation is
   available here: http://www.grubbybaby.com/mod_log_sql/directives.html

   EXAMPLE: Connect to the MySQL database called "apache" running
   on "dbmachine.foo.com".  The module uses username "loguser" and
   password "l0gger" to authenticate to the database; this user must,
   of course, exist in the MySQL user table and have the proper
   permissions -- more on that in step 11.  The log entries will be
   INSERTed into the table called "access_log".


   MySQLLoginInfo dbmachine.foo.com loguser l0gger
   MySQLDatabase apache

   <VirtualHost 1.2.3.4>
        [snip]

        MySQLTransferLogTable access_log
        MySQLTransferLogFormat huSUsbTvRA

        [snip]
   </VirtualHost>


   9a) Special step for users who have a DSO-enabled httpd:

	  If you you are building mod_log_sql as a static module BUT
	  your httpd is enabled for DSOs, add the following line to your
	  httpd.conf:

       AddModule mod_log_sql.c 


10) If you compiled mod_log_sql with the ability to make its own tables
    then you can skip this step.  Otherwise you need to do it by hand:

    Create a database and table to hold the new log data.  I log the
    same data as the regular "combined log" plus a little extra information
    that can be useful.

    The order that the fields appear in the table is irrelevant
    because you can SELECT them in any order you choose.  To create
    this table I first created a new database called "apache":

    # mysql -uadmin -pmypassword
    mysql> create database apache;

    Then create the table called "access_log".  I enclosed an SQL file
    that will create every column type that mod_log_sql supports. 
    Unless you're just testing or playing around, this is probably NOT
    what you want, so edit the file first and delete the lines that
    don't pertain to you.  Then:

    mysql> source access_log.sql


11) Create a specific MySQL userid that httpd will use to authenticate
    and enter data.  This userid need not be an actual Unix user.  It
    is a userid internal to MySQL with specific privileges.
	
	mysql> grant insert,create on apache.* to loguser@my.apachemachine.com identified by 'l0gger';
	
	Security is a very real concern.  mod_log_sql by default is 
	set up to create the SQL tables it needs.  If you have deactivated
	this capability, then create a user called "loguser" with the password
	"l0gger" with only the capability of INSERT to "access_log":

    mysql> grant insert on apache.access_log to loguser@my.apachemachine.com identified by 'l0gger';


12) Enable full logging of your MySQL daemon (at least temporarily
    for debugging purposes) if you don't do this already:

    Edit /etc/my.cnf and add the following line to your [mysqld] section:

      log=/var/log/mysql-messages

    Then restart MySQL.

13) Restart apache.

    # /etc/rc.d/init.d/httpd start

13) Load your web site in a browser to trigger some hits, then confirm that 
    the entries are being successfully logged:

    # mysql -hmysql.host.com -umysqladmin -p -e "select * from access_log" apache;
    Enter password:

    +---------------------------------------------------+-------------+-------------+------------------+------------------+------------+--------+------------+------------------------------------+
    | remote_host                                       | remote_user | request_uri | request_duration | virtual_host     | time_stamp | status | bytes_sent | referer                            |
    +---------------------------------------------------+-------------+-------------+------------------+------------------+------------+--------+------------+------------------------------------+
	[snipped lines]
	.
	.
	.
    +---------------------------------------------------+-------------+-------------+------------------+------------------+------------+--------+------------+------------------------------------+

14) You have basic functionality.  Don't disable your regular Apache logs until
    you feel comfortable that the database is behaving as you'd like and that
    things are going well.