O'Reilly logo

Apache Cookbook, 2nd Edition by Ken Coar, Rich Bowen

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required


The Apache Web server is a remarkable piece of software. The basic package distributed by the Apache Software Foundation is quite complete and very powerful, and a lot of effort has gone into keeping it from suffering software bloat. One facet of the package makes it especially remarkable: it includes extensibility by design. In short, if the Apache package right out of the box does not do what you want, you can generally extend it so that it does. Dozens of extensions (called modules) are included as part of the package distributed by the Apache Software Foundation. And if one of these doesn’t meet your needs, with several million users out there, there is an excellent chance someone else has already done your work for you, someone who has concocted a recipe of changes or enhancements to the server that will satisfy your requirements.

This book is a collection of these recipes. Its sources include tips from the firehose of the Usenet newsgroups, the Apache FAQ, Apache-related mailing lists, mail containing “how-to” questions, questions and problems posed on IRC chat channels, and volunteered submissions.

All of the items in this book come from real-life situations, encountered either by us or by other people who have asked for our help. The topics range from basic compilation of the source code to complex problems involving the treatment of URLs that require SSL encryption.

We’ve collected more than a hundred different problems and their solutions, largely based on how often they occurred, and have grouped them roughly by subject as shown in What’s in This Book.

Primarily, these recipes are useful to webmasters who are responsible for the entire server; however, many are equally applicable to users who want to customize the behavior in their own Web directories through the use of .htaccess files.

We’ve written the Apache Cookbook to be a practical reference, rather than a theoretical discourse: reading it recipe by recipe, chapter by chapter, isn’t going to reveal a plot (“Roy Fielding in the Library with an RFC!”[1]). It’s intended to provide point solutions to specific problems, located through the table of contents or the index.

What’s in This Book

Because much of the material in this book is drawn from question-and-answer discussions and consultations, we have tried to make it as complete as possible. Of course, this means that we have included “recipes” for some questions to which there are currently no satisfactory answers (at least to our knowledge). This has not been done to tease, annoy, or frustrate you; such recipes are included to provide completeness, so that you will know those problems have been considered rather than ignored.

Very few problems remain insoluble forever, and these incomplete recipes are the ones that will receive immediate attention on the book’s Web site and in revisions of the book. If a reader has figured out a way to do something the book mentions but doesn’t explain, or omits mentioning entirely, our research team can be notified, and that solution will go on the Web site and in the next revision.

Who knows, you may be the one to provide such a solution!

Platform Notes

The recipes in this book are geared toward two major platforms: Unixish (such as Linux, FreeBSD, and Solaris) and Windows. There are many that have no platform-specific aspects, and for those, any mention of the underlying operating system or hardware is gratefully omitted. Because of the authors’ personal preferences and experiences, Unixish coverage is more complete than that for the Windows platforms. However, contributions, suggestions, and corrections for Windows-specific recipes will be gladly considered for future revisions and inclusion on the Web site.

Other Books

There are a number of books currently in print that deal with the Apache Web server and its operation. Among them are:

  • Apache: The Definitive Guide, Third Edition, by Ben and Peter Laurie (O’Reilly)

  • Pro Apache, Third Edition, by Peter Wainwright (Apress)

  • Apache Administrator’s Handbook by Rich Bowen, et al. (Macmillan)

You can also keep an eye on a couple of Web pages that track Apache titles:

Other Sources

In addition to books, there is a wealth of information available online. There are Web sites, mailing lists, and Usenet newsgroups devoted to the use and management of the Apache Web server. The Web sites are limitless, but here are some active and useful sources of information:

  • The comp.infosystems.www.servers.unix and comp.infosystems.www.servers.ms-windows Usenet newsgroups. Although these aren’t dedicated to Apache specifically, there is a lot of traffic concerning it, and experienced Apache users hang out here. If you don’t have access to news, or don’t know how to reach Usenet, check out http://groups.google.com/.

  • The Apache Today Web site, http://apachetoday.com/, run by Internet.com. This site regularly lists articles about the Web server and making the most of it.

  • The mailing list is populated with people who have varying degrees of experience with the Apache software, and some of the Apache developers can be found there, too. Posting is only permitted to subscribed participants. To join the list, visit http://httpd.apache.org/userslist.html.

  • The #apache IRC channel on the irc.freenode.net network—or on many other IRC networks, for that matter. However, your chances of encountering us are most likely on the freenode network.

We must point out that none of these are “official” support mediums for the Web server. In fact, there is no “official” support path, since the software is largely developed by volunteers and is free. However, these informal support forums successfully answer many questions.

How This Book Is Organized

This book is broken up into 13 chapters and 2 appendixes, as follows:

Chapter 1, Installation, covers the basics of installing the vanilla Apache software, from source on Unixish systems, and on Windows from the Microsoft Software Installer (MSI) package built by the Apache developers.

Chapter 2, Adding Common Modules, describes the details of installing some of the most common third-party modules, and includes generic instructions that apply to many others that have less complex installation needs.

Chapter 3, Logging, includes recipes about recording the visits to your Web site(s), and Apache’s error logging mechanism.

Chapter 4, Virtual Hosts, tells you how to run multiple Web sites using a single Apache server and set of configuration files.

Chapter 5, Aliases, Redirecting, and Rewriting, describes how to manipulate URLs, how to control which files they refer to, how to change them from one thing to another, and how to make them point to other Web sites.

Chapter 6, Security, covers some of the basic issues of securing your Apache server against penetration and exposure by the nefarious elements on the Internet.

Chapter 7, SSL, addresses the issues of making your Apache Web server capable of handling secure transactions with SSL-capable browsers—a must if you’re going to be handling sensitive data such as money transfers or medical records.

Chapter 8, Dynamic Content, tells you how to enhance your server with runtime scripts and make them operate as a particular user.

Chapter 9, Error Handling, describes how to customize the Web server’s error messages to give your site its own unique flavor.

Chapter 10, Proxies, describes how to configure your Apache server to act as a proxy between users and Web pages and make the processes as transparent and seamless as possible.

Chapter 11, Performance, includes a number of recipes for addressing performance bottlenecks and improving the overall function of your Apache server.

Chapter 12, Directory Listings, describes how to customize the module for displaying a directory listing as a Web page.

Chapter 13, Miscellaneous Topics, covers a variety of miscellaneous topics that didn’t seem to fit into any of the other chapters.

Appendix A, Using Regular Expressions in Apache, explains how regular expressions are used for pattern-matching in Apache directives.

Appendix B, Troubleshooting, covers some basic troubleshooting techniques, where to look for messages, common configuration problems, and so on.

Conventions Used in This Book

Throughout this book certain stylistic conventions are followed. Once you are accustomed to them, you can easily distinguish between comments, commands you need to type, values you need to supply, and so forth.

In some cases, the typeface of terms in the main text will be different and likewise in code examples. The details of what the different styles (italic, boldface, etc.) mean are described in the following sections.

Programming Conventions

In this book, most case examples of code will be in the form of excerpts from scripts, rather than actual application code. When commands need to be issued at a command-line prompt (such as an xterm for a Unixish system or a DOS command prompt for Windows), they will look something like this:

% find/usr/local -name apachectl -print 
# /usr/local/apache/bin/apachectl graceful
C:>cd "\Program Files\Apache Group\Apache\bin"
C:\Program Files\Apache Group\Apache\bin>apache -k stop

On Unixish systems, command prompts that begin with # indicate that you need to be logged in as the superuser (root username); if the prompt begins with %, then the command can be used by any user.

Typesetting Conventions

The following typographic conventions are used in this book:


Used for commands, filenames, abbreviations, citations of books and articles, email addresses, URLs, and Usenet group names.


Used for labeling menu choices in a graphical interface.

Constant Width

Used for function names, command options, computer output, environment variable names, literal strings, and code examples.

Constant Width Bold

Used for user input in computer dialogues and examples.

Constant Width Italic

Used for replaceable parameters, filesystem paths, and variable names.


This icon signifies a tip, suggestion, or general note.


This icon indicates a warning or caution.

Documentation Conventions

Because this book deals with a general topic rather than a specific one (such as the Perl language), there are additional sources of information to which it will refer you. The most common ones are as follows.

The online manual (“man”) pages on a Unixish system

References to the manpages will appear something like, “For more information, see the kill(1) manpage.” The number in parentheses is the manual section; you can access this page with a command such as:

% man   1 kill

The Apache Web server documentation

Such a reference may appear as “See the mod_auth documentation for details.” This refers to a Web page like:


In some cases, the reference will be to a specific Apache directive rather than an actual module; in cases like this, you can locate the appropriate Web page by looking up the directive name on:


This page lists all of the directives available in the standard Apache package. In some situations, the directive may be specific to a nonstandard or third-party module, in which case the documentation should be located wherever the module itself was found. The links above are for the documentation for Version 1.3 of the software. To access the documentation for Version 2.0, replace “docs/” with “docs-2.0/” in the URLs.

Using Code Examples

This book is here to help you get your job done. In general, you may use the code in this book in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Apache Cookbook, Second Edition, by Ken Coar and Rich Bowen. Copyright 2008 Ken Coar and Rich Bowen, 978-0-596-52994-9.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at .

We’d Like to Hear from You

We have tested and verified the information in this book to the best of our ability, but you may find that features have changed (which may in fact resemble bugs). Please let us know about any errors you find, as well as your suggestions for future editions, by writing to the following address.

Please address comments and questions concerning this book to the publisher:

O’Reilly Media, Inc.
1005 Gravenstein Highway North
Sebastopol, CA 95472
800-998-9938 (in the United States or Canada)
707-829-0515 (international or local)
707-829-0104 (fax)

We have a Web page for this book, where we list errata, examples, and any additional information. You can access this page at:


To comment or ask technical questions about this book, send an email to:

For more information about our books, conferences, Resource Centers, and the O’Reilly Network, see our Web site at:


We have a Web site for the book, where we’ll list errata and plans for future editions. Here you’ll also find the source code from the book available for download so you don’t have to type it all in:


Safari® Enabled


When you see a Safari® Enabled icon on the cover of your favorite technology book, that means the book is available online through the O’Reilly Network Safari Bookshelf.

Safari offers a solution that’s better than e-books. It’s a virtual library that lets you easily search thousands of top tech books, cut and paste code samples, download chapters, and find quick answers when you need the most accurate, current information. Try it for free at http://safari.oreilly.com.


Originally, each recipe was going to be individually attributed, but that turned out to be logistically impossible.

Many people have helped us during the writing of this book, by posing a problem, providing a solution, proofreading, reviewing, editing, or just (!) providing moral support. This multitude, to each of whom we are profoundly grateful, includes Nat Torkington (our project editor and demonstrator of Herculean feats of patience), Sharco and Guy- from #apache on irc.freenode.net, Mads Toftum, Morbus Iff (known to the FBI under the alias Kevin Hemenway), and Andy Holman.

Ken Coar

I dedicate this book to my significantly better half, Cathy Coar, who has performed Heraclean feats of love and support on my behalf for more than two decades.

My sincere thanks go out to the crew at O’Reilly, for their deific patience and understanding. Thanks also to the WriterBase Authors Support Group and Cabal mailing lists, whereon much balm and advice was offered. Our technical reviewers provided much excellent feedback and helped make this a better book.

The people who have worked on the Apache Web server documentation, and the people who develop the software itself, get a big note of thanks, too; without the former, collating a lot of the information in this book would have been a whole lot more difficult, and without the latter, the book wouldn’t have happened at all.

The users of the software, whose frequently challenging questions populate the mailing lists, the IRC channels, and our inboxes, deserve thanks for all the inspiration they unwittingly provided for the recipes in this book.

But foremost among those to whom I owe gratitude is my significantly better half, Cathy, without whose patience, support, and constructive criticism I would never have achieved what I have.

Rich Bowen

I dedicate this book to the experts on #apache who answer so many of these questions every day, and to the beginners, on their way to becoming experts, who ask them.

A huge thank you goes to all the many people involved in making this book a reality. Tatiana, thank you for your patience and persistent assistance throughout this process.

And, finally, thanks go to my wonderful family. To Sarah, who always looks for my books at the bookstore. To Isaiah, for all his boundless energy and tight hugs. And to my Best Beloved, for helping me discover so much Pointless Beauty.

[1] An obscure reference to a board game called Clue and an obscure developer of HTTP.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required