summaryrefslogtreecommitdiffstats
path: root/INSTALL
diff options
context:
space:
mode:
Diffstat (limited to 'INSTALL')
-rw-r--r--INSTALL344
1 files changed, 4 insertions, 340 deletions
diff --git a/INSTALL b/INSTALL
index 20a4035..245f290 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,341 +1,5 @@
1$Id: INSTALL,v 1.10 2002/11/14 03:51:34 helios Exp $ 1$Id: INSTALL,v 1.11 2002/11/14 03:53:08 helios Exp $
2 2
3 3This document has been superseded by the new documentation
4Requirements 4in the Documentation/ directory. There you will find
5============ 5PS, plaintext, and HTML versions of the documentation.
6
7* A compatible system. I have run mod_log_sql on Red Hat based systems
8 (Red Hat, Mandrake). These instructions should easily adapt to any
9 modern distro.
10
11* Apache 1.2 or 1.3 installed. (I run 1.3.22 and it works fine).
12 You should have already successfully compiled Apache and know what
13 you're doing there.
14
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".
18
19* MySQL >= 3.23.15 configured, installed and running on either
20 localhost or an accessible networked machine. You should already
21 have a basic understanding of MySQL and how it functions.
22
23* Again, basic administrative skills with Apache and MySQL. I try to
24 make things as easy as possible in this file, but its purpose is
25 not to be an administrative tutorial.
26
27* Additionally, if you want to be able to log SSL information such as
28 keysize or cipher, you need OpenSSL and glibc-devel installed. Both
29 are available as RPMs.
30
31
32Do I want a DSO?
33================
34You need to know the answer to this question before you proceed. The
35answer is pretty straightforward: what have you done in the past? If
36you like all your Apache modules to be dynamic, then you should keep
37doing that. If you're more of an old-school type and prefer to compile
38the modules right into apache, do that. Both methods work equally
39well.
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.
44
45
46Installation as an Apache DSO (Preferred)
47=========================================
48
49For folks interested in using this module as an Apache DSO:
50
510) Perform all the following steps as root so that you have install
52 privs, etc.
53
541) Unpack the archive into a working directory.
55
56 # tar zxf mod_log_sql.tar.gz -C /usr/local/src
57 # cd /usr/local/src/mod_log_sql
58
592) Edit Makefile for your system.
60
61 NECESSARY:
62 - The location where you installed Apache -- usually /usr/local/apache,
63 'locate apxs' can help you find it.
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
80
81 You should see output similar to the following:
82
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
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
86
87 You should see no errors and have a file called "mod_log_sql.so" in your
88 directory.
89
904) Instruct apxs to install the DSO.
91
92 # make dsoinstall
93
94 You should see output similar to the following:
95
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
99
1005) Module ordering within httpd.conf is important. If you are logging
101 SSL, you must make sure that
102
103 LoadModule ssl_module libexec/libssl.so
104
105 comes before
106
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===================================================
121
1220) Perform all the following steps as root so that you have install
123 privs, etc.
124
1251) Unpack the archive into a working directory.
126
127 # tar zxf mod_log_sql.tar.gz -C /usr/local/src
128 # cd /usr/local/src/mod_log_sql
129
1302) Edit Makefile for your system.
131
132 NECESSARY:
133 - The location where you installed Apache -- usually /usr/local/apache,
134 'locate apxs' can help you find it.
135 - The location of your Apache *sources*, find using 'locate ABOUT_APACHE'
136 - The location of your MySQL header files, find using 'locate mysql.h'
137 - The location of your MySQL libraries, find using 'locate libmysqlclient'
138
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
155
1565) Change to your Apache source dir.
157
158 # cd /usr/local/src/apache-1.3.22/src
159
1606) Re-make your httpd binary as follows.
161
162 6a) Edit Configuration.apaci as follows...
163
164 * Append the following string to the EXTRA_LIBS= line. ("/usr/lib/mysql"
165 is from step 2, where your MySQL libraries live):
166
167 -L/usr/lib/mysql -lmysqlclient -lm -lz
168
169 * Find the mod_log_config.o line, and add this line immediately after it:
170
171 AddModule modules/sql/mod_log_sql.o
172
173 6b) # cp Configuration.apaci Configuration
174
175 6c) # ./Configure
176
177 6d) # make
178
179 6e) # strip httpd
180
1817) Test your new apache binary:
182
183 # ./httpd -l
184
185 You should see something like:
186
187 Compiled-in modules:
188 http_core.c
189 mod_log_sql.c <-- That's the line you're looking for.
190 mod_env.c
191 mod_log_config.c
192 mod_mime.c
193 mod_negotiation.c
194 ...etc...
195
1968) Install your httpd binary. Copy it over your old httpd binary,
197 wherever it lives. You can and should rename your old httpd first so
198 that you can easily revert to that working version in case of bugs
199 with the new version.
200
201 # /etc/rc.d/init.d/httpd stop
202 # mv /usr/local/Apache/bin/httpd ~/httpd-save
203 # cp -f ./httpd /usr/local/Apache/bin/
204
205
206Configuration
207=============
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.
212
213This section will discuss how to get started with a basic config. Full
214documentation of the run-time directives is available here:
215http://www.grubbybaby.com/mod_log_sql/directives.html
216
2171) mod_log_sql can make its own tables on-the-fly, or you can pre-make
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.
221
222 In this basic setup we'll let the module create tables for us.
223
224 We still need to have a logging database created and ready, so
225 run the MySQL command line client and create a database:
226
227 # mysql -uadmin -pmypassword
228 mysql> create database apachelogs;
229
230 If you want to hand-create the tables, run the enclosed 'create-tables'
231 SQL script as follows:
232
233 mysql> source create_tables.sql
234
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.
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.
243
244 mysql> grant insert,create on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger';
245
246 You may be especially security-paranoid and not want "loguser" to have
247 "create" capability within the "apachelogs" databse. You can disable that
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:
251
252 mysql> grant insert on apachelogs.* to loguser@my.apachemachine.com identified by 'l0gger';
253
2543) Enable full logging of your MySQL daemon (at least temporarily
255 for debugging purposes) if you don't do this already:
256
257 Edit /etc/my.cnf and add the following line to your [mysqld] section:
258
259 log=/var/log/mysql-messages
260
261 Then restart MySQL.
262
2634) Tell the module what database to use and the appropriate authentication
264 information.
265
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".
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.
274
275 LogSQLDatabase apachelogs
276 LogSQLLoginInfo dbmachine.foo.com loguser l0gger
277 LogSQLCreateTables on
278
279 If your database resides on localhost instead of another host, specify
280 the MySQL server's socket file as follows:
281
282 LogSQLSocketFile /your/path/to/mysql.sock
283
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.
288
289 <VirtualHost 1.2.3.4>
290 [snip]
291
292 LogSQLTransferLogTable access_log
293
294 [snip]
295 </VirtualHost>
296
2976) Restart apache.
298
299 # /etc/rc.d/init.d/httpd start
300
3017) Load your web site in a browser to trigger some hits, then confirm that
302 the entries are being successfully logged:
303
304 # mysql -hmysql.host.com -umysqladmin -p -e "select * from access_log" apachelogs
305 Enter password:
306
307 +---------------------------------------------------+-------------+-------------+------------------+------------------+------------+--------+------------+------------------------------------+
308 | remote_host | remote_user | request_uri | request_duration | virtual_host | time_stamp | status | bytes_sent | referer |
309 +---------------------------------------------------+-------------+-------------+------------------+------------------+------------+--------+------------+------------------------------------+
310 [snipped lines]
311 .
312 .
313 .
314 +---------------------------------------------------+-------------+-------------+------------------+------------------+------------+--------+------------+------------------------------------+
315
316 You have basic functionality. Don't disable your regular Apache logs until
317 you feel comfortable that the database is behaving as you'd like and that
318 things are going well.
319
3208) If you do not see any entries in the access_log, then something is preventing
321 the inserts from happening. This problem could be caused by several things:
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