summaryrefslogtreecommitdiffstatsabout
path: root/docs
diff options
context:
space:
mode:
authorEdward Rudd <urkle@outoforder.cc>2004-05-12 23:31:12 (GMT)
committer Edward Rudd <urkle@outoforder.cc>2004-05-12 23:31:12 (GMT)
commit360b6956ce9ecba3d671cf579f38aa5bcfbb657c (patch)
tree5769d75c980b3e02d2a670dfe0fc187f9a17c865 /docs
parenta5763701ea0d1a256c85861c0412c49b383bcc5a (diff)
renamed directory Documentation to docs
updated configure and makefile to use new m4 files
Diffstat (limited to 'docs')
-rw-r--r--docs/.cvsignore3
-rw-r--r--docs/Makefile.in84
-rw-r--r--docs/README7
-rw-r--r--docs/documentation.lyx7202
-rw-r--r--docs/manual.xml1865
5 files changed, 9161 insertions, 0 deletions
diff --git a/docs/.cvsignore b/docs/.cvsignore
new file mode 100644
index 0000000..73cd04a
--- /dev/null
+++ b/docs/.cvsignore
@@ -0,0 +1,3 @@
1Makefile
2manual.html
3manual.pdf
diff --git a/docs/Makefile.in b/docs/Makefile.in
new file mode 100644
index 0000000..81f2298
--- /dev/null
+++ b/docs/Makefile.in
@@ -0,0 +1,84 @@
1# @configure_input@
2
3# Modify these top variables.
4SUBDIRS =
5
6EXTRA_DIST = README \
7 manual.xml \
8 manual.html
9
10#Don't modify anything below here
11
12srcdir = @abs_srcdir@
13builddir = @abs_builddir@
14
15STD_DIST = Makefile.in
16
17DISTFILES = $(STD_DIST) $(EXTRA_DIST)
18
19all: all-subdirs
20
21%.html: %.xml
22 @xmlto html-nochunks $<
23
24%.pdf: %.xml
25 @xmlto pdf $<
26
27all-subdirs install-subdirs update-subdirs clean-subdirs distclean-subdirs:
28 @otarget=`echo $@|sed s/-subdirs//`; \
29 list=' $(SUBDIRS)'; \
30 for i in $$list; do \
31 if test -d "$$i"; then \
32 target="$$otarget"; \
33 echo "Making $$target in $$i"; \
34 if test "$$i" = "."; then \
35 made_local=yes; \
36 target="local-$$target"; \
37 fi; \
38 (cd $$i && $(MAKE) $$target) || exit 1; \
39 fi; \
40 done; \
41
42include:
43 rm -rf include
44 ln -s @APACHE_INCDIR@ include
45
46install: install-subdirs
47
48update: update-subdirs
49
50clean: clean-subdirs
51
52distclean: clean distclean-subdirs
53 $(RM) Makefile
54
55DESTDIR = @PACKAGE_NAME@-@PACKAGE_VERSION@
56DESTTGZ = $(DESTDIR).tar.gz
57dist:
58 @rm -rf $(DESTDIR); \
59 list=' $(SUBDIRS)'; \
60 for i in $$list; do \
61 if test -d "$$i"; then \
62 target=local-dist; \
63 echo "Making $$target in $$i"; \
64 if test "$$i" = "."; then \
65 made_local=yes; \
66 target="local-dist"; \
67 fi; \
68 NEWDESTDIR=$(builddir)/$(DESTDIR)/$$i; \
69 echo $(NEWDESTDIR); \
70 (cd $$i && $(MAKE) DESTDIR=$(builddir)/$(DESTDIR)/$$i $$target) || exit 1; \
71 fi; \
72 done;
73 if test "$$made_local" != "yes"; then \
74 $(MAKE) "local-dist" || exit 1; \
75 fi
76 tar -zcf $(DESTTGZ) $(DESTDIR)
77 rm -rf $(DESTDIR)
78
79local-dist: $(DISTFILES)
80 mkdir -p $(DESTDIR)
81 cp -dp --parents $(DISTFILES) $(DESTDIR)
82
83.PHONY: include all-subdirs update-subdirs install-subdirs \
84 clean-subdirs distclean-subdirs dist
diff --git a/docs/README b/docs/README
new file mode 100644
index 0000000..dd40351
--- /dev/null
+++ b/docs/README
@@ -0,0 +1,7 @@
1The "original" document is the Docbook file "manual.xml" -- all other
2files here are derived from it.
3
4To read the HTML docs, open manual.html in your browser.
5
6To generate other formats of the documentation use xmlto or your favorite
7xslt docbook converter to convert the xml file.
diff --git a/docs/documentation.lyx b/docs/documentation.lyx
new file mode 100644
index 0000000..eeb6af5
--- /dev/null
+++ b/docs/documentation.lyx
@@ -0,0 +1,7202 @@
1#LyX 1.3 created this file. For more info see http://www.lyx.org/
2\lyxformat 221
3\textclass article
4\language english
5\inputencoding default
6\fontscheme default
7\graphics default
8\float_placement !htbp
9\paperfontsize 10
10\spacing single
11\papersize letterpaper
12\paperpackage a4
13\use_geometry 1
14\use_amsmath 0
15\use_natbib 0
16\use_numerical_citations 0
17\paperorientation portrait
18\leftmargin 1in
19\topmargin 0.5in
20\rightmargin 1in
21\bottommargin 0.65in
22\secnumdepth 3
23\tocdepth 3
24\paragraph_separation indent
25\defskip medskip
26\quotes_language english
27\quotes_times 2
28\papercolumns 1
29\papersides 1
30\paperpagestyle default
31
32\layout Title
33\added_space_top vfill \added_space_bottom vfill
34Installing and Running mod_log_sql
35\layout Author
36
37Christopher Powell, <chris@grubbybaby.com>
38\layout Standard
39\pagebreak_bottom
40
41\begin_inset LatexCommand \tableofcontents{}
42
43\end_inset
44
45
46\layout Section
47
48Introduction
49\layout Subsection
50
51Homepage
52\layout LyX-Code
53
54http://www.grubbybaby.com/mod_log_sql/
55\layout Subsection
56
57Summary
58\layout Standard
59
60This Apache module will permit you to log to a SQL database; it can log
61 each access request as well as data associated with each request: cookies,
62 notes, and inbound/outbound headers.
63 Unlike logging to a flat text file -- which is standard in Apache -- a
64 SQL-based log exhibits tremendous flexibility and power of data extraction.
65 (See section
66\begin_inset LatexCommand \ref{sub:why}
67
68\end_inset
69
70 in the FAQ for further discussion and examples of the advantages to SQL.)
71\layout Standard
72
73This module can either replace or happily coexist with mod_log_config, Apache's
74 text file logging facility.
75 In addition to being more configurable than the standard module, mod_log_sql
76 is much more flexible.
77\layout Subsection
78
79Approach
80\layout Standard
81
82This project was formerly known as
83\begin_inset Quotes eld
84\end_inset
85
86mod_log_mysql.
87\begin_inset Quotes erd
88\end_inset
89
90 It was renamed
91\begin_inset Quotes eld
92\end_inset
93
94mod_log_sql
95\begin_inset Quotes erd
96\end_inset
97
98 in order to reflect the project goal of database-inspecificity.
99 The module currently supports MySQL, but support for other database backends
100 is underway.
101\layout Standard
102
103In order to save speed and overhead, links are kept alive in between queries.
104 This module uses one dedicated SQL link per httpd child, opened by each
105 child process when it is born.
106 Among other things, this means that this module supports logging into only
107 one MySQL server, and for now, also, only one SQL database.
108 But that's a small tradeoff compared to the blinding speed of this module.
109 Error reporting is robust throughout the module and will inform the administrat
110or of database issues in the Apache
111\noun on
112ErrorLog
113\noun default
114 for the server/virtual server.
115\layout Standard
116
117Virtual hosts are supported in the same manner they are in the regular logging
118 modules.
119 The administrator defines some basic 'global' directives in the main server
120 config, then defines more specific 'local' directives inside each VirtualHost
121 stanza.
122\layout Standard
123
124A robust "preserve" capability has now been implemented.
125 This permits the module to preserve any failed INSERT commands to a local
126 file on its machine.
127 In any situation that the database is unavailable -- e.g.
128 the network fails or the database host is rebooted -- mod_log_sql will
129 note this in the error log and begin appending its log entries to the preserve
130 file (which is created with the user & group ID of the running Apache process,
131 e.g.
132 "nobody/nobody" on many Linux installations).
133 When database availablity returns, mod_log_sql seamlessly resumes logging
134 to it.
135 When convenient for the sysadmin, he/she can easily import the preserve
136 file into the database because it is simply a series of SQL insert statements.
137\layout Subsection
138
139What gets logged by default?
140\layout Standard
141
142All the data that would be contained in the "Combined Log Format" is logged
143 by default, plus a little extra.
144 Your best bet is to begin by accepting this default, then later customize
145 the log configuration based on your needs.
146\layout Standard
147
148The documentation of the run-time directives includes a full explanation
149 of what you can log, including examples -- see section
150\begin_inset LatexCommand \ref{sec:ConfRef}
151
152\end_inset
153
154.
155\layout Subsection
156
157Miscellaneous Notes
158\layout Itemize
159
160Note which directives go in the 'main server config' and which directives
161 apply to the 'virtual host config'.
162 This is made clear in the directive documentation.
163\layout Itemize
164
165The 'time_stamp' field is stored in an UNSIGNED INTEGER format, in the standard
166 unix
167\begin_inset Quotes eld
168\end_inset
169
170seconds since the epoch
171\begin_inset Quotes erd
172\end_inset
173
174 format.
175 This is superior to storing the access time as a string due to size requirement
176s: an UNSIGNED INT requires 4 bytes, whereas an Apache date string (e.g.
177 "18/Nov/2001:13:59:52 -0800") requires 26 bytes: those extra 22 bytes become
178 significant when multiplied by thousands of accesses on a busy server.
179 Besides, an INT type is far more flexible for comparisons, etc.
180\begin_deeper
181\layout Standard
182
183In MySQL 3.21 and above you can easily convert this to a human readable format
184 using from_unixtime(), e.g.:
185\layout LyX-Code
186
187select remote_host,request_uri,from_unixtime(time_stamp) from access_log;
188\layout Standard
189
190The enclosed perl program
191\begin_inset Quotes eld
192\end_inset
193
194make_combined_log.pl
195\begin_inset Quotes srd
196\end_inset
197
198 extracts your access log in a format that is completely compatible with
199 the Combined Log Format.
200 You can then feed this to your favorite web log analysis tool.
201\end_deeper
202\layout Itemize
203
204The table's string values can be CHAR or VARCHAR, at a length of your choice.
205 VARCHAR is superior because it truncates long strings; CHAR types are fixed-len
206gth and will be padded with spaces, resulting in waste.
207 Just like the time_stamp issue described above, that kind of space waste
208 multiplies over thousands of records.
209\layout Itemize
210
211Be careful not to go overboard setting fields to NOT NULL.
212 If a field is marked NOT NULL then it must contain data in the INSERT statement
213, or the INSERT will fail.
214 These mysterious failures can be quite frustrating and difficult to debug.
215\layout Itemize
216
217When Apache logs a numeric field, it uses a '-' character to mean
218\begin_inset Quotes eld
219\end_inset
220
221not applicable,
222\begin_inset Quotes erd
223\end_inset
224
225 e.g.
226 the number of bytes returned on a 304 (unchanged) request.
227 Since '-' is an illegal character in an SQL numeric field, such fields
228 are assigned the value 0 instead of '-' which, of course, makes perfect
229 sense anyway.
230\layout Subsection
231
232Author / Maintainer
233\layout Standard
234
235The actual logging code was taken from the already existing flat file text
236 modules, so all that credit goes to the Apache Server group.
237\layout Standard
238
239The MySQL routines and directives were added by Zeev Suraski <bourbon@netvision.n
240et.il>.
241\layout Standard
242
243All changes from 1.06+ and the new documentation were added by Chris Powell
244 <chris@grubbybaby.com>.
245 It seems that the module had fallen into the "unmaintained" category --
246 it hadn't been updated since 1998 -- so Chris adopted it as the new maintainer.
247\layout Section
248
249Installation
250\layout Subsection
251
252Requirements
253\layout Itemize
254
255A compatible system.
256 mod_log_sql was authored and tested on systems based on Red Hat Linux (Red
257 Hat, Mandrake), but the module should easily adapt to any modern distribution.
258 mod_log_sql has also been ported successfully to Solaris and FreeBSD.
259\layout Itemize
260
261Apache 1.2 or 1.3.
262 Ideally you should already have successfully compiled Apache and understand
263 the process, but this document tries to make it simple for beginners.
264\layout Itemize
265
266The MySQL development headers.
267 This package is called different things on different distros.
268 For example, Red Hat 6.x calls this RPM
269\begin_inset Quotes eld
270\end_inset
271
272MySQL-devel
273\begin_inset Quotes erd
274\end_inset
275
276 whereas Mandrake calls it
277\begin_inset Quotes eld
278\end_inset
279
280libmysql10-devel.
281\begin_inset Quotes erd
282\end_inset
283
284
285\layout Itemize
286
287MySQL >= 3.23.15 configured, installed and running on either localhost or
288 an accessible networked machine.
289 You should already have a basic understanding of MySQL and how it functions.
290\layout Itemize
291
292Optionally, if you want to be able to log SSL information such as keysize
293 or cipher, you need OpenSSL and mod_ssl installed.
294\layout Subsection
295
296Platform-specific notes
297\layout Standard
298
299These installation documents assume a relatively modern GNU/Linux scenario.
300 mod_log_sql has been ported to other platforms; following are notes on
301 compiling the module for those platforms.
302\layout Subsubsection
303
304
305\begin_inset LatexCommand \label{sub:Solaris}
306
307\end_inset
308
309Solaris
310\layout Standard
311
312The nanosleep() function used in mod_log_sql relies on linking aginst the
313 librt library.
314 Make the following alterations before proceeding:
315\layout Enumerate
316
317In Makefile, search for the string
318\begin_inset Quotes eld
319\end_inset
320
321-lmysqlclient -lz
322\begin_inset Quotes erd
323\end_inset
324
325 and change it to read
326\begin_inset Quotes eld
327\end_inset
328
329-lmysqlclient -lz -lrt
330\begin_inset Quotes erd
331\end_inset
332
333
334\layout Enumerate
335
336In part
337\begin_inset LatexCommand \ref{step:Linking}
338
339\end_inset
340
341 of section
342\begin_inset LatexCommand \ref{sec:Static}
343
344\end_inset
345
346 below, change
347\begin_inset Quotes eld
348\end_inset
349
350-lmysqlclient -lm -lz
351\begin_inset Quotes erd
352\end_inset
353
354 to read
355\begin_inset Quotes eld
356\end_inset
357
358-lmysqlclient -lm -lz -lrt
359\begin_inset Quotes erd
360\end_inset
361
362
363\layout Subsubsection
364
365BSD
366\layout Standard
367
368No notes are available at present, but they are desired.
369 If you have successfully ported mod_log_sql to BSD,
370\emph on
371please
372\emph default
373contact
374\begin_inset LatexCommand \url[the maintaniner, Chris Powell]{(chris@grubbybaby.com)}
375
376\end_inset
377
378 and help fill in this section.
379\layout Subsubsection
380
381Win32
382\layout Standard
383
384No notes are available at present, but they are desired.
385 If you have successfully ported mod_log_sql to Win32,
386\emph on
387please
388\emph default
389contact
390\begin_inset LatexCommand \url[the maintaniner, Chris Powell]{(chris@grubbybaby.com)}
391
392\end_inset
393
394 and help fill in this section.
395\layout Subsubsection
396
397OS X
398\layout Standard
399
400mod_log_sql should compile and work out-of-the-box on this platform.
401 Here are some notes from a user successfully running the module on OS X:
402\layout Quote
403
404
405\emph on
406The only changes I had to make were to where I had the various libraries
407 installed.
408\layout Quote
409
410
411\emph on
412Here are the changes I made to the head of the Makefile:
413\layout LyX-Code
414
415APACHESOURCE = /usr/local/src/apache_1.3.27
416\layout Quote
417
418
419\emph on
420(Wasn't sure if this was really needed or not, so I downloaded the Apache
421 source just in case)
422\layout LyX-Code
423
424APACHEINSTALLED = /usr/sbin
425\layout LyX-Code
426
427APACHEHEADERS = /usr/include/httpd
428\layout LyX-Code
429
430APXS = $(APACHEINSTALLED)/apxs
431\layout LyX-Code
432
433MYSQLLIBRARIES = /usr/local/mysql/lib
434\layout LyX-Code
435
436MYSQLHEADERS = /usr/local/mysql/include
437\layout Quote
438
439
440\emph on
441I'm using a binary installation of MySQL and the default apache installation
442 on OS X Client 10.2.3, the locations of these files may vary depending on
443 how you've installed MySQL and will almost certainly be different if you're
444 using OS X Server.
445\layout Standard
446
447My thanks to Tom Wiebe for being the first (to my knowlege) mod_log_sql
448 user on OS X and for providing these notes.
449\layout Subsubsection
450
451Digital Unix
452\layout Standard
453
454Digital Unix, like Solaris, needs to be linked against librt; see section
455
456\begin_inset LatexCommand \ref{sub:Solaris}
457
458\end_inset
459
460.
461 Here are further notes from a user successfully running the module on Digital
462 Unix:
463\layout Quote
464
465
466\emph on
467Instead of trying to get the module to remember where the MySQL libraries
468 were, I instead compiled apache with the information:
469\layout Quote
470
471
472\emph on
473LDFLAGS='-rpath /isp/mysql/lib/mysql' ./configure ...
474\layout Quote
475
476
477\emph on
478Everything worked as expected after that.
479 (The error I got without this was "/sbin/loader: Fatal Error: cannot map
480 libmysqlclient.so" )
481\layout Quote
482
483
484\emph on
485Digital Unix (v4.0f, at least ) appears to follow the same requirements needed
486 by Solaris, so simply adding librt to the module made it compile without
487 errors.
488\layout Quote
489
490
491\emph on
492As for the warnings, here's the text:
493\layout LyX-Code
494
495
496\emph on
497mod_log_sql.c: In function `extract_request_duration':
498\layout LyX-Code
499
500
501\emph on
502mod_log_sql.c:292: warning: long int format, different type arg (arg 4)
503\layout LyX-Code
504
505
506\emph on
507mod_log_sql.c: In function `extract_request_timestamp':
508\layout LyX-Code
509
510
511\emph on
512mod_log_sql.c:497: warning: long int format, different type arg (arg 4)
513\layout Quote
514
515
516\emph on
517Poking around in the code, it looks like the compiler was complaining that
518 what time() is returning doesn't play nicely with %ld by default.
519 I just typecast them as (long)'s and the warnings went away ( not that
520 the module wasn't working correctly without them ).
521\layout Quote
522
523
524\emph on
525The module works very well so far in testing...
526 hasn't dropped a single log entry yet.
527
528\layout Standard
529
530My thanks to Jim Turner for permitting me to quote him here, and for being
531 the first known user of mod_log_sql on Digital Unix.
532\layout Subsection
533
534Do I want a DSO or a static module?
535\layout Standard
536
537You need to know the answer to this question before you proceed.
538 The answer is pretty straightforward: what have you done in the past? If
539 you like all your Apache modules to be dynamic, then you should keep doing
540 that.
541 If you're more of an old-school type and prefer to compile the modules
542 right into apache, do that.
543 Both methods work equally well.
544\layout Standard
545
546FWIW, the DSO method is more modern and increasing in popularity because
547 apxs takes care of a lot of dirty little details for you.
548 As you'll see below, the static-module method is a little more complex.
549\layout Subsection
550
551Installation as an Apache DSO (Preferred)
552\layout Enumerate
553
554Perform all the following steps as root so that you have install privs,
555 etc.
556 Unpack the archive into a working directory.
557\begin_deeper
558\layout LyX-Code
559
560# tar zxf mod_log_sql.tar.gz -C /usr/local/src
561\layout LyX-Code
562
563# cd /usr/local/src/mod_log_sql
564\end_deeper
565\layout Enumerate
566
567Edit Makefile and change the values of the variables in the first section.
568
569\begin_deeper
570\layout Enumerate
571
572These paths are
573\series bold
574necessary:
575\begin_deeper
576\layout Description
577
578APACHEINSTALLED: the location where you installed Apache -- usually /usr/local/a
579pache, 'locate apxs' can help you find it.
580\layout Description
581
582APACHEHEADERS: The location of your Apache header files, find using 'locate
583 httpd.h'
584\layout Description
585
586MYSQLLIBRARIES: The location of your MySQL libraries, find using 'locate
587 libmysqlclient.so'
588\layout Description
589
590MYSQLHEADERS: The location of your MySQL header files, find using 'locate
591 mysql.h'
592\end_deeper
593\layout Enumerate
594
595
596\series bold
597Optional
598\series default
599: if you compiled mod_ssl for Apache and want to log SSL data such as 'keysize'
600 and 'cipher type':
601\begin_deeper
602\layout Description
603
604MODSSLHEADERS: the location of your mod_ssl header files, find using 'locate
605 mod_ssl.h'
606\layout Description
607
608DB1HEADERS: the location of your db1 header files, find using 'locate ndbm.h'
609\end_deeper
610\layout Standard
611
612You do
613\series bold
614not
615\series default
616need to compile SSL support into mod_log_sql in order to simply use it with
617 a secure site.
618 You only need to compile SSL support into mod_log_sql
619\series bold
620if you want to log SSL-specific data
621\series default
622such as the cipher type.
623\end_deeper
624\layout Enumerate
625
626IMPORTANT: If you are not logging SSL info, comment out MODSSLHDRS by putting
627 a # character in front of it:
628\begin_deeper
629\layout LyX-Code
630
631#MODSSLHDRS=/usr/include/...
632\end_deeper
633\layout Enumerate
634
635Instruct apxs to compile the module as a DSO.
636\begin_deeper
637\layout LyX-Code
638
639# make dso
640\layout Standard
641
642You should see output similar to the following:
643\layout LyX-Code
644
645/usr/local/Apache/bin/apxs -Wc,-O2 -Wc,-Wall -Wc,-DEAPI -c -I/usr/...
646\layout LyX-Code
647
648gcc -DLINUX=22 -DNO_DBM_REWRITEMAP -DMOD_SSL=208111 -DUSE_HS...
649
650\layout LyX-Code
651
652gcc -shared -o mod_log_sql.so mod_log_sql.o -Wc,-O2 -Wc,-Wall -Wc...
653\layout Standard
654
655You should see no errors and have a new file called "mod_log_sql.so" in your
656 directory.
657\end_deeper
658\layout Enumerate
659
660Instruct apxs to install the DSO.
661\begin_deeper
662\layout LyX-Code
663
664# make dsoinstall
665\layout Standard
666
667You should see output similar to the following:
668\layout LyX-Code
669
670/usr/local/Apache/bin/apxs -i mod_log_sql.so
671\layout LyX-Code
672
673cp mod_log_sql.so /usr/local/Apache/libexec/mod_log_sql.so
674\layout LyX-Code
675
676chmod 755 /usr/local/Apache/libexec/mod_log_sql.so
677\end_deeper
678\layout Enumerate
679
680Load and activate the module in httpd.conf:
681\begin_deeper
682\layout Enumerate
683
684Insert this line in the same area as other logging modules, e.g.
685 near
686\begin_inset Quotes eld
687\end_inset
688
689LoadModule config_log_module
690\begin_inset Quotes erd
691\end_inset
692
693:
694\begin_deeper
695\layout LyX-Code
696
697LoadModule sql_log_module libexec/mod_log_sql.so
698\end_deeper
699\layout Enumerate
700
701Insert this line in the same area as other logging modules, e.g.
702 near
703\begin_inset Quotes eld
704\end_inset
705
706AddModule mod_log_config.c
707\begin_inset Quotes erd
708\end_inset
709
710:
711\begin_deeper
712\layout LyX-Code
713
714AddModule mod_log_sql.c
715\end_deeper
716\end_deeper
717\layout Enumerate
718
719Module ordering within httpd.conf is important if you are logging SSL information.
720 Please ensure that
721\begin_deeper
722\layout LyX-Code
723
724LoadModule ssl_module libexec/libssl.so
725\layout Standard
726
727comes before
728\layout LyX-Code
729
730LoadModule sql_log_module libexec/mod_log_sql.so
731\layout Standard
732
733in your httpd.conf file.
734 If they are out of order, simply cut-and-paste the
735\begin_inset Quotes eld
736\end_inset
737
738ssl_module
739\begin_inset Quotes erd
740\end_inset
741
742 section so that it is at the top.
743 If you do not, you will get this error when you start Apache:
744\layout LyX-Code
745
746/usr/local/apache/libexec/mod_log_mysql.so: undefined symbol: ssl_var_lookup
747\layout LyX-Code
748
749/usr/local/apache/bin/apachectl startssl: httpd could not be started
750\layout Standard
751
752(mod_log_sql has a dependency on mod_ssl for SSL symbols.
753 If the statements are out of order, mod_log_sql cannot recognize those
754 symbols.)
755\layout Standard
756
757Now skip below to section
758\begin_inset LatexCommand \ref{sec:Configuration}
759
760\end_inset
761
762,
763\series bold
764Configuration
765\series default
766.
767\end_deeper
768\layout Subsection
769
770
771\begin_inset LatexCommand \label{sec:Static}
772
773\end_inset
774
775Installation as a static module compiled into httpd
776\layout Enumerate
777
778Perform all the following steps as root so that you have install privs,
779 etc.
780\layout Enumerate
781
782Unpack the archive into a working directory.
783\begin_deeper
784\layout LyX-Code
785
786# tar zxf mod_log_sql.tar.gz -C /usr/local/src
787\layout LyX-Code
788
789# cd /usr/local/src/mod_log_sql
790\end_deeper
791\layout Enumerate
792
793
794\begin_inset LatexCommand \label{step:editMF}
795
796\end_inset
797
798Edit Makefile and change the values of the variables in the first section.
799
800\begin_deeper
801\layout Enumerate
802
803These are
804\series bold
805necessary:
806\begin_deeper
807\layout Description
808
809APACHEINSTALLED: the location where you installed Apache -- usually /usr/local/a
810pache, 'locate apxs' can help you find it.
811\layout Description
812
813APACHESOURCE: the location of your Apache
814\series bold
815sources
816\series default
817, find using 'locate ABOUT_APACHE'
818\layout Description
819
820APACHEHEADERS: the location of your Apache header files, find using 'locate
821 httpd.h'
822\layout Description
823
824MYSQLLIBRARIES: the location of your MySQL libraries, find using 'locate
825 libmysqlclient.so'
826\layout Description
827
828MYSQLHEADERS: the location of your MySQL header files, find using 'locate
829 mysql.h'
830\end_deeper
831\layout Enumerate
832
833
834\series bold
835Optional
836\series default
837: if you compiled mod_ssl for Apache and want to log SSL data such as 'keysize'
838 and 'cipher type':
839\begin_deeper
840\layout Description
841
842MODSSLHEADERS: the location of your mod_ssl header files, find using 'locate
843 mod_ssl.h'
844\layout Description
845
846DB1HEADERS: the location of your db1 header files, find using 'locate ndbm.h'
847\end_deeper
848\layout Standard
849
850You do
851\series bold
852not
853\series default
854need to compile SSL support into mod_log_sql in order to simply use it with
855 a secure site.
856 You only need to compile SSL support into mod_log_sql
857\series bold
858if you want to log SSL-specific data
859\series default
860 such as the cipher type.
861\end_deeper
862\layout Enumerate
863
864IMPORTANT: If you are not logging SSL info, comment out MODSSLHDRS by putting
865 a # character in front of it:
866\begin_deeper
867\layout LyX-Code
868
869#MODSSLHDRS=/usr/include/...
870\end_deeper
871\layout Enumerate
872
873Compile the module.
874\begin_deeper
875\layout LyX-Code
876
877# make static
878\layout Standard
879
880You should see output similar to the following:
881\layout LyX-Code
882
883gcc -fpic -O2 -Wall -I/usr/local/Apache/include -I/usr/include/mysql -I/usr/lo...
884\layout Standard
885
886You should see no errors and have a new file called "mod_log_sql.o" in your
887 directory.
888\end_deeper
889\layout Enumerate
890
891Install the module.
892\begin_deeper
893\layout LyX-Code
894
895# make statinstall
896\end_deeper
897\layout Enumerate
898
899Change to your Apache source directory.
900\begin_deeper
901\layout LyX-Code
902
903# cd /usr/local/src/apache-1.3.22/src
904\end_deeper
905\layout Enumerate
906
907Re-compile your httpd binary as follows.
908\begin_deeper
909\layout Enumerate
910
911
912\begin_inset LatexCommand \label{step:Linking}
913
914\end_inset
915
916Make these changes to Configuration.apaci:
917\begin_deeper
918\layout Itemize
919
920Append the following string to the EXTRA_LIBS= line.
921 ("/usr/lib/mysql" is from step
922\begin_inset LatexCommand \ref{step:editMF}
923
924\end_inset
925
926, and is where your MySQL libraries live):
927\layout LyX-Code
928
929-L/usr/lib/mysql -lmysqlclient -lm -lz
930\layout Itemize
931
932Find the mod_log_config.o line, and insert this line immediately after it:
933\layout LyX-Code
934
935AddModule modules/sql/mod_log_sql.o
936\end_deeper
937\layout Enumerate
938
939# cp Configuration.apaci Configuration
940\layout Enumerate
941
942# ./Configure
943\layout Enumerate
944
945# make
946\layout Enumerate
947
948# strip httpd
949\end_deeper
950\layout Enumerate
951
952Test your new apache binary:
953\begin_deeper
954\layout LyX-Code
955
956# ./httpd -l
957\layout Standard
958
959You should see something like:
960\layout LyX-Code
961
962Compiled-in modules:
963\layout LyX-Code
964
965http_core.c
966\layout LyX-Code
967
968mod_log_sql.c <-- That's the line you're looking for.
969\layout LyX-Code
970
971mod_env.c
972\layout LyX-Code
973
974mod_log_config.c
975\layout LyX-Code
976
977mod_mime.c
978\layout LyX-Code
979
980mod_negotiation.c
981\layout LyX-Code
982
983etc...
984\end_deeper
985\layout Enumerate
986
987Install your httpd binary.
988 Copy it over your old httpd binary, wherever it lives.
989 You can and should rename your old httpd first so that you can easily revert
990 to that working version in case of bugs with the new version.
991\begin_deeper
992\layout LyX-Code
993
994# /etc/rc.d/init.d/httpd stop
995\layout LyX-Code
996
997# mv /usr/local/Apache/bin/httpd ~/httpd-save
998\layout LyX-Code
999
1000# cp -f ./httpd /usr/local/Apache/bin/
1001\end_deeper
1002\layout Section
1003
1004
1005\begin_inset LatexCommand \label{sec:Configuration}
1006
1007\end_inset
1008
1009Configuration
1010\layout Subsection
1011
1012
1013\begin_inset LatexCommand \label{sub:PrepDb}
1014
1015\end_inset
1016
1017Preparing MySQL for logging
1018\layout Standard
1019
1020You have to prepare the database to receive data from mod_log_sql, and set
1021 up run-time directives in httpd.conf to control how and what mod_log_sql
1022 logs.
1023\layout Standard
1024
1025This section will discuss how to get started with a basic config.
1026 Full documentation of all available run-time directives is available in
1027 section
1028\begin_inset LatexCommand \ref{sec:ConfRef}
1029
1030\end_inset
1031
1032.
1033\layout Enumerate
1034
1035mod_log_sql can make its own tables on-the-fly, or you can pre-make the
1036 tables by hand.
1037 The advantage of letting the module make the tables is ease-of-use, but
1038 for raw performance you will want to pre-make the tables in order to save
1039 some overhead.
1040 In this basic setup we'll just let the module create tables for us.
1041\layout Enumerate
1042
1043We still need to have a logging database created and ready, so run the MySQL
1044 command line client and create a database:
1045\begin_deeper
1046\layout LyX-Code
1047
1048# mysql -uadmin -pmypassword
1049\layout LyX-Code
1050
1051Enter password:
1052\layout LyX-Code
1053
1054mysql> create database apachelogs;
1055\end_deeper
1056\layout Enumerate
1057
1058
1059\begin_inset LatexCommand \label{part:CrTbl}
1060
1061\end_inset
1062
1063If you want to hand-create the tables, run the enclosed 'create-tables'
1064 SQL script as follows (
1065\begin_inset Quotes eld
1066\end_inset
1067
1068create_tables.sql
1069\begin_inset Quotes erd
1070\end_inset
1071
1072 needs to be in your current working directory).
1073\begin_deeper
1074\layout LyX-Code
1075
1076mysql> use apachelogs
1077\layout LyX-Code
1078
1079Database changed
1080\layout LyX-Code
1081
1082mysql> source create_tables.sql
1083\end_deeper
1084\layout Enumerate
1085
1086Create a specific MySQL userid that httpd will use to authenticate and enter
1087 data.
1088 This userid need not be an actual Unix user.
1089 It is a userid internal to MySQL with specific privileges.
1090 In the following example command, "apachelogs" is the database, "loguser"
1091 is the userid to create, "my.apachemachine.com" is the name of the Apache
1092 machine, and "l0gger" is the password to assign.
1093 Choose values that are different from these examples.
1094\begin_deeper
1095\layout LyX-Code
1096
1097mysql> grant insert,create on apachelogs.* to loguser@my.apachemachine.com
1098 identified by 'l0gger';
1099\end_deeper
1100\layout Enumerate
1101
1102You may be especially security-paranoid and want "loguser" to
1103\emph on
1104not
1105\emph default
1106have "create" capability within the "apachelogs" database.
1107 You can disable that privilege, but the cost is that you will not be able
1108 to use the module's on-the-fly table creation feature.
1109 If that cost is acceptable, hand-create the tables as described in step
1110
1111\begin_inset LatexCommand \ref{part:CrTbl}
1112
1113\end_inset
1114
1115 and use the following GRANT statement instead of the one above:
1116\begin_deeper
1117\layout LyX-Code
1118
1119mysql> grant insert on apachelogs.* to loguser@my.apachemachine.com
1120\layout LyX-Code
1121
1122identified by 'l0gger';
1123\end_deeper
1124\layout Enumerate
1125
1126
1127\begin_inset LatexCommand \label{step:EnaLog}
1128
1129\end_inset
1130
1131Enable full logging of your MySQL daemon (at least temporarily for debugging
1132 purposes) if you don't do this already.
1133 Edit /etc/my.cnf and add the following line to your [mysqld] section:
1134\begin_deeper
1135\layout LyX-Code
1136
1137log=/var/log/mysql-messages
1138\layout Standard
1139
1140Then restart MySQL.
1141\layout LyX-Code
1142
1143# /etc/rc.d/init.d/mysql restart
1144\end_deeper
1145\layout Subsection
1146
1147A very basic logging setup in Apache
1148\layout Enumerate
1149
1150Tell the module what database to use and the appropriate authentication
1151 information.
1152\begin_deeper
1153\layout Standard
1154
1155So, edit httpd.conf and insert the following lines somewhere after any LoadModule
1156 / AddModule statements.
1157
1158\emph on
1159Make sure these statements are
1160\begin_inset Quotes eld
1161\end_inset
1162
1163global,
1164\begin_inset Quotes erd
1165\end_inset
1166
1167 i.e.
1168 not inside any VirtualHost stanza
1169\emph default
1170.
1171 You will also note that you are embedding a password in the file.
1172 Therefore you are advised to
1173\begin_inset Quotes eld
1174\end_inset
1175
1176chmod 660 httpd.conf
1177\begin_inset Quotes erd
1178\end_inset
1179
1180 to prevent unauthorized regular users from viewing your database user and
1181 password.
1182\layout Standard
1183
1184
1185\series bold
1186Example
1187\series default
1188: Use the MySQL database called "apachelogs" running on "dbmachine.foo.com".
1189 Use username "loguser" and password "l0gg3r" to authenticate to the database.
1190 Permit the module create tables for us.
1191\layout LyX-Code
1192
1193LogSQLLoginInfo dbmachine.foo.com loguser l0gg3r
1194\layout LyX-Code
1195
1196LogSQLDatabase apachelogs
1197\layout LyX-Code
1198
1199LogSQLCreateTables on
1200\layout Standard
1201
1202If your database resides on localhost instead of another host, specify the
1203 MySQL server's socket file as follows:
1204\layout LyX-Code
1205
1206LogSQLSocketFile /your/path/to/mysql.sock
1207\layout Standard
1208
1209If your database is listening on a port other than 3306, specify the correct
1210 TCP port as follows:
1211\layout LyX-Code
1212
1213LogSQLTCPPort 1234
1214\end_deeper
1215\layout Enumerate
1216
1217The actual logging is set up on a virtual-host-by-host basis.
1218 So, skip down to the virtual host you want to set up.
1219 Instruct this virtual host to log entries to the table
1220\begin_inset Quotes eld
1221\end_inset
1222
1223access_log
1224\begin_inset Quotes srd
1225\end_inset
1226
1227 by inserting a
1228\noun on
1229LogSQLTransferLogTable
1230\noun default
1231 directive.
1232 (The
1233\noun on
1234LogSQLTransferLogTable
1235\noun default
1236 directive is the minimum required to log -- other directives that you'll
1237 learn about later simply tune the module's behavior.)
1238\begin_deeper
1239\layout LyX-Code
1240
1241<VirtualHost 1.2.3.4>
1242\layout LyX-Code
1243
1244 [snip]
1245\layout LyX-Code
1246
1247 LogSQLTransferLogTable access_log
1248\layout LyX-Code
1249
1250 [snip]
1251\layout LyX-Code
1252
1253</VirtualHost>
1254\end_deeper
1255\layout Enumerate
1256
1257Restart apache.
1258\begin_deeper
1259\layout LyX-Code
1260
1261# /etc/rc.d/init.d/httpd stop
1262\layout LyX-Code
1263
1264# /etc/rc.d/init.d/httpd start
1265\end_deeper
1266\layout Subsection
1267
1268Testing the basic setup
1269\layout Enumerate
1270
1271Visit your web site in a browser to trigger some hits, then confirm that
1272 the entries are being successfully logged:
1273\begin_deeper
1274\layout LyX-Code
1275
1276# mysql -hdbmachine.foo.com -umysqladmin -p -e "select * from access_log"
1277 apachelogs
1278\layout LyX-Code
1279
1280Enter password:
1281\layout Standard
1282
1283Several lines of output should follow, corresponding to your hits on the
1284 site.
1285 You now have basic functionality.
1286 Don't disable your regular Apache logs until you feel comfortable that
1287 the database is behaving as you'd like and that things are going well.
1288 If you do not see any entries in the access_log, please consult section
1289
1290\begin_inset LatexCommand \ref{faq:NothingLogged}
1291
1292\end_inset
1293
1294 of the FAQ on how to debug and fix the situation.
1295\end_deeper
1296\layout Enumerate
1297
1298You can now activate the advanced features of mod_log_sql, which are described
1299 in the next section.
1300\layout Subsection
1301
1302How to tune logging with run-time directives
1303\layout Subsubsection
1304
1305Instructing the module what to log
1306\layout Standard
1307
1308The most basic directive for the module is
1309\noun on
1310LogSQLTransferLogFormat
1311\noun default
1312, which tells the module which information to send to the database; logging
1313 to the database will not take place without it.
1314 Place a
1315\noun on
1316LogSQLTransferLogFormat
1317\noun default
1318 directive in the VirtualHost stanza of each virtual host that you want
1319 to activate.
1320\layout Standard
1321
1322After
1323\noun on
1324LogSQLTransferLogFormat
1325\noun default
1326 you supply a string of characters that tell the module what information
1327 to log.
1328 In the configuration directive reference (section
1329\begin_inset LatexCommand \ref{sub:Frmat}
1330
1331\end_inset
1332
1333) there is a table which clearly defines all the possible things to log.
1334 Let's say you want to log only the
1335\begin_inset Quotes eld
1336\end_inset
1337
1338request time,
1339\begin_inset Quotes erd
1340\end_inset
1341
1342 the
1343\begin_inset Quotes eld
1344\end_inset
1345
1346remote host,
1347\begin_inset Quotes erd
1348\end_inset
1349
1350 and the
1351\begin_inset Quotes eld
1352\end_inset
1353
1354request
1355\begin_inset Quotes erd
1356\end_inset
1357
1358; you'd use:
1359\layout LyX-Code
1360
1361LogSQLTransferLogFormat hUS
1362\layout Standard
1363
1364But a more appropriate string to use is
1365\layout LyX-Code
1366
1367LogSQLTransferLogFormat AbHhmRSsTUuv
1368\layout Standard
1369
1370which logs all the information required to be compatible with the Combined
1371 Log Format (CLF).
1372\layout Standard
1373
1374If you don't choose to log everything that is available, that's fine.
1375 Fields in the unused columns in your table will simply contain NULL.
1376\layout Standard
1377
1378Some of the
1379\noun on
1380LogSQLTransferLogFormat
1381\noun default
1382 characters require a little extra configuration:
1383\layout Itemize
1384
1385If you specify 'c' to indicate that you want to log the cookie value, you
1386 must also tell the module which cookie you mean by using
1387\noun on
1388LogSQLWhichCookie
1389\noun default
1390 -- after all, there could be many cookies associated with a given request.
1391 Fail to specify
1392\noun on
1393LogSQLWhichCookie
1394\noun default
1395, and no cookie information at all will be logged.
1396
1397\layout Itemize
1398
1399If you specify 'M' to indicate that you want to log the machine ID, you
1400 must also tell the module this machine's identity using the
1401\noun on
1402LogSQLMachineID
1403\noun default
1404 directive.
1405 Fail to specify
1406\noun on
1407LogSQLMachineID
1408\noun default
1409, and a simple '-' character will be logged in the machine_id column.
1410\layout Subsubsection
1411
1412
1413\begin_inset LatexCommand \label{sub:Ignore}
1414
1415\end_inset
1416
1417Instructing the module what NOT to log using filtering directives
1418\layout Standard
1419
1420One
1421\begin_inset Quotes eld
1422\end_inset
1423
1424accept
1425\begin_inset Quotes erd
1426\end_inset
1427
1428 and two
1429\begin_inset Quotes eld
1430\end_inset
1431
1432ignore
1433\begin_inset Quotes srd
1434\end_inset
1435
1436 directives allow you to fine-tune what the module should not log.
1437 These are very handy for keeping your database as uncluttered as possible
1438 and keeping your statistics free of unneeded numbers.
1439 Think of each one as a gatekeeper.
1440\layout Standard
1441
1442
1443\emph on
1444It is important to remember that each of these three directives is purely
1445 optional.
1446 mod_log_sql's default is to log everything.
1447
1448\layout Standard
1449
1450When a request comes in, the contents of
1451\noun on
1452LogSQLRequestAccept
1453\noun default
1454are evaluated first.
1455 This optional,
1456\begin_inset Quotes eld
1457\end_inset
1458
1459blanket
1460\begin_inset Quotes erd
1461\end_inset
1462
1463 directive lets you specify that only certain things are to be accepted
1464 for logging, and everything else discarded.
1465 Because it is evaluated before
1466\noun on
1467LogSQLRequestIgnore
1468\noun default
1469and
1470\noun on
1471LogSQLRemhostIgnore
1472\noun default
1473it can halt logging before those two filtering directives
1474\begin_inset Quotes eld
1475\end_inset
1476
1477get their chance.
1478\begin_inset Quotes erd
1479\end_inset
1480
1481
1482\layout Standard
1483
1484Once a request makes it past
1485\noun on
1486LogSQLRequestAccept
1487\noun default
1488, it still can be excluded based on
1489\noun on
1490LogSQLRemhostIgnore
1491\noun default
1492 and
1493\noun on
1494LogSQLRequestIgnore
1495\noun default
1496.
1497 A good way to use
1498\noun on
1499LogSQLRemhostIgnore
1500\noun default
1501 is to prevent the module from logging the traffic that your internal hosts
1502 generate.
1503
1504\noun on
1505LogSQLRequestIgnore
1506\noun default
1507 is great for preventing things like requests for
1508\begin_inset Quotes eld
1509\end_inset
1510
1511favicon.ico
1512\begin_inset Quotes erd
1513\end_inset
1514
1515 from cluttering up your database, as well as excluding the various requests
1516 that worms make, etc.
1517\layout Standard
1518
1519You can specify a series of strings after each directive.
1520 Do not use any type of globbing or regular-expression syntax -- each string
1521 is considered a match
1522\emph on
1523 if it is a substring of the larger request or remote-host; the comarison
1524 is case-sensitive.
1525
1526\emph default
1527 This means that
1528\noun on
1529
1530\begin_inset Quotes eld
1531\end_inset
1532
1533LogSQLRemhostIgnore
1534\noun default
1535 micro
1536\begin_inset Quotes erd
1537\end_inset
1538
1539 will ignore requests from
1540\begin_inset Quotes eld
1541\end_inset
1542
1543microsoft.com,
1544\begin_inset Quotes erd
1545\end_inset
1546
1547
1548\begin_inset Quotes eld
1549\end_inset
1550
1551microworld.net,
1552\begin_inset Quotes erd
1553\end_inset
1554
1555
1556\begin_inset Quotes eld
1557\end_inset
1558
1559mymicroscope.org,
1560\begin_inset Quotes erd
1561\end_inset
1562
1563 etc.
1564
1565\begin_inset Quotes eld
1566\end_inset
1567
1568
1569\noun on
1570LogSQLRequestIgnore
1571\noun default
1572 gif
1573\begin_inset Quotes erd
1574\end_inset
1575
1576 will instruct the module to ignore requests for
1577\begin_inset Quotes eld
1578\end_inset
1579
1580leftbar.gif,
1581\begin_inset Quotes erd
1582\end_inset
1583
1584
1585\begin_inset Quotes eld
1586\end_inset
1587
1588bluedot.gif
1589\begin_inset Quotes erd
1590\end_inset
1591
1592 and even
1593\begin_inset Quotes eld
1594\end_inset
1595
1596giftwrap.jpg
1597\begin_inset Quotes erd
1598\end_inset
1599
1600 -- but
1601\begin_inset Quotes eld
1602\end_inset
1603
1604RED.GIF
1605\begin_inset Quotes erd
1606\end_inset
1607
1608 and
1609\begin_inset Quotes eld
1610\end_inset
1611
1612Tree.Gif
1613\begin_inset Quotes erd
1614\end_inset
1615
1616 would still get logged because of case sensitivity.
1617\layout Standard
1618
1619A summary of the decision flow:
1620\layout Enumerate
1621
1622If
1623\noun on
1624LogSQLRequestAccept
1625\noun default
1626 exists and a request does not match anything in that list, it is discarded.
1627\layout Enumerate
1628
1629If a request matches anything in the
1630\noun on
1631LogSQLRequestIgnore
1632\noun default
1633list, it is discarded.
1634\layout Enumerate
1635
1636If a reqiest matches anything in the
1637\noun on
1638LogSQLRemhostIgnore
1639\noun default
1640 list, it is discarded.
1641\layout Enumerate
1642
1643Otherwise the request is logged.
1644\layout Standard
1645
1646This means that you can have a series of directives similar to the following:
1647\layout LyX-Code
1648
1649LogSQLRequestAccept *.html *.gif *.jpg
1650\layout LyX-Code
1651
1652LogSQLRequestIgnore statistics.html bluedot.jpg
1653\layout Standard
1654
1655So the first line instructs the module to
1656\series bold
1657only
1658\series default
1659 log files with html, gif and jpg suffixes; requests for
1660\begin_inset Quotes eld
1661\end_inset
1662
1663formail.cgi
1664\begin_inset Quotes erd
1665\end_inset
1666
1667 and
1668\begin_inset Quotes eld
1669\end_inset
1670
1671shopping-cart.pl
1672\begin_inset Quotes erd
1673\end_inset
1674
1675 will never be considered for logging.
1676 (
1677\begin_inset Quotes eld
1678\end_inset
1679
1680LeftArrow.JPG
1681\begin_inset Quotes erd
1682\end_inset
1683
1684 will also never be considered for logging -- remember, the comparison is
1685
1686\series bold
1687case sensitive
1688\series default
1689.) The second line prunes the list further -- you never want to log requests
1690 for those two objects.
1691\layout Standard
1692
1693Tip: if you want to match all the hosts in your domain such as
1694\begin_inset Quotes eld
1695\end_inset
1696
1697host1.corp.foo.com
1698\begin_inset Quotes srd
1699\end_inset
1700
1701 and
1702\begin_inset Quotes eld
1703\end_inset
1704
1705server.dmz.foo.com
1706\begin_inset Quotes srd
1707\end_inset
1708
1709, simply specify:
1710\layout LyX-Code
1711
1712LogSQLRemhostIgnore foo.com
1713\layout Standard
1714
1715Tip: a great way to catch the vast majority of worm-attack requests and
1716 prevent them from being logged is to specify:
1717\layout LyX-Code
1718
1719LogSQLRequestIgnore root.exe cmd.exe default.ida
1720\layout Standard
1721
1722Tip: to prevent the logging of requests for common graphic types, make sure
1723 to put a '.' before the suffix to avoid matches that you didn't intend:
1724\layout LyX-Code
1725
1726LogSQLRequestIgnore .gif .jpg
1727\layout Subsection
1728
1729Advanced logging scenarios
1730\layout Subsubsection
1731
1732Using the module in an ISP environment
1733\layout Standard
1734
1735mod_log_sql has three basic tiers of operation:
1736\layout Enumerate
1737
1738The administrator creates all necessary tables by hand and configures each
1739 Apache VirtualHost by hand.
1740 (
1741\noun on
1742LogSQLCreateTables Off
1743\noun default
1744)
1745\layout Enumerate
1746
1747The module is permitted to create necessary tables on-the-fly, but the administr
1748ator configures each Apache VirtualHost by hand.
1749 (
1750\noun on
1751LogSQLCreateTables On
1752\noun default
1753)
1754\layout Enumerate
1755
1756The module is permitted to create all necessary tables and to make intelligent,
1757 on-the-fly configuration of each VirtualHost.
1758 (
1759\noun on
1760LogSQLMassVirtualHosting On
1761\noun default
1762)
1763\layout Standard
1764
1765Many users are happy to use the module in its most minimal form: they hand-creat
1766e any necessary tables (using
1767\begin_inset Quotes eld
1768\end_inset
1769
1770create_tables.sql
1771\begin_inset Quotes erd
1772\end_inset
1773
1774), and they configure each VirtualHost by hand to suit their needs.
1775 However, some administrators need extra features due to a large and growing
1776 number of VirtualHosts.
1777 The
1778\noun on
1779LogSQLMassVirtualHosting
1780\noun default
1781 directive activates module capabilities that make it far easier to manage
1782 an ISP environment, or any situation characterized by a large and varying
1783 number of virtual servers:
1784\layout Itemize
1785
1786the on-the-fly table creation feature is activated automatically
1787\layout Itemize
1788
1789the transfer log table name is dynamically set from the virtual host's name
1790 (example: a virtual host
1791\begin_inset Quotes eld
1792\end_inset
1793
1794www.grubbybaby.com
1795\begin_inset Quotes erd
1796\end_inset
1797
1798 gets logged to table
1799\begin_inset Quotes eld
1800\end_inset
1801
1802access_www_grubbybaby_com
1803\begin_inset Quotes erd
1804\end_inset
1805
1806)
1807\layout Standard
1808
1809There are numerous benefits.
1810 The admin will not need to create new tables for every new VirtualHost.
1811 (Although the admin will still need to drop the tables of virtual hosts
1812 that are removed.) The admin will not need to set
1813\noun on
1814LogSQLTransferLogTable
1815\noun default
1816 for each virtual host -- it will be configured automatically based on the
1817 host's name.
1818 Because each virtual host will log to its own segregated table, data about
1819 one virtual server will segregate from others; an admin can grant users
1820 access to the tables they need, and they will be unable to view data about
1821 another user's virtual host.
1822\layout Standard
1823
1824In an ISP scenario the admin is likely to have a cluster of many front-end
1825 webservers logging to a back-end database.
1826 mod_log_sql has a feature that permits analysis of how well the web servers
1827 are loadbalancing: the
1828\noun on
1829LogSQLMachineID
1830\noun default
1831 directive.
1832 The administrator uses this directive to assign a unique identifier to
1833 each machine in the web cluster, e.g.
1834
1835\begin_inset Quotes eld
1836\end_inset
1837
1838
1839\noun on
1840LogSQLMachineID
1841\noun default
1842 web01,
1843\begin_inset Quotes erd
1844\end_inset
1845
1846
1847\begin_inset Quotes eld
1848\end_inset
1849
1850
1851\noun on
1852LogSQLMachineID
1853\noun default
1854 web02,
1855\begin_inset Quotes erd
1856\end_inset
1857
1858 etc.
1859 Used in conjunction with the 'M' character in
1860\noun on
1861LogSQLTransferLogFormat
1862\noun default
1863, each entry in the SQL log will include the machine ID of the machine that
1864 created the entry.
1865 This permits the administrator to count the entries made by each particular
1866 machine and thereby analyze the front-end loadbalancing algorithm.
1867\layout Subsubsection
1868
1869
1870\begin_inset LatexCommand \label{secMulTable}
1871
1872\end_inset
1873
1874Logging many-to-one data in separate tables
1875\layout Standard
1876
1877A given HTTP request can have a one-to-many relationship with certain kinds
1878 of data.
1879 For example, a single HTTP request can have 4 cookies, 3 headers and 5
1880
1881\begin_inset Quotes eld
1882\end_inset
1883
1884mod_gzip
1885\begin_inset Quotes erd
1886\end_inset
1887
1888 notes associated with it.
1889 mod_log_sql is capable of logging these relationships due to the elegance
1890 of SQL relational data.
1891\layout Standard
1892
1893You already have a single table containing access requests.
1894 One of the columns in that table is 'id' which is intended to contain the
1895 unique request ID supplied by the standard Apache module mod_unique_id
1896 -- all you need to do is compile in that module and employ the
1897\noun on
1898LogSQLTransferLogFormat
1899\noun default
1900 character 'I'.
1901 Thereafter, each request gets a unique ID that can be thought of as a primary
1902 key within the database, useful for joining multiple tables.
1903 So let's envision several new tables: a notes table, a cookies table, and
1904 a table for inbound and outbound headers.
1905
1906\layout Standard
1907
1908
1909\begin_inset Float table
1910wide false
1911collapsed false
1912
1913\layout Caption
1914
1915
1916\begin_inset LatexCommand \label{tblAcc}
1917
1918\end_inset
1919
1920access_log
1921\layout Standard
1922\align center
1923
1924\begin_inset Tabular
1925<lyxtabular version="3" rows="2" columns="6">
1926<features>
1927<column alignment="left" valignment="top" leftline="true" width="0pt">
1928<column alignment="left" valignment="top" leftline="true" width="0pt">
1929<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
1930<column alignment="left" valignment="top" rightline="true" width="0pt">
1931<column alignment="left" valignment="top" rightline="true" width="0pt">
1932<column alignment="left" valignment="top" rightline="true" width="0pt">
1933<row topline="true" bottomline="true">
1934<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1935\begin_inset Text
1936
1937\layout Standard
1938
1939id
1940\end_inset
1941</cell>
1942<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1943\begin_inset Text
1944
1945\layout Standard
1946
1947remote_host
1948\end_inset
1949</cell>
1950<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1951\begin_inset Text
1952
1953\layout Standard
1954
1955request_uri
1956\end_inset
1957</cell>
1958<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1959\begin_inset Text
1960
1961\layout Standard
1962
1963time_stamp
1964\end_inset
1965</cell>
1966<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1967\begin_inset Text
1968
1969\layout Standard
1970
1971status
1972\end_inset
1973</cell>
1974<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1975\begin_inset Text
1976
1977\layout Standard
1978
1979bytes_sent
1980\end_inset
1981</cell>
1982</row>
1983<row topline="true" bottomline="true">
1984<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1985\begin_inset Text
1986
1987\layout Standard
1988
1989PPIDskBRH30AAGPtAsg
1990\end_inset
1991</cell>
1992<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1993\begin_inset Text
1994
1995\layout Standard
1996
1997zerberus.aiacs.net
1998\end_inset
1999</cell>
2000<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2001\begin_inset Text
2002
2003\layout Standard
2004
2005/mod_log_sql/index.html
2006\end_inset
2007</cell>
2008<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2009\begin_inset Text
2010
2011\layout Standard
2012
20131022493617
2014\end_inset
2015</cell>
2016<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2017\begin_inset Text
2018
2019\layout Standard
2020
2021200
2022\end_inset
2023</cell>
2024<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2025\begin_inset Text
2026
2027\layout Standard
2028
20292215
2030\end_inset
2031</cell>
2032</row>
2033</lyxtabular>
2034
2035\end_inset
2036
2037
2038\end_inset
2039
2040
2041\begin_inset Float table
2042wide false
2043collapsed false
2044
2045\layout Caption
2046
2047
2048\begin_inset LatexCommand \label{tblNotes}
2049
2050\end_inset
2051
2052notes_log
2053\layout Standard
2054\align center
2055
2056\begin_inset Tabular
2057<lyxtabular version="3" rows="3" columns="3">
2058<features>
2059<column alignment="left" valignment="top" leftline="true" width="0pt">
2060<column alignment="left" valignment="top" leftline="true" width="0pt">
2061<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
2062<row topline="true" bottomline="true">
2063<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2064\begin_inset Text
2065
2066\layout Standard
2067
2068id
2069\end_inset
2070</cell>
2071<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2072\begin_inset Text
2073
2074\layout Standard
2075
2076item
2077\end_inset
2078</cell>
2079<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2080\begin_inset Text
2081
2082\layout Standard
2083
2084val
2085\end_inset
2086</cell>
2087</row>
2088<row topline="true">
2089<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2090\begin_inset Text
2091
2092\layout Standard
2093
2094PPIDskBRH30AAGPtAsg
2095\end_inset
2096</cell>
2097<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2098\begin_inset Text
2099
2100\layout Standard
2101
2102mod_gzip_result
2103\end_inset
2104</cell>
2105<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2106\begin_inset Text
2107
2108\layout Standard
2109
2110OK
2111\end_inset
2112</cell>
2113</row>
2114<row topline="true" bottomline="true">
2115<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2116\begin_inset Text
2117
2118\layout Standard
2119
2120PPIDskBRH30AAGPtAsg
2121\end_inset
2122</cell>
2123<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2124\begin_inset Text
2125
2126\layout Standard
2127
2128mod_gzip_compression_ratio
2129\end_inset
2130</cell>
2131<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2132\begin_inset Text
2133
2134\layout Standard
2135
213669
2137\end_inset
2138</cell>
2139</row>
2140</lyxtabular>
2141
2142\end_inset
2143
2144
2145\end_inset
2146
2147
2148\layout Standard
2149
2150
2151\begin_inset Float table
2152wide false
2153collapsed false
2154
2155\layout Caption
2156
2157
2158\begin_inset LatexCommand \label{tblHdr}
2159
2160\end_inset
2161
2162headers_log
2163\layout Standard
2164\align center
2165
2166\begin_inset Tabular
2167<lyxtabular version="3" rows="5" columns="3">
2168<features>
2169<column alignment="left" valignment="top" leftline="true" width="0pt">
2170<column alignment="left" valignment="top" leftline="true" width="0pt">
2171<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
2172<row topline="true" bottomline="true">
2173<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2174\begin_inset Text
2175
2176\layout Standard
2177
2178id
2179\end_inset
2180</cell>
2181<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2182\begin_inset Text
2183
2184\layout Standard
2185
2186item
2187\end_inset
2188</cell>
2189<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2190\begin_inset Text
2191
2192\layout Standard
2193
2194val
2195\end_inset
2196</cell>
2197</row>
2198<row topline="true">
2199<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2200\begin_inset Text
2201
2202\layout Standard
2203
2204PPIDskBRH30AAGPtAsg
2205\end_inset
2206</cell>
2207<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2208\begin_inset Text
2209
2210\layout Standard
2211
2212Content-Type
2213\end_inset
2214</cell>
2215<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2216\begin_inset Text
2217
2218\layout Standard
2219
2220text/html
2221\end_inset
2222</cell>
2223</row>
2224<row topline="true">
2225<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2226\begin_inset Text
2227
2228\layout Standard
2229
2230PPIDskBRH30AAGPtAsg
2231\end_inset
2232</cell>
2233<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2234\begin_inset Text
2235
2236\layout Standard
2237
2238Accept-Encoding
2239\end_inset
2240</cell>
2241<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2242\begin_inset Text
2243
2244\layout Standard
2245
2246gzip, deflate
2247\end_inset
2248</cell>
2249</row>
2250<row topline="true">
2251<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2252\begin_inset Text
2253
2254\layout Standard
2255
2256PPIDskBRH30AAGPtAsg
2257\end_inset
2258</cell>
2259<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2260\begin_inset Text
2261
2262\layout Standard
2263
2264Expires
2265\end_inset
2266</cell>
2267<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2268\begin_inset Text
2269
2270\layout Standard
2271
2272Tue, 28 May 2002 10:00:18 GMT
2273\end_inset
2274</cell>
2275</row>
2276<row topline="true" bottomline="true">
2277<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2278\begin_inset Text
2279
2280\layout Standard
2281
2282PPIDskBRH30AAGPtAsg
2283\end_inset
2284</cell>
2285<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2286\begin_inset Text
2287
2288\layout Standard
2289
2290Cache-Control
2291\end_inset
2292</cell>
2293<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2294\begin_inset Text
2295
2296\layout Standard
2297
2298max-age=86400
2299\end_inset
2300</cell>
2301</row>
2302</lyxtabular>
2303
2304\end_inset
2305
2306
2307\end_inset
2308
2309
2310\layout Standard
2311
2312We have a certain request, and its unique ID is
2313\begin_inset Quotes eld
2314\end_inset
2315
2316PPIDskBRH30AAGPtAsg
2317\begin_inset Quotes erd
2318\end_inset
2319
2320.
2321 Within each separate table will be multiple entries with that request ID:
2322 several cookie entries, several header entries, etc.
2323 As you can see in tables
2324\begin_inset LatexCommand \ref{tblAcc}
2325
2326\end_inset
2327
2328,
2329\begin_inset LatexCommand \ref{tblNotes}
2330
2331\end_inset
2332
2333 and
2334\begin_inset LatexCommand \ref{tblHdr}
2335
2336\end_inset
2337
2338, you have a one-to-many relationship for request PPIDskBRH30AAGPtAsg: that
2339 one access has two associated notes and four associated headers.
2340 You can extract this data easily using the power of SQL's
2341\begin_inset Quotes eld
2342\end_inset
2343
2344select
2345\begin_inset Quotes erd
2346\end_inset
2347
2348 statement and table joins.
2349 To see the notes associated with a particular request:
2350\layout LyX-Code
2351
2352select a.remote_host, a.request_uri, n.item, n.val from access_log a, notes_log
2353 n
2354\layout LyX-Code
2355
2356where a.id=n.id and a.id='PPIDskBRH30AAGPtAsg';
2357\layout LyX-Code
2358
2359\layout Standard
2360\align center
2361
2362\begin_inset Tabular
2363<lyxtabular version="3" rows="3" columns="4">
2364<features>
2365<column alignment="left" valignment="top" leftline="true" width="0pt">
2366<column alignment="left" valignment="top" leftline="true" width="0pt">
2367<column alignment="left" valignment="top" leftline="true" width="0pt">
2368<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
2369<row topline="true" bottomline="true">
2370<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2371\begin_inset Text
2372
2373\layout Standard
2374
2375remote_host
2376\end_inset
2377</cell>
2378<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2379\begin_inset Text
2380
2381\layout Standard
2382
2383request_uri
2384\end_inset
2385</cell>
2386<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2387\begin_inset Text
2388
2389\layout Standard
2390
2391item
2392\end_inset
2393</cell>
2394<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2395\begin_inset Text
2396
2397\layout Standard
2398
2399val
2400\end_inset
2401</cell>
2402</row>
2403<row topline="true">
2404<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2405\begin_inset Text
2406
2407\layout Standard
2408
2409zerberus.aiacs.net
2410\end_inset
2411</cell>
2412<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2413\begin_inset Text
2414
2415\layout Standard
2416
2417/mod_log_sql/index.html
2418\end_inset
2419</cell>
2420<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2421\begin_inset Text
2422
2423\layout Standard
2424
2425mod_gzip_result
2426\end_inset
2427</cell>
2428<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2429\begin_inset Text
2430
2431\layout Standard
2432
2433OK
2434\end_inset
2435</cell>
2436</row>
2437<row topline="true" bottomline="true">
2438<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2439\begin_inset Text
2440
2441\layout Standard
2442
2443zerberus.aiacs.net
2444\end_inset
2445</cell>
2446<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2447\begin_inset Text
2448
2449\layout Standard
2450
2451/mod_log_sql/index.html
2452\end_inset
2453</cell>
2454<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2455\begin_inset Text
2456
2457\layout Standard
2458
2459mod_gzip_compression_ratio
2460\end_inset
2461</cell>
2462<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2463\begin_inset Text
2464
2465\layout Standard
2466
246769
2468\end_inset
2469</cell>
2470</row>
2471</lyxtabular>
2472
2473\end_inset
2474
2475
2476\layout LyX-Code
2477
2478\layout Standard
2479
2480Naturally you can craft similar statements for the outboud headers, inbound
2481 headers and cookies, all of which can live in separate tables.
2482 Your statements are limited in power only by your skill with SQL.
2483\layout Standard
2484
2485In order to use this capability of mod_log_sql, you must do several things:
2486\layout Itemize
2487
2488Compile mod_unique_id into Apache (statically or as a DSO).
2489 mod_log_sql employs the unique request ID that mod_unique_id provides in
2490 order to key between the separate tables.
2491 You can still log the data without mod_unqiue_id, but it will be completely
2492 uncorrelated and you will have no way to discern any meaning.
2493\layout Itemize
2494
2495Create the appropriate tables.
2496 This will be done for you if you permit mod_log_sql to create its own tables
2497 using
2498\noun on
2499LogSQLCreateTables On
2500\noun default
2501, or if you use the enclosed
2502\begin_inset Quotes eld
2503\end_inset
2504
2505create_tables.sql
2506\begin_inset Quotes erd
2507\end_inset
2508
2509 script.
2510\layout Itemize
2511
2512Create a SQL index on the
2513\begin_inset Quotes eld
2514\end_inset
2515
2516id
2517\begin_inset Quotes erd
2518\end_inset
2519
2520 column.
2521 Without this index, table joins will be deathly slow.
2522 I recommend you consult the MySQL documentation on the proper way to create
2523 a column index if you are not familiar with this operation.
2524\layout Itemize
2525
2526Within each appropriate VirtualHost stanza, use the
2527\noun on
2528 LogSQLWhich*
2529\noun default
2530 and
2531\noun on
2532LogSQL*LogTable
2533\noun default
2534 directives to tell the module what and where to log the data.
2535 In the following example, I have overridden the name for the notes table
2536 whereas I have left the other table names at their defaults.
2537 I have then specified the cookies, headers and notes that interest me.
2538 (And as you can see, these directives do not require me to add any characters
2539 to
2540\noun on
2541LogSQLTransferLogTable.)
2542\layout LyX-Code
2543
2544<VirtualHost 216.231.36.128>
2545\layout LyX-Code
2546
2547 (snip)
2548\layout LyX-Code
2549
2550 LogSQLNotesLogTable notestable
2551\layout LyX-Code
2552
2553 LogSQLWhichCookies bluecookie redcookie greencookie
2554\layout LyX-Code
2555
2556 LogSQLWhichNotes mod_gzip_result mod_gzip_compression_ratio
2557\layout LyX-Code
2558
2559 LogSQLWhichHeadersOut Expires Content-Type Cache-Control
2560\layout LyX-Code
2561
2562 LogSQLWhichHeadersIn UserAgent Accept-Encoding Host
2563\layout LyX-Code
2564
2565 (snip)
2566\layout LyX-Code
2567
2568</VirtualHost>
2569\layout Subsubsection
2570
2571Using the same database for production and test
2572\layout Standard
2573
2574Although suboptimal, it is not uncommon to use the same backend database
2575 for the
2576\begin_inset Quotes eld
2577\end_inset
2578
2579production
2580\begin_inset Quotes erd
2581\end_inset
2582
2583 webservers as well as the
2584\begin_inset Quotes eld
2585\end_inset
2586
2587test
2588\begin_inset Quotes erd
2589\end_inset
2590
2591 webservers (budgetary constraints, rackspace limits, etc.).
2592 Furthermore, an administrator in this situation may be unable to use
2593\noun on
2594LogSQLRemhostIgnore
2595\noun default
2596to exclude requests from the test servers -- perhaps the generated entries
2597 are genuinely useful for analytical or QA purposes, but their value after
2598 analysis is minimal.
2599\layout Standard
2600
2601It is wasteful and potentially confusing to permit this internal test data
2602 to clutter the database, and a solution to the problem is the proper use
2603 of the
2604\noun on
2605LogSQLMachineID
2606\noun default
2607directive.
2608 Assume a scenario where the production webservers have IDs like
2609\begin_inset Quotes eld
2610\end_inset
2611
2612web01,
2613\begin_inset Quotes erd
2614\end_inset
2615
2616
2617\begin_inset Quotes eld
2618\end_inset
2619
2620web02,
2621\begin_inset Quotes erd
2622\end_inset
2623
2624 and so on -- and the test webservers have IDs like
2625\begin_inset Quotes eld
2626\end_inset
2627
2628test01,
2629\begin_inset Quotes erd
2630\end_inset
2631
2632
2633\begin_inset Quotes eld
2634\end_inset
2635
2636test02,
2637\begin_inset Quotes erd
2638\end_inset
2639
2640 etc.
2641 Because entries in the log database are distinguished by their source machine,
2642 an administrator may purge unneeded test data from the access log as follows:
2643\layout LyX-Code
2644
2645delete from access_log where machine_id like 'test%';
2646\layout Subsubsection
2647
2648
2649\begin_inset LatexCommand \label{sub:DelayedIns}
2650
2651\end_inset
2652
2653Optimizing for a busy database
2654\layout Standard
2655
2656A busy MySQL database will have SELECT statements running concurrently with
2657 INSERT and UPDATE statements.
2658 A long-running SELECT can in certain circumstances block INSERTs and therefore
2659 block mod_log_sql.
2660 A workaround is to compile mod_log_sql for
2661\begin_inset Quotes eld
2662\end_inset
2663
2664delayed inserts,
2665\begin_inset Quotes erd
2666\end_inset
2667
2668 which are described as follows in the MySQL documentation:
2669\layout Quote
2670
2671The DELAYED option for the INSERT statement is a MySQL-specific option that
2672 is very useful if you have clients that can't wait for the INSERT to complete.
2673 This is a common problem when you use MySQL for logging and you also periodical
2674ly run SELECT and UPDATE statements that take a long time to complete.
2675 DELAYED was introduced in MySQL Version 3.22.15.
2676 It is a MySQL extension to ANSI SQL92.
2677\layout Quote
2678
2679INSERT DELAYED only works with ISAM and MyISAM tables.
2680 Note that as MyISAM tables supports concurrent SELECT and INSERT, if there
2681 is no free blocks in the middle of the data file, you very seldom need
2682 to use INSERT DELAYED with MyISAM.
2683
2684\layout Quote
2685
2686When you use INSERT DELAYED, the client will get an OK at once and the row
2687 will be inserted when the table is not in use by any other thread.
2688\layout Quote
2689
2690Another major benefit of using INSERT DELAYED is that inserts from many
2691 clients are bundled together and written in one block.
2692 This is much faster than doing many separate inserts.
2693
2694\layout Standard
2695
2696The general disadvantages of delayed inserts are:
2697\layout Enumerate
2698
2699The queued rows are only stored in memory until they are inserted into the
2700 table.
2701 If mysqld dies unexpectedly, any queued rows that weren't written to disk
2702 are lost.
2703\layout Enumerate
2704
2705There is additional overhead for the server to handle a separate thread
2706 for each table on which you use INSERT DELAYED.
2707\layout Standard
2708
2709
2710\series bold
2711The MySQL documentation concludes,
2712\begin_inset Quotes eld
2713\end_inset
2714
2715This means that you should only use INSERT DELAYED when you are really sure
2716 you need it!
2717\begin_inset Quotes erd
2718\end_inset
2719
2720 Furthermore, the current state of error return from a failed INSERT DELAYED
2721 seems to be in flux, and may behave in unpredictable ways between different
2722 MySQL versions.
2723 See section
2724\begin_inset LatexCommand \ref{sub:DelayedInsFAQ}
2725
2726\end_inset
2727
2728 in the FAQ -- you have been warned.
2729\layout Standard
2730
2731If you are experiencing issues which could be solved by delayed inserts,
2732 uncomment the #MYSQLDELAYED line in the Makefile by removing the # that
2733 is in front of it.
2734 Recompile and reinstall your module.
2735 All regular INSERT statements are now INSERT DELAYED, and you should see
2736 no more blocking of the module.
2737\layout Subsection
2738
2739
2740\begin_inset LatexCommand \label{sec:ConfRef}
2741
2742\end_inset
2743
2744Configuration directive reference
2745\layout Standard
2746
2747It is imperative that you understand which directives are used
2748\emph on
2749only once
2750\emph default
2751in the main server config, and which are used inside VirtualHost stanzas
2752 and therefore multiple times within httpd.conf.
2753 The
2754\begin_inset Quotes eld
2755\end_inset
2756
2757context
2758\begin_inset Quotes srd
2759\end_inset
2760
2761 listed with each entry informs you of this.
2762\layout Subsubsection
2763
2764LogSQLCookieLogTable
2765\layout LyX-Code
2766
2767Syntax: LogSQLCookieLogTable table-name
2768\layout LyX-Code
2769
2770Example: LogSQLCookieLogTable cookie_log
2771\layout LyX-Code
2772
2773Default: cookies
2774\layout LyX-Code
2775
2776Context: virtual host
2777\layout Standard
2778
2779Defines which table is used for logging of cookies.
2780 Working in conjunction with
2781\noun on
2782LogSQLWhichCookies
2783\noun default
2784, you can log many of each request's associated cookies to a separate table.
2785 For meaningful data retrieval the cookie table is keyed to the access table
2786 by the unique request ID supplied by the standard Apache module mod_unique_id.
2787\layout Standard
2788
2789Note that you must create the table (see create-tables.sql, included in the
2790 package), or
2791\noun on
2792LogSQLCreateTables
2793\noun default
2794 must be set to
2795\begin_inset Quotes eld
2796\end_inset
2797
2798on
2799\begin_inset Quotes erd
2800\end_inset
2801
2802.
2803\layout Subsubsection
2804
2805LogSQLCreateTables
2806\layout LyX-Code
2807
2808Syntax: LogSQLCreateTables flag
2809\layout LyX-Code
2810
2811Example: LogSQLCreateTables On
2812\layout LyX-Code
2813
2814Default: Off
2815\layout LyX-Code
2816
2817Context: main server config
2818\layout Standard
2819
2820mod_log_sql has the ability to create its tables on-the-fly.
2821 The advantage to this is convenience: you don't have to execute any SQL
2822 by hand to prepare the table.
2823 This is especially helpful for people with lots of virtual hosts (who should
2824 also see the
2825\noun on
2826LogSQLMassVirtualHosting
2827\noun default
2828 directive).
2829\layout Standard
2830
2831There is a slight disadvantage: if you wish to activate this feature, then
2832 the userid specified in
2833\noun on
2834LogSQLLoginInfo
2835\noun default
2836 must have CREATE privileges on the database.
2837 In an absolutely paranoid, locked-down situation you may only want to grant
2838 your mod_log_sql user INSERT privileges on the database; in that situation
2839 you are unable to take advantage of
2840\noun on
2841LogSQLCreateTables
2842\noun default
2843.
2844 But most people -- even the very security-conscious -- will find that granting
2845 CREATE on the logging database is reasonable.
2846\layout Standard
2847
2848This is defined only once in the httpd.conf file.
2849\layout Subsubsection
2850
2851LogSQLDatabase
2852\layout LyX-Code
2853
2854
2855\series bold
2856MANDATORY
2857\layout LyX-Code
2858
2859Syntax: LogSQLDatabase database
2860\layout LyX-Code
2861
2862Example: LogSQLDatabase loggingdb
2863\layout LyX-Code
2864
2865Context: main server config
2866\layout Standard
2867
2868Defines the database that is used for logging.
2869
2870\begin_inset Quotes eld
2871\end_inset
2872
2873database
2874\begin_inset Quotes erd
2875\end_inset
2876
2877 must be a valid db on the MySQL host defined in
2878\noun on
2879LogSQLLoginInfo
2880\noun default
2881.
2882
2883\layout Standard
2884
2885This is defined only once in the httpd.conf file.
2886\layout Subsubsection
2887
2888LogSQLForcePreserve
2889\layout LyX-Code
2890
2891Syntax: LogSQLForcePreserve Flag
2892\layout LyX-Code
2893
2894Example: LogSQLPreserveFile on
2895\layout LyX-Code
2896
2897Default: off
2898\layout LyX-Code
2899
2900Context: main server config
2901\layout Standard
2902
2903You may need to perform debugging on your database and specifically want
2904 mod_log_sql to make no attempts to log to it.
2905 This directive instructs the module to send all its log entries directly
2906 to the preserve file and to make no database INSERT attempts.
2907\layout Standard
2908
2909This is presumably a directive for temporary use only; it could be dangerous
2910 if you set it and forget it, as all your entries will simply pile up in
2911 the preserve file.
2912\layout Standard
2913
2914This is defined only once in the httpd.conf file.
2915\layout Subsubsection
2916
2917LogSQLHeadersInLogTable
2918\layout LyX-Code
2919
2920Syntax: LogSQLHeadersInLogTable table-name
2921\layout LyX-Code
2922
2923Example: LogSQLHeadersInLogTable headers
2924\layout LyX-Code
2925
2926Default: headers_in
2927\layout LyX-Code
2928
2929Context: virtual host
2930\layout Standard
2931
2932Defines which table is used for logging of inbound headers.
2933 Working in conjunction with
2934\noun on
2935LogSQLWhichHeadersIn
2936\noun default
2937, you can log many of each request's associated headers to a separate table.
2938 For meaningful data retrieval the headers table is keyed to the access
2939 table by the unique request ID supplied by the standard Apache module mod_uniqu
2940e_id.
2941\layout Standard
2942
2943Note that you must create the table (see create-tables.sql, included in the
2944 package), or
2945\noun on
2946LogSQLCreateTables
2947\noun default
2948 must be set to
2949\begin_inset Quotes eld
2950\end_inset
2951
2952on
2953\begin_inset Quotes erd
2954\end_inset
2955
2956.
2957\layout Subsubsection
2958
2959LogSQLHeadersOutLogTable
2960\layout LyX-Code
2961
2962Syntax: LogSQLHeadersOutLogTable table-name
2963\layout LyX-Code
2964
2965Example: LogSQLHeadersOutLogTable headers
2966\layout LyX-Code
2967
2968Default: headers_out
2969\layout LyX-Code
2970
2971Context: virtual host
2972\layout Standard
2973
2974Defines which table is used for logging of outbound headers.
2975 Working in conjunction with
2976\noun on
2977LogSQLWhichHeadersOut
2978\noun default
2979, you can log many of each request's associated headers to a separate table.
2980 For meaningful data retrieval the headers table is keyed to the access
2981 table by the unique request ID supplied by the standard Apache module mod_uniqu
2982e_id.
2983\layout Standard
2984
2985Note that you must create the table (see create-tables.sql, included in the
2986 package), or
2987\noun on
2988LogSQLCreateTables
2989\noun default
2990 must be set to
2991\begin_inset Quotes eld
2992\end_inset
2993
2994on
2995\begin_inset Quotes erd
2996\end_inset
2997
2998.
2999\layout Subsubsection
3000
3001LogSQLLoginInfo
3002\layout LyX-Code
3003
3004
3005\series bold
3006MANDATORY
3007\series default
3008
3009\layout LyX-Code
3010
3011Syntax: LogSQLLoginInfo host user password
3012\layout LyX-Code
3013
3014Example: LogSQLLoginInfo foobar.baz.com logwriter passw0rd
3015\layout LyX-Code
3016
3017Context: main server config
3018\layout Standard
3019
3020Defines the general parameters of the MySQL host to which you will be logging.
3021
3022\begin_inset Quotes eld
3023\end_inset
3024
3025host
3026\begin_inset Quotes erd
3027\end_inset
3028
3029 is the hostname or IP address of the MySQL machine, and is simply
3030\begin_inset Quotes eld
3031\end_inset
3032
3033localhost
3034\begin_inset Quotes erd
3035\end_inset
3036
3037 if the database lives on the same machine as Apache.
3038
3039\begin_inset Quotes eld
3040\end_inset
3041
3042user
3043\begin_inset Quotes erd
3044\end_inset
3045
3046 is the MySQL userid (not a Unix userid!) with INSERT privileges on the
3047 table defined in
3048\noun on
3049LogSQLTransferLogTable
3050\noun default
3051.
3052
3053\begin_inset Quotes eld
3054\end_inset
3055
3056password
3057\begin_inset Quotes erd
3058\end_inset
3059
3060 is that user's password.
3061
3062\layout Standard
3063
3064This is defined only once in the httpd.conf file.
3065\layout Subsubsection
3066
3067LogSQLMachineID
3068\layout LyX-Code
3069
3070Syntax: LogSQLMachineID somename
3071\layout LyX-Code
3072
3073Example: LogSQLMachineID web01
3074\layout LyX-Code
3075
3076Context: main server config
3077\layout Standard
3078
3079If you have a farm of webservers then you may wish to know which particular
3080 machine made each entry; this is useful for analyzing your loadbalancing
3081 methodology.
3082
3083\noun on
3084LogSQLMachineID
3085\noun default
3086 permits you to distinguish each machine's entries if you assign each machine
3087 its own
3088\noun on
3089LogSQLMachineID
3090\noun default
3091: for example, the first webserver gets
3092\begin_inset Quotes eld
3093\end_inset
3094
3095
3096\noun on
3097LogSQLMachineID
3098\noun default
3099 web01,
3100\begin_inset Quotes erd
3101\end_inset
3102
3103 the second gets
3104\begin_inset Quotes eld
3105\end_inset
3106
3107
3108\noun on
3109LogSQLMachineID
3110\noun default
3111 web02,
3112\begin_inset Quotes erd
3113\end_inset
3114
3115 etc.
3116\layout Standard
3117
3118This is defined only once in the httpd.conf file.
3119\layout Subsubsection
3120
3121LogSQLMassVirtualHosting
3122\layout LyX-Code
3123
3124Syntax: LogSQLMassVirtualHosting flag
3125\layout LyX-Code
3126
3127Example: LogSQLMassVirtualHosting On
3128\layout LyX-Code
3129
3130Default: Off
3131\layout LyX-Code
3132
3133Context: main server config
3134\layout Standard
3135
3136If you administer a site hosting many, many virtual hosts then this option
3137 will appeal to you.
3138 If you turn on
3139\noun on
3140LogSQLMassVirtualHosting
3141\noun default
3142 then several things happen:
3143\layout Itemize
3144
3145the on-the-fly table creation feature is activated automatically
3146\layout Itemize
3147
3148the transfer log table name is dynamically set from the virtual host's name
3149 after stripping out SQL-unfriendly characters (example: a virtual host
3150 www.grubbybaby.com gets logged to table access_www_grubbybaby_com)
3151\layout Itemize
3152
3153which, in turn, means that each virtual host logs to its own segregated
3154 table.
3155 Because there is no data shared between virtual servers you can grant your
3156 users access to the tables they need; they will be unable to view others'
3157 data.
3158\layout Standard
3159
3160This is a huge boost in convenience for sites with many virtual servers.
3161 Activating
3162\noun on
3163LogSQLMassVirtualHosting
3164\noun default
3165 obviates the need to create every virtual server's table and provides more
3166 granular security possibilities.
3167\layout Standard
3168
3169You are advised to investigate the use of Apache's
3170\noun on
3171UseCanonicalName On
3172\noun default
3173directive with this directive in order to ensure that each virtual host
3174 maps to one table namespace.
3175\layout Standard
3176
3177This is defined only once in the httpd.conf file.
3178
3179\layout Subsubsection
3180
3181LogSQLNotesLogTable
3182\layout LyX-Code
3183
3184Syntax: LogSQLNotesLogTable table-name
3185\layout LyX-Code
3186
3187Example: LogSQLNotesLogTable notes_log
3188\layout LyX-Code
3189
3190Default: notes
3191\layout LyX-Code
3192
3193Context: virtual host
3194\layout Standard
3195
3196Defines which table is used for logging of notes.
3197 Working in conjunction with
3198\noun on
3199LogSQLWhichNotes
3200\noun default
3201, you can log many of each request's associated notes to a separate table.
3202 For meaningful data retrieval the notes table is keyed to the access table
3203 by the unique request ID supplied by the standard Apache module mod_unique_id.
3204\layout Standard
3205
3206Note that you must create the table (see create-tables.sql, included in the
3207 package), or
3208\noun on
3209LogSQLCreateTables
3210\noun default
3211 must be set to ``on''.
3212
3213\layout Subsubsection
3214
3215LogSQLPreserveFile
3216\layout LyX-Code
3217
3218Syntax: LogSQLPreserveFile filename
3219\layout LyX-Code
3220
3221Example: LogSQLPreserveFile offline-preserve
3222\layout LyX-Code
3223
3224Default: /tmp/sql-preserve
3225\layout LyX-Code
3226
3227Context: virtual host
3228\layout Standard
3229
3230mod_log_sql writes queries to this local preserve file in the event that
3231 it cannot reach the database, and thus ensures that your high-availability
3232 web frontend does not lose logs during a temporary database outage.
3233 This could happen for a number of reasons: the database goes offline, the
3234 network breaks, etc.
3235 You will not lose entries since the module has this backup.
3236 The file consists of a series of SQL statements that can be imported into
3237 your database at your convenience; furthermore, because the SQL queries
3238 contain the access timestamps you do not need to worry about out-of-order
3239 data after the import, which is done in a simple manner:
3240\layout LyX-Code
3241
3242# mysql -uadminuser -p mydbname < /tmp/sql-preserve
3243\layout Standard
3244
3245If you do not define
3246\noun on
3247LogSQLPreserveFile
3248\noun default
3249 then all virtual servers will log to the same default preserve file (/tmp/sql-p
3250reserve).
3251 You can redefine this on a virtual-host basis in order to segregate your
3252 preserve files if you desire.
3253 Note that segregation is not usually necessary, as the SQL statements that
3254 are written to the preserve file already distinguish between different
3255 virtual hosts if you include the 'v' character in your
3256\noun on
3257LogSQLTransferLogFormat
3258\noun default
3259 directive.
3260 It is only necessary to segregate preserve-files by virualhost if you also
3261 segregate access logs by virtualhost.
3262\layout Standard
3263
3264The module will log to Apache's
3265\noun on
3266ErrorLog
3267\noun default
3268 when it notices a database outage, and upon database return.
3269 You will therefore know when the preserve file is being used, although
3270 it is your responsibility to import the file.
3271\layout Standard
3272
3273The file does not need to be created in advance.
3274 It is safe to remove or rename the file without interrupting Apache, as
3275 the module closes the filehandle immediately after completing the write.
3276 The file is created with the user & group ID of the running Apache process
3277 (e.g.
3278 'nobody' on many Linux distributions).
3279\layout Subsubsection
3280
3281LogSQLRemhostIgnore
3282\layout LyX-Code
3283
3284Syntax: LogSQLRemhostIgnore host1 host2 host3 ...
3285 hostN
3286\layout LyX-Code
3287
3288Example: LogSQLRemhostIgnore localnet.com
3289\layout LyX-Code
3290
3291Context: virtual host
3292\layout Standard
3293
3294Lists a series of strings that, if present in the REMOTE_HOST, will cause
3295 that request to
3296\series bold
3297not
3298\series default
3299 be logged.
3300 This directive is useful for cutting down on log clutter when you are certain
3301 that you want to ignore requests from certain hosts, such as your own internal
3302 network machines.
3303 See section
3304\begin_inset LatexCommand \ref{sub:Ignore}
3305
3306\end_inset
3307
3308 for some tips for using this directive.
3309\layout Standard
3310
3311Each string is separated by a space, and no regular expressions or globbing
3312 are allowed.
3313 Each string is evaluated as a substring of the REMOTE_HOST using strstr().
3314 The comparison is case sensitive.
3315\layout Subsubsection
3316
3317LogSQLRequestAccept
3318\layout LyX-Code
3319
3320Syntax: LogSQLRequestAccept req1 req2 req3 ...
3321 reqN
3322\layout LyX-Code
3323
3324Example: LogSQLRequestAccept .html .php .jpg
3325\layout LyX-Code
3326
3327Default: if not specified, all requests are
3328\begin_inset Quotes eld
3329\end_inset
3330
3331accepted
3332\begin_inset Quotes erd
3333\end_inset
3334
3335
3336\layout LyX-Code
3337
3338Context: virtual host
3339\layout Standard
3340
3341Lists a series of strings that, if present in the URI, will permit that
3342 request to be
3343\series bold
3344
3345\series default
3346considered for logging (depending on additional filtering by the
3347\begin_inset Quotes eld
3348\end_inset
3349
3350ignore
3351\begin_inset Quotes erd
3352\end_inset
3353
3354 directives).
3355 Any request that fails to match one of the
3356\noun on
3357LogSQLRequestAccept
3358\noun default
3359entries will be discarded.
3360\layout Standard
3361
3362This directive is useful for cutting down on log clutter when you are certain
3363 that you only want to log certain kinds of requests, and just blanket-ignore
3364 everything else.
3365 See section
3366\begin_inset LatexCommand \ref{sub:Ignore}
3367
3368\end_inset
3369
3370 for some tips for using this directive.
3371\layout Standard
3372
3373Each string is separated by a space, and no regular expressions or globbing
3374 are allowed.
3375 Each string is evaluated as a substring of the URI using strstr().
3376 The comparison is case sensitive.
3377\layout Standard
3378
3379This directive is completely optional.
3380 It is more general than
3381\noun on
3382LogSQLRequestIgnore
3383\noun default
3384and
3385\noun on
3386
3387\noun default
3388is evaluated before
3389\noun on
3390 LogSQLRequestIgnore
3391\noun default
3392.
3393 If this directive is not used,
3394\series bold
3395all
3396\series default
3397 requests are accepted and passed on to the other filtering directives.
3398 Therefore, only use this directive if you have a specific reason to do
3399 so.
3400\layout Subsubsection
3401
3402LogSQLRequestIgnore
3403\layout LyX-Code
3404
3405Syntax: LogSQLRequestIgnore req1 req2 req3 ...
3406 reqN
3407\layout LyX-Code
3408
3409Example: LogSQLRequestIgnore root.exe cmd.exe default.ida favicon.ico
3410\layout LyX-Code
3411
3412Context: virtual host
3413\layout Standard
3414
3415Lists a series of strings that, if present in the URI, will cause that request
3416 to
3417\series bold
3418NOT
3419\series default
3420 be
3421\series bold
3422
3423\series default
3424logged.
3425 This directive is useful for cutting down on log clutter when you are certain
3426 that you want to ignore requests for certain objects.
3427 See section
3428\begin_inset LatexCommand \ref{sub:Ignore}
3429
3430\end_inset
3431
3432 for some tips for using this directive.
3433\layout Standard
3434
3435Each string is separated by a space, and no regular expressions or globbing
3436 are allowed.
3437 Each string is evaluated as a substring of the URI using strstr().
3438 The comparison is case sensitive.
3439\layout Subsubsection
3440
3441LogSQLSocketFile
3442\layout LyX-Code
3443
3444Syntax: LogSQLSocketFile filename
3445\layout LyX-Code
3446
3447Example: LogSQLSocketFile /tmp/mysql.sock
3448\layout LyX-Code
3449
3450Default: /var/lib/mysql/mysql.sock
3451\layout LyX-Code
3452
3453Context: main server config
3454\layout Standard
3455
3456At Apache runtime you can specify the MySQL socket file to use.
3457 Set this once in your main server config to override the default value.
3458 This value is irrelevant if your database resides on a separate machine.
3459\layout Standard
3460
3461mod_log_sql will automatically employ the socket for db communications if
3462 the database resides on the local host.
3463 If the db resides on a separate host the module will automatically use
3464 TCP/IP.
3465 This is a function of the MySQL API and is not user-configurable.
3466\layout Standard
3467
3468This is defined only once in the httpd.conf file.
3469\layout Subsubsection
3470
3471LogSQLTCPPort
3472\layout LyX-Code
3473
3474Syntax: LogSQLTCPPort portnumber
3475\layout LyX-Code
3476
3477Example: LogSQLTCPPort 3309
3478\layout LyX-Code
3479
3480Default: 3306
3481\layout LyX-Code
3482
3483Context: main server config
3484\layout Standard
3485
3486Your database may listen on a different port than the default.
3487 If so, use this directive to instruct the module which port to use.
3488 This directive only applies if the database is on a different machine connected
3489 via TCP/IP.
3490\layout Standard
3491
3492This is defined only once in the httpd.conf file.
3493\layout Subsubsection
3494
3495
3496\begin_inset LatexCommand \label{sub:Frmat}
3497
3498\end_inset
3499
3500LogSQLTransferLogFormat
3501\layout LyX-Code
3502
3503Syntax: LogSQLTransferLogFormat format-string
3504\layout LyX-Code
3505
3506Example: LogSQLTransferLogFormat huSUTv
3507\layout LyX-Code
3508
3509Default: AbHhmRSsTUuv
3510\layout LyX-Code
3511
3512Context: virtual host
3513\layout Standard
3514
3515Each character in the format-string defines an attribute of the request
3516 that you wish to log.
3517 The default logs the information required to create Combined Log Format
3518 logs, plus several extras.
3519 Here is the full list of allowable keys, which sometimes resemble their
3520 Apache counterparts, but do not always:
3521\layout Quote
3522
3523
3524\size footnotesize
3525
3526\begin_inset Tabular
3527<lyxtabular version="3" rows="22" columns="5">
3528<features>
3529<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
3530<column alignment="left" valignment="top" width="0pt">
3531<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
3532<column alignment="left" valignment="top" width="0pt">
3533<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
3534<row topline="true" bottomline="true" endhead="true">
3535<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
3536\begin_inset Text
3537
3538\layout Standard
3539
3540\end_inset
3541</cell>
3542<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3543\begin_inset Text
3544
3545\layout Standard
3546
3547
3548\series bold
3549\size footnotesize
3550What is this?
3551\end_inset
3552</cell>
3553<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3554\begin_inset Text
3555
3556\layout Standard
3557
3558
3559\series bold
3560\size footnotesize
3561Data field
3562\end_inset
3563</cell>
3564<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3565\begin_inset Text
3566
3567\layout Standard
3568
3569
3570\series bold
3571\size footnotesize
3572Column type
3573\end_inset
3574</cell>
3575<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3576\begin_inset Text
3577
3578\layout Standard
3579
3580
3581\series bold
3582\size footnotesize
3583Example
3584\end_inset
3585</cell>
3586</row>
3587<row topline="true">
3588<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3589\begin_inset Text
3590
3591\layout Standard
3592
3593
3594\size footnotesize
3595A
3596\end_inset
3597</cell>
3598<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3599\begin_inset Text
3600
3601\layout Standard
3602
3603
3604\size footnotesize
3605User agent
3606\end_inset
3607</cell>
3608<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3609\begin_inset Text
3610
3611\layout Standard
3612
3613
3614\size footnotesize
3615agent
3616\end_inset
3617</cell>
3618<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3619\begin_inset Text
3620
3621\layout Standard
3622
3623
3624\size footnotesize
3625varchar(255)
3626\end_inset
3627</cell>
3628<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3629\begin_inset Text
3630
3631\layout Standard
3632
3633
3634\size footnotesize
3635Mozilla/4.0 (compat; MSIE 6.0; Windows)
3636\end_inset
3637</cell>
3638</row>
3639<row topline="true">
3640<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3641\begin_inset Text
3642
3643\layout Standard
3644
3645a
3646\end_inset
3647</cell>
3648<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3649\begin_inset Text
3650
3651\layout Standard
3652
3653CGI request arguments
3654\end_inset
3655</cell>
3656<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3657\begin_inset Text
3658
3659\layout Standard
3660
3661request_args
3662\end_inset
3663</cell>
3664<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3665\begin_inset Text
3666
3667\layout Standard