Gentoo Archives: gentoo-doc-cvs

From: Jan Kundrat <jkt@××××××××××××.org>
To: gentoo-doc-cvs@l.g.o
Subject: [gentoo-doc-cvs] cvs commit: apache-troubleshooting.xml apache-upgrading.xml
Date: Sun, 23 Mar 2008 11:26:53
Message-Id: E1JdOLf-0001ti-UE@stork.gentoo.org
1 jkt 08/03/23 11:26:47
2
3 Modified: apache-troubleshooting.xml apache-upgrading.xml
4 Log:
5 Files were moved to /proj/en/apache, now for real and with an extra version bump :)
6
7 Revision Changes Path
8 1.8 xml/htdocs/doc/en/apache-troubleshooting.xml
9
10 file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/apache-troubleshooting.xml?rev=1.8&view=markup
11 plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/apache-troubleshooting.xml?rev=1.8&content-type=text/plain
12 diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/apache-troubleshooting.xml?r1=1.7&r2=1.8
13
14 Index: apache-troubleshooting.xml
15 ===================================================================
16 RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/apache-troubleshooting.xml,v
17 retrieving revision 1.7
18 retrieving revision 1.8
19 diff -u -r1.7 -r1.8
20 --- apache-troubleshooting.xml 23 Mar 2008 11:19:46 -0000 1.7
21 +++ apache-troubleshooting.xml 23 Mar 2008 11:26:47 -0000 1.8
22 @@ -1,5 +1,5 @@
23 <?xml version='1.0' encoding="UTF-8"?>
24 -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/apache-troubleshooting.xml,v 1.7 2008/03/23 11:19:46 jkt Exp $ -->
25 +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/apache-troubleshooting.xml,v 1.8 2008/03/23 11:26:47 jkt Exp $ -->
26 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
27
28 <guide link="/doc/en/apache-troubleshooting.xml" lang="en" disclaimer="obsolete" redirect="/proj/en/apache/doc/troubleshooting.xml">
29 @@ -27,423 +27,17 @@
30 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
31 <license/>
32
33 -<version>1.8</version>
34 -<date>2007-11-29</date>
35 +<version>2</version>
36 +<date>2008-03-23</date>
37
38 <chapter>
39 -<title>Checking the Logs</title>
40 +<title>Moved</title>
41 <section>
42 <body>
43
44 <p>
45 -If there is something wrong with your Apache, but you have no idea how to
46 -figure out what's wrong, your first clues will be in the log files.
47 -</p>
48 -
49 -<p>
50 -There are a few log files around. All of them are located inside
51 -<path>/var/log/apache2/</path>. Not all of the following log files will be
52 -on your system: this depends on what modules you have enabled.
53 -</p>
54 -
55 -</body>
56 -</section>
57 -
58 -<section>
59 -<title>access_log and ssl_access_log</title>
60 -<body>
61 -
62 -<pre caption="access_log">
63 -67.185.0.236 - - [18/Jun/2005:12:05:50 -0700] "GET / HTTP/1.0" 200 721
64 -10.0.1.80 - - [18/Jun/2005:12:11:07 -0700] "GET /~jaspenelle/__journal1.jpg HTTP/1.1" 200 19079
65 -66.239.233.163 - - [18/Jun/2005:12:15:06 -0700] "GET /~jaspenelle/avy14.gif HTTP/1.0" 200 1661
66 -67.185.60.155 - - [18/Jun/2005:12:18:48 -0700] "GET / HTTP/1.0" 200 721
67 -67.185.0.236 - - [18/Jun/2005:12:25:39 -0700] "GET / HTTP/1.0" 200 721
68 -10.0.1.80 - - [18/Jun/2005:12:28:04 -0700] "GET /~jaspenelle/avy14.gif HTTP/1.1" 200 1661
69 -10.0.1.80 - - [18/Jun/2005:12:28:46 -0700] "GET /~jaspenelle/avy7.png HTTP/1.1" 200 13066
70 -</pre>
71 -
72 -<p>
73 -This file is simply a listing of every file requested from your server. Unless
74 -you have changed the default configuration, it will be in Common Log Format:
75 -</p>
76 -
77 -<pre caption="Common Log Format syntax">
78 -remotehost rfc931 authuser [date] "request" status bytes
79 -</pre>
80 -
81 -<table>
82 -<tr>
83 - <ti>remotehost</ti>
84 - <ti>Remote host name or IP address</ti>
85 -</tr>
86 -<tr>
87 - <ti>rfc931</ti>
88 - <ti>The remote log name of the user.</ti>
89 -</tr>
90 -<tr>
91 - <ti>authuser</ti>
92 - <ti>The user name as which the user has authenticated himself.</ti>
93 -</tr>
94 -<tr>
95 - <ti>[date]</ti>
96 - <ti>Date and time of the request.</ti>
97 -</tr>
98 -<tr>
99 - <ti>"request"</ti>
100 - <ti>The request line exactly as it came from the client.</ti>
101 -</tr>
102 -<tr>
103 - <ti>status</ti>
104 - <ti>The HTTP status code returned to the client.</ti>
105 -</tr>
106 -<tr>
107 - <ti>bytes</ti>
108 - <ti>The content-length of the document transferred.</ti>
109 -</tr>
110 -</table>
111 -
112 -</body>
113 -</section>
114 -<section>
115 -<title>error_log and ssl_error_log</title>
116 -<body>
117 -
118 -<pre caption="error_log">
119 -[Mon Feb 07 23:33:18 2005] [notice] suEXEC mechanism enabled (wrapper: /usr/sbin/suexec2)
120 -[Mon Feb 07 23:33:18 2005] [notice] Digest: generating secret for digest authentication ...
121 -[Mon Feb 07 23:33:18 2005] [notice] Digest: done
122 -[Mon Feb 07 23:33:18 2005] [notice] Apache/2.0.52 (Gentoo/Linux) PHP/4.3.10 configured -- resuming normal operations
123 -[Sat Jun 18 13:01:54 2005] [error] [client 10.0.1.80] File does not exist: /var/www/localhost/htdocs/favicon.ico
124 -[Sat Jun 18 13:02:14 2005] [error] [client 10.0.1.80] File does not exist: /var/www/localhost/htdocs/favicon.ico
125 -[Sat Jun 18 13:02:18 2005] [error] [client 10.0.1.80] File does not exist: /var/www/localhost/htdocs/favicon.ico
126 -[Sat Jun 18 13:02:21 2005] [error] [client 10.0.1.80] File does not exist: /var/www/localhost/htdocs/favicon.ico
127 -[Sat Jun 18 13:02:24 2005] [error] [client 10.0.1.80] File does not exist: /var/www/localhost/htdocs/favicon.ico
128 -</pre>
129 -
130 -<p>
131 -As you can see, this file can contain a lot of stuff, depending on the
132 -<c>ErrorLevel</c> directive in your <path>httpd.conf</path> file. It tells you
133 -if apache started up correctly, what errors it has run into, ... In general it
134 -will tell you what went wrong. If something isn't working right, this should
135 -be the first file you check for more information.
136 -</p>
137 -
138 -</body>
139 -</section>
140 -<section>
141 -<title>suexec_log</title>
142 -<body>
143 -
144 -<pre caption="suexec_log">
145 -[2005-02-11 22:33:19]: uid: (1000/vericgar) gid: (1000/1000) cmd: test.cgi
146 -[2005-03-11 19:20:13]: uid: (1000/vericgar) gid: (1000/1000) cmd: test.cgi
147 -[2005-03-11 19:34:47]: uid: (1000/vericgar) gid: (1000/1000) cmd: test.cgi
148 -</pre>
149 -
150 -<p>
151 -This file contains a log entry for every time a script is ran using CGI and
152 -suexec. If you can't get a script to work with suexec, this log is the one
153 -to check as it will generally have a line listing why it wouldn't run a script.
154 -</p>
155 -
156 -</body>
157 -</section>
158 -</chapter>
159 -
160 -<chapter>
161 -<title>I installed a module, but it's not working!!!</title>
162 -<section>
163 -<body>
164 -
165 -<p>
166 -Just installing a module is not enough - you have to explicitly turn it on. We
167 -do this so that it's easy to turn on and off individual modules, which makes
168 -it easy to find which module is causing problems and let's you test
169 -modules and disable them easily.
170 -</p>
171 -
172 -<p>
173 -When you install a module, it should display a message similar to this:
174 -</p>
175 -
176 -<pre caption="Post-installation message from emerge">
177 - *
178 - * To enable mod_layout, you need to edit your /etc/conf.d/apache2 file and
179 - * add '-D LAYOUT' to APACHE2_OPTS.
180 - *
181 - *
182 - * Configuration file installed as
183 - * /etc/apache2/modules.d/15_mod_layout.conf
184 - * You may want to edit it before turning the module on in /etc/conf.d/apache2
185 - *
186 -</pre>
187 -
188 -<p>
189 -This is pretty straightforward. It tells you exactly what you need to do to
190 -enable this module.
191 -</p>
192 -
193 -<p>
194 -If you missed this message, there is another way to find out what you need to
195 -add to <c>APACHE2_OPTS</c> in <path>/etc/conf.d/apache2</path>: simply
196 -check the configuration file the module installed. The module's
197 -configuration file should be added to <path>/etc/apache2/modules.d/</path>.
198 -Look for it there and find a line that has <c>IfDefine</c>:
199 -</p>
200 -
201 -<pre caption="An excerpt from 15_mod_layout.conf">
202 -&lt;IfDefine LAYOUT&gt;
203 - &lt;IfModule !mod_layout.c&gt;
204 - LoadModule layout_module modules/mod_layout.so
205 - &lt;/IfModule&gt;
206 -&lt;/IfDefine&gt;
207 -</pre>
208 -
209 -<p>
210 -The <c>IfDefine</c> block is ran when you add <c>-D LAYOUT</c> to
211 -<path>/etc/conf.d/apache2</path>. The <c>LAYOUT</c> is just an example.
212 -</p>
213 -
214 -<p>
215 -There are several options you can add to <c>APACHE2_OPTS</c> that are specified
216 -in the default configuration and well explained in
217 -<path>/etc/conf.d/apache2</path>.
218 -</p>
219 -
220 -<p>
221 -Documentation for all of the built-in modules can be found in the <uri
222 -link="http://httpd.apache.org/docs/2.0/">Apache 2.0 documentation</uri>.
223 -</p>
224 -
225 -</body>
226 -</section>
227 -</chapter>
228 -
229 -<chapter>
230 -<title>Apache is returning zero-length pages or segfaulting</title>
231 -<section>
232 -<body>
233 -
234 -<p>
235 -This happens mostly after an upgrade because binary compatibility
236 -broke in APR (which may happen for a number for reasons). To fix this, you need
237 -to rebuild the Apache tool stack:
238 -</p>
239 -
240 -<pre caption="Rebuilding the Apache tool stack">
241 -<comment>(make sure you do these in order, it's very important!)</comment>
242 -
243 -<comment>(first, we have to remove the currently installed apache)</comment>
244 -# <i>emerge -aCv '=www-servers/apache-2*'</i>
245 -
246 -<comment>(then we rebuild the tool stack)</comment>
247 -# <i>emerge -av '=dev-libs/apr-0*' '=dev-libs/apr-util-0*'</i>
248 -
249 -<comment>(then we reinstall apache)</comment>
250 -# <i>emerge -av '=www-servers/apache-2*'</i>
251 -
252 -<comment>(determine any packages that depend on apache)</comment>
253 -$ <i>equery depends www-servers/apache</i>
254 -[ Searching for packages depending on www-servers/apache... ]
255 -dev-php/phpsysinfo-2.3-r2
256 -dev-php/phpsysinfo-2.1-r2
257 -dev-lang/php-5.2.4_p20070914-r2
258 -net-www/mod_layout-4.0.1a-r1
259 -www-servers/gorg-0.5
260 -
261 -<comment>(then rebuild any modules you have installed)</comment>
262 -# <i>emerge -av '=dev-lang/php-5.2.4_p20070914-r2' '=net-www/mod_layout-4.0.1.a-r1'</i>
263 -</pre>
264 -
265 -</body>
266 -</section>
267 -<section>
268 -<title>Determining a buggy add-on module</title>
269 -<body>
270 -
271 -<p>
272 -If you are still having problems after following the instructions above, the
273 -culprit is most likely one of your installed add-on modules.
274 -</p>
275 -
276 -<p>
277 -Start off by disabling all add-on modules and restarting Apache.
278 -</p>
279 -
280 -<pre caption="Disabling add-on modules">
281 -<comment>(edit /etc/conf.d/apache2)</comment>
282 -
283 -<comment>(before the change)</comment>
284 -APACHE2_OPTS="-D PHP5 -D USERDIR -D SSL"
285 -
286 -<comment>(after the change)</comment>
287 -APACHE2_OPTS=""
288 -</pre>
289 -
290 -<pre caption="Restarting Apache">
291 -# <i>/etc/init.d/apache2 stop</i>
292 -<comment>(make sure apache is completely stopped)</comment>
293 -# <i>ps -A</i>
294 -# <i>/etc/init.d/apache2 start</i>
295 -</pre>
296 -
297 -<note>
298 -You may have to make minor changes to some places of your configuration if you
299 -have added <c>Directive</c>s that these modules provide in places that don't
300 -test for the module being loaded. It's recommended that <c>Directive</c>s
301 -like these be placed in test containers. See any of the .conf files in
302 -<path>/etc/apache2/modules.d</path> examples.
303 -</note>
304 -
305 -<p>
306 -If Apache quits segfaulting and giving blank pages, then you know for sure it
307 -was one of the add-on modules. To figure out which add-on modules, we add them
308 -back, one at a time, completely restarting apache every time.
309 -</p>
310 -
311 -<p>
312 -When Apache stops working after adding a module back, you know that module is
313 -the one that is causing problems. Sometimes, simply rebuilding the module
314 -will fix the problem.
315 -</p>
316 -
317 -<p>
318 -If after rebuilding the module and restarting apache, you are still having
319 -problems with Apache segfaulting or returning blank pages, you should <uri
320 -link="http://bugs.gentoo.org">file a bug</uri> listing the specific version
321 -and revision of the module and mention that it is segfaulting. Be sure to
322 -search for already open bugs first!
323 -</p>
324 -
325 -</body>
326 -</section>
327 -</chapter>
328 -
329 -<chapter>
330 -<title>Webserver doesn't interpret PHP or CGI scripts and returns their code
331 -instead</title>
332 -<section>
333 -<body>
334 -
335 -<p>
336 -Apache sometimes appears to return the PHP or CGI code instead of running those
337 -scripts and returning the script output. If this happens even though the module
338 -is enabled in <path>/etc/conf.d/apache2</path> it's very likely to be a cache
339 -issue. Clearing the webbrowser cache fixes this browser side issue.
340 -</p>
341 -
342 -<p>
343 -Sometimes this problem can also be seen only when accessing the webserver using
344 -it's DNS name but not when accessing the webserver using its IP address. This is
345 -a strong indication that it's a cache issue.
346 -</p>
347 -
348 -<p>
349 -This problem can be fixed by clearing the webbrowser cache and any other
350 -webproxies like squid or wwwoffle.
351 -</p>
352 -
353 -</body>
354 -</section>
355 -</chapter>
356 -
357 -<chapter>
358 -<title>configure: error: changes in the environment can compromise the build</title>
359 -<section>
360 -<body>
361 -
362 -<p>
363 -If you get this error, then you probably have unneeded spaces in your
364 -<c>CFLAGS</c> in <path>/etc/make.conf</path>. The fix is simple, remove the
365 -extra spaces:
366 -</p>
367 -
368 -<pre caption="Example of changes to /etc/make.conf">
369 -<comment>(before the change)</comment>
370 -CFLAGS="-O2 -mcpu=pentium3 -march=pentium3 -pipe"
371 -
372 -<comment>(after the change - notice the removal of the space)</comment>
373 -CFLAGS="-O2 -mcpu=pentium3 -march=pentium3 -pipe"
374 -</pre>
375 -
376 -</body>
377 -</section>
378 -</chapter>
379 -
380 -<chapter>
381 -<title>Address already in use: make_sock: could not bind to address 0.0.0.0:443</title>
382 -<section>
383 -<body>
384 -
385 -<p>
386 -This error occurs during start-up and is caused by having multiple
387 -<c>Listen</c> directives in your configuration that are incompatible. To solve
388 -this problem, you should grep your configuration for <c>Listen</c> and fix each
389 -occurrence.
390 -</p>
391 -
392 -<pre caption="Finding all Listen directives">
393 -<comment>(Make sure you are in the configuration directory)</comment>
394 -# <i>cd /etc/apache2/</i>
395 -
396 -<comment>(List all listen directives)</comment>
397 -# <i>grep Listen httpd.conf vhosts.d/*.conf modules.d/*.conf</i>
398 -</pre>
399 -
400 -<p>
401 -What you are looking for conflicts with what Apache is trying to bind to. For
402 -example, if there is a <c>Listen 80</c> in <path>httpd.conf</path> and there
403 -is a <c>Listen 10.0.0.15:80</c> in another file, then Apache will not be able
404 -to start. This is because Apache first binds to port 80 on all IP addresses
405 -for the machine and then tries to bind to port 80 on IP address 10.0.0.15
406 -and fails because port 80 is already in use.
407 -</p>
408 -
409 -<p>
410 -The recommended configuration is that you have a single <c>Listen 80</c>
411 -(this is in the default <path>httpd.conf</path>) so that you bind to all
412 -addresses by default for the standard HTTP port and then for every SSL
413 -<c>VirtualHost</c> you run you create a separate absolute <c>Listen</c>
414 -directive (such as <c>Listen 10.0.0.15:443</c>).
415 -</p>
416 -
417 -</body>
418 -</section>
419 -</chapter>
420 -
421 -<chapter>
422 -<title>After upgrade to apache-2.0.54-r13 the default vhosts (SSL and non-SSL) don't work any more</title>
423 -<section>
424 -<body>
425 -
426 -<p>
427 -With the upgrade to apache-2.0.54-r13, two new directives were added to it
428 -to fix <uri link="http://bugs.gentoo.org/show_bug.cgi?id=100624">bug
429 -100624</uri>.
430 -</p>
431 -
432 -<p>
433 -The new directives are <c>-D DEFAULT_VHOST</c> to activate the default
434 -virtual host and <c>-D SSL_DEFAULT_VHOST</c> to activate the default SSL
435 -virtual host. Both need to be added to the <c>APACHE2_OPTS</c> variable in
436 -<path>/etc/conf.d/apache2</path> if you want Apache to behave like before.
437 -</p>
438 -
439 -</body>
440 -</section>
441 -</chapter>
442 -
443 -<chapter id="getting-help">
444 -<title>Getting Help</title>
445 -<section>
446 -<body>
447 -
448 -<p>
449 -If none of the above was of any use to you, or if you have other questions,
450 -feel free to stop by our IRC channel, <path>#gentoo-apache</path> on
451 -<path>irc.freenode.net</path>. Or you may also file a bug on <uri
452 -link="http://bugs.gentoo.org">Gentoo's Bugzilla</uri>.
453 +This document has been moved to a <uri
454 +link="/proj/en/apache/doc/troubleshooting.xml">new location</uri>.
455 </p>
456
457 </body>
458
459
460
461 1.14 xml/htdocs/doc/en/apache-upgrading.xml
462
463 file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/apache-upgrading.xml?rev=1.14&view=markup
464 plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/apache-upgrading.xml?rev=1.14&content-type=text/plain
465 diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/apache-upgrading.xml?r1=1.13&r2=1.14
466
467 Index: apache-upgrading.xml
468 ===================================================================
469 RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/apache-upgrading.xml,v
470 retrieving revision 1.13
471 retrieving revision 1.14
472 diff -u -r1.13 -r1.14
473 --- apache-upgrading.xml 23 Mar 2008 11:19:46 -0000 1.13
474 +++ apache-upgrading.xml 23 Mar 2008 11:26:47 -0000 1.14
475 @@ -1,6 +1,6 @@
476 <?xml version='1.0' encoding="UTF-8"?>
477 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
478 -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/apache-upgrading.xml,v 1.13 2008/03/23 11:19:46 jkt Exp $ -->
479 +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/apache-upgrading.xml,v 1.14 2008/03/23 11:26:47 jkt Exp $ -->
480
481 <guide link="/doc/en/apache-upgrading.xml" lang="en" disclaimer="obsolete" redirect="/proj/en/apache/doc/upgrading.xml">
482 <title>Upgrading Apache</title>
483 @@ -24,762 +24,21 @@
484 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
485 <license/>
486
487 -<version>2.8</version>
488 -<date>2007-12-11</date>
489 +<version>3</version>
490 +<date>2008-03-23</date>
491
492 -<chapter id="upgrade-2.2.6-r4">
493 -<title>Upgrading from &lt;2.2.6-r4</title>
494 +<chapter>
495 +<title>Moved</title>
496 <section>
497 <body>
498
499 <p>
500 -The Apache ebuilds have used <path>/etc/apache2/apache2-builtin-mods</path> for
501 -a very long time to select the built-in modules during compile time. However,
502 -this behavior has several disadvantages:
503 -</p>
504 -
505 -<ul>
506 - <li>
507 - Selecting built-in modules during the initial merge is not possible
508 - </li>
509 - <li>
510 - Portage does not know which modules have been installed. This is especially
511 - annoying for binary packages.
512 - </li>
513 - <li>
514 - Portage will try to overwrite <path>apache2-builtin-mods</path> on every
515 - upgrade
516 - </li>
517 -</ul>
518 -
519 -<p>
520 -To rectify this situation <path>/etc/apache2/apache2-builtin-mods</path> has
521 -been deprecated and migrated to the new <c>APACHE2_MODULES</c> <c>USE_EXPAND</c>
522 -variable. To convert your custom module selection to the new format use the
523 -following command:
524 -</p>
525 -
526 -<pre caption="Convert apache2-builtin-mods to APACHE2_MODULES">
527 -$ <i>echo APACHE2_MODULES=\"$(sed '/^mod_/s/mod_\(.*\)\s\+\(shared\|static\)/\1/;t n;d;:n' /etc/apache2/apache2-builtin-mods)\" >> /etc/make.conf</i>
528 -# <i>rm /etc/apache2/apache2-builtin-mods</i>
529 -
530 -<comment>(You can now safely upgrade apache:)</comment>
531 -# <i>emerge -uva '>=www-servers/apache-2.2.6-r4'</i>
532 -</pre>
533 -
534 -<p>
535 -Additionally to the new <c>APACHE2_MODULES</c> the local USE flags have been
536 -cleaned up:
537 -</p>
538 -
539 -<ul>
540 - <li>
541 - All MPM USE flags have been moved to the <c>APACHE2_MPMS</c>
542 - <c>USE_EXPAND</c> variable
543 - </li>
544 - <li>
545 - <c>no-suexec</c> is now <c>suexec</c>
546 - </li>
547 - <li>
548 - <c>static-modules</c> is now <c>static</c>
549 - </li>
550 -</ul>
551 -
552 -<p>
553 -For a detailed description of old and corresponding new USE flags see <uri
554 -link="#use-2.2.6-r4">below</uri>.
555 -</p>
556 -
557 -</body>
558 -</section>
559 -</chapter>
560 -
561 -<chapter id="upgrade-2.0.52-r3">
562 -<title>Upgrading from &lt;2.0.52-r3</title>
563 -<section>
564 -<title>Introduction</title>
565 -<body>
566 -
567 -<p>
568 -The state of Apache and its modules in Gentoo was becoming dismal. There were a
569 -number of problems that caused support problems and made maintaining everything
570 -the Apache herd is responsible for difficult:
571 -</p>
572 -
573 -<ul>
574 - <li>
575 - The configuration that came with Gentoo was dramatically different from
576 - the upstream configuration that most users expect
577 - </li>
578 - <li>
579 - Many modules used similar code, but all did things their own way
580 - </li>
581 - <li>
582 - Most modules weren't maintained very well - mostly because of the large
583 - number of modules available
584 - </li>
585 - <li>Modules didn't have a configuration standard</li>
586 - <li>
587 - Some modules could support both versions of Apache, but the ebuilds
588 - didn't handle that
589 - </li>
590 - <li>
591 - Choices available in Apache were not available for Gentoo users (for
592 - example MPMs)
593 - </li>
594 - <li>Bugs for Apache were stacking up</li>
595 -</ul>
596 -
597 -<p>
598 -This document details how to upgrade without breaking your system. If you are
599 -a developer or would like to know what we changed, or how ebuilds need to be
600 -modified to take advantage of our eclass, then check the <uri
601 -link="/proj/en/apache/apache-developer.xml">Apache Developer Reference</uri>.
602 -</p>
603 -
604 -</body>
605 -</section>
606 -<section>
607 -<title>Upgrading</title>
608 -<body>
609 -
610 -<p>
611 -There have been many changes to how Apache works within Gentoo. Every package
612 -that is directly related to Apache needs to be updated and some things that
613 -worked previously will no longer work.
614 -</p>
615 -
616 -<p>
617 -First you need to figure out what packages you need to upgrade. You can do this
618 -using the <c>equery</c> tool, which is part of the
619 -<c>app-portage/gentoolkit</c> package.
620 -</p>
621 -
622 -<pre caption="Finding packages to update">
623 -$ <i>equery depends www-servers/apache</i>
624 -[ Searching for packages depending on www-servers/apache... ]
625 -dev-db/phpmyadmin-2.5.6
626 -dev-php/mod_php-4.3.10
627 -dev-php/phpsysinfo-2.1-r2
628 -net-www/mod_bandwidth-2.0.5
629 -net-www/mod_layout-4.0.1a
630 -net-www/mod_mp3-0.40
631 -net-www/mod_random-2.0
632 -net-www/mod_throttle-3.1.2-r1
633 -www-apache/mod_ldap_userdir-1.1.4
634 -www-apache/mod_loopback-1.04
635 -www-apache/mod_watch-3.18
636 -www-apps/viewcvs-0.9.2_p20030430
637 -</pre>
638 -
639 -<impo>
640 -The packages you have installed may be vastly different; make sure you run this
641 -command for yourself.
642 -</impo>
643 -
644 -<warn>
645 -There are some modules and packages that depend on Apache that have not yet
646 -been updated. Please <uri link="http://bugs.gentoo.org">search bugzilla</uri>
647 -for any critical packages that you use with Apache.
648 -</warn>
649 -
650 -<p>
651 -Many webapps aren't affected in any way as most use the <c>webapp</c> eclass
652 -which takes care of installing them correctly. You may want to check to see if
653 -there is a new revision.
654 -</p>
655 -
656 -<p>
657 -As we have added some new USE flags, you may want to review them and add
658 -appropriate lines to <path>/etc/portage/package.use</path>. See <uri
659 -link="#use-2.2.6-r4">Apache supported USE flags</uri> for more details.
660 -</p>
661 -
662 -<pre caption="Checking USE flag settings and rebuild">
663 -<comment>(Check the USE flags and needed updates)</comment>
664 -# <i>emerge --pretend --verbose --update --newuse --deep apache subversion \
665 -mod_php mod_bandwidth mod_layout mod_ldap_userdir mod_loopback mod_mp3 \
666 -mod_random mod_throttle mod_watch</i>
667 -
668 -<comment>(Update the packages)</comment>
669 -# <i>emerge --verbose --update --newuse --deep apache subversion mod_php \
670 -mod_bandwidth mod_layout mod_ldap_userdir mod_loopback mod_mp3 mod_random \
671 -mod_throttle mod_watch</i>
672 -
673 -<comment>(It may be easier to just update world instead of the above)</comment>
674 -# <i>emerge --ask --verbose --update --newuse --deep world</i>
675 -</pre>
676 -
677 -<p>
678 -Now you need to reconfigure Apache and its modules. Start by using
679 -<c>etc-update</c> or <c>dispatch-conf</c> to update the <path>/etc/init.d</path>
680 -and <path>/etc/conf.d</path> files. You will notice that your apache
681 -configuration files won't show up in the updates - this is because all the
682 -configuration files have moved.
683 -</p>
684 -
685 -<p>
686 -If you have made changes to the previous default <path>apache.conf</path> and
687 -<path>commonapache.conf</path> you will need to migrate your changes to
688 -<path>/etc/apache{|2}/httpd.conf</path>. Also configuration locations for
689 -modules and virtual hosts have changed -- they are now located in
690 -<path>/etc/apache2/modules.d</path> and <path>/etc/apache2/vhosts.d</path>
691 -respectively.
692 -</p>
693 -
694 -<p>
695 -When you have finished migrating your changes to the new configuration file,
696 -you will need to delete the old configuration files (or move them to a safe
697 -place). The new <path>/etc/init.d/apache{|2}</path> checks for these files and
698 -doesn't let you start apache unless you have removed them, indicating that you
699 -have reconfigured apache using the new paths.
700 -</p>
701 -
702 -<note>
703 -Many modules that used to be enabled by default are now disabled. If they are
704 -apache built-in modules, then uncomment the appropriate line in httpd.conf.
705 -If they are external modules, check the module's .conf for <c>IfDefine</c> and
706 -add the name to <path>/etc/conf.d/apache{|2}</path> to enable it.
707 -</note>
708 -
709 -<p>
710 -Now you may restart apache.
711 -</p>
712 -
713 -<pre caption="Restarting apache">
714 -# <i>/etc/init.d/apache stop</i>
715 -# <i>/etc/init.d/apache start</i>
716 -</pre>
717 -
718 -<p>
719 -If you run into any problems check the <uri
720 -link="/doc/en/apache-troubleshooting.xml">Apache Troubleshooting Guide</uri>
721 -and if that doesn't solve the issue, please report it on <uri
722 -link="http://bugs.gentoo.org">Gentoo Bugzilla</uri>. Be sure to include the
723 -modules you have enabled and (if you are using Apache 2) what MPM USE flag you
724 -compiled with (if any). You may also join <path>#gentoo-apache</path> on
725 -<path>irc.freenode.net</path> for support.
726 +This document has been moved to a <uri
727 +link="/proj/en/apache/doc/upgrading.xml">new location</uri>.
728 </p>
729
730 </body>
731 </section>
732 </chapter>
733
734 -<chapter id="use-pre-2.2.6-r4">
735 -<title>Supported USE flags in &lt;2.2.6-r4</title>
736 -<section>
737 -<body>
738 -
739 -
740 -<p>
741 -There are USE flags that are local to apache and its modules. Apache
742 -supports several other more generic USE flags such as <c>ssl</c>, but the
743 -effect they have on apache doesn't differ much from the effect is has elsewhere,
744 -so it's not included in this list. Run a <c>emerge --verbose --pretend
745 -apache</c> to see the full listing of supported USE flags.
746 -</p>
747 -
748 -<table>
749 -<tr>
750 - <th>USE flag</th>
751 - <th>Description</th>
752 -</tr>
753 -<tr>
754 - <ti>apache2</ti>
755 - <ti>
756 - Should always be set if using the Apache-2.0 line, should not be set if
757 - using the Apache-1.3 line. The eclass uses this to determine what version of
758 - apache to depend on.
759 - </ti>
760 -</tr>
761 -<tr>
762 - <ti>debug</ti>
763 - <ti>
764 - Enables a hook that allows external modules to plug in and do something
765 - after a child crashed. There are already two modules,
766 - <c>mod_whatkilledus</c> and <c>mod_backtrace</c> that make use of this
767 - hook.
768 - </ti>
769 -</tr>
770 -<tr>
771 - <ti>doc</ti>
772 - <ti>
773 - Install the Apache manual and configuration.
774 - </ti>
775 -</tr>
776 -<tr>
777 - <ti>ldap</ti>
778 - <ti>
779 - Install <c>mod_ldap</c> and <c>mod_auth_ldap</c>/<c>mod_authnz_ldap</c>.
780 - </ti>
781 -</tr>
782 -<tr>
783 - <ti>ssl</ti>
784 - <ti>
785 - Installs <c>mod_ssl</c>.
786 - </ti>
787 -</tr>
788 -<tr>
789 - <ti>mpm-itk</ti>
790 - <ti>Builds the <uri link="http://mpm-itk.sesse.net/">itk</uri> MPM</ti>
791 -</tr>
792 -<tr>
793 - <ti>mpm-leader</ti>
794 - <ti>
795 - Builds the <uri
796 - link="http://httpd.apache.org/docs/2.0/mod/leader.html">leader</uri> MPM
797 - </ti>
798 -</tr>
799 -<tr>
800 - <ti>mpm-peruser</ti>
801 - <ti>
802 - Builds the <uri link="http://www.telana.com/peruser.php">peruser</uri> MPM
803 - </ti>
804 -</tr>
805 -<tr>
806 - <ti>mpm-prefork</ti>
807 - <ti>
808 - Builds the <uri
809 - link="http://httpd.apache.org/docs/2.0/mod/prefork.html">prefork</uri>
810 - MPM</ti>
811 -</tr>
812 -<tr>
813 - <ti>mpm-threadpool</ti>
814 - <ti>
815 - Builds the <uri
816 - link="http://httpd.apache.org/docs/2.0/mod/threadpool.html">threadpool</uri>
817 - MPM
818 - </ti>
819 -</tr>
820 -<tr>
821 - <ti>mpm-worker</ti>
822 - <ti>
823 - Builds the <uri
824 - link="http://httpd.apache.org/docs/2.0/mod/worker.html">worker</uri> MPM
825 - </ti>
826 -</tr>
827 -<tr>
828 - <ti>static-modules</ti>
829 - <ti>
830 - Statically links the modules into the apache binary, so that a
831 - LoadModule isn't required for loading the base modules into
832 - Apache.
833 - </ti>
834 -</tr>
835 -</table>
836 -
837 -<note>
838 -While there are many <c>mpm-*</c> USE flags, they are mutually exclusive. You
839 -should enable one and only one of the <c>mpm-*</c> USE flags. (If you do not
840 -enable one, <c>mpm-prefork</c> or <c>mpm-worker</c> will be used, depending on
841 -if the threads USE flag is set.)
842 -</note>
843 -
844 -</body>
845 -</section>
846 -</chapter>
847 -
848 -<chapter id="use-2.2.6-r4">
849 -<title>Supported USE flags in 2.2.6-r4 and above</title>
850 -<section>
851 -<body>
852 -
853 -<p>
854 -With the advent of <c>APACHE2_MODULES</c> a general cleanup of USE flags was
855 -necessary. The following table lists supported USE flags for
856 -<c>apache-2.2.6-r4</c> and above as well as their equivalent in previous
857 -versions.
858 -</p>
859 -
860 -<table>
861 -<tr>
862 - <th>USE flag</th>
863 - <th>Old USE flag</th>
864 - <th>Description</th>
865 -</tr>
866 -<tr>
867 - <ti>debug</ti>
868 - <ti>debug</ti>
869 - <ti>
870 - Enables a hook that allows external modules to plug in and do something
871 - after a child crashed. There are already two modules,
872 - <c>mod_whatkilledus</c> and <c>mod_backtrace</c>, that make use of this
873 - hook.
874 - </ti>
875 -</tr>
876 -<tr>
877 - <ti>doc</ti>
878 - <ti>doc</ti>
879 - <ti>Install the Apache manual and configuration.</ti>
880 -</tr>
881 -<tr>
882 - <ti>ldap</ti>
883 - <ti>ldap</ti>
884 - <ti>Install <c>mod_ldap</c> and <c>mod_authnz_ldap</c></ti>
885 -</tr>
886 -<tr>
887 - <ti>ssl</ti>
888 - <ti>ssl</ti>
889 - <ti>Installs <c>mod_ssl</c></ti>
890 -</tr>
891 -<tr>
892 - <ti>static</ti>
893 - <ti>static-modules</ti>
894 - <ti>
895 - Statically links the modules into the apache binary, so that a LoadModule
896 - isn't required for loading the base modules into Apache
897 - </ti>
898 -</tr>
899 -<tr>
900 - <ti>suexec</ti>
901 - <ti>no-suexec</ti>
902 - <ti>Install <c>mod_suexec</c> and the <c>suexec</c> helper binary</ti>
903 -</tr>
904 -<tr>
905 - <ti>threads</ti>
906 - <ti>threads</ti>
907 - <ti>Selects the default MPM if none is set in APACHE2_MPMS</ti>
908 -</tr>
909 -</table>
910 -
911 -<p>
912 -The following table lists supported <c>APACHE2_MPMS</c> as of
913 -<c>apache-2.2.6-r4</c> and their corresponding previous local USE flag.
914 -</p>
915 -
916 -<table>
917 -<tr>
918 - <th>Flag</th>
919 - <th>Old USE flag</th>
920 - <th>Description</th>
921 -</tr>
922 -<tr>
923 - <ti>event</ti>
924 - <ti>mpm-event</ti>
925 - <ti>An experimental variant of the standard worker MPM</ti>
926 -</tr>
927 -<tr>
928 - <ti>itk</ti>
929 - <ti>mpm-itk</ti>
930 - <ti>Allows to run each virtual host under a separate uid and gid</ti>
931 -</tr>
932 -<tr>
933 - <ti>peruser</ti>
934 - <ti>mpm-peruser</ti>
935 - <ti>
936 - Peruser is a working implementation of the perchild MPM allowing to run each
937 - apache child process as its own user and group, each handling its own set of
938 - virtual hosts
939 - </ti>
940 -</tr>
941 -<tr>
942 - <ti>prefork</ti>
943 - <ti>mpm-prefork</ti>
944 - <ti>Implements a non-threaded, pre-forking web server</ti>
945 -</tr>
946 -<tr>
947 - <ti>worker</ti>
948 - <ti>mpm-worker</ti>
949 - <ti>
950 - Multi-Processing Module implementing a hybrid multi-threaded multi-process
951 - web server
952 - </ti>
953 -</tr>
954 -</table>
955 -
956 -<p>
957 -The following table lists supported <c>APACHE2_MODULES</c> as of
958 -<c>apache-2.2.6-r4</c>.
959 -</p>
960 -
961 -<table>
962 -<tr>
963 - <th>Flag</th>
964 - <th>Description</th>
965 -</tr>
966 -<tr>
967 - <ti>actions</ti>
968 - <ti>
969 - Provides for executing CGI scripts based on media type or request method
970 - </ti>
971 -</tr>
972 -<tr>
973 - <ti>alias</ti>
974 - <ti>
975 - Provides for mapping different parts of the host filesystem in the
976 - document tree and for URL redirection
977 - </ti>
978 -</tr>
979 -<tr>
980 - <ti>asis</ti>
981 - <ti>Sends files that contain their own HTTP headers</ti>
982 -</tr>
983 -<tr>
984 - <ti>auth_basic</ti>
985 - <ti>Basic authentication</ti>
986 -</tr>
987 -<tr>
988 - <ti>auth_digest</ti>
989 - <ti>User authentication using MD5 Digest Authentication</ti>
990 -</tr>
991 -<tr>
992 - <ti>authn_alias</ti>
993 - <ti>
994 - Provides the ability to create extended authentication providers based on
995 - actual providers
996 - </ti>
997 -</tr>
998 -<tr>
999 - <ti>authn_anon</ti>
1000 - <ti>Allows "anonymous" user access to authenticated areas</ti>
1001 -</tr>
1002 -<tr>
1003 - <ti>authn_dbd</ti>
1004 - <ti>User authentication using an SQL database</ti>
1005 -</tr>
1006 -<tr>
1007 - <ti>authn_dbm</ti>
1008 - <ti>User authentication using DBM files</ti>
1009 -</tr>
1010 -<tr>
1011 - <ti>authn_default</ti>
1012 - <ti>Authentication fallback module</ti>
1013 -</tr>
1014 -<tr>
1015 - <ti>authn_file</ti>
1016 - <ti>User authentication using text files</ti>
1017 -</tr>
1018 -<tr>
1019 - <ti>authz_dbm</ti>
1020 - <ti>Group authorization using DBM files</ti>
1021 -</tr>
1022 -<tr>
1023 - <ti>authz_default</ti>
1024 - <ti>Authorization fallback module</ti>
1025 -</tr>
1026 -<tr>
1027 - <ti>authz_groupfile</ti>
1028 - <ti>Group authorization using plaintext files</ti>
1029 -</tr>
1030 -<tr>
1031 - <ti>authz_host</ti>
1032 - <ti>Group authorizations based on host (name or IP address)</ti>
1033 -</tr>
1034 -<tr>
1035 - <ti>authz_owner</ti>
1036 - <ti>Authorization based on file ownership</ti>
1037 -</tr>
1038 -<tr>
1039 - <ti>authz_user</ti>
1040 - <ti>User Authorization</ti>
1041 -</tr>
1042 -<tr>
1043 - <ti>autoindex</ti>
1044 - <ti>
1045 - Generates directory indexes automatically, similar to the Unix <c>ls</c>
1046 - command
1047 - </ti>
1048 -</tr>
1049 -<tr>
1050 - <ti>cache</ti>
1051 - <ti>Content cache keyed to URIs</ti>
1052 -</tr>
1053 -<tr>
1054 - <ti>cern_meta</ti>
1055 - <ti>CERN httpd metafile semantics</ti>
1056 -</tr>
1057 -<tr>
1058 - <ti>charset_lite</ti>
1059 - <ti>Specify character set translation or recoding</ti>
1060 -</tr>
1061 -<tr>
1062 - <ti>dav</ti>
1063 - <ti>Distributed Authoring and Versioning (WebDAV) functionality</ti>
1064 -</tr>
1065 -<tr>
1066 - <ti>dav_fs</ti>
1067 - <ti>filesystem provider for mod_dav</ti>
1068 -</tr>
1069 -<tr>
1070 - <ti>dav_lock</ti>
1071 - <ti>generic locking module for mod_dav</ti>
1072 -</tr>
1073 -<tr>
1074 - <ti>dbd</ti>
1075 - <ti>Manages SQL database connections</ti>
1076 -</tr>
1077 -<tr>
1078 - <ti>deflate</ti>
1079 - <ti>Compress content before it is delivered to the client</ti>
1080 -</tr>
1081 -<tr>
1082 - <ti>dir</ti>
1083 - <ti>
1084 - Provides for "trailing slash" redirects and serving directory index files
1085 - </ti>
1086 -</tr>
1087 -<tr>
1088 - <ti>disk_cache</ti>
1089 - <ti>Content cache storage manager keyed to URIs</ti>
1090 -</tr>
1091 -<tr>
1092 - <ti>dumpio</ti>
1093 - <ti>Dumps all I/O to error log as desired</ti>
1094 -</tr>
1095 -<tr>
1096 - <ti>env</ti>
1097 - <ti>Modifies the environment which is passed to CGI scripts and SSI pages</ti>
1098 -</tr>
1099 -<tr>
1100 - <ti>expires</ti>
1101 - <ti>
1102 - Generation of Expires and Cache-Control HTTP headers according to
1103 - user-specified criteria
1104 - </ti>
1105 -</tr>
1106 -<tr>
1107 - <ti>ext_filter</ti>
1108 - <ti>
1109 - Pass the response body through an external program before delivery to the
1110 - client
1111 - </ti>
1112 -</tr>
1113 -<tr>
1114 - <ti>file_cache</ti>
1115 - <ti>Caches a static list of files in memory</ti>
1116 -</tr>
1117 -<tr>
1118 - <ti>filter</ti>
1119 - <ti>Context-sensitive smart filter configuration module</ti>
1120 -</tr>
1121 -<tr>
1122 - <ti>headers</ti>
1123 - <ti>Customization of HTTP request and response headers</ti>
1124 -</tr>
1125 -<tr>
1126 - <ti>ident</ti>
1127 - <ti>RFC 1413 ident lookups</ti>
1128 -</tr>
1129 -<tr>
1130 - <ti>imagemap</ti>
1131 - <ti>Server-side imagemap processing</ti>
1132 -</tr>
1133 -<tr>
1134 - <ti>include</ti>
1135 - <ti>Server-parsed html documents (Server Side Includes)</ti>
1136 -</tr>
1137 -<tr>
1138 - <ti>info</ti>
1139 - <ti>Provides a comprehensive overview of the server configuration</ti>
1140 -</tr>
1141 -<tr>
1142 - <ti>log_config</ti>
1143 - <ti>Logging of the requests made to the server</ti>
1144 -</tr>
1145 -<tr>
1146 - <ti>log_forensic</ti>
1147 - <ti>Forensic Logging of the requests made to the server</ti>
1148 -</tr>
1149 -<tr>
1150 - <ti>logio</ti>
1151 - <ti>Logging of input and output bytes per request</ti>
1152 -</tr>
1153 -<tr>
1154 - <ti>mem_cache</ti>
1155 - <ti>Content cache keyed to URIs</ti>
1156 -</tr>
1157 -<tr>
1158 - <ti>mime</ti>
1159 - <ti>
1160 - Associates the requested filename's extensions with the file's behavior
1161 - (handlers and filters) and content (mime-type, language, character set and
1162 - encoding)
1163 - </ti>
1164 -</tr>
1165 -<tr>
1166 - <ti>mime_magic</ti>
1167 - <ti>
1168 - Determines the MIME type of a file by looking at a few bytes of its
1169 - contents
1170 - </ti>
1171 -</tr>
1172 -<tr>
1173 - <ti>negotiation</ti>
1174 - <ti>Provides for content negotiation</ti>
1175 -</tr>
1176 -<tr>
1177 - <ti>proxy</ti>
1178 - <ti>HTTP/1.1 proxy/gateway server</ti>
1179 -</tr>
1180 -<tr>
1181 - <ti>proxy_ajp</ti>
1182 - <ti>AJP support module for mod_proxy</ti>
1183 -</tr>
1184 -<tr>
1185 - <ti>proxy_balancer</ti>
1186 - <ti>mod_proxy extension for load balancing</ti>
1187 -</tr>
1188 -<tr>
1189 - <ti>proxy_connect</ti>
1190 - <ti>mod_proxy extension for CONNECT request handling</ti>
1191 -</tr>
1192 -<tr>
1193 - <ti>proxy_ftp</ti>
1194 - <ti>FTP support module for mod_proxy</ti>
1195 -</tr>
1196 -<tr>
1197 - <ti>proxy_http</ti>
1198 - <ti>HTTP support module for mod_proxy</ti>
1199 -</tr>
1200 -<tr>
1201 - <ti>rewrite</ti>
1202 - <ti>
1203 - Provides a rule-based rewriting engine to rewrite requested URLs on the fly
1204 - </ti>
1205 -</tr>
1206 -<tr>
1207 - <ti>setenvif</ti>
1208 - <ti>
1209 - Allows the setting of environment variables based on characteristics of the
1210 - request
1211 - </ti>
1212 -</tr>
1213 -<tr>
1214 - <ti>speling</ti>
1215 - <ti>
1216 - Attempts to correct mistaken URLs that users might have entered by
1217 - ignoring capitalization and by allowing up to one misspelling
1218 - </ti>
1219 -</tr>
1220 -<tr>
1221 - <ti>status</ti>
1222 - <ti>Provides information on server activity and performance</ti>
1223 -</tr>
1224 -<tr>
1225 - <ti>unique_id</ti>
1226 - <ti>
1227 - Provides an environment variable with a unique identifier for each request
1228 - </ti>
1229 -</tr>
1230 -<tr>
1231 - <ti>userdir</ti>
1232 - <ti>User-specific directories</ti>
1233 -</tr>
1234 -<tr>
1235 - <ti>usertrack</ti>
1236 - <ti>Clickstream logging of user activity on a site</ti>
1237 -</tr>
1238 -<tr>
1239 - <ti>version</ti>
1240 - <ti>Version dependent configuration</ti>
1241 -</tr>
1242 -<tr>
1243 - <ti>vhost_alias</ti>
1244 - <ti>Provides for dynamically configured mass virtual hosting</ti>
1245 -</tr>
1246 -</table>
1247 -
1248 -</body>
1249 -</section>
1250 -</chapter>
1251 </guide>
1252
1253
1254
1255 --
1256 gentoo-doc-cvs@l.g.o mailing list