Apache Cookbook Rich Bowen Ken Coar Copyright © 2009 Ken Coar and Rich Bowen O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://safari.oreilly.com). For more information, contact our corporate/institutional sales department: (800) 998-9938 or [email protected]. Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. The Cookbook series designations, Apache Cookbook, the image of a moose, and related trade dress are trademarks of O’Reilly Media, Inc. Many of the designations uses by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. This book uses RepKover™, a durable and flexible lay-flat binding. O'Reilly Media 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, 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 files. .htaccess 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! [1] An obscure reference to a board game called Clue and an obscure developer of HTTP. 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: 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-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 [email protected] 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.