Project:Apache/Troubleshooting

This document covers a number of ways to figure out how to fix your Apache installation when things are not working correctly.

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. 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
access_log

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:

Common Log Format syntax

error_log and ssl_error_log
error_log

As you can see, this file can contain a lot of stuff, depending on the  directive in your  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
suexec_log

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:

Post-installation message from emerge

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  in  : simply check the configuration file the module installed. The module's configuration file should be added to. Look for it there and find a line that has  :

An excerpt from 15_mod_layout.conf

The  block is ran when you add   to. The  is just an example.

There are several options you can add to  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:

Rebuilding the Apache tool stack

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.

Disabling add-on modules

Restarting Apache

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 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 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  in. The fix is simple, remove the extra spaces:

Example of changes to /etc/make.conf

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  directives in your configuration that are incompatible. To solve this problem, you should grep your configuration for  and fix each occurrence.

Finding all Listen directives

What you are looking for conflicts with what Apache is trying to bind to. For example, if there is a  in  and there is a   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  (this is in the default  ) so that you bind to all addresses by default for the standard HTTP port and then for every SSL   you run you create a separate absolute   directive (such as   ).

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  to activate the default virtual host and   to activate the default SSL virtual host. Both need to be added to the  variable in  if you want Apache to behave like before.

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, on. Or you may also file a bug on Gentoo's Bugzilla.

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:


 * Michael Stewart
 * Elfyn McBratney
 * Bryan Østergaard
 * Benedikt Böhm