From c00607cbde2fc719bfc1af4e9c58a9eb4eccf691 Mon Sep 17 00:00:00 2001
From: Christopher Powell
Date: Tue, 19 Nov 2002 07:13:47 +0000
Subject: Some more doc edits & cleanup.
---
Documentation/documentation.lyx | 410 +++++++++++++++++++++++++++-------------
1 file changed, 278 insertions(+), 132 deletions(-)
(limited to 'Documentation')
diff --git a/Documentation/documentation.lyx b/Documentation/documentation.lyx
index efca178..39daba8 100644
--- a/Documentation/documentation.lyx
+++ b/Documentation/documentation.lyx
@@ -422,11 +422,14 @@ Perform all the following steps as root so that you have install privs,
\end_deeper
\layout Enumerate
-Edit Makefile for your system.
+Edit Makefile for your system:
\begin_deeper
-\layout Standard
+\layout Enumerate
-NECESSARY:
+These are
+\series bold
+necessary:
+\begin_deeper
\layout Itemize
The location where you installed Apache -- usually /usr/local/apache, 'locate
@@ -437,13 +440,30 @@ The location of your MySQL libraries, find using 'locate libmysqlclient'
\layout Itemize
The location of your MySQL header files, find using 'locate mysql.h'
-\layout Standard
+\end_deeper
+\layout Enumerate
-OPTIONAL if you have included mod_ssl in Apache and want to log SSL data
- such as keysize and cipher type:
+This is
+\series bold
+optional
+\series default
+: if you have included mod_ssl in Apache and want to log SSL data such as
+ keysize and cipher type:
+\begin_deeper
\layout Itemize
The location of your SSL header files, find using 'locate mod_ssl.h'
+\end_deeper
+\layout Standard
+
+Note: you do
+\series bold
+not
+\series default
+need to compile SSL support into mod_log_sql in order to simply use it with
+ a secure site.
+ You only need to compile SSL support into mod_log_sql if you want to log
+ SSL-specific data such as cipher type.
\layout Standard
Now that you know these things, edit Makefile and replace the stock values
@@ -528,8 +548,8 @@ in your httpd.conf file.
/usr/local/apache/bin/apachectl startssl: httpd could not be started
\layout Standard
-(If the statements are out of order, mod_log_sql doesn't recognize the SSL
- symbols that mod_ssl provides.)
+(mod_log_sql has a dependency on mod_ssl for SSL symbols.
+ If the statements are out of order, mod_log_sql can't recognize those symbols.)
\layout Standard
Now skip below to section
@@ -575,9 +595,12 @@ Unpack the archive into a working directory.
Edit Makefile for your system.
\begin_deeper
-\layout Standard
+\layout Enumerate
-NECESSARY:
+These are
+\series bold
+necessary:
+\begin_deeper
\layout Itemize
The location where you installed Apache -- usually /usr/local/apache, 'locate
@@ -593,10 +616,16 @@ The location of your MySQL header files, find using 'locate mysql.h'
\layout Itemize
The location of your MySQL libraries, find using 'locate libmysqlclient'
-\layout Standard
+\end_deeper
+\layout Enumerate
-OPTIONAL if you have included mod_ssl in Apache and want to log SSL data
- such as keysize and cipher type:
+This is
+\series bold
+optional
+\series default
+: if you have included mod_ssl in Apache and want to log SSL data such as
+ keysize and cipher type:
+\begin_deeper
\layout Itemize
The location of your mod_ssl header files, find using 'locate mod_ssl.h'
@@ -606,6 +635,17 @@ The location of your OpenSSL header files, find using 'locate x509.h'
\layout Itemize
The location of your db1 header files, find using 'locate mpool.h'
+\end_deeper
+\layout Standard
+
+Note: you do
+\series bold
+not
+\series default
+need to compile SSL support into mod_log_sql in order to simply use it with
+ a secure site.
+ You only need to compile SSL support into mod_log_sql if you want to log
+ SSL-specific data such as cipher type.
\layout Standard
Now that you know these things, edit Makefile and replace the stock values
@@ -1408,6 +1448,11 @@ LogSQLCreateTables On
The module is permitted to create all necessary tables and to make intelligent,
on-the-fly configuration of each VirtualHost.
+ (
+\noun on
+LogSQLMassVirtualHosting On
+\noun default
+)
\layout Standard
Many users are happy to use the module in its most minimal form: they hand-creat
@@ -1514,6 +1559,83 @@ LogSQLTransferLogFormat
machine and thereby analyze the front-end loadbalancing algorithm.
\layout Subsubsection
+Using the same database for production and test
+\layout Standard
+
+Although suboptimal, it is not uncommon to use the same backend database
+ for the
+\begin_inset Quotes eld
+\end_inset
+
+production
+\begin_inset Quotes erd
+\end_inset
+
+ webservers as well as the
+\begin_inset Quotes eld
+\end_inset
+
+test
+\begin_inset Quotes erd
+\end_inset
+
+ webservers (budgetary constraints, rackspace limits, etc.).
+ Furthermore, an administrator in this situation may be unable to use
+\noun on
+LogSQLRemhostIgnore
+\noun default
+to exclude requests from the test servers -- perhaps the generated entries
+ are genuinely useful for analytical or QA purposes, but their value after
+ analysis is minimal.
+\layout Standard
+
+It is wasteful and potentially confusing to permit this internal test data
+ to clutter the database, and a solution to the problem is the proper use
+ of the
+\noun on
+LogSQLMachineID
+\noun default
+directive.
+ Assume a scenario where the production webservers have IDs like
+\begin_inset Quotes eld
+\end_inset
+
+web01,
+\begin_inset Quotes erd
+\end_inset
+
+
+\begin_inset Quotes eld
+\end_inset
+
+web02,
+\begin_inset Quotes erd
+\end_inset
+
+ and so on -- and the test webservers have IDs like
+\begin_inset Quotes eld
+\end_inset
+
+test01,
+\begin_inset Quotes erd
+\end_inset
+
+
+\begin_inset Quotes eld
+\end_inset
+
+test02,
+\begin_inset Quotes erd
+\end_inset
+
+ etc.
+ Because entries in the log database are distinguished by their source machine,
+ an administrator may purge unneeded test data from the access log as follows:
+\layout LyX-Code
+
+delete from access_log where machine_id like 'test%';
+\layout Subsubsection
+
\begin_inset LatexCommand \label{secMulTable}
@@ -1570,11 +1692,14 @@ access_log
\align center
\begin_inset Tabular
-<lyxtabular version="3" rows="2" columns="3">
+<lyxtabular version="3" rows="2" columns="6">
<features>
<column alignment="left" valignment="top" leftline="true" width="0pt">
<column alignment="left" valignment="top" leftline="true" width="0pt">
<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
+<column alignment="left" valignment="top" rightline="true" width="0pt">
+<column alignment="left" valignment="top" rightline="true" width="0pt">
+<column alignment="left" valignment="top" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
@@ -1600,6 +1725,30 @@ remote_host
request_uri
\end_inset
</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+time_stamp
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+status
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+bytes_sent
+\end_inset
+</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1607,7 +1756,7 @@ request_uri
\layout Standard
-XYZ123
+PPIDskBRH30AAGPtAsg
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1615,7 +1764,7 @@ XYZ123
\layout Standard
-foo.bar.com
+zerberus.aiacs.net
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -1626,6 +1775,30 @@ foo.bar.com
/index.html
\end_inset
</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1022493617
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+200
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+2215
+\end_inset
+</cell>
</row>
</lyxtabular>
@@ -1688,7 +1861,7 @@ val
\layout Standard
-XYZ123
+PPIDskBRH30AAGPtAsg
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1714,7 +1887,7 @@ OK
\layout Standard
-XYZ123
+PPIDskBRH30AAGPtAsg
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1798,7 +1971,7 @@ val
\layout Standard
-XYZ123
+PPIDskBRH30AAGPtAsg
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1824,7 +1997,7 @@ text/html
\layout Standard
-XYZ123
+PPIDskBRH30AAGPtAsg
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1850,7 +2023,7 @@ gzip, deflate
\layout Standard
-XYZ123
+PPIDskBRH30AAGPtAsg
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1876,7 +2049,7 @@ Tue, 28 May 2002 10:00:18 GMT
\layout Standard
-XYZ123
+PPIDskBRH30AAGPtAsg
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
@@ -1910,7 +2083,7 @@ We have a certain request, and its unique ID is
\begin_inset Quotes eld
\end_inset
-XYZ123
+PPIDskBRH30AAGPtAsg
\begin_inset Quotes erd
\end_inset
@@ -1932,8 +2105,8 @@ XYZ123
\end_inset
-, you have a one-to-many relationship for request XYZ123: that one access
- has two associated notes and four associated headers.
+, you have a one-to-many relationship for request PPIDskBRH30AAGPtAsg: that
+ one access has two associated notes and four associated headers.
You can extract this data easily using the power of SQL's
\begin_inset Quotes eld
\end_inset
@@ -2011,7 +2184,7 @@ zerberus.aiacs.net
\layout Standard
-/mod_log_sql/style_1.css
+/mod_log_sql/index.html
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -2027,7 +2200,7 @@ mod_gzip_result
\layout Standard
-DECLINED:EXCLUDED
+OK
\end_inset
</cell>
</row>
@@ -2045,7 +2218,7 @@ zerberus.aiacs.net
\layout Standard
-/mod_log_sql/style_1.css
+/mod_log_sql/index.html
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
@@ -2061,7 +2234,7 @@ mod_gzip_compression_ratio
\layout Standard
-0
+69
\end_inset
</cell>
</row>
@@ -2074,6 +2247,11 @@ mod_gzip_compression_ratio
\layout Standard
+Naturally you can craft similar statements for the outboud headers, inbound
+ headers and cookies, all of which can live in separate tables.
+ Your statements are limited in power only by your skill with SQL.
+\layout Standard
+
In order to use this capability of mod_log_sql, you must do several things:
\layout Itemize
@@ -2085,8 +2263,12 @@ Compile mod_unique_id into Apache (statically or as a DSO).
\layout Itemize
Create the appropriate tables.
- This will be done for you if you permit mod_log_sql to create its own tables,
- or if you use the enclosed
+ This will be done for you if you permit mod_log_sql to create its own tables
+ using
+\noun on
+LogSQLCreateTables On
+\noun default
+, or if you use the enclosed
\begin_inset Quotes eld
\end_inset
@@ -2122,11 +2304,11 @@ LogSQL*LogTable
directives to tell the module what and where to log the data.
In the following example, I have overridden the name for the notes table
whereas I have left the other table names at their defaults.
- I then specified the cookies, headers and notes that interest me.
- As you can see, these directives do not require me to add any characters
+ I have then specified the cookies, headers and notes that interest me.
+ (And as you can see, these directives do not require me to add any characters
to
\noun on
-LogSQLTransferLogTable.
+LogSQLTransferLogTable.)
\layout LyX-Code
<VirtualHost 216.231.36.128>
@@ -2154,83 +2336,6 @@ LogSQLTransferLogTable.
\layout LyX-Code
</VirtualHost>
-\layout Subsubsection
-
-Using the same database for production and test
-\layout Standard
-
-Although suboptimal, it is not uncommon to use the same backend database
- for the
-\begin_inset Quotes eld
-\end_inset
-
-production
-\begin_inset Quotes erd
-\end_inset
-
- webservers as well as the
-\begin_inset Quotes eld
-\end_inset
-
-test
-\begin_inset Quotes erd
-\end_inset
-
- webservers (budgetary constraints, rackspace limits, etc.).
- Furthermore, an administrator in this situation may be unable to use
-\noun on
-LogSQLRemhostIgnore
-\noun default
-to exclude requests from the test servers -- perhaps the generated entries
- are genuinely useful for analytical or QA purposes, but their value after
- analysis is minimal.
-\layout Standard
-
-It is wasteful and potentially confusing to permit this internal test data
- to clutter the database, and a solution to the problem is the proper use
- of the
-\noun on
-LogSQLMachineID
-\noun default
-directive.
- Assume a scenario where the production webservers have IDs like
-\begin_inset Quotes eld
-\end_inset
-
-web01,
-\begin_inset Quotes erd
-\end_inset
-
-
-\begin_inset Quotes eld
-\end_inset
-
-web02,
-\begin_inset Quotes erd
-\end_inset
-
- and so on -- and the test webservers have IDs like
-\begin_inset Quotes eld
-\end_inset
-
-test01,
-\begin_inset Quotes erd
-\end_inset
-
-
-\begin_inset Quotes eld
-\end_inset
-
-test02,
-\begin_inset Quotes erd
-\end_inset
-
- etc.
- Because entries in the log database are distinguished by their source machine,
- an administrator may purge unneeded test data from the access log as follows:
-\layout LyX-Code
-
-delete from access_log where machine_id like 'test%';
\layout Subsection
@@ -5648,14 +5753,23 @@ LogSQLWhichCookies
What are the SSL logging features, and how do I activate them?
\layout Standard
-If you run an SSL-enabled server you may benefit from logging some SSL details.
- mod_log_sql now supports this ability.
- By adding certain characters to your
+Note: you do
+\series bold
+not
+\series default
+need to compile SSL support into mod_log_sql in order to simply use it with
+ a secure site.
+ You only need to compile SSL support into mod_log_sql if you want to log
+ SSL-specific data such as the cipher type used, or the keysize that was
+ negotiated.
+\layout Standard
+
+By adding certain characters to your
\noun on
LogSQLTransferLogFormat
\noun default
string you can tell mod_log_sql to log the SSL cipher, the SSL keysize
- of the connection, and the Max-keysize that was available.
+ of the connection, and the maximum keysize that was available.
This would let you tell, for example, which clients were using only export-grad
e security to access your secure software area.
\layout Standard
@@ -5697,11 +5811,21 @@ Qqz
</VirtualHost>
\layout Standard
-The last three characters (Qqz) in the directive are the SSL ones; see the
- directives documentation for details.
+The last three characters (Qqz) in the directive are the SSL ones; see section
+
+\begin_inset LatexCommand \ref{sub:Frmat}
+
+\end_inset
+
+ in the directives documentation for details of the
+\noun on
+LogSQLTransferLogFormat
+\noun default
+ directive.
\layout Standard
-Perform some hits on your server and run a select:
+Restart Apache, then perform some hits on your server.
+ Then run the following select statement:
\layout LyX-Code
mysql> select remote_host,request_uri,ssl_cipher,ssl_keysize,ssl_maxkeysize
@@ -5901,30 +6025,52 @@ RC4-MD5
Does mod_log_sql connect to MySQL via TCP/IP or a socket?
\layout Standard
-It depends! This actually is not determined by mod_log_sql.
+It depends! This is not determined by mod_log_sql.
mod_log_sql relies on a connection command that is supplied in the MySQL
API, and that command is somewhat intelligent.
- When mod_log_sql issues the connect command to MySQL, this intelligent
- connect command uses sockets to communicate with MySQL if the specified
- MySQL database is on the same machine (because sockets are more efficient
- than TCP/IP).
- However, if the specified MySQL db is on a different machine, mod_log_sql
- connects using TCP/IP.
- You don't have any control of which methodology is used.
+ How it works:
+\layout Itemize
+
+if the specified MySQL database is on the same machine, the connection command
+ uses a socket to communicate with MySQL
+\layout Itemize
+
+if the specified MySQL database is on a different machine, mod_log_sql connects
+ using TCP/IP.
+
\layout Standard
-You do have control over where mod_log_sql looks for the socket.
+You don't have any control of which methodology is used.
+ You can fine-tune some of the configuration, however.
The
\noun on
LogSQLSocketFile
\noun default
- runtime configuration directive overrides the default of "/var/lib/mysql/mysql.s
-ock" to whatever you wish.
- (Applies to mod_log_sql 1.16 or later only.)
+ runtime configuration directive overrides the default of
+\begin_inset Quotes eld
+\end_inset
+
+/var/lib/mysql/mysql.sock
+\begin_inset Quotes erd
+\end_inset
+
+ for socket-based connections, whereas the
+\noun on
+LogSQLTCPPort
+\noun default
+ command allows to you override the default TCP port of 3306 for TCP/IP
+ connections.
\layout Subsection
-Why do I occasionally see a "lost connection to MySQL server" message in
- my error-log?
+Why do I occasionally see a
+\begin_inset Quotes eld
+\end_inset
+
+lost connection to MySQL server
+\begin_inset Quotes erd
+\end_inset
+
+ message in my error-log?
\layout Standard
This message may appear every now and then in your Apache error log, especially
--
cgit