Troubleshooting Checklist

This section summarizes some of the most common issues found when troubleshooting an Apache problem.

Starting the Server

If you cannot successfully start the server, check the error log for information on why the failure occurred.

If another server is already running at that address, choose a different address/port combination for your server.

If you do not have permissions to bind to the requested port, start Apache as the superuser (root) so that you have access to bind to privileged ports.

If Apache is unable to open the configuration or log files, ensure that the files are owned by the same user that installed Apache and that the user in question has permission to write to them.

Connecting to the Server

If you are trying to access a page in the server and it does not display, to solve the problem you must first try to isolate whether it is caused by the server, network, or browser.

First, ensure that Apache is running using ps, netstat, or the Task Manager (in Windows). It may be that the server is not running at all.

Then ensure that you can connect to Apache from the local machine. To do this, use telnet to connect directly to the server and issue a sample request.

Next, ensure that Apache running on the correct address/port combination. If you can access the server locally, but not remotely, Apache is likely listening on a local address or port that is not accessible remotely. Use netstat or lsof to determine on which addresses Apache is listening and ensure that they are correct.

Ensure that your firewall or router is correctly configured. If Apache is listening to the correct address but is inaccessible outside your network, network traffic to your Apache server may be blocked. Use the traceroute utility (tracert on Windows) to test for network connectivity between the hosts in question. Many operating systems prevent access from the outside by default except on a few selected ports. If you are running Apache on a nonstandard port, you may be blocked. How to fix this varies from distribution to distribution. For example, you can use the system-config-securitylevel tool on Fedora systems and the Windows Firewall tool in the Windows Control Panel.

Finally, if you are using Secure Sockets Layer (SSL) to access the server (explained in Chapter 7) and you are connecting using older browser versions or running unusual configurations, check the error log for problems related to SSL data encryption.

Document Not Found

If you can access the server, but you get a "Document not found" error, ensure that the document does indeed exist in the file system.

Then, ensure that the request reached the server by checking the access_log file for request(s) from the host in question. If you have multiple Apache instances running simultaneously, it may be that you are connecting to the wrong server.

Next, ensure that your Alias directives point to the right locationthat is, to the location your target documents are located. Make sure that you did not misspell or accidentally delete the target directory.

Finally, check for incorrect redirects, including "trailing slashes" and the ServerName issues described earlier in this chapter.

Access Forbidden

If the document exists but you are told that you have been forbidden from accessing it, check for a number of common errors.

Ensure that the owner of the Apache process has permission to read the file.

Ensure that the owner of the Apache process has read and list permissions for all directories in the path leading to the file.

Check to see whether you are trying to access a directory without an index file when directory listings are forbidden in the Apache configuration file.

Verify that the request meets all of the requirements outlined by the access control directives in the Apache configuration file.

If you are trying to access a CGI-script, ensure that it has been given read and execute permissions.

Internal Server Errors

If you get an "Internal server error" in your browser when you try to load a page from the web server, check the Apache error_log to try to find the cause. Ask yourself the following questions:

Are you trying to access a CGI program? Does it have the right read and execute permissions? Is the path to the interpreter in the first line of the script correct? Is it marked as a CGI script by a ScriptAlias directive or similar?

If All Else Fails

This chapter has discussed only the most common problems faced by Apache users. If you encounter a problem not covered in this chapter, the first step toward resolving it is to check the error logs for details. Increase the Apache server's LogLevel, if necessary, to find hints as to what the problem may be. Search the Apache documentation, mailing lists, and bug database. Finally, post your question to the Apache Users mailing list at the following address, taking care to follow the posting guidelines when doing so: Do your homework first, then provide enough information for others to be able to help.

http://httpd.apache.org/lists.html#http-users