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
Code Listing 1.1: access_log
220.127.116.11 - - [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
18.104.22.168 - - [18/Jun/2005:12:15:06 -0700] "GET /~jaspenelle/avy14.gif HTTP/1.0" 200 1661
22.214.171.124 - - [18/Jun/2005:12:18:48 -0700] "GET / HTTP/1.0" 200 721
126.96.36.199 - - [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:
Code Listing 1.2: Common Log Format syntax
remotehost rfc931 authuser [date] "request" status bytes
||Remote host name or IP address
||The remote log name of the user.
||The user name as which the user has authenticated himself.
||Date and time of the request.
||The request line exactly as it came from the client.
||The HTTP status code returned to the client.
||The content-length of the document transferred.
error_log and ssl_error_log
Code Listing 1.3: 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.
Code Listing 1.4: 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.
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:
Code Listing 2.1: Post-installation message from emerge
* 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
* 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:
Code Listing 2.2: An excerpt from 15_mod_layout.conf
LoadModule layout_module modules/mod_layout.so
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
Documentation for all of the built-in modules can be found in the Apache 2.0 documentation.
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:
Code Listing 3.1: Rebuilding the Apache tool stack
# emerge -aCv '=www-servers/apache-2*'
# emerge -av '=dev-libs/apr-0*' '=dev-libs/apr-util-0*'
# emerge -av '=www-servers/apache-2*'
$ equery depends www-servers/apache
[ Searching for packages depending on www-servers/apache... ]
# 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.
Code Listing 3.2: Disabling add-on modules
APACHE2_OPTS="-D PHP5 -D USERDIR -D SSL"
Code Listing 3.3: Restarting Apache
# /etc/init.d/apache2 stop
# ps -A
# /etc/init.d/apache2 start
You may have to make minor changes to some places of your configuration if you
have added Directives that these modules provide in places that don't
test for the module being loaded. It's recommended that Directives
like these be placed in test containers. See any of the .conf files in
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!
Webserver doesn't interpret PHP or CGI scripts and returns their code
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.
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
Code Listing 5.1: Example of changes to /etc/make.conf
CFLAGS="-O2 -mcpu=pentium3 -march=pentium3 -pipe"
CFLAGS="-O2 -mcpu=pentium3 -march=pentium3 -pipe"
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
Code Listing 6.1: Finding all Listen directives
# cd /etc/apache2/
# 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).
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
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.
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.