Apache Cookbook

Preface

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, 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 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 (or 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 ones (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. Due to 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 (O’Reilly)

• Apache Server Unleashed (Macmillan)

• Apache Administrator’s Handbook (Macmillan)

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

• http://Apache-Server.Com/store.html

• http://httpd.apache.org/info/apache_books.html

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-dos 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 know how to reach USENET, check out http://groups.google.com/.

• The Apache Today web site, run by Internet.Com. This site regularly lists articles about the web server and making the most of it. The URL is http://ApacheToday.Com/.

• The [e-mail] 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 is an “official” support medium 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 twelve chapters and two appendixes, as follows:

Chapter 1 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 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 includes recipes about recording the visits to your web site(s), and Apache’s error logging mechanism.

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

Chapter 5 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 covers some of the basic issues of securing your Apache server against penetration and exposure by the nefarious elements on the Internet.

Chapter 7 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 tells you how to enhance your server with runtime scripts and make them operate as a particular user.

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

Chapter 10 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 includes a number of recipes for addressing performance bottlenecks and improving the overall function of your Apache server.

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

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

Appendix B covers some basic troubleshooting techniques, where to look for messages, common configuration problems, etc.

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:

Italic

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

Bold

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.

Tip

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

Warning

This icon indicates a warning or caution.

Documentation Conventions

Since 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:

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:

http://httpd.apache.org/docs/mod/mod_auth.html

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:

http://httpd.apache.org/docs/mod/directives.html

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.

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:

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

O’Reilly & Associates, Inc.

1005 Gravenstein Highway North

Sebastopol, CA 95472

[phone] (in the United States or Canada)

[phone] (international or local)

[phone] (fax)

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

http://www.oreilly.com/catalog/apacheckbk

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

[e-mail]

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

http://www.oreilly.com

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:

http://Apache-Cookbook.Com/

Acknowledgments

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 father, Richard J. Coar, for all the various kinds of support he has provided over the years.

My sincere thanks go out to the crew at O’Reilly, including Paula and Nat, who apparently never gave up hope regardless of how many deadlines whooshed past unmet. Thanks also to the WriterBase Authors Support Group and Cabal mailing lists, whereon much balm and advice was offered. Our technical reviewers Morbus and Quasi provided much excellent feedback and helped make this a better book. The VMware software package was very useful, and I’m grateful to its makers for their help and support.

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 Sarah, who is the motivation for all the important things I do.

While it would be impossible to adequately thank all the folks who made this book possible, there are some people, in addition to those already mentioned, that I’d like to especially thank.

A huge thank you to our technical reviewers. You created a huge quantity of additional work for us, made our lives miserable, and made the book late. I don’t think I’ve ever had such a thorough tech review, and the comments that you made served to make this a much better book than it otherwise would have been. Without quasi, large parts of the book would have been significantly less complete—and less correct. And Morbus gave the entire project the sort of surreal, other-worldly aura that you expect from...well, from Morbus. Thank you both and to the many other people who made various remarks about what we’d written.

To my wonderful family, thank you all. You have helped me through a very difficult time, and shown more love, patience, and acceptance than I deserve. Mom and Dad, I love you. Ruth, you have given me the courage to plough on. Andy, you are my hero.

Thanks to the folks on the Apache web server documentation project. The Apache documentation is some of the best in the world of free software. Thanks to the dedication and attention to detail.

To the folks on irc.freenode.net, you are the ones who made this book happen. The recipes in this book are answers to questions that you asked, refined over time by dozens and dozens of people who asked them again and again and again.

And, finally, thanks to the members of the Geocachers of Central Kentucky (http://www.geocky.org/) for getting me hooked on Geocaching, and placing the caches around the area, giving me something to go out and do when my sanity was stretched a little thin.

---

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