There's plenty of documentation on installing and configuring the Apache web server, but where do you find help for the day-to-day stuff, like adding common modules or fine-tuning your activity logging? That's easy. The new edition of the "Apache Cookbook" offers you updated solutions to the problems you're likely to encounter with the new versions of Apache. Written by members of the Apache Software Foundation, and thoroughly revised for Apache versions 2.0 and 2.2, recipes in this book range from simple tasks, such installing the server on Red Hat Linux or Windows, to more complex tasks, such as setting up name-based virtual hosts or securing and managing your proxy server.Altogether, you get more than 200 timesaving recipes for solving a crisis or other deadline conundrums, with topics including: Security; Aliases, Redirecting, and Rewriting; CGI Scripts, the suexec Wrapper, and other dynamic content techniques; Error Handling; SSL; and Performance. This book tackles everything from beginner problems to those faced by experienced users.

For every problem addressed in the book, you will find a worked-out solution that includes short, focused pieces of code you can use immediately. You also get explanations of how and why the code works, so you can adapt the problem-solving techniques to similar situations. Instead of poking around mailing lists, online documentation, and other sources, rely on the "Apache Cookbook" for quick solutions when you need them. Then you can spend your time and energy where it matters most.

Rich Bowen has been involved with the Apache Web Server project since 1998, and has written a number of books about it. He works on the web team at Asbury College, where he gets to put into practice a few of the things he writes about. Rich lives in Lexington, Kentucky.

Ken Coar is a member of the Apache Software Foundation, the body that oversees Apache development. He is the author of "Apache Server for Dummies" and co-author of "Apache Server Unleashed" (Sams). Ken is responsible for fielding email sent to the Apache project; his experience with that mailing list provided a foundation for this book. Ken is a resident of Raleigh, North Carolina.

Chapter 9 - Error Handling

When you?re running a web site, things go wrong. And when they do, it?s important that they are handled gracefully, so that the user experience is not too greatly diminished. In this chapter, you?ll learn how to handle error conditions, return useful messages to the user, and capture information that will help you fix the problem so that it does not happen again.

9.1 Handling a Missing Host Field

Problem
You have multiple virtual hosts in your configuration, and at least one of them is name-based. For name-based virtual hosts to work properly, the client must send a valid Host field in the request header. This recipe describes how you can deal with situations in which the field is not included.

Solution
Add the following lines to your httpd.conf file:

Alias /NoHost.cgi /usr/local/apache/cgi-bin/NoHost.cgi
RewriteEngine On
RewriteCond "%{HTTP_HOST}" "^$"
RewriteRule "(.*)" "/NoHost.cgi$1" [PT]

The file NoHost.cgi can contain something like the following:

#! /usr/bin/perl ?Tw

my $msg = "To properly direct your request, this server requires thatn"
. "your Web client include the HTTP 'Host' request header field.n"
. "The request which caused this response did not include suchn"
. "a field, so we cannot determine the correct document for you.n";
print "Status: 400 Bad Requestrn"
. "Content-type: text/plainrn". 'Content-length: ' . length($msg) . "rn"
. "rn"
. $msg;
exit(0);

Discussion
Once the directives in the solution are in place, all requests made of the server that do not include a Host: field in the request header are redirected to the specified CGI script, which can take appropriate action.

The solution uses a CGI script so that the response text can be tailored according to the attributes of the request and the server?s environment. For instance, the script might respond with a list of links to valid sites on the server, determined by the script at runtime by examining the server?s own configuration files. If all you need is a "please try again, this time with a Host: field" sort of message, a static HTML file would suffice:

RewriteRule .* /nohost.html [PT]

A more advanced version of the script approach could possibly scan the httpd.conf file for ServerName directives, construct a list of possibilities from them, and present links in a 300 Multiple Choices response. Of course, there?s an excellent chance they wouldn?t work, because the client would still not be including the Host: field.

9.2 Changing the Response Status for CGI Scripts

Problem
There may be times when you want to change the status for a response?for example, you want 404 Not Found errors to be sent back to the client as 403 Forbidden instead.

Solution
Point your ErrorDocument to a CGI script instead of a static file. The CGI specification permits scripts to specify the response status code.

In addition to the other header fields the script emits, like the Content-type: field,
include one named Status: with the value and text of the status you want to return:

#! /bin/perl -w
print "Content-type: text/html;charset=iso-8859-1rn";
print "Status: 403 Access deniedrn";
:

Discussion
If Apache encounters an error processing a document, such as not being able to locate a file, by default it will return a canned error response to the client. You can customize this error response with the ErrorDocument directive, and Apache will generally maintain the error status when it sends your custom error text to the client.

However, if you want to change the status to something else, such as hiding the fact that a file doesn?t exist by returning a Forbidden status, you need to tell Apache about the change.

This requires that the ErrorDocument be a dynamic page, such as a CGI script. The CGI specification provides a very simple means of specifying the status code for a response: the Status: CGI header field. The Solution shows how it can be used.