Writing Apache Modules with Perl and C
Lincoln Stein
Doug MacEachern
Publisher: O'Reilly
First Edition March 1999
ISBN: 1-56592-567-X, 746 pages
This guide to Web programming teaches you how to extend the
capabilities of the Apache Web server. It explains the design of
Apache, mod_perl, and the Apache API, then demonstrates how
to use them to rewrite CGI scripts, filter HTML documents on
the server-side, enhance server log functionality, convert file
formats on the fly, and more.
1
2
Copyright © 1999 O'Reilly & Associates, Inc. All rights reserved.
Printed in the United States of America.
Published by O'Reilly & Associates, Inc., 101 Morris Street, Sebastopol, CA 95472.
The O'Reilly logo is a registered trademark 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 use of the white-tailed eagle image in association with Apache modules is a trademark of
O'Reilly & Associates, Inc.
While every precaution has been taken in the preparation of this book, the publisher assumes
no responsibility for errors or omissions, or for damages resulting from the use of the
information contained herein.
3
Preface
What You Need to Know to Get the Most out of This Book
How This Book Is Organized
Conventions
The Companion Web Site to This Book
Using FTP and CPAN
Comments and Questions
Acknowledgments
1. Server-Side Programming with Apache
1.1 Web Programming Then and Now
1.2 The Apache Project
1.3 The Apache C and Perl APIs
1.4 Ideas and Success Stories
2. A First Module
2.1 Preliminaries
2.2 Directory Layout Structure
2.3 Installing mod_perl
2.4 "Hello World" with the Perl API
2.5 "Hello World" with the C API
2.6 Instant Modules with Apache::Registry
2.7 Troubleshooting Modules
3. The Apache Module Architecture and API
3.1 How Apache Works
3.2 The Apache Life Cycle
3.3 The Handler API
3.4 Perl API Classes and Data Structures
4. Content Handlers
4.1 Content Handlers as File Processors
4.2 Virtual Documents
4.3 Redirection
4.4 Processing Input
4.5 Apache::Registry
4.6 Handling Errors
4.7 Chaining Content Handlers
4.8 Method Handlers
5. Maintaining State
5.1 Choosing the Right Technique
5.2 Maintaining State in Hidden Fields
5.3 Maintaining State with Cookies
5.4 Protecting Client-Side Information
5.5 Storing State at the Server Side
5.6 Storing State Information in SQL Databases
5.7 Other Server-Side Techniques
6. Authentication and Authorization
6.1 Access Control, Authentication, and Authorization
6.2 Access Control with mod_perl
6.3 Authentication Handlers
6.4 Authorization Handlers
6.5 Cookie-Based Access Control
4
6.6 Authentication with the Secure Sockets Layer
7. Other Request Phases
7.1 The Child Initialization and Exit Phases
7.2 The Post Read Request Phase
7.3 The URI Translation Phase
7.4 The Header Parser Phase
7.5 Customizing the Type Checking Phase
7.6 Customizing the Fixup Phase
7.7 The Logging Phase
7.8 Registered Cleanups
7.9 Handling Proxy Requests
7.10 Perl Server-Side Includes
7.11 Subclassing the Apache Class
8. Customizing the Apache Configuration Process
8.1 Simple Configuration with the PerlSetVar Directive
8.2 The Apache Configuration Directive API
8.3 Configuring Apache with Perl
8.4 Documenting Configuration Files
9. Perl API Reference Guide
9.1 The Apache Request Object
9.2 Other Core Perl API Classes
9.3 Configuration Classes
9.4 The Apache::File Class
9.5 Special Global Variables, Subroutines, and Literals
10. C API Reference Guide, Part I
10.1 Which Header Files to Use?
10.2 Major Data Structures
10.3 Memory Management and Resource Pools
10.4 The Array API
10.5 The Table API
10.6 Processing Requests
10.7 Server Core Routines
11. C API Reference Guide, Part II
11.1 Implementing Configuration Directives in C
11.2 Customizing the Configuration Process
11.3 String and URI Manipulation
11.4 File and Directory Management
11.5 Time and Date Functions
11.6 Message Digest Algorithm Functions
11.7 User and Group ID Information Routines
11.8 Data Mutex Locking
11.9 Launching Subprocesses
A. Standard Noncore Modules
A.1 The Apache::Registry Class
A.2 The Apache::PerlRun Class
A.3 The Apache::RegistryLoader Class
A.4 The Apache::Resource Class
A.5 The Apache::PerlSections Class
A.6 The Apache::ReadConfig Class
A.7 The Apache::StatINC Class
A.8 The Apache::Include Class