diff options
Diffstat (limited to 'INSTALL')
-rw-r--r-- | INSTALL | 303 |
1 files changed, 192 insertions, 111 deletions
@@ -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 | ||
4 | Requirements | 4 | Requirements |
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 | |||
37 | the modules right into apache, do that. Both methods work equally | 38 | the modules right into apache, do that. Both methods work equally |
38 | well. | 39 | well. |
39 | 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. | ||
40 | 44 | ||
41 | Installation (as an Apache DSO) | 45 | |
42 | =============================== | 46 | Installation as an Apache DSO (Preferred) |
47 | ========================================= | ||
43 | 48 | ||
44 | For folks interested in using this module as an Apache DSO: | 49 | For 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 | ||
54 | 2) Edit Makefile and make any adjustments for your system. These are | 59 | 2) Edit Makefile for your system. |
55 | fully explained in the Makefile. | ||
56 | 60 | ||
57 | 3) 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 | |||
77 | 3) 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 | 90 | 4) 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 | ||
75 | 4) 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 | ||
82 | 5) Now go to step (9) in the instructions below to configure httpd.conf... | 100 | 5) 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 | ||
85 | Installation (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 | |||
116 | 6) Now skip below to the "Configuration" section. | ||
117 | |||
118 | |||
119 | Installation as a static module compiled into httpd | ||
120 | =================================================== | ||
89 | 121 | ||
90 | 0) Perform all the following steps as root so that you have install | 122 | 0) 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 | ||
98 | 2) Examine the DEFINEs at the top of mod_log_sql.c and alter any that | 130 | 2) 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 | ||
102 | 3) # 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 | ||
108 | 4) # 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 | |||
152 | 3) # make static | ||
153 | |||
154 | 4) # make statinstall | ||
109 | 155 | ||
110 | 5) Change to your Apache source dir. | 156 | 5) 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 | ||
147 | 8) Install your httpd binary. Copy it over your old httpd binary, | 196 | 8) 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 | ||
155 | 9) 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 | 206 | Configuration |
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 | ||
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. | ||
166 | 212 | ||
167 | MySQLLoginInfo dbmachine.foo.com loguser l0gger | 213 | This section will discuss how to get started with a basic config. Full |
168 | MySQLDatabase apache | 214 | documentation of the run-time directives is available here: |
215 | http://www.grubbybaby.com/mod_log_sql/directives.html | ||
169 | 216 | ||
170 | <VirtualHost 1.2.3.4> | 217 | 1) 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 | 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. | ||
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 | ||
189 | 10) 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 | 254 | 3) 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 | ||
212 | 11) Create a specific MySQL userid that httpd will use to authenticate | 263 | 4) 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 | ||
226 | 12) 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. | 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. | ||
234 | 288 | ||
235 | 13) Restart apache. | 289 | <VirtualHost 1.2.3.4> |
290 | [snip] | ||
291 | |||
292 | LogSQLTransferLogTable access_log | ||
293 | |||
294 | [snip] | ||
295 | </VirtualHost> | ||
296 | |||
297 | 6) Restart apache. | ||
236 | 298 | ||
237 | # /etc/rc.d/init.d/httpd start | 299 | # /etc/rc.d/init.d/httpd start |
238 | 300 | ||
239 | 13) Load your web site in a browser to trigger some hits, then confirm that | 301 | 7) 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 | ||
254 | 14) 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 | 320 | 8) 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 | |||
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 | ||