Troubleshooting Apache

Troubleshooting a basic Apache configuration is fairly straightforward; you'll find errors in the /var/log/httpd/error_log file during normal operation or displayed on the screen when Apache starts up. Most of the errors you'll encounter will probably be related to incompatible syntax in the <VirtualHosts> statement caused by typing errors.

Testing Basic HTTP Connectivity

The very first step is to determine whether your Web server is accessible on TCP port 80 (HTTP).

Lack of connectivity could be caused by a firewall with incorrect permit, NAT, or port forwarding rules to your Web server. Other sources of failure include Apache not being started at all, the server being down, or network-related failures.

If you can connect on port 80 but no pages are being served, then the problem is usually due to a bad Web application, not the Web server software itself.

It is best to test this from both inside your network and from the Internet. Troubleshooting with TELNET is covered in Chapter 4, "Simple Network Troubleshooting."

Browser 403 Forbidden Messages

Browser 403 Forbidden messages are usually caused by file permissions and security context issues. Please refer to the "General Configuration Steps" section for further details.

A sure sign of problems related to security context are "avc: denied" messages in your /var/log/messages log file.

     Nov 21 20:41:23 bigboy kernel: audit(1101098483.897:0): avc: denied
     { getattr } for  pid=1377 exe=/usr/sbin/httpd
     path=/home/www/index.html dev=hda5 ino=12
     scontext=root:system_r:httpd_t tcontext=root:object_r:home_root_t
     tclass=file

Only the Default Apache Page Appears

When only the default Apache page appears, there are two main causes. The first is the lack of an index.html file in your Web site's DocumentRoot directory. The second cause is usually related to an incorrect security context for the Web page's file. Please refer to the "General Configuration Steps" section for further details.

Incompatible /etc/httpd/conf/http.conf Files When Upgrading

Your old configuration files will be incompatible when upgrading from Apache version 1.3 to Apache 2.X. The new version 2.X default configuration file is stored in /etc/httpd/conf/httpd.conf.rpmnew. For the simple virtual hosting example above, it would be easiest to:

Server Name Errors

All ServerName directives must list a domain that is resolvable in DNS, or else you'll get an error similar to these when starting httpd:

     Starting httpd: httpd: Could not determine the server's fully
     qualified domain name, using 127.0.0.1 for ServerName

     Starting httpd: [Wed Feb 04 21:18:16 2004] [error] (EAI 2)Name or
     service not known: Failed to resolve server name for 192.16.1.100
     (check DNS) -- or specify an explicit ServerName

You can avoid this by adding a default generic ServerName directive at the top of the httpd.conf file that references localhost instead of the default new.host.name:80:

     #ServerName new.host.name:80
     ServerName localhost

The Apache Status Log Files

The /var/log/httpd/access_log file is updated after every HTTP query and is a good source of general purpose information about your Web site. There is a fixed formatting style with each entry separated by spaces or quotation marks. Table 20.3 lists the layout.

Table 20.3. Apache Log File Format

Field Number	Description	Separator
1	IP address of the remote Web surfer	Spaces
2	Time stamp	Square Brackets []
3	HTTP query including the Web page served	Quotes ""
4	HTTP result code	Spaces
5	The amount of data in bytes sent to the remote Web browser	Spaces
6	The Web page that contained the link to the page served	Quotes ""
7	The version of the Web browser used to get the page	Quotes ""

Upon examining the entry, you can determine that someone at IP address 67.119.25.115 on February 15 looked at the Web page /dns-static.htm returning a successful 200 status code. The amount of data sent was 15190 bytes and the surfer got to the site by clicking on the link http://www.linuxhomenetworking.com/sendmail.htm using Microsoft Internet Explorer version 5.5.

     67.119.25.115 - - [15/Feb/2003:23:06:51 -0800] "GET /dns-static.htm
     HTTP/1.1" 200 15190 "http://www.linuxhomenetworking.com/sendmail.htm"
     "Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 4.0; AT&T CSM6.0; YComp
     5.0.2.6)"

The HTTP status code can provide some insight into the types of operations surfers are trying to attempt and may help to isolate problems with your pages, not the operation of the Apache server. For example, 404 errors are generated when someone tries to access a Web page that doesn't exist anymore. This could be caused by incorrect URL links in other pages on your site. Table 20.4 has some of the more common examples.

Table 20.4. HTTP Status Codes

HTTP Code	Description
200	Successful request.
304	Successful request, but the Web page requested hasn't been modified since the current version in the remote Web browser's cache. This means the Web page will not be sent to the remote browser, it will just use its cached version instead. Frequently occurs when a surfer is browsing back and forth on a site.
401	Unauthorized access. Someone entered an incorrect username or password on a password-protected page.
403	Forbidden. File permissions prevent Apache from reading the file. Often occurs when the Web page file is owned by user root, even though it has universal read access.
404	Not found. Page requested doesn't exist.
500	Internal server error. Frequently generated by CGI scripts that fail from bad syntax. Check your error_log file for further details on the script's error message.

The Apache Error Log Files

The /var/log/httpd/error_log file is a good source for error information. Unlike the /var/log/httpd/access_log file, there is no standardized formatting.

Typical errors that you'll find here are HTTP queries for files that don't exist or forbidden requests for directory listings. The file will also include Apache startup errors, which can be very useful.

The /var/log/httpd/error_log file also is the location where CGI script errors are written. Many times CGI scripts fail with a blank screen on your browser; the /var/log/httpd/error_log file most likely lists the cause of the problem.