Troubleshooting Apache

1.  Checking the Logs

If there is something wrong with your Apache, but you have no idea how to figure out what's wrong, your first clues will be in the log files.

There are a few log files around. All of them are located inside /var/log/apache2/. Not all of the following log files will be on your system: this depends on what modules you have enabled.

access_log and ssl_access_log

67.185.0.236 - - [18/Jun/2005:12:05:50 -0700] "GET / HTTP/1.0" 200 721
10.0.1.80 - - [18/Jun/2005:12:11:07 -0700] "GET /~jaspenelle/__journal1.jpg HTTP/1.1" 200 19079
66.239.233.163 - - [18/Jun/2005:12:15:06 -0700] "GET /~jaspenelle/avy14.gif HTTP/1.0" 200 1661
67.185.60.155 - - [18/Jun/2005:12:18:48 -0700] "GET / HTTP/1.0" 200 721
67.185.0.236 - - [18/Jun/2005:12:25:39 -0700] "GET / HTTP/1.0" 200 721
10.0.1.80 - - [18/Jun/2005:12:28:04 -0700] "GET /~jaspenelle/avy14.gif HTTP/1.1" 200 1661
10.0.1.80 - - [18/Jun/2005:12:28:46 -0700] "GET /~jaspenelle/avy7.png HTTP/1.1" 200 13066

This file is simply a listing of every file requested from your server. Unless you have changed the default configuration, it will be in Common Log Format:

remotehost rfc931 authuser [date] "request" status bytes

error_log and ssl_error_log

[Mon Feb 07 23:33:18 2005] [notice] suEXEC mechanism enabled (wrapper: /usr/sbin/suexec2)
[Mon Feb 07 23:33:18 2005] [notice] Digest: generating secret for digest authentication ...
[Mon Feb 07 23:33:18 2005] [notice] Digest: done
[Mon Feb 07 23:33:18 2005] [notice] Apache/2.0.52 (Gentoo/Linux) PHP/4.3.10 configured -- resuming normal operations
[Sat Jun 18 13:01:54 2005] [error] [client 10.0.1.80] File does not exist: /var/www/localhost/htdocs/favicon.ico
[Sat Jun 18 13:02:14 2005] [error] [client 10.0.1.80] File does not exist: /var/www/localhost/htdocs/favicon.ico
[Sat Jun 18 13:02:18 2005] [error] [client 10.0.1.80] File does not exist: /var/www/localhost/htdocs/favicon.ico
[Sat Jun 18 13:02:21 2005] [error] [client 10.0.1.80] File does not exist: /var/www/localhost/htdocs/favicon.ico
[Sat Jun 18 13:02:24 2005] [error] [client 10.0.1.80] File does not exist: /var/www/localhost/htdocs/favicon.ico

As you can see, this file can contain a lot of stuff, depending on the ErrorLevel directive in your httpd.conf file. It tells you if apache started up correctly, what errors it has run into, ... In general it will tell you what went wrong. If something isn't working right, this should be the first file you check for more information.

suexec_log

[2005-02-11 22:33:19]: uid: (1000/vericgar) gid: (1000/1000) cmd: test.cgi
[2005-03-11 19:20:13]: uid: (1000/vericgar) gid: (1000/1000) cmd: test.cgi
[2005-03-11 19:34:47]: uid: (1000/vericgar) gid: (1000/1000) cmd: test.cgi

This file contains a log entry for every time a script is ran using CGI and suexec. If you can't get a script to work with suexec, this log is the one to check as it will generally have a line listing why it wouldn't run a script.

2.  I installed a module, but it's not working!!!

Just installing a module is not enough - you have to explicitly turn it on. We do this so that it's easy to turn on and off individual modules, which makes it easy to find which module is causing problems and let's you test modules and disable them easily.

When you install a module, it should display a message similar to this:

 * 
 * To enable mod_layout, you need to edit your /etc/conf.d/apache2 file and
 * add '-D LAYOUT' to APACHE2_OPTS.
 * 
 * 
 * Configuration file installed as
 *     /etc/apache2/modules.d/15_mod_layout.conf
 * You may want to edit it before turning the module on in /etc/conf.d/apache2
 * 

This is pretty straightforward. It tells you exactly what you need to do to enable this module.

If you missed this message, there is another way to find out what you need to add to APACHE2_OPTS in /etc/conf.d/apache2: simply check the configuration file the module installed. The module's configuration file should be added to /etc/apache2/modules.d/. Look for it there and find a line that has IfDefine:

<IfDefine LAYOUT>
  <IfModule !mod_layout.c>
    LoadModule layout_module    modules/mod_layout.so
  </IfModule>
</IfDefine>

The IfDefine block is ran when you add -D LAYOUT to /etc/conf.d/apache2. The LAYOUT is just an example.

There are several options you can add to APACHE2_OPTS that are specified in the default configuration and well explained in /etc/conf.d/apache2.

Documentation for all of the built-in modules can be found in the Apache 2.0 documentation.

3.  Apache is returning zero-length pages or segfaulting

This happens mostly after an upgrade because binary compatibility broke in APR (which may happen for a number for reasons). To fix this, you need to rebuild the Apache tool stack:

(make sure you do these in order, it's very important!)

(first, we have to remove the currently installed apache)
# emerge -aCv '=www-servers/apache-2*'

(then we rebuild the tool stack)
# emerge -av '=dev-libs/apr-0*' '=dev-libs/apr-util-0*'

(then we reinstall apache)
# emerge -av '=www-servers/apache-2*'

(determine any packages that depend on apache)
$ equery depends www-servers/apache
[ Searching for packages depending on www-servers/apache... ]
dev-php/phpsysinfo-2.3-r2
dev-php/phpsysinfo-2.1-r2
dev-lang/php-5.2.4_p20070914-r2
net-www/mod_layout-4.0.1a-r1
www-servers/gorg-0.5

(then rebuild any modules you have installed)
# emerge -av '=dev-lang/php-5.2.4_p20070914-r2' '=net-www/mod_layout-4.0.1.a-r1'

Determining a buggy add-on module

If you are still having problems after following the instructions above, the culprit is most likely one of your installed add-on modules.

Start off by disabling all add-on modules and restarting Apache.

(edit /etc/conf.d/apache2)

(before the change)
APACHE2_OPTS="-D PHP5 -D USERDIR -D SSL"

(after the change)
APACHE2_OPTS=""

# /etc/init.d/apache2 stop
(make sure apache is completely stopped)
# ps -A 
# /etc/init.d/apache2 start

If Apache quits segfaulting and giving blank pages, then you know for sure it was one of the add-on modules. To figure out which add-on modules, we add them back, one at a time, completely restarting apache every time.

When Apache stops working after adding a module back, you know that module is the one that is causing problems. Sometimes, simply rebuilding the module will fix the problem.

If after rebuilding the module and restarting apache, you are still having problems with Apache segfaulting or returning blank pages, you should file a bug listing the specific version and revision of the module and mention that it is segfaulting. Be sure to search for already open bugs first!

4.  Webserver doesn't interpret PHP or CGI scripts and returns their code instead

Apache sometimes appears to return the PHP or CGI code instead of running those scripts and returning the script output. If this happens even though the module is enabled in /etc/conf.d/apache2 it's very likely to be a cache issue. Clearing the webbrowser cache fixes this browser side issue.

Sometimes this problem can also be seen only when accessing the webserver using it's DNS name but not when accessing the webserver using its IP address. This is a strong indication that it's a cache issue.

This problem can be fixed by clearing the webbrowser cache and any other webproxies like squid or wwwoffle.

5.  configure: error: changes in the environment can compromise the build

If you get this error, then you probably have unneeded spaces in your CFLAGS in /etc/make.conf. The fix is simple, remove the extra spaces:

(before the change)
CFLAGS="-O2 -mcpu=pentium3 -march=pentium3  -pipe"

(after the change - notice the removal of the space)
CFLAGS="-O2 -mcpu=pentium3 -march=pentium3 -pipe"

6.  Address already in use: make_sock: could not bind to address 0.0.0.0:443

This error occurs during start-up and is caused by having multiple Listen directives in your configuration that are incompatible. To solve this problem, you should grep your configuration for Listen and fix each occurrence.

(Make sure you are in the configuration directory)
# cd /etc/apache2/

(List all listen directives)
# grep Listen httpd.conf vhosts.d/*.conf modules.d/*.conf

What you are looking for conflicts with what Apache is trying to bind to. For example, if there is a Listen 80 in httpd.conf and there is a Listen 10.0.0.15:80 in another file, then Apache will not be able to start. This is because Apache first binds to port 80 on all IP addresses for the machine and then tries to bind to port 80 on IP address 10.0.0.15 and fails because port 80 is already in use.

The recommended configuration is that you have a single Listen 80 (this is in the default httpd.conf) so that you bind to all addresses by default for the standard HTTP port and then for every SSL VirtualHost you run you create a separate absolute Listen directive (such as Listen 10.0.0.15:443).

7.  After upgrade to apache-2.0.54-r13 the default vhosts (SSL and non-SSL) don't work any more

With the upgrade to apache-2.0.54-r13, two new directives were added to it to fix bug 100624.

The new directives are -D DEFAULT_VHOST to activate the default virtual host and -D SSL_DEFAULT_VHOST to activate the default SSL virtual host. Both need to be added to the APACHE2_OPTS variable in /etc/conf.d/apache2 if you want Apache to behave like before.

8.  Getting Help

If none of the above was of any use to you, or if you have other questions, feel free to stop by our IRC channel, #gentoo-apache on irc.freenode.net. Or you may also file a bug on Gentoo's Bugzilla.

The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.