2 Installation

2.1 Requirements

• A compatible system. mod_log_sql was authored and tested on systems based on Red Hat Linux (Red Hat, Mandrake), but the module should easily adapt to any modern distribution. mod_log_sql has also been ported successfully to Solaris and FreeBSD.
• Apache 1.2 or 1.3. Ideally you should already have successfully compiled Apache and understand the process, but this document tries to make it simple for beginners.
• The MySQL development headers. This package is called different things on different distros. For example, Red Hat 6.x calls this RPM ``MySQL-devel'' whereas Mandrake calls it ``libmysql10-devel.''
• 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.
• Optionally, if you want to be able to log SSL information such as keysize or cipher, you need OpenSSL and mod_ssl installed.

2.2 Platform-specific notes

These installation documents assume a relatively modern GNU/Linux scenario. mod_log_sql has been ported to other platforms; following are notes on compiling the module for those platforms.

2.2.1 Solaris

The nanosleep() function used in mod_log_sql relies on linking aginst the librt library. Make the following alterations before proceeding:

1. In Makefile, search for the string ``-lmysqlclient -lz'' and change it to read ``-lmysqlclient -lz -lrt''
2. In part 8a of section 2.5 below, change ``-lmysqlclient -lm -lz'' to read ``-lmysqlclient -lm -lz -lrt''

2.2.2 BSD

No notes are available at present, but they are desired. If you have successfully ported mod_log_sql to BSD, please contact the maintaniner, Chris Powell (chris@grubbybaby.com) and help fill in this section.

2.2.3 Win32

No notes are available at present, but they are desired. If you have successfully ported mod_log_sql to Win32, please contact the maintaniner, Chris Powell (chris@grubbybaby.com) and help fill in this section.

2.3 Do I want a DSO or a static module?

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.

FWIW, the DSO method is more modern and increasing in popularity because apxs takes care of a lot of dirty little details for you. As you'll see below, the static-module method is a little more complex.

2.4 Installation as an Apache DSO (Preferred)

1. Perform all the following steps as root so that you have install privs, etc. 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 change the values of the variables in the first section.
   1. These paths are necessary:

      APACHEINSTALLED:

      the location where you installed Apache - usually /usr/local/apache, 'locate apxs' can help you find it.

      APACHEHEADERS:

      The location of your Apache header files, find using 'locate httpd.h'

      MYSQLLIBRARIES:

      The location of your MySQL libraries, find using 'locate libmysqlclient.so'

      MYSQLHEADERS:

      The location of your MySQL header files, find using 'locate mysql.h'

   2. Optional: if you compiled mod_ssl for Apache and want to log SSL data such as 'keysize' and 'cipher type':

      MODSSLHEADERS:

      the location of your mod_ssl header files, find using 'locate mod_ssl.h'

      DB1HEADERS:

      the location of your db1 header files, find using 'locate ndbm.h'

   You do not need to compile SSL support into mod_log_sql in order to simply use it with a secure site. You only need to compile SSL support into mod_log_sql if you want to log SSL-specific data such as the cipher type.

3. IMPORTANT: If you are not logging SSL info, comment out MODSSLHDRS by putting a # character in front of it:

   #MODSSLHDRS=/usr/include/...

4. Instruct apxs to compile the module as a DSO.

   # make dso

   You should see output similar to the following:

   /usr/local/Apache/bin/apxs -Wc,-O2 -Wc,-Wall -Wc,-DEAPI -c -I/usr/...

   gcc -DLINUX=22 -DNO_DBM_REWRITEMAP -DMOD_SSL=208111 -DUSE_HS... 

   gcc -shared -o mod_log_sql.so mod_log_sql.o -Wc,-O2 -Wc,-Wall -Wc...

   You should see no errors and have a new file called "mod_log_sql.so" in your directory.

5. Instruct apxs to install the DSO.

   # make dsoinstall

   You should see output similar to the following:

   /usr/local/Apache/bin/apxs -i mod_log_sql.so 

   cp mod_log_sql.so /usr/local/Apache/libexec/mod_log_sql.so 

   chmod 755 /usr/local/Apache/libexec/mod_log_sql.so 

6. Load and activate the module in httpd.conf:
   1. Insert this line in the same area as other logging modules, e.g. near ``LoadModule config_log_module'':

      LoadModule sql_log_module libexec/mod_log_sql.so

   2. Insert this line in the same area as other logging modules, e.g. near ``AddModule mod_log_config.c'':

      AddModule mod_log_sql.c

7. Module ordering within httpd.conf is important if you are logging SSL information. Please ensure that

   LoadModule ssl_module libexec/libssl.so

   comes before

   LoadModule sql_log_module libexec/mod_log_sql.so

   in your httpd.conf file. If they are out of order, simply cut-and-paste the ``ssl_module'' section so that it is at the top. If you do not, you will get this error when you start Apache:

   /usr/local/apache/libexec/mod_log_mysql.so: undefined symbol: ssl_var_lookup

   /usr/local/apache/bin/apachectl startssl: httpd could not be started

   (mod_log_sql has a dependency on mod_ssl for SSL symbols. If the statements are out of order, mod_log_sql cannot recognize those symbols.)

   Now skip below to section 3, Configuration.

2.5 Installation as a static module compiled into httpd

1. Perform all the following steps as root so that you have install privs, etc.
2. 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

3. Edit Makefile and change the values of the variables in the first section.
   1. These are necessary:

      APACHEINSTALLED:

      the location where you installed Apache - usually /usr/local/apache, 'locate apxs' can help you find it.

      APACHESOURCE:

      the location of your Apache sources, find using 'locate ABOUT_APACHE'

      APACHEHEADERS:

      the location of your Apache header files, find using 'locate httpd.h'

      MYSQLLIBRARIES:

      the location of your MySQL libraries, find using 'locate libmysqlclient.so'

      MYSQLHEADERS:

      the location of your MySQL header files, find using 'locate mysql.h'

   2. Optional: if you compiled mod_ssl for Apache and want to log SSL data such as 'keysize' and 'cipher type':

      MODSSLHEADERS:

      the location of your mod_ssl header files, find using 'locate mod_ssl.h'

      DB1HEADERS:

      the location of your db1 header files, find using 'locate ndbm.h'

   You do not need to compile SSL support into mod_log_sql in order to simply use it with a secure site. You only need to compile SSL support into mod_log_sql if you want to log SSL-specific data such as the cipher type.

4. IMPORTANT: If you are not logging SSL info, comment out MODSSLHDRS by putting a # character in front of it:

   #MODSSLHDRS=/usr/include/...

5. Compile the module.

   # make static

   You should see output similar to the following:

   gcc -fpic -O2 -Wall -I/usr/local/Apache/include -I/usr/include/mysql -I/usr/lo...

   You should see no errors and have a new file called "mod_log_sql.o" in your directory.

6. Install the module.

   # make statinstall

7. Change to your Apache source directory.

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

8. Re-compile your httpd binary as follows.
   1. Make these changes to Configuration.apaci:
      • Append the following string to the EXTRA_LIBS= line. ("/usr/lib/mysql" is from step 3, and is where your MySQL libraries live):

      -L/usr/lib/mysql -lmysqlclient -lm -lz

      • Find the mod_log_config.o line, and insert this line immediately after it:

      AddModule modules/sql/mod_log_sql.o

   2. # cp Configuration.apaci Configuration
   3. # ./Configure
   4. # make
   5. # strip httpd
9. 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...

10. 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 with the new version.

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

    # mv /usr/local/Apache/bin/httpd ~/httpd-save 

    # cp -f ./httpd /usr/local/Apache/bin/