summaryrefslogtreecommitdiffstats
path: root/INSTALL
diff options
context:
space:
mode:
Diffstat (limited to 'INSTALL')
-rw-r--r--INSTALL303
1 files changed, 192 insertions, 111 deletions
diff --git a/INSTALL b/INSTALL
index 7c48c21..20a4035 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,26 +1,27 @@
1$Id: INSTALL,v 1.9 2002/06/27 20:09:17 helios Exp $ 1$Id: INSTALL,v 1.10 2002/11/14 03:51:34 helios Exp $
2 2
3 3
4Requirements 4Requirements
5============ 5============
6 6
7* I run a Red Hat 6.2 system, but these instructions should easily 7* A compatible system. I have run mod_log_sql on Red Hat based systems
8 adapt to any modern distro. 8 (Red Hat, Mandrake). These instructions should easily adapt to any
9 modern distro.
9 10
10* Apache 1.2 or 1.3 installed. (I run 1.3.22 and it works fine). 11* Apache 1.2 or 1.3 installed. (I run 1.3.22 and it works fine).
11 You should have already successfully compiled Apache and know what 12 You should have already successfully compiled Apache and know what
12 you're doing there. In fact, you should already have any other 13 you're doing there.
13 modules and add-ons like mod_ssl or PHP configured and installed
14 before you start this process.
15 14
16* The MySQL development headers. (I run MySQL-devel-3.23.44-1.i386.rpm). 15* The MySQL development headers. This is called different things on
16 different distros. For example, Red Hat 6.x called this RPM
17 "MySQL-devel" whereas Mandrake calls it "libmysql10-devel".
17 18
18* MySQL >= 3.23.15 configured, installed and running on either 19* MySQL >= 3.23.15 configured, installed and running on either
19 localhost or an accessible networked machine. You should already 20 localhost or an accessible networked machine. You should already
20 have a basic understanding of MySQL and how it functions. 21 have a basic understanding of MySQL and how it functions.
21 22
22* Again, basic administrative skills with Apache and MySQL. I try to 23* Again, basic administrative skills with Apache and MySQL. I try to
23 make things as easy as possible in this README, but its purpose is 24 make things as easy as possible in this file, but its purpose is
24 not to be an administrative tutorial. 25 not to be an administrative tutorial.
25 26
26* Additionally, if you want to be able to log SSL information such as 27* Additionally, if you want to be able to log SSL information such as
@@ -37,9 +38,13 @@ doing that. If you're more of an old-school type and prefer to compile
37the modules right into apache, do that. Both methods work equally 38the modules right into apache, do that. Both methods work equally
38well. 39well.
39 40
41FWIW, the DSO method is more modern and increasing in popularity because
42apxs takes care of a lot of dirty little details for you. As you'll
43see below, the static-module method is a little more complex.
40 44
41Installation (as an Apache DSO) 45
42=============================== 46Installation as an Apache DSO (Preferred)
47=========================================
43 48
44For folks interested in using this module as an Apache DSO: 49For folks interested in using this module as an Apache DSO:
45 50
@@ -51,41 +56,68 @@ For folks interested in using this module as an Apache DSO:
51 # tar zxf mod_log_sql.tar.gz -C /usr/local/src 56 # tar zxf mod_log_sql.tar.gz -C /usr/local/src
52 # cd /usr/local/src/mod_log_sql 57 # cd /usr/local/src/mod_log_sql
53 58
542) Edit Makefile and make any adjustments for your system. These are 592) Edit Makefile for your system.
55 fully explained in the Makefile.
56 60
573) Instruct apxs to compile and install the module as a DSO. You need 61 NECESSARY:
58 to know two things before you run apxs: 62 - The location where you installed Apache -- usually /usr/local/apache,
59 - The location of the apxs binary, find using 'locate apxs' 63 'locate apxs' can help you find it.
60 - The location of your MySQL libraries, find using 'locate libmysqlclient' 64 - The location of your MySQL libraries, find using 'locate libmysqlclient'
65 - The location of your MySQL header files, find using 'locate mysql.h'
66
67 OPTIONAL if you have included mod_ssl in Apache and want to log SSL data
68 such as keysize and cipher type:
69 - The location of your SSL header files, find using 'locate mod_ssl.h'
70
71 Now that you know these things, edit Makefile and replace the stock
72 values with your own.
73
74 IMPORTANT: If you are not logging SSL info, comment out MODSSLHDRS by putting
75 a # character in front of it, e.g. #MODSSLHDRS=/usr/include/...
76
773) Instruct apxs to compile the module as a DSO.
78
79 # make dso
61 80
62 FORMAT: 81 You should see output similar to the following:
63 # <path>/apxs -i -c -L/path/to/mysqllibs -lmysqlclient -lz mod_log_sql.c
64 82
65 EXAMPLE: 83 /usr/local/Apache/bin/apxs -Wc,-O2 -Wc,-Wall -Wc,-DEAPI -c -I/usr/include/mysql -I/usr/local/src/apache_1.3.27-dso/src/modules/ssl -L/usr/lib -lmysqlclient -lz mod_log_sql.c
66 # /usr/sbin/apxs -i -c -L/usr/lib/mysql -lmysqlclient -lz mod_log_sql.c 84 gcc -DLINUX=22 -DNO_DBM_REWRITEMAP -DMOD_SSL=208111 -DUSE_HSREGEX -DEAPI -DUSE_EXPAT -I../lib/expat-lite -fpic -DSHARED_CORE -DSHARED_MODULE -I/usr/local/Apache/include -O2 -Wall -DEAPI -I/usr/include/mysql -I/usr/local/src/apache_1.3.27-dso/src/modules/ssl -c mod_log_sql.c
85 gcc -shared -o mod_log_sql.so mod_log_sql.o -Wc,-O2 -Wc,-Wall -Wc,-DEAPI -L/usr/lib -lmysqlclient -lz -lm -lcrypt -ldb
67 86
68 You should see something similar to this: 87 You should see no errors and have a file called "mod_log_sql.so" in your
88 directory.
69 89
70 gcc -fpic -DSHARED_MODULE -I/usr/local/apache/include -c mod_log_mysql.c 904) Instruct apxs to install the DSO.
71 gcc -shared -o mod_log_mysql.so mod_log_mysql.o -L/usr/local/lib/mysql/ -lmysqlclient -lz
72 cp mod_log_mysql.so /usr/local/apache/libexec/mod_log_mysql.so
73 chmod 755 /usr/local/apache/libexec/mod_log_mysql.so
74 91
754) Add the following lines to your httpd.conf file. Put the second line 92 # make dsoinstall
76 somewhere after the ClearModuleList directive.
77 93
78 LoadModule mysql_log_module libexec/mod_log_sql.so 94 You should see output similar to the following:
79 95
80 AddModule mod_log_sql.c 96 /usr/local/Apache/bin/apxs -i mod_log_sql.so
97 cp mod_log_sql.so /usr/local/Apache/libexec/mod_log_sql.so
98 chmod 755 /usr/local/Apache/libexec/mod_log_sql.so
81 99
825) Now go to step (9) in the instructions below to configure httpd.conf... 1005) Module ordering within httpd.conf is important. If you are logging
101 SSL, you must make sure that
83 102
103 LoadModule ssl_module libexec/libssl.so
84 104
85Installation (as a static module compiled into httpd) 105 comes before
86=====================================================
87 106
88[This is what I do, FYI.] 107 LoadModule sql_log_module libexec/mod_log_sql.so
108
109 If you don't, you will get this error when you start Apache:
110 /usr/local/apache/libexec/mod_log_mysql.so: undefined symbol: ssl_var_lookup
111 /usr/local/apache/bin/apachectl startssl: httpd could not be started
112
113 (Because mod_log_sql doesn't yet have the required symbols that mod_ssl
114 provides.)
115
1166) Now skip below to the "Configuration" section.
117
118
119Installation as a static module compiled into httpd
120===================================================
89 121
900) Perform all the following steps as root so that you have install 1220) Perform all the following steps as root so that you have install
91 privs, etc. 123 privs, etc.
@@ -95,17 +127,31 @@ Installation (as a static module compiled into httpd)
95 # tar zxf mod_log_sql.tar.gz -C /usr/local/src 127 # tar zxf mod_log_sql.tar.gz -C /usr/local/src
96 # cd /usr/local/src/mod_log_sql 128 # cd /usr/local/src/mod_log_sql
97 129
982) Examine the DEFINEs at the top of mod_log_sql.c and alter any that 1302) Edit Makefile for your system.
99 you choose. Edit Makefile and make any adjustments for your system.
100 These are fully explained in the Makefile.
101 131
1023) # make all 132 NECESSARY:
103 (You should receive NO warnings or errors of any kind. 133 - The location where you installed Apache -- usually /usr/local/apache,
104 If you see messages like this: "mod_log_sql.c:69: httpd.h: No such 134 'locate apxs' can help you find it.
105 file or directory" then you do not have your CFLAGS correctly 135 - The location of your Apache *sources*, find using 'locate ABOUT_APACHE'
106 pointing to the right include directory.) 136 - The location of your MySQL header files, find using 'locate mysql.h'
137 - The location of your MySQL libraries, find using 'locate libmysqlclient'
107 138
1084) # make install 139 OPTIONAL if you have included mod_ssl in Apache and want to log SSL data
140 such as keysize and cipher type:
141 - The location of your mod_ssl header files, find using 'locate mod_ssl.h'
142 - The location of your OpenSSL header files, find using 'locate x509.h'
143 - The location of your db1 header files, find using 'locate mpool.h'
144
145 Now that you know these things, edit Makefile and replace the stock
146 values with your own.
147
148 IMPORTANT: If you are not logging SSL info, comment out MODSSLHDRS,
149 OPNSSLHDRS and DB1HDRS by putting a # character in front of each one,
150 e.g. #OPNSSLHDRS=/usr/include/...
151
1523) # make static
153
1544) # make statinstall
109 155
1105) Change to your Apache source dir. 1565) Change to your Apache source dir.
111 157
@@ -115,11 +161,14 @@ Installation (as a static module compiled into httpd)
115 161
116 6a) Edit Configuration.apaci as follows... 162 6a) Edit Configuration.apaci as follows...
117 163
118 * Append the following string to the EXTRA_LIBS= line. (/usr/lib/mysql is where your libmysqlclient.a file lives): 164 * Append the following string to the EXTRA_LIBS= line. ("/usr/lib/mysql"
119 -L/usr/lib/mysql -lmysqlclient -lm -lz 165 is from step 2, where your MySQL libraries live):
166
167 -L/usr/lib/mysql -lmysqlclient -lm -lz
120 168
121 * Find the mod_log_config.o line, and add this line immediately after it: 169 * Find the mod_log_config.o line, and add this line immediately after it:
122 AddModule modules/sql/mod_log_sql.o 170
171 AddModule modules/sql/mod_log_sql.o
123 172
124 6b) # cp Configuration.apaci Configuration 173 6b) # cp Configuration.apaci Configuration
125 174
@@ -146,100 +195,113 @@ Installation (as a static module compiled into httpd)
146 195
1478) Install your httpd binary. Copy it over your old httpd binary, 1968) Install your httpd binary. Copy it over your old httpd binary,
148 wherever it lives. You can and should rename your old httpd first so 197 wherever it lives. You can and should rename your old httpd first so
149 that you can easily revert to that working version in case of bugs or 198 that you can easily revert to that working version in case of bugs
150 whatever. 199 with the new version.
151 200
152 # /etc/rc.d/init.d/httpd stop 201 # /etc/rc.d/init.d/httpd stop
202 # mv /usr/local/Apache/bin/httpd ~/httpd-save
153 # cp -f ./httpd /usr/local/Apache/bin/ 203 # cp -f ./httpd /usr/local/Apache/bin/
154 204
1559) Configure your apache daemon to log to your database. Here's a very
156 basic set of config lines to start you off. Full documentation is
157 available here: http://www.grubbybaby.com/mod_log_sql/directives.html
158 205
159 EXAMPLE: Connect to the MySQL database called "apache" running 206Configuration
160 on "dbmachine.foo.com". The module uses username "loguser" and 207=============
161 password "l0gger" to authenticate to the database; this user must,
162 of course, exist in the MySQL user table and have the proper
163 permissions -- more on that in step 11. The log entries will be
164 INSERTed into the table called "access_log".
165 208
209You have to prepare the database to receive data from mod_log_sql, and
210set up run-time directives in httpd.conf to control how and what mod_log_sql
211logs.
166 212
167 MySQLLoginInfo dbmachine.foo.com loguser l0gger 213This section will discuss how to get started with a basic config. Full
168 MySQLDatabase apache 214documentation of the run-time directives is available here:
215http://www.grubbybaby.com/mod_log_sql/directives.html
169 216
170 <VirtualHost 1.2.3.4> 2171) mod_log_sql can make its own tables on-the-fly, or you can pre-make
171 [snip] 218 the tables by hand. The advantage of letting the module make the
219 tables is ease-of-use, but for raw performance you will want to
220 pre-make the tables in order to save overhead.
172 221
173 MySQLTransferLogTable access_log 222 In this basic setup we'll let the module create tables for us.
174 MySQLTransferLogFormat huSUsbTvRA
175 223
176 [snip] 224 We still need to have a logging database created and ready, so
177 </VirtualHost> 225 run the MySQL command line client and create a database:
178 226
227 # mysql -uadmin -pmypassword
228 mysql> create database apachelogs;
179 229
180 9a) Special step for users who have a DSO-enabled httpd: 230 If you want to hand-create the tables, run the enclosed 'create-tables'
231 SQL script as follows:
181 232
182 If you you are building mod_log_sql as a static module BUT 233 mysql> source create_tables.sql
183 your httpd is enabled for DSOs, add the following line to your
184 httpd.conf:
185 234
186 AddModule mod_log_sql.c 2352) Create a specific MySQL userid that httpd will use to authenticate
236 and enter data. This userid need not be an actual Unix user. It
237 is a userid internal to MySQL with specific privileges.
187 238
239 In the following example command, "apachelogs" is the database, "loguser"
240 is the userid to create, "my.apachemachine.com" is the name of the Apache
241 machine, and "l0gger" is the password to assign. Choose values that are
242 different from these examples.
188 243
18910) If you compiled mod_log_sql with the ability to make its own tables 244 mysql> grant insert,create on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger';
190 then you can skip this step. Otherwise you need to do it by hand:
191 245
192 Create a database and table to hold the new log data. I log the 246 You may be especially security-paranoid and not want "loguser" to have
193 same data as the regular "combined log" plus a little extra information 247 "create" capability within the "apachelogs" databse. You can disable that
194 that can be useful. 248 but the cost is that you cannot use the module's automatic-table-creation
249 feature. If that's an acceptable cost, hand-create the tables as described
250 in step 1 and use the following GRANT statement instead of the one above:
195 251
196 The order that the fields appear in the table is irrelevant 252 mysql> grant insert on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger';
197 because you can SELECT them in any order you choose. To create
198 this table I first created a new database called "apache":
199 253
200 # mysql -uadmin -pmypassword 2543) Enable full logging of your MySQL daemon (at least temporarily
201 mysql> create database apache; 255 for debugging purposes) if you don't do this already:
202 256
203 Then create the table called "access_log". I enclosed an SQL file 257 Edit /etc/my.cnf and add the following line to your [mysqld] section:
204 that will create every column type that mod_log_sql supports.
205 Unless you're just testing or playing around, this is probably NOT
206 what you want, so edit the file first and delete the lines that
207 don't pertain to you. Then:
208 258
209 mysql> source access_log.sql 259 log=/var/log/mysql-messages
210 260
261 Then restart MySQL.
211 262
21211) Create a specific MySQL userid that httpd will use to authenticate 2634) Tell the module what database to use and the appropriate authentication
213 and enter data. This userid need not be an actual Unix user. It 264 information.
214 is a userid internal to MySQL with specific privileges.
215
216 mysql> grant insert,create on apache.* to loguser@my.apachemachine.com identified by 'l0gger';
217
218 Security is a very real concern. mod_log_sql by default is
219 set up to create the SQL tables it needs. If you have deactivated
220 this capability, then create a user called "loguser" with the password
221 "l0gger" with only the capability of INSERT to "access_log":
222 265
223 mysql> grant insert on apache.access_log to loguser@my.apachemachine.com identified by 'l0gger'; 266 OUR EXAMPLE: use the MySQL database called "apachelogs" running
267 on "dbmachine.foo.com". The module uses username "loguser" and
268 password "l0gger" to authenticate to the database. The log entries
269 will be INSERTed into the table called "access_log".
224 270
271 So, edit httpd.conf and insert the following lines somewhere AFTER any
272 LoadModule / AddModule statements. Make sure these statements are
273 "global," i.e. not inside any VirtualHost stanza.
225 274
22612) Enable full logging of your MySQL daemon (at least temporarily 275 LogSQLDatabase apachelogs
227 for debugging purposes) if you don't do this already: 276 LogSQLLoginInfo dbmachine.foo.com loguser l0gger
277 LogSQLCreateTables on
228 278
229 Edit /etc/my.cnf and add the following line to your [mysqld] section: 279 If your database resides on localhost instead of another host, specify
280 the MySQL server's socket file as follows:
230 281
231 log=/var/log/mysql-messages 282 LogSQLSocketFile /your/path/to/mysql.sock
232 283
233 Then restart MySQL. 2845) The actual logging is set up on a virtual-host-by-host basis. So,
285 skip down to the virtual host you want to set up. The LogSQLTransferLogTable
286 directive is the minimum required to log -- other directives simply
287 tune the module's behavior.
234 288
23513) Restart apache. 289 <VirtualHost 1.2.3.4>
290 [snip]
291
292 LogSQLTransferLogTable access_log
293
294 [snip]
295 </VirtualHost>
296
2976) Restart apache.
236 298
237 # /etc/rc.d/init.d/httpd start 299 # /etc/rc.d/init.d/httpd start
238 300
23913) Load your web site in a browser to trigger some hits, then confirm that 3017) Load your web site in a browser to trigger some hits, then confirm that
240 the entries are being successfully logged: 302 the entries are being successfully logged:
241 303
242 # mysql -hmysql.host.com -umysqladmin -p -e "select * from access_log" apache; 304 # mysql -hmysql.host.com -umysqladmin -p -e "select * from access_log" apachelogs
243 Enter password: 305 Enter password:
244 306
245 +---------------------------------------------------+-------------+-------------+------------------+------------------+------------+--------+------------+------------------------------------+ 307 +---------------------------------------------------+-------------+-------------+------------------+------------------+------------+--------+------------+------------------------------------+
@@ -251,10 +313,29 @@ Installation (as a static module compiled into httpd)
251 . 313 .
252 +---------------------------------------------------+-------------+-------------+------------------+------------------+------------+--------+------------+------------------------------------+ 314 +---------------------------------------------------+-------------+-------------+------------------+------------------+------------+--------+------------+------------------------------------+
253 315
25414) You have basic functionality. Don't disable your regular Apache logs until 316 You have basic functionality. Don't disable your regular Apache logs until
255 you feel comfortable that the database is behaving as you'd like and that 317 you feel comfortable that the database is behaving as you'd like and that
256 things are going well. 318 things are going well.
257 319
258 3208) If you do not see any entries in the access_log, then something is preventing
259 321 the inserts from happening. This problem could be caused by several things:
260 322 - Improper privileges set up in the MySQL database
323 - You aren't hitting a VirtualHost that has a LogSQLTransferLogTable entry
324 - You didn't specify the right host
325
326 If you have confirmed your LogSQL* directives and know them to be correct,
327 you should examine the httpd server logs for mod_log_sql messages; the module
328 will offer hints as to why it cannot connect, etc. Also examine the MySQL
329 log that you established in step 3. Ensure that the INSERTs are not being
330 rejected because of a malformed table entry or other clerical error. If you
331 see no INSERT attempts in the log, the module isn't successfully connecting
332 to the database.
333
334 The next thing to do is recompile the module with debugging output activated.
335 change the "#undef DEBUG" on line 8 of mod_log_sql.c to "#define DEBUG" and
336 recompile/reinstall. The module will now output copious notes about what
337 it is doing, and this will help you (and the maintainer) solve the problem.
338
3399) You can now activate the advanced features of mod_log_sql. These are all
340 described in the online directive documentation:
341 http://www.grubbybaby.com/mod_log_sql/directives.html