10 Apache Troubleshooting Tips

As a community supported project, the open source Apache web
server is well-proven, but can still offer an administrator headaches from time
to time when things don’t go quite as planned. In this article, I will provide
you with eight tips to help you solve the most common Apache dilemmas.

Tip #1: Know where to look

If you’re having trouble with Apache, or seeming to have
trouble with one of its modules, your first stop should be in looking over
Apache’s detailed error log. Depending on how your system and Apache are
configured, the error log may live in different locations. The default location
for this file is a file named error_log located in the logs directory inside
your Apache root installation. If you can’t find your error log, open the
httpd.conf configuration file and look for the ErrorLog directive, which
defines the location.

Apache is initially configured to the “warn” log
level, meaning that any problem more serious than a warning (critical,
emergency, error, alert, and warn) is logged. You can adjust the logging level
in httpd.conf my manipulating the LogLevel directive.

From the Apache documentation, Table A outlines the eight
available warning levels and provides an example of what would be logged at
that level.

If you can’t figure out why your Apache server is having a
problem, try adjusting the log level to a higher threshold to capture more
information. After you change the level, stop and restart your server.

There are actually two log files in Apache: error_log, which
I described in this section, and access_log. The error_log file, as you might
expect, is the log of most interest for troubleshooting purposes. However, also
make use of the access_log when looking for problems. This file lists all of
the items pulled down by clients along with the HTTP error or success code.

Tip #2: Don’t let an AllowOverride ruin your day

Depending on how you want to run your web site, you can
selectively alter the behavior of your Apache server by making use of .htaccess
files. Simply put, an .htaccess file is a file in a directory that lets you
make configuration changes that affect just that folder. For example, if you’ve
disabled the “Indexes” in httpd.conf for all directories, none f your
visitors will be able to access a directory listing. You may have a single
folder for which this access should be allowed. In this case, you would have an
.htaccess file with the “Options Indexes” directive.

You can probably begin to see some reasons that .htaccess
files can be problematic. First of all, for very large sites, keeping track of
these files could be a very difficult task. Now, when you have a functionality
problem, you can’t just look to one source for possible configuration problems.
You now need to traverse your directory structure and look for .htaccess files.

Second, by allowing the use of these files, you may be
allowing users the lack your Apache security prowess to make potentially
insecure changes to your web site.

Finally, use of .htaccess can exact a performance penalty on
your web site due to the need of the web server to look for an .htaccess file
in the current directory and in every superior directory all the way to the
document root of the web server.

Unless you have a really good reason, avoid the use of
.htaccess files. Instead, in the httpd.conf file, make liberal use of “Directory”
sections to set per-directory options.

On the other hand, if you are using .htaccess files and they don’t seem to be activated, look
to the httpd.conf file and make sure the directive “AllowOverride” is
not set to “None”. You can limit what options are allowed in an
.htaccess file by further manipulating the AllowOverride directive’s type. Table B, based on the Apache documentation, provides you with a list of possible
AllowOverride options. Only use the options you need.

Tip #3: A newly installed module/extension (such as PHP) is not working

Suppose, for example, that you recently installed the PHP extension,
but, upon visiting your site, you’re seeing the PHP code itself instead of the
results of that code’s execution. First off, for folks new to Linux, installing
new modules and getting everything working perfectly can be akin to setting up
a Christmas tree with your hands tied behind your back.

Since it’s among the most popular available, let’s use the
PHP module for an example.

Your problem could be something very simple. Apache may not
be configured to do anything with the .php extension. Look at your httpd.conf
configuration file and look for the DirectoryIndex directive. Make sure the
line reads:

DirectoryIndex
index.html index.php

The default Apache installation omits the “Index.php”
file, rendering many PHP-based sites useless.

Further, your httpd.conf file needs to tell Apache a little
bit about the .php extension through the use of the AddType directive. If you’re
using PHP, you should have a line in your configuration that reads:

AddType
application/x-httpd-php .php

Normally, this line is commented out.

Finally, make sure your httpd.conf file is actually loading
a supported PHP module. If you’re not loading the PHP handling module, Apache
won’t know what to do with .php pages, no matter how many AddType directives
you include. Here is an example LoadModule directory for PHP 4.

(Apache 2+) LoadModule
php4_module modules/libphp4.so

(Apache 1.3) LoadModule
php4_module libexec/libphp4.so

Apache 1.3 also requires a fourth directive:

AddModule mod_php4.c

If this still isn’t working, make sure your module is
compatible with the version of Apache you’re running. The PHP developers, for
example, recommend that, for Apache 2 and later, you use at least PHP 4.3.0.

The short answer: Make sure you’ve strictly followed the
instructions for setting up Apache with additional modules. I’ve highlighted
some of PHP’s requirements in this tip, but every module has its own nuances.

Tip #4: Don’t worry about “connection reset by peer” errors too
much… but do watch for it.

When a user cancels a request to your site (presses the Stop
button or hits Escape), your server logs will be appended with the message “connection
reset by peer”. If you see this message only occasionally, it probably
means someone typed in the wrong address or just got impatient while waiting
for your site to load. If you’re seeing this message on a regular basis, you
might have congestion issues slowing your site to a point beyond the tolerance
of some people. You may have other network issues creating this problem.

Tip #5: Make sure Apache is actually running

I’m going to ‘fess up here… This one has bitten me in the
past. I spent quite some time looking through error logs and the httpd.conf
file before I even bothered to make sure Apache was evening running! After severely reprimanding myself, I started
the service and, until today, have never told a soul.

The point: Any day can be an off day! Look for the simple
things, too.

Tip #6: Use configtest

So you’ve made some modifications to your httpd.conf file
and now Apache isn’t working properly… oh, by the way, you don’t have a handy
backup of the original file to find out what’s wrong.

The god folks that created Apache have provided you with a
way to scan your httpd.conf file and make sure it’s free from obvious errors. This
error checking tool is provided as a part of the apachectl program. To use it,
execute apachectl -configtest from
the command line. The apachectl program is located in the bin directory of your
Apache installation.

If no errors are found, the utility will execute like this
example:

[root@localhost bin]#
./apachectl configtest

Syntax OK

To show how this tool works, I’ve intentionally create a
httpd.conf file with an error or two.

[root@localhost bin]#
./apachectl configtest

Syntax error on line 22
of /usr/local/apache/conf/httpd.conf:

Invalid command 'sserversignature',
perhaps misspelled or defined by a module not included in the server configuration

In this case, I have misspelled a directive, which should
read “ServerSignature”, not “SServerSignature”. Even if you
correct the error, run the tool again as more errors may be found. As a
highlight to this, I actually had another error in my httpd.conf file.

[root@localhost bin]#
./apachectl configtest

Syntax error on line
108 of /usr/local/apache/conf/httpd.conf:

DocumentRoot must be a
directory

In this case, the directory name in the DocumentRoot
directive also had a spelling error which would have resulted in Apache being
unable to serve any content since the directory does not exist.

The apachectl program has a number of options, some of which
you can see in Table C. You’ve probably used “start” and “stop”,
but there are many more that maybe useful depending on what you’re trying to
do.

Tip #7: Know where to find Apache community resources

The Apache community is huge and there are a ton of places
to go for help when you have a problem. In my Apache experience, I’ve used
TechRepublic and other professional sites, but my first stop is Google. Type
the exact error message or symptom and the chances are really good that you’ll
get some hits back.

Failing that, here are some other outstanding resources that
you can use for help:

  • http://p.webring.com/hub?ring=apachesupport
    –     This is the main page of the Apache support webring that houses a
    plethora of information about Apache and provides a place to start when
    trying to solve a difficult problem.
  • IRC channel #Apache – This is an
    IRC room with live Apache experts that, if you are patient, are willing to
    help you through a problem. When using this resource, make sure to
    understand that these folks do this out of the goodness of their hearts,
    so be thankful!
  • http://httpd.apache.org/docs/
    –     A link to the Apache documentation. It’s amazing how many problems
    can be solved by reading the manual!

Tip #8: Understand the various HTTP/1.1 error codes

Specific HTTP errors on a client or in your server logs can
help point you in the right direction. For example, if you have users
complaining that they always get “404” errors when they click a link
to visit your site, the host link is pointing to a page on your Apache server
that does not exist. Or, if a client receives a “501” error, the
client is attempting to access content on your server for which no handler
exists. Often this error can be the result of a problem with a CGI script.

In Table D, I’ve taken information (with permission)
from the W3C, the organization responsible for keeping HTTP error messages
consistent, and reformatted it to be a little more easily read and removed from the extraneous information.

Eight isn’t enough

Will these eight tips help you solve all of your problems? Probably not, but these tips were designed to
help point you in the right direction to solve problems. Share your Apache
troubleshooting tips with me for a future version of this article.