summaryrefslogtreecommitdiffstatsabout
path: root/Documentation/manual.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/manual.xml')
-rw-r--r--Documentation/manual.xml274
1 files changed, 143 insertions, 131 deletions
diff --git a/Documentation/manual.xml b/Documentation/manual.xml
index 495b15f..d7dfc12 100644
--- a/Documentation/manual.xml
+++ b/Documentation/manual.xml
@@ -36,6 +36,11 @@
36 </copyright> 36 </copyright>
37 <revhistory> 37 <revhistory>
38 <revision> 38 <revision>
39 <revnumber>1.2</revnumber>
40 <date>2004-04-?</date>
41 <revremark>Updated for mod_log_sql v1.97</revremark>
42 </revision>
43 <revision>
39 <revnumber>1.1</revnumber> 44 <revnumber>1.1</revnumber>
40 <date>2004-03-02</date> 45 <date>2004-03-02</date>
41 <revremark>Updated for mod_log_sql v1.96</revremark> 46 <revremark>Updated for mod_log_sql v1.96</revremark>
@@ -120,50 +125,7 @@
120 </itemizedlist> 125 </itemizedlist>
121 </sect2> 126 </sect2>
122 <sect2> 127 <sect2>
123 <title>Platform Specific Notes</title> 128 <title>Compiling and Installing</title>
124 <remark>This section is currently not applicable as the new autoconf setup should auto-detect everything for your server. The win32 compilation, however, is still on my todo list. This section needs to be overhauled so do not rely completely on any information presented in it. And anyone who compiles the mod_log_sql on these platforms, please report any issues/resolutions to compiling the module.</remark>
125 <para>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.</para>
126 <sect3 id="Sect.Solaris">
127 <title id="Sect.Solaris.title">Solaris</title>
128 <para>The nanosleep() function used in mod_log_sql relies on linking aginst the librt library. Make the following alterations before proceeding: </para>
129 <orderedlist>
130 <listitem>
131 <para>In Makefile, search for the string "-lmysqlclient -lz" and change it to read "-lmysqlclient -lz -lrt"</para>
132 </listitem>
133 <listitem>
134 <para> In part [step:Linking] of section [sec:Static] below, change "-lmysqlclient -lm -lz" to read "-lmysqlclient -lm -lz -lrt"</para>
135 </listitem>
136 </orderedlist>
137 </sect3>
138 <sect3>
139 <title>BSD</title>
140 <para>No notes are available at present, but they are desired. If you have successfully ported mod_log_sql to BSD, please contact &MaintainerContact; and help fill in this section.</para>
141 </sect3>
142 <sect3>
143 <title>Win32</title>
144 <para>No notes are available at present, but they are desired. If you have successfully ported mod_log_sql to Win32, please contact &MaintainerContact; and help fill in this section.</para>
145 </sect3>
146 <sect3>
147 <title>OS X</title>
148 <para>mod_log_sql should compile and work out-of-the-box on this platform. Here are some notes from a user successfully running the module on OS X:</para>
149 <para>The only changes I had to make were to where I had the various libraries installed. Here are the changes I made to the head of the Makefile: APACHESOURCE = /usr/local/src/apache_1.3.27 (Wasn't sure if this was really needed or not, so I downloaded the Apache source just in case) APACHEINSTALLED = /usr/sbin APACHEHEADERS = /usr/include/httpd APXS = $(APACHEINSTALLED)/apxs MYSQLLIBRARIES = /usr/local/mysql/lib MYSQLHEADERS = /usr/local/mysql/include I'm using a binary installation of MySQL and the default apache installation on OS X Client 10.2.3, the locations of these files may vary depending on how you've installed MySQL and will almost certainly be different if you're using OS X Server.</para>
150 <para> My thanks to Tom Wiebe for being the first (to my knowlege) mod_log_sql user on OS X and for providing these notes.</para>
151 </sect3>
152 <sect3>
153 <title>Digital Unix</title>
154 <para>Digital Unix, like Solaris, needs to be linked against librt; see section <xref endterm="Sect.Solaris.title" linkend="Sect.Solaris"/>. Here are further notes from a user successfully running the module on Digital Unix:</para>
155 <para>Instead of trying to get the module to remember where the MySQL libraries were, I instead compiled apache with the information: LDFLAGS='-rpath /isp/mysql/lib/mysql' ./configure ... Everything worked as expected after that. (The error I got without this was "/sbin/loader: Fatal Error: cannot map libmysqlclient.so" ) Digital Unix (v4.0f, at least ) appears to follow the same requirements needed by Solaris, so simply adding librt to the module made it compile without errors. As for the warnings, here's the text: mod_log_sql.c: In function `extract_request_duration': mod_log_sql.c:292: warning: long int format, different type arg (arg 4) mod_log_sql.c: In function `extract_request_timestamp': mod_log_sql.c:497: warning: long int format, different type arg (arg 4) Poking around in the code, it looks like the compiler was complaining that what time() is returning doesn't play nicely with %ld by default. I just typecast them as (long)'s and the warnings went away ( not that the module wasn't working correctly without them ). The module works very well so far in testing... hasn't dropped a single log entry yet. </para>
156 <para>My thanks to Jim Turner for permitting me to quote him here, and for being the first known user of mod_log_sql on Digital Unix</para>
157 </sect3>
158 </sect2>
159 <sect2>
160 <title>Do I want a DSO or a static module</title>
161 <remark>This section is no longer applicable, as the new autoconf setup only allows DSO with Apache 1.3 and 2.0. This section will be removed shortly.</remark>
162 <para>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. </para>
163 <para>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.</para>
164 </sect2>
165 <sect2>
166 <title>Installation as an Apache DSO (preferred)</title>
167 <orderedlist> 129 <orderedlist>
168 <listitem> 130 <listitem>
169 <para>Unpack the archive into a working directory.</para> 131 <para>Unpack the archive into a working directory.</para>
@@ -233,20 +195,23 @@ $ cd mod_log_sql-1.9</screen>
233 </listitem> 195 </listitem>
234 <listitem> 196 <listitem>
235 <para>Now compile the module with GNU make. You may have to specify gmake on some systems like FreeBSD.</para> 197 <para>Now compile the module with GNU make. You may have to specify gmake on some systems like FreeBSD.</para>
236 <screen>$ make</screen> 198 <screen>$ gmake</screen>
237 </listitem> 199 </listitem>
238 <listitem> 200 <listitem>
239 <para>If there were no errors, you can now install the module(s). If you compiled as a non-root user you may need to switch users with <application>su</application> or <application>sudo</application>.</para> 201 <para>If there were no errors, you can now install the module(s). If you compiled as a non-root user you may need to switch users with <application>su</application> or <application>sudo</application>.</para>
240 <screen>$ su -c "make install" 202 <screen>$ su -c "gmake install"
241Password:</screen> 203Password:</screen>
242 </listitem> 204 </listitem>
243 <listitem> 205 <listitem>
244 <para>Now edit your Apache configuration and load the modules.</para> 206 <para>Now edit your Apache configuration and load the modules.</para>
245 <remark>If you are loading the SSL logging module, you need to make sure it is loaded after mod_ssl and mod_log_sql.</remark> 207 <remark>If you are loading the SSL logging module, you need to make sure it is loaded after mod_ssl and mod_log_sql.</remark>
208 <remark>If you have previously used mod_log_sql version 1.18, the name of the module has changed from sql_log_module to log_sql_module (the first parameter to LoadModule)</remark>
209 <remark>If you are upgrading from any release earlier than 1.97 you need to add an extra LoadModule directive to load the database driver (ie mysql).</remark>
246 <orderedlist> 210 <orderedlist>
247 <listitem> 211 <listitem>
248 <para>Insert these lines to either the main <filename>httpd.conf</filename> or a file included via an include directive.</para> 212 <para>Insert these lines to either the main <filename>httpd.conf</filename> or a file included via an include directive.</para>
249 <programlisting>LoadModule log_sql_module modules/mod_log_sql.so 213 <programlisting>LoadModule log_sql_module modules/mod_log_sql.so
214LoadModule log_sql_mysql_module modules/mod_log_sql_mysql.so
250&lt;IfModule mod_ssl.c&gt; 215&lt;IfModule mod_ssl.c&gt;
251LoadModule log_sql_ssl_module moduels/mod_log_sql_ssl.so 216LoadModule log_sql_ssl_module moduels/mod_log_sql_ssl.so
252&lt;/IfModule&gt;</programlisting> 217&lt;/IfModule&gt;</programlisting>
@@ -255,6 +220,7 @@ LoadModule log_sql_ssl_module moduels/mod_log_sql_ssl.so
255 <listitem> 220 <listitem>
256 <para>If you are using Apache 1.3 you may need add these lines later in the configuration.</para> 221 <para>If you are using Apache 1.3 you may need add these lines later in the configuration.</para>
257 <programlisting>AddModule mod_log_sql.c 222 <programlisting>AddModule mod_log_sql.c
223AddModule mod_log_sql_mysql.c
258&lt;IfModule mod_ssl.c&gt; 224&lt;IfModule mod_ssl.c&gt;
259AddModule mod_log_sql_ssl.c 225AddModule mod_log_sql_ssl.c
260&lt;/IfModule&gt;</programlisting> 226&lt;/IfModule&gt;</programlisting>
@@ -312,14 +278,13 @@ mysql&gt; source create_tables.sql</screen>
312 <para>Use the <application>MySQL</application> database called "apachelogs" running on "dbmachine.foo.com". Use username "loguser" and password "l0gg3r" to authenticate to the database. Permit the module create tables for us.</para> 278 <para>Use the <application>MySQL</application> database called "apachelogs" running on "dbmachine.foo.com". Use username "loguser" and password "l0gg3r" to authenticate to the database. Permit the module create tables for us.</para>
313 <example> 279 <example>
314 <title>Basic Example</title> 280 <title>Basic Example</title>
315 <programlisting>LogSQLLoginInfo dbmachine.foo.com loguser l0gg3r 281 <programlisting>LogSQLLoginInfo mysql://loguser;l0gg3r@dbmachine.foo.com/apachelogs
316LogSQLDatabase apachelogs
317LogSQLCreateTables on</programlisting> 282LogSQLCreateTables on</programlisting>
318 </example> 283 </example>
319 <para>If your database resides on localhost instead of another host, specify the MySQL server's socket file as follows:</para> 284 <para>If your database resides on localhost instead of another host, specify the MySQL server's socket file as follows:</para>
320 <programlisting>LogSQLSocketFile /your/path/to/mysql.sock</programlisting> 285 <programlisting>LogSQLDBParam socketfile /your/path/to/mysql.sock</programlisting>
321 <para>If your database is listening on a port other than 3306, specify the correct TCP port as follows:</para> 286 <para>If your database is listening on a port other than 3306, specify the correct TCP port as follows:</para>
322 <programlisting>LogSQLTCPPort 1234</programlisting> 287 <programlisting>LogSQLDBParam port 1234</programlisting>
323 </listitem> 288 </listitem>
324 <listitem> 289 <listitem>
325 <para>The actual logging is set up on a virtual-host-by-host basis. So, skip down to the virtual host you want to set up. Instruct this virtual host to log entries to the table "access_log" by inserting a LogSQLTransferLogTable directive. (The LogSQLTransferLogTable directive is the minimum required to log -- other directives that you will learn about later simply tune the module's behavior.)</para> 290 <para>The actual logging is set up on a virtual-host-by-host basis. So, skip down to the virtual host you want to set up. Instruct this virtual host to log entries to the table "access_log" by inserting a LogSQLTransferLogTable directive. (The LogSQLTransferLogTable directive is the minimum required to log -- other directives that you will learn about later simply tune the module's behavior.)</para>
@@ -635,18 +600,55 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
635 <varlistentry> 600 <varlistentry>
636 <term>LogSQLLoginInfo</term> 601 <term>LogSQLLoginInfo</term>
637 <listitem> 602 <listitem>
638 <cmdsynopsis sepchar=" "> 603 <cmdsynopsis>
639 <command moreinfo="none">LogSQLLoginInfo</command> 604 <command>LogSQLLoginInfo</command>
640 <arg choice="req" rep="norepeat"><replaceable>host</replaceable></arg> 605 <arg choice="req"><replaceable>connection URI</replaceable></arg>
641 <arg choice="req" rep="norepeat"><replaceable>user</replaceable></arg>
642 <arg choice="req" rep="norepeat"><replaceable>password</replaceable></arg>
643 </cmdsynopsis> 606 </cmdsynopsis>
644 <simpara>Example: LogSQLLoginInfo foobar.baz.com logwriter passw0rd</simpara> 607 <simpara>Example: LogSQLLoginInfo mysql://logwriter:passw0rd@foobar.baz.com/Apache_log</simpara>
645 <simpara>Context: main server config</simpara> 608 <simpara>Context: main server config</simpara>
646 <para>Defines the general parameters of the MySQL host to which you will be logging. "host" is the hostname or IP address of the MySQL machine, and is simply "localhost" if the database lives on the same machine as Apache. "user" is the MySQL userid (not a Unix userid!) with INSERT privileges on the table defined in LogSQLTransferLogTable. "password" is that user's password.</para> 609 <para>Defines the basic connection URI to connect to the database with. The format of the connection URI is</para>
610 <simpara>driver://username[:password]@hostname[:port]/database</simpara>
611 <variablelist>
612 <varlistentry>
613 <term>driver</term>
614 <listitem>
615 <simpara>The database driver to use (mysql, pgsql, etc..)</simpara>
616 </listitem>
617 </varlistentry>
618 <varlistentry>
619 <term>username</term>
620 <listitem>
621 <simpara>The database username to login with INSERT privileges on the logging table defined in LogSQLtransferLogTable.</simpara>
622 </listitem>
623 </varlistentry>
624 <varlistentry>
625 <term>password</term>
626 <listitem>
627 <simpara>The password to use for username, and can be omitted if there is no password.</simpara>
628 </listitem>
629 </varlistentry>
630 <varlistentry>
631 <term>hostname</term>
632 <listitem>
633 <simpara>The hostname or Ip address of the Database machine, ans is simple "localhost" if the database lives on the same machine as Apache.</simpara>
634 </listitem>
635 </varlistentry>
636 <varlistentry>
637 <term>port</term>
638 <listitem>
639 <simpara>Port on hostname to connect to the Database, if not specified use the default port for the database.</simpara>
640 </listitem>
641 </varlistentry>
642 <varlistentry>
643 <term>database</term>
644 <listitem>
645 <simpara>The database to connect to on the server.</simpara>
646 </listitem>
647 </varlistentry>
648 </variablelist>
647 <note> 649 <note>
648 <para>This is defined only once in the <filename moreinfo="none">httpd.conf</filename> file.</para> 650 <para>This is defined only once in the <filename moreinfo="none">httpd.conf</filename> file.</para>
649 <para>This directive Must be defined for logging to be enabled. Or the use of LogSQLDBParam</para> 651 <para>This directive Must be defined for logging to be enabled.</para>
650 </note> 652 </note>
651 </listitem> 653 </listitem>
652 </varlistentry> 654 </varlistentry>
@@ -658,12 +660,11 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
658 <arg choice="req" rep="norepeat"><replaceable>parameter-name</replaceable></arg> 660 <arg choice="req" rep="norepeat"><replaceable>parameter-name</replaceable></arg>
659 <arg choice="req" rep="norepeat"><replaceable>value</replaceable></arg> 661 <arg choice="req" rep="norepeat"><replaceable>value</replaceable></arg>
660 </cmdsynopsis> 662 </cmdsynopsis>
661 <simpara>Example: LogSQLDBParam database loggingdb</simpara> 663 <simpara>Example: LogSQLDBParam socketfile /var/lib/mysql/mysql.socket</simpara>
662 <simpara>Context: main server config</simpara> 664 <simpara>Context: main server config</simpara>
663 <para>This is the new method of specifying Database connection credentials and settings. This can be used to define all Database specific options and allows for a specific database driver to define new configuration attributes without modifying the mod_log_sql core. This is the preferred configuration mechanism.</para> 665 <para>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.</para>
664 <note> 666 <note>
665 <para>Each parameter-name may only be defined once.</para> 667 <para>Each parameter-name may only be defined once.</para>
666 <para>Either this directive defining the minimum of 'database','host','user','passwd' or the use of LogSQlLoginInfo and LogSQLDatabase</para>
667 </note> 668 </note>
668 </listitem> 669 </listitem>
669 </varlistentry> 670 </varlistentry>
@@ -685,60 +686,6 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
685 </listitem> 686 </listitem>
686 </varlistentry> 687 </varlistentry>
687 <varlistentry> 688 <varlistentry>
688 <term>LogSQLSocketFile [Deprecated]</term>
689 <listitem>
690 <cmdsynopsis sepchar=" ">
691 <command moreinfo="none">LogSQLSocketFile</command>
692 <arg choice="req" rep="norepeat"><replaceable>filename</replaceable></arg>
693 </cmdsynopsis>
694 <simpara>Example: LogSQLSocketFile /tmp/mysql.sock</simpara>
695 <simpara>Default: (database specific)</simpara>
696 <simpara>Default (MySQL): /var/lib/mysql/mysql.sock</simpara>
697 <simpara>Context: main server config</simpara>
698 <para>At Apache runtime you can specify the MySQL socket file to use. Set this once in your main server config to override the default value. This value is irrelevant if your database resides on a separate machine.</para>
699 <para>mod_log_sql will automatically employ the socket for db communications if the database resides on the local host. If the db resides on a separate host the module will automatically use TCP/IP. This is a function of the MySQL API and is not user-configurable.</para>
700 <note>
701 <para>This directive is deprecated in favor of LogSQLDBParam socketfile [socketfilename]</para>
702 <para>This is defined only once in the <filename moreinfo="none">httpd.conf</filename> file.</para>
703 </note>
704 </listitem>
705 </varlistentry>
706 <varlistentry>
707 <term>LogSQLTCPPort [Deprecated]</term>
708 <listitem>
709 <cmdsynopsis sepchar=" ">
710 <command moreinfo="none">LogSQLTCPPort</command>
711 <arg choice="req" rep="norepeat"><replaceable>port-number</replaceable></arg>
712 </cmdsynopsis>
713 <simpara>Example: LogSQLTCPPort 3309</simpara>
714 <simpara>Default: (database specific)</simpara>
715 <simpara>Default (MySQL): 3306</simpara>
716 <simpara>Context: main server config</simpara>
717 <para>Your database may listen on a different port than the default. If so, use this directive to instruct the module which port to use. This directive only applies if the database is on a different machine connected via TCP/IP.</para>
718 <note>
719 <para>This directive is deprecated in favor of LogSQLDBParam tcpport [port-number]</para>
720 <para>This is defined only once in the <filename moreinfo="none">httpd.conf</filename> file.</para>
721 </note>
722 </listitem>
723 </varlistentry>
724 <varlistentry>
725 <term>LogSQLDatabase [Deprecated]</term>
726 <listitem>
727 <cmdsynopsis sepchar=" ">
728 <command moreinfo="none">LogSQLDatabase</command>
729 <arg choice="req" rep="norepeat"><replaceable>database</replaceable></arg>
730 </cmdsynopsis>
731 <simpara>Example: LogSQLDatabase loggingdb</simpara>
732 <simpara>Context: main server config</simpara>
733 <para>Defines the database that is used for logging. "database" must be a valid db on the MySQL host defined in LogSQLLoginInfo</para>
734 <note>
735 <para>This directive is deprecated in favor of LogSQLDBParam database [database-name]</para>
736 <para>This is defined only once in the <filename moreinfo="none">httpd.conf</filename> file.</para>
737 <para>This directive Must be defined for logging to be enabled.</para>
738 </note>
739 </listitem>
740 </varlistentry>
741 <varlistentry>
742 <term>LogSQLForcePreserve</term> 689 <term>LogSQLForcePreserve</term>
743 <listitem> 690 <listitem>
744 <cmdsynopsis sepchar=" "> 691 <cmdsynopsis sepchar=" ">
@@ -801,7 +748,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
801 </cmdsynopsis> 748 </cmdsynopsis>
802 <simpara>Example: LogSQLTransferLogTable access_log_table</simpara> 749 <simpara>Example: LogSQLTransferLogTable access_log_table</simpara>
803 <simpara>Context: virtual host</simpara> 750 <simpara>Context: virtual host</simpara>
804 <para>Defines which table is used for logging of Apache's transfers; this is analogous to Apache's TransferLog directive. table-name must be a valid table within the database defined in LogSQLDatabase.</para> 751 <para>Defines which table is used for logging of Apache's transfers; this is analogous to Apache's TransferLog directive. table-name must be a valid table within the database defined in the LogSQLLoginInfo connection URI.</para>
805 <para>This directive is <emphasis>not</emphasis> necessary if you declare LogSQLMassVirtualHosting On, since that directive activates dynamically-named tables. If you attempt to use LogSqlTransferlogTable at the same time a warning will be logged and it will be ignored, since LogSQLMassVirtualHosting takes priority.</para> 752 <para>This directive is <emphasis>not</emphasis> necessary if you declare LogSQLMassVirtualHosting On, since that directive activates dynamically-named tables. If you attempt to use LogSqlTransferlogTable at the same time a warning will be logged and it will be ignored, since LogSQLMassVirtualHosting takes priority.</para>
806 <note> 753 <note>
807 <para>Requires unless LogSQLMassVirtualHosting is set to On</para> 754 <para>Requires unless LogSQLMassVirtualHosting is set to On</para>
@@ -905,6 +852,20 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
905 <sect3> 852 <sect3>
906 <title>Configuring What Is logged</title> 853 <title>Configuring What Is logged</title>
907 <variablelist> 854 <variablelist>
855 <varlistentry id="Conf.LogSQLTransferLogFormat">
856 <term>LogSQLTransferLogFormat </term>
857 <listitem>
858 <cmdsynopsis sepchar=" ">
859 <command moreinfo="none">LogSQLTransferLogFormat</command>
860 <arg choice="req" rep="norepeat"><replaceable>format-string</replaceable></arg>
861 </cmdsynopsis>
862 <simpara>Example: LogSQLTransferLogFormat huSUTv</simpara>
863 <simpara>Default: AbHhmRSsTUuv</simpara>
864 <simpara>Context: virtual host</simpara>
865 <para>Each character in the format-string defines an attribute of the request that you wish to log. The default logs the information required to create Combined Log Format logs, plus several extras. Here is the full list of allowable keys, which sometimes resemble their Apache counterparts, but do not always:</para>
866 <para>TODO: Insert Log Format Types Table</para>
867 </listitem>
868 </varlistentry>
908 <varlistentry> 869 <varlistentry>
909 <term>LogSQLRemhostIgnore</term> 870 <term>LogSQLRemhostIgnore</term>
910 <listitem> 871 <listitem>
@@ -915,6 +876,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
915 <simpara>Example: LogSQLRemhostIgnore localnet.com</simpara> 876 <simpara>Example: LogSQLRemhostIgnore localnet.com</simpara>
916 <simpara>Context: virtual host</simpara> 877 <simpara>Context: virtual host</simpara>
917 <para>Lists a series of strings that, if present in the REMOTE_HOST, will cause that request to <emphasis>not</emphasis> be logged. This directive is useful for cutting down on log clutter when you are certain that you want to ignore requests from certain hosts, such as your own internal network machines. See section <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore"/> for some tips for using this directive.</para> 878 <para>Lists a series of strings that, if present in the REMOTE_HOST, will cause that request to <emphasis>not</emphasis> be logged. This directive is useful for cutting down on log clutter when you are certain that you want to ignore requests from certain hosts, such as your own internal network machines. See section <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore"/> for some tips for using this directive.</para>
879 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para>
918 <para>Each string is separated by a space, and no regular expressions or globbing are allowed. Each string is evaluated as a substring of the REMOTE_HOST using strstr(). The comparison is case sensitive.</para> 880 <para>Each string is separated by a space, and no regular expressions or globbing are allowed. Each string is evaluated as a substring of the REMOTE_HOST using strstr(). The comparison is case sensitive.</para>
919 </listitem> 881 </listitem>
920 </varlistentry> 882 </varlistentry>
@@ -929,6 +891,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
929 <simpara>Default: if not specified, all requests are 'accepted'</simpara> 891 <simpara>Default: if not specified, all requests are 'accepted'</simpara>
930 <simpara>Context: virtual host</simpara> 892 <simpara>Context: virtual host</simpara>
931 <para>Lists a series of strings that, if present in the URI, will permit that request to be considered for logging (depending on additional filtering by the "ignore" directives). Any request that fails to match one of the LogSQLRequestAccept entries will be discarded.</para> 893 <para>Lists a series of strings that, if present in the URI, will permit that request to be considered for logging (depending on additional filtering by the "ignore" directives). Any request that fails to match one of the LogSQLRequestAccept entries will be discarded.</para>
894 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para>
932 <para>This directive is useful for cutting down on log clutter when you are certain that you only want to log certain kinds of requests, and just blanket-ignore everything else. See section <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore"/> for some tips for using this directive.</para> 895 <para>This directive is useful for cutting down on log clutter when you are certain that you only want to log certain kinds of requests, and just blanket-ignore everything else. See section <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore"/> for some tips for using this directive.</para>
933 <para>Each string is separated by a space, and no regular expressions or globbing are allowed. Each string is evaluated as a substring of the URI using strstr(). The comparison is case sensitive.</para> 896 <para>Each string is separated by a space, and no regular expressions or globbing are allowed. Each string is evaluated as a substring of the URI using strstr(). The comparison is case sensitive.</para>
934 <para>This directive is completely optional. It is more general than LogSQLRequestIgnore and is evaluated before LogSQLRequestIgnore . If this directive is not used, <emphasis>all</emphasis> requests are accepted and passed on to the other filtering directives. Therefore, only use this directive if you have a specific reason to do so.</para> 897 <para>This directive is completely optional. It is more general than LogSQLRequestIgnore and is evaluated before LogSQLRequestIgnore . If this directive is not used, <emphasis>all</emphasis> requests are accepted and passed on to the other filtering directives. Therefore, only use this directive if you have a specific reason to do so.</para>
@@ -944,23 +907,10 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
944 <simpara>Example: LogSQLRequestIgnore root.exe cmd.exe default.ida favicon.ico</simpara> 907 <simpara>Example: LogSQLRequestIgnore root.exe cmd.exe default.ida favicon.ico</simpara>
945 <simpara>Context: virtual host</simpara> 908 <simpara>Context: virtual host</simpara>
946 <para>Lists a series of strings that, if present in the URI, will cause that request to <emphasis>NOT</emphasis> be logged. This directive is useful for cutting down on log clutter when you are certain that you want to ignore requests for certain objects. See section <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore"/> for some tips for using this directive.</para> 909 <para>Lists a series of strings that, if present in the URI, will cause that request to <emphasis>NOT</emphasis> be logged. This directive is useful for cutting down on log clutter when you are certain that you want to ignore requests for certain objects. See section <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore"/> for some tips for using this directive.</para>
910 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para>
947 <para>Each string is separated by a space, and no regular expressions or globbing are allowed. Each string is evaluated as a substring of the URI using strstr(). The comparison is case sensitive.</para> 911 <para>Each string is separated by a space, and no regular expressions or globbing are allowed. Each string is evaluated as a substring of the URI using strstr(). The comparison is case sensitive.</para>
948 </listitem> 912 </listitem>
949 </varlistentry> 913 </varlistentry>
950 <varlistentry id="Conf.LogSQLTransferLogFormat">
951 <term>LogSQLTransferLogFormat </term>
952 <listitem>
953 <cmdsynopsis sepchar=" ">
954 <command moreinfo="none">LogSQLTransferLogFormat</command>
955 <arg choice="req" rep="norepeat"><replaceable>format-string</replaceable></arg>
956 </cmdsynopsis>
957 <simpara>Example: LogSQLTransferLogFormat huSUTv</simpara>
958 <simpara>Default: AbHhmRSsTUuv</simpara>
959 <simpara>Context: virtual host</simpara>
960 <para>Each character in the format-string defines an attribute of the request that you wish to log. The default logs the information required to create Combined Log Format logs, plus several extras. Here is the full list of allowable keys, which sometimes resemble their Apache counterparts, but do not always:</para>
961 <para>TODO: Insert Log Format Types Table</para>
962 </listitem>
963 </varlistentry>
964 <varlistentry> 914 <varlistentry>
965 <term>LogSQLWhichCookie</term> 915 <term>LogSQLWhichCookie</term>
966 <listitem> 916 <listitem>
@@ -988,6 +938,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
988 <simpara>Example: logSQLWhichCookies userlogin cookie1 cookie2</simpara> 938 <simpara>Example: logSQLWhichCookies userlogin cookie1 cookie2</simpara>
989 <simpara>Context: virtual host</simpara> 939 <simpara>Context: virtual host</simpara>
990 <para>Defines the list of cookies you would like logged. This works in conjunction with LogSQLCookieLogTable. This directive does <emphasis>not</emphasis> require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate cookie table with data.</para> 940 <para>Defines the list of cookies you would like logged. This works in conjunction with LogSQLCookieLogTable. This directive does <emphasis>not</emphasis> require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate cookie table with data.</para>
941 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para>
991 <note> 942 <note>
992 <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para> 943 <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para>
993 </note> 944 </note>
@@ -1003,6 +954,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
1003 <simpara>Example: LogSQLWhichHeadersIn UserAgent Accept-Encodeing Host</simpara> 954 <simpara>Example: LogSQLWhichHeadersIn UserAgent Accept-Encodeing Host</simpara>
1004 <simpara>Context: virtual host</simpara> 955 <simpara>Context: virtual host</simpara>
1005 <para>Defines the list of inbound headers you would like logged. This works in conjunction with LogSQLHeadersInLogTable. This directive does not require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate inbound-headers table with data.</para> 956 <para>Defines the list of inbound headers you would like logged. This works in conjunction with LogSQLHeadersInLogTable. This directive does not require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate inbound-headers table with data.</para>
957 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para>
1006 <note> 958 <note>
1007 <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para> 959 <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para>
1008 </note> 960 </note>
@@ -1018,6 +970,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
1018 <simpara>Example: LogSQLWhichHeadersOut Expires Content-Type Cache-Control</simpara> 970 <simpara>Example: LogSQLWhichHeadersOut Expires Content-Type Cache-Control</simpara>
1019 <simpara>Context: virtual host</simpara> 971 <simpara>Context: virtual host</simpara>
1020 <para>Defines the list of outbound headers you would like logged. This works in conjunction with LogSQLHeadersOutLogTable. This directive does not require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate outbound-headers table with data.</para> 972 <para>Defines the list of outbound headers you would like logged. This works in conjunction with LogSQLHeadersOutLogTable. This directive does not require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate outbound-headers table with data.</para>
973 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para>
1021 <note> 974 <note>
1022 <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para> 975 <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para>
1023 </note> 976 </note>
@@ -1033,6 +986,7 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
1033 <simpara>Example: LogSQLWhichNotes mod_gzip_result mod_gzip_ompression_ratio</simpara> 986 <simpara>Example: LogSQLWhichNotes mod_gzip_result mod_gzip_ompression_ratio</simpara>
1034 <simpara>Context: virtual host</simpara> 987 <simpara>Context: virtual host</simpara>
1035 <para>Defines the list of notes you would like logged. This works in conjunction with LogSQLNotesLogTable. This directive does not require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate notes table with data.</para> 988 <para>Defines the list of notes you would like logged. This works in conjunction with LogSQLNotesLogTable. This directive does not require any additional characters to be added to the LogSQLTransferLogFormat string. The feature is activated simply by including this directive, upon which you will begin populating the separate notes table with data.</para>
989 <para>Each string may contain a + or - prefix in a &lt;VirtualHost&gt; context and will cause those strings to be added (+) or removed (-) from the global configuration. Otherwise the global is completely ignored and overridden if defined in a &lt;VirtualHost&gt;</para>
1036 <note> 990 <note>
1037 <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para> 991 <para>The table must be created (see create-tables.sql, included in the package), or LogSQLCreateTables must be set to 'On'.</para>
1038 </note> 992 </note>
@@ -1040,6 +994,64 @@ where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';</screen>
1040 </varlistentry> 994 </varlistentry>
1041 </variablelist> 995 </variablelist>
1042 </sect3> 996 </sect3>
997 <sect3>
998 <title>Deprecated Command</title>
999 <variablelist>
1000 <varlistentry>
1001 <term>LogSQLSocketFile [Deprecated]</term>
1002 <listitem>
1003 <cmdsynopsis sepchar=" ">
1004 <command moreinfo="none">LogSQLSocketFile</command>
1005 <arg choice="req" rep="norepeat"><replaceable>filename</replaceable></arg>
1006 </cmdsynopsis>
1007 <simpara>Example: LogSQLSocketFile /tmp/mysql.sock</simpara>
1008 <simpara>Default: (database specific)</simpara>
1009 <simpara>Default (MySQL): /var/lib/mysql/mysql.sock</simpara>
1010 <simpara>Context: main server config</simpara>
1011 <para>At Apache runtime you can specify the MySQL socket file to use. Set this once in your main server config to override the default value. This value is irrelevant if your database resides on a separate machine.</para>
1012 <para>mod_log_sql will automatically employ the socket for db communications if the database resides on the local host. If the db resides on a separate host the module will automatically use TCP/IP. This is a function of the MySQL API and is not user-configurable.</para>
1013 <note>
1014 <para>This directive is deprecated in favor of LogSQLDBParam socketfile [socketfilename]</para>
1015 <para>This is defined only once in the <filename moreinfo="none">httpd.conf</filename> file.</para>
1016 </note>
1017 </listitem>
1018 </varlistentry>
1019 <varlistentry>
1020 <term>LogSQLTCPPort [Deprecated]</term>
1021 <listitem>
1022 <cmdsynopsis sepchar=" ">
1023 <command moreinfo="none">LogSQLTCPPort</command>
1024 <arg choice="req" rep="norepeat"><replaceable>port-number</replaceable></arg>
1025 </cmdsynopsis>
1026 <simpara>Example: LogSQLTCPPort 3309</simpara>
1027 <simpara>Default: (database specific)</simpara>
1028 <simpara>Default (MySQL): 3306</simpara>
1029 <simpara>Context: main server config</simpara>
1030 <para>Your database may listen on a different port than the default. If so, use this directive to instruct the module which port to use. This directive only applies if the database is on a different machine connected via TCP/IP.</para>
1031 <note>
1032 <para>This directive is deprecated in favor of LogSQLDBParam tcpport [port-number]</para>
1033 <para>This is defined only once in the <filename moreinfo="none">httpd.conf</filename> file.</para>
1034 </note>
1035 </listitem>
1036 </varlistentry>
1037 <varlistentry>
1038 <term>LogSQLDatabase [Deprecated]</term>
1039 <listitem>
1040 <cmdsynopsis sepchar=" ">
1041 <command moreinfo="none">LogSQLDatabase</command>
1042 <arg choice="req" rep="norepeat"><replaceable>database</replaceable></arg>
1043 </cmdsynopsis>
1044 <simpara>Example: LogSQLDatabase loggingdb</simpara>
1045 <simpara>Context: main server config</simpara>
1046 <para>Defines the database that is used for logging. "database" must be a valid db on the MySQL host defined in LogSQLLoginInfo</para>
1047 <note>
1048 <para>This directive is deprecated in favor of the URI form of LogSQLLoginInfo.</para>
1049 <para>This is defined only once in the <filename moreinfo="none">httpd.conf</filename> file.</para>
1050 </note>
1051 </listitem>
1052 </varlistentry>
1053 </variablelist>
1054 </sect3>
1043 </sect2> 1055 </sect2>
1044 </sect1> 1056 </sect1>
1045 <sect1> 1057 <sect1>
@@ -1314,7 +1326,7 @@ ErrorLog /var/log/httpd/server-messages </programlisting>
1314 <para>Why do I get the message "insufficient configuration info to establish database link" in my Apache error log?</para> 1326 <para>Why do I get the message "insufficient configuration info to establish database link" in my Apache error log?</para>
1315 </question> 1327 </question>
1316 <answer> 1328 <answer>
1317 <para>At a minimum, LogSQLDatabase and LogSQLLoginInfo and either LogSQLTableName or LogSQLMassVirtualHosting must be defined in order for the module to be able to establish a database link. If these are not defined or are incomplete you will receive this error message.</para> 1329 <para>At a minimum, LogSQLLoginInfo in the URl form and either LogSQLTableName or LogSQLMassVirtualHosting must be defined in order for the module to be able to establish a database link. If these are not defined or are incomplete you will receive this error message.</para>
1318 </answer> 1330 </answer>
1319 </qandaentry> 1331 </qandaentry>
1320 <qandaentry> 1332 <qandaentry>