the apache modules book - application development with apache

www.sharexxx.net - free books & magazines
The Apache Modules Book
Prentice Hall
Open Source Software Development Series
Arnold Robbins, Series Editor
“Real world code from real world applications”
Open Source technology has revolutionized the computing world. Many large-scale projects are
in production use worldwide, such as Apache, MySQL, and Postgres, with programmers writing
applications in a variety of languages including Perl, Python, and PHP. These technologies are in
use on many different systems, ranging from proprietary systems, to Linux systems, to traditional
UNIX systems, to mainframes.
The Prentice Hall Open Source Software Development Series is designed to bring you the
best of these Open Source technologies. Not only will you learn how to use them for your
projects, but you will learn from them. By seeing real code from real applications, you will learn
the best practices of Open Source developers the world over.
Titles currently in the series include:
Linux
®
Debugging and Performance Tuning: Tips and Techniques
Steve Best
0131492470, Paper, ©2006
Understanding AJAX: Using JavaScript to Create Rich Internet Applications
Joshua Eichorn
0132216353, Paper, ©2007
Embedded Linux Primer
Christopher Hallinan
0131679848, Paper, ©2007
SELinux by Example
Frank Mayer, David Caplan, Karl MacMillan
0131963694, Paper, ©2007
UNIX to Linux® Porting

Alfredo Mendoza, Chakarat Skawratananond, Artis Walker
0131871099, Paper, ©2006
Linux Programming by Example: The Fundamentals
Arnold Robbins
0131429647, Paper, ©2004
The Linux
®
Kernel Primer: A Top-Down Approach for x86 and PowerPC Architectures
Claudia Salzberg, Gordon Fischer, Steven Smolski
0131181637, Paper, ©2006
The Apache Modules Book
Application Development
with Apache
Nick Kew
Upper Saddle River, NJ • Boston • Indianapolis • San Francisco
New York • Toronto • Montreal • London • Munich • Paris
Madrid • Cape Town • Sydney • Tokyo • Singapore • Mexico City
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trade-
marks. Where those designations appear in this book, and the publisher was aware of a trademark claim, the
designations have been printed with initial capital letters or in all capitals.
The author and publisher have taken care in the preparation of this book, but make no expressed or implied war-
ranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for incidental or con-
sequential damages in connection with or arising out of the use of the information or programs contained herein.
The publisher offers excellent discounts on this book when ordered in quantity for bulk purchases or special
sales, which may include electronic versions and/or custom covers and content particular to your business,
training goals, marketing focus, and branding interests. For more information, please contact:
U.S. Corporate and Government Sales
(800) 382-3419

For sales outside the United States, please contact:

International Sales

Visit us on the Web: www.prenhallprofessional.com
Library of Congress Cataloging-in-Publication Data
Kew, Nick.
The Apache modules book : application development with Apache / Nick Kew.
p. cm.
Includes bibliographical references and index.
ISBN 0-13-240967-4 (pbk. : alk. paper)
1. Apache (Computer file : Apache Group) 2. Web servers—Computer programs. 3. Application software—
Development. I. Title.
TK5105.8885.A63K49 2007
005.7'1376—dc22
2006036623
Copyright © 2007 Pearson Education, Inc.
All rights reserved. Printed in the United States of America. This publication is protected by copyright, and per-
mission must be obtained from the publisher prior to any prohibited reproduction, storage in a retrieval sys-
tem, or transmission in any form or by any means, electronic, mechanical, photocopying, recording, or likewise.
For information regarding permissions, write to:
Pearson Education, Inc.
Rights and Contracts Department
One Lake Street
Upper Saddle River, NJ 07458
Fax: (201) 236-3290
ISBN 0-13-240967-4
Text printed in the United States on recycled paper at RR Donnelley in Crawfordsville, Indiana.
First printing, January 2007
To all who share my dream, and are working to help make it happen …
… the dream of a world where your work, your colleagues, and your opportunities
in life are not dictated by where you live or how far you commute. Where the

old-fashioned office of the nineteenth and twentieth centuries has passed into
history, along with its soul-destroying bums-on-seats culture and Dilbertian work
practices. A world inclusive of those who cannot work in a standard office. A world
inclusive of those who reject car-dependence, but embrace a full and active life.
A world inclusive of those who seek to fit study and learning into a busy life, yet
have no accessible library, let alone university. Of those who are housebound …
Our information infrastructure is poised to liberate us all. We who develop
with Apache are playing a small but exciting part in that. This work is
dedicated to all of us!
This page intentionally left blank
Foreword. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
About the Author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxix
Chapter 1 Applications Development with Apache . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 A Brief History of the Apache Web Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1.1 Apache 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1.2 Apache 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 The Apache Software Foundation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2.1 Meritocracy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.2 Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.3 Philosophy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3 The Apache Development Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3.1 The Apache Codebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.2 Development Forums. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.3.3 Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.3.4 Participation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.4 Apache and Intellectual Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.4.1 The Apache License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.4.2 Third-Party Intellectual Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.5 Further Reading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.5.1 Interactive Online Forums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.5.2 Conferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.5.3 Websites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
vii
Contents
Chapter 2 The Apache Platform and Architecture . . . . . . . . . . . . . . . . . . . . . . . 21
2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.2 Two-Phase Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.2.1 Start-up Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.2.2 Operational Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.2.3 Shutdown. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.3 Multi-Processing Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.3.1 Why MPMs? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.3.2 The UNIX-Family MPMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.3.3 Working with MPMs and Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.4 Basic Concepts and Structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.4.1 request_rec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.4.2 server_rec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
2.4.3 conn_rec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
2.4.4 process_rec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.5 Other Key API Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
2.6 Apache Configuration Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
2.7 Request Processing in Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
2.7.1 Content Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
2.7.2 Request Processing Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.7.3 Processing Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
2.7.4 The Data Axis and Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
2.7.5 Order of Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

2.7.6 Processing Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
2.8 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Chapter 3 The Apache Portable Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
3.1 APR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
3.2 APR-UTIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
3.3 Basic Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
3.3.1 Reference Manual: API Documentation and Doxygen. . . . . . . . . . . . . . . . . . . 57
3.3.2 Namespacing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
3.3.3 Declaration Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
3.3.4 apr_status_t and Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
3.3.5 Conditional Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
viii Contents
3.4 Resource Management: APR Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
3.4.1 The Problem of Resource Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
3.4.2 APR Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
3.4.3 Resource Lifetime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
3.4.4 Limitations of Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
3.5 Selected APR Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
3.5.1 Strings and Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
3.5.2 Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
3.5.3 Time and Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
3.5.4 Data Structs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
3.5.5 Buckets and Brigades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
3.5.6 Filesystem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
3.5.7 Network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
3.5.8 Encoding and Cryptography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
3.5.9 URI Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
3.5.10 Processes and Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.5.11 Resource Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
3.5.12 API Extensions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

3.6 Databases in APR/Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
3.6.1 DBMs and apr_dbm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
3.6.2 SQL Databases and apr_dbd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
3.7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Chapter 4 Programming Techniques and Caveats. . . . . . . . . . . . . . . . . . . . . . . . 85
4.1 Apache Coding Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
4.1.1 Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
4.1.2 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
4.1.3 Blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
4.1.4 Flow Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
4.1.5 Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
4.1.6 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
4.2 Managing Module Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
4.2.1 Configuration Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
4.2.2 Lifetime Scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
4.3 Communicating Between Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
4.4 Thread-Safe Programming Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Contents ix
4.5 Managing Persistent Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.5.1 Thread Safety . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
4.5.2 Memory/Resource Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
4.6 Cross-Platform Programming Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
4.6.1 Example: Creating a Temporary File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.7 Cross-MPM Programming Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
4.7.1 Process and Global Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.7.2 Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
4.8 Secure Programming Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
4.8.1 The Precautionary Principle: Trust Nothing . . . . . . . . . . . . . . . . . . . . . . . . . . 107
4.8.2 Denial of Service: Limit the Damage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
4.8.3 Help the Operating System to Help You . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

4.9 External Dependencies and Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
4.9.1 Third-Part Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
4.9.2 Library Good Practice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
4.9.3 Building Modules with Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
4.10 Modules Written and Compiled in Other Languages . . . . . . . . . . . . . . . . . . . . . 120
4.11 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Chapter 5 Writing a Content Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
5.1 The HelloWorld Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
5.1.1 The Module Skeleton. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
5.1.2 Return Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
5.1.3 The Handler Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
5.1.4 The Complete Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
5.1.5 Using the request_rec Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5.2 The Request, the Response, and the Environment. . . . . . . . . . . . . . . . . . . . . . . . . 130
5.2.1 Module I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
5.2.2 Reading Form Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
5.3 The Default Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
5.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Chapter 6 Request Processing Cycle and Metadata Handlers . . . . . . . . . . . . . . 151
6.1 HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
6.1.1 The HTTP Protocol. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
6.1.2 Anatomy of an HTTP Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
x Contents
6.2 Request Processing in Apache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
6.2.1 Mapping to the Filesystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
6.2.2 Content Negotiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
6.2.3 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.2.4 Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.2.5 Private Metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
6.2.6 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

6.3 Diverting a Request: The Internal Redirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
6.3.1 Error Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
6.3.2 Dealing with Malformed and Malicious Requests . . . . . . . . . . . . . . . . . . . . . 163
6.4 Gathering Information: Subrequests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
6.4.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
6.5 Developing a Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
6.5.1 Selecting Different Variants of a Document . . . . . . . . . . . . . . . . . . . . . . . . . . 168
6.5.2 Error Handling and Reusability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
6.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Chapter 7 AAA: Access, Authentication, and Authorization . . . . . . . . . . . . . . . 177
7.1 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
7.1.1 Authentication: Levels of Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
7.1.2 Login on the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
7.2 An Overview of AAA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
7.3 AAA in Apache 1.x and 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
7.4 AAA in Apache 2.1/2.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
7.4.1 Host-Based Access Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
7.4.2 Authentication: check_user_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
7.4.3 Password Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
7.4.4 Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
7.5 AAA Logic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
7.5.1 Authentication and Require . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
7.5.2 Denying Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
7.5.3 Authentication Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
7.6 Writing AAA Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
7.6.1 A Basic Authentication Provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
7.6.2 An Authorization Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
7.6.3 Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
7.6.4 Basic and Digest Authentication Providers . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Contents xi

7.7 Implementing a Custom Login Scheme. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
7.7.1 Session Management with SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
7.7.2 Working Without Browser Authentication Dialogs . . . . . . . . . . . . . . . . . . . . 197
7.8 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Chapter 8 Filter Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
8.1 Input and Output Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
8.2 Content, Protocol, and Connection Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
8.3 Anatomy of a Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
8.3.1 Callback Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
8.3.2 Pipelining. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
8.4 The Filter API and Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
8.4.1 Output Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
8.4.2 Input Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
8.5 Filter Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
8.6 Filter I/O. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
8.7 Smart Filtering in Apache 2.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
8.7.1 Preprocessing and Postprocessing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
8.7.2 mod_filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
8.7.3 Filter Self-configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
8.7.4 Protocol Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
8.8 Example: Filtering Text by Direct Manipulation of Buckets . . . . . . . . . . . . . . . . . 217
8.8.1 Bucket Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
8.8.2 The Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
8.9 Complex Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
8.10 Filtering Through an Existing Parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
8.11 stdio-Like Filter I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
8.12 Input Filters and the Pull API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
8.12.1 Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
8.12.2 Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
8.12.3 readbytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

8.12.4 Input Filter Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
8.13 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
xii Contents
Chapter 9 Configuration for Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
9.1 Configuration Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
9.2 Configuration Data Structs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
9.3 Managing a Module Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
9.3.1 Module Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
9.3.2 Server and Directory Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
9.4 Implementing Configuration Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
9.4.1 Configuration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
9.4.2 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
9.4.3 User Data in Configuration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
9.4.4 Prepackaged Configuration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
9.4.5 Scope of Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
9.4.6 Configuration Function Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
9.5 The Configuration Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
9.6 Context in Configuration Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
9.6.1 Context Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
9.6.2 Method and <Limit> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
9.7 Custom Configuration Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
9.8 Alternative Configuration Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
9.9 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Chapter 10 Extending the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
10.1 Implementing New Functions in Apache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
10.1.1 Exporting Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
10.1.2 Optional Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
10.2 Hooks and Optional Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
10.2.1 A Closer Look at Hooks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
10.2.2 Order of Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

10.2.3 Optional Hooks Example: mod_authz_dbd. . . . . . . . . . . . . . . . . . . . . . . . . 270
10.3 The Provider API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
10.3.1 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
10.3.2 Implementing a Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
10.4 Providing a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
10.4.1 Example: mod_dbd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
10.4.2 Implementing the reslist. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Contents xiii
10.5 Cross-Platform API Builds. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
10.5.1 Using Preprocessor Directives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
10.5.2 Declaring the Module API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
10.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Chapter 11 The Apache Database Framework . . . . . . . . . . . . . . . . . . . . . . . . . . 289
11.1 The Need for a New Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
11.1.1 Apache 1.x/2.0 Versus Apache 2.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
11.1.2 Connection Pooling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
11.2 The DBD Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
11.3 The apr_dbd API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
11.3.1 Database Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
11.3.2 API Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
11.4 The ap_dbd API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
11.5 An Example Application Module: mod_authn_dbd . . . . . . . . . . . . . . . . . . . . . . 303
11.6 Developing a New DBD Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
11.6.1 The apr_dbd_internal.h Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
11.6.2 Exporting a Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
11.6.3 The Driver Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
11.7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Chapter 12 Module Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
12.1 Logging for Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
12.1.1 The Error Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

12.1.2 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
12.2 Running Apache Under a Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
12.2.1 Server Start-up and Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
12.2.2 Debugging and MPMs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
12.2.3 Tracing a Crash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
12.2.4 Debugging a Core Dump. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
12.3 Special-Purpose Hooks and Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
12.3.1 Standard Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
12.3.2 Fatal Exception Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
12.3.3 Modules to Deal with Abnormal Running . . . . . . . . . . . . . . . . . . . . . . . . . . 337
xiv Contents
12.4 Filter Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
12.4.1 mod_diagnostics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
12.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Appendix A Apache License. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Appendix B Contributor License Agreements . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Individual CLA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Corporate CLA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Appendix C Hypertext Transfer Protocol: HTTP/1.1 . . . . . . . . . . . . . . . . . . . . . 357
Status of This Memo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Copyright Notice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
1.1 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
1.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
1.3 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
1.4 Overall Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
2 Notational Conventions and Generic Grammar . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
2.1 Augmented BNF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
2.2 Basic Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

3 Protocol Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
3.1 HTTP Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
3.2 Uniform Resource Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
3.3 Date/Time Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
3.4 Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
3.5 Content Codings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
3.6 Transfer Codings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
3.7 Media Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
3.8 Product Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
3.9 Quality Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
3.10 Language Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
3.11 Entity Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
3.12 Range Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Contents xv
4 HTTP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
4.1 Message Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
4.2 Message Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
4.3 Message Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
4.4 Message Length. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
4.5 General Header Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
5 Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
5.1 Request-Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
5.2 The Resource Identified by a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
5.3 Request Header Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
6 Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
6.1 Status-Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
6.2 Response Header Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
7 Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
7.1 Entity Header Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
7.2 Entity Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

8 Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
8.1 Persistent Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
8.2 Message Transmission Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
9 Method Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
9.1 Safe and Idempotent Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
9.2 OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
9.3 GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
9.4 HEAD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
9.5 POST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
9.6 PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
9.7 DELETE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
9.8 TRACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
9.9 CONNECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
10 Status Code Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
10.1 Informational 1xx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
10.2 Successful 2xx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
10.3 Redirection 3xx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
10.4 Client Error 4xx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
10.5 Server Error 5xx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
11 Access Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
xvi Contents
12 Content Negotiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424
12.1 Server-Driven Negotiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
12.2 Agent-Driven Negotiation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
12.3 Transparent Negotiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
13 Caching in HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
13.2 Expiration Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
13.3 Validation Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
13.4 Response Cacheability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
13.5 Constructing Responses from Caches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

13.6 Caching Negotiated Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
13.7 Shared and Non-shared Caches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
13.8 Errors or Incomplete Response Cache Behavior . . . . . . . . . . . . . . . . . . . . . . . 450
13.9 Side Effects of GET and HEAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
13.10 Invalidation After Updates or Deletions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
13.11 Write-Through Mandatory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
13.12 Cache Replacement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
13.13 History Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
14 Header Field Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
14.1 Accept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
14.2 Accept-Charset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
14.3 Accept-Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
14.4 Accept-Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
14.5 Accept-Ranges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
14.6 Age . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
14.7 Allow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
14.8 Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
14.9 Cache-Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
14.10 Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
14.11 Content-Encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
14.12 Content-Language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
14.13 Content-Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
14.14 Content-Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
14.15 Content-MD5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
14.16 Content-Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
14.17 Content-Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
14.18 Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
14.19 ETag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
14.20 Expect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
14.21 Expires . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481

Contents xvii
14.22 From . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
14.23 Host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
14.24 If-Match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483
14.25 If-Modified-Since . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
14.26 If-None-Match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
14.27 If-Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
14.28 If-Unmodified-Since . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
14.29 Last-Modified . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
14.30 Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
14.31 Max-Forwards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
14.32 Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490
14.33 Proxy-Authenticate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
14.34 Proxy-Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
14.35 Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
14.36 Referer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
14.37 Retry-After . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
14.38 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
14.39 TE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
14.40 Trailer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
14.41 Transfer-Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
14.42 Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
14.43 User-Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
14.44 Vary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
14.45 Via . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
14.46 Warning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
14.47 WWW-Authenticate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
15 Security Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504
15.1 Personal Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
15.2 Attacks Based on File and Path Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507

15.3 DNS Spoofing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
15.4 Location Headers and Spoofing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
15.5 Content-Disposition Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
15.6 Authentication Credentials and Idle Clients . . . . . . . . . . . . . . . . . . . . . . . . . . 509
15.7 Proxies and Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
16 Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510
17 References. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512
18 Authors’ Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516
xviii Contents
19 Appendices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518
19.1 Internet Media Type message/http and application/http . . . . . . . . . . . . . . . . . 518
19.2 Internet Media Type multipart/byteranges. . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
19.3 Tolerant Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
19.4 Differences Between HTTP Entities and RFC 2045 Entities . . . . . . . . . . . . . 521
19.5 Additional Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
19.6 Compatibility with Previous Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
20 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
21 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Acknowledgment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
Contents xix
This page intentionally left blank
xxi
Foreword
Nick’s book is something that we’ve long been waiting for. The “Eagle Book,” which
came out in 1999, was a great book, but it focused primarily on
mod_perl. Thus
it was a rather different thing from this book.
And this book comes along at just the right time. With web applications needing
more and more scalability, we’re all looking for ways for our code to run faster, use

fewer resources, have tighter integration with the webserver, and just plain be more
robust.
It used to be sufficient to write Perl CGI programs to run even large websites, but
over the years most of us have moved to
mod_perl, PHP, Ruby on Rails, and other
development tools that allow us to build bigger, faster, cheaper. Those of us looking
for that next thing, wondering if it might be best to write our applications as an
Apache module, tend to get frustrated with the lack of decent documentation and
examples.
For the most part, when you ask on IRC for documentation of how to write an
Apache module, the answers include looking at the code of some existing module,
or looking at API documentation that was, at best, somewhat elderly and, for the
most part, intended for Apache 1.3.
When Nick told me that he was going to write this book, I made sure to sign up
for the first copy. I knew that Nick was the right person for the job because of his
prolific module authoring and his numerous helpful tutorials.
For those of us who learn best by example and experimentation, this book is ideal—
it provides many of the former and it encourages the latter. So make sure that you
have your favorite editor and compiler ready as you dive in, as you’ll encounter
xxii Foreword
example code almost right away and will want to try it out. And don’t be afraid to
experiment.
You’ve picked the right book. This is sure to become the de facto standard docu-
ment about how to write an Apache module.
—Rich Bowen
September 2006
xxiii
Preface
Introduction
The Apache Web Server (commonly known as “Apache”) is, by most measures, the

leading server on the Web today. For ten years it has been the unrivaled and unchal-
lenged market leader, with approximately 70 percent of all websites running Apache.
It is backed by a vibrant and active development community that operates under
the umbrella of the Apache Software Foundation (ASF), and it is supported by a
wide range of people and organizations, ranging from giants such as IBM down to
individual consultants.
The key characteristics of Apache are its openness and diversity. The source code is
completely open: Not only the current version, but also past versions and experi-
mental development versions can be downloaded by anyone from apache.org. The
development process is also open, with the exception of a few matters dealing with
project management. Apache’s diversity is a reflection of its user and developer com-
munities: It is equally at home in an ultra-high-volume site that receives tens of
thousands of hits per second, a complex and highly dynamic web application, a
bridge to a separate application server, or a simple homepage host. The inclusion of
developers from such diverse roles helps ensure that Apache continues to serve all
of these widely differing environments successfully.
Yet that doesn’t mean Apache follows a one-size-fits-all approach. Its highly modu-
lar architecture is built on a small core, which enables every user to tailor it to meet
his or her own specific needs. Apache serves equally well as a stand-alone webserver
or a component in some other system. Most importantly, it is a highly flexible and
extensible applications platform.
Audience and Readership
This book is intended for software developers who are working with the Apache
Web Server. It is the first such book published since March 1999, and the first and
(to date) only developer book that is relevant to Apache 2.
The book’s primary purpose is to serve as an in-depth textbook for module devel-
opers working with Apache. The narrative and examples deal with development in
C, and a working knowledge of C is assumed. However, the Apache architecture
and API are shared by major scripting environments such as
mod_perl and

mod_python, as well as C. With the exception of Chapter 3 (on the Apache
Portable Runtime), much of this book should also be relevant to developers work-
ing with scripting languages at any level more advanced than standard CGI.
The current Apache release—version 2.2—is the primary focus of this book.
Version 2.2.0 was released in December 2005 and, given Apache’s development
cycle, is likely to remain current for some time (the previous stable version 2.0 was
released in April 2002). This book is also very relevant to developers who are still
working with version 2.0 (the architecture and API are substantially the same across
all 2.x versions), and is expected to remain valid for the foreseeable future.
Organization and Scope
This book comprises twelve chapters and three appendixes.
The first chapter is a nontechnical overview that sets the scene and introduces the
social, cultural, and legal background of Apache. It is followed by an extended tech-
nical introduction and overview that is spread over the next three chapters. Chapter
2 is a technical overview of the Apache architecture and API. Chapter 3 introduces
the Apache Portable Runtime (APR), a semi-autonomous library that is used
throughout Apache and relieves the programmer of many of the traditional burdens
of C programming. Chapter 4 discusses general programming techniques appro-
priate to working with Apache, to ensure that your modules work well across dif-
ferent platforms and environments, remain secure, and don’t present difficulties to
systems administrators.
The central part of the book moves from the general to the specific. Chapters 5–8
present detailed discussions of various aspects of the core function of a webserver—
namely, processing HTTP requests. A number of real-life modules are developed in
these chapters. Chapter 5 starts with a “Hello World” example and takes you to the
xxiv Preface