summaryrefslogtreecommitdiffstatsabout
diff options
context:
space:
mode:
authorEdward Rudd <urkle@outoforder.cc>2011-07-21 23:10:20 (GMT)
committer Edward Rudd <urkle@outoforder.cc>2011-07-21 23:10:38 (GMT)
commitf1fd1c9714256bb9b212462dd31ca6dc56ea31ef (patch)
tree6d3aaaf843f758f5cd7dd2dc7641dca6ed4badca
add in project web page
Diffstat
-rw-r--r--docs-2.0/index.xml11
-rw-r--r--docs-2.0/manual.xml3927
-rw-r--r--docs/contents.pngbin0 -> 278 bytes
-rw-r--r--docs/crossref.pngbin0 -> 147 bytes
-rw-r--r--docs/documentation.css33
-rw-r--r--docs/documentation.html269
-rw-r--r--docs/img1.pngbin0 -> 154 bytes
-rw-r--r--docs/img2.pngbin0 -> 214 bytes
-rw-r--r--docs/img3.pngbin0 -> 318 bytes
-rw-r--r--docs/img4.pngbin0 -> 564 bytes
-rw-r--r--docs/index.html269
-rw-r--r--docs/next.pngbin0 -> 245 bytes
-rw-r--r--docs/next_g.pngbin0 -> 272 bytes
-rw-r--r--docs/node1.html128
-rw-r--r--docs/node2.html276
-rw-r--r--docs/node3.html664
-rw-r--r--docs/node4.html2014
-rw-r--r--docs/node5.html1270
-rw-r--r--docs/node6.html74
-rw-r--r--docs/prev.pngbin0 -> 279 bytes
-rw-r--r--docs/prev_g.pngbin0 -> 327 bytes
-rw-r--r--docs/style_1.css33
-rw-r--r--docs/up.pngbin0 -> 211 bytes
-rw-r--r--docs/up_g.pngbin0 -> 231 bytes
-rw-r--r--index.xml260
25 files changed, 9228 insertions, 0 deletions
diff --git a/docs-2.0/index.xml b/docs-2.0/index.xml
new file mode 100644
index 0000000..e04d194
--- /dev/null
+++ b/docs-2.0/index.xml
@@ -0,0 +1,11 @@
1<?xml version="1.0"?>
2<?xml-stylesheet type="text/xsl" href="../../../../../xsl/projects.xsl"?>
3<ooo title="mod_log_sql 2.0 Documentation" path="/projects/apache/mod_log_sql/docs-2.0/">
4 <content type="docbook" mode="article">
5 <xi:include href="manual.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
6 <xi:fallback>
7 <para>Error loading XML Documentation</para>
8 </xi:fallback>
9 </xi:include>
10 </content>
11</ooo>
diff --git a/docs-2.0/manual.xml b/docs-2.0/manual.xml
new file mode 100644
index 0000000..9019e80
--- /dev/null
+++ b/docs-2.0/manual.xml
@@ -0,0 +1,3927 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<?xml-stylesheet href="file://localhost/home/urkle/Documents/DocBook/docbook.css" type="text/css"?>
3<!DOCTYPE article PUBLIC "-//OOOCC//DTD Simplified DocBook XML V1.1 Variant V1.0//EN" "http://outoforder.cc/dtds/odocbook/1.1/odocbook.dtd" [
4<!ENTITY EmailContact "<email>urkle &lt;at&gt; outoforder &lt;dot&gt; cc</email>">
5]>
6<article>
7 <articleinfo>
8 <title>mod_log_sql Manual</title>
9 <author>
10 <firstname>Edward</firstname>
11 <surname>Rudd</surname>
12 <contrib>Conversion from Lyx to DocBook</contrib>
13 <contrib>Current Maintainer</contrib>
14 <authorblurb>
15 <simpara>
16 &EmailContact;
17 </simpara>
18 </authorblurb>
19 </author>
20 <author>
21 <firstname>Christopher</firstname>
22 <othername>B.</othername>
23 <surname>Powell</surname>
24 <contrib>Original documentation author.</contrib>
25 <authorblurb>
26 <simpara>
27 <email>chris &lt;at&gt; grubbybaby &lt;dot&gt; com</email>
28 </simpara>
29 </authorblurb>
30 </author>
31 <copyright>
32 <year>2001</year>
33 <year>2002</year>
34 <year>2003</year>
35 <holder>Christopher B. Powell</holder>
36 </copyright>
37 <copyright>
38 <year>2004</year>
39 <year>2005</year>
40 <year>2006</year>
41 <holder>Edward Rudd</holder>
42 </copyright>
43 <revhistory>
44 <revision>
45 <revnumber>1.5</revnumber>
46 <date>2006-11-04</date>
47 <revremark>Added documentation about logio parameters and added DBParam Mysql driver parameters (including tabletype)</revremark>
48 </revision>
49 <revision>
50 <revnumber>1.4</revnumber>
51 <date>2006-02-13</date>
52 <revremark>Added missing logformat types, switched to simplified docbook 1.1</revremark>
53 </revision>
54 <revision>
55 <revnumber>1.3</revnumber>
56 <date>2005-01-11</date>
57 <revremark>Updated for mod_log_sql v1.100</revremark>
58 </revision>
59 <revision>
60 <revnumber>1.2</revnumber>
61 <date>2004-04-08</date>
62 <revremark>Updated for mod_log_sql v1.97</revremark>
63 </revision>
64 <revision>
65 <revnumber>1.1</revnumber>
66 <date>2004-03-02</date>
67 <revremark>Updated for mod_log_sql v1.96</revremark>
68 </revision>
69 <revision>
70 <revnumber>1.0</revnumber>
71 <date>2004-01-22</date>
72 <revremark>Initial Conversion from Lyx to Docbook</revremark>
73 </revision>
74 </revhistory>
75 </articleinfo>
76 <section>
77 <title>Introduction</title>
78 <section tocstyle="fragment">
79 <title>Summary</title>
80 <para>
81 This Apache module will permit you to log to a SQL database; it
82 can log each access request as well as data associated with each
83 request: cookies, notes, and inbound/outbound headers. Unlike
84 logging to a flat text file -- which is standard in Apache -- a
85 SQL-based log exhibits tremendous flexibility and power of data
86 extraction. (See FAQ entry
87 <xref linkend="FAQ.WhyLogToSQL" />
88 for further discussion and examples of the advantages to SQL.)
89 </para>
90 <para>
91 This module can either replace or happily coexist with
92 mod_log_config, Apache's text file logging facility. In addition
93 to being more configurable than the standard module, mod_log_sql
94 is much more flexible.
95 </para>
96 </section>
97 <section tocstyle="fragment">
98 <title>Approach</title>
99 <para>
100 This project was formerly known as "mod_log_mysql." It was
101 renamed "mod_log_sql" in order to reflect the project goal of
102 database in-specificity. The module currently supports MySQL,
103 but support for other database back-ends is underway.
104 </para>
105 <para>
106 In order to save speed and overhead, links are kept alive in
107 between queries. This module uses one dedicated SQL link per
108 httpd child, opened by each child process when it is born. Among
109 other things, this means that this module supports logging into
110 only one MySQL server, and for now, also, only one SQL database.
111 But that's a small tradeoff compared to the blinding speed of
112 this module. Error reporting is robust throughout the module and
113 will inform the administrator of database issues in the Apache
114 ErrorLog for the server/virtual server.
115 </para>
116 <para>
117 Virtual hosts are supported in the same manner they are in the
118 regular logging modules. The administrator defines some basic
119 'global' directives in the main server config, then defines more
120 specific 'local' directives inside each VirtualHost stanza.
121 </para>
122 <para>
123 A robust "preserve" capability has now been implemented. This
124 permits the module to preserve any failed INSERT commands to a
125 local file on its machine. In any situation that the database is
126 unavailable -- e.g. the network fails or the database host is
127 rebooted -- mod_log_sql will note this in the error log and
128 begin appending its log entries to the preserve file (which is
129 created with the user and group ID of the running Apache
130 process, e.g. "nobody/nobody" on many Linux installations). When
131 database availability returns, mod_log_sql seamlessly resumes
132 logging to it. When convenient for the sysadmin, he/she can
133 easily import the preserve file into the database because it is
134 simply a series of SQL insert statements.
135 </para>
136 </section>
137 <section tocstyle="fragment">
138 <title>What gets logged by default?</title>
139 <para>
140 All the data that would be contained in the "Combined Log
141 Format" is logged by default, plus a little extra. Your best bet
142 is to begin by accepting this default, then later customize the
143 log configuration based on your needs. The documentation of the
144 run-time directives includes a full explanation of what you can
145 log, including examples -- see section
146 <xref endterm="Sect.ConfigReference.title"
147 linkend="Sect.ConfigReference" />
148 .
149 </para>
150 </section>
151 <section tocstyle="fragment">
152 <title>Miscellaneous Notes</title>
153 <itemizedlist>
154 <listitem>
155 <para>
156 Note which directives go in the 'main server config' and
157 which directives apply to the 'virtual host config'. This is
158 made clear in the directive documentation.
159 </para>
160 </listitem>
161 <listitem>
162 <para>
163 The 'time_stamp' field is stored in an UNSIGNED INTEGER
164 format, in the standard unix "seconds since the epoch"
165 format. This is superior to storing the access time as a
166 string due to size requirements: an UNSIGNED INT requires 4
167 bytes, whereas an Apache date string (e.g.
168 "18/Nov/2001:13:59:52 -0800") requires 26 bytes: those extra
169 22 bytes become significant when multiplied by thousands of
170 accesses on a busy server. Besides, an INT type is far more
171 flexible for comparisons, etc.
172 </para>
173 <para>
174 In MySQL 3.21 and above you can easily convert this to a
175 human readable format using from_unixtime(), e.g.:
176 </para>
177 <programlisting>SELECT remote_host,request_uri,from_unixtime(time_stamp)
178FROM access_log;</programlisting>
179 <para>
180 The enclosed perl program "make_combined_log.pl" extracts
181 your access log in a format that is completely compatible
182 with the Combined Log Format. You can then feed this to your
183 favorite web log analysis tool.
184 </para>
185 </listitem>
186 <listitem>
187 <para>
188 The table's string values can be CHAR or VARCHAR, at a
189 length of your choice. VARCHAR is superior because it
190 truncates long strings; CHAR types are fixed-length and will
191 be padded with spaces, resulting in waste. Just like the
192 time_stamp issue described above, that kind of space waste
193 multiplies over thousands of records.
194 </para>
195 </listitem>
196 <listitem>
197 <para>
198 Be careful not to go overboard setting fields to NOT NULL.
199 If a field is marked NOT NULL then it must contain data in
200 the INSERT statement, or the INSERT will fail. These
201 mysterious failures can be quite frustrating and difficult
202 to debug.
203 </para>
204 </listitem>
205 <listitem>
206 <para>
207 When Apache logs a numeric field, it uses a '-' character to
208 mean "not applicable," e.g. the number of bytes returned on
209 a 304 (unchanged) request. Since '-' is an illegal character
210 in an SQL numeric field, such fields are assigned the value
211 0 instead of '-' which, of course, makes perfect sense
212 anyway.
213 </para>
214 </listitem>
215 </itemizedlist>
216 </section>
217 <section tocstyle="fragment">
218 <title>Author / Maintainer</title>
219 <para>
220 The actual logging code was taken from the already existing flat
221 file text modules, so all that credit goes to the Apache
222 Software Foundation.
223 </para>
224 <para>
225 The MySQL routines and directives were added by Zeev Suraski
226 &lt;bourbon@netvision.net.il&gt;.
227 </para>
228 <para>
229 All changes from 1.06+ and the new documentation were added by
230 Chris Powell
231 <email>chris &lt;at&gt; grubbybaby &lt;dot&gt; com</email>
232 . It seems that the module had fallen into the "un-maintained"
233 category -- it had not been updated since 1998 -- so Chris
234 adopted it as the new maintainer.
235 </para>
236 <para>
237 In December of 2003, Edward Rudd
238 &EmailContact;
239 porting the module to Apache 2.0, cleaning up the code,
240 converting the documentation to DocBook, optimizing the main
241 logging loop, and added the much anticipated database
242 abstraction layer.
243 </para>
244 <para>
245 As of February 2004, Chris Powell handed over maintenance of the
246 module over to Edward Rudd. So you should contact Edward Rudd
247 about the module from now on.
248 </para>
249 </section>
250 <section id="Sect.MailingLists" tocstyle="fragment">
251 <title id="Sect.MailingLists.title">Mailing Lists</title>
252 <para>
253 A general discussion and support mailing list is provided for
254 mod_log_sq at lists.outoforder.cc. To subscribe to the mailing
255 list send a blank e-mail to
256 mod_log_sql-subscribe@lists.outoforder.cc. The list archives can
257 be accessed via Gmane.org's mailng list gateway via any new
258 reader
259 <ulink
260 url="news://news.gmane.org/gmane.comp.apache.mod-log-sql">
261 news://news.gmane.org/gmane.comp.apache.mod-log-sql
262 </ulink>
263 , or via a web browser at
264 <ulink
265 url="http://news.gmane.org/gmane.comp.apache.mod-log-sql">
266 http://news.gmane.org/gmane.comp.apache.mod-log-sql
267 </ulink>
268 .
269 </para>
270 </section>
271 </section>
272 <section>
273 <title>Installation</title>
274 <section tocstyle="fragment">
275 <title>Requirements</title>
276 <itemizedlist>
277 <listitem>
278 <para>
279 A compatible system. mod_log_sql was authored and tested on
280 systems based on Red Hat Linux (Red Hat, Mandrake), but the
281 module should easily adapt to any modern distribution.
282 mod_log_sql has also been ported successfully to Solaris and
283 FreeBSD.
284 </para>
285 </listitem>
286 <listitem>
287 <para>
288 Apache 1.3 or 2.0, 1.2 is no longer supported, but may still
289 compile. Ideally you should already have successfully
290 compiled Apache and understand the process, but this
291 document tries to make it simple for beginners.
292 </para>
293 </listitem>
294 <listitem>
295 <para>
296 The MySQL development headers. This package is called
297 different things on different distributions. For example,
298 Red Hat 6.x calls this RPM "MySQL-devel" whereas Mandrake
299 calls it "libmysql10-devel." Both MySQL 3.23.x and 4.x are
300 supported.
301 </para>
302 </listitem>
303 <listitem>
304 <para>
305 MySQL &gt;= 3.23.15 configured, installed and running on
306 either localhost or an accessible networked machine. You
307 should already have a basic understanding of MySQL and how
308 it functions.
309 </para>
310 </listitem>
311 <listitem>
312 <para>
313 Optionally, if you want to be able to log SSL information
314 such as keysize or cipher, you need OpenSSL and mod_ssl
315 installed.
316 </para>
317 </listitem>
318 </itemizedlist>
319 </section>
320 <section>
321 <title>Compiling and Installing</title>
322 <orderedlist>
323 <listitem>
324 <para>Unpack the archive into a working directory.</para>
325 <programlisting>$ tar -xzf mod_log_sql-1.94.tar.gz
326$ cd mod_log_sql-1.94</programlisting>
327 </listitem>
328 <listitem>
329 <para>run configure to configure the source directory.</para>
330 <programlisting>$ ./configure</programlisting>
331 <para>
332 The
333 <filename>configure</filename>
334 script should automatically detect all the required
335 libraries and program if the are installed in standard
336 locations.. If it returns an error, here is a description of
337 the arguments you can specify when you run
338 <filename>configure</filename>
339 .
340 </para>
341 <variablelist>
342 <varlistentry>
343 <term>--with-apxs=/usr/sbin/apxs</term>
344 <listitem>
345 <para>
346 This is the full path to the apxs binary, or the
347 directory which contains the program. This program is
348 part of the Apache 1.3 and 2.0 installation.
349 </para>
350 <para>
351 The default is to search
352 <filename>/usr/bin/apxs</filename>
353 and
354 <filename>/usr/sbin/apxs</filename>
355 .
356 </para>
357 <para>
358 Specifying a directory here will search
359 $directory/apxs, $directory/bin/apxs, and
360 $directory/sbin/apxs
361 </para>
362 <para>
363 If you have more than one version of Apache installed,
364 you need to specify the correct apxs binary for the
365 one you wish to compile for.
366 </para>
367 </listitem>
368 </varlistentry>
369 <varlistentry>
370 <term>--with-mysql=/path/to/mysql</term>
371 <listitem>
372 <para>
373 This is the directory to search for the
374 <filename>libmysqlclient</filename>
375 library and the
376 <application>MySQL</application>
377 headers.
378 </para>
379 <para>
380 The default is to search
381 <filename>/usr/include</filename>
382 ,
383 <filename>/usr/include/mysql</filename>
384 ,
385 <filename>/usr/local/include</filename>
386 , and
387 <filename>/usr/local/include/mysql</filename>
388 for
389 <application>MySQL</application>
390 headers.. And
391 <filename>/usr/lib</filename>
392 .
393 <filename>/usr/lib/mysql</filename>
394 ,
395 <filename>/usr/local/lib</filename>
396 , and
397 <filename>/usr/local/lin/mysql</filename>
398 for the
399 <application>MySQL</application>
400 libraries.
401 </para>
402 <para>
403 Specifying this testargument will search
404 $directory/include and $directory/mysql for
405 <application>MySQL</application>
406 headers. And $directory/lib and $directory/lib/mysql
407 for
408 <application>MySQL</application>
409 libraries.
410 </para>
411 </listitem>
412 </varlistentry>
413 <varlistentry>
414 <term>--enable-ssl</term>
415 <listitem>
416 <para>
417 Specifying this argument will enable the search for
418 mod_ssl and SSL headers, and if found will enable
419 compilation of SSL support into mod_log_sql. SSL
420 support is compiled into a separate module that can be
421 loaded after the main mod_log_sql.
422 </para>
423 </listitem>
424 </varlistentry>
425 <varlistentry>
426 <term>--with-ssl-inc=/usr/include/openssl</term>
427 <listitem>
428 <para>
429 This is the path to the SSL toolkit header files that
430 were used to compile mod_ssl. If you want SSL support
431 you most likely need to specify this.
432 </para>
433 <para>
434 The default is to search
435 <filename>/usr/include</filename>
436 and
437 <filename>/usr/include/openssl</filename>
438 .
439 </para>
440 <para>
441 Specifying this argument will search that directory
442 for the SSL headers.
443 </para>
444 </listitem>
445 </varlistentry>
446 <varlistentry>
447 <term>--with-db-inc=/usr/include/db1</term>
448 <listitem>
449 <para>
450 This argument is only needed when compiling SSL
451 support for Apache 1.3, and needs to be the directory
452 which contains the ndbm.h header file. You can find
453 this by using
454 </para>
455 <programlisting>$ locate ndbm.h
456/usr/include/db1/ndbm.h
457/usr/include/gdbm/ndbm.h</programlisting>
458 <para>
459 As far as I can tell, there is no difference as to
460 which you specify, but it should be the one that you
461 compiled mod_ssl with.
462 </para>
463 <para>
464 The default is
465 <filename>/usr/include/db1</filename>
466 , which should work on most systems.
467 </para>
468 </listitem>
469 </varlistentry>
470 <varlistentry>
471 <term>--disable-apachetest</term>
472 <listitem>
473 <para>
474 This will disable the apache version test. However
475 there is a side affect if you specify this where I
476 will not be able to determine which version of Apache
477 you are compiling for. So don't specify this.. If you
478 are having troubles with the script detecting your
479 Apache version, then send a bug report along with your
480 system OS version and versions of related packages.
481 </para>
482 </listitem>
483 </varlistentry>
484 <varlistentry>
485 <term>--disable-mysqltest</term>
486 <listitem>
487 <para>
488 This will disable the MySQL compile test. Specify this
489 if for some reason the test fail but you know you have
490 specified the correct directories. If mod_los_sql also
491 fails to compile report a bug along with your system
492 OS version and versions of related packages.
493 </para>
494 </listitem>
495 </varlistentry>
496 </variablelist>
497 </listitem>
498 <listitem>
499 <para>
500 Now compile the module with GNU make. You may have to
501 specify gmake on some systems like FreeBSD.
502 </para>
503 <programlisting>$ gmake</programlisting>
504 </listitem>
505 <listitem>
506 <para>
507 If there were no errors, you can now install the module(s).
508 If you compiled as a non-root user you may need to switch
509 users with
510 <application>su</application>
511 or
512 <application>sudo</application>
513 .
514 </para>
515 <programlisting>$ su -c "gmake install"
516Password:</programlisting>
517 </listitem>
518 <listitem>
519 <para>
520 Now edit your Apache configuration and load the modules.
521 </para>
522 <note>
523 <itemizedlist>
524 <listitem>
525 <para>
526 If you are loading the SSL logging module, you need to
527 make sure it is loaded after mod_ssl and mod_log_sql.
528 </para>
529 </listitem>
530 <listitem>
531 <para>
532 If you have previously used mod_log_sql version 1.18,
533 the name of the module has changed from sql_log_module
534 to log_sql_module (the first parameter to LoadModule)
535 </para>
536 </listitem>
537 <listitem>
538 <para>
539 If you are upgrading from any release earlier than
540 1.97 you need to add an extra LoadModule directive to
541 load the database driver (ie mysql).
542 </para>
543 </listitem>
544 </itemizedlist>
545 </note>
546 <orderedlist>
547 <listitem>
548 <para>
549 Insert these lines to either the main
550 <filename>httpd.conf</filename>
551 or a file included via an include directive.
552 </para>
553 <programlisting>LoadModule log_sql_module modules/mod_log_sql.so
554LoadModule log_sql_mysql_module modules/mod_log_sql_mysql.so
555&lt;IfModule mod_ssl.c&gt;
556LoadModule log_sql_ssl_module moduels/mod_log_sql_ssl.so
557&lt;/IfModule&gt;</programlisting>
558 <note>
559 <para>
560 If you did not compile SSL support in mod_log_sql, do
561 not include the lines between the &lt;IfModule&gt;
562 directives.
563 </para>
564 </note>
565 </listitem>
566 <listitem>
567 <para>
568 If you are using Apache 1.3 you may need add these lines
569 later in the configuration.
570 </para>
571 <programlisting>AddModule mod_log_sql.c
572AddModule mod_log_sql_mysql.c
573&lt;IfModule mod_ssl.c&gt;
574AddModule mod_log_sql_ssl.c
575&lt;/IfModule&gt;</programlisting>
576 <note>
577 <para>
578 If you did not compile SSL support in mod_log_sql, do
579 not include the lines between the &lt;IfModule&gt;
580 directives.
581 </para>
582 </note>
583 </listitem>
584 </orderedlist>
585 </listitem>
586 </orderedlist>
587 </section>
588 </section>
589 <section id="Sect.Configuration">
590 <title id="Sect.Configuration.title">Configuration</title>
591 <section id="Sect.Preperation">
592 <title id="Sect.Preperation.title">
593 Preparing MySQL for logging
594 </title>
595 <para>
596 You have to prepare the database to receive data from
597 <application>mod_log_sql</application>
598 , and set up run-time directives in
599 <filename>httpd.conf</filename>
600 to control how and what
601 <application>mod_log_sql</application>
602 logs.
603 </para>
604 <para>
605 This section will discuss how to get started with a basic
606 configuration. Full documentation of all available run-time
607 directives is available in section
608 <xref endterm="Sect.ConfigReference.title"
609 linkend="Sect.ConfigReference" />
610 .
611 </para>
612 <orderedlist>
613 <listitem>
614 <para>
615 mod_log_sql can make its own tables on-the-fly, or you can
616 pre-make the tables by hand. The advantage of letting the
617 module make the tables is ease-of-use, but for raw
618 performance you will want to pre-make the tables in order to
619 save some overhead. In this basic setup we'll just let the
620 module create tables for us.
621 </para>
622 </listitem>
623 <listitem>
624 <para>
625 We still need to have a logging database created and ready,
626 so run the MySQL command line client and create a database:
627 </para>
628 <programlisting># mysql -uadmin -p
629Enter password:
630mysql&gt; create database apachelogs;</programlisting>
631 </listitem>
632 <listitem id="Item.CreateTable">
633 <para>
634 If you want to hand-create the tables, run the enclosed
635 'create-tables' SQL script as follows ("create_tables.sql"
636 needs to be in your current working directory).
637 </para>
638 <programlisting>mysql&gt; use apachelogs
639Database changed
640mysql&gt; source create_tables.sql</programlisting>
641 </listitem>
642 <listitem>
643 <para>
644 Create a specific
645 <application>MySQL</application>
646 userid that
647 <application>httpd</application>
648 will use to authenticate and enter data. This userid need
649 not be an actual Unix user. It is a userid internal to
650 <application>MySQL</application>
651 with specific privileges. In the following example command,
652 "apachelogs" is the database, "loguser" is the userid to
653 create, "my.apachemachine.com" is the name of the Apache
654 machine, and "l0gger" is the password to assign. Choose
655 values that are different from these examples.
656 </para>
657 <programlisting>mysql&gt; grant insert,create on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger';</programlisting>
658 </listitem>
659 <listitem>
660 <para>
661 You may be especially security-paranoid and want "loguser"
662 to not have "create" capability within the "apachelogs"
663 database. You can disable that privilege, but the cost is
664 that you will not be able to use the module's on-the-fly
665 table creation feature. If that cost is acceptable,
666 hand-create the tables as described in step
667 <xref linkend="Item.CreateTable" />
668 and use the following GRANT statement instead of the one
669 above:
670 </para>
671 <programlisting>mysql&gt; grant insert on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger';</programlisting>
672 </listitem>
673 <listitem id="Item.EnableLogging">
674 <para>
675 Enable full logging of your
676 <application>MySQL</application>
677 daemon (at least temporarily for debugging purposes) if you
678 don't do this already. Edit /etc/my.cnf and add the
679 following line to your [mysqld] section:
680 </para>
681 <programlisting>log=/var/log/mysql-messages</programlisting>
682 <para>
683 Then restart
684 <application>MySQL</application>
685 </para>
686 <programlisting># /etc/rc.d/init.d/mysql restart</programlisting>
687 </listitem>
688 </orderedlist>
689 </section>
690 <section>
691 <title>A very basic logging setup in Apache</title>
692 <orderedlist>
693 <listitem>
694 <para>
695 Tell the module what database to use and the appropriate
696 authentication information.
697 </para>
698 <para>
699 So, edit httpd.conf and insert the following lines somewhere
700 after any LoadModule / AddModule statements. Make sure these
701 statements are "global," i.e. not inside any VirtualHost
702 stanza. You will also note that you are embedding a password
703 in the file. Therefore you are advised to "chmod 660
704 httpd.conf" to prevent unauthorized regular users from
705 viewing your database user and password.
706 </para>
707 <para>
708 Use the
709 <application>MySQL</application>
710 database called "apachelogs" running on "dbmachine.foo.com".
711 Use username "loguser" and password "l0gg3r" to authenticate
712 to the database. Permit the module create tables for us.
713 </para>
714 <example>
715 <title>Basic Example</title>
716 <programlisting>LogSQLLoginInfo mysql://loguser:l0gg3r@dbmachine.foo.com/apachelogs
717LogSQLCreateTables on</programlisting>
718 </example>
719 <para>
720 If your database resides on localhost instead of another
721 host, specify the MySQL server's socket file as follows:
722 </para>
723 <programlisting>LogSQLDBParam socketfile /your/path/to/mysql.sock</programlisting>
724 <para>
725 If your database is listening on a port other than 3306,
726 specify the correct TCP port as follows:
727 </para>
728 <programlisting>LogSQLDBParam port 1234</programlisting>
729 </listitem>
730 <listitem>
731 <para>
732 The actual logging is set up on a virtual-host-by-host
733 basis. So, skip down to the virtual host you want to set up.
734 Instruct this virtual host to log entries to the table
735 "access_log" by inserting a LogSQLTransferLogTable
736 directive. (The LogSQLTransferLogTable directive is the
737 minimum required to log -- other directives that you will
738 learn about later simply tune the module's behavior.)
739 </para>
740 <programlisting>&lt;VirtualHost 1.2.3.4&gt;
741 [snip]
742 LogSQLTransferLogTable access_log
743 [snip]
744&lt;/VirtualHost&gt;</programlisting>
745 </listitem>
746 <listitem>
747 <para>Restart apache.</para>
748 <programlisting># /etc/rc.d/init.d/httpd stop
749# /etc/rc.d/init.d/httpd start</programlisting>
750 </listitem>
751 </orderedlist>
752 </section>
753 <section>
754 <title>Testing the basic setup</title>
755 <orderedlist>
756 <listitem>
757 <para>
758 Visit your web site in a browser to trigger some hits, then
759 confirm that the entries are being successfully logged:
760 </para>
761 <programlisting># mysql -hdbmachine.foo.com -umysqladmin -p -e "SELECT * FROM access_log" apachelogs
762Enter password:</programlisting>
763 <para>
764 Several lines of output should follow, corresponding to your
765 hits on the site. You now have basic functionality. Don't
766 disable your regular Apache logs until you feel comfortable
767 that the database is behaving as you'd like and that things
768 are going well. If you do not see any entries in the
769 access_log, please consult section
770 <xref linkend="FAQ.NothingLogged" />
771 of the FAQ on how to debug and fix the situation.
772 </para>
773 </listitem>
774 <listitem>
775 <para>
776 You can now activate the advanced features of mod_log_sql,
777 which are described in the next section.
778 </para>
779 </listitem>
780 </orderedlist>
781 </section>
782 <section>
783 <title>How to tune logging with run-time directives</title>
784 <section tocstyle="fragment">
785 <title>Instructing the module what to log</title>
786 <para>
787 The most basic directive for the module is
788 LogSQLTransferLogFormat, which tells the module which
789 information to send to the database; logging to the database
790 will not take place without it. Place a
791 LogSQLTransferLogFormat directive in the VirtualHost stanza of
792 each virtual host that you want to activate.
793 </para>
794 <para>
795 After LogSQLTransferLogFormat you supply a string of
796 characters that tell the module what information to log. In
797 the configuration directive reference (section
798 <xref linkend="Conf.LogSQLTransferLogFormat" />
799 ) there is a table which clearly defines all the possible
800 things to log. Let's say you want to log only the "request
801 time," the "remote host," and the "request"; you'd use:
802 </para>
803 <programlisting>LogSQLTransferLogFormat hUS</programlisting>
804 <para>But a more appropriate string to use is</para>
805 <programlisting>LogSQLTransferLogFormat AbHhmRSsTUuv</programlisting>
806 <para>
807 which logs all the information required to be compatible with
808 the Combined Log Format (CLF).
809 </para>
810 <para>
811 If you don't choose to log everything that is available,
812 that's fine. Fields in the unused columns in your table will
813 simply contain NULL.
814 </para>
815 <para>
816 Some of the LogSQLTransferLogFormat characters require a
817 little extra configuration:
818 </para>
819 <itemizedlist>
820 <listitem>
821 <para>
822 If you specify 'c' to indicate that you want to log the
823 cookie value, you must also tell the module which cookie
824 you mean by using LogSQLWhichCookie -- after all, there
825 could be many cookies associated with a given request.
826 Fail to specify LogSQLWhichCookie, and no cookie
827 information at all will be logged.
828 </para>
829 </listitem>
830 <listitem>
831 <para>
832 If you specify 'M' to indicate that you want to log the
833 machine ID, you must also tell the module this machine's
834 identity using the LogSQLMachineID directive. Fail to
835 specify LogSQLMachineID, and a simple '-' character will
836 be logged in the machine_id column.
837 </para>
838 </listitem>
839 </itemizedlist>
840 </section>
841 <section id="Sect.Ignore">
842 <title id="Sect.Ignore.title">
843 Instructing the module what NOT to log using filtering
844 directives
845 </title>
846 <para>
847 One "accept" and two "ignore" directives allow you to
848 fine-tune what the module should not log. These are very handy
849 for keeping your database as uncluttered as possible and
850 keeping your statistics free of unneeded numbers. Think of
851 each one as a gatekeeper.
852 </para>
853 <para>
854 <emphasis>
855 It is important to remember that each of these three
856 directives is purely optional. mod_log_sql's default is to
857 log everything.
858 </emphasis>
859 </para>
860 <para>
861 When a request comes in, the contents of LogSQLRequestAccept
862 are evaluated first. This optional, "blanket" directive lets
863 you specify that only certain things are to be accepted for
864 logging, and everything else discarded. Because it is
865 evaluated before LogSQLRequestIgnore and LogSQLRemhostIgnore
866 it can halt logging before those two filtering directives "get
867 their chance."
868 </para>
869 <para>
870 Once a request makes it past LogSQLRequestAccept, it still can
871 be excluded based on LogSQLRemhostIgnore and
872 LogSQLRequestIgnore. A good way to use LogSQLRemhostIgnore is
873 to prevent the module from logging the traffic that your
874 internal hosts generate. LogSQLRequestIgnore is great for
875 preventing things like requests for "favicon.ico" from
876 cluttering up your database, as well as excluding the various
877 requests that worms make, etc.
878 </para>
879 <para>
880 You can specify a series of strings after each directive. Do
881 not use any type of globbing or regular-expression syntax --
882 each string is considered a match
883 <emphasis>
884 if it is a substring of the larger request or remote-host;
885 the comarison is case-sensitive
886 </emphasis>
887 . This means that "LogSQLRemhostIgnore micro" will ignore
888 requests from "microsoft.com," "microworld.net,"
889 "mymicroscope.org," etc. "LogSQLRequestIgnore gif" will
890 instruct the module to ignore requests for "leftbar.gif,"
891 "bluedot.gif" and even "giftwrap.jpg" -- but "RED.GIF" and
892 "Tree.Gif" would still get logged because of case sensitivity.
893 </para>
894 <para>A summary of the decision flow:</para>
895 <orderedlist>
896 <listitem>
897 <para>
898 If LogSQLRequestAccept exists and a request does not match
899 anything in that list, it is discarded.
900 </para>
901 </listitem>
902 <listitem>
903 <para>
904 If a request matches anything in the LogSQLRequestIgnore
905 list, it is discarded.
906 </para>
907 </listitem>
908 <listitem>
909 <para>
910 If a reqiest matches anything in the LogSQLRemhostIgnore
911 list, it is discarded.
912 </para>
913 </listitem>
914 <listitem>
915 <para>Otherwise the request is logged.</para>
916 </listitem>
917 </orderedlist>
918 <para>
919 This means that you can have a series of directives similar to
920 the following:
921 </para>
922 <programlisting>LogSQLRequestAccept .html .gif .jpg
923LogSQLRequestIgnore statistics.html bluedot.jpg</programlisting>
924 <para>
925 So the first line instructs the module to only log files with
926 html, gif and jpg suffixes; requests for "formail.cgi" and
927 "shopping-cart.pl" will never be considered for logging.
928 ("LeftArrow.JPG" will also never be considered for logging --
929 remember, the comparison is case sensitive.) The second line
930 prunes the list further -- you never want to log requests for
931 those two objects.
932 </para>
933 <note role="tip">
934 <itemizedlist>
935 <listitem>
936 <para>
937 If you want to match all the hosts in your domain such
938 as "host1.corp.foo.com" and "server.dmz.foo.com", simply
939 specify:
940 </para>
941 <programlisting>LogSQLRemhostIgnore foo.com</programlisting>
942 </listitem>
943 <listitem>
944 <para>
945 A great way to catch the vast majority of worm-attack
946 requests and prevent them from being logged is to
947 specify:
948 </para>
949 <programlisting>LogSQLRequestIgnore root.exe cmd.exe default.ida</programlisting>
950 </listitem>
951 <listitem>
952 <para>
953 To prevent the logging of requests for common graphic
954 types, make sure to put a '.' before the suffix to avoid
955 matches that you didn't intend:
956 </para>
957 <programlisting>LogSQLRequestIgnore .gif .jpg</programlisting>
958 </listitem>
959 </itemizedlist>
960 </note>
961 </section>
962 </section>
963 <section>
964 <title>Advanced logging scenarios</title>
965 <section tocstyle="fragment">
966 <title>Using the module in an ISP environment</title>
967 <para>mod_log_sql has three basic tiers of operation:</para>
968 <orderedlist>
969 <listitem>
970 <para>
971 The administrator creates all necessary tables by hand and
972 configures each Apache VirtualHost by hand.
973 (LogSQLCreateTables Off)
974 </para>
975 </listitem>
976 <listitem>
977 <para>
978 The module is permitted to create necessary tables
979 on-the-fly, but the administrator configures each Apache
980 VirtualHost by hand. (LogSQLCreateTables On)
981 </para>
982 </listitem>
983 <listitem>
984 <para>
985 The module is permitted to create all necessary tables and
986 to make intelligent, on-the-fly configuration of each
987 VirtualHost. (LogSQLMassVirtualHosting On)
988 </para>
989 </listitem>
990 </orderedlist>
991 <para>
992 Many users are happy to use the module in its most minimal
993 form: they hand-create any necessary tables (using
994 "create_tables.sql"), and they configure each VirtualHost by
995 hand to suit their needs. However, some administrators need
996 extra features due to a large and growing number of
997 VirtualHosts. The LogSQLMassVirtualHosting directive activates
998 module capabilities that make it far easier to manage an ISP
999 environment, or any situation characterized by a large and
1000 varying number of virtual servers.
1001 </para>
1002 <itemizedlist>
1003 <listitem>
1004 <para>
1005 the on-the-fly table creation feature is activated
1006 automatically
1007 </para>
1008 </listitem>
1009 <listitem>
1010 <para>
1011 the transfer log table name is dynamically set from the
1012 virtual host's name (example: a virtual host
1013 "www.grubbybaby.com" gets logged to table
1014 "access_www_grubbybaby_com")
1015 </para>
1016 </listitem>
1017 </itemizedlist>
1018 <para>
1019 There are numerous benefits. The admin will not need to create
1020 new tables for every new VirtualHost. (Although the admin will
1021 still need to drop the tables of virtual hosts that are
1022 removed.) The admin will not need to set
1023 LogSQLTransferLogTable for each virtual host -- it will be
1024 configured automatically based on the host's name. Because
1025 each virtual host will log to its own segregated table, data
1026 about one virtual server will segregate from others; an admin
1027 can grant users access to the tables they need, and they will
1028 be unable to view data about another user's virtual host.
1029 </para>
1030 <para>
1031 In an ISP scenario the admin is likely to have a cluster of
1032 many front-end webservers logging to a back-end database.
1033 mod_log_sql has a feature that permits analysis of how well
1034 the web servers are loadbalancing: the LogSQLMachineID
1035 directive. The administrator uses this directive to assign a
1036 unique identifier to each machine in the web cluster, e.g.
1037 "LogSQLMachineID web01," "LogSQLMachineID web02," etc. Used in
1038 conjunction with the 'M' character in LogSQLTransferLogFormat,
1039 each entry in the SQL log will include the machine ID of the
1040 machine that created the entry. This permits the administrator
1041 to count the entries made by each particular machine and
1042 thereby analyze the front-end loadbalancing algorithm.
1043 </para>
1044 </section>
1045 <section id="Sect.MultiTable">
1046 <title id="Sect.MultiTable.title">
1047 Logging many-to-one data in separate tables
1048 </title>
1049 <para>
1050 A given HTTP request can have a one-to-many relationship with
1051 certain kinds of data. For example, a single HTTP request can
1052 have 4 cookies, 3 headers and 5 "mod_gzip" notes associated
1053 with it. mod_log_sql is capable of logging these relationships
1054 due to the elegance of SQL relational data.
1055 </para>
1056 <para>
1057 You already have a single table containing access requests.
1058 One of the columns in that table is 'id' which is intended to
1059 contain the unique request ID supplied by the standard Apache
1060 module mod_unique_id -- all you need to do is compile in that
1061 module and employ the LogSQLTransferLogFormat character 'I'.
1062 Thereafter, each request gets a unique ID that can be thought
1063 of as a primary key within the database, useful for joining
1064 multiple tables. So let's envision several new tables: a notes
1065 table, a cookies table, and a table for inbound and outbound
1066 headers.
1067 </para>
1068 <table>
1069 <title>&lt;tblAcc&gt;access_log</title>
1070 <tgroup cols="6">
1071 <colspec colname="1" />
1072 <colspec colname="2" />
1073 <colspec colname="3" />
1074 <colspec colname="4" />
1075 <colspec colname="5" colwidth="40" />
1076 <colspec colname="6" colwidth="70" />
1077 <thead>
1078 <row>
1079 <entry colname="1">id</entry>
1080 <entry colname="2">remote_host</entry>
1081 <entry colname="3">request_uri</entry>
1082 <entry colname="4">time_stamp</entry>
1083 <entry colname="5">status</entry>
1084 <entry colname="6">bytes_sent</entry>
1085 </row>
1086 </thead>
1087 <tbody>
1088 <row>
1089 <entry colname="1">PPIDskBRH30AAGPtAsg</entry>
1090 <entry colname="2">zerberus.aiacs.net</entry>
1091 <entry colname="3">/mod_log_sql/index.html</entry>
1092 <entry colname="4">1022493617</entry>
1093 <entry colname="5">200</entry>
1094 <entry colname="6">2215</entry>
1095 </row>
1096 </tbody>
1097 </tgroup>
1098 </table>
1099 <table>
1100 <title>&lt;tblNotes&gt;notes_log</title>
1101 <tgroup cols="3">
1102 <colspec colname="1" />
1103 <colspec colname="2" />
1104 <colspec colname="3" colwidth="30" />
1105 <thead>
1106 <row>
1107 <entry colname="1">id</entry>
1108 <entry colname="2">item</entry>
1109 <entry colname="3">val</entry>
1110 </row>
1111 </thead>
1112 <tbody>
1113 <row>
1114 <entry colname="1">PPIDskBRH30AAGPtAsg</entry>
1115 <entry colname="2">mod_gzip_result</entry>
1116 <entry colname="3">OK</entry>
1117 </row>
1118 <row>
1119 <entry colname="1">PPIDskBRH30AAGPtAsg</entry>
1120 <entry colname="2">mod_gzip_compression_ratio</entry>
1121 <entry colname="3">69</entry>
1122 </row>
1123 </tbody>
1124 </tgroup>
1125 </table>
1126 <table>
1127 <title>&lt;tblHdr&gt;headers_log</title>
1128 <tgroup cols="3">
1129 <colspec colname="1" colnum="1" />
1130 <colspec colname="2" colnum="2" />
1131 <colspec colname="3" colnum="3" />
1132 <thead>
1133 <row>
1134 <entry colname="1">id</entry>
1135 <entry colname="2">item</entry>
1136 <entry colname="3">val</entry>
1137 </row>
1138 </thead>
1139 <tbody>
1140 <row>
1141 <entry colname="1">PPIDskBRH30AAGPtAsg</entry>
1142 <entry colname="2">Content-Type</entry>
1143 <entry colname="3">text/html</entry>
1144 </row>
1145 <row>
1146 <entry colname="1">PPIDskBRH30AAGPtAsg</entry>
1147 <entry colname="2">Accept-Encoding</entry>
1148 <entry colname="3">gzip, deflate</entry>
1149 </row>
1150 <row>
1151 <entry colname="1">PPIDskBRH30AAGPtAsg</entry>
1152 <entry colname="2">Expires</entry>
1153 <entry colname="3">Tue, 28 May 2002 10:00:18 GMT</entry>
1154 </row>
1155 <row>
1156 <entry colname="1">PPIDskBRH30AAGPtAsg</entry>
1157 <entry colname="2">Cache-Control</entry>
1158 <entry colname="3">max-age=86400</entry>
1159 </row>
1160 </tbody>
1161 </tgroup>
1162 </table>
1163 <para>
1164 We have a certain request, and its unique ID is
1165 "PPIDskBRH30AAGPtAsg". Within each separate table will be
1166 multiple entries with that request ID: several cookie entries,
1167 several header entries, etc. As you can see in tables
1168 [tblAcc], [tblNotes] and [tblHdr], you have a one-to-many
1169 relationship for request PPIDskBRH30AAGPtAsg: that one access
1170 has two associated notes and four associated headers. You can
1171 extract this data easily using the power of SQL's "select"
1172 statement and table joins. To see the notes associated with a
1173 particular request:
1174 </para>
1175 <programlisting>SELECT a.remote_host, a.request_uri, n.item, n.val
1176FROM access_log a JOIN notes_log n ON a.id=n.id
1177WHERE a.id='PPIDskBRH30AAGPtAsg';</programlisting>
1178 <table>
1179 <title>access_log joined to notes_log</title>
1180 <tgroup cols="4">
1181 <colspec colname="1" />
1182 <colspec colname="2" />
1183 <colspec colname="3" />
1184 <colspec colname="4" colwidth="30" />
1185 <thead>
1186 <row>
1187 <entry colname="1">remote_host</entry>
1188 <entry colname="2">request_uri</entry>
1189 <entry colname="3">item</entry>
1190 <entry colname="4">val</entry>
1191 </row>
1192 </thead>
1193 <tbody>
1194 <row>
1195 <entry colname="1">zerberus.aiacs.net</entry>
1196 <entry colname="2">/mod_log_sql/index.html</entry>
1197 <entry colname="3">mod_gzip_result</entry>
1198 <entry colname="4">OK</entry>
1199 </row>
1200 <row>
1201 <entry colname="1">zerberus.aiacs.net</entry>
1202 <entry colname="2">/mod_log_sql/index.html</entry>
1203 <entry colname="3">mod_gzip_compression_ratio</entry>
1204 <entry colname="4">69</entry>
1205 </row>
1206 </tbody>
1207 </tgroup>
1208 </table>
1209 <para>
1210 Naturally you can craft similar statements for the outboud
1211 headers, inbound headers and cookies, all of which can live in
1212 separate tables. Your statements are limited in power only by
1213 your skill with SQL.
1214 </para>
1215 <para>
1216 In order to use this capability of mod_log_sql, you must do
1217 several things.
1218 </para>
1219 <itemizedlist>
1220 <listitem>
1221 <para>
1222 Compile mod_unique_id into Apache (statically or as a
1223 DSO). mod_log_sql employs the unique request ID that
1224 mod_unique_id provides in order to key between the
1225 separate tables. You can still log the data without
1226 mod_unqiue_id, but it will be completely uncorrelated and
1227 you will have no way to discern any meaning.
1228 </para>
1229 </listitem>
1230 <listitem>
1231 <para>
1232 Create the appropriate tables. This will be done for you
1233 if you permit mod_log_sql to create its own tables using
1234 LogSQLCreateTables On, or if you use the enclosed
1235 "create_tables.sql" script.
1236 </para>
1237 </listitem>
1238 <listitem>
1239 <para>
1240 Create a SQL index on the "id" column. Without this index,
1241 table joins will be deathly slow. I recommend you consult
1242 the MySQL documentation on the proper way to create a
1243 column index if you are not familiar with this operation.
1244 </para>
1245 </listitem>
1246 <listitem>
1247 <para>
1248 Within each appropriate VirtualHost stanza, use the
1249 LogSQLWhich* and LogSQL*LogTable directives to tell the
1250 module what and where to log the data. In the following
1251 example, I have overridden the name for the notes table
1252 whereas I have left the other table names at their
1253 defaults. I have then specified the cookies, headers and
1254 notes that interest me. (And as you can see, these
1255 directives do not require me to add any characters to
1256 LogSQLTransferLogTable.)
1257 </para>
1258 <programlisting>&lt;VirtualHost 216.231.36.128&gt;
1259 (snip)
1260 LogSQLNotesLogTable notestable
1261 LogSQLWhichCookies bluecookie redcookie greencookie
1262 LogSQLWhichNotes mod_gzip_result mod_gzip_compression_ratio
1263 LogSQLWhichHeadersOut Expires Content-Type Cache-Control
1264 LogSQLWhichHeadersIn User-Agent Accept-Encoding Host
1265 (snip)
1266&lt;/VirtualHost&gt;</programlisting>
1267 </listitem>
1268 </itemizedlist>
1269 </section>
1270 <section>
1271 <title>Using the same database for production and test</title>
1272 <para>
1273 Although sub-optimal, it is not uncommon to use the same
1274 back-end database for the "production" webservers as well as
1275 the "test" webservers (budgetary constraints, rack-space
1276 limits, etc.). Furthermore, an administrator in this situation
1277 may be unable to use LogSQLRemhostIgnore to exclude requests
1278 from the test servers -- perhaps the generated entries are
1279 genuinely useful for analytical or QA purposes, but their
1280 value after analysis is minimal.
1281 </para>
1282 <para>
1283 It is wasteful and potentially confusing to permit this
1284 internal test data to clutter the database, and a solution to
1285 the problem is the proper use of the LogSQLMachineID
1286 directive. Assume a scenario where the production webservers
1287 have IDs like "web01," "web02," and so on -- and the test
1288 webservers have IDs like "test01," "test02," etc. Because
1289 entries in the log database are distinguished by their source
1290 machine, an administrator may purge unneeded test data from
1291 the access log as follows:
1292 </para>
1293 <programlisting>DELETE FROM access_log WHERE machine_id like 'test%';</programlisting>
1294 </section>
1295 <section id="Sect.DelayedInsert">
1296 <title id="Sect.DelayedInsert.title">
1297 Optimizing for a busy database
1298 </title>
1299 <para>
1300 A busy MySQL database will have SELECT statements running
1301 concurrently with INSERT and UPDATE statements. A long-running
1302 SELECT can in certain circumstances block INSERTs and
1303 therefore block mod_log_sql. A workaround is to enable
1304 mod_log_sql for "delayed inserts," which are described as
1305 follows in the MySQL documentation.
1306 </para>
1307 <para>
1308 The DELAYED option for the INSERT statement is a
1309 MySQL-specific option that is very useful if you have clients
1310 that can't wait for the INSERT to complete. This is a common
1311 problem when you use MySQL for logging and you also
1312 periodically run SELECT and UPDATE statements that take a long
1313 time to complete. DELAYED was introduced in MySQL Version
1314 3.22.15. It is a MySQL extension to ANSI SQL92.
1315 </para>
1316 <para>
1317 INSERT DELAYED only works with ISAM and MyISAM tables. Note
1318 that as MyISAM tables supports concurrent SELECT and INSERT,
1319 if there is no free blocks in the middle of the data file, you
1320 very seldom need to use INSERT DELAYED with MyISAM.
1321 </para>
1322 <para>
1323 When you use INSERT DELAYED, the client will get an OK at once
1324 and the row will be inserted when the table is not in use by
1325 any other thread.
1326 </para>
1327 <para>
1328 Another major benefit of using INSERT DELAYED is that inserts
1329 from many clients are bundled together and written in one
1330 block. This is much faster than doing many separate inserts.
1331 </para>
1332 <para>The general disadvantages of delayed inserts are</para>
1333 <orderedlist>
1334 <listitem>
1335 <para>
1336 The queued rows are only stored in memory until they are
1337 inserted into the table. If mysqld dies unexpectedly, any
1338 queued rows that were not written to disk are lost.
1339 </para>
1340 </listitem>
1341 <listitem>
1342 <para>
1343 There is additional overhead for the server to handle a
1344 separate thread for each table on which you use INSERT
1345 DELAYED.
1346 </para>
1347 </listitem>
1348 </orderedlist>
1349 <note role="warning">
1350 <para>
1351 The MySQL documentation concludes, "This means that you
1352 should only use INSERT DELAYED when you are really sure you
1353 need it!" Furthermore, the current state of error return
1354 from a failed INSERT DELAYED seems to be in flux, and may
1355 behave in unpredictable ways between different MySQL
1356 versions. See FAQ entry
1357 <xref linkend="FAQ.DelayedInsert" />
1358 -- you have been warned.
1359 </para>
1360 </note>
1361 <para>
1362 If you are experiencing issues which could be solved by
1363 delayed inserts, then set LogSqlDelayedInserts On in the
1364 <filename>httpd.conf</filename>
1365 . All regular INSERT statements are now INSERT DELAYED, and
1366 you should see no more blocking of the module.
1367 </para>
1368 </section>
1369 </section>
1370 <section id="Sect.ConfigReference">
1371 <title id="Sect.ConfigReference.title">
1372 Configuration Directive Reference
1373 </title>
1374 <para>
1375 It is imperative that you understand which directives are used
1376 only once in the main server config, and which are used inside
1377 VirtualHost stanzas and therefore multiple times within
1378 httpd.conf. The "context" listed with each entry informs you of
1379 this.
1380 </para>
1381 <section tocstyle="fragment">
1382 <title>DataBase Configuration</title>
1383 <variablelist>
1384 <varlistentry>
1385 <term>LogSQLLoginInfo</term>
1386 <listitem>
1387 <cmdsynopsis>
1388 <command>LogSQLLoginInfo</command>
1389 <arg choice="req">
1390 <replaceable>connection URI</replaceable>
1391 </arg>
1392 </cmdsynopsis>
1393 <simpara>
1394 Example: LogSQLLoginInfo
1395 mysql://logwriter:passw0rd@foobar.baz.com/Apache_log
1396 </simpara>
1397 <simpara>Context: main server config</simpara>
1398 <para>
1399 Defines the basic connection URI to connect to the
1400 database with. The format of the connection URI is
1401 </para>
1402 <simpara>
1403 driver://username[:password]@hostname[:port]/database
1404 </simpara>
1405 <variablelist>
1406 <varlistentry>
1407 <term>driver</term>
1408 <listitem>
1409 <simpara>
1410 The database driver to use (mysql, pgsql, etc..)
1411 </simpara>
1412 </listitem>
1413 </varlistentry>
1414 <varlistentry>
1415 <term>username</term>
1416 <listitem>
1417 <simpara>
1418 The database username to login with INSERT
1419 privileges on the logging table defined in
1420 LogSQLtransferLogTable.
1421 </simpara>
1422 </listitem>
1423 </varlistentry>
1424 <varlistentry>
1425 <term>password</term>
1426 <listitem>
1427 <simpara>
1428 The password to use for username, and can be
1429 omitted if there is no password.
1430 </simpara>
1431 </listitem>
1432 </varlistentry>
1433 <varlistentry>
1434 <term>hostname</term>
1435 <listitem>
1436 <simpara>
1437 The hostname or Ip address of the Database
1438 machine, ans is simple "localhost" if the database
1439 lives on the same machine as Apache.
1440 </simpara>
1441 </listitem>
1442 </varlistentry>
1443 <varlistentry>
1444 <term>port</term>
1445 <listitem>
1446 <simpara>
1447 Port on hostname to connect to the Database, if
1448 not specified use the default port for the
1449 database.
1450 </simpara>
1451 </listitem>
1452 </varlistentry>
1453 <varlistentry>
1454 <term>database</term>
1455 <listitem>
1456 <simpara>
1457 The database to connect to on the server.
1458 </simpara>
1459 </listitem>
1460 </varlistentry>
1461 </variablelist>
1462 <note>
1463 <para>
1464 This is defined only once in the
1465 <filename>httpd.conf</filename>
1466 file.
1467 </para>
1468 <para>
1469 This directive Must be defined for logging to be
1470 enabled.
1471 </para>
1472 </note>
1473 </listitem>
1474 </varlistentry>
1475 <varlistentry>
1476 <term>LogSQLDBParam</term>
1477 <listitem>
1478 <cmdsynopsis sepchar=" ">
1479 <command>LogSQLDBParam</command>
1480 <arg choice="req">
1481 <replaceable>parameter-name</replaceable>
1482 </arg>
1483 <arg choice="req">
1484 <replaceable>value</replaceable>
1485 </arg>
1486 </cmdsynopsis>
1487 <simpara>
1488 Example: LogSQLDBParam socketfile
1489 /var/lib/mysql/mysql.socket
1490 </simpara>
1491 <simpara>Context: main server config</simpara>
1492 <para>
1493 This is the new method of specifying Database connection
1494 credentials and settings. This is used to define
1495 database driver specific options. For a list of options
1496 read the documentation for each specific database
1497 driver.
1498 </para>
1499 <table>
1500 <title>MySQL Driver parameters</title>
1501 <tgroup cols="5">
1502 <colspec colname="1" colnum="1" />
1503 <colspec colname="2" colnum="2" />
1504 <colspec colname="3" colnum="3" />
1505 <thead>
1506 <row>
1507 <entry colname="1">Parameter</entry>
1508 <entry colname="2">Meaning</entry>
1509 <entry colname="3">Default</entry>
1510 </row>
1511 </thead>
1512 <tbody>
1513 <row>
1514 <entry colname="1">hostname</entry>
1515 <entry colname="2">MySQL Server hostname</entry>
1516 <entry colname="3">none (use LogSQLLoginInfo to set)</entry>
1517 </row>
1518 <row>
1519 <entry colname="1">username</entry>
1520 <entry colname="2">The username to log in with</entry>
1521 <entry colname="3">none (use LogSQLLoginInfo to set)</entry>
1522 </row>
1523 <row>
1524 <entry colname="1">password</entry>
1525 <entry colname="2">The password to use</entry>
1526 <entry colname="3">none (use LogSQLLoginInfo to set)</entry>
1527 </row>
1528 <row>
1529 <entry colname="1">database</entry>
1530 <entry colname="2">Which database to connect to</entry>
1531 <entry colname="3">none (use LogSQLLoginInfo to set)</entry>
1532 </row>
1533 <row>
1534 <entry colname="1">port</entry>
1535 <entry colname="2">The TCP port to connect to the MySQL server over</entry>
1536 <entry colname="3">3306 (use LogSQLLoginInfo to set)</entry>
1537 </row>
1538 <row>
1539 <entry colname="1">socketfile</entry>
1540 <entry colname="2">The MySQL Unix socket file to use</entry>
1541 <entry colname="3">none</entry>
1542 </row>
1543 <row>
1544 <entry colname="1">tabletype</entry>
1545 <entry colname="2">MySQL Table Engine to use</entry>
1546 <entry colname="3">MySQL server default</entry>
1547 </row>
1548 </tbody>
1549 </tgroup>
1550 </table>
1551 <note>
1552 <para>
1553 Each parameter-name may only be defined once.
1554 </para>
1555 </note>
1556 </listitem>
1557 </varlistentry>
1558 <varlistentry>
1559 <term>LogSQLCreateTables</term>
1560 <listitem>
1561 <cmdsynopsis sepchar=" ">
1562 <command>LogSQLCreateTables</command>
1563 <arg choice="req">flag</arg>
1564 </cmdsynopsis>
1565 <simpara>Example: LogSQLCreateTables On</simpara>
1566 <simpara>Default: Off</simpara>
1567 <simpara>Context: main server config</simpara>
1568 <para>
1569 mod_log_sql has the ability to create its tables
1570 on-the-fly. The advantage to this is convenience: you
1571 don't have to execute any SQL by hand to prepare the
1572 table. This is especially helpful for people with lots
1573 of virtual hosts (who should also see the
1574 LogSQLMassVirtualHosting directive).
1575 </para>
1576 <para>
1577 There is a slight disadvantage: if you wish to activate
1578 this feature, then the userid specified in
1579 LogSQLLoginInfo must have CREATE privileges on the
1580 database. In an absolutely paranoid, locked-down
1581 situation you may only want to grant your mod_log_sql
1582 user INSERT privileges on the database; in that
1583 situation you are unable to take advantage of
1584 LogSQLCreateTables. But most people -- even the very
1585 security-conscious -- will find that granting CREATE on
1586 the logging database is reasonable.
1587 </para>
1588 <note>
1589 <para>
1590 This is defined only once in the
1591 <filename>httpd.conf</filename>
1592 file.
1593 </para>
1594 </note>
1595 </listitem>
1596 </varlistentry>
1597 <varlistentry>
1598 <term>LogSQLForcePreserve</term>
1599 <listitem>
1600 <cmdsynopsis sepchar=" ">
1601 <command>LogSQLForcePreserve</command>
1602 <arg choice="req">flag</arg>
1603 </cmdsynopsis>
1604 <simpara>Example: LogForcePreserve On</simpara>
1605 <simpara>Default: Off</simpara>
1606 <simpara>Context: main server config</simpara>
1607 <para>
1608 You may need to perform debugging on your database and
1609 specifically want mod_log_sql to make no attempts to log
1610 to it. This directive instructs the module to send all
1611 its log entries directly to the preserve file and to
1612 make no database INSERT attempts.
1613 </para>
1614 <para>
1615 This is presumably a directive for temporary use only;
1616 it could be dangerous if you set it and forget it, as
1617 all your entries will simply pile up in the preserve
1618 file.
1619 </para>
1620 <note>
1621 <para>
1622 This is defined only once in the
1623 <filename>httpd.conf</filename>
1624 file.
1625 </para>
1626 </note>
1627 </listitem>
1628 </varlistentry>
1629 <varlistentry>
1630 <term>LogSQLDisablePreserve</term>
1631 <listitem>
1632 <cmdsynopsis>
1633 <command>LogSQLDisablePreserve</command>
1634 <arg choice="req">flag</arg>
1635 </cmdsynopsis>
1636 <simpara>Example: LogDisablePreserve On</simpara>
1637 <simpara>Default: Off</simpara>
1638 <simpara>Context; main server config</simpara>
1639 <para>
1640 This option can be enabled to completely disable the
1641 preserve file fail back. This may be useful for servers
1642 where the file-system is read-only.
1643 </para>
1644 <para>
1645 If the database is not available those log entries will
1646 be lost.
1647 </para>
1648 <note>
1649 <para>
1650 This is defined only once in the
1651 <filename>httpd.conf</filename>
1652 file.
1653 </para>
1654 </note>
1655 </listitem>
1656 </varlistentry>
1657 <varlistentry>
1658 <term>LogSQLMachineID</term>
1659 <listitem>
1660 <cmdsynopsis sepchar=" ">
1661 <command>LogSQLMachineID</command>
1662 <arg choice="req">machineID</arg>
1663 </cmdsynopsis>
1664 <simpara>Example: LogSQLMachineID web01</simpara>
1665 <simpara>Context: main server config</simpara>
1666 <para>
1667 If you have a farm of webservers then you may wish to
1668 know which particular machine made each entry; this is
1669 useful for analyzing your load-balancing methodology.
1670 LogSQLMachineID permits you to distinguish each
1671 machine's entries if you assign each machine its own
1672 LogSQLMachineID: for example, the first webserver gets
1673 ``LogSQLMachineID web01,'' the second gets
1674 ``LogSQLMachineID web02,'' etc.
1675 </para>
1676 <note>
1677 <para>
1678 This is defined only once in the
1679 <filename>httpd.conf</filename>
1680 file.
1681 </para>
1682 </note>
1683 </listitem>
1684 </varlistentry>
1685 <varlistentry>
1686 <term>LogSQlPreserveFile</term>
1687 <listitem>
1688 <cmdsynopsis sepchar=" ">
1689 <command>LogSQLPreserveFile</command>
1690 <arg choice="req">
1691 <replaceable>filename</replaceable>
1692 </arg>
1693 </cmdsynopsis>
1694 <simpara>
1695 Example: LogSQLPreserveFile offline-preserve
1696 </simpara>
1697 <simpara>Default: /tmp/sql-preserve</simpara>
1698 <simpara>Context: virtual host</simpara>
1699 <para>
1700 mod_log_sql writes queries to this local preserve file
1701 in the event that it cannot reach the database, and thus
1702 ensures that your high-availability web frontend does
1703 not lose logs during a temporary database outage. This
1704 could happen for a number of reasons: the database goes
1705 offline, the network breaks, etc. You will not lose
1706 entries since the module has this backup. The file
1707 consists of a series of SQL statements that can be
1708 imported into your database at your convenience;
1709 furthermore, because the SQL queries contain the access
1710 timestamps you do not need to worry about out-of-order
1711 data after the import, which is done in a simple manner:
1712 </para>
1713 <programlisting format="linespecific"># mysql -uadminuser -p mydbname &lt; /tmp/sql-preserve</programlisting>
1714 <para>
1715 If you do not define LogSQLPreserveFile then all virtual
1716 servers will log to the same default preserve file (
1717 <filename>/tmp/sql-preserve</filename>
1718 ). You can redefine this on a virtual-host basis in
1719 order to segregate your preserve files if you desire.
1720 Note that segregation is not usually necessary, as the
1721 SQL statements that are written to the preserve file
1722 already distinguish between different virtual hosts if
1723 you include the 'v' character in your
1724 LogSQLTransferLogFormat directive. It is only necessary
1725 to segregate preserve-files by virualhost if you also
1726 segregate access logs by virtualhost.
1727 </para>
1728 <para>
1729 The module will log to Apache's ErrorLog when it notices
1730 a database outage, and upon database return. You will
1731 therefore know when the preserve file is being used,
1732 although it is your responsibility to import the file.
1733 </para>
1734 <para>
1735 The file does not need to be created in advance. It is
1736 safe to remove or rename the file without interrupting
1737 Apache, as the module closes the filehandle immediately
1738 after completing the write. The file is created with the
1739 user &amp; group ID of the running Apache process (e.g.
1740 'nobody' on many Linux distributions).
1741 </para>
1742 </listitem>
1743 </varlistentry>
1744 </variablelist>
1745 </section>
1746 <section>
1747 <title>Table Names</title>
1748 <variablelist>
1749 <varlistentry>
1750 <term>LogSQLTransferLogTable</term>
1751 <listitem>
1752 <cmdsynopsis sepchar=" ">
1753 <command>LogSQLTransferLogTable</command>
1754 <arg choice="req">
1755 <replaceable>table-name</replaceable>
1756 </arg>
1757 </cmdsynopsis>
1758 <simpara>
1759 Example: LogSQLTransferLogTable access_log_table
1760 </simpara>
1761 <simpara>Context: virtual host</simpara>
1762 <para>
1763 Defines which table is used for logging of Apache's
1764 transfers; this is analogous to Apache's TransferLog
1765 directive. table-name must be a valid table within the
1766 database defined in the LogSQLLoginInfo connection URI.
1767 </para>
1768 <para>
1769 This directive is
1770 <emphasis>not</emphasis>
1771 necessary if you declare LogSQLMassVirtualHosting On,
1772 since that directive activates dynamically-named tables.
1773 If you attempt to use LogSqlTransferlogTable at the same
1774 time a warning will be logged and it will be ignored,
1775 since LogSQLMassVirtualHosting takes priority.
1776 </para>
1777 <note>
1778 <para>
1779 Requires unless LogSQLMassVirtualHosting is set to On
1780 </para>
1781 </note>
1782 </listitem>
1783 </varlistentry>
1784 <varlistentry>
1785 <term>LogSQLCookieLogTable</term>
1786 <listitem>
1787 <cmdsynopsis sepchar=" ">
1788 <command>LogSQLCookieLogTable</command>
1789 <arg choice="req">
1790 <replaceable></replaceable>
1791 table-name
1792 </arg>
1793 </cmdsynopsis>
1794 <simpara>
1795 Example: LogSQLCookieLogTable cookie_log
1796 </simpara>
1797 <simpara>Default: cookies</simpara>
1798 <simpara>Context: virtual host</simpara>
1799 <para>
1800 Defines which table is used for logging of cookies.
1801 Working in conjunction with LogSQLWhichCookies, you can
1802 log many of each request's associated cookies to a
1803 separate table. For meaningful data retrieval the cookie
1804 table is keyed to the access table by the unique request
1805 ID supplied by the standard Apache module mod_unique_id.
1806 </para>
1807 <note>
1808 <para>
1809 You must create the table (see create-tables.sql,
1810 included in the package), or LogSQLCreateTables must
1811 be set to "on".
1812 </para>
1813 </note>
1814 </listitem>
1815 </varlistentry>
1816 <varlistentry>
1817 <term>LogSQLHeadersInLogTable</term>
1818 <listitem>
1819 <cmdsynopsis sepchar=" ">
1820 <command>LogSQLHeadersInLogTable</command>
1821 <arg choice="req">
1822 <replaceable>table-name</replaceable>
1823 </arg>
1824 </cmdsynopsis>
1825 <simpara>
1826 Example: LogSQLHeadersInLogTable headers
1827 </simpara>
1828 <simpara>Default: headers_in</simpara>
1829 <simpara>Context: virtual host</simpara>
1830 <para>
1831 Defines which table is used for logging of inbound
1832 headers. Working in conjunction with
1833 LogSQLWhichHeadersIn, you can log many of each request's
1834 associated headers to a separate table. For meaningful
1835 data retrieval the headers table is keyed to the access
1836 table by the unique request ID supplied by the standard
1837 Apache module mod_unique_id.
1838 </para>
1839 <note>
1840 <para>
1841 Note that you must create the table (see
1842 create-tables.sql, included in the package), or
1843 LogSQLCreateTables must be set to "on".
1844 </para>
1845 </note>
1846 </listitem>
1847 </varlistentry>
1848 <varlistentry>
1849 <term>LogSQLHeadersOutLogTable</term>
1850 <listitem>
1851 <cmdsynopsis sepchar=" ">
1852 <command>LogSQLHeadersOutLogTable</command>
1853 <arg choice="req">
1854 <replaceable>table-name</replaceable>
1855 </arg>
1856 </cmdsynopsis>
1857 <simpara>
1858 Example: LogSQLHeadersOutLogTable headers
1859 </simpara>
1860 <simpara>Default: headers_out</simpara>
1861 <simpara>Context: virtual host</simpara>
1862 <para>
1863 Defines which table is used for logging of outbound
1864 headers. Working in conjunction with
1865 LogSQLWhichHeadersOut, you can log many of each
1866 request's associated headers to a separate table. For
1867 meaningful data retrieval the headers table is keyed to
1868 the access table by the unique request ID supplied by
1869 the standard Apache module mod_unique_id.
1870 </para>
1871 <note>
1872 <para>
1873 Note that you must create the table (see
1874 create-tables.sql, included in the package), or
1875 LogSQLCreateTables must be set to "on".
1876 </para>
1877 </note>
1878 </listitem>
1879 </varlistentry>
1880 <varlistentry>
1881 <term>LogSQLNotesLogTable</term>
1882 <listitem>
1883 <cmdsynopsis sepchar=" ">
1884 <command>LogSQLNotesLogTable</command>
1885 <arg choice="req">
1886 <replaceable>table-name</replaceable>
1887 </arg>
1888 </cmdsynopsis>
1889 <simpara>Example: LogSQLNotesLogTable notes-log</simpara>
1890 <simpara>Default: notes</simpara>
1891 <simpara>Context: virtual_host</simpara>
1892 <para>
1893 Defines which table is used for logging of notes.
1894 Working in conjunction with LogSQLWhichNotes, you can
1895 log many of each request's associated notes to a
1896 separate table. For meaningful data retrieval the notes
1897 table is keyed to the access table by the unique request
1898 ID supplied by the standard Apache module mod_unique_id.
1899 </para>
1900 <note>
1901 <para>
1902 This table must be created (see create-tables.sql
1903 included in the package), or LogSQLCreateTables must
1904 be set to 'On'.
1905 </para>
1906 </note>
1907 </listitem>
1908 </varlistentry>
1909 <varlistentry>
1910 <term>LogSQLMassVirtualHosting</term>
1911 <listitem>
1912 <cmdsynopsis sepchar=" ">
1913 <command>LogSQLMassVirtualHosting</command>
1914 <arg choice="req">flag</arg>
1915 </cmdsynopsis>
1916 <simpara>Example: LogSQLMassVirtualHosting On</simpara>
1917 <simpara>Default: Off</simpara>
1918 <simpara>Context: main server config</simpara>
1919 <para>
1920 If you administer a site hosting many, many virtual
1921 hosts then this option will appeal to you. If you turn
1922 on LogSQLMassVirtualHosting then several things happen:
1923 </para>
1924 <itemizedlist>
1925 <listitem>
1926 <para>
1927 the on-the-fly table creation feature is activated
1928 automatically
1929 </para>
1930 </listitem>
1931 <listitem>
1932 <para>
1933 the transfer log table name is dynamically set from
1934 the virtual host's name after stripping out
1935 SQL-unfriendly characters (example: a virtual host
1936 www.grubbybaby.com gets logged to table
1937 access_www_grubbybaby_com)
1938 </para>
1939 </listitem>
1940 <listitem>
1941 <para>
1942 which, in turn, means that each virtual host logs to
1943 its own segregated table. Because there is no data
1944 shared between virtual servers you can grant your
1945 users access to the tables they need; they will be
1946 unable to view others' data.
1947 </para>
1948 </listitem>
1949 </itemizedlist>
1950 <para>
1951 This is a huge boost in convenience for sites with many
1952 virtual servers. Activating LogSQLMassVirtualHosting
1953 obviates the need to create every virtual server's table
1954 and provides more granular security possibilities.
1955 </para>
1956 <note>
1957 <para>
1958 This is defined only once in the
1959 <filename>httpd.conf</filename>
1960 file.
1961 </para>
1962 </note>
1963 </listitem>
1964 </varlistentry>
1965 </variablelist>
1966 </section>
1967 <section>
1968 <title>Configuring What Is logged</title>
1969 <variablelist>
1970 <varlistentry id="Conf.LogSQLTransferLogFormat">
1971 <term>LogSQLTransferLogFormat</term>
1972 <listitem>
1973 <cmdsynopsis sepchar=" ">
1974 <command>LogSQLTransferLogFormat</command>
1975 <arg choice="req">
1976 <replaceable>format-string</replaceable>
1977 </arg>
1978 </cmdsynopsis>
1979 <simpara>Example: LogSQLTransferLogFormat huSUTv</simpara>
1980 <simpara>Default: AbHhmRSsTUuv</simpara>
1981 <simpara>Context: virtual host</simpara>
1982 <para>
1983 Each character in the format-string defines an attribute
1984 of the request that you wish to log. The default logs
1985 the information required to create Combined Log Format
1986 logs, plus several extras. Here is the full list of
1987 allowable keys, which sometimes resemble their Apache
1988 counterparts, but do not always:
1989 </para>
1990 <table>
1991 <title>Core LogFormat parameters</title>
1992 <tgroup cols="5">
1993 <colspec colname="1" colnum="1" />
1994 <colspec colname="2" colnum="2" />
1995 <colspec colname="3" colnum="3" />
1996 <colspec colname="4" colnum="4" />
1997 <colspec colname="5" colnum="5" />
1998 <thead>
1999 <row>
2000 <entry colname="1">Symbol</entry>
2001 <entry colname="2">Meaning</entry>
2002 <entry colname="3">DB Field</entry>
2003 <entry colname="4">Data Type</entry>
2004 <entry colname="5">Example</entry>
2005 </row>
2006 </thead>
2007 <tbody>
2008 <row>
2009 <entry colname="1">A</entry>
2010 <entry colname="2">User Agent</entry>
2011 <entry colname="3">agent</entry>
2012 <entry colname="4">varchar(255)</entry>
2013 <entry colname="5">
2014 Mozilla/4.0 (compat; MSIE 6.0; Windows)
2015 </entry>
2016 </row>
2017 <row>
2018 <entry colname="1">a</entry>
2019 <entry colname="2">CGi request arguments</entry>
2020 <entry colname="3">request_args</entry>
2021 <entry colname="4">varchar(255)</entry>
2022 <entry colname="5">
2023 user=Smith&amp;cart=1231&amp;item=532
2024 </entry>
2025 </row>
2026 <row>
2027 <entry colname="1">b</entry>
2028 <entry colname="2">Bytes transfered</entry>
2029 <entry colname="3">bytes_sent</entry>
2030 <entry colname="4">int unsigned</entry>
2031 <entry colname="5">32561</entry>
2032 </row>
2033 <row>
2034 <entry colname="1">
2035 c
2036 <xref linkend="Foot.LogCookie" xrefstyle="footer" />
2037 </entry>
2038 <entry colname="2">Text of cookie</entry>
2039 <entry colname="3">cookie</entry>
2040 <entry colname="4">varchar(255)</entry>
2041 <entry colname="5">
2042 Apache=sdyn.fooonline.net 1300102700823
2043 </entry>
2044 </row>
2045 <row>
2046 <entry>f</entry>
2047 <entry>Local filename requested</entry>
2048 <entry>request_file</entry>
2049 <entry>varchar(255)</entry>
2050 <entry>/var/www/html/books-cycroad.html</entry>
2051 </row>
2052 <row>
2053 <entry>H</entry>
2054 <entry>HTTP request_protocol</entry>
2055 <entry>request_protocol</entry>
2056 <entry>varchar(10)</entry>
2057 <entry>HTTP/1.1</entry>
2058 </row>
2059 <row>
2060 <entry>h</entry>
2061 <entry>Name of remote host</entry>
2062 <entry>remote_host</entry>
2063 <entry>varchar(50)</entry>
2064 <entry>blah.foobar.com</entry>
2065 </row>
2066 <row>
2067 <entry>I</entry>
2068 <entry>Request ID (from modd_unique_id)</entry>
2069 <entry>id</entry>
2070 <entry>char(19)</entry>
2071 <entry>POlFcUBRH30AAALdBG8</entry>
2072 </row>
2073 <row>
2074 <entry>l</entry>
2075 <entry>Ident user info</entry>
2076 <entry>remote_logname</entry>
2077 <entry>varcgar(50)</entry>
2078 <entry>bobby</entry>
2079 </row>
2080 <row>
2081 <entry>M</entry>
2082 <entry>
2083 Machine ID
2084 <xref linkend="Foot.MachineID" xrefstyle="footer" />
2085 </entry>
2086 <entry>machine_id</entry>
2087 <entry>varchar(25)</entry>
2088 <entry>web01</entry>
2089 </row>
2090 <row>
2091 <entry>m</entry>
2092 <entry>HTTP request method</entry>
2093 <entry>request_method</entry>
2094 <entry>varchar(10)</entry>
2095 <entry>GET</entry>
2096 </row>
2097 <row>
2098 <entry>P</entry>
2099 <entry>httpd cchild PID</entry>
2100 <entry>child_pid</entry>
2101 <entry>smallint unsigned</entry>
2102 <entry>3215</entry>
2103 </row>
2104 <row>
2105 <entry>p</entry>
2106 <entry>http port</entry>
2107 <entry>server_port</entry>
2108 <entry>smallint unsigned</entry>
2109 <entry>80</entry>
2110 </row>
2111 <row>
2112 <entry>R</entry>
2113 <entry>Referer</entry>
2114 <entry>referer</entry>
2115 <entry>varchar(255)</entry>
2116 <entry>
2117 http://www.biglinks4u.com/linkpage.html
2118 </entry>
2119 </row>
2120 <row>
2121 <entry>r</entry>
2122 <entry>Request in full form</entry>
2123 <entry>request_line</entry>
2124 <entry>varchar(255)</entry>
2125 <entry>GET /books-cycroad.html HTTP/1.1</entry>
2126 </row>
2127 <row>
2128 <entry>S</entry>
2129 <entry>
2130 Time of request in UNIX time_t format
2131 </entry>
2132 <entry>time_stamp</entry>
2133 <entry>int unsigned</entry>
2134 <entry>1005598029</entry>
2135 </row>
2136 <row>
2137 <entry>s</entry>
2138 <entry>HTTP Response Code Status</entry>
2139 <entry>status</entry>
2140 <entry>smallint</entry>
2141 <entry>200</entry>
2142 </row>
2143 <row>
2144 <entry>T</entry>
2145 <entry>Seconds to service request</entry>
2146 <entry>request_duration</entry>
2147 <entry>smallint unsigned</entry>
2148 <entry>2</entry>
2149 </row>
2150 <row>
2151 <entry>t</entry>
2152 <entry>Time of request in human format</entry>
2153 <entry>request_time</entry>
2154 <entry>char(28)</entry>
2155 <entry>[02/Dec/2001:15:01:26 -0800]</entry>
2156 </row>
2157 <row>
2158 <entry>U</entry>
2159 <entry>Request in simple form</entry>
2160 <entry>request_uri</entry>
2161 <entry>varchar(255)</entry>
2162 <entry>/books-cycroad.html</entry>
2163 </row>
2164 <row>
2165 <entry>u</entry>
2166 <entry>User info from HTTP auth</entry>
2167 <entry>remote_user</entry>
2168 <entry>varchar(50)</entry>
2169 <entry>bobby</entry>
2170 </row>
2171 <row>
2172 <entry>v</entry>
2173 <entry>Virtual host servicing the request</entry>
2174 <entry>virtual_host</entry>
2175 <entry>varchar(255)</entry>
2176 <entry>www.foobar.com</entry>
2177 </row>
2178 <row>
2179 <entry>V</entry>
2180 <entry>
2181 requested Virtual host name (mass
2182 virtualhosting)
2183 </entry>
2184 <entry>virtual_host</entry>
2185 <entry>varchar(255)</entry>
2186 <entry>www.foobar.org</entry>
2187 </row>
2188 </tbody>
2189 </tgroup>
2190 </table>
2191 <note>
2192 <simpara id="Foot.LogCookie">
2193 [1] You must also specify LogSQLWhichCookie for this
2194 to take effect.
2195 </simpara>
2196 <simpara id="Foot.MachineID">
2197 [2] You must also specify LogSQLmachineID for this to
2198 take effect.
2199 </simpara>
2200 </note>
2201 <table>
2202 <title>SSL LogFormat Parameters</title>
2203 <tgroup cols="5">
2204 <colspec colname="1" colnum="1" />
2205 <colspec colname="2" colnum="2" />
2206 <colspec colname="3" colnum="3" />
2207 <colspec colname="4" colnum="4" />
2208 <colspec colname="5" colnum="5" />
2209 <thead>
2210 <row>
2211 <entry colname="1">Symbol</entry>
2212 <entry colname="2">Meaning</entry>
2213 <entry colname="3">DB Field</entry>
2214 <entry colname="4">Data Type</entry>
2215 <entry colname="5">Example</entry>
2216 </row>
2217 </thead>
2218 <tbody>
2219 <row>
2220 <entry colname="1">z</entry>
2221 <entry colname="2">SSL cipher used</entry>
2222 <entry colname="3">ssl_cipher</entry>
2223 <entry colname="4">varchar(25)</entry>
2224 <entry colname="5">RC4-MD5</entry>
2225 </row>
2226 <row>
2227 <entry colname="1">q</entry>
2228 <entry colname="2">
2229 Keysize of the SSL connection
2230 </entry>
2231 <entry colname="3">ssl_keysize</entry>
2232 <entry colname="4">smallint unsigned</entry>
2233 <entry colname="5">56</entry>
2234 </row>
2235 <row>
2236 <entry colname="1">Q</entry>
2237 <entry colname="2">
2238 maximum keysize supported
2239 </entry>
2240 <entry colname="3">ssl_maxkeysize</entry>
2241 <entry colname="4">smallint unsigned</entry>
2242 <entry colname="5">128</entry>
2243 </row>
2244 </tbody>
2245 </tgroup>
2246 </table>
2247 <table>
2248 <title>LogIO LogFormat Parameters</title>
2249 <tgroup cols="5">
2250 <colspec colname="1" colnum="1" />
2251 <colspec colname="2" colnum="2" />
2252 <colspec colname="3" colnum="3" />
2253 <colspec colname="4" colnum="4" />
2254 <colspec colname="5" colnum="5" />
2255 <thead>
2256 <row>
2257 <entry colname="1">Symbol</entry>
2258 <entry colname="2">Meaning</entry>
2259 <entry colname="3">DB Field</entry>
2260 <entry colname="4">Data Type</entry>
2261 <entry colname="5">Example</entry>
2262 </row>
2263 </thead>
2264 <tbody>
2265 <row>
2266 <entry colname="1">i</entry>
2267 <entry colname="2">Number of actual Bytes transfered in with the request</entry>
2268 <entry colname="3">bytes_in</entry>
2269 <entry colname="4">int unsigned</entry>
2270 <entry colname="5">505</entry>
2271 </row>
2272 <row>
2273 <entry colname="1">o</entry>
2274 <entry colname="2">Number of actual Bytes transfered out with the request</entry>
2275 <entry colname="3">bytes_out</entry>
2276 <entry colname="4">int unsigned</entry>
2277 <entry colname="5">4168</entry>
2278 </row>
2279 </tbody>
2280 </tgroup>
2281 </table>
2282 </listitem>
2283 </varlistentry>
2284 <varlistentry>
2285 <term>LogSQLRemhostIgnore</term>
2286 <listitem>
2287 <cmdsynopsis sepchar=" ">
2288 <command>LogSQLRemhostIgnore</command>
2289 <arg choice="req" rep="repeat">
2290 <replaceable>hostname</replaceable>
2291 </arg>
2292 </cmdsynopsis>
2293 <simpara>
2294 Example: LogSQLRemhostIgnore localnet.com
2295 </simpara>
2296 <simpara>Context: virtual host</simpara>
2297 <para>
2298 Lists a series of smortrings that, if present in the
2299 REMOTE_HOST, will cause that request to
2300 <emphasis>not</emphasis>
2301 be logged. This directive is useful for cutting down on
2302 log clutter when you are certain that you want to ignore
2303 requests from certain hosts, such as your own internal
2304 network machines. See section
2305 <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore" />
2306 for some tips for using this directive.
2307 </para>
2308 <para>
2309 Each string may contain a + or - prefix in a
2310 &lt;VirtualHost&gt; context and will cause those strings
2311 to be added (+) or removed (-) from the global
2312 configuration. Otherwise the global is completely
2313 ignored and overridden if defined in a
2314 &lt;VirtualHost&gt;
2315 </para>
2316 <para>
2317 Each string is separated by a space, and no regular
2318 expressions or globbing are allowed. Each string is
2319 evaluated as a substring of the REMOTE_HOST using
2320 strstr(). The comparison is case sensitive.
2321 </para>
2322 </listitem>
2323 </varlistentry>
2324 <varlistentry>
2325 <term>LogSQLRequestAccept</term>
2326 <listitem>
2327 <cmdsynopsis sepchar=" ">
2328 <command>LogSQLRequestAccept</command>
2329 <arg choice="req" rep="repeat">
2330 <replaceable>substring</replaceable>
2331 </arg>
2332 </cmdsynopsis>
2333 <simpara>
2334 Example: LogSQLRequestAccept .html .php .jpg
2335 </simpara>
2336 <simpara>
2337 Default: if not specified, all requests are 'accepted'
2338 </simpara>
2339 <simpara>Context: virtual host</simpara>
2340 <para>
2341 Lists a series of strings that, if present in the URI,
2342 will permit that request to be considered for logging
2343 (depending on additional filtering by the "ignore"
2344 directives). Any request that fails to match one of the
2345 LogSQLRequestAccept entries will be discarded.
2346 </para>
2347 <para>
2348 Each string may contain a + or - prefix in a
2349 &lt;VirtualHost&gt; context and will cause those strings
2350 to be added (+) or removed (-) from the global
2351 configuration. Otherwise the global is completely
2352 ignored and overridden if defined in a
2353 &lt;VirtualHost&gt;
2354 </para>
2355 <para>
2356 This directive is useful for cutting down on log clutter
2357 when you are certain that you only want to log certain
2358 kinds of requests, and just blanket-ignore everything
2359 else. See section
2360 <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore" />
2361 for some tips for using this directive.
2362 </para>
2363 <para>
2364 Each string is separated by a space, and no regular
2365 expressions or globbing are allowed. Each string is
2366 evaluated as a substring of the URI using strstr(). The
2367 comparison is case sensitive.
2368 </para>
2369 <para>
2370 This directive is completely optional. It is more
2371 general than LogSQLRequestIgnore and is evaluated before
2372 LogSQLRequestIgnore . If this directive is not used,
2373 <emphasis>all</emphasis>
2374 requests are accepted and passed on to the other
2375 filtering directives. Therefore, only use this directive
2376 if you have a specific reason to do so.
2377 </para>
2378 </listitem>
2379 </varlistentry>
2380 <varlistentry>
2381 <term>LogSQLRequestIgnore</term>
2382 <listitem>
2383 <cmdsynopsis sepchar=" ">
2384 <command>LogSQLRequestIgnore</command>
2385 <arg choice="req" rep="repeat">
2386 <replaceable>substring</replaceable>
2387 </arg>
2388 </cmdsynopsis>
2389 <simpara>
2390 Example: LogSQLRequestIgnore root.exe cmd.exe
2391 default.ida favicon.ico
2392 </simpara>
2393 <simpara>Context: virtual host</simpara>
2394 <para>
2395 Lists a series of strings that, if present in the URI,
2396 will cause that request to
2397 <emphasis>NOT</emphasis>
2398 be logged. This directive is useful for cutting down on
2399 log clutter when you are certain that you want to ignore
2400 requests for certain objects. See section
2401 <xref endterm="Sect.Ignore.title" linkend="Sect.Ignore" />
2402 for some tips for using this directive.
2403 </para>
2404 <para>
2405 Each string may contain a + or - prefix in a
2406 &lt;VirtualHost&gt; context and will cause those strings
2407 to be added (+) or removed (-) from the global
2408 configuration. Otherwise the global is completely
2409 ignored and overridden if defined in a
2410 &lt;VirtualHost&gt;
2411 </para>
2412 <para>
2413 Each string is separated by a space, and no regular
2414 expressions or globbing are allowed. Each string is
2415 evaluated as a substring of the URI using strstr(). The
2416 comparison is case sensitive.
2417 </para>
2418 </listitem>
2419 </varlistentry>
2420 <varlistentry>
2421 <term>LogSQLWhichCookie</term>
2422 <listitem>
2423 <cmdsynopsis sepchar=" ">
2424 <command>LogSQLWhichCookie</command>
2425 <arg choice="req">
2426 <replaceable>cookiename</replaceable>
2427 </arg>
2428 </cmdsynopsis>
2429 <simpara>Example; LogSQLWhichCookie Clicks</simpara>
2430 <simpara>Context: virtual host</simpara>
2431 <para>
2432 In HTTP, cookies have names to distinguish them from
2433 each other. Using mod_usertrack, for example, you can
2434 give your user-tracking cookies a name with the
2435 CookieName directive.
2436 </para>
2437 <para>
2438 mod_log_sql allows you to log cookie information.
2439 LogSQL_WhichCookie tells mod_log_sql which cookie to
2440 log. This is necessary because you will usually be
2441 setting and receiving more than one cookie from a
2442 client.
2443 </para>
2444 <note>
2445 <para>
2446 You must include a 'c' character in
2447 LogSQLTransferLogFormat for this directive to take
2448 effect.
2449 </para>
2450 <para>
2451 although this was origintally intended for people
2452 using mod_usertrack to create user-tracking cookies,
2453 you are not restricted in any way. You can choose
2454 which cookie you wish to log to the database - any
2455 cookie at all - and it does not necessarily have to
2456 have anything to do with mod_usertrack.
2457 </para>
2458 </note>
2459 </listitem>
2460 </varlistentry>
2461 <varlistentry>
2462 <term>LogSQLWhichCookies</term>
2463 <listitem>
2464 <cmdsynopsis sepchar=" ">
2465 <command>LogSQLWhichCookies</command>
2466 <arg choice="req" rep="repeat">
2467 <replaceable>cookie-name</replaceable>
2468 </arg>
2469 </cmdsynopsis>
2470 <simpara>
2471 Example: logSQLWhichCookies userlogin cookie1 cookie2
2472 </simpara>
2473 <simpara>Context: virtual host</simpara>
2474 <para>
2475 Defines the list of cookies you would like logged. This
2476 works in conjunction with LogSQLCookieLogTable. This
2477 directive does
2478 <emphasis>not</emphasis>
2479 require any additional characters to be added to the
2480 LogSQLTransferLogFormat string. The feature is activated
2481 simply by including this directive, upon which you will
2482 begin populating the separate cookie table with data.
2483 </para>
2484 <para>
2485 Each string may contain a + or - prefix in a
2486 &lt;VirtualHost&gt; context and will cause those strings
2487 to be added (+) or removed (-) from the global
2488 configuration. Otherwise the global is completely
2489 ignored and overridden if defined in a
2490 &lt;VirtualHost&gt;
2491 </para>
2492 <note>
2493 <para>
2494 The table must be created (see create-tables.sql,
2495 included in the package), or LogSQLCreateTables must
2496 be set to 'On'.
2497 </para>
2498 </note>
2499 </listitem>
2500 </varlistentry>
2501 <varlistentry>
2502 <term>LogSQLWhichHeadersIn</term>
2503 <listitem>
2504 <cmdsynopsis sepchar=" ">
2505 <command>LogSQLWhichHeadersIn</command>
2506 <arg choice="req" rep="repeat">
2507 <replaceable>header-name</replaceable>
2508 </arg>
2509 </cmdsynopsis>
2510 <simpara>
2511 Example: LogSQLWhichHeadersIn User-Agent Accept-Encoding
2512 Host
2513 </simpara>
2514 <simpara>Context: virtual host</simpara>
2515 <para>
2516 Defines the list of inbound headers you would like
2517 logged. This works in conjunction with
2518 LogSQLHeadersInLogTable. This directive does not require
2519 any additional characters to be added to the
2520 LogSQLTransferLogFormat string. The feature is activated
2521 simply by including this directive, upon which you will
2522 begin populating the separate inbound-headers table with
2523 data.
2524 </para>
2525 <para>
2526 Each string may contain a + or - prefix in a
2527 &lt;VirtualHost&gt; context and will cause those strings
2528 to be added (+) or removed (-) from the global
2529 configuration. Otherwise the global is completely
2530 ignored and overridden if defined in a
2531 &lt;VirtualHost&gt;
2532 </para>
2533 <note>
2534 <para>
2535 The table must be created (see create-tables.sql,
2536 included in the package), or LogSQLCreateTables must
2537 be set to 'On'.
2538 </para>
2539 </note>
2540 </listitem>
2541 </varlistentry>
2542 <varlistentry>
2543 <term>LogSQLWhichHeadersOut</term>
2544 <listitem>
2545 <cmdsynopsis sepchar=" ">
2546 <command>LogSQLWhichHeadersOut</command>
2547 <arg choice="req" rep="repeat">
2548 <replaceable>header-name</replaceable>
2549 </arg>
2550 </cmdsynopsis>
2551 <simpara>
2552 Example: LogSQLWhichHeadersOut Expires Content-Type
2553 Cache-Control
2554 </simpara>
2555 <simpara>Context: virtual host</simpara>
2556 <para>
2557 Defines the list of outbound headers you would like
2558 logged. This works in conjunction with
2559 LogSQLHeadersOutLogTable. This directive does not
2560 require any additional characters to be added to the
2561 LogSQLTransferLogFormat string. The feature is activated
2562 simply by including this directive, upon which you will
2563 begin populating the separate outbound-headers table
2564 with data.
2565 </para>
2566 <para>
2567 Each string may contain a + or - prefix in a
2568 &lt;VirtualHost&gt; context and will cause those strings
2569 to be added (+) or removed (-) from the global
2570 configuration. Otherwise the global is completely
2571 ignored and overridden if defined in a
2572 &lt;VirtualHost&gt;
2573 </para>
2574 <note>
2575 <para>
2576 The table must be created (see create-tables.sql,
2577 included in the package), or LogSQLCreateTables must
2578 be set to 'On'.
2579 </para>
2580 </note>
2581 </listitem>
2582 </varlistentry>
2583 <varlistentry>
2584 <term>LogSQLWhichNotes</term>
2585 <listitem>
2586 <cmdsynopsis sepchar=" ">
2587 <command>LogSQLWhichNotes</command>
2588 <arg choice="req" rep="repeat">
2589 <replaceable>note-name</replaceable>
2590 </arg>
2591 </cmdsynopsis>
2592 <simpara>
2593 Example: LogSQLWhichNotes mod_gzip_result
2594 mod_gzip_ompression_ratio
2595 </simpara>
2596 <simpara>Context: virtual host</simpara>
2597 <para>
2598 Defines the list of notes you would like logged. This
2599 works in conjunction with LogSQLNotesLogTable. This
2600 directive does not require any additional characters to
2601 be added to the LogSQLTransferLogFormat string. The
2602 feature is activated simply by including this directive,
2603 upon which you will begin populating the separate notes
2604 table with data.
2605 </para>
2606 <para>
2607 Each string may contain a + or - prefix in a
2608 &lt;VirtualHost&gt; context and will cause those strings
2609 to be added (+) or removed (-) from the global
2610 configuration. Otherwise the global is completely
2611 ignored and overridden if defined in a
2612 &lt;VirtualHost&gt;
2613 </para>
2614 <note>
2615 <para>
2616 The table must be created (see create-tables.sql,
2617 included in the package), or LogSQLCreateTables must
2618 be set to 'On'.
2619 </para>
2620 </note>
2621 </listitem>
2622 </varlistentry>
2623 </variablelist>
2624 </section>
2625 <section>
2626 <title>Deprecated Commands</title>
2627 <variablelist>
2628 <varlistentry>
2629 <term>LogSQLSocketFile [Deprecated]</term>
2630 <listitem>
2631 <cmdsynopsis sepchar=" ">
2632 <command>LogSQLSocketFile</command>
2633 <arg choice="req">
2634 <replaceable>filename</replaceable>
2635 </arg>
2636 </cmdsynopsis>
2637 <simpara>
2638 Example: LogSQLSocketFile /tmp/mysql.sock
2639 </simpara>
2640 <simpara>Default: (database specific)</simpara>
2641 <simpara>
2642 Default (MySQL): /var/lib/mysql/mysql.sock
2643 </simpara>
2644 <simpara>Context: main server config</simpara>
2645 <para>
2646 At Apache runtime you can specify the MySQL socket file
2647 to use. Set this once in your main server config to
2648 override the default value. This value is irrelevant if
2649 your database resides on a separate machine.
2650 </para>
2651 <para>
2652 mod_log_sql will automatically employ the socket for db
2653 communications if the database resides on the local
2654 host. If the db resides on a separate host the module
2655 will automatically use TCP/IP. This is a function of the
2656 MySQL API and is not user-configurable.
2657 </para>
2658 <note>
2659 <para>
2660 This directive is deprecated in favor of LogSQLDBParam
2661 socketfile [socketfilename]
2662 </para>
2663 <para>
2664 This is defined only once in the
2665 <filename>httpd.conf</filename>
2666 file.
2667 </para>
2668 </note>
2669 </listitem>
2670 </varlistentry>
2671 <varlistentry>
2672 <term>LogSQLTCPPort [Deprecated]</term>
2673 <listitem>
2674 <cmdsynopsis sepchar=" ">
2675 <command>LogSQLTCPPort</command>
2676 <arg choice="req">
2677 <replaceable>port-number</replaceable>
2678 </arg>
2679 </cmdsynopsis>
2680 <simpara>Example: LogSQLTCPPort 3309</simpara>
2681 <simpara>Default: (database specific)</simpara>
2682 <simpara>Default (MySQL): 3306</simpara>
2683 <simpara>Context: main server config</simpara>
2684 <para>
2685 Your database may listen on a different port than the
2686 default. If so, use this directive to instruct the
2687 module which port to use. This directive only applies if
2688 the database is on a different machine connected via
2689 TCP/IP.
2690 </para>
2691 <note>
2692 <para>
2693 This directive is deprecated in favor of LogSQLDBParam
2694 tcpport [port-number]
2695 </para>
2696 <para>
2697 This is defined only once in the
2698 <filename>httpd.conf</filename>
2699 file.
2700 </para>
2701 </note>
2702 </listitem>
2703 </varlistentry>
2704 <varlistentry>
2705 <term>LogSQLDatabase [Deprecated]</term>
2706 <listitem>
2707 <cmdsynopsis sepchar=" ">
2708 <command>LogSQLDatabase</command>
2709 <arg choice="req">
2710 <replaceable>database</replaceable>
2711 </arg>
2712 </cmdsynopsis>
2713 <simpara>Example: LogSQLDatabase loggingdb</simpara>
2714 <simpara>Context: main server config</simpara>
2715 <para>
2716 Defines the database that is used for logging.
2717 "database" must be a valid db on the MySQL host defined
2718 in LogSQLLoginInfo
2719 </para>
2720 <note>
2721 <para>
2722 This directive is deprecated in favor of the URI form
2723 of LogSQLLoginInfo.
2724 </para>
2725 <para>
2726 This is defined only once in the
2727 <filename>httpd.conf</filename>
2728 file.
2729 </para>
2730 </note>
2731 </listitem>
2732 </varlistentry>
2733 </variablelist>
2734 </section>
2735 </section>
2736 </section>
2737 <section id="Sect.FAQ">
2738 <title>FAQ</title>
2739 <qandaset>
2740 <qandadiv>
2741 <title>General module questions</title>
2742 <qandaentry id="FAQ.WhyLogToSQL">
2743 <question>
2744 <para>Why log to an SQL database?</para>
2745 </question>
2746 <answer>
2747 <para>
2748 To begin with, let's get it out of the way: logging to a
2749 database is not a panacea. But while there are
2750 complexities with this solution, the benefit can be
2751 substantial for certain classes of administrator or people
2752 with advanced requirements:
2753 </para>
2754 <itemizedlist>
2755 <listitem>
2756 <para>
2757 Chores like log rotation go away, as you can DELETE
2758 records from the SQL database once they are no longer
2759 useful. For example, the excellent and popular
2760 log-analysis tool Webalizer (http://www.webalizer.com)
2761 does not need historic logs after it has processed
2762 them, enabling you to delete older logs.
2763 </para>
2764 </listitem>
2765 <listitem>
2766 <para>
2767 People with clusters of web servers (for high
2768 availability) will benefit the most - all their
2769 webservers can log to a single SQL database. This
2770 obviates the need to collate/interleave the many
2771 separate logfiles, which can be / highly/ problematic.
2772 </para>
2773 </listitem>
2774 <listitem>
2775 <para>
2776 People acquainted with the power of SQL SELECT
2777 statements will know the flexibility of the extraction
2778 possibilities at their fingertips.
2779 </para>
2780 </listitem>
2781 </itemizedlist>
2782 <para>
2783 For example, do you want to see all your 404's? Do this:
2784 </para>
2785 <programlisting>SELECT remote_host, status, request_uri, bytes_sent, from_unixtime(time_stamp)
2786FROM acc_log_tbl WHERE status=404 ORDER BY time_stamp;</programlisting>
2787 <table>
2788 <title></title>
2789 <tgroup cols="5">
2790 <colspec colname="1" />
2791 <colspec colname="2" />
2792 <colspec colname="3" />
2793 <colspec colname="4" />
2794 <colspec colname="5" />
2795 <thead>
2796 <row>
2797 <entry colname="1">remote_host</entry>
2798 <entry colname="2">status</entry>
2799 <entry colname="3">request_uri</entry>
2800 <entry colname="4">bytes_sent</entry>
2801 <entry colname="5">from_unixtime(time_stamp)</entry>
2802 </row>
2803 </thead>
2804 <tbody>
2805 <row>
2806 <entry colname="1">marge.mmm.co.uk</entry>
2807 <entry colname="2">404</entry>
2808 <entry colname="3">/favicon.ico</entry>
2809 <entry colname="4">321</entry>
2810 <entry colname="5">2001-11-20 02:30:56</entry>
2811 </row>
2812 <row>
2813 <entry colname="1">62.180.239.251</entry>
2814 <entry colname="2">404</entry>
2815 <entry colname="3">/favicon.ico</entry>
2816 <entry colname="4">333</entry>
2817 <entry colname="5">2001-11-20 02:45:25</entry>
2818 </row>
2819 <row>
2820 <entry colname="1">212.234.12.66</entry>
2821 <entry colname="2">404</entry>
2822 <entry colname="3">/favicon.ico</entry>
2823 <entry colname="4">321</entry>
2824 <entry colname="5">2001-11-20 03:01:00</entry>
2825 </row>
2826 <row>
2827 <entry colname="1">212.210.78.254</entry>
2828 <entry colname="2">404</entry>
2829 <entry colname="3">/favicon.ico</entry>
2830 <entry colname="4">333</entry>
2831 <entry colname="5">2001-11-20 03:26:05</entry>
2832 </row>
2833 </tbody>
2834 </tgroup>
2835 </table>
2836 <para>
2837 Or do you want to see how many bytes you've sent within a
2838 certain directory or site? Do this:
2839 </para>
2840 <programlisting>SELECT request_uri,sum(bytes_sent) AS bytes, count(request_uri) AS howmany
2841FROM acc_log_tbl
2842WHERE request_uri LIKE '%mod_log_sql%'
2843GROUP BY request_uri ORDER BY howmany DESC;</programlisting>
2844 <table>
2845 <title></title>
2846 <tgroup cols="3">
2847 <colspec colname="1" />
2848 <colspec colname="2" />
2849 <colspec colname="3" />
2850 <thead>
2851 <row>
2852 <entry colname="1">request_uri</entry>
2853 <entry colname="2">bytes</entry>
2854 <entry colname="3">howmany</entry>
2855 </row>
2856 </thead>
2857 <tbody>
2858 <row>
2859 <entry colname="1">/mod_log_sql/style_1.css</entry>
2860 <entry colname="2">157396</entry>
2861 <entry colname="3">1288</entry>
2862 </row>
2863 <row>
2864 <entry colname="1">/mod_log_sql/</entry>
2865 <entry colname="2">2514337</entry>
2866 <entry colname="3">801</entry>
2867 </row>
2868 <row>
2869 <entry colname="1">
2870 /mod_log_sql/mod_log_sql.tar.gz
2871 </entry>
2872 <entry colname="2">9769312</entry>
2873 <entry colname="3">456</entry>
2874 </row>
2875 <row>
2876 <entry colname="1">/mod_log_sql/faq.html</entry>
2877 <entry colname="2">5038728</entry>
2878 <entry colname="3">436</entry>
2879 </row>
2880 </tbody>
2881 </tgroup>
2882 </table>
2883 <para>
2884 Or maybe you want to see who's linking to you? Do this:
2885 </para>
2886 <programlisting>SELECT count(referer) AS num,referer
2887FROM acc_log_tbl
2888WHERE request_uri='/mod_log_sql/'
2889GROUP BY referer ORDER BY num DESC;</programlisting>
2890 <table>
2891 <title></title>
2892 <tgroup cols="2">
2893 <colspec colname="1" />
2894 <colspec colname="2" />
2895 <thead>
2896 <row>
2897 <entry colname="1">num</entry>
2898 <entry colname="2">referer</entry>
2899 </row>
2900 </thead>
2901 <tbody>
2902 <row>
2903 <entry colname="1">271</entry>
2904 <entry colname="2">
2905 http://freshmeat.net/projects/mod_log_sql/
2906 </entry>
2907 </row>
2908 <row>
2909 <entry colname="1">96</entry>
2910 <entry colname="2">
2911 http://modules.apache.org/search?id=339
2912 </entry>
2913 </row>
2914 <row>
2915 <entry colname="1">48</entry>
2916 <entry colname="2">http://freshmeat.net/</entry>
2917 </row>
2918 <row>
2919 <entry colname="1">8</entry>
2920 <entry colname="2">http://freshmeat.net</entry>
2921 </row>
2922 </tbody>
2923 </tgroup>
2924 </table>
2925 <para>
2926 As you can see, there are myriad possibilities that can be
2927 constructed with the wonderful SQL SELECT statement.
2928 Logging to an SQL database can be really quite useful!
2929 </para>
2930 </answer>
2931 </qandaentry>
2932 <qandaentry>
2933 <question>
2934 <para>Why use MySQL? Are there alternatives?</para>
2935 </question>
2936 <answer>
2937 <para>
2938 MySQL is a robust, free, and very powerful
2939 production-quality database engine. It is well supported
2940 and comes with detailed documentation. Many 3rd-party
2941 software pacakges (e.g. Slashcode, the engine that powers
2942 Slashdot) run exclusively with MySQL. In other words, you
2943 will belong to a very robust and well-supported community
2944 by choosing MySQL.
2945 </para>
2946 <para>
2947 That being said, there are alternatives. PostgreSQL is
2948 probably MySQL's leading "competitor" in the free database
2949 world. There is also an excellent module available for
2950 Apache to permit logging to a PostgreSQL database, called
2951 <ulink url="http://www.digitalstratum.com/pglogd/">
2952 pgLOGd
2953 </ulink>
2954 </para>
2955 </answer>
2956 <answer>
2957 <note>
2958 <para>
2959 Currently a database abstraction system is in the works
2960 to allow any database to be used with mod_log_sql.
2961 </para>
2962 </note>
2963 </answer>
2964 </qandaentry>
2965 <qandaentry>
2966 <question>
2967 <para>Is this code production-ready?</para>
2968 </question>
2969 <answer>
2970 <para>
2971 By all accounts it is. It is known to work without a
2972 problem on many-thousands-of-hits-per-day webservers. Does
2973 that mean it is 100% bug free? Well, no software is, but
2974 it is well-tested and believed to be fully compatible with
2975 production environments. (The usual disclaimers apply.
2976 This software is provided without warranty of any kind.)
2977 </para>
2978 </answer>
2979 </qandaentry>
2980 <qandaentry>
2981 <question>
2982 <para>Who's using mod_log_sql?</para>
2983 </question>
2984 <answer>
2985 <para>
2986 Good question! It would be great to find out! If you are a
2987 production-level mod_log_sql user, please contact eddie at
2988 &EmailContact;
2989 so that you can be mentioned here.
2990 </para>
2991 </answer>
2992 </qandaentry>
2993 <qandaentry>
2994 <question>
2995 <para>
2996 Why doesn't the module also replace the Apache ErrorLog?
2997 </para>
2998 </question>
2999 <answer>
3000 <para>
3001 There are circumstances when that would be quite unwise --
3002 for example, if Apache could not reach the MySQL server
3003 for some reason and needed to log that fact. Without a
3004 text-based error log you'd never know anything was wrong,
3005 because Apache would be trying to log a database
3006 connection error to the database... you get the point.
3007 </para>
3008 </answer>
3009 <answer>
3010 <para>
3011 Error logs are usually not very high-traffic and are
3012 really best left as text files on a web server machine.
3013 </para>
3014 </answer>
3015 <answer>
3016 <para>
3017 The Error log is free format text.. (no specified
3018 formatting what, so ever) which is rather difficult to
3019 nicely format for storing in a database.
3020 </para>
3021 </answer>
3022 </qandaentry>
3023 <qandaentry>
3024 <question>
3025 <para>Does mod_log_sql work with Apache 2.x?</para>
3026 </question>
3027 <answer>
3028 <para>
3029 Yes. A port of mod_log_sql is available for Apache 2.x as
3030 of mod_log_sql 1.90
3031 </para>
3032 </answer>
3033 </qandaentry>
3034 <qandaentry>
3035 <question>
3036 <para>
3037 Does mod_log_sql connect to MySQL via TCP/IP or a socket?
3038 </para>
3039 </question>
3040 <answer>
3041 <para>Quick answer, Yes.</para>
3042 </answer>
3043 <answer>
3044 <para>
3045 It depends! This is not determined by mod_log_sql.
3046 mod_log_sql relies on a connection command that is
3047 supplied in the MySQL API, and that command is somewhat
3048 intelligent. How it works:
3049 </para>
3050 <itemizedlist>
3051 <listitem>
3052 <simpara>
3053 if the specified MySQL database is on the same
3054 machine, the connection command uses a socket to
3055 communicate with MySQL
3056 </simpara>
3057 </listitem>
3058 <listitem>
3059 <simpara>
3060 if the specified MySQL database is on a different
3061 machine, mod_log_sql connects using TCP/IP.
3062 </simpara>
3063 </listitem>
3064 </itemizedlist>
3065 <para>
3066 You don't have any control of which methodology is used.
3067 You can fine-tune some of the configuration, however. The
3068 LogSQLSocketFile runtime configuration directive overrides
3069 the default of "/var/lib/mysql/mysql.sock" for
3070 socket-based connections, whereas the LogSQLTCPPort
3071 command allows to you override the default TCP port of
3072 3306 for TCP/IP connections.
3073 </para>
3074 </answer>
3075 </qandaentry>
3076 <qandaentry>
3077 <question>
3078 <para>I have discovered a bug. Who can I contact?</para>
3079 </question>
3080 <answer>
3081 <para>
3082 Please contact Edward Rudd at
3083 &EmailContact;
3084 , or post a message to the mod_log_sql
3085 <xref endterm="Sect.MailingLists.title"
3086 linkend="Sect.MailingLists" />
3087 . Your comments, suggestions, bugfixes, bug catches, and
3088 usage testimonials are always welcome. As free software,
3089 mod_log_sql is intended to be a community effort -- any
3090 code contributions or other ideas will be fully and openly
3091 credited, of course.
3092 </para>
3093 </answer>
3094 </qandaentry>
3095 </qandadiv>
3096 <qandadiv>
3097 <title>Problems</title>
3098 <qandaentry>
3099 <question>
3100 <para>
3101 Apache segfaults or has other problems when using PHP and
3102 mod_log_sql
3103 </para>
3104 </question>
3105 <answer>
3106 <para>
3107 This occurs if you compiled PHP with MySQL database
3108 support. PHP utilizes its internal, bundled MySQL
3109 libraries by default. These conflict with the "real" MySQL
3110 libraries linked by mod_log_sql, causing the segmentation
3111 fault.
3112 </para>
3113 <para>
3114 PHP and mod_log_sql can be configured to happily coexist.
3115 The solution is to configure PHP to link against the real
3116 MySQL libraries: recompile PHP using
3117 --with-mysql=/your/path. Apache will run properly once the
3118 modules are all using the same version of the MySQL
3119 libraries.
3120 </para>
3121 </answer>
3122 </qandaentry>
3123 <qandaentry id="FAQ.NothingLogged">
3124 <question>
3125 <para>
3126 Apache appears to start up fine, but nothing is getting
3127 logged in the database
3128 </para>
3129 </question>
3130 <answer>
3131 <para>
3132 If you do not see any entries in the access_log, then
3133 something is preventing the inserts from happening. This
3134 could be caused by several things:
3135 </para>
3136 <itemizedlist>
3137 <listitem>
3138 <simpara>
3139 Improper privileges set up in the MySQL database
3140 </simpara>
3141 </listitem>
3142 <listitem>
3143 <simpara>
3144 You are not hitting a VirtualHost that has a
3145 LogSQLTransferLogTable entry
3146 </simpara>
3147 </listitem>
3148 <listitem>
3149 <simpara>
3150 You did not specify the right database host or login
3151 information
3152 </simpara>
3153 </listitem>
3154 <listitem>
3155 <simpara>
3156 Another factor is preventing a connection to the
3157 database
3158 </simpara>
3159 </listitem>
3160 </itemizedlist>
3161 <note>
3162 <para>
3163 It is improper to ask for help before you have followed
3164 these steps.
3165 </para>
3166 </note>
3167 <para>
3168 First examine the MySQL log that you established in step
3169 <xref linkend="Item.EnableLogging" />
3170 of section
3171 <xref endterm="Sect.Preperation.title"
3172 linkend="Sect.Preperation" />
3173 . Ensure that the INSERT statements are not being rejected
3174 because of a malformed table name or other typographical
3175 error. By enabling that log, you instructed MySQL to log
3176 every connection and command it receives -- if you see no
3177 INSERT attempts in the log, the module isn't successfully
3178 connecting to the database. If you see nothing at all in
3179 the log -- not even a record of your administrative
3180 connection attempts, then you did not enable the log
3181 correctly. If you do see INSERT attempts but they are
3182 failing, the log should tell you why.
3183 </para>
3184 <para>
3185 Second, confirm that your LogSQL* directives are all
3186 correct.
3187 </para>
3188 <para>
3189 Third, examine the Apache error logs for messages from
3190 mod_log_sql; the module will offer hints as to why it
3191 cannot connect, etc.
3192 </para>
3193 <para>
3194 The next thing to do is to change the LogLevel directive
3195 <emphasis>
3196 in the main server config as well as in each VirtualHost
3197 config:
3198 </emphasis>
3199 </para>
3200 <programlisting>LogLevel debug
3201ErrorLog /var/log/httpd/server-messages</programlisting>
3202 </answer>
3203 </qandaentry>
3204 <qandaentry>
3205 <question>
3206 <para>
3207 Why do I get the message "insufficient configuration info
3208 to establish database link" in my Apache error log?
3209 </para>
3210 </question>
3211 <answer>
3212 <para>
3213 At a minimum, LogSQLLoginInfo in the URl form and either
3214 LogSQLTableName or LogSQLMassVirtualHosting must be
3215 defined in order for the module to be able to establish a
3216 database link. If these are not defined or are incomplete
3217 you will receive this error message.
3218 </para>
3219 </answer>
3220 </qandaentry>
3221 <qandaentry>
3222 <question>
3223 <para>
3224 My database cannot handle all the open connections from
3225 mod_log_sql, is there anything I can do?
3226 </para>
3227 </question>
3228 <answer>
3229 <para>
3230 The rule of thumb: if you have n webservers each
3231 configured to support y MaxClients, then your database
3232 must be able to handle n times y simultaneous connections
3233 in the worst case. Certainly you must use common sense,
3234 consider reasonable traffic expectations and structure
3235 things accordingly.
3236 </para>
3237 </answer>
3238 <answer>
3239 <para>
3240 Tweaking my.cnf to scale to high connection loads is
3241 imperative. But if hardware limitations prevent your MySQL
3242 server from gracefully handling the number of incoming
3243 connections, it would be beneficial to upgrade the memory
3244 or CPU on that server in order to handle the load.
3245 </para>
3246 </answer>
3247 <answer>
3248 <para>
3249 Jeremy Zawodny, a highly respected MySQL user and
3250 contributor to Linux Magazine, has this very helpful and
3251 highly appropriate article on tuning MySQL:
3252 <ulink
3253 url="http://jeremy.zawodny.com/blog/archives/000173.html">
3254 MySQL, Linux, and Thread Caching
3255 </ulink>
3256 </para>
3257 </answer>
3258 <answer>
3259 <para>
3260 Please remember that mod_log_sql's overriding principle is
3261 performance -- that is what the target audience demands
3262 and expects. Other database logging solutions do not open
3263 and maintain many database connections, but their
3264 performance suffers drastically. For example, pgLOGd
3265 funnels all log connections through a separate daemon that
3266 connects to the database, but that bottlenecks the entire
3267 process. mod_log_sql achieves performance numbers an order
3268 of magnitude greater than the alternatives because it
3269 dispenses with the overhead associated with rapid
3270 connection cycling, and it does not attempt to shoehorn
3271 all the database traffic through a single extra daemon or
3272 proxy process.
3273 </para>
3274 </answer>
3275 <answer>
3276 <note>
3277 <para>
3278 Currently connection pooling is being implemented as
3279 part of the Database Abstraction layer to allow multiple
3280 httpd processes to share connections.
3281 </para>
3282 </note>
3283 </answer>
3284 </qandaentry>
3285 <qandaentry>
3286 <question>
3287 <para>
3288 Why do I occasionally see a "lost connection to MySQL
3289 server" message in my Apache error log?
3290 </para>
3291 </question>
3292 <answer>
3293 <para>
3294 This message may appear every now and then in your Apache
3295 error log, especially on very lightly loaded servers. This
3296 does not mean that anything is necessarily wrong. Within
3297 each httpd child process, mod_log_sql will open (and keep
3298 open) a connection to the MySQL server. MySQL, however,
3299 will close connections that have not been used in a while;
3300 the default timeout is 8 hours. When this occurs,
3301 mod_log_sql will notice and re-open the connection. That
3302 event is what is being logged, and looks like this:
3303 </para>
3304 <programlisting>[Tue Nov 12 19:04:10 2002] [error] mod_log_sql: first attempt failed,
3305 API said: error 2013, Lost connection to MySQL server during query
3306[Tue Nov 12 19:04:10 2002] [error] mod_log_sql: reconnect successful
3307[Tue Nov 12 19:04:10 2002] [error] mod_log_sql: second attempt successful</programlisting>
3308 <para>
3309 Reference:
3310 <ulink
3311 url="http://dev.mysql.com/doc/mysql/en/Gone_away.html">
3312 MySQL documentation
3313 </ulink>
3314 </para>
3315 </answer>
3316 </qandaentry>
3317 <qandaentry>
3318 <question>
3319 <para>
3320 Sometimes a single VirtualHost gets logged to two
3321 different tables (e.g. access_foo_com,
3322 access_www_foo_com). Or, accesses to an unqualified
3323 hostname (e.g. "http://intranet/index.html") get logged in
3324 separate tables.
3325 </para>
3326 </question>
3327 <answer>
3328 <para>
3329 Proper usage of the Apache runtime ServerName directive
3330 and the directive UseCanonicalName On (or DNS) are
3331 necessary to prevent this problem. "On" is the default for
3332 UseCanonicalName, and specifies that self-referential URLs
3333 are generated from the ServerName part of your
3334 VirtualHost:
3335 </para>
3336 <para>
3337 With UseCanonicalName on (and in all versions prior to
3338 1.3) Apache will use the ServerName and Port directives to
3339 construct the canonical name for the server. With
3340 UseCanonicalName off Apache will form self-referential
3341 URLs using the hostname and port supplied by the client if
3342 any are supplied (otherwise it will use the canonical
3343 name, as defined above). [From
3344 <ulink
3345 url="http://httpd.apache.org/docs/mod/core.html#usecanonicalname">
3346 the Apache documentation
3347 </ulink>
3348 ]
3349 </para>
3350 <para>
3351 The module inherits Apache's "knowledge" about the server
3352 name being accessed. As long as those two directives are
3353 properly configured, mod_log_sql will log to only one
3354 table per virtual host while using
3355 LogSQLMassVirtualHosting.
3356 </para>
3357 </answer>
3358 </qandaentry>
3359 </qandadiv>
3360 <qandadiv>
3361 <title>Performance and Tuning</title>
3362 <qandaentry>
3363 <question>
3364 <para>How well does it perform?</para>
3365 </question>
3366 <answer>
3367 <para>
3368 mod_log_sql scales to very high loads. Apache 1.3.22 +
3369 mod_log_sql was benchmarked using the "ab" (Apache Bench)
3370 program that comes with the Apache distribution; here are
3371 the results.
3372 </para>
3373 <itemizedlist>
3374 <title>Overall configuration</title>
3375 <listitem>
3376 <simpara>Machine A: Apache webserver</simpara>
3377 </listitem>
3378 <listitem>
3379 <simpara>Machine B: MySQL server</simpara>
3380 </listitem>
3381 <listitem>
3382 <simpara>
3383 Machines A and B connected with 100Mbps Ethernet
3384 </simpara>
3385 </listitem>
3386 <listitem>
3387 <simpara>
3388 Webserver: Celeron 400, 128MB RAM, IDE storage
3389 </simpara>
3390 </listitem>
3391 </itemizedlist>
3392 <example>
3393 <title>Apache configuration</title>
3394 <programlisting>Timeout 300
3395KeepAlive On
3396MaxKeepAliveRequests 100
3397KeepAliveTimeout 15
3398MinSpareServers 5
3399StartServers 10
3400MaxSpareServers 15
3401MaxClients 256
3402MaxRequestsPerChild 5000
3403LogSQLTransferLogFormat AbHhmRSsTUuvc
3404LogSQLWhichCookie Clicks
3405CookieTracking on
3406CookieName Clicks</programlisting>
3407 </example>
3408 <example>
3409 <title>"ab" commandline</title>
3410 <programlisting>./ab -c 10 -t 20 -v 2 -C Clicks=ab_run http://www.hostname.com/target</programlisting>
3411 </example>
3412 <para>
3413 ( 10 concurrent requests; 20 second test; setting a cookie
3414 "Clicks=ab_run"; target = the mod_log_sql homepage. )
3415 </para>
3416 <para>
3417 Ten total ab runs were conducted: five with MySQL logging
3418 enabled, and five with all MySQL directives commented out
3419 of httpd.conf. Then each five were averaged. The results:
3420 </para>
3421 <itemizedlist>
3422 <listitem>
3423 <simpara>
3424 Average of five runs employing MySQL and standard text
3425 logging:
3426 <emphasis>
3427 139.01 requests per second, zero errors.
3428 </emphasis>
3429 </simpara>
3430 </listitem>
3431 <listitem>
3432 <simpara>
3433 Average of five runs employing only standard text
3434 logging:
3435 <emphasis>
3436 139.96 requests per second, zero errors.
3437 </emphasis>
3438 </simpara>
3439 </listitem>
3440 </itemizedlist>
3441 <para>
3442 In other words, any rate-limiting effects on this
3443 particular hardware setup are not caused by MySQL. Note
3444 that although this very simple webserver setup is hardly
3445 cutting-edge -- it is, after all, a fairly small machine
3446 -- 139 requests per second equal over twelve million hits
3447 per day.
3448 </para>
3449 <orderedlist>
3450 <title>
3451 If you run this benchmark yourself, take note of three
3452 things:
3453 </title>
3454 <listitem>
3455 <simpara>
3456 Use a target URL that is on your own webserver :-).
3457 </simpara>
3458 </listitem>
3459 <listitem>
3460 <simpara>
3461 Wait until all your connections are closed out between
3462 runs; after several thousand requests your TCP/IP
3463 stack will be filled with hundreds of connections in
3464 TIME_WAIT that need to close. Do a "netstat -t|wc -l"
3465 on the webserver to see. If you don't wait, you can
3466 expect to see a lot of messages like "ip_conntrack:
3467 table full, dropping packet" in your logs. (This has
3468 nothing to do with mod_log_sql, this is simply the
3469 nature of the TCP/IP stack in the Linux kernel.)
3470 </simpara>
3471 </listitem>
3472 <listitem>
3473 <simpara>
3474 When done with your runs, clean these many thousands
3475 of requests out of your database:
3476 </simpara>
3477 <programlisting>mysql&gt; delete from access_log where agent like 'ApacheBench%';
3478mysql&gt; optimize table access_log;</programlisting>
3479 </listitem>
3480 </orderedlist>
3481 </answer>
3482 </qandaentry>
3483 <qandaentry>
3484 <question>
3485 <para>
3486 Do I need to be worried about all the running MySQL
3487 children? Will holding open n Apache-to-MySQL connections
3488 consume a lot of memory?
3489 </para>
3490 </question>
3491 <answer>
3492 <para>Short answer: you shouldn't be worried.</para>
3493 </answer>
3494 <answer>
3495 <para>
3496 Long answer: you might be evaluating at the output of "ps
3497 -aufxw" and becoming alarmed at all the 7MB httpd
3498 processes or 22MB mysqld children that you see. Don't be
3499 alarmed. It's true that mod_log_sql opens and holds open
3500 many MySQL connections: each httpd child maintains one
3501 open database connection (and holds it open for
3502 performance reasons). Four webservers, each running 20
3503 Apache children, will hold open 80 MySQL connections,
3504 which means that your MySQL server needs to handle 80
3505 simultaneous connections. In truth, your MySQL server
3506 needs to handle far more than that if traffic to your
3507 website spikes and the Apache webservers spawn off an
3508 additional 30 children each...
3509 </para>
3510 <para>
3511 Fortunately the cost reported by 'ps -aufxw' is deceptive.
3512 This is due to an OS memory-management feature called
3513 "copy-on-write." When you have a number of identical child
3514 processes (e.g. Apache, MySQL), it would appear in "ps" as
3515 though each one occupies a great deal of RAM -- as much as
3516 7MB per httpd child! In actuality each additional child
3517 only occupies a small bit of extra memory -- most of the
3518 memory pages are common to each child and therefore shared
3519 in a "read-only" fashion. The OS can get away with this
3520 because the majority of memory pages for one child are
3521 identical across all children. Instead of thinking of each
3522 child as a rubber stamp of the others, think of each child
3523 as a basket of links to a common memory area.
3524 </para>
3525 <para>
3526 A memory page is only duplicated when it needs to be
3527 written to, hence "copy-on-write." The result is
3528 efficiency and decreased memory consumption. "ps" may
3529 report 7MB per child, but it might really only "cost" 900K
3530 of extra memory to add one more child. It is not correct
3531 to assume that 20 Apache children with a VSZ of 7MB each
3532 equals (2 x 7MB) of memory consumption -- the real answer
3533 is much, much lower. The same "copy-on-write" rules apply
3534 to all your MySQL children: 40 mysqld children @ 22MB each
3535 do not occupy 880MB of RAM.
3536 </para>
3537 <para>
3538 The bottom line: although there is a cost to spawn extra
3539 httpd or mysqld children, that cost is not as great as
3540 "ps" would lead you to believe.
3541 </para>
3542 </answer>
3543 </qandaentry>
3544 <qandaentry>
3545 <question>
3546 <para>
3547 My webserver cannot handle all the traffic that my site
3548 receives, is there anything I can do?
3549 </para>
3550 </question>
3551 <answer>
3552 <para>
3553 If you have exhausted all the tuning possibilities on your
3554 existing server, it is probably time you evaluated the
3555 benefits of clustering two or more webservers together in
3556 a load-balanced fashion. In fact, users of such a setup
3557 are mod_log_sql's target audience!
3558 </para>
3559 </answer>
3560 </qandaentry>
3561 <qandaentry id="FAQ.DelayedInsert">
3562 <question>
3563 <para>
3564 What is the issue with activating delayed inserts?
3565 </para>
3566 </question>
3567 <answer>
3568 <para>
3569 INSERT DELAYED is a specific syntax to MySQL and is not
3570 supported by any other database. Ergo, why is it needed,
3571 and what MySQL deficiency is it working around? INSERT
3572 DELAYED is a kluge.
3573 </para>
3574 </answer>
3575 <answer>
3576 <para>
3577 The MySQL documentation is unclear whether INSERT DELAYED
3578 is even necessary for an optimized database. It says, "The
3579 DELAYED option for the INSERT statement is a
3580 MySQL-specific option that is very useful if you have
3581 clients that can't wait for the INSERT to complete." But
3582 then it goes on to say, "Note that as MyISAM tables
3583 supports concurrent SELECT and INSERT, if there is no free
3584 blocks in the middle of the data file, you very seldom
3585 need to use INSERT DELAYED with MyISAM."
3586 </para>
3587 </answer>
3588 <answer>
3589 <para>
3590 Because INSERT DELAYED returns without waiting for the
3591 data to be written, a hard kill of your MySQL database at
3592 the right (wrong?) moment could lose those logfile
3593 entries.
3594 </para>
3595 </answer>
3596 <answer>
3597 <para>
3598 As of MySQL version 3.23.52, the error return functions
3599 disagree after a failed INSERT DELAYED: mysql_errno()
3600 always returns 0, even if mysql_error() returns a textual
3601 error. I have reported this bug to the MySQL folks.
3602 However, we have no way of knowing what solution they will
3603 adopt to fix this, and with the worst case solution
3604 mod_log_sql would not be able to tell if anything went
3605 wrong with a delayed insert.
3606 </para>
3607 </answer>
3608 <answer>
3609 <para>
3610 Instead of delayed inserts, you may wish to utilize InnoDB
3611 tables (instead of the standard MyISAM tables). InnoDB
3612 tables suppot row-level locking and are recommended for
3613 high-volume databases.
3614 </para>
3615 </answer>
3616 <answer>
3617 <para>
3618 If after understanding these problems you still wish to
3619 enable delayed inserts, section
3620 <xref endterm="Sect.DelayedInsert.title"
3621 linkend="Sect.DelayedInsert" />
3622 discusses how.
3623 </para>
3624 </answer>
3625 </qandaentry>
3626 </qandadiv>
3627 <qandadiv>
3628 <title>"How do I...?" -- accomplishing certain tasks</title>
3629 <qandaentry>
3630 <question>
3631 <para>
3632 How do I extract the data in a format that my analysis
3633 tool can understand?
3634 </para>
3635 </question>
3636 <answer>
3637 <para>
3638 mod_log_sql would be virtually useless if there weren't a
3639 way for you to extract the data from your database in a
3640 somewhat meaningful fashion. To that end there's a Perl
3641 script enclosed with the distribution. That script
3642 (make_combined_log.pl) is designed to extract N-many days
3643 worth of access logs and provide them in a Combined Log
3644 Format output. You can use this very tool right in
3645 /etc/crontab to extract logs on a regular basis so that
3646 your favorite web analysis tool can read them. Or you can
3647 examine the Perl code to construct your own custom tool.
3648 </para>
3649 <para>
3650 For example, let's say that you want your web statistics
3651 updated once per day in the wee hours of the morning. A
3652 good way to accomplish that could be the following entries
3653 in /etc/crontab:
3654 </para>
3655 <programlisting># Generate the temporary apache logs from the MySQL database (for webalizer)
365605 04 * * * root make_combined_log.pl 1 www.grubbybaby.com &gt; /var/log/temp01
3657# Run webalizer on httpd log
365830 04 * * * root webalizer -c /etc/webalizer.conf; rm -f /var/log/temp01</programlisting>
3659 <para>
3660 Or if you have a newer system that puts files in
3661 /etc/cron.daily etc., create a file called "webalizer" in
3662 the cron.daily subdirectory. Use the following as the
3663 contents of your file, and make sure to chmod 755 it when
3664 done.
3665 </para>
3666 <programlisting>#!/bin/sh
3667/usr/local/sbin/make_combined_log.pl 1 www.yourdomain.com &gt; /var/log/httpd/templog
3668/usr/local/bin/webalizer -q -c /etc/webalizer.conf
3669rm -f /var/log/httpd/templog</programlisting>
3670 <para>See? Easy.</para>
3671 </answer>
3672 </qandaentry>
3673 <qandaentry id="FAQ.Cookie">
3674 <question>
3675 <para>How can I log mod_usertrack cookies?</para>
3676 </question>
3677 <answer>
3678 <para>
3679 A number of people like to log mod_usertrack cookies in
3680 their Apache TransferLog to aid in understanding their
3681 visitors' clickstreams. This is accomplished, for example,
3682 with a statement as follows:
3683 </para>
3684 <programlisting>LogFormat "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\"" \"%{cookie}n\""</programlisting>
3685 <para>
3686 Naturally it would be nice for mod_log_sql to permit the
3687 admin to log the cookie data as well, so as of version
3688 1.10 you can do this. You need to have already compiled
3689 mod_usertrack into httpd -- it's one of the standard
3690 Apache modules.
3691 </para>
3692 <para>
3693 First make sure you have a column called "cookie" in the
3694 MySQL database to hold the cookies, which can be done as
3695 follows if you already have a working database:
3696 </para>
3697 <programlisting>mysql&gt; alter table acc_log_tbl add column cookie varchar(255);</programlisting>
3698 <para>
3699 Next configure your server to set usertracking cookies as
3700 follows, and make sure you include the new 'c' directive
3701 in your LogSQLTransferLogFormat, which activates cookie
3702 logging. Here's an example:
3703 </para>
3704 <programlisting>&lt;VirtualHost 1.2.3.4&gt;
3705 CookieTracking on
3706 CookieStyle Cookie
3707 CookieName Foobar
3708 LogSQLTransferLogFormat huSUsbTvRAc
3709 LogSQLWhichCookie Foobar
3710&lt;/VirtualHost&gt;</programlisting>
3711 <para>
3712 The first three lines configure mod_usertrack to create a
3713 COOKIE (RFC 2109) format cookie called Foobar. The last
3714 two lines tell mod_log_sql to log cookies named Foobar.
3715 You have to choose which cookie to log because more than
3716 one cookie can/will be sent to the server by the client.
3717 </para>
3718 <para>
3719 Recap: the 'c' character activates cookie logging, and the
3720 LogSQLWhichCookie directive chooses which cookie to log.
3721 </para>
3722 <para>
3723 FYI, you are advised NOT to use CookieStyle Cookie2 -- it
3724 seems that even newer browsers (IE 5.5, etc.) have trouble
3725 with the new COOKIE2 (RFC 2965) format. Just stick with
3726 the standard COOKIE format and you'll be fine.
3727 </para>
3728 <para>
3729 Perform some hits on your server and run a select
3730 </para>
3731 <programlisting>SELECT request_uri,cookie
3732FROM access_log
3733WHERE cookie IS NOT NULL;</programlisting>
3734 <table>
3735 <title></title>
3736 <tgroup cols="2">
3737 <colspec colname="1" />
3738 <colspec colname="2" />
3739 <thead>
3740 <row>
3741 <entry colname="1">request_uri</entry>
3742 <entry colname="2">cookie</entry>
3743 </row>
3744 </thead>
3745 <tbody>
3746 <row>
3747 <entry colname="1">/mod_log_sql/</entry>
3748 <entry colname="2">
3749 ool-18e4.dyn.optonline.net.130051007102700823
3750 </entry>
3751 </row>
3752 <row>
3753 <entry colname="1">/mod_log_sql/usa.gif</entry>
3754 <entry colname="2">
3755 ool-18e4.dyn.optonline.net.130051007102700823
3756 </entry>
3757 </row>
3758 <row>
3759 <entry colname="1">/mod_log_sql/style_1.css</entry>
3760 <entry colname="2">
3761 ool-18e4.dyn.optonline.net.130051007102700823
3762 </entry>
3763 </row>
3764 </tbody>
3765 </tgroup>
3766 </table>
3767 </answer>
3768 </qandaentry>
3769 <qandaentry>
3770 <question>
3771 <para>
3772 What if I want to log more than one cookie? What is the
3773 difference between LogSQLWhichCookie and
3774 LogSQLWhichCookies?
3775 </para>
3776 </question>
3777 <answer>
3778 <para>
3779 As of version 1.17, you have a choice in how you want
3780 cookie logging handled.
3781 </para>
3782 <para>
3783 If you are interested in logging only one cookie per
3784 request, follow the instructions in FAQ entry
3785 <xref linkend="FAQ.Cookie" />
3786 above. That cookie will be logged to a column in the
3787 regular access_log table, and the actual cookie you want
3788 to log is specified with LogSQLWhichCookie. Don't forget
3789 to specify the 'c' character in LogSQLTransferLogFormat.
3790 </para>
3791 <para>
3792 If, however, you need to log multiple cookies per request,
3793 you must employ the LogSQLWhichCookies (note the plural)
3794 directive. The cookies you specify will be logged to a
3795 separate table (as discussed in section
3796 <xref endterm="Sect.MultiTable.title"
3797 linkend="Sect.MultiTable" />
3798 ), and entries in that table will be linked to the regular
3799 access_log entries via the unique ID that is supplied by
3800 mod_unique_id. Without mod_unique_id the information will
3801 still be logged but you will be unable to correlate which
3802 cookies go with which access-requests. Furthermore, with
3803 LogSQLWhichCookies, you do not need to include the 'c'
3804 character in LogSQLTransferLogFormat.
3805 </para>
3806 <para>
3807 LogSQLWhichCookie and LogSQLWhichCookies can coexist
3808 without conflict because they operate on entireley
3809 different tables, but you're better off choosing the one
3810 you need.
3811 </para>
3812 </answer>
3813 </qandaentry>
3814 <qandaentry>
3815 <question>
3816 <para>
3817 What are the SSL logging features, and how do I activate
3818 them?
3819 </para>
3820 </question>
3821 <answer>
3822 <note>
3823 <para>
3824 You do not need to compile SSL support into mod_log_sql
3825 in order to simply use it with a secure site. You only
3826 need to compile SSL support into mod_log_sql if you want
3827 to log SSL-specific data such as the cipher type used,
3828 or the keysize that was negotiated. If that information
3829 is unimportant to you, you can ignore this FAQ.
3830 </para>
3831 </note>
3832 <para>
3833 By adding certain characters to your
3834 LogSQLTransferLogFormat string you can tell mod_log_sql to
3835 log the SSL cipher, the SSL keysize of the connection, and
3836 the maximum keysize that was available. This would let you
3837 tell, for example, which clients were using only
3838 export-grade security to access your secure software area.
3839 </para>
3840 <para>
3841 You can compile mod_log_sql with SSL logging support if
3842 you have the right packages installed. If you already have
3843 an SSL-enabled Apache then you by definition have the
3844 correct packages already installed: OpenSSL and mod_ssl.
3845 </para>
3846 <para>
3847 You need to ensure that your database is set up to log the
3848 SSL data. Issue the following commands to MySQL if your
3849 access table does not already have them:
3850 </para>
3851 <programlisting>mysql&gt; alter table access_log add column ssl_cipher varchar(25);
3852mysql&gt; alter table access_log add column ssl_keysize smallint unsigned;
3853mysql&gt; alter table access_log add column ssl_maxkeysize smallint unsigned;</programlisting>
3854 <para>
3855 Finally configure httpd.conf to activate the SSL fields.
3856 Note that this is only meaningful in a VirtualHost that is
3857 set up for SSL.
3858 </para>
3859 <programlisting>&lt;VirtualHost 1.2.3.4:443&gt;
3860 LogSQLTransferLogFormat AbHhmRSsTUuvcQqz
3861&lt;/VirtualHost&gt;</programlisting>
3862 <para>
3863 You also need to make sure you have the mod_log_sql_ssl
3864 module loaded as well.
3865 </para>
3866 <para>
3867 The last three characters (Qqz) in the directive are the
3868 SSL ones; see section
3869 <xref linkend="Conf.LogSQLTransferLogFormat" />
3870 in the directives documentation for details of the
3871 LogSQLTransferLogFormat directive.
3872 </para>
3873 <para>
3874 Restart Apache, then perform some hits on your server.
3875 Then run the following select statement:
3876 </para>
3877 <programlisting>SELECT remote_host,request_uri,ssl_cipher,ssl_keysize,ssl_maxkeysize
3878FROM access_log
3879WHERE ssl_cipher IS NOT NULL;</programlisting>
3880 <table>
3881 <title></title>
3882 <tgroup cols="5">
3883 <colspec colname="1" />
3884 <colspec colname="2" />
3885 <colspec colname="3" />
3886 <colspec colname="4" />
3887 <colspec colname="5" />
3888 <thead>
3889 <row>
3890 <entry colname="1">remote_host</entry>
3891 <entry colname="2">request_uri</entry>
3892 <entry colname="3">ssl_cipher</entry>
3893 <entry colname="4">ssl_keysize</entry>
3894 <entry colname="5">ssl_maxkeysize</entry>
3895 </row>
3896 </thead>
3897 <tbody>
3898 <row>
3899 <entry colname="1">216.192.52.4</entry>
3900 <entry colname="2">/dir/somefile.html</entry>
3901 <entry colname="3">RC4-MD5</entry>
3902 <entry colname="4">128</entry>
3903 <entry colname="5">128</entry>
3904 </row>
3905 <row>
3906 <entry colname="1">216.192.52.4</entry>
3907 <entry colname="2">/dir/somefile.gif</entry>
3908 <entry colname="3">RC4-MD5</entry>
3909 <entry colname="4">128</entry>
3910 <entry colname="5">128</entry>
3911 </row>
3912 <row>
3913 <entry colname="1">216.192.52.4</entry>
3914 <entry colname="2">/dir/somefile.jpg</entry>
3915 <entry colname="3">RC4-MD5</entry>
3916 <entry colname="4">128</entry>
3917 <entry colname="5">128</entry>
3918 </row>
3919 </tbody>
3920 </tgroup>
3921 </table>
3922 </answer>
3923 </qandaentry>
3924 </qandadiv>
3925 </qandaset>
3926 </section>
3927</article>
diff --git a/docs/contents.png b/docs/contents.png
new file mode 100644
index 0000000..0c752c6
--- /dev/null
+++ b/docs/contents.png
Binary files differ
diff --git a/docs/crossref.png b/docs/crossref.png
new file mode 100644
index 0000000..7dd2ddd
--- /dev/null
+++ b/docs/crossref.png
Binary files differ
diff --git a/docs/documentation.css b/docs/documentation.css
new file mode 100644
index 0000000..f12a3af
--- /dev/null
+++ b/docs/documentation.css
@@ -0,0 +1,33 @@
1body {
2 margin-left: 3%;
3 background-color: #ccccFF;
4 font-family: sans-serif;
5}
6
7h1 {
8 text-align: center;
9}
10
11h2 {
12 margin-left: -1%;
13 font-size: 150%;
14}
15
16h3 {
17 margin-left: -1%;
18}
19
20h4 {
21 text-align: center;
22}
23
24p {
25}
26
27pre {
28 font-family: monospace;
29}
30
31DD {
32 font-family: monospace;
33} \ No newline at end of file
diff --git a/docs/documentation.html b/docs/documentation.html
new file mode 100644
index 0000000..d63b31f
--- /dev/null
+++ b/docs/documentation.html
@@ -0,0 +1,269 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2
3<!--Converted with LaTeX2HTML 2002-1 (1.68)
4original version by: Nikos Drakos, CBLU, University of Leeds
5* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6* with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
8<HTML>
9<HEAD>
10<TITLE>Installing and Running mod_log_sql</TITLE>
11<META NAME="description" CONTENT="Installing and Running mod_log_sql">
12<META NAME="keywords" CONTENT="documentation">
13<META NAME="resource-type" CONTENT="document">
14<META NAME="distribution" CONTENT="global">
15
16<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17<META NAME="Generator" CONTENT="LaTeX2HTML v2002-1">
18<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
19
20<LINK REL="STYLESHEET" HREF="documentation.css">
21
22<LINK REL="next" HREF="node1.html">
23</HEAD>
24
25<BODY >
26<!--Navigation Panel-->
27<A NAME="tex2html6"
28 HREF="node1.html">
29<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
30<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up_g.png">
31<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev_g.png">
32<A NAME="tex2html4"
33 HREF="node1.html">
34<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
35<BR>
36<B> Next:</B> <A NAME="tex2html7"
37 HREF="node1.html">Contents</A>
38 &nbsp; <B> <A NAME="tex2html5"
39 HREF="node1.html">Contents</A></B>
40<BR>
41<BR>
42<!--End of Navigation Panel-->
43
44<P>
45
46
47
48
49<P>
50
51<P>
52<H1 ALIGN="CENTER">Installing and Running mod_log_sql</H1>
53<P ALIGN="CENTER"><STRONG>Christopher Powell, &lt;chris@grubbybaby.com&gt; </STRONG></P>
54<BR><HR>
55<!--Table of Child-Links-->
56<A NAME="CHILD_LINKS"></A>
57
58<UL>
59<LI><A NAME="tex2html8"
60 HREF="node1.html">Contents</A>
61<LI><A NAME="tex2html9"
62 HREF="node2.html">1 Introduction</A>
63<UL>
64<LI><A NAME="tex2html10"
65 HREF="node2.html#SECTION00021000000000000000">1.1 Homepage </A>
66<LI><A NAME="tex2html11"
67 HREF="node2.html#SECTION00022000000000000000">1.2 Summary</A>
68<LI><A NAME="tex2html12"
69 HREF="node2.html#SECTION00023000000000000000">1.3 Approach</A>
70<LI><A NAME="tex2html13"
71 HREF="node2.html#SECTION00024000000000000000">1.4 What gets logged by default? </A>
72<LI><A NAME="tex2html14"
73 HREF="node2.html#SECTION00025000000000000000">1.5 Miscellaneous Notes</A>
74<LI><A NAME="tex2html15"
75 HREF="node2.html#SECTION00026000000000000000">1.6 Author / Maintainer</A>
76</UL>
77<BR>
78<LI><A NAME="tex2html16"
79 HREF="node3.html">2 Installation</A>
80<UL>
81<LI><A NAME="tex2html17"
82 HREF="node3.html#SECTION00031000000000000000">2.1 Requirements</A>
83<LI><A NAME="tex2html18"
84 HREF="node3.html#SECTION00032000000000000000">2.2 Platform-specific notes</A>
85<UL>
86<LI><A NAME="tex2html19"
87 HREF="node3.html#SECTION00032100000000000000">2.2.1 Solaris</A>
88<LI><A NAME="tex2html20"
89 HREF="node3.html#SECTION00032200000000000000">2.2.2 BSD</A>
90<LI><A NAME="tex2html21"
91 HREF="node3.html#SECTION00032300000000000000">2.2.3 Win32</A>
92</UL>
93<LI><A NAME="tex2html22"
94 HREF="node3.html#SECTION00033000000000000000">2.3 Do I want a DSO or a static module?</A>
95<LI><A NAME="tex2html23"
96 HREF="node3.html#SECTION00034000000000000000">2.4 Installation as an Apache DSO (Preferred) </A>
97<LI><A NAME="tex2html24"
98 HREF="node3.html#SECTION00035000000000000000">2.5 Installation as a static module compiled into
99httpd</A>
100</UL>
101<BR>
102<LI><A NAME="tex2html25"
103 HREF="node4.html">3 Configuration</A>
104<UL>
105<LI><A NAME="tex2html26"
106 HREF="node4.html#SECTION00041000000000000000">3.1 Preparing MySQL for logging</A>
107<LI><A NAME="tex2html27"
108 HREF="node4.html#SECTION00042000000000000000">3.2 A very basic logging setup in Apache</A>
109<LI><A NAME="tex2html28"
110 HREF="node4.html#SECTION00043000000000000000">3.3 Testing the basic setup</A>
111<LI><A NAME="tex2html29"
112 HREF="node4.html#SECTION00044000000000000000">3.4 How to tune logging with run-time directives</A>
113<UL>
114<LI><A NAME="tex2html30"
115 HREF="node4.html#SECTION00044100000000000000">3.4.1 Instructing the module what to log</A>
116<LI><A NAME="tex2html31"
117 HREF="node4.html#SECTION00044200000000000000">3.4.2 Instructing the module what NOT to log using filtering
118directives</A>
119</UL>
120<LI><A NAME="tex2html32"
121 HREF="node4.html#SECTION00045000000000000000">3.5 Advanced logging scenarios</A>
122<UL>
123<LI><A NAME="tex2html33"
124 HREF="node4.html#SECTION00045100000000000000">3.5.1 Using the module in an ISP environment</A>
125<LI><A NAME="tex2html34"
126 HREF="node4.html#SECTION00045200000000000000">3.5.2 Logging many-to-one data in separate tables</A>
127<LI><A NAME="tex2html35"
128 HREF="node4.html#SECTION00045300000000000000">3.5.3 Using the same database for production and test</A>
129<LI><A NAME="tex2html36"
130 HREF="node4.html#SECTION00045400000000000000">3.5.4 Optimizing for a busy database</A>
131</UL>
132<LI><A NAME="tex2html37"
133 HREF="node4.html#SECTION00046000000000000000">3.6 Configuration directive reference</A>
134<UL>
135<LI><A NAME="tex2html38"
136 HREF="node4.html#SECTION00046100000000000000">3.6.1 LogSQLCookieLogTable</A>
137<LI><A NAME="tex2html39"
138 HREF="node4.html#SECTION00046200000000000000">3.6.2 LogSQLCreateTables</A>
139<LI><A NAME="tex2html40"
140 HREF="node4.html#SECTION00046300000000000000">3.6.3 LogSQLDatabase </A>
141<LI><A NAME="tex2html41"
142 HREF="node4.html#SECTION00046400000000000000">3.6.4 LogSQLForcePreserve</A>
143<LI><A NAME="tex2html42"
144 HREF="node4.html#SECTION00046500000000000000">3.6.5 LogSQLHeadersInLogTable</A>
145<LI><A NAME="tex2html43"
146 HREF="node4.html#SECTION00046600000000000000">3.6.6 LogSQLHeadersOutLogTable</A>
147<LI><A NAME="tex2html44"
148 HREF="node4.html#SECTION00046700000000000000">3.6.7 LogSQLLoginInfo </A>
149<LI><A NAME="tex2html45"
150 HREF="node4.html#SECTION00046800000000000000">3.6.8 LogSQLMachineID</A>
151<LI><A NAME="tex2html46"
152 HREF="node4.html#SECTION00046900000000000000">3.6.9 LogSQLMassVirtualHosting</A>
153<LI><A NAME="tex2html47"
154 HREF="node4.html#SECTION000461000000000000000">3.6.10 LogSQLNotesLogTable</A>
155<LI><A NAME="tex2html48"
156 HREF="node4.html#SECTION000461100000000000000">3.6.11 LogSQLPreserveFile</A>
157<LI><A NAME="tex2html49"
158 HREF="node4.html#SECTION000461200000000000000">3.6.12 LogSQLRemhostIgnore</A>
159<LI><A NAME="tex2html50"
160 HREF="node4.html#SECTION000461300000000000000">3.6.13 LogSQLRequestAccept</A>
161<LI><A NAME="tex2html51"
162 HREF="node4.html#SECTION000461400000000000000">3.6.14 LogSQLRequestIgnore</A>
163<LI><A NAME="tex2html52"
164 HREF="node4.html#SECTION000461500000000000000">3.6.15 LogSQLSocketFile </A>
165<LI><A NAME="tex2html53"
166 HREF="node4.html#SECTION000461600000000000000">3.6.16 LogSQLTCPPort</A>
167<LI><A NAME="tex2html54"
168 HREF="node4.html#SECTION000461700000000000000">3.6.17 LogSQLTransferLogFormat </A>
169<LI><A NAME="tex2html55"
170 HREF="node4.html#SECTION000461800000000000000">3.6.18 LogSQLTransferLogTable</A>
171<LI><A NAME="tex2html56"
172 HREF="node4.html#SECTION000461900000000000000">3.6.19 LogSQLWhichCookie</A>
173<LI><A NAME="tex2html57"
174 HREF="node4.html#SECTION000462000000000000000">3.6.20 LogSQLWhichCookies</A>
175<LI><A NAME="tex2html58"
176 HREF="node4.html#SECTION000462100000000000000">3.6.21 LogSQLWhichHeadersIn</A>
177<LI><A NAME="tex2html59"
178 HREF="node4.html#SECTION000462200000000000000">3.6.22 LogSQLWhichHeadersOut</A>
179<LI><A NAME="tex2html60"
180 HREF="node4.html#SECTION000462300000000000000">3.6.23 LogSQLWhichNotes</A>
181</UL>
182</UL>
183<BR>
184<LI><A NAME="tex2html61"
185 HREF="node5.html">4 FAQ</A>
186<UL>
187<LI><A NAME="tex2html62"
188 HREF="node5.html#SECTION00051000000000000000">4.1 General module questions</A>
189<UL>
190<LI><A NAME="tex2html63"
191 HREF="node5.html#SECTION00051100000000000000">4.1.1 Why log to an SQL database?</A>
192<LI><A NAME="tex2html64"
193 HREF="node5.html#SECTION00051200000000000000">4.1.2 Why use MySQL? Are there alternatives?</A>
194<LI><A NAME="tex2html65"
195 HREF="node5.html#SECTION00051300000000000000">4.1.3 Is this code production-ready?</A>
196<LI><A NAME="tex2html66"
197 HREF="node5.html#SECTION00051400000000000000">4.1.4 Who's using mod_log_sql?</A>
198<LI><A NAME="tex2html67"
199 HREF="node5.html#SECTION00051500000000000000">4.1.5 Why doesn't the module also replace the Apache ErrorLog?</A>
200<LI><A NAME="tex2html68"
201 HREF="node5.html#SECTION00051600000000000000">4.1.6 Does mod_log_sql work with Apache 2.x?</A>
202<LI><A NAME="tex2html69"
203 HREF="node5.html#SECTION00051700000000000000">4.1.7 Does mod_log_sql connect to MySQL via TCP/IP or a socket?</A>
204<LI><A NAME="tex2html70"
205 HREF="node5.html#SECTION00051800000000000000">4.1.8 I have discovered a bug. Who can I contact?</A>
206</UL>
207<LI><A NAME="tex2html71"
208 HREF="node5.html#SECTION00052000000000000000">4.2 Problems</A>
209<UL>
210<LI><A NAME="tex2html72"
211 HREF="node5.html#SECTION00052100000000000000">4.2.1 Apache segfaults when using PHP and mod_log_sql</A>
212<LI><A NAME="tex2html73"
213 HREF="node5.html#SECTION00052200000000000000">4.2.2 Apache appears to start up fine, but nothing
214is getting logged in the database</A>
215<LI><A NAME="tex2html74"
216 HREF="node5.html#SECTION00052300000000000000">4.2.3 Why do I get the message ``insufficient configuration info to
217establish database link'' in my Apache error log?</A>
218<LI><A NAME="tex2html75"
219 HREF="node5.html#SECTION00052400000000000000">4.2.4 My database cannot handle all the open connections from mod_log_sql,
220is there anything I can do?</A>
221<LI><A NAME="tex2html76"
222 HREF="node5.html#SECTION00052500000000000000">4.2.5 Why do I occasionally see a ``lost connection to MySQL server''
223message in my Apache error log?</A>
224</UL>
225<LI><A NAME="tex2html77"
226 HREF="node5.html#SECTION00053000000000000000">4.3 Performance and Tuning</A>
227<UL>
228<LI><A NAME="tex2html78"
229 HREF="node5.html#SECTION00053100000000000000">4.3.1 How well does it perform?</A>
230<LI><A NAME="tex2html79"
231 HREF="node5.html#SECTION00053200000000000000">4.3.2 Do I need to be worried about all the running MySQL children? Will
232holding open <I>n</I> Apache-to-MySQL connections consume a lot of
233memory? </A>
234<LI><A NAME="tex2html80"
235 HREF="node5.html#SECTION00053300000000000000">4.3.3 My webserver cannot handle all the traffic that my site receives,
236is there anything I can do?</A>
237<LI><A NAME="tex2html81"
238 HREF="node5.html#SECTION00053400000000000000">4.3.4 What is the issue with activating delayed
239inserts?</A>
240</UL>
241<LI><A NAME="tex2html82"
242 HREF="node5.html#SECTION00054000000000000000">4.4 ``How do I...?'' - accomplishing certain tasks</A>
243<UL>
244<LI><A NAME="tex2html83"
245 HREF="node5.html#SECTION00054100000000000000">4.4.1 I am using LogSQLMassVirtualHosting, and sometimes a single VirtualHost
246gets logged to two different tables. How do I prevent that?</A>
247<LI><A NAME="tex2html84"
248 HREF="node5.html#SECTION00054200000000000000">4.4.2 How do I extract the data in a format that my analysis tool can understand?</A>
249<LI><A NAME="tex2html85"
250 HREF="node5.html#SECTION00054300000000000000">4.4.3 How can I log mod_usertrack cookies?</A>
251<LI><A NAME="tex2html86"
252 HREF="node5.html#SECTION00054400000000000000">4.4.4 What if I want to log more than one cookie? What is the difference
253between LogSQLWhichCookie and LogSQLWhichCookies?</A>
254<LI><A NAME="tex2html87"
255 HREF="node5.html#SECTION00054500000000000000">4.4.5 What are the SSL logging features, and how do I activate them?</A>
256</UL>
257</UL>
258<BR>
259<LI><A NAME="tex2html88"
260 HREF="node6.html">About this document ...</A>
261</UL>
262<!--End of Table of Child-Links-->
263<BR><HR>
264<ADDRESS>
265Chris Powell
2662002-12-18
267</ADDRESS>
268</BODY>
269</HTML>
diff --git a/docs/img1.png b/docs/img1.png
new file mode 100644
index 0000000..d34217e
--- /dev/null
+++ b/docs/img1.png
Binary files differ
diff --git a/docs/img2.png b/docs/img2.png
new file mode 100644
index 0000000..df51a7c
--- /dev/null
+++ b/docs/img2.png
Binary files differ
diff --git a/docs/img3.png b/docs/img3.png
new file mode 100644
index 0000000..1cd68cf
--- /dev/null
+++ b/docs/img3.png
Binary files differ
diff --git a/docs/img4.png b/docs/img4.png
new file mode 100644
index 0000000..1e2543f
--- /dev/null
+++ b/docs/img4.png
Binary files differ
diff --git a/docs/index.html b/docs/index.html
new file mode 100644
index 0000000..d63b31f
--- /dev/null
+++ b/docs/index.html
@@ -0,0 +1,269 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2
3<!--Converted with LaTeX2HTML 2002-1 (1.68)
4original version by: Nikos Drakos, CBLU, University of Leeds
5* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6* with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
8<HTML>
9<HEAD>
10<TITLE>Installing and Running mod_log_sql</TITLE>
11<META NAME="description" CONTENT="Installing and Running mod_log_sql">
12<META NAME="keywords" CONTENT="documentation">
13<META NAME="resource-type" CONTENT="document">
14<META NAME="distribution" CONTENT="global">
15
16<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17<META NAME="Generator" CONTENT="LaTeX2HTML v2002-1">
18<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
19
20<LINK REL="STYLESHEET" HREF="documentation.css">
21
22<LINK REL="next" HREF="node1.html">
23</HEAD>
24
25<BODY >
26<!--Navigation Panel-->
27<A NAME="tex2html6"
28 HREF="node1.html">
29<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
30<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up_g.png">
31<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev_g.png">
32<A NAME="tex2html4"
33 HREF="node1.html">
34<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
35<BR>
36<B> Next:</B> <A NAME="tex2html7"
37 HREF="node1.html">Contents</A>
38 &nbsp; <B> <A NAME="tex2html5"
39 HREF="node1.html">Contents</A></B>
40<BR>
41<BR>
42<!--End of Navigation Panel-->
43
44<P>
45
46
47
48
49<P>
50
51<P>
52<H1 ALIGN="CENTER">Installing and Running mod_log_sql</H1>
53<P ALIGN="CENTER"><STRONG>Christopher Powell, &lt;chris@grubbybaby.com&gt; </STRONG></P>
54<BR><HR>
55<!--Table of Child-Links-->
56<A NAME="CHILD_LINKS"></A>
57
58<UL>
59<LI><A NAME="tex2html8"
60 HREF="node1.html">Contents</A>
61<LI><A NAME="tex2html9"
62 HREF="node2.html">1 Introduction</A>
63<UL>
64<LI><A NAME="tex2html10"
65 HREF="node2.html#SECTION00021000000000000000">1.1 Homepage </A>
66<LI><A NAME="tex2html11"
67 HREF="node2.html#SECTION00022000000000000000">1.2 Summary</A>
68<LI><A NAME="tex2html12"
69 HREF="node2.html#SECTION00023000000000000000">1.3 Approach</A>
70<LI><A NAME="tex2html13"
71 HREF="node2.html#SECTION00024000000000000000">1.4 What gets logged by default? </A>
72<LI><A NAME="tex2html14"
73 HREF="node2.html#SECTION00025000000000000000">1.5 Miscellaneous Notes</A>
74<LI><A NAME="tex2html15"
75 HREF="node2.html#SECTION00026000000000000000">1.6 Author / Maintainer</A>
76</UL>
77<BR>
78<LI><A NAME="tex2html16"
79 HREF="node3.html">2 Installation</A>
80<UL>
81<LI><A NAME="tex2html17"
82 HREF="node3.html#SECTION00031000000000000000">2.1 Requirements</A>
83<LI><A NAME="tex2html18"
84 HREF="node3.html#SECTION00032000000000000000">2.2 Platform-specific notes</A>
85<UL>
86<LI><A NAME="tex2html19"
87 HREF="node3.html#SECTION00032100000000000000">2.2.1 Solaris</A>
88<LI><A NAME="tex2html20"
89 HREF="node3.html#SECTION00032200000000000000">2.2.2 BSD</A>
90<LI><A NAME="tex2html21"
91 HREF="node3.html#SECTION00032300000000000000">2.2.3 Win32</A>
92</UL>
93<LI><A NAME="tex2html22"
94 HREF="node3.html#SECTION00033000000000000000">2.3 Do I want a DSO or a static module?</A>
95<LI><A NAME="tex2html23"
96 HREF="node3.html#SECTION00034000000000000000">2.4 Installation as an Apache DSO (Preferred) </A>
97<LI><A NAME="tex2html24"
98 HREF="node3.html#SECTION00035000000000000000">2.5 Installation as a static module compiled into
99httpd</A>
100</UL>
101<BR>
102<LI><A NAME="tex2html25"
103 HREF="node4.html">3 Configuration</A>
104<UL>
105<LI><A NAME="tex2html26"
106 HREF="node4.html#SECTION00041000000000000000">3.1 Preparing MySQL for logging</A>
107<LI><A NAME="tex2html27"
108 HREF="node4.html#SECTION00042000000000000000">3.2 A very basic logging setup in Apache</A>
109<LI><A NAME="tex2html28"
110 HREF="node4.html#SECTION00043000000000000000">3.3 Testing the basic setup</A>
111<LI><A NAME="tex2html29"
112 HREF="node4.html#SECTION00044000000000000000">3.4 How to tune logging with run-time directives</A>
113<UL>
114<LI><A NAME="tex2html30"
115 HREF="node4.html#SECTION00044100000000000000">3.4.1 Instructing the module what to log</A>
116<LI><A NAME="tex2html31"
117 HREF="node4.html#SECTION00044200000000000000">3.4.2 Instructing the module what NOT to log using filtering
118directives</A>
119</UL>
120<LI><A NAME="tex2html32"
121 HREF="node4.html#SECTION00045000000000000000">3.5 Advanced logging scenarios</A>
122<UL>
123<LI><A NAME="tex2html33"
124 HREF="node4.html#SECTION00045100000000000000">3.5.1 Using the module in an ISP environment</A>
125<LI><A NAME="tex2html34"
126 HREF="node4.html#SECTION00045200000000000000">3.5.2 Logging many-to-one data in separate tables</A>
127<LI><A NAME="tex2html35"
128 HREF="node4.html#SECTION00045300000000000000">3.5.3 Using the same database for production and test</A>
129<LI><A NAME="tex2html36"
130 HREF="node4.html#SECTION00045400000000000000">3.5.4 Optimizing for a busy database</A>
131</UL>
132<LI><A NAME="tex2html37"
133 HREF="node4.html#SECTION00046000000000000000">3.6 Configuration directive reference</A>
134<UL>
135<LI><A NAME="tex2html38"
136 HREF="node4.html#SECTION00046100000000000000">3.6.1 LogSQLCookieLogTable</A>
137<LI><A NAME="tex2html39"
138 HREF="node4.html#SECTION00046200000000000000">3.6.2 LogSQLCreateTables</A>
139<LI><A NAME="tex2html40"
140 HREF="node4.html#SECTION00046300000000000000">3.6.3 LogSQLDatabase </A>
141<LI><A NAME="tex2html41"
142 HREF="node4.html#SECTION00046400000000000000">3.6.4 LogSQLForcePreserve</A>
143<LI><A NAME="tex2html42"
144 HREF="node4.html#SECTION00046500000000000000">3.6.5 LogSQLHeadersInLogTable</A>
145<LI><A NAME="tex2html43"
146 HREF="node4.html#SECTION00046600000000000000">3.6.6 LogSQLHeadersOutLogTable</A>
147<LI><A NAME="tex2html44"
148 HREF="node4.html#SECTION00046700000000000000">3.6.7 LogSQLLoginInfo </A>
149<LI><A NAME="tex2html45"
150 HREF="node4.html#SECTION00046800000000000000">3.6.8 LogSQLMachineID</A>
151<LI><A NAME="tex2html46"
152 HREF="node4.html#SECTION00046900000000000000">3.6.9 LogSQLMassVirtualHosting</A>
153<LI><A NAME="tex2html47"
154 HREF="node4.html#SECTION000461000000000000000">3.6.10 LogSQLNotesLogTable</A>
155<LI><A NAME="tex2html48"
156 HREF="node4.html#SECTION000461100000000000000">3.6.11 LogSQLPreserveFile</A>
157<LI><A NAME="tex2html49"
158 HREF="node4.html#SECTION000461200000000000000">3.6.12 LogSQLRemhostIgnore</A>
159<LI><A NAME="tex2html50"
160 HREF="node4.html#SECTION000461300000000000000">3.6.13 LogSQLRequestAccept</A>
161<LI><A NAME="tex2html51"
162 HREF="node4.html#SECTION000461400000000000000">3.6.14 LogSQLRequestIgnore</A>
163<LI><A NAME="tex2html52"
164 HREF="node4.html#SECTION000461500000000000000">3.6.15 LogSQLSocketFile </A>
165<LI><A NAME="tex2html53"
166 HREF="node4.html#SECTION000461600000000000000">3.6.16 LogSQLTCPPort</A>
167<LI><A NAME="tex2html54"
168 HREF="node4.html#SECTION000461700000000000000">3.6.17 LogSQLTransferLogFormat </A>
169<LI><A NAME="tex2html55"
170 HREF="node4.html#SECTION000461800000000000000">3.6.18 LogSQLTransferLogTable</A>
171<LI><A NAME="tex2html56"
172 HREF="node4.html#SECTION000461900000000000000">3.6.19 LogSQLWhichCookie</A>
173<LI><A NAME="tex2html57"
174 HREF="node4.html#SECTION000462000000000000000">3.6.20 LogSQLWhichCookies</A>
175<LI><A NAME="tex2html58"
176 HREF="node4.html#SECTION000462100000000000000">3.6.21 LogSQLWhichHeadersIn</A>
177<LI><A NAME="tex2html59"
178 HREF="node4.html#SECTION000462200000000000000">3.6.22 LogSQLWhichHeadersOut</A>
179<LI><A NAME="tex2html60"
180 HREF="node4.html#SECTION000462300000000000000">3.6.23 LogSQLWhichNotes</A>
181</UL>
182</UL>
183<BR>
184<LI><A NAME="tex2html61"
185 HREF="node5.html">4 FAQ</A>
186<UL>
187<LI><A NAME="tex2html62"
188 HREF="node5.html#SECTION00051000000000000000">4.1 General module questions</A>
189<UL>
190<LI><A NAME="tex2html63"
191 HREF="node5.html#SECTION00051100000000000000">4.1.1 Why log to an SQL database?</A>
192<LI><A NAME="tex2html64"
193 HREF="node5.html#SECTION00051200000000000000">4.1.2 Why use MySQL? Are there alternatives?</A>
194<LI><A NAME="tex2html65"
195 HREF="node5.html#SECTION00051300000000000000">4.1.3 Is this code production-ready?</A>
196<LI><A NAME="tex2html66"
197 HREF="node5.html#SECTION00051400000000000000">4.1.4 Who's using mod_log_sql?</A>
198<LI><A NAME="tex2html67"
199 HREF="node5.html#SECTION00051500000000000000">4.1.5 Why doesn't the module also replace the Apache ErrorLog?</A>
200<LI><A NAME="tex2html68"
201 HREF="node5.html#SECTION00051600000000000000">4.1.6 Does mod_log_sql work with Apache 2.x?</A>
202<LI><A NAME="tex2html69"
203 HREF="node5.html#SECTION00051700000000000000">4.1.7 Does mod_log_sql connect to MySQL via TCP/IP or a socket?</A>
204<LI><A NAME="tex2html70"
205 HREF="node5.html#SECTION00051800000000000000">4.1.8 I have discovered a bug. Who can I contact?</A>
206</UL>
207<LI><A NAME="tex2html71"
208 HREF="node5.html#SECTION00052000000000000000">4.2 Problems</A>
209<UL>
210<LI><A NAME="tex2html72"
211 HREF="node5.html#SECTION00052100000000000000">4.2.1 Apache segfaults when using PHP and mod_log_sql</A>
212<LI><A NAME="tex2html73"
213 HREF="node5.html#SECTION00052200000000000000">4.2.2 Apache appears to start up fine, but nothing
214is getting logged in the database</A>
215<LI><A NAME="tex2html74"
216 HREF="node5.html#SECTION00052300000000000000">4.2.3 Why do I get the message ``insufficient configuration info to
217establish database link'' in my Apache error log?</A>
218<LI><A NAME="tex2html75"
219 HREF="node5.html#SECTION00052400000000000000">4.2.4 My database cannot handle all the open connections from mod_log_sql,
220is there anything I can do?</A>
221<LI><A NAME="tex2html76"
222 HREF="node5.html#SECTION00052500000000000000">4.2.5 Why do I occasionally see a ``lost connection to MySQL server''
223message in my Apache error log?</A>
224</UL>
225<LI><A NAME="tex2html77"
226 HREF="node5.html#SECTION00053000000000000000">4.3 Performance and Tuning</A>
227<UL>
228<LI><A NAME="tex2html78"
229 HREF="node5.html#SECTION00053100000000000000">4.3.1 How well does it perform?</A>
230<LI><A NAME="tex2html79"
231 HREF="node5.html#SECTION00053200000000000000">4.3.2 Do I need to be worried about all the running MySQL children? Will
232holding open <I>n</I> Apache-to-MySQL connections consume a lot of
233memory? </A>
234<LI><A NAME="tex2html80"
235 HREF="node5.html#SECTION00053300000000000000">4.3.3 My webserver cannot handle all the traffic that my site receives,
236is there anything I can do?</A>
237<LI><A NAME="tex2html81"
238 HREF="node5.html#SECTION00053400000000000000">4.3.4 What is the issue with activating delayed
239inserts?</A>
240</UL>
241<LI><A NAME="tex2html82"
242 HREF="node5.html#SECTION00054000000000000000">4.4 ``How do I...?'' - accomplishing certain tasks</A>
243<UL>
244<LI><A NAME="tex2html83"
245 HREF="node5.html#SECTION00054100000000000000">4.4.1 I am using LogSQLMassVirtualHosting, and sometimes a single VirtualHost
246gets logged to two different tables. How do I prevent that?</A>
247<LI><A NAME="tex2html84"
248 HREF="node5.html#SECTION00054200000000000000">4.4.2 How do I extract the data in a format that my analysis tool can understand?</A>
249<LI><A NAME="tex2html85"
250 HREF="node5.html#SECTION00054300000000000000">4.4.3 How can I log mod_usertrack cookies?</A>
251<LI><A NAME="tex2html86"
252 HREF="node5.html#SECTION00054400000000000000">4.4.4 What if I want to log more than one cookie? What is the difference
253between LogSQLWhichCookie and LogSQLWhichCookies?</A>
254<LI><A NAME="tex2html87"
255 HREF="node5.html#SECTION00054500000000000000">4.4.5 What are the SSL logging features, and how do I activate them?</A>
256</UL>
257</UL>
258<BR>
259<LI><A NAME="tex2html88"
260 HREF="node6.html">About this document ...</A>
261</UL>
262<!--End of Table of Child-Links-->
263<BR><HR>
264<ADDRESS>
265Chris Powell
2662002-12-18
267</ADDRESS>
268</BODY>
269</HTML>
diff --git a/docs/next.png b/docs/next.png
new file mode 100644
index 0000000..1628652
--- /dev/null
+++ b/docs/next.png
Binary files differ
diff --git a/docs/next_g.png b/docs/next_g.png
new file mode 100644
index 0000000..9d3f591
--- /dev/null
+++ b/docs/next_g.png
Binary files differ
diff --git a/docs/node1.html b/docs/node1.html
new file mode 100644
index 0000000..0238180
--- /dev/null
+++ b/docs/node1.html
@@ -0,0 +1,128 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2
3<!--Converted with LaTeX2HTML 2002-1 (1.68)
4original version by: Nikos Drakos, CBLU, University of Leeds
5* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6* with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
8<HTML>
9<HEAD>
10<TITLE>Contents</TITLE>
11<META NAME="description" CONTENT="Contents">
12<META NAME="keywords" CONTENT="documentation">
13<META NAME="resource-type" CONTENT="document">
14<META NAME="distribution" CONTENT="global">
15
16<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17<META NAME="Generator" CONTENT="LaTeX2HTML v2002-1">
18<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
19
20<LINK REL="STYLESHEET" HREF="documentation.css">
21
22<LINK REL="next" HREF="node2.html">
23<LINK REL="previous" HREF="documentation.html">
24<LINK REL="up" HREF="documentation.html">
25<LINK REL="next" HREF="node2.html">
26</HEAD>
27
28<BODY >
29<!--Navigation Panel-->
30<A NAME="tex2html97"
31 HREF="node2.html">
32<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
33<A NAME="tex2html95"
34 HREF="documentation.html">
35<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
36<A NAME="tex2html89"
37 HREF="documentation.html">
38<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
39<BR>
40<B> Next:</B> <A NAME="tex2html98"
41 HREF="node2.html">1 Introduction</A>
42<B> Up:</B> <A NAME="tex2html96"
43 HREF="documentation.html">Installing and Running mod_log_sql</A>
44<B> Previous:</B> <A NAME="tex2html90"
45 HREF="documentation.html">Installing and Running mod_log_sql</A>
46<BR>
47<BR>
48<!--End of Navigation Panel-->
49<BR>
50
51<H2><A NAME="SECTION00010000000000000000">
52Contents</A>
53</H2>
54<!--Table of Contents-->
55
56<UL>
57<LI><A NAME="tex2html99"
58 HREF="node2.html">1 Introduction</A>
59<UL>
60<LI><A NAME="tex2html100"
61 HREF="node2.html#SECTION00021000000000000000">1.1 Homepage </A>
62<LI><A NAME="tex2html101"
63 HREF="node2.html#SECTION00022000000000000000">1.2 Summary</A>
64<LI><A NAME="tex2html102"
65 HREF="node2.html#SECTION00023000000000000000">1.3 Approach</A>
66<LI><A NAME="tex2html103"
67 HREF="node2.html#SECTION00024000000000000000">1.4 What gets logged by default? </A>
68<LI><A NAME="tex2html104"
69 HREF="node2.html#SECTION00025000000000000000">1.5 Miscellaneous Notes</A>
70<LI><A NAME="tex2html105"
71 HREF="node2.html#SECTION00026000000000000000">1.6 Author / Maintainer</A>
72</UL>
73<BR>
74<LI><A NAME="tex2html106"
75 HREF="node3.html">2 Installation</A>
76<UL>
77<LI><A NAME="tex2html107"
78 HREF="node3.html#SECTION00031000000000000000">2.1 Requirements</A>
79<LI><A NAME="tex2html108"
80 HREF="node3.html#SECTION00032000000000000000">2.2 Platform-specific notes</A>
81<LI><A NAME="tex2html109"
82 HREF="node3.html#SECTION00033000000000000000">2.3 Do I want a DSO or a static module?</A>
83<LI><A NAME="tex2html110"
84 HREF="node3.html#SECTION00034000000000000000">2.4 Installation as an Apache DSO (Preferred) </A>
85<LI><A NAME="tex2html111"
86 HREF="node3.html#SECTION00035000000000000000">2.5 Installation as a static module compiled into
87httpd</A>
88</UL>
89<BR>
90<LI><A NAME="tex2html112"
91 HREF="node4.html">3 Configuration</A>
92<UL>
93<LI><A NAME="tex2html113"
94 HREF="node4.html#SECTION00041000000000000000">3.1 Preparing MySQL for logging</A>
95<LI><A NAME="tex2html114"
96 HREF="node4.html#SECTION00042000000000000000">3.2 A very basic logging setup in Apache</A>
97<LI><A NAME="tex2html115"
98 HREF="node4.html#SECTION00043000000000000000">3.3 Testing the basic setup</A>
99<LI><A NAME="tex2html116"
100 HREF="node4.html#SECTION00044000000000000000">3.4 How to tune logging with run-time directives</A>
101<LI><A NAME="tex2html117"
102 HREF="node4.html#SECTION00045000000000000000">3.5 Advanced logging scenarios</A>
103<LI><A NAME="tex2html118"
104 HREF="node4.html#SECTION00046000000000000000">3.6 Configuration directive reference</A>
105</UL>
106<BR>
107<LI><A NAME="tex2html119"
108 HREF="node5.html">4 FAQ</A>
109<UL>
110<LI><A NAME="tex2html120"
111 HREF="node5.html#SECTION00051000000000000000">4.1 General module questions</A>
112<LI><A NAME="tex2html121"
113 HREF="node5.html#SECTION00052000000000000000">4.2 Problems</A>
114<LI><A NAME="tex2html122"
115 HREF="node5.html#SECTION00053000000000000000">4.3 Performance and Tuning</A>
116<LI><A NAME="tex2html123"
117 HREF="node5.html#SECTION00054000000000000000">4.4 ``How do I...?'' - accomplishing certain tasks</A>
118</UL></UL>
119<!--End of Table of Contents-->
120
121<P>
122<BR><HR>
123<ADDRESS>
124Chris Powell
1252002-12-18
126</ADDRESS>
127</BODY>
128</HTML>
diff --git a/docs/node2.html b/docs/node2.html
new file mode 100644
index 0000000..33a2849
--- /dev/null
+++ b/docs/node2.html
@@ -0,0 +1,276 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2
3<!--Converted with LaTeX2HTML 2002-1 (1.68)
4original version by: Nikos Drakos, CBLU, University of Leeds
5* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6* with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
8<HTML>
9<HEAD>
10<TITLE>1 Introduction</TITLE>
11<META NAME="description" CONTENT="1 Introduction">
12<META NAME="keywords" CONTENT="documentation">
13<META NAME="resource-type" CONTENT="document">
14<META NAME="distribution" CONTENT="global">
15
16<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17<META NAME="Generator" CONTENT="LaTeX2HTML v2002-1">
18<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
19
20<LINK REL="STYLESHEET" HREF="documentation.css">
21
22<LINK REL="next" HREF="node3.html">
23<LINK REL="previous" HREF="node1.html">
24<LINK REL="up" HREF="documentation.html">
25<LINK REL="next" HREF="node3.html">
26</HEAD>
27
28<BODY >
29<!--Navigation Panel-->
30<A NAME="tex2html134"
31 HREF="node3.html">
32<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
33<A NAME="tex2html130"
34 HREF="documentation.html">
35<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
36<A NAME="tex2html124"
37 HREF="node1.html">
38<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
39<A NAME="tex2html132"
40 HREF="node1.html">
41<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
42<BR>
43<B> Next:</B> <A NAME="tex2html135"
44 HREF="node3.html">2 Installation</A>
45<B> Up:</B> <A NAME="tex2html131"
46 HREF="documentation.html">Installing and Running mod_log_sql</A>
47<B> Previous:</B> <A NAME="tex2html125"
48 HREF="node1.html">Contents</A>
49 &nbsp; <B> <A NAME="tex2html133"
50 HREF="node1.html">Contents</A></B>
51<BR>
52<BR>
53<!--End of Navigation Panel-->
54<!--Table of Child-Links-->
55<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
56
57<UL>
58<LI><A NAME="tex2html136"
59 HREF="node2.html#SECTION00021000000000000000">1.1 Homepage </A>
60<LI><A NAME="tex2html137"
61 HREF="node2.html#SECTION00022000000000000000">1.2 Summary</A>
62<LI><A NAME="tex2html138"
63 HREF="node2.html#SECTION00023000000000000000">1.3 Approach</A>
64<LI><A NAME="tex2html139"
65 HREF="node2.html#SECTION00024000000000000000">1.4 What gets logged by default? </A>
66<LI><A NAME="tex2html140"
67 HREF="node2.html#SECTION00025000000000000000">1.5 Miscellaneous Notes</A>
68<LI><A NAME="tex2html141"
69 HREF="node2.html#SECTION00026000000000000000">1.6 Author / Maintainer</A>
70</UL>
71<!--End of Table of Child-Links-->
72<HR>
73
74<H1><A NAME="SECTION00020000000000000000">
751 Introduction</A>
76</H1>
77
78<P>
79
80<H2><A NAME="SECTION00021000000000000000">
811.1 Homepage </A>
82</H2>
83
84<P>
85
86<DL COMPACT>
87<DT>
88<DD>http://www.grubbybaby.com/mod_log_sql/
89</DD>
90</DL>
91<P>
92
93<H2><A NAME="SECTION00022000000000000000">
941.2 Summary</A>
95</H2>
96
97<P>
98This Apache module will permit you to log to a SQL database; it can
99log each access request as well as data associated with each request:
100cookies, notes, and inbound/outbound headers. Unlike logging to a
101flat text file - which is standard in Apache - a SQL-based log exhibits
102tremendous flexibility and power of data extraction. (See section
103<A HREF="node5.html#sub:why">4.1.1</A> in the FAQ for further discussion and examples of the
104advantages to SQL.)
105
106<P>
107This module can either replace or happily coexist with mod_log_config,
108Apache's text file logging facility. In addition to being more configurable
109than the standard module, mod_log_sql is much more flexible.
110
111<P>
112
113<H2><A NAME="SECTION00023000000000000000">
1141.3 Approach</A>
115</H2>
116
117<P>
118This project was formerly known as ``mod_log_mysql.'' It was
119renamed ``mod_log_sql'' in order to reflect the project goal
120of database-inspecificity. The module currently supports MySQL, but
121support for other database backends is underway.
122
123<P>
124In order to save speed and overhead, links are kept alive in between
125queries. This module uses one dedicated SQL link per httpd child,
126opened by each child process when it is born. Among other things,
127this means that this module supports logging into only one MySQL server,
128and for now, also, only one SQL database. But that's a small tradeoff
129compared to the blinding speed of this module. Error reporting is
130robust throughout the module and will inform the administrator of
131database issues in the Apache E<SMALL>RROR</SMALL>L<SMALL>OG</SMALL> for the server/virtual
132server.
133
134<P>
135Virtual hosts are supported in the same manner they are in the regular
136logging modules. The administrator defines some basic 'global' directives
137in the main server config, then defines more specific 'local' directives
138inside each VirtualHost stanza.
139
140<P>
141A robust &#34;preserve&#34; capability has now been implemented.
142This permits the module to preserve any failed INSERT commands to
143a local file on its machine. In any situation that the database is
144unavailable - e.g. the network fails or the database host is rebooted
145- mod_log_sql will note this in the error log and begin appending
146its log entries to the preserve file (which is created with the user
147&amp; group ID of the running Apache process, e.g. &#34;nobody/nobody&#34;
148on many Linux installations). When database availablity returns, mod_log_sql
149seamlessly resumes logging to it. When convenient for the sysadmin,
150he/she can easily import the preserve file into the database because
151it is simply a series of SQL insert statements.
152
153<P>
154
155<H2><A NAME="SECTION00024000000000000000">
1561.4 What gets logged by default? </A>
157</H2>
158
159<P>
160All the data that would be contained in the &#34;Combined Log
161Format&#34; is logged by default, plus a little extra. Your best
162bet is to begin by accepting this default, then later customize the
163log configuration based on your needs.
164
165<P>
166The documentation of the run-time directives includes a full explanation
167of what you can log, including examples - see section <A HREF="node4.html#sec:ConfRef">3.6</A>.
168
169<P>
170
171<H2><A NAME="SECTION00025000000000000000">
1721.5 Miscellaneous Notes</A>
173</H2>
174
175<P>
176
177<UL>
178<LI>Note which directives go in the 'main server config' and which directives
179apply to the 'virtual host config'. This is made clear in the directive
180documentation.
181</LI>
182<LI>The 'time_stamp' field is stored in an UNSIGNED INTEGER column, in
183the standard unix ``seconds since the epoch'' format. This is
184superior to storing the access time as a string due to size requirements:
185an UNSIGNED INT requires 4 bytes, whereas an Apache date string -
186e.g. &#34;18/Nov/2001:13:59:52 -0800&#34; - requires 26
187bytes: those extra 22 bytes become significant when multiplied by
188thousands of accesses on a busy server. Besides, an INT type is far
189more flexible for comparisons, etc.
190
191<P>
192In MySQL 3.21 and above you can easily convert this to a human readable
193format using from_unixtime(), e.g.:
194
195<P>
196
197<DL COMPACT>
198<DT>
199<DD>select&nbsp;remote_host,request_uri,from_unixtime(time_stamp)&nbsp;from&nbsp;access_log;
200</DD>
201</DL>The enclosed perl program ``make_combined_log.pl'' extracts
202your access log in a format that is completely compatible with the
203Combined Log Format. You can then feed this to your favorite web log
204analysis tool.
205
206<P>
207</LI>
208<LI>The table's string values can be CHAR or VARCHAR, at a length of your
209choice. VARCHAR is superior because it truncates long strings; CHAR
210types are fixed-length and will be padded with spaces, resulting in
211waste. Just like the time_stamp issue described above, that kind
212of space waste multiplies over thousands of records.
213</LI>
214<LI>Be careful not to go overboard setting fields to NOT NULL. If a field
215is marked NOT NULL then it must contain data in the INSERT statement,
216or the INSERT will fail. These mysterious failures can be quite frustrating
217and difficult to debug.
218</LI>
219<LI>When Apache logs a numeric field, it uses a '-' character to mean
220``not applicable,'' e.g. the number of bytes returned on a 304
221(unchanged) request. Since '-' is an illegal character in an SQL numeric
222field, such fields are assigned the value 0 instead of '-' which,
223of course, makes perfect sense anyway.
224</LI>
225</UL>
226
227<P>
228
229<H2><A NAME="SECTION00026000000000000000">
2301.6 Author / Maintainer</A>
231</H2>
232
233<P>
234The actual logging code was taken from the already existing flat file
235text modules, so all that credit goes to the Apache Server group.
236
237<P>
238The MySQL routines and directives were added by Zeev Suraski &lt;bourbon@netvision.net.il&gt;.
239
240<P>
241All changes from 1.06+ and the new documentation were added by Chris
242Powell &lt;chris@grubbybaby.com&gt;. It seems that the module had fallen
243into the &#34;unmaintained&#34; category - it hadn't been
244updated since 1998 - so Chris adopted it as the new maintainer.
245
246<P>
247<HR>
248<!--Navigation Panel-->
249<A NAME="tex2html134"
250 HREF="node3.html">
251<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
252<A NAME="tex2html130"
253 HREF="documentation.html">
254<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
255<A NAME="tex2html124"
256 HREF="node1.html">
257<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
258<A NAME="tex2html132"
259 HREF="node1.html">
260<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
261<BR>
262<B> Next:</B> <A NAME="tex2html135"
263 HREF="node3.html">2 Installation</A>
264<B> Up:</B> <A NAME="tex2html131"
265 HREF="documentation.html">Installing and Running mod_log_sql</A>
266<B> Previous:</B> <A NAME="tex2html125"
267 HREF="node1.html">Contents</A>
268 &nbsp; <B> <A NAME="tex2html133"
269 HREF="node1.html">Contents</A></B>
270<!--End of Navigation Panel-->
271<ADDRESS>
272Chris Powell
2732002-12-18
274</ADDRESS>
275</BODY>
276</HTML>
diff --git a/docs/node3.html b/docs/node3.html
new file mode 100644
index 0000000..e832759
--- /dev/null
+++ b/docs/node3.html
@@ -0,0 +1,664 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2
3<!--Converted with LaTeX2HTML 2002-1 (1.68)
4original version by: Nikos Drakos, CBLU, University of Leeds
5* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6* with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
8<HTML>
9<HEAD>
10<TITLE>2 Installation</TITLE>
11<META NAME="description" CONTENT="2 Installation">
12<META NAME="keywords" CONTENT="documentation">
13<META NAME="resource-type" CONTENT="document">
14<META NAME="distribution" CONTENT="global">
15
16<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17<META NAME="Generator" CONTENT="LaTeX2HTML v2002-1">
18<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
19
20<LINK REL="STYLESHEET" HREF="documentation.css">
21
22<LINK REL="next" HREF="node4.html">
23<LINK REL="previous" HREF="node2.html">
24<LINK REL="up" HREF="documentation.html">
25<LINK REL="next" HREF="node4.html">
26</HEAD>
27
28<BODY >
29<!--Navigation Panel-->
30<A NAME="tex2html152"
31 HREF="node4.html">
32<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
33<A NAME="tex2html148"
34 HREF="documentation.html">
35<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
36<A NAME="tex2html142"
37 HREF="node2.html">
38<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
39<A NAME="tex2html150"
40 HREF="node1.html">
41<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
42<BR>
43<B> Next:</B> <A NAME="tex2html153"
44 HREF="node4.html">3 Configuration</A>
45<B> Up:</B> <A NAME="tex2html149"
46 HREF="documentation.html">Installing and Running mod_log_sql</A>
47<B> Previous:</B> <A NAME="tex2html143"
48 HREF="node2.html">1 Introduction</A>
49 &nbsp; <B> <A NAME="tex2html151"
50 HREF="node1.html">Contents</A></B>
51<BR>
52<BR>
53<!--End of Navigation Panel-->
54<!--Table of Child-Links-->
55<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
56
57<UL>
58<LI><A NAME="tex2html154"
59 HREF="node3.html#SECTION00031000000000000000">2.1 Requirements</A>
60<LI><A NAME="tex2html155"
61 HREF="node3.html#SECTION00032000000000000000">2.2 Platform-specific notes</A>
62<UL>
63<LI><A NAME="tex2html156"
64 HREF="node3.html#SECTION00032100000000000000">2.2.1 Solaris</A>
65<LI><A NAME="tex2html157"
66 HREF="node3.html#SECTION00032200000000000000">2.2.2 BSD</A>
67<LI><A NAME="tex2html158"
68 HREF="node3.html#SECTION00032300000000000000">2.2.3 Win32</A>
69</UL>
70<BR>
71<LI><A NAME="tex2html159"
72 HREF="node3.html#SECTION00033000000000000000">2.3 Do I want a DSO or a static module?</A>
73<LI><A NAME="tex2html160"
74 HREF="node3.html#SECTION00034000000000000000">2.4 Installation as an Apache DSO (Preferred) </A>
75<LI><A NAME="tex2html161"
76 HREF="node3.html#SECTION00035000000000000000">2.5 Installation as a static module compiled into
77httpd</A>
78</UL>
79<!--End of Table of Child-Links-->
80<HR>
81
82<H1><A NAME="SECTION00030000000000000000">
832 Installation</A>
84</H1>
85
86<P>
87
88<H2><A NAME="SECTION00031000000000000000">
892.1 Requirements</A>
90</H2>
91
92<P>
93
94<UL>
95<LI>A compatible system. mod_log_sql was authored and tested on systems
96based on Red Hat Linux (Red Hat, Mandrake), but the module should
97easily adapt to any modern distribution. mod_log_sql has also been
98ported successfully to Solaris and FreeBSD.
99</LI>
100<LI>Apache 1.2 or 1.3. Ideally you should already have successfully compiled
101Apache and understand the process, but this document tries to make
102it simple for beginners.
103</LI>
104<LI>The MySQL development headers. This package is called different things
105on different distros. For example, Red Hat 6.x calls this RPM ``MySQL-devel''
106whereas Mandrake calls it ``libmysql10-devel.''
107</LI>
108<LI>MySQL &gt;= 3.23.15 configured, installed and running on either localhost
109or an accessible networked machine. You should already have a basic
110understanding of MySQL and how it functions.
111</LI>
112<LI>Optionally, if you want to be able to log SSL information such as
113keysize or cipher, you need OpenSSL and mod_ssl installed.
114</LI>
115</UL>
116
117<P>
118
119<H2><A NAME="SECTION00032000000000000000">
1202.2 Platform-specific notes</A>
121</H2>
122
123<P>
124These installation documents assume a relatively modern GNU/Linux
125scenario. mod_log_sql has been ported to other platforms; following
126are notes on compiling the module for those platforms.
127
128<P>
129
130<H3><A NAME="SECTION00032100000000000000">
1312.2.1 Solaris</A>
132</H3>
133
134<P>
135The nanosleep() function used in mod_log_sql relies on linking aginst
136the librt library. Make the following alterations before proceeding:
137
138<P>
139
140<OL>
141<LI>In Makefile, search for the string ``-lmysqlclient -lz'' and change
142it to read ``-lmysqlclient -lz -lrt''
143</LI>
144<LI>In part <A HREF="node3.html#step:Linking">8a</A> of section <A HREF="node3.html#sec:Static">2.5</A> below, change
145``-lmysqlclient -lm -lz'' to read ``-lmysqlclient -lm -lz -lrt''
146</LI>
147</OL>
148
149<P>
150
151<H3><A NAME="SECTION00032200000000000000">
1522.2.2 BSD</A>
153</H3>
154
155<P>
156No notes are available at present, but they are desired. If you have
157successfully ported mod_log_sql to BSD, <I>please</I> contact the maintaniner, Chris Powell (chris@grubbybaby.com)
158and help fill in this section.
159
160<P>
161
162<H3><A NAME="SECTION00032300000000000000">
1632.2.3 Win32</A>
164</H3>
165
166<P>
167No notes are available at present, but they are desired. If you have
168successfully ported mod_log_sql to Win32, <I>please</I> contact
169the maintaniner, Chris Powell (chris@grubbybaby.com) and help
170fill in this section.
171
172<P>
173
174<H2><A NAME="SECTION00033000000000000000">
1752.3 Do I want a DSO or a static module?</A>
176</H2>
177
178<P>
179You need to know the answer to this question before you proceed. The
180answer is pretty straightforward: what have you done in the past?
181If you like all your Apache modules to be dynamic, then you should
182keep doing that. If you're more of an old-school type and prefer to
183compile the modules right into apache, do that. Both methods work
184equally well.
185
186<P>
187FWIW, the DSO method is more modern and increasing in popularity because
188apxs takes care of a lot of dirty little details for you. As you'll
189see below, the static-module method is a little more complex.
190
191<P>
192
193<H2><A NAME="SECTION00034000000000000000">
1942.4 Installation as an Apache DSO (Preferred) </A>
195</H2>
196
197<P>
198
199<OL>
200<LI>Perform all the following steps as root so that you have install privs,
201etc. Unpack the archive into a working directory.
202
203<P>
204
205<DL COMPACT>
206<DT>
207<DD>#&nbsp;tar&nbsp;zxf&nbsp;mod_log_sql.tar.gz&nbsp;-C&nbsp;/usr/local/src&nbsp;
208
209<P>
210#&nbsp;cd&nbsp;/usr/local/src/mod_log_sql
211</DD>
212</DL>
213</LI>
214<LI>Edit Makefile and change the values of the variables in the first
215section.
216
217<P>
218
219<OL>
220<LI>These paths are <B>necessary:</B>
221
222<P>
223<DL>
224<DT><STRONG>APACHEINSTALLED:</STRONG></DT>
225<DD>the location where you installed Apache - usually
226/usr/local/apache, 'locate apxs' can help you find it.
227</DD>
228<DT><STRONG>APACHEHEADERS:</STRONG></DT>
229<DD>The location of your Apache header files, find using
230'locate httpd.h'
231</DD>
232<DT><STRONG>MYSQLLIBRARIES:</STRONG></DT>
233<DD>The location of your MySQL libraries, find using
234'locate libmysqlclient.so'
235</DD>
236<DT><STRONG>MYSQLHEADERS:</STRONG></DT>
237<DD>The location of your MySQL header files, find using
238'locate mysql.h'
239</DD>
240</DL>
241</LI>
242<LI><B>Optional</B>: if you compiled mod_ssl for Apache and want to
243log SSL data such as 'keysize' and 'cipher type':
244
245<P>
246<DL>
247<DT><STRONG>MODSSLHEADERS:</STRONG></DT>
248<DD>the location of your mod_ssl header files, find
249using 'locate mod_ssl.h'
250</DD>
251<DT><STRONG>DB1HEADERS:</STRONG></DT>
252<DD>the location of your db1 header files, find using 'locate
253ndbm.h'
254</DD>
255</DL>
256</LI>
257</OL>
258You do <B>not</B> need to compile SSL support into mod_log_sql
259in order to simply use it with a secure site. You only need to compile
260SSL support into mod_log_sql <B>if you want to log SSL-specific
261data</B> such as the cipher type.
262
263<P>
264</LI>
265<LI>IMPORTANT: If you are not logging SSL info, comment out MODSSLHDRS
266by putting a # character in front of it:
267
268<P>
269
270<DL COMPACT>
271<DT>
272<DD>#MODSSLHDRS=/usr/include/...
273</DD>
274</DL>
275</LI>
276<LI>Instruct apxs to compile the module as a DSO.
277
278<P>
279
280<DL COMPACT>
281<DT>
282<DD>#&nbsp;make&nbsp;dso
283</DD>
284</DL>You should see output similar to the following:
285
286<P>
287
288<DL COMPACT>
289<DT>
290<DD>/usr/local/Apache/bin/apxs&nbsp;-Wc,-O2&nbsp;-Wc,-Wall&nbsp;-Wc,-DEAPI&nbsp;-c&nbsp;-I/usr/...
291
292<P>
293gcc&nbsp;-DLINUX=22&nbsp;-DNO_DBM_REWRITEMAP&nbsp;-DMOD_SSL=208111&nbsp;-DUSE_HS...&nbsp;
294
295<P>
296gcc&nbsp;-shared&nbsp;-o&nbsp;mod_log_sql.so&nbsp;mod_log_sql.o&nbsp;-Wc,-O2&nbsp;-Wc,-Wall&nbsp;-Wc...
297</DD>
298</DL>You should see no errors and have a new file called &#34;mod_log_sql.so&#34;
299in your directory.
300
301<P>
302</LI>
303<LI>Instruct apxs to install the DSO.
304
305<P>
306
307<DL COMPACT>
308<DT>
309<DD>#&nbsp;make&nbsp;dsoinstall
310</DD>
311</DL>You should see output similar to the following:
312
313<P>
314
315<DL COMPACT>
316<DT>
317<DD>/usr/local/Apache/bin/apxs&nbsp;-i&nbsp;mod_log_sql.so&nbsp;
318
319<P>
320cp&nbsp;mod_log_sql.so&nbsp;/usr/local/Apache/libexec/mod_log_sql.so&nbsp;
321
322<P>
323chmod&nbsp;755&nbsp;/usr/local/Apache/libexec/mod_log_sql.so&nbsp;
324</DD>
325</DL>
326</LI>
327<LI>Load and activate the module in httpd.conf:
328
329<P>
330
331<OL>
332<LI>Insert this line in the same area as other logging modules, e.g. near
333``LoadModule config_log_module'':
334
335<P>
336
337<DL COMPACT>
338<DT>
339<DD>LoadModule&nbsp;sql_log_module&nbsp;libexec/mod_log_sql.so
340</DD>
341</DL>
342</LI>
343<LI>Insert this line in the same area as other logging modules, e.g. near
344``AddModule mod_log_config.c'':
345
346<P>
347
348<DL COMPACT>
349<DT>
350<DD>AddModule&nbsp;mod_log_sql.c
351</DD>
352</DL>
353</LI>
354</OL>
355</LI>
356<LI>Module ordering within httpd.conf is important if you are logging
357SSL information. Please ensure that
358
359<P>
360
361<DL COMPACT>
362<DT>
363<DD>LoadModule&nbsp;ssl_module&nbsp;libexec/libssl.so
364</DD>
365</DL>comes before
366
367<P>
368
369<DL COMPACT>
370<DT>
371<DD>LoadModule&nbsp;sql_log_module&nbsp;libexec/mod_log_sql.so
372</DD>
373</DL>in your httpd.conf file. If they are out of order, simply cut-and-paste
374the ``ssl_module'' section so that it is at the top. If you do
375not, you will get this error when you start Apache:
376
377<P>
378
379<DL COMPACT>
380<DT>
381<DD>/usr/local/apache/libexec/mod_log_mysql.so:&nbsp;undefined&nbsp;symbol:&nbsp;ssl_var_lookup
382
383<P>
384/usr/local/apache/bin/apachectl&nbsp;startssl:&nbsp;httpd&nbsp;could&nbsp;not&nbsp;be&nbsp;started
385</DD>
386</DL>(mod_log_sql has a dependency on mod_ssl for SSL symbols. If the
387statements are out of order, mod_log_sql cannot recognize those
388symbols.)
389
390<P>
391Now skip below to section <A HREF="node4.html#sec:Configuration">3</A>, <B>Configuration</B>.
392
393<P>
394</LI>
395</OL>
396
397<P>
398
399<H2><A NAME="SECTION00035000000000000000"></A><A NAME="sec:Static"></A>
400<BR>
4012.5 Installation as a static module compiled into
402httpd
403</H2>
404
405<P>
406
407<OL>
408<LI>Perform all the following steps as root so that you have install privs,
409etc.
410</LI>
411<LI>Unpack the archive into a working directory.
412
413<P>
414
415<DL COMPACT>
416<DT>
417<DD>#&nbsp;tar&nbsp;zxf&nbsp;mod_log_sql.tar.gz&nbsp;-C&nbsp;/usr/local/src&nbsp;
418
419<P>
420#&nbsp;cd&nbsp;/usr/local/src/mod_log_sql
421</DD>
422</DL>
423</LI>
424<LI><A NAME="step:editMF"></A>Edit Makefile and change the values of the variables
425in the first section.
426
427<P>
428
429<OL>
430<LI>These are <B>necessary:</B>
431
432<P>
433<DL>
434<DT><STRONG>APACHEINSTALLED:</STRONG></DT>
435<DD>the location where you installed Apache - usually
436/usr/local/apache, 'locate apxs' can help you find it.
437</DD>
438<DT><STRONG>APACHESOURCE:</STRONG></DT>
439<DD>the location of your Apache <B>sources</B>, find
440using 'locate ABOUT_APACHE'
441</DD>
442<DT><STRONG>APACHEHEADERS:</STRONG></DT>
443<DD>the location of your Apache header files, find using
444'locate httpd.h'
445</DD>
446<DT><STRONG>MYSQLLIBRARIES:</STRONG></DT>
447<DD>the location of your MySQL libraries, find using
448'locate libmysqlclient.so'
449</DD>
450<DT><STRONG>MYSQLHEADERS:</STRONG></DT>
451<DD>the location of your MySQL header files, find using
452'locate mysql.h'
453</DD>
454</DL>
455</LI>
456<LI><B>Optional</B>: if you compiled mod_ssl for Apache and want to
457log SSL data such as 'keysize' and 'cipher type':
458
459<P>
460<DL>
461<DT><STRONG>MODSSLHEADERS:</STRONG></DT>
462<DD>the location of your mod_ssl header files, find
463using 'locate mod_ssl.h'
464</DD>
465<DT><STRONG>DB1HEADERS:</STRONG></DT>
466<DD>the location of your db1 header files, find using 'locate
467ndbm.h'
468</DD>
469</DL>
470</LI>
471</OL>
472You do <B>not</B> need to compile SSL support into mod_log_sql
473in order to simply use it with a secure site. You only need to compile
474SSL support into mod_log_sql <B>if you want to log SSL-specific
475data</B> such as the cipher type.
476
477<P>
478</LI>
479<LI>IMPORTANT: If you are not logging SSL info, comment out MODSSLHDRS
480by putting a # character in front of it:
481
482<P>
483
484<DL COMPACT>
485<DT>
486<DD>#MODSSLHDRS=/usr/include/...
487</DD>
488</DL>
489</LI>
490<LI>Compile the module.
491
492<P>
493
494<DL COMPACT>
495<DT>
496<DD>#&nbsp;make&nbsp;static
497</DD>
498</DL>You should see output similar to the following:
499
500<P>
501
502<DL COMPACT>
503<DT>
504<DD>gcc&nbsp;-fpic&nbsp;-O2&nbsp;-Wall&nbsp;-I/usr/local/Apache/include&nbsp;-I/usr/include/mysql&nbsp;-I/usr/lo...
505</DD>
506</DL>You should see no errors and have a new file called &#34;mod_log_sql.o&#34;
507in your directory.
508
509<P>
510</LI>
511<LI>Install the module.
512
513<P>
514
515<DL COMPACT>
516<DT>
517<DD>#&nbsp;make&nbsp;statinstall
518</DD>
519</DL>
520</LI>
521<LI>Change to your Apache source directory.
522
523<P>
524
525<DL COMPACT>
526<DT>
527<DD>#&nbsp;cd&nbsp;/usr/local/src/apache-1.3.22/src
528</DD>
529</DL>
530</LI>
531<LI>Re-compile your httpd binary as follows.
532
533<P>
534
535<OL>
536<LI><A NAME="step:Linking"></A>Make these changes to Configuration.apaci:
537
538<P>
539
540<UL>
541<LI>Append the following string to the EXTRA_LIBS= line. (&#34;/usr/lib/mysql&#34;
542is from step <A HREF="node3.html#step:editMF">3</A>, and is where your MySQL libraries
543live):
544</LI>
545</UL>
546
547<DL COMPACT>
548<DT>
549<DD>-L/usr/lib/mysql&nbsp;-lmysqlclient&nbsp;-lm&nbsp;-lz
550</DD>
551</DL>
552<UL>
553<LI>Find the mod_log_config.o line, and insert this line immediately
554after it:
555</LI>
556</UL>
557
558<DL COMPACT>
559<DT>
560<DD>AddModule&nbsp;modules/sql/mod_log_sql.o
561</DD>
562</DL>
563</LI>
564<LI># cp Configuration.apaci Configuration
565</LI>
566<LI># ./Configure
567</LI>
568<LI># make
569</LI>
570<LI># strip httpd
571</LI>
572</OL>
573</LI>
574<LI>Test your new apache binary:
575
576<P>
577
578<DL COMPACT>
579<DT>
580<DD>#&nbsp;./httpd&nbsp;-l
581</DD>
582</DL>You should see something like:
583
584<P>
585
586<DL COMPACT>
587<DT>
588<DD>Compiled-in&nbsp;modules:&nbsp;
589
590<P>
591http_core.c
592
593<P>
594mod_log_sql.c&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;-&nbsp;That's&nbsp;the&nbsp;line&nbsp;you're&nbsp;looking&nbsp;for.
595
596<P>
597mod_env.c&nbsp;
598
599<P>
600mod_log_config.c&nbsp;
601
602<P>
603mod_mime.c&nbsp;
604
605<P>
606mod_negotiation.c
607
608<P>
609etc...
610</DD>
611</DL>
612</LI>
613<LI>Install your httpd binary. Copy it over your old httpd binary, wherever
614it lives. You can and should rename your old httpd first so that you
615can easily revert to that working version in case of bugs with the
616new version.
617
618<P>
619
620<DL COMPACT>
621<DT>
622<DD>#&nbsp;/etc/rc.d/init.d/httpd&nbsp;stop&nbsp;
623
624<P>
625#&nbsp;mv&nbsp;/usr/local/Apache/bin/httpd&nbsp;~/httpd-save&nbsp;
626
627<P>
628#&nbsp;cp&nbsp;-f&nbsp;./httpd&nbsp;/usr/local/Apache/bin/
629</DD>
630</DL>
631</LI>
632</OL>
633
634<P>
635<HR>
636<!--Navigation Panel-->
637<A NAME="tex2html152"
638 HREF="node4.html">
639<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
640<A NAME="tex2html148"
641 HREF="documentation.html">
642<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
643<A NAME="tex2html142"
644 HREF="node2.html">
645<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
646<A NAME="tex2html150"
647 HREF="node1.html">
648<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
649<BR>
650<B> Next:</B> <A NAME="tex2html153"
651 HREF="node4.html">3 Configuration</A>
652<B> Up:</B> <A NAME="tex2html149"
653 HREF="documentation.html">Installing and Running mod_log_sql</A>
654<B> Previous:</B> <A NAME="tex2html143"
655 HREF="node2.html">1 Introduction</A>
656 &nbsp; <B> <A NAME="tex2html151"
657 HREF="node1.html">Contents</A></B>
658<!--End of Navigation Panel-->
659<ADDRESS>
660Chris Powell
6612002-12-18
662</ADDRESS>
663</BODY>
664</HTML>
diff --git a/docs/node4.html b/docs/node4.html
new file mode 100644
index 0000000..287333c
--- /dev/null
+++ b/docs/node4.html
@@ -0,0 +1,2014 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2
3<!--Converted with LaTeX2HTML 2002-1 (1.68)
4original version by: Nikos Drakos, CBLU, University of Leeds
5* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6* with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
8<HTML>
9<HEAD>
10<TITLE>3 Configuration</TITLE>
11<META NAME="description" CONTENT="3 Configuration">
12<META NAME="keywords" CONTENT="documentation">
13<META NAME="resource-type" CONTENT="document">
14<META NAME="distribution" CONTENT="global">
15
16<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17<META NAME="Generator" CONTENT="LaTeX2HTML v2002-1">
18<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
19
20<LINK REL="STYLESHEET" HREF="documentation.css">
21
22<LINK REL="next" HREF="node5.html">
23<LINK REL="previous" HREF="node3.html">
24<LINK REL="up" HREF="documentation.html">
25<LINK REL="next" HREF="node5.html">
26</HEAD>
27
28<BODY >
29<!--Navigation Panel-->
30<A NAME="tex2html172"
31 HREF="node5.html">
32<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
33<A NAME="tex2html168"
34 HREF="documentation.html">
35<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
36<A NAME="tex2html162"
37 HREF="node3.html">
38<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
39<A NAME="tex2html170"
40 HREF="node1.html">
41<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
42<BR>
43<B> Next:</B> <A NAME="tex2html173"
44 HREF="node5.html">4 FAQ</A>
45<B> Up:</B> <A NAME="tex2html169"
46 HREF="documentation.html">Installing and Running mod_log_sql</A>
47<B> Previous:</B> <A NAME="tex2html163"
48 HREF="node3.html">2 Installation</A>
49 &nbsp; <B> <A NAME="tex2html171"
50 HREF="node1.html">Contents</A></B>
51<BR>
52<BR>
53<!--End of Navigation Panel-->
54<!--Table of Child-Links-->
55<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
56
57<UL>
58<LI><A NAME="tex2html174"
59 HREF="node4.html#SECTION00041000000000000000">3.1 Preparing MySQL for logging</A>
60<LI><A NAME="tex2html175"
61 HREF="node4.html#SECTION00042000000000000000">3.2 A very basic logging setup in Apache</A>
62<LI><A NAME="tex2html176"
63 HREF="node4.html#SECTION00043000000000000000">3.3 Testing the basic setup</A>
64<LI><A NAME="tex2html177"
65 HREF="node4.html#SECTION00044000000000000000">3.4 How to tune logging with run-time directives</A>
66<UL>
67<LI><A NAME="tex2html178"
68 HREF="node4.html#SECTION00044100000000000000">3.4.1 Instructing the module what to log</A>
69<LI><A NAME="tex2html179"
70 HREF="node4.html#SECTION00044200000000000000">3.4.2 Instructing the module what NOT to log using filtering
71directives</A>
72</UL>
73<BR>
74<LI><A NAME="tex2html180"
75 HREF="node4.html#SECTION00045000000000000000">3.5 Advanced logging scenarios</A>
76<UL>
77<LI><A NAME="tex2html181"
78 HREF="node4.html#SECTION00045100000000000000">3.5.1 Using the module in an ISP environment</A>
79<LI><A NAME="tex2html182"
80 HREF="node4.html#SECTION00045200000000000000">3.5.2 Logging many-to-one data in separate tables</A>
81<LI><A NAME="tex2html183"
82 HREF="node4.html#SECTION00045300000000000000">3.5.3 Using the same database for production and test</A>
83<LI><A NAME="tex2html184"
84 HREF="node4.html#SECTION00045400000000000000">3.5.4 Optimizing for a busy database</A>
85</UL>
86<BR>
87<LI><A NAME="tex2html185"
88 HREF="node4.html#SECTION00046000000000000000">3.6 Configuration directive reference</A>
89<UL>
90<LI><A NAME="tex2html186"
91 HREF="node4.html#SECTION00046100000000000000">3.6.1 LogSQLCookieLogTable</A>
92<LI><A NAME="tex2html187"
93 HREF="node4.html#SECTION00046200000000000000">3.6.2 LogSQLCreateTables</A>
94<LI><A NAME="tex2html188"
95 HREF="node4.html#SECTION00046300000000000000">3.6.3 LogSQLDatabase </A>
96<LI><A NAME="tex2html189"
97 HREF="node4.html#SECTION00046400000000000000">3.6.4 LogSQLForcePreserve</A>
98<LI><A NAME="tex2html190"
99 HREF="node4.html#SECTION00046500000000000000">3.6.5 LogSQLHeadersInLogTable</A>
100<LI><A NAME="tex2html191"
101 HREF="node4.html#SECTION00046600000000000000">3.6.6 LogSQLHeadersOutLogTable</A>
102<LI><A NAME="tex2html192"
103 HREF="node4.html#SECTION00046700000000000000">3.6.7 LogSQLLoginInfo </A>
104<LI><A NAME="tex2html193"
105 HREF="node4.html#SECTION00046800000000000000">3.6.8 LogSQLMachineID</A>
106<LI><A NAME="tex2html194"
107 HREF="node4.html#SECTION00046900000000000000">3.6.9 LogSQLMassVirtualHosting</A>
108<LI><A NAME="tex2html195"
109 HREF="node4.html#SECTION000461000000000000000">3.6.10 LogSQLNotesLogTable</A>
110<LI><A NAME="tex2html196"
111 HREF="node4.html#SECTION000461100000000000000">3.6.11 LogSQLPreserveFile</A>
112<LI><A NAME="tex2html197"
113 HREF="node4.html#SECTION000461200000000000000">3.6.12 LogSQLRemhostIgnore</A>
114<LI><A NAME="tex2html198"
115 HREF="node4.html#SECTION000461300000000000000">3.6.13 LogSQLRequestAccept</A>
116<LI><A NAME="tex2html199"
117 HREF="node4.html#SECTION000461400000000000000">3.6.14 LogSQLRequestIgnore</A>
118<LI><A NAME="tex2html200"
119 HREF="node4.html#SECTION000461500000000000000">3.6.15 LogSQLSocketFile </A>
120<LI><A NAME="tex2html201"
121 HREF="node4.html#SECTION000461600000000000000">3.6.16 LogSQLTCPPort</A>
122<LI><A NAME="tex2html202"
123 HREF="node4.html#SECTION000461700000000000000">3.6.17 LogSQLTransferLogFormat </A>
124<LI><A NAME="tex2html203"
125 HREF="node4.html#SECTION000461800000000000000">3.6.18 LogSQLTransferLogTable</A>
126<LI><A NAME="tex2html204"
127 HREF="node4.html#SECTION000461900000000000000">3.6.19 LogSQLWhichCookie</A>
128<LI><A NAME="tex2html205"
129 HREF="node4.html#SECTION000462000000000000000">3.6.20 LogSQLWhichCookies</A>
130<LI><A NAME="tex2html206"
131 HREF="node4.html#SECTION000462100000000000000">3.6.21 LogSQLWhichHeadersIn</A>
132<LI><A NAME="tex2html207"
133 HREF="node4.html#SECTION000462200000000000000">3.6.22 LogSQLWhichHeadersOut</A>
134<LI><A NAME="tex2html208"
135 HREF="node4.html#SECTION000462300000000000000">3.6.23 LogSQLWhichNotes</A>
136</UL></UL>
137<!--End of Table of Child-Links-->
138<HR>
139
140<H1><A NAME="SECTION00040000000000000000"></A><A NAME="sec:Configuration"></A>
141<BR>
1423 Configuration
143</H1>
144
145<P>
146
147<H2><A NAME="SECTION00041000000000000000"></A><A NAME="sub:PrepDb"></A>
148<BR>
1493.1 Preparing MySQL for logging
150</H2>
151
152<P>
153You have to prepare the database to receive data from mod_log_sql,
154and set up run-time directives in httpd.conf to control how and what
155mod_log_sql logs.
156
157<P>
158This section will discuss how to get started with a basic config.
159Full documentation of all available run-time directives is available
160in section <A HREF="node4.html#sec:ConfRef">3.6</A>.
161
162<P>
163
164<OL>
165<LI>mod_log_sql can make its own tables on-the-fly, or you can pre-make
166the tables by hand. The advantage of letting the module make the tables
167is ease-of-use, but for raw performance you will want to pre-make
168the tables in order to save some overhead. In this basic setup we'll
169just let the module create tables for us.
170</LI>
171<LI>We still need to have a logging database created and ready, so run
172the MySQL command line client and create a database:
173
174<P>
175
176<DL COMPACT>
177<DT>
178<DD>#&nbsp;mysql&nbsp;-uadmin&nbsp;-pmypassword&nbsp;
179
180<P>
181Enter&nbsp;password:
182
183<P>
184mysql&gt;&nbsp;create&nbsp;database&nbsp;apachelogs;
185</DD>
186</DL>
187</LI>
188<LI><A NAME="part:CrTbl"></A>If you want to hand-create the tables, run the
189enclosed 'create-tables' SQL script as follows:
190
191<P>
192
193<DL COMPACT>
194<DT>
195<DD>mysql&gt;&nbsp;source&nbsp;create_tables.sql
196</DD>
197</DL>
198</LI>
199<LI>Create a specific MySQL userid that httpd will use to authenticate
200and enter data. This userid need not be an actual Unix user. It is
201a userid internal to MySQL with specific privileges. In the following
202example command, &#34;apachelogs&#34; is the database, &#34;loguser&#34;
203is the userid to create, &#34;my.apachemachine.com&#34;
204is the name of the Apache machine, and &#34;l0gger&#34;
205is the password to assign. Choose values that are different from these
206examples.
207
208<P>
209
210<DL COMPACT>
211<DT>
212<DD>mysql&gt;&nbsp;grant&nbsp;insert,create&nbsp;on&nbsp;apachelogs.*&nbsp;to&nbsp;loguser@my.apachemachine.com
213
214<P>
215identified&nbsp;by&nbsp;'l0gger';
216</DD>
217</DL>
218</LI>
219<LI>You may be especially security-paranoid and want &#34;loguser&#34;
220to <I>not</I> have &#34;create&#34; capability within the
221&#34;apachelogs&#34; database. You can disable that privilege,
222but the cost is that you will not be able to use the module's on-the-fly
223table creation feature. If that cost is acceptable, hand-create the
224tables as described in step <A HREF="node4.html#part:CrTbl">3</A> and use the following
225GRANT statement instead of the one above:
226
227<P>
228
229<DL COMPACT>
230<DT>
231<DD>mysql&gt;&nbsp;grant&nbsp;insert&nbsp;on&nbsp;apachelogs.*&nbsp;to&nbsp;loguser@my.apachemachine.com
232
233<P>
234identified&nbsp;by&nbsp;'l0gger';
235</DD>
236</DL>
237</LI>
238<LI><A NAME="step:EnaLog"></A>Enable full logging of your MySQL daemon (at least
239temporarily for debugging purposes) if you don't do this already.
240Edit /etc/my.cnf and add the following line to your [mysqld] section:
241
242<P>
243
244<DL COMPACT>
245<DT>
246<DD>log=/var/log/mysql-messages
247</DD>
248</DL>Then restart MySQL.
249
250<P>
251
252<DL COMPACT>
253<DT>
254<DD>#&nbsp;/etc/rc.d/init.d/mysql&nbsp;restart
255</DD>
256</DL>
257</LI>
258</OL>
259
260<P>
261
262<H2><A NAME="SECTION00042000000000000000">
2633.2 A very basic logging setup in Apache</A>
264</H2>
265
266<P>
267
268<OL>
269<LI>Tell the module what database to use and the appropriate authentication
270information.
271
272<P>
273So, edit httpd.conf and insert the following lines somewhere after
274any LoadModule / AddModule statements. <I>Make sure these statements
275are ``global,'' i.e. not inside any VirtualHost stanza</I>. You will
276also note that you are embedding a password in the file. Therefore
277you are advised to ``chmod 660 httpd.conf'' to prevent unauthorized
278regular users from viewing your database user and password.
279
280<P>
281<B>Example</B>: Use the MySQL database called &#34;apachelogs&#34;
282running on &#34;dbmachine.foo.com&#34;. Use username &#34;loguser&#34;
283and password &#34;l0gg3r&#34; to authenticate to the database.
284Permit the module create tables for us.
285
286<P>
287
288<DL COMPACT>
289<DT>
290<DD>LogSQLLoginInfo&nbsp;dbmachine.foo.com&nbsp;loguser&nbsp;l0gg3r&nbsp;
291
292<P>
293LogSQLDatabase&nbsp;apachelogs
294
295<P>
296LogSQLCreateTables&nbsp;on
297</DD>
298</DL>If your database resides on localhost instead of another host, specify
299the MySQL server's socket file as follows:
300
301<P>
302
303<DL COMPACT>
304<DT>
305<DD>LogSQLSocketFile&nbsp;/your/path/to/mysql.sock
306</DD>
307</DL>If your database is listening on a port other than 3306, specify the
308correct TCP port as follows:
309
310<P>
311
312<DL COMPACT>
313<DT>
314<DD>LogSQLTCPPort&nbsp;1234
315</DD>
316</DL>
317</LI>
318<LI>The actual logging is set up on a virtual-host-by-host basis. So,
319skip down to the virtual host you want to set up. Instruct this virtual
320host to log entries to the table ``access_log'' by inserting
321a L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>T<SMALL>ABLE</SMALL> directive. (The L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>T<SMALL>ABLE</SMALL>
322directive is the minimum required to log - other directives that
323you'll learn about later simply tune the module's behavior.)
324
325<P>
326
327<DL COMPACT>
328<DT>
329<DD>&lt;VirtualHost&nbsp;1.2.3.4&gt;
330
331<P>
332&nbsp;[snip]
333
334<P>
335&nbsp;LogSQLTransferLogTable&nbsp;access_log
336
337<P>
338&nbsp;[snip]
339
340<P>
341&lt;/VirtualHost&gt;
342</DD>
343</DL>
344</LI>
345<LI>Restart apache.
346
347<P>
348
349<DL COMPACT>
350<DT>
351<DD>#&nbsp;/etc/rc.d/init.d/httpd&nbsp;stop
352
353<P>
354#&nbsp;/etc/rc.d/init.d/httpd&nbsp;start
355</DD>
356</DL>
357</LI>
358</OL>
359
360<P>
361
362<H2><A NAME="SECTION00043000000000000000">
3633.3 Testing the basic setup</A>
364</H2>
365
366<P>
367
368<OL>
369<LI>Visit your web site in a browser to trigger some hits, then confirm
370that the entries are being successfully logged:
371
372<P>
373
374<DL COMPACT>
375<DT>
376<DD>#&nbsp;mysql&nbsp;-hdbmachine.foo.com&nbsp;-umysqladmin&nbsp;-p&nbsp;-e&nbsp;&#34;select&nbsp;*&nbsp;from&nbsp;access_log&#34;&nbsp;apachelogs&nbsp;
377
378<P>
379Enter&nbsp;password:
380</DD>
381</DL>Several lines of output should follow, corresponding to your hits
382on the site. You now have basic functionality. Don't disable your
383regular Apache logs until you feel comfortable that the database is
384behaving as you'd like and that things are going well. If you do not
385see any entries in the access_log, please consult section <A HREF="node5.html#faq:NothingLogged">4.2.2</A>
386of the FAQ on how to debug and fix the situation.
387
388<P>
389</LI>
390<LI>You can now activate the advanced features of mod_log_sql, which
391are described in the next section.
392</LI>
393</OL>
394
395<P>
396
397<H2><A NAME="SECTION00044000000000000000">
3983.4 How to tune logging with run-time directives</A>
399</H2>
400
401<P>
402
403<H3><A NAME="SECTION00044100000000000000">
4043.4.1 Instructing the module what to log</A>
405</H3>
406
407<P>
408The most basic directive for the module is L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL>,
409which tells the module which information to send to the database;
410logging to the database will not take place without it. Place a L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL>
411directive in the VirtualHost stanza of each virtual host that you
412want to activate.
413
414<P>
415After L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL> you supply a string of characters
416that tell the module what information to log. In the configuration
417directive reference (section <A HREF="node4.html#sub:Frmat">3.6.17</A>) there is a table which
418clearly defines all the possible things to log. Let's say you want
419to log only the ``request time,'' the ``remote host,'' and
420the ``request''; you'd use:
421
422<P>
423
424<DL COMPACT>
425<DT>
426<DD>LogSQLTransferLogFormat&nbsp;hUS
427</DD>
428</DL>But a more appropriate string to use is
429
430<P>
431
432<DL COMPACT>
433<DT>
434<DD>LogSQLTransferLogFormat&nbsp;AbHhmRSsTUuv
435</DD>
436</DL>which logs all the information required to be compatible with the
437Combined Log Format (CLF).
438
439<P>
440If you don't choose to log everything that is available, that's fine.
441Fields in the unused columns in your table will simply contain NULL.
442
443<P>
444Some of the L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL> characters require a
445little extra configuration:
446
447<P>
448
449<UL>
450<LI>If you specify 'c' to indicate that you want to log the cookie value,
451you must also tell the module which cookie you mean by using L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>C<SMALL>OOKIE</SMALL>
452- after all, there could be many cookies associated with a given
453request. Fail to specify L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>C<SMALL>OOKIE</SMALL>, and no cookie
454information at all will be logged.
455</LI>
456<LI>If you specify 'M' to indicate that you want to log the machine ID,
457you must also tell the module this machine's identity using the L<SMALL>OG</SMALL>SQLM<SMALL>ACHINE</SMALL>ID
458directive. Fail to specify L<SMALL>OG</SMALL>SQLM<SMALL>ACHINE</SMALL>ID, and a simple
459'-' character will be logged in the machine_id column.
460</LI>
461</UL>
462
463<P>
464
465<H3><A NAME="SECTION00044200000000000000"></A><A NAME="sub:Ignore"></A>
466<BR>
4673.4.2 Instructing the module what NOT to log using filtering
468directives
469</H3>
470
471<P>
472One ``accept'' and two ``ignore'' directives allow you to
473fine-tune what the module should not log. These are very handy for
474keeping your database as uncluttered as possible and keeping your
475statistics free of unneeded numbers. Think of each one as a gatekeeper.
476
477<P>
478<I>It is important to remember that each of these three directives
479is purely optional. mod_log_sql's default is to log everything. </I>
480
481<P>
482When a request comes in, the contents of L<SMALL>OG</SMALL>SQLR<SMALL>EQUEST</SMALL>A<SMALL>CCEPT</SMALL>
483are evaluated first. This optional, ``blanket'' directive lets
484you specify that only certain things are to be accepted for logging,
485and everything else discarded. Because it is evaluated before L<SMALL>OG</SMALL>SQLR<SMALL>EQUEST</SMALL>I<SMALL>GNORE</SMALL>
486and L<SMALL>OG</SMALL>SQLR<SMALL>EMHOST</SMALL>I<SMALL>GNORE</SMALL> it can halt logging before those
487two filtering directives ``get their chance.''
488
489<P>
490Once a request makes it past L<SMALL>OG</SMALL>SQLR<SMALL>EQUEST</SMALL>A<SMALL>CCEPT</SMALL>, it still
491can be excluded based on L<SMALL>OG</SMALL>SQLR<SMALL>EMHOST</SMALL>I<SMALL>GNORE</SMALL> and L<SMALL>OG</SMALL>SQLR<SMALL>EQUEST</SMALL>I<SMALL>GNORE</SMALL>.
492A good way to use L<SMALL>OG</SMALL>SQLR<SMALL>EMHOST</SMALL>I<SMALL>GNORE</SMALL> is to prevent the module
493from logging the traffic that your internal hosts generate. L<SMALL>OG</SMALL>SQLR<SMALL>EQUEST</SMALL>I<SMALL>GNORE</SMALL>
494is great for preventing things like requests for ``favicon.ico''
495from cluttering up your database, as well as excluding the various
496requests that worms make, etc.
497
498<P>
499You can specify a series of strings after each directive. Do not use
500any type of globbing or regular-expression syntax - each string is
501considered a match <I>if it is a substring of the larger request
502or remote-host; the comarison is case-sensitive.</I> This means that
503``L<SMALL>OG</SMALL>SQLR<SMALL>EMHOST</SMALL>I<SMALL>GNORE</SMALL> micro'' will ignore requests from
504``microsoft.com,'' ``microworld.net,'' ``mymicroscope.org,''
505etc. ``L<SMALL>OG</SMALL>SQLR<SMALL>EQUEST</SMALL>I<SMALL>GNORE</SMALL> gif'' will instruct the module
506to ignore requests for ``leftbar.gif,'' ``bluedot.gif'' and
507even ``giftwrap.jpg'' - but ``RED.GIF'' and ``Tree.Gif''
508would still get logged because of case sensitivity.
509
510<P>
511A summary of the decision flow:
512
513<P>
514
515<OL>
516<LI>If L<SMALL>OG</SMALL>SQLR<SMALL>EQUEST</SMALL>A<SMALL>CCEPT</SMALL> exists and a request does not match
517anything in that list, it is discarded.
518</LI>
519<LI>If a request matches anything in the L<SMALL>OG</SMALL>SQLR<SMALL>EQUEST</SMALL>I<SMALL>GNORE</SMALL>
520list, it is discarded.
521</LI>
522<LI>If a reqiest matches anything in the L<SMALL>OG</SMALL>SQLR<SMALL>EMHOST</SMALL>I<SMALL>GNORE</SMALL>
523list, it is discarded.
524</LI>
525<LI>Otherwise the request is logged.
526</LI>
527</OL>
528This means that you can have a series of directives similar to the
529following:
530
531<P>
532
533<DL COMPACT>
534<DT>
535<DD>LogSQLRequestAccept&nbsp;*.html&nbsp;*.gif&nbsp;*.jpg
536
537<P>
538LogSQLRequestIgnore&nbsp;statistics.html&nbsp;bluedot.jpg
539</DD>
540</DL>So the first line instructs the module to <B>only</B> log files
541with html, gif and jpg suffixes; requests for ``formail.cgi''
542and ``shopping-cart.pl'' will never be considered for logging.
543(``LeftArrow.JPG'' will also never be considered for logging -
544remember, the comparison is <B>case sensitive</B>.) The second line
545prunes the list further - you never want to log requests for those
546two objects.
547
548<P>
549Tip: if you want to match all the hosts in your domain such as ``host1.corp.foo.com''
550and ``server.dmz.foo.com'', simply specify:
551
552<P>
553
554<DL COMPACT>
555<DT>
556<DD>LogSQLRemhostIgnore&nbsp;foo.com
557</DD>
558</DL>Tip: a great way to catch the vast majority of worm-attack requests
559and prevent them from being logged is to specify:
560
561<P>
562
563<DL COMPACT>
564<DT>
565<DD>LogSQLRequestIgnore&nbsp;root.exe&nbsp;cmd.exe&nbsp;default.ida
566</DD>
567</DL>Tip: to prevent the logging of requests for common graphic types,
568make sure to put a '.' before the suffix to avoid matches that you
569didn't intend:
570
571<P>
572
573<DL COMPACT>
574<DT>
575<DD>LogSQLRequestIgnore&nbsp;.gif&nbsp;.jpg
576</DD>
577</DL>
578<P>
579
580<H2><A NAME="SECTION00045000000000000000">
5813.5 Advanced logging scenarios</A>
582</H2>
583
584<P>
585
586<H3><A NAME="SECTION00045100000000000000">
5873.5.1 Using the module in an ISP environment</A>
588</H3>
589
590<P>
591mod_log_sql has three basic tiers of operation:
592
593<P>
594
595<OL>
596<LI>The administrator creates all necessary tables by hand and configures
597each Apache VirtualHost by hand. (L<SMALL>OG</SMALL>SQLC<SMALL>REATE</SMALL>T<SMALL>ABLES </SMALL>O<SMALL>FF</SMALL>)
598</LI>
599<LI>The module is permitted to create necessary tables on-the-fly, but
600the administrator configures each Apache VirtualHost by hand. (L<SMALL>OG</SMALL>SQLC<SMALL>REATE</SMALL>T<SMALL>ABLES
601</SMALL>O<SMALL>N</SMALL>)
602</LI>
603<LI>The module is permitted to create all necessary tables and to make
604intelligent, on-the-fly configuration of each VirtualHost. (L<SMALL>OG</SMALL>SQLM<SMALL>ASS</SMALL>V<SMALL>IRTUAL</SMALL>H<SMALL>OSTING
605</SMALL>O<SMALL>N</SMALL>)
606</LI>
607</OL>
608Many users are happy to use the module in its most minimal form: they
609hand-create any necessary tables (using ``create_tables.sql''),
610and they configure each VirtualHost by hand to suit their needs. However,
611some administrators need extra features due to a large and growing
612number of VirtualHosts. The L<SMALL>OG</SMALL>SQLM<SMALL>ASS</SMALL>V<SMALL>IRTUAL</SMALL>H<SMALL>OSTING</SMALL> directive
613activates module capabilities that make it far easier to manage an
614ISP environment, or any situation characterized by a large and varying
615number of virtual servers:
616
617<P>
618
619<UL>
620<LI>the on-the-fly table creation feature is activated automatically
621</LI>
622<LI>the transfer log table name is dynamically set from the virtual host's
623name (example: a virtual host ``www.grubbybaby.com'' gets logged
624to table ``access_www_grubbybaby_com'')
625</LI>
626</UL>
627There are numerous benefits. The admin will not need to create new
628tables for every new VirtualHost. (Although the admin will still need
629to drop the tables of virtual hosts that are removed.) The admin will
630not need to set L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>T<SMALL>ABLE</SMALL> for each virtual host
631- it will be configured automatically based on the host's name. Because
632each virtual host will log to its own segregated table, data about
633one virtual server will segregate from others; an admin can grant
634users access to the tables they need, and they will be unable to view
635data about another user's virtual host.
636
637<P>
638In an ISP scenario the admin is likely to have a cluster of many front-end
639webservers logging to a back-end database. mod_log_sql has a feature
640that permits analysis of how well the web servers are loadbalancing:
641the L<SMALL>OG</SMALL>SQLM<SMALL>ACHINE</SMALL>ID directive. The administrator uses this
642directive to assign a unique identifier to each machine in the web
643cluster, e.g. ``L<SMALL>OG</SMALL>SQLM<SMALL>ACHINE</SMALL>ID web01,'' ``L<SMALL>OG</SMALL>SQLM<SMALL>ACHINE</SMALL>ID
644web02,'' etc. Used in conjunction with the 'M' character in L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL>,
645each entry in the SQL log will include the machine ID of the machine
646that created the entry. This permits the administrator to count the
647entries made by each particular machine and thereby analyze the front-end
648loadbalancing algorithm.
649
650<P>
651
652<H3><A NAME="SECTION00045200000000000000"></A><A NAME="secMulTable"></A>
653<BR>
6543.5.2 Logging many-to-one data in separate tables
655</H3>
656
657<P>
658A given HTTP request can have a one-to-many relationship with certain
659kinds of data. For example, a single HTTP request can have 4 cookies,
6603 headers and 5 ``mod_gzip'' notes associated with it. mod_log_sql
661is capable of logging these relationships due to the elegance of SQL
662relational data.
663
664<P>
665You already have a single table containing access requests. One of
666the columns in that table is 'id' which is intended to contain the
667unique request ID supplied by the standard Apache module mod_unique_id
668- all you need to do is compile in that module and employ the L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL>
669character 'I'. Thereafter, each request gets a unique ID that can
670be thought of as a primary key within the database, useful for joining
671multiple tables. So let's envision several new tables: a notes table,
672a cookies table, and a table for inbound and outbound headers.
673
674<P>
675<BR><P></P>
676<DIV ALIGN="CENTER">
677
678<P>
679
680<P>
681<DIV ALIGN="CENTER">
682<A NAME="958"></A>
683<TABLE CELLPADDING=3 BORDER="1">
684<CAPTION><STRONG>Table 1:</STRONG>
685access_log</CAPTION>
686<TR><TD ALIGN="LEFT">id</TD>
687<TD ALIGN="LEFT">remote_host</TD>
688<TD ALIGN="LEFT">request_uri</TD>
689<TD ALIGN="LEFT">time_stamp</TD>
690<TD ALIGN="LEFT">status</TD>
691<TD ALIGN="LEFT">bytes_sent</TD>
692</TR>
693<TR><TD ALIGN="LEFT">PPIDskBRH30AAGPtAsg</TD>
694<TD ALIGN="LEFT">zerberus.aiacs.net</TD>
695<TD ALIGN="LEFT">/mod_log_sql/index.html</TD>
696<TD ALIGN="LEFT">1022493617</TD>
697<TD ALIGN="LEFT">200</TD>
698<TD ALIGN="LEFT">2215</TD>
699</TR>
700</TABLE>
701</DIV>
702</DIV>
703<BR>
704<BR><P></P>
705<DIV ALIGN="CENTER">
706
707<P>
708
709<P>
710<DIV ALIGN="CENTER">
711<A NAME="959"></A>
712<TABLE CELLPADDING=3 BORDER="1">
713<CAPTION><STRONG>Table 2:</STRONG>
714notes_log</CAPTION>
715<TR><TD ALIGN="LEFT">id</TD>
716<TD ALIGN="LEFT">item</TD>
717<TD ALIGN="LEFT">val</TD>
718</TR>
719<TR><TD ALIGN="LEFT">PPIDskBRH30AAGPtAsg</TD>
720<TD ALIGN="LEFT">mod_gzip_result</TD>
721<TD ALIGN="LEFT">OK</TD>
722</TR>
723<TR><TD ALIGN="LEFT">PPIDskBRH30AAGPtAsg</TD>
724<TD ALIGN="LEFT">mod_gzip_compression_ratio</TD>
725<TD ALIGN="LEFT">69</TD>
726</TR>
727</TABLE>
728</DIV>
729</DIV>
730<BR>
731
732<P>
733<BR><P></P>
734<DIV ALIGN="CENTER">
735
736<P>
737
738<P>
739<DIV ALIGN="CENTER">
740<A NAME="960"></A>
741<TABLE CELLPADDING=3 BORDER="1">
742<CAPTION><STRONG>Table 3:</STRONG>
743headers_log</CAPTION>
744<TR><TD ALIGN="LEFT">id</TD>
745<TD ALIGN="LEFT">item</TD>
746<TD ALIGN="LEFT">val</TD>
747</TR>
748<TR><TD ALIGN="LEFT">PPIDskBRH30AAGPtAsg</TD>
749<TD ALIGN="LEFT">Content-Type</TD>
750<TD ALIGN="LEFT">text/html</TD>
751</TR>
752<TR><TD ALIGN="LEFT">PPIDskBRH30AAGPtAsg</TD>
753<TD ALIGN="LEFT">Accept-Encoding</TD>
754<TD ALIGN="LEFT">gzip, deflate</TD>
755</TR>
756<TR><TD ALIGN="LEFT">PPIDskBRH30AAGPtAsg</TD>
757<TD ALIGN="LEFT">Expires</TD>
758<TD ALIGN="LEFT">Tue, 28 May 2002 10:00:18 GMT</TD>
759</TR>
760<TR><TD ALIGN="LEFT">PPIDskBRH30AAGPtAsg</TD>
761<TD ALIGN="LEFT">Cache-Control</TD>
762<TD ALIGN="LEFT">max-age=86400</TD>
763</TR>
764</TABLE>
765</DIV>
766</DIV>
767<BR>
768
769<P>
770We have a certain request, and its unique ID is ``PPIDskBRH30AAGPtAsg''.
771Within each separate table will be multiple entries with that request
772ID: several cookie entries, several header entries, etc. As you can
773see in tables <A HREF="#tblAcc">1</A>, <A HREF="#tblNotes">2</A> and <A HREF="#tblHdr">3</A>, you
774have a one-to-many relationship for request PPIDskBRH30AAGPtAsg: that
775one access has two associated notes and four associated headers. You
776can extract this data easily using the power of SQL's ``select''
777statement and table joins. To see the notes associated with a particular
778request:
779
780<P>
781
782<DL COMPACT>
783<DT>
784<DD>select&nbsp;a.remote_host,&nbsp;a.request_uri,&nbsp;n.item,&nbsp;n.val&nbsp;from&nbsp;access_log&nbsp;a,&nbsp;notes_log&nbsp;n
785
786<P>
787where&nbsp;a.id=n.id&nbsp;and&nbsp;a.id='PPIDskBRH30AAGPtAsg';
788
789<P>
790</DD>
791</DL>
792<DIV ALIGN="CENTER">
793<TABLE CELLPADDING=3 BORDER="1">
794<TR><TD ALIGN="LEFT">remote_host</TD>
795<TD ALIGN="LEFT">request_uri</TD>
796<TD ALIGN="LEFT">item</TD>
797<TD ALIGN="LEFT">val</TD>
798</TR>
799<TR><TD ALIGN="LEFT">zerberus.aiacs.net</TD>
800<TD ALIGN="LEFT">/mod_log_sql/index.html</TD>
801<TD ALIGN="LEFT">mod_gzip_result</TD>
802<TD ALIGN="LEFT">OK</TD>
803</TR>
804<TR><TD ALIGN="LEFT">zerberus.aiacs.net</TD>
805<TD ALIGN="LEFT">/mod_log_sql/index.html</TD>
806<TD ALIGN="LEFT">mod_gzip_compression_ratio</TD>
807<TD ALIGN="LEFT">69</TD>
808</TR>
809</TABLE>
810</DIV>
811
812<P>
813
814<DL COMPACT>
815<DT>
816<DD><P>
817</DD>
818</DL>Naturally you can craft similar statements for the outboud headers,
819inbound headers and cookies, all of which can live in separate tables.
820Your statements are limited in power only by your skill with SQL.
821
822<P>
823In order to use this capability of mod_log_sql, you must do several
824things:
825
826<P>
827
828<UL>
829<LI>Compile mod_unique_id into Apache (statically or as a DSO). mod_log_sql
830employs the unique request ID that mod_unique_id provides in order
831to key between the separate tables. You can still log the data without
832mod_unqiue_id, but it will be completely uncorrelated and you will
833have no way to discern any meaning.
834</LI>
835<LI>Create the appropriate tables. This will be done for you if you permit
836mod_log_sql to create its own tables using L<SMALL>OG</SMALL>SQLC<SMALL>REATE</SMALL>T<SMALL>ABLES
837</SMALL>O<SMALL>N</SMALL>, or if you use the enclosed ``create_tables.sql'' script.
838</LI>
839<LI>Create a SQL index on the ``id'' column. Without this index, table
840joins will be deathly slow. I recommend you consult the MySQL documentation
841on the proper way to create a column index if you are not familiar
842with this operation.
843</LI>
844<LI>Within each appropriate VirtualHost stanza, use the L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>*
845and L<SMALL>OG</SMALL>SQL*L<SMALL>OG</SMALL>T<SMALL>ABLE</SMALL> directives to tell the module what
846and where to log the data. In the following example, I have overridden
847the name for the notes table whereas I have left the other table names
848at their defaults. I have then specified the cookies, headers and
849notes that interest me. (And as you can see, these directives do not
850require me to add any characters to L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>T<SMALL>ABLE.)</SMALL>
851</LI>
852</UL>
853
854<DL COMPACT>
855<DT>
856<DD>&lt;VirtualHost&nbsp;216.231.36.128&gt;
857
858<P>
859&nbsp;&nbsp;(snip)
860
861<P>
862&nbsp;&nbsp;LogSQLNotesLogTable&nbsp;notestable
863
864<P>
865&nbsp;&nbsp;LogSQLWhichCookies&nbsp;bluecookie&nbsp;redcookie&nbsp;greencookie&nbsp;
866
867<P>
868&nbsp;&nbsp;LogSQLWhichNotes&nbsp;mod_gzip_result&nbsp;mod_gzip_compression_ratio
869
870<P>
871&nbsp;&nbsp;LogSQLWhichHeadersOut&nbsp;Expires&nbsp;Content-Type&nbsp;Cache-Control&nbsp;
872
873<P>
874&nbsp;&nbsp;LogSQLWhichHeadersIn&nbsp;UserAgent&nbsp;Accept-Encoding&nbsp;Host
875
876<P>
877&nbsp;&nbsp;(snip)
878
879<P>
880&lt;/VirtualHost&gt;
881</DD>
882</DL>
883<P>
884
885<H3><A NAME="SECTION00045300000000000000">
8863.5.3 Using the same database for production and test</A>
887</H3>
888
889<P>
890Although suboptimal, it is not uncommon to use the same backend database
891for the ``production'' webservers as well as the ``test''
892webservers (budgetary constraints, rackspace limits, etc.). Furthermore,
893an administrator in this situation may be unable to use L<SMALL>OG</SMALL>SQLR<SMALL>EMHOST</SMALL>I<SMALL>GNORE</SMALL>
894to exclude requests from the test servers - perhaps the generated
895entries are genuinely useful for analytical or QA purposes, but their
896value after analysis is minimal.
897
898<P>
899It is wasteful and potentially confusing to permit this internal test
900data to clutter the database, and a solution to the problem is the
901proper use of the L<SMALL>OG</SMALL>SQLM<SMALL>ACHINE</SMALL>ID directive. Assume a scenario
902where the production webservers have IDs like ``web01,'' ``web02,''
903and so on - and the test webservers have IDs like ``test01,''
904``test02,'' etc. Because entries in the log database are distinguished
905by their source machine, an administrator may purge unneeded test
906data from the access log as follows:
907
908<P>
909
910<DL COMPACT>
911<DT>
912<DD>delete&nbsp;from&nbsp;access_log&nbsp;where&nbsp;machine_id&nbsp;like&nbsp;'test%';
913</DD>
914</DL>
915<P>
916
917<H3><A NAME="SECTION00045400000000000000"></A><A NAME="sub:DelayedIns"></A>
918<BR>
9193.5.4 Optimizing for a busy database
920</H3>
921
922<P>
923A busy MySQL database will have SELECT statements running concurrently
924with INSERT and UPDATE statements. A long-running SELECT can in certain
925circumstances block INSERTs and therefore block mod_log_sql. A workaround
926is to compile mod_log_sql for ``delayed inserts,'' which are
927described as follows in the MySQL documentation:
928
929<P>
930<BLOCKQUOTE>
931The DELAYED option for the INSERT statement is a MySQL-specific option
932that is very useful if you have clients that can't wait for the INSERT
933to complete. This is a common problem when you use MySQL for logging
934and you also periodically run SELECT and UPDATE statements that take
935a long time to complete. DELAYED was introduced in MySQL Version 3.22.15.
936It is a MySQL extension to ANSI SQL92.
937</BLOCKQUOTE>
938<P>
939<BLOCKQUOTE>INSERT DELAYED only works with ISAM and MyISAM tables. Note that as
940MyISAM tables supports concurrent SELECT and INSERT, if there is no
941free blocks in the middle of the data file, you very seldom need to
942use INSERT DELAYED with MyISAM.
943</BLOCKQUOTE>
944<P>
945<BLOCKQUOTE>When you use INSERT DELAYED, the client will get an OK at once and
946the row will be inserted when the table is not in use by any other
947thread.
948</BLOCKQUOTE>
949<P>
950<BLOCKQUOTE>Another major benefit of using INSERT DELAYED is that inserts from
951many clients are bundled together and written in one block. This is
952much faster than doing many separate inserts.
953
954</BLOCKQUOTE>
955The general disadvantages of delayed inserts are:
956
957<P>
958
959<OL>
960<LI>The queued rows are only stored in memory until they are inserted
961into the table. If mysqld dies unexpectedly, any queued rows that
962weren't written to disk are lost.
963</LI>
964<LI>There is additional overhead for the server to handle a separate thread
965for each table on which you use INSERT DELAYED.
966</LI>
967</OL>
968<B>The MySQL documentation concludes, ``This means that you
969should only use INSERT DELAYED when you are really sure you need it!''
970Furthermore, the current state of error return from a failed INSERT
971DELAYED seems to be in flux, and may behave in unpredictable ways
972between different MySQL versions. See section <A HREF="node5.html#sub:DelayedInsFAQ">4.3.4</A>
973in the FAQ - you have been warned.</B>
974
975<P>
976If you are experiencing issues which could be solved by delayed inserts,
977uncomment the #MYSQLDELAYED line in the Makefile by removing the
978# that is in front of it. Recompile and reinstall your module. All
979regular INSERT statements are now INSERT DELAYED, and you should see
980no more blocking of the module.
981
982<P>
983
984<H2><A NAME="SECTION00046000000000000000"></A><A NAME="sec:ConfRef"></A>
985<BR>
9863.6 Configuration directive reference
987</H2>
988
989<P>
990It is imperative that you understand which directives are used <I>only
991once</I> in the main server config, and which are used inside VirtualHost
992stanzas and therefore multiple times within httpd.conf. The ``context''
993listed with each entry informs you of this.
994
995<P>
996
997<H3><A NAME="SECTION00046100000000000000">
9983.6.1 LogSQLCookieLogTable</A>
999</H3>
1000
1001<P>
1002
1003<DL COMPACT>
1004<DT>
1005<DD>Syntax:&nbsp;LogSQLCookieLogTable&nbsp;table-name&nbsp;
1006
1007<P>
1008Example:&nbsp;LogSQLCookieLogTable&nbsp;cookie_log
1009
1010<P>
1011Default:&nbsp;cookies
1012
1013<P>
1014Context:&nbsp;virtual&nbsp;host
1015</DD>
1016</DL>Defines which table is used for logging of cookies. Working in conjunction
1017with L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>C<SMALL>OOKIES</SMALL>, you can log many of each request's
1018associated cookies to a separate table. For meaningful data retrieval
1019the cookie table is keyed to the access table by the unique request
1020ID supplied by the standard Apache module mod_unique_id.
1021
1022<P>
1023Note that you must create the table (see create-tables.sql, included
1024in the package), or L<SMALL>OG</SMALL>SQLC<SMALL>REATE</SMALL>T<SMALL>ABLES</SMALL> must be set to ``on''.
1025
1026<P>
1027
1028<H3><A NAME="SECTION00046200000000000000">
10293.6.2 LogSQLCreateTables</A>
1030</H3>
1031
1032<P>
1033
1034<DL COMPACT>
1035<DT>
1036<DD>Syntax:&nbsp;LogSQLCreateTables&nbsp;flag
1037
1038<P>
1039Example:&nbsp;LogSQLCreateTables&nbsp;On&nbsp;
1040
1041<P>
1042Default:&nbsp;Off&nbsp;
1043
1044<P>
1045Context:&nbsp;main&nbsp;server&nbsp;config
1046</DD>
1047</DL>mod_log_sql has the ability to create its tables on-the-fly. The
1048advantage to this is convenience: you don't have to execute any SQL
1049by hand to prepare the table. This is especially helpful for people
1050with lots of virtual hosts (who should also see the L<SMALL>OG</SMALL>SQLM<SMALL>ASS</SMALL>V<SMALL>IRTUAL</SMALL>H<SMALL>OSTING</SMALL>
1051directive).
1052
1053<P>
1054There is a slight disadvantage: if you wish to activate this feature,
1055then the userid specified in L<SMALL>OG</SMALL>SQLL<SMALL>OGIN</SMALL>I<SMALL>NFO</SMALL> must have CREATE
1056privileges on the database. In an absolutely paranoid, locked-down
1057situation you may only want to grant your mod_log_sql user INSERT
1058privileges on the database; in that situation you are unable to take
1059advantage of L<SMALL>OG</SMALL>SQLC<SMALL>REATE</SMALL>T<SMALL>ABLES</SMALL>. But most people - even
1060the very security-conscious - will find that granting CREATE on the
1061logging database is reasonable.
1062
1063<P>
1064This is defined only once in the httpd.conf file.
1065
1066<P>
1067
1068<H3><A NAME="SECTION00046300000000000000">
10693.6.3 LogSQLDatabase </A>
1070</H3>
1071
1072<P>
1073
1074<DL COMPACT>
1075<DT>
1076<DD><B>MANDATORY</B>
1077
1078<P>
1079Syntax:&nbsp;LogSQLDatabase&nbsp;database&nbsp;
1080
1081<P>
1082Example:&nbsp;LogSQLDatabase&nbsp;loggingdb&nbsp;
1083
1084<P>
1085Context:&nbsp;main&nbsp;server&nbsp;config
1086</DD>
1087</DL>Defines the database that is used for logging. ``database'' must
1088be a valid db on the MySQL host defined in L<SMALL>OG</SMALL>SQLL<SMALL>OGIN</SMALL>I<SMALL>NFO</SMALL>.
1089
1090<P>
1091This is defined only once in the httpd.conf file.
1092
1093<P>
1094
1095<H3><A NAME="SECTION00046400000000000000">
10963.6.4 LogSQLForcePreserve</A>
1097</H3>
1098
1099<P>
1100
1101<DL COMPACT>
1102<DT>
1103<DD>Syntax:&nbsp;LogSQLForcePreserve&nbsp;Flag
1104
1105<P>
1106Example:&nbsp;LogSQLPreserveFile&nbsp;on
1107
1108<P>
1109Default:&nbsp;off
1110
1111<P>
1112Context:&nbsp;main&nbsp;server&nbsp;config
1113</DD>
1114</DL>You may need to perform debugging on your database and specifically
1115want mod_log_sql to make no attempts to log to it. This directive
1116instructs the module to send all its log entries directly to the preserve
1117file and to make no database INSERT attempts.
1118
1119<P>
1120This is presumably a directive for temporary use only; it could be
1121dangerous if you set it and forget it, as all your entries will simply
1122pile up in the preserve file.
1123
1124<P>
1125This is defined only once in the httpd.conf file.
1126
1127<P>
1128
1129<H3><A NAME="SECTION00046500000000000000">
11303.6.5 LogSQLHeadersInLogTable</A>
1131</H3>
1132
1133<P>
1134
1135<DL COMPACT>
1136<DT>
1137<DD>Syntax:&nbsp;LogSQLHeadersInLogTable&nbsp;table-name&nbsp;
1138
1139<P>
1140Example:&nbsp;LogSQLHeadersInLogTable&nbsp;headers
1141
1142<P>
1143Default:&nbsp;headers_in
1144
1145<P>
1146Context:&nbsp;virtual&nbsp;host
1147</DD>
1148</DL>Defines which table is used for logging of inbound headers. Working
1149in conjunction with L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>H<SMALL>EADERS</SMALL>I<SMALL>N</SMALL>, you can log many
1150of each request's associated headers to a separate table. For meaningful
1151data retrieval the headers table is keyed to the access table by the
1152unique request ID supplied by the standard Apache module mod_unique_id.
1153
1154<P>
1155Note that you must create the table (see create-tables.sql, included
1156in the package), or L<SMALL>OG</SMALL>SQLC<SMALL>REATE</SMALL>T<SMALL>ABLES</SMALL> must be set to ``on''.
1157
1158<P>
1159
1160<H3><A NAME="SECTION00046600000000000000">
11613.6.6 LogSQLHeadersOutLogTable</A>
1162</H3>
1163
1164<P>
1165
1166<DL COMPACT>
1167<DT>
1168<DD>Syntax:&nbsp;LogSQLHeadersOutLogTable&nbsp;table-name&nbsp;
1169
1170<P>
1171Example:&nbsp;LogSQLHeadersOutLogTable&nbsp;headers
1172
1173<P>
1174Default:&nbsp;headers_out
1175
1176<P>
1177Context:&nbsp;virtual&nbsp;host
1178</DD>
1179</DL>Defines which table is used for logging of outbound headers. Working
1180in conjunction with L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>H<SMALL>EADERS</SMALL>O<SMALL>UT</SMALL>, you can log many
1181of each request's associated headers to a separate table. For meaningful
1182data retrieval the headers table is keyed to the access table by the
1183unique request ID supplied by the standard Apache module mod_unique_id.
1184
1185<P>
1186Note that you must create the table (see create-tables.sql, included
1187in the package), or L<SMALL>OG</SMALL>SQLC<SMALL>REATE</SMALL>T<SMALL>ABLES</SMALL> must be set to ``on''.
1188
1189<P>
1190
1191<H3><A NAME="SECTION00046700000000000000">
11923.6.7 LogSQLLoginInfo </A>
1193</H3>
1194
1195<P>
1196
1197<DL COMPACT>
1198<DT>
1199<DD><B>MANDATORY</B>&nbsp;
1200
1201<P>
1202Syntax:&nbsp;LogSQLLoginInfo&nbsp;host&nbsp;user&nbsp;password
1203
1204<P>
1205Example:&nbsp;LogSQLLoginInfo&nbsp;foobar.baz.com&nbsp;logwriter&nbsp;passw0rd&nbsp;
1206
1207<P>
1208Context:&nbsp;main&nbsp;server&nbsp;config
1209</DD>
1210</DL>Defines the general parameters of the MySQL host to which you will
1211be logging. ``host'' is the hostname or IP address of the MySQL
1212machine, and is simply ``localhost'' if the database lives on
1213the same machine as Apache. ``user'' is the MySQL userid (not
1214a Unix userid!) with INSERT privileges on the table defined in L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>T<SMALL>ABLE</SMALL>.
1215``password'' is that user's password.
1216
1217<P>
1218This is defined only once in the httpd.conf file.
1219
1220<P>
1221
1222<H3><A NAME="SECTION00046800000000000000">
12233.6.8 LogSQLMachineID</A>
1224</H3>
1225
1226<P>
1227
1228<DL COMPACT>
1229<DT>
1230<DD>Syntax:&nbsp;LogSQLMachineID&nbsp;somename
1231
1232<P>
1233Example:&nbsp;LogSQLMachineID&nbsp;web01
1234
1235<P>
1236Context:&nbsp;main&nbsp;server&nbsp;config
1237</DD>
1238</DL>If you have a farm of webservers then you may wish to know which particular
1239machine made each entry; this is useful for analyzing your loadbalancing
1240methodology. L<SMALL>OG</SMALL>SQLM<SMALL>ACHINE</SMALL>ID permits you to distinguish each
1241machine's entries if you assign each machine its own L<SMALL>OG</SMALL>SQLM<SMALL>ACHINE</SMALL>ID:
1242for example, the first webserver gets ``L<SMALL>OG</SMALL>SQLM<SMALL>ACHINE</SMALL>ID
1243web01,'' the second gets ``L<SMALL>OG</SMALL>SQLM<SMALL>ACHINE</SMALL>ID web02,''
1244etc.
1245
1246<P>
1247This is defined only once in the httpd.conf file.
1248
1249<P>
1250
1251<H3><A NAME="SECTION00046900000000000000">
12523.6.9 LogSQLMassVirtualHosting</A>
1253</H3>
1254
1255<P>
1256
1257<DL COMPACT>
1258<DT>
1259<DD>Syntax:&nbsp;LogSQLMassVirtualHosting&nbsp;flag&nbsp;
1260
1261<P>
1262Example:&nbsp;LogSQLMassVirtualHosting&nbsp;On&nbsp;
1263
1264<P>
1265Default:&nbsp;Off&nbsp;
1266
1267<P>
1268Context:&nbsp;main&nbsp;server&nbsp;config
1269</DD>
1270</DL>If you administer a site hosting many, many virtual hosts then this
1271option will appeal to you. If you turn on L<SMALL>OG</SMALL>SQLM<SMALL>ASS</SMALL>V<SMALL>IRTUAL</SMALL>H<SMALL>OSTING</SMALL>
1272then several things happen:
1273
1274<P>
1275
1276<UL>
1277<LI>the on-the-fly table creation feature is activated automatically
1278</LI>
1279<LI>the transfer log table name is dynamically set from the virtual host's
1280name after stripping out SQL-unfriendly characters (example: a virtual
1281host www.grubbybaby.com gets logged to table access_www_grubbybaby_com)
1282</LI>
1283<LI>which, in turn, means that each virtual host logs to its own segregated
1284table. Because there is no data shared between virtual servers you
1285can grant your users access to the tables they need; they will be
1286unable to view others' data.
1287</LI>
1288</UL>
1289This is a huge boost in convenience for sites with many virtual servers.
1290Activating L<SMALL>OG</SMALL>SQLM<SMALL>ASS</SMALL>V<SMALL>IRTUAL</SMALL>H<SMALL>OSTING</SMALL> obviates the need to
1291create every virtual server's table and provides more granular security
1292possibilities.
1293
1294<P>
1295You are advised to investigate the use of Apache's U<SMALL>SE</SMALL>C<SMALL>ANONICAL</SMALL>N<SMALL>AME
1296</SMALL>O<SMALL>N</SMALL> directive with this directive in order to ensure that each virtual
1297host maps to one table namespace.
1298
1299<P>
1300This is defined only once in the httpd.conf file.
1301
1302<P>
1303
1304<H3><A NAME="SECTION000461000000000000000">
13053.6.10 LogSQLNotesLogTable</A>
1306</H3>
1307
1308<P>
1309
1310<DL COMPACT>
1311<DT>
1312<DD>Syntax:&nbsp;LogSQLNotesLogTable&nbsp;table-name&nbsp;
1313
1314<P>
1315Example:&nbsp;LogSQLNotesLogTable&nbsp;notes_log
1316
1317<P>
1318Default:&nbsp;notes
1319
1320<P>
1321Context:&nbsp;virtual&nbsp;host&nbsp;
1322</DD>
1323</DL>Defines which table is used for logging of notes. Working in conjunction
1324with L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>N<SMALL>OTES</SMALL>, you can log many of each request's
1325associated notes to a separate table. For meaningful data retrieval
1326the notes table is keyed to the access table by the unique request
1327ID supplied by the standard Apache module mod_unique_id.
1328
1329<P>
1330Note that you must create the table (see create-tables.sql, included
1331in the package), or L<SMALL>OG</SMALL>SQLC<SMALL>REATE</SMALL>T<SMALL>ABLES</SMALL> must be set to ``on''.
1332
1333<P>
1334
1335<H3><A NAME="SECTION000461100000000000000">
13363.6.11 LogSQLPreserveFile</A>
1337</H3>
1338
1339<P>
1340
1341<DL COMPACT>
1342<DT>
1343<DD>Syntax:&nbsp;LogSQLPreserveFile&nbsp;filename&nbsp;
1344
1345<P>
1346Example:&nbsp;LogSQLPreserveFile&nbsp;offline-preserve&nbsp;
1347
1348<P>
1349Default:&nbsp;/tmp/sql-preserve
1350
1351<P>
1352Context:&nbsp;virtual&nbsp;host
1353</DD>
1354</DL>mod_log_sql writes queries to this local preserve file in the event
1355that it cannot reach the database, and thus ensures that your high-availability
1356web frontend does not lose logs during a temporary database outage.
1357This could happen for a number of reasons: the database goes offline,
1358the network breaks, etc. You will not lose entries since the module
1359has this backup. The file consists of a series of SQL statements that
1360can be imported into your database at your convenience; furthermore,
1361because the SQL queries contain the access timestamps you do not need
1362to worry about out-of-order data after the import, which is done in
1363a simple manner:
1364
1365<P>
1366
1367<DL COMPACT>
1368<DT>
1369<DD>#&nbsp;mysql&nbsp;-uadminuser&nbsp;-p&nbsp;mydbname&nbsp;&lt;&nbsp;/tmp/sql-preserve
1370</DD>
1371</DL>If you do not define L<SMALL>OG</SMALL>SQLP<SMALL>RESERVE</SMALL>F<SMALL>ILE</SMALL> then all virtual
1372servers will log to the same default preserve file (/tmp/sql-preserve).
1373You can redefine this on a virtual-host basis in order to segregate
1374your preserve files if you desire. Note that segregation is not usually
1375necessary, as the SQL statements that are written to the preserve
1376file already distinguish between different virtual hosts if you include
1377the 'v' character in your L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL> directive.
1378It is only necessary to segregate preserve-files by virualhost if
1379you also segregate access logs by virtualhost.
1380
1381<P>
1382The module will log to Apache's E<SMALL>RROR</SMALL>L<SMALL>OG</SMALL> when it notices
1383a database outage, and upon database return. You will therefore know
1384when the preserve file is being used, although it is your responsibility
1385to import the file.
1386
1387<P>
1388The file does not need to be created in advance. It is safe to remove
1389or rename the file without interrupting Apache, as the module closes
1390the filehandle immediately after completing the write. The file is
1391created with the user &amp; group ID of the running Apache process (e.g.
1392'nobody' on many Linux distributions).
1393
1394<P>
1395
1396<H3><A NAME="SECTION000461200000000000000">
13973.6.12 LogSQLRemhostIgnore</A>
1398</H3>
1399
1400<P>
1401
1402<DL COMPACT>
1403<DT>
1404<DD>Syntax:&nbsp;LogSQLRemhostIgnore&nbsp;host1&nbsp;host2&nbsp;host3&nbsp;...&nbsp;hostN&nbsp;
1405
1406<P>
1407Example:&nbsp;LogSQLRemhostIgnore&nbsp;localnet.com&nbsp;
1408
1409<P>
1410Context:&nbsp;virtual&nbsp;host
1411</DD>
1412</DL>Lists a series of strings that, if present in the REMOTE_HOST, will
1413cause that request to <B>not</B> be logged. This directive is useful
1414for cutting down on log clutter when you are certain that you want
1415to ignore requests from certain hosts, such as your own internal network
1416machines. See section <A HREF="node4.html#sub:Ignore">3.4.2</A> for some tips for using this
1417directive.
1418
1419<P>
1420Each string is separated by a space, and no regular expressions or
1421globbing are allowed. Each string is evaluated as a substring of the
1422REMOTE_HOST using strstr(). The comparison is case sensitive.
1423
1424<P>
1425
1426<H3><A NAME="SECTION000461300000000000000">
14273.6.13 LogSQLRequestAccept</A>
1428</H3>
1429
1430<P>
1431
1432<DL COMPACT>
1433<DT>
1434<DD>Syntax:&nbsp;LogSQLRequestAccept&nbsp;req1&nbsp;req2&nbsp;req3&nbsp;...&nbsp;reqN&nbsp;
1435
1436<P>
1437Example:&nbsp;LogSQLRequestAccept&nbsp;.html&nbsp;.php&nbsp;.jpg
1438
1439<P>
1440Default:&nbsp;if&nbsp;not&nbsp;specified,&nbsp;all&nbsp;requests&nbsp;are&nbsp;``accepted''
1441
1442<P>
1443Context:&nbsp;virtual&nbsp;host
1444</DD>
1445</DL>Lists a series of strings that, if present in the URI, will permit
1446that request to be considered for logging (depending on additional
1447filtering by the ``ignore'' directives). Any request that fails
1448to match one of the L<SMALL>OG</SMALL>SQLR<SMALL>EQUEST</SMALL>A<SMALL>CCEPT</SMALL> entries will be discarded.
1449
1450<P>
1451This directive is useful for cutting down on log clutter when you
1452are certain that you only want to log certain kinds of requests, and
1453just blanket-ignore everything else. See section <A HREF="node4.html#sub:Ignore">3.4.2</A>
1454for some tips for using this directive.
1455
1456<P>
1457Each string is separated by a space, and no regular expressions or
1458globbing are allowed. Each string is evaluated as a substring of the
1459URI using strstr(). The comparison is case sensitive.
1460
1461<P>
1462This directive is completely optional. It is more general than L<SMALL>OG</SMALL>SQLR<SMALL>EQUEST</SMALL>I<SMALL>GNORE</SMALL>
1463and is evaluated before L<SMALL>OG</SMALL>SQLR<SMALL>EQUEST</SMALL>I<SMALL>GNORE</SMALL>. If
1464this directive is not used, <B>all</B> requests are accepted and
1465passed on to the other filtering directives. Therefore, only use this
1466directive if you have a specific reason to do so.
1467
1468<P>
1469
1470<H3><A NAME="SECTION000461400000000000000">
14713.6.14 LogSQLRequestIgnore</A>
1472</H3>
1473
1474<P>
1475
1476<DL COMPACT>
1477<DT>
1478<DD>Syntax:&nbsp;LogSQLRequestIgnore&nbsp;req1&nbsp;req2&nbsp;req3&nbsp;...&nbsp;reqN&nbsp;
1479
1480<P>
1481Example:&nbsp;LogSQLRequestIgnore&nbsp;root.exe&nbsp;cmd.exe&nbsp;default.ida&nbsp;favicon.ico&nbsp;
1482
1483<P>
1484Context:&nbsp;virtual&nbsp;host
1485</DD>
1486</DL>Lists a series of strings that, if present in the URI, will cause
1487that request to <B>NOT</B> be logged. This directive is
1488useful for cutting down on log clutter when you are certain that you
1489want to ignore requests for certain objects. See section <A HREF="node4.html#sub:Ignore">3.4.2</A>
1490for some tips for using this directive.
1491
1492<P>
1493Each string is separated by a space, and no regular expressions or
1494globbing are allowed. Each string is evaluated as a substring of the
1495URI using strstr(). The comparison is case sensitive.
1496
1497<P>
1498
1499<H3><A NAME="SECTION000461500000000000000">
15003.6.15 LogSQLSocketFile </A>
1501</H3>
1502
1503<P>
1504
1505<DL COMPACT>
1506<DT>
1507<DD>Syntax:&nbsp;LogSQLSocketFile&nbsp;filename&nbsp;
1508
1509<P>
1510Example:&nbsp;LogSQLSocketFile&nbsp;/tmp/mysql.sock&nbsp;
1511
1512<P>
1513Default:&nbsp;/var/lib/mysql/mysql.sock&nbsp;
1514
1515<P>
1516Context:&nbsp;main&nbsp;server&nbsp;config
1517</DD>
1518</DL>At Apache runtime you can specify the MySQL socket file to use. Set
1519this once in your main server config to override the default value.
1520This value is irrelevant if your database resides on a separate machine.
1521
1522<P>
1523mod_log_sql will automatically employ the socket for db communications
1524if the database resides on the local host. If the db resides on a
1525separate host the module will automatically use TCP/IP. This is a
1526function of the MySQL API and is not user-configurable.
1527
1528<P>
1529This is defined only once in the httpd.conf file.
1530
1531<P>
1532
1533<H3><A NAME="SECTION000461600000000000000">
15343.6.16 LogSQLTCPPort</A>
1535</H3>
1536
1537<P>
1538
1539<DL COMPACT>
1540<DT>
1541<DD>Syntax:&nbsp;LogSQLTCPPort&nbsp;portnumber
1542
1543<P>
1544Example:&nbsp;LogSQLTCPPort&nbsp;3309
1545
1546<P>
1547Default:&nbsp;3306
1548
1549<P>
1550Context:&nbsp;main&nbsp;server&nbsp;config
1551</DD>
1552</DL>Your database may listen on a different port than the default. If
1553so, use this directive to instruct the module which port to use. This
1554directive only applies if the database is on a different machine connected
1555via TCP/IP.
1556
1557<P>
1558This is defined only once in the httpd.conf file.
1559
1560<P>
1561
1562<H3><A NAME="SECTION000461700000000000000"></A><A NAME="sub:Frmat"></A>
1563<BR>
15643.6.17 LogSQLTransferLogFormat
1565</H3>
1566
1567<P>
1568
1569<DL COMPACT>
1570<DT>
1571<DD>Syntax:&nbsp;LogSQLTransferLogFormat&nbsp;format-string&nbsp;
1572
1573<P>
1574Example:&nbsp;LogSQLTransferLogFormat&nbsp;huSUTv&nbsp;
1575
1576<P>
1577Default:&nbsp;AbHhmRSsTUuv&nbsp;
1578
1579<P>
1580Context:&nbsp;virtual&nbsp;host
1581</DD>
1582</DL>Each character in the format-string defines an attribute of the request
1583that you wish to log. The default logs the information required to
1584create Combined Log Format logs, plus several extras. Here is the
1585full list of allowable keys, which sometimes resemble their Apache
1586counterparts, but do not always:
1587
1588<P>
1589<BLOCKQUOTE>
1590<TABLE CELLPADDING=3 BORDER="1">
1591<TR><TD ALIGN="CENTER">&nbsp;</TD>
1592<TH ALIGN="LEFT"><B><FONT SIZE="-1">What is this?</FONT></B></TH>
1593<TH ALIGN="LEFT"><B><FONT SIZE="-1">Data field</FONT></B></TH>
1594<TH ALIGN="LEFT"><B><FONT SIZE="-1">Column type</FONT></B></TH>
1595<TH ALIGN="LEFT"><B><FONT SIZE="-1">Example</FONT></B></TH>
1596</TR>
1597<TR><TD ALIGN="CENTER"><FONT SIZE="-1">A</FONT></TD>
1598<TD ALIGN="LEFT"><FONT SIZE="-1">User agent</FONT></TD>
1599<TD ALIGN="LEFT"><FONT SIZE="-1">agent</FONT></TD>
1600<TD ALIGN="LEFT"><FONT SIZE="-1">varchar(255)</FONT></TD>
1601<TD ALIGN="LEFT"><FONT SIZE="-1">Mozilla/4.0 (compat; MSIE 6.0; Windows)</FONT></TD>
1602</TR>
1603<TR><TD ALIGN="CENTER">a</TD>
1604<TD ALIGN="LEFT">CGI request arguments</TD>
1605<TD ALIGN="LEFT">request_args</TD>
1606<TD ALIGN="LEFT">varchar(255)</TD>
1607<TD ALIGN="LEFT">user=Smith&amp;cart=1231&amp;item=532</TD>
1608</TR>
1609<TR><TD ALIGN="CENTER"><FONT SIZE="-1">b</FONT></TD>
1610<TD ALIGN="LEFT"><FONT SIZE="-1">Bytes transfered</FONT></TD>
1611<TD ALIGN="LEFT"><FONT SIZE="-1">bytes_sent</FONT></TD>
1612<TD ALIGN="LEFT"><FONT SIZE="-1">int unsigned</FONT></TD>
1613<TD ALIGN="LEFT"><FONT SIZE="-1">32561</FONT></TD>
1614</TR>
1615<TR><TD ALIGN="CENTER"><FONT SIZE="-1">c</FONT></TD>
1616<TD ALIGN="LEFT"><FONT SIZE="-1">Text of cookie <IMG
1617 WIDTH="13" HEIGHT="21" ALIGN="BOTTOM" BORDER="0"
1618 SRC="img1.png"
1619 ALT="$^{\textrm{1}}$"></FONT></TD>
1620<TD ALIGN="LEFT"><FONT SIZE="-1">cookie</FONT></TD>
1621<TD ALIGN="LEFT"><FONT SIZE="-1">varchar(255)</FONT></TD>
1622<TD ALIGN="LEFT"><FONT SIZE="-1">Apache=sdyn.fooonline.net.1300102700823</FONT></TD>
1623</TR>
1624<TR><TD ALIGN="CENTER"><FONT SIZE="-1">H</FONT></TD>
1625<TD ALIGN="LEFT"><FONT SIZE="-1">HTTP request protocol</FONT></TD>
1626<TD ALIGN="LEFT"><FONT SIZE="-1">request_protocol</FONT></TD>
1627<TD ALIGN="LEFT"><FONT SIZE="-1">varchar(10)</FONT></TD>
1628<TD ALIGN="LEFT"><FONT SIZE="-1">HTTP/1.1</FONT></TD>
1629</TR>
1630<TR><TD ALIGN="CENTER"><FONT SIZE="-1">h</FONT></TD>
1631<TD ALIGN="LEFT"><FONT SIZE="-1">Name of remote host</FONT></TD>
1632<TD ALIGN="LEFT"><FONT SIZE="-1">remote_host</FONT></TD>
1633<TD ALIGN="LEFT"><FONT SIZE="-1">varchar(50)</FONT></TD>
1634<TD ALIGN="LEFT"><FONT SIZE="-1">blah.foobar.com</FONT></TD>
1635</TR>
1636<TR><TD ALIGN="CENTER"><FONT SIZE="-1">I</FONT></TD>
1637<TD ALIGN="LEFT"><FONT SIZE="-1">Request ID (from mod_unique_id)</FONT></TD>
1638<TD ALIGN="LEFT"><FONT SIZE="-1">id</FONT></TD>
1639<TD ALIGN="LEFT"><FONT SIZE="-1">char(19)</FONT></TD>
1640<TD ALIGN="LEFT"><FONT SIZE="-1">POlFcUBRH30AAALdBG8</FONT></TD>
1641</TR>
1642<TR><TD ALIGN="CENTER"><FONT SIZE="-1">l</FONT></TD>
1643<TD ALIGN="LEFT"><FONT SIZE="-1">Ident user info</FONT></TD>
1644<TD ALIGN="LEFT"><FONT SIZE="-1">remote_logname</FONT></TD>
1645<TD ALIGN="LEFT"><FONT SIZE="-1">varchar(50)</FONT></TD>
1646<TD ALIGN="LEFT"><FONT SIZE="-1">bobby</FONT></TD>
1647</TR>
1648<TR><TD ALIGN="CENTER"><FONT SIZE="-1">M</FONT></TD>
1649<TD ALIGN="LEFT"><FONT SIZE="-1">Machine ID <IMG
1650 WIDTH="13" HEIGHT="21" ALIGN="BOTTOM" BORDER="0"
1651 SRC="img2.png"
1652 ALT="$^{\textrm{2}}$"></FONT></TD>
1653<TD ALIGN="LEFT"><FONT SIZE="-1">machine_id</FONT></TD>
1654<TD ALIGN="LEFT"><FONT SIZE="-1">varchar(25)</FONT></TD>
1655<TD ALIGN="LEFT"><FONT SIZE="-1">web01</FONT></TD>
1656</TR>
1657<TR><TD ALIGN="CENTER"><FONT SIZE="-1">m</FONT></TD>
1658<TD ALIGN="LEFT"><FONT SIZE="-1">HTTP request method</FONT></TD>
1659<TD ALIGN="LEFT"><FONT SIZE="-1">request_method</FONT></TD>
1660<TD ALIGN="LEFT"><FONT SIZE="-1">varchar(6)</FONT></TD>
1661<TD ALIGN="LEFT"><FONT SIZE="-1">GET</FONT></TD>
1662</TR>
1663<TR><TD ALIGN="CENTER"><FONT SIZE="-1">P</FONT></TD>
1664<TD ALIGN="LEFT"><FONT SIZE="-1">httpd child PID</FONT></TD>
1665<TD ALIGN="LEFT"><FONT SIZE="-1">child_pid</FONT></TD>
1666<TD ALIGN="LEFT"><FONT SIZE="-1">smallint unsigned</FONT></TD>
1667<TD ALIGN="LEFT"><FONT SIZE="-1">3215</FONT></TD>
1668</TR>
1669<TR><TD ALIGN="CENTER"><FONT SIZE="-1">p</FONT></TD>
1670<TD ALIGN="LEFT"><FONT SIZE="-1">httpd port</FONT></TD>
1671<TD ALIGN="LEFT"><FONT SIZE="-1">server_port</FONT></TD>
1672<TD ALIGN="LEFT"><FONT SIZE="-1">smallint unsigned</FONT></TD>
1673<TD ALIGN="LEFT"><FONT SIZE="-1">80</FONT></TD>
1674</TR>
1675<TR><TD ALIGN="CENTER"><FONT SIZE="-1">R</FONT></TD>
1676<TD ALIGN="LEFT"><FONT SIZE="-1">Referer</FONT></TD>
1677<TD ALIGN="LEFT"><FONT SIZE="-1">referer</FONT></TD>
1678<TD ALIGN="LEFT"><FONT SIZE="-1">varchar(255)</FONT></TD>
1679<TD ALIGN="LEFT"><FONT SIZE="-1">http://www.biglinks4u.com/linkpage.html</FONT></TD>
1680</TR>
1681<TR><TD ALIGN="CENTER"><FONT SIZE="-1">r</FONT></TD>
1682<TD ALIGN="LEFT"><FONT SIZE="-1">Request in full form</FONT></TD>
1683<TD ALIGN="LEFT"><FONT SIZE="-1">request_line</FONT></TD>
1684<TD ALIGN="LEFT"><FONT SIZE="-1">varchar(255)</FONT></TD>
1685<TD ALIGN="LEFT"><FONT SIZE="-1">GET /books-cycroad.html HTTP/1.1</FONT></TD>
1686</TR>
1687<TR><TD ALIGN="CENTER"><FONT SIZE="-1">S</FONT></TD>
1688<TD ALIGN="LEFT"><FONT SIZE="-1">Time of request in UNIX format</FONT></TD>
1689<TD ALIGN="LEFT"><FONT SIZE="-1">time_stamp</FONT></TD>
1690<TD ALIGN="LEFT"><FONT SIZE="-1">int unsigned</FONT></TD>
1691<TD ALIGN="LEFT"><FONT SIZE="-1">1005598029</FONT></TD>
1692</TR>
1693<TR><TD ALIGN="CENTER"><FONT SIZE="-1">s</FONT></TD>
1694<TD ALIGN="LEFT"><FONT SIZE="-1">HTTP status of request</FONT></TD>
1695<TD ALIGN="LEFT"><FONT SIZE="-1">status</FONT></TD>
1696<TD ALIGN="LEFT"><FONT SIZE="-1">smallint unsigned</FONT></TD>
1697<TD ALIGN="LEFT"><FONT SIZE="-1">404</FONT></TD>
1698</TR>
1699<TR><TD ALIGN="CENTER"><FONT SIZE="-1">T</FONT></TD>
1700<TD ALIGN="LEFT"><FONT SIZE="-1">Seconds to service request</FONT></TD>
1701<TD ALIGN="LEFT"><FONT SIZE="-1">request_duration</FONT></TD>
1702<TD ALIGN="LEFT"><FONT SIZE="-1">smallint unsigned</FONT></TD>
1703<TD ALIGN="LEFT"><FONT SIZE="-1">2</FONT></TD>
1704</TR>
1705<TR><TD ALIGN="CENTER"><FONT SIZE="-1">t</FONT></TD>
1706<TD ALIGN="LEFT"><FONT SIZE="-1">Time of request in human format</FONT></TD>
1707<TD ALIGN="LEFT"><FONT SIZE="-1">request_time</FONT></TD>
1708<TD ALIGN="LEFT"><FONT SIZE="-1">char(28)</FONT></TD>
1709<TD ALIGN="LEFT"><FONT SIZE="-1">[02/Dec/2001:15:01:26 -0800]</FONT></TD>
1710</TR>
1711<TR><TD ALIGN="CENTER"><FONT SIZE="-1">U</FONT></TD>
1712<TD ALIGN="LEFT"><FONT SIZE="-1">Request in simple form</FONT></TD>
1713<TD ALIGN="LEFT"><FONT SIZE="-1">request_uri</FONT></TD>
1714<TD ALIGN="LEFT"><FONT SIZE="-1">varchar(255)</FONT></TD>
1715<TD ALIGN="LEFT"><FONT SIZE="-1">/books-cycroad.html</FONT></TD>
1716</TR>
1717<TR><TD ALIGN="CENTER"><FONT SIZE="-1">u</FONT></TD>
1718<TD ALIGN="LEFT"><FONT SIZE="-1">User info from HTTP auth</FONT></TD>
1719<TD ALIGN="LEFT"><FONT SIZE="-1">remote_user</FONT></TD>
1720<TD ALIGN="LEFT"><FONT SIZE="-1">varchar(50)</FONT></TD>
1721<TD ALIGN="LEFT"><FONT SIZE="-1">bobby</FONT></TD>
1722</TR>
1723<TR><TD ALIGN="CENTER"><FONT SIZE="-1">v</FONT></TD>
1724<TD ALIGN="LEFT"><FONT SIZE="-1">Virtual host servicing the request</FONT></TD>
1725<TD ALIGN="LEFT"><FONT SIZE="-1">virtual_host</FONT></TD>
1726<TD ALIGN="LEFT"><FONT SIZE="-1">varchar(50)</FONT></TD>
1727<TD ALIGN="LEFT"><FONT SIZE="-1">www.foobar.com</FONT></TD>
1728</TR>
1729</TABLE></BLOCKQUOTE>
1730<P>
1731<BLOCKQUOTE>
1732</BLOCKQUOTE>
1733<P>
1734<BLOCKQUOTE><IMG
1735 WIDTH="13" HEIGHT="21" ALIGN="BOTTOM" BORDER="0"
1736 SRC="img1.png"
1737 ALT="$^{\textrm{1}}$"> You must also specify L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>C<SMALL>OOKIE</SMALL>
1738for this to take effect.
1739</BLOCKQUOTE>
1740<P>
1741<BLOCKQUOTE><IMG
1742 WIDTH="13" HEIGHT="21" ALIGN="BOTTOM" BORDER="0"
1743 SRC="img2.png"
1744 ALT="$^{\textrm{2}}$"> You must also specify L<SMALL>OG</SMALL>SQLM<SMALL>ACHINE</SMALL>ID for
1745this to take effect.
1746
1747</BLOCKQUOTE>
1748If you have compiled mod_log_sql with SSL logging capability, you
1749also can use these:
1750
1751<P>
1752<BLOCKQUOTE>
1753<TABLE CELLPADDING=3 BORDER="1">
1754<TR><TD ALIGN="CENTER">&nbsp;</TD>
1755<TH ALIGN="LEFT"><B>What is this?</B></TH>
1756<TH ALIGN="LEFT"><B>Data field</B></TH>
1757<TH ALIGN="LEFT"><B>Column Type</B></TH>
1758<TH ALIGN="LEFT"><B>Example</B></TH>
1759</TR>
1760<TR><TD ALIGN="CENTER">z</TD>
1761<TD ALIGN="LEFT">SSL cipher used</TD>
1762<TD ALIGN="LEFT">ssl_cipher</TD>
1763<TD ALIGN="LEFT">varchar(25)</TD>
1764<TD ALIGN="LEFT">RC4-MD5</TD>
1765</TR>
1766<TR><TD ALIGN="CENTER">q</TD>
1767<TD ALIGN="LEFT">Keysize of the SSL connection</TD>
1768<TD ALIGN="LEFT">ssl_keysize</TD>
1769<TD ALIGN="LEFT">smallint unsigned</TD>
1770<TD ALIGN="LEFT">56</TD>
1771</TR>
1772<TR><TD ALIGN="CENTER">Q</TD>
1773<TD ALIGN="LEFT">Maximum keysize supported</TD>
1774<TD ALIGN="LEFT">ssl_maxkeysize</TD>
1775<TD ALIGN="LEFT">smallint unsigned</TD>
1776<TD ALIGN="LEFT">128</TD>
1777</TR>
1778</TABLE>
1779</BLOCKQUOTE>
1780
1781<P>
1782
1783<H3><A NAME="SECTION000461800000000000000">
17843.6.18 LogSQLTransferLogTable</A>
1785</H3>
1786
1787<P>
1788
1789<DL COMPACT>
1790<DT>
1791<DD><B>MANDATORY&nbsp;(unless</B>&nbsp;<B>L<SMALL>OG</SMALL>SQLM<SMALL>ASS</SMALL>V<SMALL>IRTUAL</SMALL>H<SMALL>OSTING</SMALL></B>&nbsp;<B>is&nbsp;``on'')</B>
1792
1793<P>
1794Syntax:&nbsp;LogSQLTransferLogTable&nbsp;table-name&nbsp;
1795
1796<P>
1797Example:&nbsp;LogSQLTransferLogTable&nbsp;access_log_table&nbsp;
1798
1799<P>
1800Context:&nbsp;virtual&nbsp;host
1801</DD>
1802</DL>Defines which table is used for logging of Apache's transfers; this
1803is analogous to Apache's TransferLog directive. table-name must be
1804a valid table within the database defined in L<SMALL>OG</SMALL>SQLD<SMALL>ATABASE</SMALL>.
1805
1806<P>
1807This directive is not necessary if you declare L<SMALL>OG</SMALL>SQLM<SMALL>ASS</SMALL>V<SMALL>IRTUAL</SMALL>H<SMALL>OSTING
1808</SMALL>O<SMALL>N</SMALL>, since that directive activates dynamically-named tables. If you
1809attempt to use L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>T<SMALL>ABLE</SMALL> at the same time a
1810warning will be logged and it will be ignored, since L<SMALL>OG</SMALL>SQLM<SMALL>ASS</SMALL>V<SMALL>IRTUAL</SMALL>H<SMALL>OSTING</SMALL>
1811takes priority.
1812
1813<P>
1814
1815<H3><A NAME="SECTION000461900000000000000">
18163.6.19 LogSQLWhichCookie</A>
1817</H3>
1818
1819<P>
1820
1821<DL COMPACT>
1822<DT>
1823<DD>Syntax:&nbsp;LogSQLWhichCookie&nbsp;cookiename&nbsp;
1824
1825<P>
1826Example:&nbsp;LogSQLWhichCookie&nbsp;Clicks
1827
1828<P>
1829Default:&nbsp;None
1830
1831<P>
1832Context:&nbsp;virtual&nbsp;host
1833</DD>
1834</DL>In HTTP, cookies have names to distinguish them from each other. Using
1835mod_usertrack, for example, you can give your user-tracking cookies
1836a name with the CookieName directive.
1837
1838<P>
1839You must include a 'c' character in L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL>
1840for this directive to take effect; once you specify 'c', L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>C<SMALL>OOKIE</SMALL>
1841tells mod_log_sql which cookie to log. This is necessary because
1842you will usually be setting and receiving more than one cookie from
1843a client; this cookie designates which one to log.
1844
1845<P>
1846Note: although this was intended for people who are using mod_usertrack
1847to set user-tracking cookies, you aren't restricted in any way. You
1848can choose which cookie you wish to log to the database -any cookie
1849at all - and it doesn't necessarily have to have anything to do with
1850mod_usertrack.
1851
1852<P>
1853
1854<H3><A NAME="SECTION000462000000000000000">
18553.6.20 LogSQLWhichCookies</A>
1856</H3>
1857
1858<P>
1859
1860<DL COMPACT>
1861<DT>
1862<DD>Syntax:&nbsp;LogSQLWhichCookies&nbsp;cookie1&nbsp;cookie2&nbsp;...&nbsp;cookieN
1863
1864<P>
1865Example:&nbsp;LogSQLWhichCookies&nbsp;userlogin&nbsp;foobar&nbsp;foobaz
1866
1867<P>
1868Default:&nbsp;None
1869
1870<P>
1871Context:&nbsp;virtual&nbsp;host
1872</DD>
1873</DL>Defines the list of cookies you would like logged. This works in conjunction
1874with L<SMALL>OG</SMALL>SQLC<SMALL>OOKIE</SMALL>L<SMALL>OG</SMALL>T<SMALL>ABLE</SMALL>. This directive does not require
1875any additional characters to be added to the L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL>
1876string. The feature is activated simply by including this directive,
1877upon which you will begin populating the separate cookie table with
1878data.
1879
1880<P>
1881Note that you must have already created the table (see create-tables.sql,
1882included in the package), or L<SMALL>OG</SMALL>SQLC<SMALL>REATE</SMALL>T<SMALL>ABLES</SMALL> must be set
1883to ``on''.
1884
1885<P>
1886
1887<H3><A NAME="SECTION000462100000000000000">
18883.6.21 LogSQLWhichHeadersIn</A>
1889</H3>
1890
1891<P>
1892
1893<DL COMPACT>
1894<DT>
1895<DD>Syntax:&nbsp;LogSQLWhichHeadersIn&nbsp;item1&nbsp;item2&nbsp;...&nbsp;itemN
1896
1897<P>
1898Example:&nbsp;LogSQLWhichHeadersIn&nbsp;UserAgent&nbsp;Accept-Encoding&nbsp;Host
1899
1900<P>
1901Default:&nbsp;None
1902
1903<P>
1904Context:&nbsp;virtual&nbsp;host
1905</DD>
1906</DL>Defines the list of inbound headers you would like logged. This works
1907in conjunction with L<SMALL>OG</SMALL>SQLH<SMALL>EADERS</SMALL>I<SMALL>N</SMALL>L<SMALL>OG</SMALL>T<SMALL>ABLE</SMALL>. This directive
1908does not require any additional characters to be added to the L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL>
1909string. The feature is activated simply by including this directive,
1910upon which you will begin populating the separate inbound-headers
1911table with data.
1912
1913<P>
1914Note that you must have already created the table (see create-tables.sql,
1915included in the package), or L<SMALL>OG</SMALL>SQLC<SMALL>REATE</SMALL>T<SMALL>ABLES</SMALL> must be set
1916to ``on''.
1917
1918<P>
1919
1920<H3><A NAME="SECTION000462200000000000000">
19213.6.22 LogSQLWhichHeadersOut</A>
1922</H3>
1923
1924<P>
1925
1926<DL COMPACT>
1927<DT>
1928<DD>Syntax:&nbsp;LogSQLWhichHeadersOut&nbsp;item1&nbsp;item2&nbsp;...&nbsp;itemN
1929
1930<P>
1931Example:&nbsp;LogSQLWhichHeadersOut&nbsp;Expires&nbsp;Content-Type&nbsp;Cache-Control
1932
1933<P>
1934Default:&nbsp;None
1935
1936<P>
1937Context:&nbsp;virtual&nbsp;host
1938</DD>
1939</DL>Defines the list of outbound headers you would like logged. This works
1940in conjunction with L<SMALL>OG</SMALL>SQLH<SMALL>EADERS</SMALL>O<SMALL>UT</SMALL>L<SMALL>OG</SMALL>T<SMALL>ABLE</SMALL>. This directive
1941does not require any additional characters to be added to the L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL>
1942string. The feature is activated simply by including this directive,
1943upon which you will begin populating the separate outbound-headers
1944table with data.
1945
1946<P>
1947Note that you must have already created the table (see create-tables.sql,
1948included in the package), or L<SMALL>OG</SMALL>SQLC<SMALL>REATE</SMALL>T<SMALL>ABLES</SMALL> must be set
1949to ``on''.
1950
1951<P>
1952
1953<H3><A NAME="SECTION000462300000000000000">
19543.6.23 LogSQLWhichNotes</A>
1955</H3>
1956
1957<P>
1958
1959<DL COMPACT>
1960<DT>
1961<DD>Syntax:&nbsp;LogSQLWhichNotes&nbsp;item1&nbsp;item2&nbsp;...&nbsp;itemN
1962
1963<P>
1964Example:&nbsp;LogSQLWhichNotes&nbsp;mod_gzip_result&nbsp;mod_gzip_compression_ratio
1965
1966<P>
1967Default:&nbsp;None
1968
1969<P>
1970Context:&nbsp;virtual&nbsp;host
1971</DD>
1972</DL>Defines the list of notes you would like logged. This works in conjunction
1973with L<SMALL>OG</SMALL>SQLN<SMALL>OTES</SMALL>L<SMALL>OG</SMALL>T<SMALL>ABLE</SMALL>. This directive does not require
1974any additional characters to be added to the L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL>
1975string. The feature is activated simply by including this directive,
1976upon which you will begin populating the separate notes table with
1977data.
1978
1979<P>
1980Note that you must have already created the table (see create-tables.sql,
1981included in the package), or L<SMALL>OG</SMALL>SQLC<SMALL>REATE</SMALL>T<SMALL>ABLES</SMALL> must be set
1982to ``on''.
1983
1984<P>
1985<HR>
1986<!--Navigation Panel-->
1987<A NAME="tex2html172"
1988 HREF="node5.html">
1989<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
1990<A NAME="tex2html168"
1991 HREF="documentation.html">
1992<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
1993<A NAME="tex2html162"
1994 HREF="node3.html">
1995<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
1996<A NAME="tex2html170"
1997 HREF="node1.html">
1998<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
1999<BR>
2000<B> Next:</B> <A NAME="tex2html173"
2001 HREF="node5.html">4 FAQ</A>
2002<B> Up:</B> <A NAME="tex2html169"
2003 HREF="documentation.html">Installing and Running mod_log_sql</A>
2004<B> Previous:</B> <A NAME="tex2html163"
2005 HREF="node3.html">2 Installation</A>
2006 &nbsp; <B> <A NAME="tex2html171"
2007 HREF="node1.html">Contents</A></B>
2008<!--End of Navigation Panel-->
2009<ADDRESS>
2010Chris Powell
20112002-12-18
2012</ADDRESS>
2013</BODY>
2014</HTML>
diff --git a/docs/node5.html b/docs/node5.html
new file mode 100644
index 0000000..e9a593c
--- /dev/null
+++ b/docs/node5.html
@@ -0,0 +1,1270 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2
3<!--Converted with LaTeX2HTML 2002-1 (1.68)
4original version by: Nikos Drakos, CBLU, University of Leeds
5* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6* with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
8<HTML>
9<HEAD>
10<TITLE>4 FAQ</TITLE>
11<META NAME="description" CONTENT="4 FAQ">
12<META NAME="keywords" CONTENT="documentation">
13<META NAME="resource-type" CONTENT="document">
14<META NAME="distribution" CONTENT="global">
15
16<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17<META NAME="Generator" CONTENT="LaTeX2HTML v2002-1">
18<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
19
20<LINK REL="STYLESHEET" HREF="documentation.css">
21
22<LINK REL="next" HREF="node6.html">
23<LINK REL="previous" HREF="node4.html">
24<LINK REL="up" HREF="documentation.html">
25<LINK REL="next" HREF="node6.html">
26</HEAD>
27
28<BODY >
29<!--Navigation Panel-->
30<A NAME="tex2html219"
31 HREF="node6.html">
32<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
33<A NAME="tex2html215"
34 HREF="documentation.html">
35<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
36<A NAME="tex2html209"
37 HREF="node4.html">
38<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
39<A NAME="tex2html217"
40 HREF="node1.html">
41<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
42<BR>
43<B> Next:</B> <A NAME="tex2html220"
44 HREF="node6.html">About this document ...</A>
45<B> Up:</B> <A NAME="tex2html216"
46 HREF="documentation.html">Installing and Running mod_log_sql</A>
47<B> Previous:</B> <A NAME="tex2html210"
48 HREF="node4.html">3 Configuration</A>
49 &nbsp; <B> <A NAME="tex2html218"
50 HREF="node1.html">Contents</A></B>
51<BR>
52<BR>
53<!--End of Navigation Panel-->
54<!--Table of Child-Links-->
55<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
56
57<UL>
58<LI><A NAME="tex2html221"
59 HREF="node5.html#SECTION00051000000000000000">4.1 General module questions</A>
60<UL>
61<LI><A NAME="tex2html222"
62 HREF="node5.html#SECTION00051100000000000000">4.1.1 Why log to an SQL database?</A>
63<LI><A NAME="tex2html223"
64 HREF="node5.html#SECTION00051200000000000000">4.1.2 Why use MySQL? Are there alternatives?</A>
65<LI><A NAME="tex2html224"
66 HREF="node5.html#SECTION00051300000000000000">4.1.3 Is this code production-ready?</A>
67<LI><A NAME="tex2html225"
68 HREF="node5.html#SECTION00051400000000000000">4.1.4 Who's using mod_log_sql?</A>
69<LI><A NAME="tex2html226"
70 HREF="node5.html#SECTION00051500000000000000">4.1.5 Why doesn't the module also replace the Apache ErrorLog?</A>
71<LI><A NAME="tex2html227"
72 HREF="node5.html#SECTION00051600000000000000">4.1.6 Does mod_log_sql work with Apache 2.x?</A>
73<LI><A NAME="tex2html228"
74 HREF="node5.html#SECTION00051700000000000000">4.1.7 Does mod_log_sql connect to MySQL via TCP/IP or a socket?</A>
75<LI><A NAME="tex2html229"
76 HREF="node5.html#SECTION00051800000000000000">4.1.8 I have discovered a bug. Who can I contact?</A>
77</UL>
78<BR>
79<LI><A NAME="tex2html230"
80 HREF="node5.html#SECTION00052000000000000000">4.2 Problems</A>
81<UL>
82<LI><A NAME="tex2html231"
83 HREF="node5.html#SECTION00052100000000000000">4.2.1 Apache segfaults when using PHP and mod_log_sql</A>
84<LI><A NAME="tex2html232"
85 HREF="node5.html#SECTION00052200000000000000">4.2.2 Apache appears to start up fine, but nothing
86is getting logged in the database</A>
87<LI><A NAME="tex2html233"
88 HREF="node5.html#SECTION00052300000000000000">4.2.3 Why do I get the message ``insufficient configuration info to
89establish database link'' in my Apache error log?</A>
90<LI><A NAME="tex2html234"
91 HREF="node5.html#SECTION00052400000000000000">4.2.4 My database cannot handle all the open connections from mod_log_sql,
92is there anything I can do?</A>
93<LI><A NAME="tex2html235"
94 HREF="node5.html#SECTION00052500000000000000">4.2.5 Why do I occasionally see a ``lost connection to MySQL server''
95message in my Apache error log?</A>
96</UL>
97<BR>
98<LI><A NAME="tex2html236"
99 HREF="node5.html#SECTION00053000000000000000">4.3 Performance and Tuning</A>
100<UL>
101<LI><A NAME="tex2html237"
102 HREF="node5.html#SECTION00053100000000000000">4.3.1 How well does it perform?</A>
103<LI><A NAME="tex2html238"
104 HREF="node5.html#SECTION00053200000000000000">4.3.2 Do I need to be worried about all the running MySQL children? Will
105holding open <I>n</I> Apache-to-MySQL connections consume a lot of
106memory? </A>
107<LI><A NAME="tex2html239"
108 HREF="node5.html#SECTION00053300000000000000">4.3.3 My webserver cannot handle all the traffic that my site receives,
109is there anything I can do?</A>
110<LI><A NAME="tex2html240"
111 HREF="node5.html#SECTION00053400000000000000">4.3.4 What is the issue with activating delayed
112inserts?</A>
113</UL>
114<BR>
115<LI><A NAME="tex2html241"
116 HREF="node5.html#SECTION00054000000000000000">4.4 ``How do I...?'' - accomplishing certain tasks</A>
117<UL>
118<LI><A NAME="tex2html242"
119 HREF="node5.html#SECTION00054100000000000000">4.4.1 I am using LogSQLMassVirtualHosting, and sometimes a single VirtualHost
120gets logged to two different tables. How do I prevent that?</A>
121<LI><A NAME="tex2html243"
122 HREF="node5.html#SECTION00054200000000000000">4.4.2 How do I extract the data in a format that my analysis tool can understand?</A>
123<LI><A NAME="tex2html244"
124 HREF="node5.html#SECTION00054300000000000000">4.4.3 How can I log mod_usertrack cookies?</A>
125<LI><A NAME="tex2html245"
126 HREF="node5.html#SECTION00054400000000000000">4.4.4 What if I want to log more than one cookie? What is the difference
127between LogSQLWhichCookie and LogSQLWhichCookies?</A>
128<LI><A NAME="tex2html246"
129 HREF="node5.html#SECTION00054500000000000000">4.4.5 What are the SSL logging features, and how do I activate them?</A>
130</UL></UL>
131<!--End of Table of Child-Links-->
132<HR>
133
134<H1><A NAME="SECTION00050000000000000000">
1354 FAQ</A>
136</H1>
137
138<P>
139
140<H2><A NAME="SECTION00051000000000000000">
1414.1 General module questions</A>
142</H2>
143
144<P>
145
146<H3><A NAME="SECTION00051100000000000000"></A><A NAME="sub:why"></A>
147<BR>
1484.1.1 Why log to an SQL database?
149</H3>
150
151<P>
152To begin with, let's get it out of the way: logging to a database
153is not a panacea. But while there are complexities with this solution,
154the benefit can be substantial for certain classes of administrator
155or people with advanced requirements:
156
157<P>
158
159<UL>
160<LI>Chores like log rotation go away, as you can DELETE records from the
161SQL database once they are no longer useful. For example, the excellent
162and popular log-analysis tool Webalizer (http://www.webalizer.com)
163does not need historic logs after it has processed them, enabling
164you to delete older logs.
165</LI>
166<LI>People with clusters of web servers (for high availability) will benefit
167the most - all their webservers can log to a single SQL database.
168This obviates the need to collate/interleave the many separate logfiles,
169which can be / highly/ problematic.
170</LI>
171<LI>People acquainted with the power of SQL SELECT statements will know
172the flexibility of the extraction possibilities at their fingertips.
173</LI>
174</UL>
175For example, do you want to see all your 404's? Do this:
176
177<P>
178
179<DL COMPACT>
180<DT>
181<DD>select&nbsp;remote_host,status,request_uri,bytes_sent,from_unixtime(time_stamp)
182
183<P>
184from&nbsp;acc_log_tbl&nbsp;where&nbsp;status=404&nbsp;order&nbsp;by&nbsp;time_stamp;
185
186<P>
187</DD>
188</DL>
189<DIV ALIGN="CENTER">
190<TABLE CELLPADDING=3 BORDER="1">
191<TR><TD ALIGN="LEFT">remote_host</TD>
192<TD ALIGN="LEFT">status</TD>
193<TD ALIGN="LEFT">request_uri</TD>
194<TD ALIGN="LEFT">bytes_sent</TD>
195<TD ALIGN="LEFT">from_unixtime(time_stamp)</TD>
196</TR>
197<TR><TD ALIGN="LEFT">marge.mmm.co.uk</TD>
198<TD ALIGN="LEFT">404</TD>
199<TD ALIGN="LEFT">/favicon.ico</TD>
200<TD ALIGN="LEFT">321</TD>
201<TD ALIGN="LEFT">2001-11-20 02:30:56</TD>
202</TR>
203<TR><TD ALIGN="LEFT">62.180.239.251</TD>
204<TD ALIGN="LEFT">404</TD>
205<TD ALIGN="LEFT">/favicon.ico</TD>
206<TD ALIGN="LEFT">333</TD>
207<TD ALIGN="LEFT">2001-11-20 02:45:25</TD>
208</TR>
209<TR><TD ALIGN="LEFT">212.234.12.66</TD>
210<TD ALIGN="LEFT">404</TD>
211<TD ALIGN="LEFT">/favicon.ico</TD>
212<TD ALIGN="LEFT">321</TD>
213<TD ALIGN="LEFT">2001-11-20 03:01:00</TD>
214</TR>
215<TR><TD ALIGN="LEFT">212.210.78.254</TD>
216<TD ALIGN="LEFT">404</TD>
217<TD ALIGN="LEFT">/favicon.ico</TD>
218<TD ALIGN="LEFT">333</TD>
219<TD ALIGN="LEFT">2001-11-20 03:26:05</TD>
220</TR>
221</TABLE>
222</DIV>
223
224<P>
225
226<DL COMPACT>
227<DT>
228<DD><P>
229</DD>
230</DL>Or do you want to see how many bytes you've sent within a certain
231directory or site? Do this:
232
233<P>
234
235<DL COMPACT>
236<DT>
237<DD>select&nbsp;request_uri,sum(bytes_sent)&nbsp;as&nbsp;bytes,count(request_uri)&nbsp;as&nbsp;howmany&nbsp;from
238
239<P>
240acc_log_tbl&nbsp;where&nbsp;request_uri&nbsp;like&nbsp;'%mod_log_sql%'&nbsp;group&nbsp;by&nbsp;request_uri&nbsp;order
241
242<P>
243by&nbsp;howmany&nbsp;desc;&nbsp;
244
245<P>
246</DD>
247</DL>
248<DIV ALIGN="CENTER">
249<TABLE CELLPADDING=3 BORDER="1">
250<TR><TD ALIGN="LEFT">request_uri</TD>
251<TD ALIGN="LEFT">bytes</TD>
252<TD ALIGN="LEFT">howmany</TD>
253</TR>
254<TR><TD ALIGN="LEFT">/mod_log_sql/style_1.css</TD>
255<TD ALIGN="LEFT">157396</TD>
256<TD ALIGN="LEFT">1288</TD>
257</TR>
258<TR><TD ALIGN="LEFT">/mod_log_sql/</TD>
259<TD ALIGN="LEFT">2514337</TD>
260<TD ALIGN="LEFT">801</TD>
261</TR>
262<TR><TD ALIGN="LEFT">/mod_log_sql/mod_log_sql.tar.gz</TD>
263<TD ALIGN="LEFT">9769312</TD>
264<TD ALIGN="LEFT">456</TD>
265</TR>
266<TR><TD ALIGN="LEFT">/mod_log_sql/faq.html</TD>
267<TD ALIGN="LEFT">5038728</TD>
268<TD ALIGN="LEFT">436</TD>
269</TR>
270</TABLE>
271</DIV>
272
273<P>
274
275<DL COMPACT>
276<DT>
277<DD><P>
278</DD>
279</DL>Or maybe you want to see who's linking to you? Do this:
280
281<P>
282
283<DL COMPACT>
284<DT>
285<DD>select&nbsp;count(referer)&nbsp;as&nbsp;num,referer&nbsp;from&nbsp;acc_log_tbl&nbsp;where
286
287<P>
288request_uri='/mod_log_sql/'&nbsp;group&nbsp;by&nbsp;referer&nbsp;order&nbsp;by&nbsp;num&nbsp;desc;
289
290<P>
291</DD>
292</DL>
293<DIV ALIGN="CENTER">
294<TABLE CELLPADDING=3 BORDER="1">
295<TR><TD ALIGN="LEFT">num</TD>
296<TD ALIGN="LEFT">referer</TD>
297</TR>
298<TR><TD ALIGN="LEFT">271</TD>
299<TD ALIGN="LEFT">http://freshmeat.net/projects/mod_log_sql/</TD>
300</TR>
301<TR><TD ALIGN="LEFT">96</TD>
302<TD ALIGN="LEFT">http://modules.apache.org/search?id=339</TD>
303</TR>
304<TR><TD ALIGN="LEFT">48</TD>
305<TD ALIGN="LEFT">http://freshmeat.net/</TD>
306</TR>
307<TR><TD ALIGN="LEFT">8</TD>
308<TD ALIGN="LEFT">http://freshmeat.net</TD>
309</TR>
310</TABLE>
311</DIV>
312
313<P>
314
315<DL COMPACT>
316<DT>
317<DD><P>
318</DD>
319</DL>As you can see, there are myriad possibilities that can be constructed
320with the wonderful SQL SELECT statement. Logging to an SQL database
321can be really quite useful!
322
323<P>
324
325<H3><A NAME="SECTION00051200000000000000">
3264.1.2 Why use MySQL? Are there alternatives?</A>
327</H3>
328
329<P>
330MySQL is a robust, free, and very powerful production-quality database
331engine. It is well supported and comes with detailed documentation.
332Many 3rd-party software pacakges (e.g. Slashcode, the engine that
333powers Slashdot) run exclusively with MySQL. In other words, you will
334belong to a very robust and well-supported community by choosing MySQL.
335
336<P>
337That being said, there are alternatives. PostgreSQL is probably MySQL's
338leading &#34;competitor&#34; in the free database world.
339There is also an excellent module available for Apache to permit logging
340to a PostgreSQL database, called pgLOGd (http://www.digitalstratum.com/pglogd/).
341
342<P>
343
344<H3><A NAME="SECTION00051300000000000000">
3454.1.3 Is this code production-ready?</A>
346</H3>
347
348<P>
349By all accounts it is. It is known to work without a problem on many-thousands-of-hits-per-day
350webservers. Does that mean it is 100% bug free? Well, no software
351is. But it is well-tested and believed to be fully compatible with
352production environments. (The usual disclaimers apply. This software
353is provided without warranty of any kind.)
354
355<P>
356
357<H3><A NAME="SECTION00051400000000000000">
3584.1.4 Who's using mod_log_sql?</A>
359</H3>
360
361<P>
362Good question! It would be great to find out! If you are a production-level
363mod_log_sql user, please contact the maintainer, Chris Powell (chris@grubbybaby.com)
364so that you can be mentioned here.
365
366<P>
367
368<H3><A NAME="SECTION00051500000000000000">
3694.1.5 Why doesn't the module also replace the Apache ErrorLog?</A>
370</H3>
371
372<P>
373There are circumstances when that would be quite unwise - for example,
374if Apache could not reach the MySQL server for some reason and needed
375to log that fact. Without a text-based error log you'd never know
376anything was wrong, because Apache would be trying to log a database
377connection error to the database... you get the point.
378
379<P>
380Error logs are usually not very high-traffic and are really best left
381as text files on a web server machine.
382
383<P>
384
385<H3><A NAME="SECTION00051600000000000000">
3864.1.6 Does mod_log_sql work with Apache 2.x?</A>
387</H3>
388
389<P>
390As of this writing, no. The Apache Group significantly altered the
391module API with the release of Apache 2.0. All modules written for
3921.3, including mod_log_sql, will not work with 2.0.
393
394<P>
395mod_log_sql will eventually be ported to Apache 2.x, but not immediately.
396It is going to take some time, and there are other features that have
397higher priority. Please sign up for the announcements list (on the
398main website) or monitor the website for updates to learn when the
399port (and other releases) are available.
400
401<P>
402&lt;OPINION&gt;If you're a *NIX user, stick with Apache 1.3.x for now.
403Major modules like mod_ssl and PHP are not even ready for 2.0 yet,
404and the main benefits in 2.0 are for Win32 users anyway. Apache 1.3.x
405is rock-stable and performs equally well on *NIX as 2.0.&lt;/OPINION&gt;
406
407<P>
408
409<H3><A NAME="SECTION00051700000000000000">
4104.1.7 Does mod_log_sql connect to MySQL via TCP/IP or a socket?</A>
411</H3>
412
413<P>
414It depends! This is not determined by mod_log_sql. mod_log_sql
415relies on a connection command that is supplied in the MySQL API,
416and that command is somewhat intelligent. How it works:
417
418<P>
419
420<UL>
421<LI>if the specified MySQL database is on the same machine, the connection
422command uses a socket to communicate with MySQL
423</LI>
424<LI>if the specified MySQL database is on a different machine, mod_log_sql
425connects using TCP/IP.
426</LI>
427</UL>
428You don't have any control of which methodology is used. You can fine-tune
429some of the configuration, however. The L<SMALL>OG</SMALL>SQLS<SMALL>OCKET</SMALL>F<SMALL>ILE</SMALL>
430runtime configuration directive overrides the default of ``/var/lib/mysql/mysql.sock''
431for socket-based connections, whereas the L<SMALL>OG</SMALL>SQLTCPP<SMALL>ORT</SMALL> command
432allows to you override the default TCP port of 3306 for TCP/IP connections.
433
434<P>
435
436<H3><A NAME="SECTION00051800000000000000">
4374.1.8 I have discovered a bug. Who can I contact?</A>
438</H3>
439
440<P>
441Please contact the maintainer (chris@grubbybaby.com)! Your
442comments, suggestions, bugfixes, bug catches, and usage testimonials
443are always welcome. As free software, mod_log_sql is intended to
444be a community effort - any code contributions or other ideas will
445be fully and openly credited, of course.
446
447<P>
448
449<H2><A NAME="SECTION00052000000000000000">
4504.2 Problems</A>
451</H2>
452
453<P>
454
455<H3><A NAME="SECTION00052100000000000000">
4564.2.1 Apache segfaults when using PHP and mod_log_sql</A>
457</H3>
458
459<P>
460This occurs if you compiled PHP with MySQL database support. PHP utilizes
461its internal, bundled MySQL libraries by default. These conflict with
462the ``real'' MySQL libraries linked by mod_log_sql, causing
463the segmentation fault.
464
465<P>
466The solution is to configure PHP to link against the real MySQL libraries
467and recompile mod_php. Apache will run properly once the modules
468are all using the same version of the MySQL libraries.
469
470<P>
471
472<H3><A NAME="SECTION00052200000000000000"></A><A NAME="faq:NothingLogged"></A>
473<BR>
4744.2.2 Apache appears to start up fine, but nothing
475is getting logged in the database
476</H3>
477
478<P>
479If you do not see any entries in the access_log, then something is
480preventing the inserts from happening. This could be caused by several
481things:
482
483<P>
484
485<UL>
486<LI>Improper privileges set up in the MySQL database
487</LI>
488<LI>You aren't hitting a VirtualHost that has a LogSQLTransferLogTable
489entry
490</LI>
491<LI>You didn't specify the right database host or login information
492</LI>
493<LI>Another factor is preventing a connection to the database
494</LI>
495</UL>
496Important: it is improper to ask for help before you have followed
497these steps.
498
499<P>
500First examine the MySQL log that you established in step <A HREF="node4.html#step:EnaLog">6</A>
501of section <A HREF="node4.html#sub:PrepDb">3.1</A>. Ensure that the INSERT statements are
502not being rejected because of a malformed table name or other typographical
503error. By enabling that log, you instructed MySQL to log every connection
504and command it receives - if you see no INSERT attempts in the log,
505the module isn't successfully connecting to the database. If you see
506nothing at all in the log - not even a record of your administrative
507connection attempts, then you did not enable the log correctly. If
508you do see INSERT attempts but they are failing, the log should tell
509you why.
510
511<P>
512Second, confirm that your L<SMALL>OG</SMALL>SQL* directives are all correct.
513
514<P>
515Third, examine the Apache error logs for messages from mod_log_sql;
516the module will offer hints as to why it cannot connect, etc.
517
518<P>
519The next thing to do is recompile the module with debugging output
520activated. change the &#34;#undef DEBUG&#34; on line 8
521of mod_log_sql.c to &#34;#define DEBUG&#34; and recompile/reinstall.
522The module will now output copious notes about what it is doing, and
523this will help you (and the maintainer) solve the problem. In order
524to see the debugging messages, ensure that you make them visible using
525the L<SMALL>OG</SMALL>L<SMALL>EVEL</SMALL> directive <B>in the main server config
526as well as in each</B> <B>V<SMALL>IRTUAL</SMALL>H<SMALL>OST</SMALL></B> <B>config:</B>
527
528<P>
529
530<DL COMPACT>
531<DT>
532<DD>LogLevel&nbsp;debug
533
534<P>
535ErrorLog&nbsp;/var/log/httpd/server-messages&nbsp;
536</DD>
537</DL>
538<P>
539
540<H3><A NAME="SECTION00052300000000000000">
5414.2.3 Why do I get the message ``insufficient configuration info to
542establish database link'' in my Apache error log?</A>
543</H3>
544
545<P>
546At a minimum, L<SMALL>OG</SMALL>SQLD<SMALL>ATABASE</SMALL> and L<SMALL>OG</SMALL>SQLL<SMALL>OGIN</SMALL>I<SMALL>NFO</SMALL>
547must be defined in order for the module to be able to establish a
548database link. If these are not defined or are incomplete you will
549receive this error message.
550
551<P>
552
553<H3><A NAME="SECTION00052400000000000000">
5544.2.4 My database cannot handle all the open connections from mod_log_sql,
555is there anything I can do?</A>
556</H3>
557
558<P>
559The rule of thumb: if you have <I>n</I> webservers each configured
560to support <I>y</I> M<SMALL>AX</SMALL>C<SMALL>LIENTS</SMALL>, then your database must be
561able to handle <IMG
562 WIDTH="41" HEIGHT="29" ALIGN="MIDDLE" BORDER="0"
563 SRC="img3.png"
564 ALT="$n\times y$"> simultenous connections <I>in the worst
565case.</I> Certainly you must use common sense, consider reasonable traffic
566expectations and structure things accordingly.
567
568<P>
569Tweaking my.cnf to scale to high connection loads is imperative. But
570if hardware limitations prevent your MySQL server from gracefully
571handling the number of incoming connections, it would be beneficial
572to upgrade the memory or CPU on that server in order to handle the
573load.
574
575<P>
576Jeremy Zawodny, a highly respected MySQL user and contributor to Linux
577Magazine, has this very helpful and highly appropriate article on
578tuning MySQL: http://jeremy.zawodny.com/blog/archives/000173.html
579
580<P>
581Please remember that mod_log_sql's overriding principle is <B>performance</B>
582- that is what the target audience demands and expects. Other database
583logging solutions do not open and maintain many database connections,
584but their performance suffers drastically. For example, pgLOGd funnels
585all log connections through a separate daemon that connects to the
586database, but that bottlenecks the entire process. mod_log_sql achieves
587performance numbers an order of magnitude greater than the alternatives
588because it dispenses with the overhead associated with rapid connection
589cycling, and it doesn't attempt to shoehorn all the database traffic
590through a single extra daemon or proxy process.
591
592<P>
593
594<H3><A NAME="SECTION00052500000000000000">
5954.2.5 Why do I occasionally see a ``lost connection to MySQL server''
596message in my Apache error log?</A>
597</H3>
598
599<P>
600This message may appear every now and then in your Apache error log,
601especially on very lightly loaded servers. This doesn't mean that
602anything is necessarily wrong. Within each httpd child process, mod_log_sql
603will open (and keep open) a connection to the MySQL server. MySQL,
604however, will close connections that haven't been used in a while;
605the default timeout is 8 hours. When this occurs, mod_log_sql will
606notice and re-open the connection. That event is what is being logged,
607and looks like this:
608
609<P>
610
611<DL COMPACT>
612<DT>
613<DD>[Tue&nbsp;Nov&nbsp;12&nbsp;19:04:10&nbsp;2002]&nbsp;[error]&nbsp;mod_log_sql:&nbsp;first&nbsp;attempt&nbsp;failed,&nbsp;
614
615<P>
616&nbsp;&nbsp;API&nbsp;said:&nbsp;error&nbsp;2013,&nbsp;Lost&nbsp;connection&nbsp;to&nbsp;MySQL&nbsp;server&nbsp;during&nbsp;query&nbsp;
617
618<P>
619[Tue&nbsp;Nov&nbsp;12&nbsp;19:04:10&nbsp;2002]&nbsp;[error]&nbsp;mod_log_sql:&nbsp;reconnect&nbsp;successful
620
621<P>
622[Tue&nbsp;Nov&nbsp;12&nbsp;19:04:10&nbsp;2002]&nbsp;[error]&nbsp;mod_log_sql:&nbsp;second&nbsp;attempt&nbsp;successful
623</DD>
624</DL>Reference: MySQL documentation (http://www.mysql.com/documentation/mysql/bychapter/manual_Problems.html#Gone_away)
625
626<P>
627
628<H2><A NAME="SECTION00053000000000000000">
6294.3 Performance and Tuning</A>
630</H2>
631
632<P>
633
634<H3><A NAME="SECTION00053100000000000000">
6354.3.1 How well does it perform?</A>
636</H3>
637
638<P>
639mod_log_sql scales to very high loads. Apache 1.3.22 + mod_log_sql
640was benchmarked using the &#34;ab&#34; (Apache Bench) program
641that comes with the Apache distribution; here are the results.
642
643<P>
644Overall configuration:
645
646<P>
647
648<UL>
649<LI>Machine A: Apache webserver
650</LI>
651<LI>Machine B: MySQL server
652</LI>
653<LI>Machines A and B connected with 100Mbps Ethernet
654</LI>
655<LI>Webserver: Celeron 400, 128 MB RAM, IDE storage
656</LI>
657</UL>
658Apache configuration:
659
660<P>
661
662<DL COMPACT>
663<DT>
664<DD>Timeout&nbsp;300&nbsp;
665
666<P>
667KeepAlive&nbsp;On&nbsp;
668
669<P>
670MaxKeepAliveRequests&nbsp;100&nbsp;
671
672<P>
673KeepAliveTimeout&nbsp;15&nbsp;
674
675<P>
676MinSpareServers&nbsp;5&nbsp;
677
678<P>
679StartServers&nbsp;10&nbsp;
680
681<P>
682MaxSpareServers&nbsp;15&nbsp;
683
684<P>
685MaxClients&nbsp;256&nbsp;
686
687<P>
688MaxRequestsPerChild&nbsp;5000&nbsp;
689
690<P>
691LogSQLTransferLogFormat&nbsp;AbHhmRSsTUuvc&nbsp;
692
693<P>
694LogSQLWhichCookie&nbsp;Clicks&nbsp;
695
696<P>
697CookieTracking&nbsp;on&nbsp;
698
699<P>
700CookieName&nbsp;Clicks
701</DD>
702</DL>&#34;ab&#34; commandline:
703
704<P>
705
706<DL COMPACT>
707<DT>
708<DD>./ab&nbsp;-c&nbsp;10&nbsp;-t&nbsp;20&nbsp;-v&nbsp;2&nbsp;-C&nbsp;Clicks=ab_run&nbsp;http://www.hostname.com/target&nbsp;
709</DD>
710</DL>( 10 concurrent requests; 20 second test; setting a cookie &#34;Clicks=ab_run&#34;;
711target = the mod_log_sql homepage. )
712
713<P>
714Ten total ab runs were conducted: five with MySQL logging enabled,
715and five with all MySQL directives commented out of httpd.conf. Then
716each five were averaged. The results:
717
718<P>
719
720<UL>
721<LI>Average of five runs employing MySQL <I>and</I> standard text logging:
722<B>139.01 requests per second, zero errors</B>.
723</LI>
724<LI>Average of five runs employing <I>only</I> standard text logging:
725<B>139.96 requests per second, zero errors</B>.
726</LI>
727</UL>
728In other words, any rate-limiting effects on this particular hardware
729setup are not caused by MySQL. Note that although this very simple
730webserver setup is hardly cutting-edge - it is, after all, a fairly
731small machine - 139 requests per second equal over <I>twelve million
732hits per day.</I>
733
734<P>
735If you run this benchmark yourself, take note of three things:
736
737<P>
738
739<OL>
740<LI>Use a target URL that is on your own webserver :-).
741</LI>
742<LI>Wait until all your connections are closed out between runs; after
743several thousand requests your TCP/IP stack will be filled with hundreds
744of connections in TIME_WAIT that need to close. Do a &#34;netstat
745-t|wc -l&#34; on the webserver to see. If you don't wait, you
746can expect to see a lot of messages like &#34;ip_conntrack:
747table full, dropping packet&#34; in your logs. (This has nothing
748to do with mod_log_sql, this is simply the nature of the TCP/IP
749stack in the Linux kernel.)
750</LI>
751<LI>When done with your runs, clean these many thousands of requests out
752of your database:
753</LI>
754</OL>
755
756<DL COMPACT>
757<DT>
758<DD>mysql&gt;&nbsp;delete&nbsp;from&nbsp;access_log&nbsp;where&nbsp;agent&nbsp;like&nbsp;'ApacheBench%';&nbsp;
759
760<P>
761mysql&gt;&nbsp;optimize&nbsp;table&nbsp;access_log;&nbsp;
762</DD>
763</DL>
764<P>
765
766<H3><A NAME="SECTION00053200000000000000">
7674.3.2 Do I need to be worried about all the running MySQL children? Will
768holding open <I>n</I> Apache-to-MySQL connections consume a lot of
769memory? </A>
770</H3>
771
772<P>
773Short answer: you shouldn't be worried.
774
775<P>
776Long answer: you might be evaluating at the output of ``ps -aufxw''
777and becoming alarmed at all the 7MB httpd processes or 22MB mysqld
778children that you see. Don't be alarmed<I>.</I> It's true that mod_log_sql
779opens and holds open many MySQL connections: each httpd child maintains
780one open database connection (and holds it open for performance reasons).
781Four webservers, each running 20 Apache children, will hold open 80
782MySQL connections, which means that your MySQL server needs to handle
78380 simultaneous connections. In truth, your MySQL server needs to
784handle far more than that if traffic to your website spikes and the
785Apache webservers spawn off an additional 30 children each...
786
787<P>
788Fortunately the cost reported by 'ps -aufxw' is deceptive. This is
789due to an OS memory-management feature called ``copy-on-write.''
790When you have a number of identical child processes (e.g. Apache,
791MySQL), it would appear in ``ps'' as though each one occupies
792a great deal of RAM - as much as 7MB per httpd child! In actuality
793each additional child only occupies a small bit of extra memory -
794most of the memory pages are common to each child and therefore shared
795in a ``read-only'' fashion. The OS can get away with this because
796the majority of memory pages for one child are identical across all
797children. Instead of thinking of each child as a rubber stamp of the
798others, think of each child as a basket of links to a common memory
799area.
800
801<P>
802A memory page is only duplicated when it needs to be written to, hence
803``copy-on-write.'' The result is efficiency and decreased memory
804consumption. ``ps'' may report 7MB per child, but it might really
805only ``cost'' 900K of extra memory to add one more child. It is
806<B>not</B> <B>correct</B> to assume that 20 Apache
807children with a VSZ of 7MB each equals <!-- MATH
808 $(20\times 7MB)$
809 -->
810<IMG
811 WIDTH="90" HEIGHT="32" ALIGN="MIDDLE" BORDER="0"
812 SRC="img4.png"
813 ALT="$(20\times 7MB)$"> of memory
814consumption - the real answer is much, much lower. The same ``copy-on-write''
815rules apply to all your MySQL children: 40 mysqld children @ 22MB
816each <B>do not</B> occupy 880MB of RAM.
817
818<P>
819The bottom line: although there is a cost to spawn extra httpd or
820mysqld children, that cost is not as great as ``ps'' would lead
821you to believe.
822
823<P>
824
825<H3><A NAME="SECTION00053300000000000000">
8264.3.3 My webserver cannot handle all the traffic that my site receives,
827is there anything I can do?</A>
828</H3>
829
830<P>
831If you have exhausted all the tuning possibilities on your existing
832server, it is probably time you evaluated the benefits of clustering
833two or more webservers together in a load-balanced fashion. In fact,
834users of such a setup are mod_log_sql's target audience!
835
836<P>
837
838<H3><A NAME="SECTION00053400000000000000"></A><A NAME="sub:DelayedInsFAQ"></A>
839<BR>
8404.3.4 What is the issue with activating delayed
841inserts?
842</H3>
843
844<P>
845There are several.
846
847<P>
848
849<OL>
850<LI>INSERT DELAYED is a specific syntax to MySQL and is not supported
851by any other database. Ergo, why is it needed, and what MySQL deficiency
852is it working around? INSERT DELAYED is a kluge.
853</LI>
854<LI>The MySQL documentation is unclear whether INSERT DELAYED is even
855necessary for an optimized database. It says, ``The DELAYED option
856for the INSERT statement is a MySQL-specific option that is very useful
857if you have clients that can't wait for the INSERT to complete.''
858But then it goes on to say, ``Note that as MyISAM tables supports
859concurrent SELECT and INSERT, if there is no free blocks in the middle
860of the data file, you very seldom need to use INSERT DELAYED with
861MyISAM.''
862</LI>
863<LI>Because INSERT DELAYED returns without waiting for the data to be
864written, a hard kill of your MySQL database at the right (wrong?)
865moment could lose those logfile entries.
866</LI>
867<LI>As of MySQL version 3.23.52, the error return functions disagree after
868a failed INSERT DELAYED: mysql_errno() always returns 0, even if
869mysql_error() returns a textual error. I have reported this bug to
870the MySQL folks. However, we have no way of knowing what solution
871they will adopt to fix this, and with the worst case solution mod_log_sql
872would not be able to tell if anything went wrong with a delayed insert.
873</LI>
874</OL>
875Instead of delayed inserts, you may wish to utilize InnoDB tables
876(instead of the standard MyISAM tables). InnoDB tables suppot row-level
877locking and are recommended for high-volume databases.
878
879<P>
880If after understanding these problems you still wish to enable delayed
881inserts, section <A HREF="node4.html#sub:DelayedIns">3.5.4</A> discusses how.
882
883<P>
884
885<H2><A NAME="SECTION00054000000000000000">
8864.4 ``How do I...?'' - accomplishing certain tasks</A>
887</H2>
888
889<P>
890
891<H3><A NAME="SECTION00054100000000000000">
8924.4.1 I am using LogSQLMassVirtualHosting, and sometimes a single VirtualHost
893gets logged to two different tables. How do I prevent that?</A>
894</H3>
895
896<P>
897Proper usage of the Apache runtime S<SMALL>ERVER</SMALL>N<SMALL>AME</SMALL> directive and
898the directive U<SMALL>SE</SMALL>C<SMALL>ANONICAL</SMALL>N<SMALL>AME </SMALL>O<SMALL>N</SMALL> (or DNS) are necessary
899to prevent this problem. ``On'' is the default for U<SMALL>SE</SMALL>C<SMALL>ANONICAL</SMALL>N<SMALL>AME</SMALL>,
900and specifies that self-referential URLs are generated from the S<SMALL>ERVER</SMALL>N<SMALL>AME</SMALL>
901part of your VirtualHost:
902
903<P>
904<BLOCKQUOTE>
905With UseCanonicalName on (and in all versions prior to 1.3) Apache
906will use the ServerName and Port directives to construct the canonical
907name for the server. With UseCanonicalName off Apache will form self-referential
908URLs using the hostname and port supplied by the client if any are
909supplied (otherwise it will use the canonical name, as defined above).
910[From the Apache documentation http://httpd.apache.org/docs/mod/core.html#usecanonicalname]
911
912</BLOCKQUOTE>
913The module inherits Apache's ``knowledge'' about the server name
914being accessed. As long as those two directives are properly configured,
915mod_log_sql will log to only one table per virtual host while using
916L<SMALL>OG</SMALL>SQLM<SMALL>ASS</SMALL>V<SMALL>IRTUAL</SMALL>H<SMALL>OSTING</SMALL>.
917
918<P>
919
920<H3><A NAME="SECTION00054200000000000000">
9214.4.2 How do I extract the data in a format that my analysis tool can understand?</A>
922</H3>
923
924<P>
925mod_log_sql would be virtually useless if there weren't a way for
926you to extract the data from your database in a somewhat meaningful
927fashion. To that end there's a Perl script enclosed with the distribution.
928That script (make_combined_log.pl) is designed to extract N-many
929days worth of access logs and provide them in a Combined Log Format
930output. You can use this very tool right in /etc/crontab to extract
931logs on a regular basis so that your favorite web analysis tool can
932read them. Or you can examine the Perl code to construct your own
933custom tool.
934
935<P>
936For example, let's say that you want your web statistics updated once
937per day in the wee hours of the morning. A good way to accomplish
938that could be the following entries in /etc/crontab:
939
940<P>
941
942<DL COMPACT>
943<DT>
944<DD>#&nbsp;Generate&nbsp;the&nbsp;temporary&nbsp;apache&nbsp;logs&nbsp;from&nbsp;the&nbsp;MySQL&nbsp;database&nbsp;(for&nbsp;webalizer)&nbsp;
945
946<P>
94705&nbsp;04&nbsp;*&nbsp;*&nbsp;*&nbsp;root&nbsp;make_combined_log.pl&nbsp;1&nbsp;www.grubbybaby.com&nbsp;&gt;&nbsp;/var/log/temp01
948
949<P>
950#&nbsp;Run&nbsp;webalizer&nbsp;on&nbsp;httpd&nbsp;log&nbsp;
951
952<P>
95330&nbsp;04&nbsp;*&nbsp;*&nbsp;*&nbsp;root&nbsp;webalizer&nbsp;-c&nbsp;/etc/webalizer.conf;&nbsp;rm&nbsp;-f&nbsp;/var/log/temp01
954</DD>
955</DL>Or if you have a newer system that puts files in /etc/cron.daily etc.,
956create a file called ``webalizer'' in the cron.daily subdirectory.
957Use the following as the contents of your file, and make sure to chmod
958755 it when done.
959
960<P>
961
962<DL COMPACT>
963<DT>
964<DD>#!/bin/sh
965
966<P>
967/usr/local/sbin/make_combined_log.pl&nbsp;1&nbsp;www.yourdomain.com&nbsp;&gt;&nbsp;/var/log/httpd/templog
968
969<P>
970/usr/local/bin/webalizer&nbsp;-q&nbsp;-c&nbsp;/etc/webalizer.conf&nbsp;
971
972<P>
973rm&nbsp;-f&nbsp;/var/log/httpd/templog
974</DD>
975</DL>See? Easy.
976
977<P>
978
979<H3><A NAME="SECTION00054300000000000000"></A><A NAME="sec:cookie"></A>
980<BR>
9814.4.3 How can I log mod_usertrack cookies?
982</H3>
983
984<P>
985A number of people like to log mod_usertrack cookies in their Apache
986TransferLog to aid in understanding their visitors' clickstreams.
987This is accomplished, for example, with a statement as follows:
988
989<P>
990
991<DL COMPACT>
992<DT>
993<DD>LogFormat&nbsp;&#34;%h&nbsp;%l&nbsp;%u&nbsp;%t&nbsp;&#92;&#34;%r&#92;&#34;&nbsp;%s&nbsp;%b&nbsp;&#92;&#34;%{Referer}i&#92;&#34;&nbsp;&#92;&#34;%{User-Agent}i&#92;&#34;&#34;&nbsp;&#92;&#34;%{cookie}n&#92;&#34;&#34;
994</DD>
995</DL>Naturally it would be nice for mod_log_sql to permit the admin to
996log the cookie data as well, so as of version 1.10 you can do this.
997You need to have already compiled mod_usertrack into httpd - it's
998one of the standard Apache modules.
999
1000<P>
1001First make sure you have a column called &#34;cookie&#34;
1002in the MySQL database to hold the cookies, which can be done as follows
1003if you already have a working database:
1004
1005<P>
1006
1007<DL COMPACT>
1008<DT>
1009<DD>alter&nbsp;table&nbsp;acc_log_tbl&nbsp;add&nbsp;column&nbsp;cookie&nbsp;varchar(255);
1010</DD>
1011</DL>Next configure your server to set usertracking cookies as follows,
1012and make sure you include the new 'c' directive in your L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL>,
1013which activates cookie logging. Here's an example:
1014
1015<P>
1016
1017<DL COMPACT>
1018<DT>
1019<DD>&lt;VirtualHost&nbsp;1.2.3.4&gt;&nbsp;
1020
1021<P>
1022&nbsp;CookieTracking&nbsp;on&nbsp;
1023
1024<P>
1025&nbsp;CookieStyle&nbsp;Cookie&nbsp;
1026
1027<P>
1028&nbsp;CookieName&nbsp;Foobar&nbsp;
1029
1030<P>
1031&nbsp;LogSQLTransferLogFormat&nbsp;huSUsbTvRAc&nbsp;
1032
1033<P>
1034&nbsp;LogSQLWhichCookie&nbsp;Foobar&nbsp;
1035
1036<P>
1037&lt;/VirtualHost&gt;
1038</DD>
1039</DL>The first three lines configure mod_usertrack to create a COOKIE
1040(RFC 2109) format cookie called Foobar. The last two lines tell mod_log_sql
1041to log cookies named Foobar. You have to choose which cookie to log
1042because more than one cookie can/will be sent to the server by the
1043client.
1044
1045<P>
1046Recap: the 'c' character <I>activates</I> cookie logging, and the
1047L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>C<SMALL>OOKIE</SMALL> directive <I>chooses</I> which cookie to
1048log.
1049
1050<P>
1051FYI, you are advised NOT to use C<SMALL>OOKIE</SMALL>S<SMALL>TYLE </SMALL>C<SMALL>OOKIE2</SMALL> - it
1052seems that even newer browsers (IE 5.5, etc.) have trouble with the
1053new COOKIE2 (RFC 2965) format. Just stick with the standard COOKIE
1054format and you'll be fine.
1055
1056<P>
1057Perform some hits on your server and run a select:
1058
1059<P>
1060
1061<DL COMPACT>
1062<DT>
1063<DD>mysql&gt;&nbsp;select&nbsp;request_uri,cookie&nbsp;from&nbsp;access_log&nbsp;where&nbsp;cookie&nbsp;is&nbsp;not&nbsp;null;
1064
1065<P>
1066</DD>
1067</DL>
1068<DIV ALIGN="CENTER">
1069<TABLE CELLPADDING=3 BORDER="1">
1070<TR><TD ALIGN="LEFT">request_uri</TD>
1071<TD ALIGN="LEFT">cookie</TD>
1072</TR>
1073<TR><TD ALIGN="LEFT">/mod_log_sql/</TD>
1074<TD ALIGN="LEFT">ool-18e4.dyn.optonline.net.130051007102700823</TD>
1075</TR>
1076<TR><TD ALIGN="LEFT">/mod_log_sql/usa.gif</TD>
1077<TD ALIGN="LEFT">ool-18e4.dyn.optonline.net.130051007102700823</TD>
1078</TR>
1079<TR><TD ALIGN="LEFT">/mod_log_sql/style_1.css</TD>
1080<TD ALIGN="LEFT">ool-18e4.dyn.optonline.net.130051007102700823</TD>
1081</TR>
1082</TABLE>
1083</DIV>
1084
1085<P>
1086
1087<DL COMPACT>
1088<DT>
1089<DD><P>
1090</DD>
1091</DL>
1092<P>
1093
1094<H3><A NAME="SECTION00054400000000000000">
10954.4.4 What if I want to log more than one cookie? What is the difference
1096between LogSQLWhichCookie and LogSQLWhichCookies?</A>
1097</H3>
1098
1099<P>
1100As of version 1.17, you have a choice in how you want cookie logging
1101handled.
1102
1103<P>
1104If you are interested in logging only one cookie per request, follow
1105the instructions in section <A HREF="node5.html#sec:cookie">4.4.3</A> above. That cookie will
1106be logged to a column in the regular access_log table, and the actual
1107cookie you want to log is specified with L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>C<SMALL>OOKIE</SMALL>.
1108Don't forget to specify the 'c' character in L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL>.
1109
1110<P>
1111If, however, you need to log multiple cookies per request, you must
1112employ the L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>C<SMALL>OOKIES</SMALL> (note the plural) directive.
1113The cookies you specify will be logged to a separate table (as discussed
1114in section <A HREF="node4.html#secMulTable">3.5.2</A>), and entries in that table will be
1115linked to the regular access_log entries via the unique ID that is
1116supplied by mod_unique_id. Without mod_unique_id the information
1117will still be logged but you will be unable to correlate which cookies
1118go with which access-requests. Furthermore, with L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>C<SMALL>OOKIES</SMALL>,
1119you do <B>not</B> need to include the 'c' character in L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL>.
1120
1121<P>
1122L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>C<SMALL>OOKIE</SMALL> and L<SMALL>OG</SMALL>SQLW<SMALL>HICH</SMALL>C<SMALL>OOKIES</SMALL> can coexist
1123without conflict because they operate on entireley different tables,
1124but you're better off choosing the one you need.
1125
1126<P>
1127
1128<H3><A NAME="SECTION00054500000000000000">
11294.4.5 What are the SSL logging features, and how do I activate them?</A>
1130</H3>
1131
1132<P>
1133Note: you do <B>not</B> need to compile SSL support into mod_log_sql
1134in order to simply use it with a secure site. You only need to compile
1135SSL support into mod_log_sql if you want to log SSL-specific data
1136such as the cipher type used, or the keysize that was negotiated.
1137If that information is unimportant to you, you can ignore this FAQ.
1138
1139<P>
1140By adding certain characters to your L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL>
1141string you can tell mod_log_sql to log the SSL cipher, the SSL keysize
1142of the connection, and the maximum keysize that was available. This
1143would let you tell, for example, which clients were using only export-grade
1144security to access your secure software area.
1145
1146<P>
1147You can compile mod_log_sql with SSL logging support if you have
1148the right packages installed. If you already have an SSL-enabled Apache
1149then you by definition have the correct packages already installed:
1150OpenSSL and mod_ssl.
1151
1152<P>
1153You need to ensure that your database is set up to log the SSL data.
1154Issue the following commands to MySQL if your access table does not
1155already have them:
1156
1157<P>
1158
1159<DL COMPACT>
1160<DT>
1161<DD>alter&nbsp;table&nbsp;access_log&nbsp;add&nbsp;column&nbsp;ssl_cipher&nbsp;varchar(25);
1162
1163<P>
1164alter&nbsp;table&nbsp;access_log&nbsp;add&nbsp;column&nbsp;ssl_keysize&nbsp;smallint&nbsp;unsigned;
1165
1166<P>
1167alter&nbsp;table&nbsp;access_log&nbsp;add&nbsp;column&nbsp;ssl_maxkeysize&nbsp;smallint&nbsp;unsigned;
1168</DD>
1169</DL>Finally configure httpd.conf to activate the SSL fields. Note that
1170this is only meaningful in a VirtualHost that is set up for SSL.
1171
1172<P>
1173
1174<DL COMPACT>
1175<DT>
1176<DD>&lt;VirtualHost&nbsp;1.2.3.4:443&gt;&nbsp;
1177
1178<P>
1179&nbsp;LogSQLTransferLogFormat&nbsp;AbHhmRSsTUuvc<B>Qqz</B>&nbsp;
1180
1181<P>
1182&lt;/VirtualHost&gt;
1183</DD>
1184</DL>The last three characters (Qqz) in the directive are the SSL ones;
1185see section <A HREF="node4.html#sub:Frmat">3.6.17</A> in the directives documentation for details
1186of the L<SMALL>OG</SMALL>SQLT<SMALL>RANSFER</SMALL>L<SMALL>OG</SMALL>F<SMALL>ORMAT</SMALL> directive.
1187
1188<P>
1189Restart Apache, then perform some hits on your server. Then run the
1190following select statement:
1191
1192<P>
1193
1194<DL COMPACT>
1195<DT>
1196<DD>mysql&gt;&nbsp;select&nbsp;remote_host,request_uri,ssl_cipher,ssl_keysize,ssl_maxkeysize
1197
1198<P>
1199from&nbsp;access_log&nbsp;where&nbsp;ssl_cipher&nbsp;is&nbsp;not&nbsp;null;
1200
1201<P>
1202</DD>
1203</DL>
1204<DIV ALIGN="CENTER">
1205<TABLE CELLPADDING=3 BORDER="1">
1206<TR><TD ALIGN="LEFT">remote_host</TD>
1207<TD ALIGN="LEFT">request_uri</TD>
1208<TD ALIGN="LEFT">ssl_cipher</TD>
1209<TD ALIGN="LEFT">ssl_keysize</TD>
1210<TD ALIGN="LEFT">ssl_maxkeysize</TD>
1211</TR>
1212<TR><TD ALIGN="LEFT">216.190.52.4</TD>
1213<TD ALIGN="LEFT">/dir/somefile.html</TD>
1214<TD ALIGN="LEFT">RC4-MD5</TD>
1215<TD ALIGN="LEFT">128</TD>
1216<TD ALIGN="LEFT">128</TD>
1217</TR>
1218<TR><TD ALIGN="LEFT">216.190.52.4</TD>
1219<TD ALIGN="LEFT">/dir/somefile.gif</TD>
1220<TD ALIGN="LEFT">RC4-MD5</TD>
1221<TD ALIGN="LEFT">128</TD>
1222<TD ALIGN="LEFT">128</TD>
1223</TR>
1224<TR><TD ALIGN="LEFT">216.190.52.4</TD>
1225<TD ALIGN="LEFT">/dir/somefile.jpg</TD>
1226<TD ALIGN="LEFT">RC4-MD5</TD>
1227<TD ALIGN="LEFT">128</TD>
1228<TD ALIGN="LEFT">128</TD>
1229</TR>
1230</TABLE>
1231</DIV>
1232
1233<P>
1234
1235<DL COMPACT>
1236<DT>
1237<DD>
1238</DD>
1239</DL>
1240<P>
1241<HR>
1242<!--Navigation Panel-->
1243<A NAME="tex2html219"
1244 HREF="node6.html">
1245<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
1246<A NAME="tex2html215"
1247 HREF="documentation.html">
1248<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
1249<A NAME="tex2html209"
1250 HREF="node4.html">
1251<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
1252<A NAME="tex2html217"
1253 HREF="node1.html">
1254<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
1255<BR>
1256<B> Next:</B> <A NAME="tex2html220"
1257 HREF="node6.html">About this document ...</A>
1258<B> Up:</B> <A NAME="tex2html216"
1259 HREF="documentation.html">Installing and Running mod_log_sql</A>
1260<B> Previous:</B> <A NAME="tex2html210"
1261 HREF="node4.html">3 Configuration</A>
1262 &nbsp; <B> <A NAME="tex2html218"
1263 HREF="node1.html">Contents</A></B>
1264<!--End of Navigation Panel-->
1265<ADDRESS>
1266Chris Powell
12672002-12-18
1268</ADDRESS>
1269</BODY>
1270</HTML>
diff --git a/docs/node6.html b/docs/node6.html
new file mode 100644
index 0000000..cefac28
--- /dev/null
+++ b/docs/node6.html
@@ -0,0 +1,74 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2
3<!--Converted with LaTeX2HTML 2002-1 (1.68)
4original version by: Nikos Drakos, CBLU, University of Leeds
5* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6* with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
8<HTML>
9<HEAD>
10<TITLE>About this document ...</TITLE>
11<META NAME="description" CONTENT="About this document ...">
12<META NAME="keywords" CONTENT="documentation">
13<META NAME="resource-type" CONTENT="document">
14<META NAME="distribution" CONTENT="global">
15
16<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17<META NAME="Generator" CONTENT="LaTeX2HTML v2002-1">
18<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
19
20<LINK REL="STYLESHEET" HREF="documentation.css">
21
22<LINK REL="previous" HREF="node5.html">
23<LINK REL="up" HREF="documentation.html">
24</HEAD>
25
26<BODY >
27<!--Navigation Panel-->
28<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next_g.png">
29<A NAME="tex2html251"
30 HREF="documentation.html">
31<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
32<A NAME="tex2html247"
33 HREF="node5.html">
34<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
35<A NAME="tex2html253"
36 HREF="node1.html">
37<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
38<BR>
39<B> Up:</B> <A NAME="tex2html252"
40 HREF="documentation.html">Installing and Running mod_log_sql</A>
41<B> Previous:</B> <A NAME="tex2html248"
42 HREF="node5.html">4 FAQ</A>
43 &nbsp; <B> <A NAME="tex2html254"
44 HREF="node1.html">Contents</A></B>
45<BR>
46<BR>
47<!--End of Navigation Panel-->
48
49<H1><A NAME="SECTION00060000000000000000">
50About this document ...</A>
51</H1>
52 <STRONG>Installing and Running mod_log_sql</STRONG><P>
53This document was generated using the
54<A HREF="http://www.latex2html.org/"><STRONG>LaTeX</STRONG>2<tt>HTML</tt></A> translator Version 2002-1 (1.68)
55<P>
56Copyright &#169; 1993, 1994, 1995, 1996,
57<A HREF="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos Drakos</A>,
58Computer Based Learning Unit, University of Leeds.
59<BR>
60Copyright &#169; 1997, 1998, 1999,
61<A HREF="http://www.maths.mq.edu.au/~ross/">Ross Moore</A>,
62Mathematics Department, Macquarie University, Sydney.
63<P>
64The command line arguments were: <BR>
65 <STRONG>latex2html</STRONG> <TT>-local_icons -show_section_numbers -split 4 -navigation -noindex_in_navigation -contents_in_navigation -dir Documentation/HTML Documentation/documentation.tex</TT>
66<P>
67The translation was initiated by Chris Powell on 2002-12-18
68<BR><HR>
69<ADDRESS>
70Chris Powell
712002-12-18
72</ADDRESS>
73</BODY>
74</HTML>
diff --git a/docs/prev.png b/docs/prev.png
new file mode 100644
index 0000000..e60b8b4
--- /dev/null
+++ b/docs/prev.png
Binary files differ
diff --git a/docs/prev_g.png b/docs/prev_g.png
new file mode 100644
index 0000000..476d956
--- /dev/null
+++ b/docs/prev_g.png
Binary files differ
diff --git a/docs/style_1.css b/docs/style_1.css
new file mode 100644
index 0000000..f12a3af
--- /dev/null
+++ b/docs/style_1.css
@@ -0,0 +1,33 @@
1body {
2 margin-left: 3%;
3 background-color: #ccccFF;
4 font-family: sans-serif;
5}
6
7h1 {
8 text-align: center;
9}
10
11h2 {
12 margin-left: -1%;
13 font-size: 150%;
14}
15
16h3 {
17 margin-left: -1%;
18}
19
20h4 {
21 text-align: center;
22}
23
24p {
25}
26
27pre {
28 font-family: monospace;
29}
30
31DD {
32 font-family: monospace;
33} \ No newline at end of file
diff --git a/docs/up.png b/docs/up.png
new file mode 100644
index 0000000..3937e16
--- /dev/null
+++ b/docs/up.png
Binary files differ
diff --git a/docs/up_g.png b/docs/up_g.png
new file mode 100644
index 0000000..54ceb68
--- /dev/null
+++ b/docs/up_g.png
Binary files differ
diff --git a/index.xml b/index.xml
new file mode 100644
index 0000000..1db68be
--- /dev/null
+++ b/index.xml
@@ -0,0 +1,260 @@
1<?xml version="1.0"?>
2<?xml-stylesheet type="text/xsl" href="../../../../xsl/projects.xsl"?>
3<ooo title="mod_log_sql" path="/projects/apache/mod_log_sql/" osi="on">
4 <section title="Abstract">
5 <content>
6 <div xmlns="http://www.w3.org/1999/xhtml">
7 <p>mod_log_sql is a logging module for Apache 1.3 and 2.0 which logs all requests to a database. This began a port of the Apache 1.3 version of the module by Chris Powell, and as of February 6th, 2004 Chris Powell and I have decided to switch maintainer-ship of the module over to me. <br/>
8This module now compiles under Apache 1.3 and Apache 2.0 from the same source.</p>
9<p>The 1.9x versions are to be considered beta quality, as they contain new features
10 and some major code cleanups. If you are using Apache 1.3 it is recommended that you use
11 mod_log_sql version 1.18. Only use the 1.9x releases if you need the new features they provide.</p>
12 </div>
13 </content>
14 </section>
15
16 <changelog>
17 <entry version="1.101">
18 <content type="docbook">
19 <para>
20 This release adds more documentation of the all the log formats and also adds documentation
21 of the tabletype DBParam for the mysql driver. Using LogSQLDBParam tabletype ARCHIVE will
22 set the tabletype for autocreated tables to ARCHIVE (and save TONS of space too)
23 </para>
24 <para>
25 Segfaulting due to not loading a driver module no longer occurs and an error message is
26 logged to the log file stating that you didn't load the driver module.
27 </para>
28 <para>
29 This release also adds another sub-module that will log incoming and outgoing bytes (logio)
30 This modules is EXCLUSIVE to the mod_logio module. Meaning if you use the mod_log_sql version
31 you must NOT load the standard apache version. Currenlty due to how logging of outgoing bytes
32 is done in the apache core there is NO workaround for this, you either log outgoing bytes
33 in the text access logs OR mod_log_sql.
34 </para>
35 <para>
36 To actually USE the new logging fields you just need to add the "i" and "o" LogSQLLogFormat options.
37 Please note that these are lowercase instead of uppercase like they are in mod_logio.
38 </para>
39 <note>
40 <para>
41 Due to the addition of the logio two new fields are added to the log tables. If you wish to use
42 logging if IO then you MUST alter your existing tables adding fields bytes_in and bytes out of type int unsigned.
43 </para>
44 <programlisting>ALTER TABLE mylogingtable ADD COLUMN bytes_in INT UNSIGNED, ADD COLUMN bytes_out INT UNSIGNED</programlisting>
45 </note>
46 </content>
47 </entry>
48 <entry version="1.100">
49 <content type="docbook">
50 <para>
51 This release adds a new "V" log format which logs the requested hostname into
52 virtual_host instead of the ServerName. This is exclusive to "v", Only one or the other
53 can be used.
54 </para>
55 <para>
56 There are several fixes in the configure system to not error out if an optional library
57 or file is not found. And there are several fixes to the SQL generation code fixing
58 escaping, table names, and NULL values.
59 </para>
60 </content>
61 </entry>
62 <entry version="1.99">
63 <content type="docbook">
64 <para>
65 This release fixes segmentation faults of apache that occured when the preserve file
66 was used. The errors printed to the error log are also more informative. And several
67 autoconf detection routines were fixed.
68 </para>
69 <para>
70 It also adds the dbi provider which works for adding SQL content to postgresql and mysql servers,
71 but does not support the auto creation of tables in either database.
72 The pgsql driver stub is also included, which is no where near completed.
73 </para>
74 <para>
75 For win32 users, the build scripts are included in the distribution now, read the
76 changelog for the 1.98 release for more information. If anyone wishes to contribute a
77 MSVC project file they will be welcomed.
78 </para>
79 </content>
80 </entry>
81 <entry version="1.98">
82 <content type="docbook">
83 <para>
84 Contains a new configuration directives to control the Preserve file,
85 LogSQLDisablePreserve. This option completely disables the preserve
86 file, so if the Database cannot be contacted, those records will be
87 lost and not logged. Also the LogSQLPreserveFile is now relative, if
88 it does not begin with a &quot;/&quot;, to the ServerRoot and defaults
89 to logs/mod_log_sql-preserve. It will appear with your log files now.
90 </para>
91 <para>
92 Also in this release is the much requested Win32 support. I have added 2
93 batch scripts to compile mod_log_sql for apache 1.3 and apache 2.0. You
94 will need to edit the files to setup the include and library paths for
95 compiling. I compiled this with the free Command line compiler provided
96 by Microsoft, Apache 2.0.49 and 1.3.29, Mysql 4.0, and the MS SDK from
97 Microsoft's website. I had to obtain the msvcrt.lib file from a MS VS
98 installation to get the dlls to compile, however. If anybody can
99 contribute a MSVC 6 project or nmake Makefiles I would greatly
100 appreciate it.
101 </para>
102 <note role="important">
103 <simpara>
104 Unfortunately due to the license that the free compiler from Microsoft
105 has I can not distribute binaries for Win32.
106 </simpara>
107 </note>
108 </content>
109 </entry>
110 <entry version="1.97">
111 <content type="docbook">
112 <para>
113 This release has several changes so be sure to read the
114 documentation and Changelog. Changes are a new LogSQLLoginInfo syntax which
115 better allows configuring mod_log_sql with multiple databases.. basic example.
116 </para>
117 <programlisting>mysql://loguser:Mypass@dbhost/apache_log</programlisting>
118 <para>
119 Also the mysql code is not in a separate module that must be loaded after
120 the core mod_log_sql.so, so you will NEED to add this to your httpd.conf
121 file.
122 </para>
123 <programlisting>LoadModule log_sql_mysql_module modules/mod_log_sql_mysql.so</programlisting>
124 </content>
125 </entry>
126 <entry version="1.9.6">
127 <content type="docbook">
128 <para>
129 This release offers a new configuration directive to configure Database
130 configuration options. LogSQLDBParam should be used over LogSQLTcpPort,
131 LogSQLDatabase, and LogSQLSocketFile. as they are deprecated, and will
132 most likely be removed in future versions.
133 </para>
134 </content>
135 </entry>
136 </changelog>
137
138 <section title="Documentation">
139 <content>
140 <div xmlns="http://www.w3.org/1999/xhtml">
141 <a href="docs/">mod_log_sql 1.18 documentation</a><br/>
142 <a href="docs-2.0/">mod_log_sql 2.0 documentation</a>
143 </div>
144 </content>
145 </section>
146
147 <requirements>
148 <title>Prerequisites</title>
149 <software name="MySQL" url="http://www.mysql.com/">
150 <requirement version="3.23.30" type="minimum"/>
151 </software>
152 <software name="libDBI" url="http://libdbi.sourceforge.net/" optional="1">
153 <requirement version="0.7.0" type="minimum"/>
154 </software>
155 <software name="Apache HTTPd" url="http://httpd.apache.org/">
156 <requirement version="2.0.40" type="minimum"/>
157 <requirement version="1.3.20" type="minimum"/>
158 </software>
159 </requirements>
160
161 <downloads
162 name="mod_log_sql"
163 baseref="/downloads/mod_log_sql/">
164 <category branch="development" latest="1.99" extension="tar.gz">
165 <download version="1.101" extension="tar.bz2" md5sum="16157f311eba364d8ee467078e7cc086"/>
166 <download version="1.100" extension="tar.bz2" md5sum="b54657ad270cffc34dfab12302c53306"/>
167 <download version="1.99" md5sum="e246a3d8e96d2d62715eb34f75c7c11d">
168 <patch shortname="config Patch" version="1.99" extension="diff">
169 This patch stops configure from erroring out if libdbi is not detected
170 on the system.
171 </patch>
172 <patch shortname="config Patch" version="1.99-2" extension="diff">
173 This patch fixes loggin request_args(a) and fixes the MySQL reconnect segfault.
174 </patch>
175 </download>
176 <download version="1.98" md5sum="122a7f8a42876ff8ab0d1369dfe4d201"/>
177 <download version="1.97" md5sum="6e5616dbb6eec5e1acd2d3fd8b42e5be">
178 <patch shortname="config Patch" version="1.97" extension="diff">
179 This patch fixes a compile issues with certain builds of Apache 2 which
180 generate the &quot;PACKAGE_NAME&quot; redefined error.
181 </patch>
182 </download>
183 <download version="1.96" md5sum="3212f333fc29d013d0b6d9f7dd477fa2"/>
184 <download version="1.95" md5sum="fcbacbac6e180e9ec46631b181ba12d9"/>
185 <download version="1.94" md5sum="0a6d403f29ec00cf10dbeb282b85c49c"/>
186 <download version="1.93" md5sum="5314a79fd78b9014cc1952b873168e8f"/>
187 <download version="1.92" md5sum="5f8c17fd6f7bda1c2dc8513b747e7468"/>
188 <download name="mod-log-sql" version="1.91" md5sum="a5da1e34368e74848a9464cb45094bcc"/>
189 <download name="mod-log-sql" version="1.90" md5sum="f9dc3814f375f6a36a32cb2ebc69c11e"/>
190 </category>
191 <category branch="stable">
192 <title>Historic version 1.18 (Last stable release for Apache 1.3 only)</title>
193 <download extension="tar.bz2" version="1.18" md5sum="27a83f0555a53353ab1a7adf8c4b25ad"/>
194 </category>
195 <category>
196 <title>Repositories</title>
197 <repository
198 type="svn"
199 name="mod_log_sql"
200 baseref="http://svn.outoforder.cc/"
201 view="chora"/>
202 </category>
203 </downloads>
204
205 <section title="Unofficial Binaries" position="bottom">
206 <content>
207 <div xmlns="http://www.w3.org/1999/xhtml">
208 <h4>Debian</h4>
209 <p>
210 Thanks to Thomas Goirand, Debian users can add the following repository to
211 their /etc/apt/sources.list if using stable branch of Debian (mod_log_sql 1.18 only):</p>
212
213 <p><code>deb ftp://ftp.gplhost.com/debian stable main</code></p>
214 <p>This repository also includes the following packages: dtc, qmail, ucspi-tcp,mysqmail
215 and checklocalpasswd.</p>
216 <p>The packages can also be downloaded separately for version 1.18 and 1.9x on the
217 <a href="http://www.gplhost.com/?rub=softwares&amp;sousrub=logsql">GPLHost website.</a>
218 <p><b>NOTE:</b> Please direct any issues with these binary releases to Thomas Goirand (links on
219 the his website), or to the mod_log_sql mailing list.</p>
220 </p>
221 </div>
222 <div xmlns="http://www.w3.org/1999/xhtml">
223 <h4>Win32</h4>
224 <p>There are no win32 binaries provided by anyone at this time. If you wish to build them
225 there is a build.bat provided in the source distribution to build with MySQL and Apache 1.3.x and
226 Apache 2.0.x. However, remember that win32 is an unsupported platform for running mod_log_sql.</p>
227 </div>
228 </content>
229 </section>
230
231 <mailinglists spam="warning">
232 <content type="docbook">
233 <para>
234 There are two mailing lists for mod_log_sql. The first is the generic announcement mailing list which
235 provides announcements for all software releases on OutOfOrder.cc, but can be filtered by
236 choosing topics in the mailing list options page. The second is the user mailing list specific to
237 mod_log_sql only. Release announcements will be cross posted to both lists.
238 </para>
239 </content>
240 <list>
241 <mailinglist name="announce" type="mailman" host="lists.outoforder.cc"/>
242 <mailinglist name="mod_log_sql" type="mailman" host="lists.outoforder.cc"/>
243 </list>
244 </mailinglists>
245
246 <section position="bottom">
247 <title>Contact &amp; Help</title>
248 <content type="docbook">
249 <para>
250 E-Mail me, <ulink url="/email/?Alias=Edward+Rudd&amp;Subject=mod_log_sql">Edward Rudd</ulink>, about mod_log_sql.
251 </para>
252 <para>
253 Send an e-mail to the <link linkend="mailinglist">mod_log_sql mailing list</link>.
254 </para>
255 <para>
256 Bugs should be reported to the <ulink url="http://bugs.outoforder.cc">OutOfOrder.cc Bug Tracker</ulink>.
257 </para>
258 </content>
259 </section>
260</ooo>
generated by cgit v0.9.2 at 2024-04-16 17:26:53 (GMT)