DataBase Configuration

LogSQLLoginInfo

LogSQLLoginInfo connection URI

Example: LogSQLLoginInfo mysql://logwriter:passw0rd@foobar.baz.com/Apache_log

Context: main server config

Defines the basic connection URI to connect to the database with. The format of the connection URI is

driver://username[:password]@hostname[:port]/database

driver

The database driver to use (mysql, pgsql, etc..)

username

The database username to login with INSERT privileges on the logging table defined in LogSQLtransferLogTable.

password

The password to use for username, and can be omitted if there is no password.

hostname

The hostname or Ip address of the Database machine, ans is simple "localhost" if the database lives on the same machine as Apache.

port

Port on hostname to connect to the Database, if not specified use the default port for the database.

database

The database to connect to on the server.

This is defined only once in the httpd.conf file.

This directive Must be defined for logging to be enabled.

LogSQLDBParam

LogSQLDBParam parameter-name value

Example: LogSQLDBParam socketfile /var/lib/mysql/mysql.socket

Context: main server config

This is the new method of specifying Database connection credentials and settings. This is used to define database driver specific options. For a list of options read the documentation for each specific database driver.

Table 5: MySQL Driver parameters

Parameter	Meaning	Default
hostname	MySQL Server hostname	none (use LogSQLLoginInfo to set)
username	The username to log in with	none (use LogSQLLoginInfo to set)
password	The password to use	none (use LogSQLLoginInfo to set)
database	Which database to connect to	none (use LogSQLLoginInfo to set)
port	The TCP port to connect to the MySQL server over	3306 (use LogSQLLoginInfo to set)
socketfile	The MySQL Unix socket file to use	none
tabletype	MySQL Table Engine to use	MySQL server default

Each parameter-name may only be defined once.

LogSQLCreateTables

LogSQLCreateTables flag

Example: LogSQLCreateTables On

Default: Off

Context: main server config

mod_log_sql has the ability to create its tables on-the-fly. The advantage to this is convenience: you don't have to execute any SQL by hand to prepare the table. This is especially helpful for people with lots of virtual hosts (who should also see the LogSQLMassVirtualHosting directive).

There is a slight disadvantage: if you wish to activate this feature, then the userid specified in LogSQLLoginInfo must have CREATE privileges on the database. In an absolutely paranoid, locked-down situation you may only want to grant your mod_log_sql user INSERT privileges on the database; in that situation you are unable to take advantage of LogSQLCreateTables. But most people -- even the very security-conscious -- will find that granting CREATE on the logging database is reasonable.

This is defined only once in the httpd.conf file.

LogSQLForcePreserve

LogSQLForcePreserve flag

Example: LogForcePreserve On

Default: Off

Context: main server config

You may need to perform debugging on your database and specifically want mod_log_sql to make no attempts to log to it. This directive instructs the module to send all its log entries directly to the preserve file and to make no database INSERT attempts.

This is presumably a directive for temporary use only; it could be dangerous if you set it and forget it, as all your entries will simply pile up in the preserve file.

This is defined only once in the httpd.conf file.

LogSQLDisablePreserve

LogSQLDisablePreserve flag

Example: LogDisablePreserve On

Default: Off

Context; main server config

This option can be enabled to completely disable the preserve file fail back. This may be useful for servers where the file-system is read-only.

If the database is not available those log entries will be lost.

This is defined only once in the httpd.conf file.

LogSQLMachineID

LogSQLMachineID machineID

Example: LogSQLMachineID web01

Context: main server config

If you have a farm of webservers then you may wish to know which particular machine made each entry; this is useful for analyzing your load-balancing methodology. LogSQLMachineID permits you to distinguish each machine's entries if you assign each machine its own LogSQLMachineID: for example, the first webserver gets ``LogSQLMachineID web01,'' the second gets ``LogSQLMachineID web02,'' etc.

This is defined only once in the httpd.conf file.

LogSQlPreserveFile

LogSQLPreserveFile filename

Example: LogSQLPreserveFile offline-preserve

Default: /tmp/sql-preserve

Context: virtual host

mod_log_sql writes queries to this local preserve file in the event that it cannot reach the database, and thus ensures that your high-availability web frontend does not lose logs during a temporary database outage. This could happen for a number of reasons: the database goes offline, the network breaks, etc. You will not lose entries since the module has this backup. The file consists of a series of SQL statements that can be imported into your database at your convenience; furthermore, because the SQL queries contain the access timestamps you do not need to worry about out-of-order data after the import, which is done in a simple manner:

# mysql -uadminuser -p mydbname < /tmp/sql-preserve

If you do not define LogSQLPreserveFile then all virtual servers will log to the same default preserve file ( /tmp/sql-preserve ). You can redefine this on a virtual-host basis in order to segregate your preserve files if you desire. Note that segregation is not usually necessary, as the SQL statements that are written to the preserve file already distinguish between different virtual hosts if you include the 'v' character in your LogSQLTransferLogFormat directive. It is only necessary to segregate preserve-files by virualhost if you also segregate access logs by virtualhost.

The module will log to Apache's ErrorLog when it notices a database outage, and upon database return. You will therefore know when the preserve file is being used, although it is your responsibility to import the file.

The file does not need to be created in advance. It is safe to remove or rename the file without interrupting Apache, as the module closes the filehandle immediately after completing the write. The file is created with the user & group ID of the running Apache process (e.g. 'nobody' on many Linux distributions).