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 - + + + + \begin_inset Text @@ -1600,6 +1725,30 @@ remote_host request_uri \end_inset + +\begin_inset Text + +\layout Standard + +time_stamp +\end_inset + + +\begin_inset Text + +\layout Standard + +status +\end_inset + + +\begin_inset Text + +\layout Standard + +bytes_sent +\end_inset + @@ -1607,7 +1756,7 @@ request_uri \layout Standard -XYZ123 +PPIDskBRH30AAGPtAsg \end_inset @@ -1615,7 +1764,7 @@ XYZ123 \layout Standard -foo.bar.com +zerberus.aiacs.net \end_inset @@ -1626,6 +1775,30 @@ foo.bar.com /index.html \end_inset + +\begin_inset Text + +\layout Standard + +1022493617 +\end_inset + + +\begin_inset Text + +\layout Standard + +200 +\end_inset + + +\begin_inset Text + +\layout Standard + +2215 +\end_inset + @@ -1688,7 +1861,7 @@ val \layout Standard -XYZ123 +PPIDskBRH30AAGPtAsg \end_inset @@ -1714,7 +1887,7 @@ OK \layout Standard -XYZ123 +PPIDskBRH30AAGPtAsg \end_inset @@ -1798,7 +1971,7 @@ val \layout Standard -XYZ123 +PPIDskBRH30AAGPtAsg \end_inset @@ -1824,7 +1997,7 @@ text/html \layout Standard -XYZ123 +PPIDskBRH30AAGPtAsg \end_inset @@ -1850,7 +2023,7 @@ gzip, deflate \layout Standard -XYZ123 +PPIDskBRH30AAGPtAsg \end_inset @@ -1876,7 +2049,7 @@ Tue, 28 May 2002 10:00:18 GMT \layout Standard -XYZ123 +PPIDskBRH30AAGPtAsg \end_inset @@ -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 @@ -2027,7 +2200,7 @@ mod_gzip_result \layout Standard -DECLINED:EXCLUDED +OK \end_inset @@ -2045,7 +2218,7 @@ zerberus.aiacs.net \layout Standard -/mod_log_sql/style_1.css +/mod_log_sql/index.html \end_inset @@ -2061,7 +2234,7 @@ mod_gzip_compression_ratio \layout Standard -0 +69 \end_inset @@ -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 @@ -2154,83 +2336,6 @@ LogSQLTransferLogTable. \layout LyX-Code -\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 \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