diff options
Diffstat (limited to 'INSTALL')
-rw-r--r-- | INSTALL | 344 |
1 files changed, 4 insertions, 340 deletions
@@ -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 | 3 | This document has been superseded by the new documentation | |
4 | Requirements | 4 | in the Documentation/ directory. There you will find |
5 | ============ | 5 | PS, 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 | |||
32 | Do I want a DSO? | ||
33 | ================ | ||
34 | You need to know the answer to this question before you proceed. The | ||
35 | answer is pretty straightforward: what have you done in the past? If | ||
36 | you like all your Apache modules to be dynamic, then you should keep | ||
37 | doing that. If you're more of an old-school type and prefer to compile | ||
38 | the modules right into apache, do that. Both methods work equally | ||
39 | well. | ||
40 | |||
41 | FWIW, the DSO method is more modern and increasing in popularity because | ||
42 | apxs takes care of a lot of dirty little details for you. As you'll | ||
43 | see below, the static-module method is a little more complex. | ||
44 | |||
45 | |||
46 | Installation as an Apache DSO (Preferred) | ||
47 | ========================================= | ||
48 | |||
49 | For folks interested in using this module as an Apache DSO: | ||
50 | |||
51 | 0) Perform all the following steps as root so that you have install | ||
52 | privs, etc. | ||
53 | |||
54 | 1) 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 | |||
59 | 2) 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 | |||
77 | 3) 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 | |||
90 | 4) 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 | |||
100 | 5) 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 | |||
116 | 6) Now skip below to the "Configuration" section. | ||
117 | |||
118 | |||
119 | Installation as a static module compiled into httpd | ||
120 | =================================================== | ||
121 | |||
122 | 0) Perform all the following steps as root so that you have install | ||
123 | privs, etc. | ||
124 | |||
125 | 1) 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 | |||
130 | 2) 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 | |||
152 | 3) # make static | ||
153 | |||
154 | 4) # make statinstall | ||
155 | |||
156 | 5) Change to your Apache source dir. | ||
157 | |||
158 | # cd /usr/local/src/apache-1.3.22/src | ||
159 | |||
160 | 6) 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 | |||
181 | 7) 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 | |||
196 | 8) 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 | |||
206 | Configuration | ||
207 | ============= | ||
208 | |||
209 | You have to prepare the database to receive data from mod_log_sql, and | ||
210 | set up run-time directives in httpd.conf to control how and what mod_log_sql | ||
211 | logs. | ||
212 | |||
213 | This section will discuss how to get started with a basic config. Full | ||
214 | documentation of the run-time directives is available here: | ||
215 | http://www.grubbybaby.com/mod_log_sql/directives.html | ||
216 | |||
217 | 1) 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 | |||
235 | 2) 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 | |||
254 | 3) 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 | |||
263 | 4) 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 | |||
284 | 5) 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 | |||
297 | 6) Restart apache. | ||
298 | |||
299 | # /etc/rc.d/init.d/httpd start | ||
300 | |||
301 | 7) 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 | |||
320 | 8) 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 | |||
339 | 9) 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 | ||