Table of • Contents • Index • Reviews • Examples Reader • Reviews • Errata Apache The Definitive Guide, 3rd Edition By Ben Laurie, Peter Laurie Publisher : O'Reilly Pub Date : December 2002 ISBN : 0-596-00203-3 Updated to cover the changes in Apache's latest release, 2.0, as well as Apache 1.3, this useful guide discusses how to obtain, set up, secure, modify, and troubleshoot the Apache software on both Unix and Windows systems In addition to covering the installation and configuration of mod_perl and Tomcat, the book examines PHP, Cocoon, and other new technologies that are associated with the Apache web server 777 Copyright Preface Who Wrote Apache, and Why? The Demonstration Code Conventions Used in This Book Organization of This Book Acknowledgments Chapter 1 Getting Started Section 1.1 What Does a Web Server Do? Section 1.2 How Apache Works Section 1.3 Apache and Networking Section 1.4 How HTTP Clients Work Section 1.5 What Happens at the Server End? Section 1.6 Planning the Apache Installation Section 1.7 Windows? Section 1.8 Which Apache? Section 1.9 Installing Apache Section 1.10 Building Apache 1.3.X Under Unix Section 1.11 New Features in Apache v2 Section 1.12 Making and Installing Apache v2 Under Unix Section 1.13 Apache Under Windows Chapter 2 Configuring Apache: The First Steps Section 2.1 What's Behind an Apache Web Site? Section 2.2 site.toddle Section 2.3 Setting Up a Unix Server Section 2.4 Setting Up a Win32 Server Section 2.5 Directives Section 2.6 Shared Objects Chapter 3 Toward a Real Web Site Section 3.1 More and Better Web Sites: site.simple Section 3.2 Butterthlies, Inc., Gets Going Section 3.3 Block Directives Section 3.4 Other Directives Section 3.5 HTTP Response Headers Section 3.6 Restarts Section 3.7 .htaccess Section 3.8 CERN Metafiles Section 3.9 Expirations Chapter 4 Virtual Hosts Section 4.1 Two Sites and Apache Section 4.2 Virtual Hosts Section 4.3 Two Copies of Apache Section 4.4 Dynamically Configured Virtual Hosting Chapter 5 Authentication Section 5.1 Authentication Protocol Section 5.2 Authentication Directives Section 5.3 Passwords Under Unix Section 5.4 Passwords Under Win32 Section 5.5 Passwords over the Web Section 5.6 From the Client's Point of View Section 5.7 CGI Scripts Section 5.8 Variations on a Theme Section 5.9 Order, Allow, and Deny Section 5.10 DBM Files on Unix Section 5.11 Digest Authentication Section 5.12 Anonymous Access Section 5.13 Experiments Section 5.14 Automatic User Information Section 5.15 Using htaccess Files Section 5.16 Overrides Chapter 6 Content Description and Modification Section 6.1 MIME Types Section 6.2 Content Negotiation Section 6.3 Language Negotiation Section 6.4 Type Maps Section 6.5 Browsers and HTTP 1.1 Section 6.6 Filters Chapter 7 Indexing Section 7.1 Making Better Indexes in Apache Section 7.2 Making Our Own Indexes Section 7.3 Imagemaps Section 7.4 Image Map Directives Chapter 8 Redirection Section 8.1 Alias Section 8.2 Rewrite Section 8.3 Speling Chapter 9 Proxying Section 9.1 Security Section 9.2 Proxy Directives Section 9.3 Apparent Bug Section 9.4 Performance Section 9.5 Setup Chapter 10 Logging Section 10.1 Logging by Script and Database Section 10.2 Apache's Logging Facilities Section 10.3 Configuration Logging Section 10.4 Status Chapter 11 Security Section 11.1 Internal and External Users Section 11.2 Binary Signatures, Virtual Cash Section 11.3 Certificates Section 11.4 Firewalls Section 11.5 Legal Issues Section 11.6 Secure Sockets Layer (SSL) Section 11.7 Apache's Security Precautions Section 11.8 SSL Directives Section 11.9 Cipher Suites Section 11.10 Security in Real Life Section 11.11 Future Directions Chapter 12 Running a Big Web Site Section 12.1 Machine Setup Section 12.2 Server Security Section 12.3 Managing a Big Site Section 12.4 Supporting Software Section 12.5 Scalability Section 12.6 Load Balancing Chapter 13 Building Applications Section 13.1 Web Sites as Applications Section 13.2 Providing Application Logic Section 13.3 XML, XSLT, and Web Applications Chapter 14 Server-Side Includes Section 14.1 File Size Section 14.2 File Modification Time Section 14.3 Includes Section 14.4 Execute CGI Section 14.5 Echo Section 14.6 Apache v2: SSI Filters Chapter 15 PHP Section 15.1 Installing PHP Section 15.2 Site.php Chapter 16 CGI and Perl Section 16.1 The World of CGI Section 16.2 Telling Apache About the Script Section 16.3 Setting Environment Variables Section 16.4 Cookies Section 16.5 Script Directives Section 16.6 suEXEC on Unix Section 16.7 Handlers Section 16.8 Actions Section 16.9 Browsers Chapter 17 mod_perl Section 17.1 How mod_perl Works Section 17.2 mod_perl Documentation Section 17.3 Installing mod_perl — The Simple Way Section 17.4 Modifying Your Scripts to Run Under mod_perl Section 17.5 Global Variables Section 17.6 Strict Pregame Section 17.7 Loading Changes Section 17.8 Opening and Closing Files Section 17.9 Configuring Apache to Use mod_perl Chapter 18 mod_jserv and Tomcat Section 18.1 mod_jserv Section 18.2 Tomcat Section 18.3 Connecting Tomcat to Apache Chapter 19 XML and Cocoon Section 19.1 XML Section 19.2 XML and Perl Section 19.3 Cocoon Section 19.4 Cocoon 1.8 and JServ Section 19.5 Cocoon 2.0.3 and Tomcat Section 19.6 Testing Cocoon Chapter 20 The Apache API Section 20.1 Documentation Section 20.2 APR Section 20.3 Pools Section 20.4 Per-Server Configuration Section 20.5 Per-Directory Configuration Section 20.6 Per-Request Information Section 20.7 Access to Configuration and Request Information Section 20.8 Hooks, Optional Hooks, and Optional Functions Section 20.9 Filters, Buckets, and Bucket Brigades Section 20.10 Modules Chapter 21 Writing Apache Modules Section 21.1 Overview Section 21.2 Status Codes Section 21.3 The Module Structure Section 21.4 A Complete Example Section 21.5 General Hints Section 21.6 Porting to Apache 2.0 Appendix A The Apache 1.x API Section A.1 Pools Section A.2 Per-Server Configuration Section A.3 Per-Directory Configuration Section A.4 Per-Request Information Section A.5 Access to Configuration and Request Information Section A.6 Functions Colophon Index Copyright Copyright © O'Reilly & Associates, Inc Printed in the United States of America Published by O'Reilly & Associates, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472 O'Reilly & Associates 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 corporate@oreilly.com Nutshell Handbook, the Nutshell Handbook logo, and the O'Reilly logo are registered trademarks of O'Reilly & Associates, Inc Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks Where those designations appear in this book, and O'Reilly & Associates, Inc was aware of a trademark claim, the designations have been printed in caps or initial caps The association between the image of Appaloosa horse and the topic of Apache is a trademark of O'Reilly & Associates, Inc 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 Preface Apache: The Definitive Guide, Third Edition, is principally about the Apache web-server software We explain what a web server is and how it works, but our assumption is that most of our readers have used the World Wide Web and understand in practical terms how it works, and that they are now thinking about running their own servers and sites This book takes the reader through the process of acquiring, compiling, installing, configuring, and modifying Apache We exercise most of the package's functions by showing a set of example sites that take a reasonably typical web business — in our case, a postcard publisher — through a process of development and increasing complexity However, we have deliberately tried to make each site as simple as possible, focusing on the particular feature being described Each site is pretty well self-contained, so that the reader can refer to it while following the text without having to disentangle the meat from extraneous vegetables If desired, it is possible to install and run each site on a suitable system Perhaps it is worth saying what this book is not It is not a manual, in the sense of formally documenting every command — such a manual exists on the Apache site and has been much improved with Versions 1.3 and 2.0; we assume that if you want to use Apache, you will download it and keep it at hand Rather, if the manual is a road map that tells you how to get somewhere, this book tries to be a tourist guide that tells you why you might want to make the journey In passing, we do reproduce some sections of the web site manual simply to save the reader the trouble of looking up the formal definitions as she follows the argument Occasionally, we found the manual text hard to follow and in those cases we have changed the wording slightly We have also interspersed comments as seemed useful at the time This is not a book about HTML or creating web pages, or one about web security or even about running a web site These are all complex subjects that should be either treated thoroughly or left alone As a result, a webmaster's library might include books on the following topics: The Web and how it works HTML — formal definitions, what you can do with it How to decide what sort of web site you want, how to organize it, and how to protect it How to implement the site you want using one of the available servers (for instance, Apache) Handbooks on Java, Perl, and other languages Security Apache: The Definitive Guide is just one of the six or so possible titles in the fourth category Apache is a versatile package and is becoming more versatile every day, so we have not tried to illustrate every possible combination of commands; that would require a book of a million pages or so Rather, we have tried to suggest lines of development that a typical webmaster could follow once an understanding of the basic concepts is achieved We realized from our own experience that the hardest stage of Unix systems Win32 systems pathnames 2nd paths API functions pcalloc( ) pclosef( ) per-directory configuration 2nd 3rd 4th per-request information 2nd per-server configuration 2nd 3rd 4th performance caching PK encryption performance tuning, mod_perl use Perl flags, mod_perl XML and permissions (Unix) suEXEC utility persistent-state cookies 2nd pfclose( ) pfdopen( ) pfopen( ) PidFile directive PIDs (process identifiers) pinging IP addresses pipe buckets piped logs, API functions PK encryption pool functions, API pools 2nd popenf( ) Port directive port-based virtual hosting porting to Apache 2.0 ports 2nd 3rd POST method (HTTP) post read requests preconfiguration pregcomp( ) prerun fixups to modules privacy [See encryption security] process functions, API process identifiers (PIDs) processes killing limiting for CGI scripts protocols proxy servers configuring cache ProxyDomain directive ProxyPass directive ProxyPassReverse directive ProxyRemote directive ProxyRequests directive ps utility pstrcat( ) pstrdup( ) pstrndup( ) public key encryption push_array( ) PUT method (HTTP) [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] quality scores (qs values) -? flag (httpd/apache) [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] read permission realms, authentication redirection URL substitutions RedirectMatch directive register_cleanup( ) registration, functions, hooks and regular expressions API functions for URLs release_semaphore( ) remote proxy servers Remote-Addr header Remote-Host header Remote-User header Request-Method header request_rec structure Request-URI header request-handling API functions request_rec structure requests information on maximum wait time per-request information 2nd post read requests status information require directive reset_event( ) reset_timeout( ) resource pools 2nd response codes, HTTP 2nd response headers restart flag (apachect1) restarting httpd reverse-DNS lookups rewrite module RewriteBase directive RewriteCond directive RewriteEngine directive RewriteLog directive RewriteLogLevel directive RewriteMap directive RewriteRule directive rewriting URLs example of RLimitCPU directive RLimitMEM directive RLimitNPROC directive root certificates root user 2nd routers rputc( ) rputs( ) run_sub_req( ) rvprintf( ) rvputs( ) [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] -s flag (apache) satisfy directive ScoreBoardFile directive ScriptAlias directive 2nd ScriptAliasMatch directive 2nd 3rd ScriptLog directive ScriptLogBuffer directive ScriptLogLength directive scripts, CGI [See CGI] SE Linux Secure Sockets Layer [See SSL] security access control anonymous access Apache v2 and SSL authentication [See authentication] certificates server certificates test certificates cipher suites CookBook security digital signatures encryption EROS firewalls fixed-length buffers future of .htaccess file [See htaccess file] IgnoreIndex directive and legal issues logging and [See logging] passwords precautions real-life applications SE Linux SSL Apache v1.3 and directives suEXEC wrapper for CGI Unix and Unix permissions Win32 2nd semaphores semiformatted menus send-as-is handler send_fd( ) send_fd_length( ) send_http_header( ) SendBufferSize directive separate networks server configuration files Unix, setting up Win32, setting up server certificates server-info handler server information functions, API server-parsed handler server-status handler server-side includes CGI scripts executed as 2nd IncludesNoExec (Options directive) 2nd XSSI facility server_rec structure 2nd 3rd ServerAdmin directive ServerAlias directive ServerName directive 2nd 3rd ServerPath directive ServerRoot directive servers configuration, per-server configuration information on maximum wait for requests per-server configuration 2nd proxy servers ServerSignature directive ServerTokens directive ServerType directive service, Apache as (Win32) servlets JServ writing Tomcat testing writing set_event( ) set_string_slot( ) SetEnv directive 2nd SetEnvIf directive SetEnvIfNoCase directive SetHandler directive 2nd 3rd setup_client_block( ) SGML (Standard Generalized Markup Language) shell output should_client_block( ) .shtml filename extension Simple Mail Transfer Protocol (SMTP) size cache files pool TCP send buffer SMTP (Simple Mail Transfer Protocol) socket buckets sockets, API functions SOCKS rules soft_timeout( ) spawn_child_err( ) spell-checking URLs SSL (Secure Sockets Layer) Apache v1.3 and Apache v2 and Apache-SSL directives global session cache mod_ssl, Apache v1.3 and OpenSSL SSLBanCipher directive 2nd SSLCACertificateFile directive SSLCACertificatePath directive SSLCacheServerPath directive SSLCacheServerPort directive SSLCacheServerRunDir directive SSLCertificateFile directive SSLCertificateKeyFile directive SSLCipherSuite SSLDisable directive SSLEnable directive SSLExportClientCertificates directive SSLFakeBasicAuth directive SSLLogFile directive SSLRequireCipher directive SSLRequiredCiphers directive SSLRequireSSL directive SSLSessionCacheTimeout directive SSLVerifyClient directive SSLVerifyDepth directive standalone mode ServerType Standard Generalized Markup Language (SGML) start flag (apachect1) status codes, HTTP 2nd status flag (apachect1) STATUS rule stop flag (apachect1) stop script (example) strcasecmp_match( ) strcmp_match( ) strftime( ) string functions, API structures hooks optional hooks sub_req_lookup_file( ) sub_req_lookup_uri( ) subnet masks substitutions within URLs suEXEC wrapper superuser 2nd symbolic links 2nd SymLinksIfOwnerMatch option (Options) synchronization, API functions [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] table functions, API table_add( ) 2nd table_elts( ) table_get( ) table_merge( ) 2nd table_set( ) 2nd table_unset( ) TCP (Transmission Control Protocol) send buffer size TCP/IP API functions testing if running telnet test certificates testing Cocoon mod_perl servlets, Tomcat TFTP protocol threads, API functions time caching-related display format expiring [See expiring] time and date functions, API TimeOut directive timeout functions, API tm2sec( ) Tomcat 2nd Cocoon and Conf file connecting to Apache directories installation mod_jk servlets testing writing TRACE method (HTTP) TransferLog directive translating URLs to names Transmission Control Protocol [See TCP] troubleshooting imagemaps installation, mod_perl logging errors 2nd prerun mixups to modules proxy server configuration security precautions spelling of URLs SSL suEXEC utility type checker type-map handler type maps typesafety, hooks and TypesConfig directive 2nd [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] -u flag (apache) UDP (User Datagram Protocol) "unable to get hostbyname" error uname2id( ) unblock_alarms( ) unescape_url( ) unformatted menus uniform resource identifiers [See URIs] uniform resource locators [See URLs] unique_id_child_init( ) Unix operating system configuring server DBM files making Apache multiple IP addresses passwords permissions restarting Apache security and suEXEC wrapper versions of uri_components structure URIs (uniform resource identifiers) API functions URLs (uniform resource locators) 2nd API functions digest authentication 2nd imagemaps limiting directives to redirecting upon errors rewriting spell-checking translating to names UseCanonicalName directive User Datagram Protocol (UDP) User directive 2nd 3rd 4th 5th 6th 7th 8th UserDir directive users API functions automatic information on checking if access allowed creating DBM files home directories permissions [See permissions] security and uudecode( ) [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] -v flag (httpd/apache) -V flag (httpd/apache) .var files [See type maps] variables environment access control global, mod_perl printing 2nd versions Apache 2nd HTTP, forcing to 1.0 SOCKS Unix virtual attribute (include command) virtual cash virtual hosts 2nd 3rd [See also multiple copies of Apache] directive 2nd [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] WANTHSREGEX rule Weather Observation Definition Format web addresses [See URLs] web browsers HTTP 1.1 and icons and imagemaps Web of Trust (WOT), certificates and web redirection web servers information on controlling access to maximum wait for requests per-server configuration 2nd 3rd 4th 5th proxy servers web sites defined demonstration multiple [See virtual hosts] webgroup group (example) webuser user (example) Win32 configuring server home directories multiple IP addresses passwords restarting Apache security 2nd time display format versions of Apache Windows OS [See Win32] WOT (Web of Trust), certificates and wrappers writing modules writing permission [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] XML (Extensible Markup Language) overview Perl and vocabularies XSSI facility [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] [Y] Year 2000 and time formats ... quite properly, want to be paid for doing the work everyone loathes The Demonstration Code The code for the demonstration web sites referred to throughout the book is available at http://www .oreilly. com/catalog /apache3 / It contains the requisite README file with installation instructions and... When a request appears, Apache receives it and analyzes the headers It then applies the rules it finds in the Config file and takes the appropriate action The webmaster's main control over Apache is through the Config file The webmaster has some 200 directives at her disposal, and most of this book is an... native English speaker, we rearranged the syntax a little As they stand, they save the reader having to break off and go to the Apache site 1.3 Apache and Networking At its core, Apache is about communication over networks Apache uses the