Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Preface

In this section...

Introduction 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

Introduction

In This 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

One of the minor miracles of the World Wide Web is that it makes client/server network programming easy. With the Common Gateway Interface (CGI) anyone can become a network programmer, creating dynamic web pages, frontends for databases, and even complex intranet applications with ease. If you're like many web programmers, you started out by writing CGI scripts in Perl. With its powerful text-processing facilities, forgiving syntax, and tool-oriented design, Perl lends itself to the small programs that CGI was designed for.

Unfortunately the Perl/CGI love affair doesn't last forever. As your scripts get larger and your server more heavily loaded, you inevitably run into the performance wall. A 1,000-line Perl CGI script that runs fine on a lightly loaded web site becomes unacceptably slow when it increases to 10,000 lines and the hit rate triples. You may have tried switching to a different programming language and been disappointed. Because the main bottleneck in the CGI protocol is the need to relaunch the script every time it's requested, even compiled C won't give you the performance boost you expect.

If your application needs go beyond simple dynamic pages, you may have run into the limitations of the CGI protocol itself. Many interesting things go on in the heart of a web server--things like the smart remapping of URLs, access control and authentication, or the assignment of MIME types to different documents. The CGI protocol doesn't give you access to these internals. You can neither find out what's going on nor intervene in any meaningful way.

To go beyond simple CGI scripting, you must use an alternative protocol that doesn't rely on launching and relaunching an external program each time a script runs. Alternatives include NSAPI on Netscape servers, ISAPI on Windows servers, Java servlets, server-side includes, Active Server Pages (ASP), FastCGI, Dynamic HTML, ActiveX, JavaScript, and Java applets.

Sadly, choosing among these technologies is a no-win situation. Some choices lock you into a server platform for life. Others limit the browsers you can support. Many offer proprietary solutions that aren't available in other vendors' products. Nearly all of them require you to throw out your existing investment in Perl CGI scripts and reimplement everything from scratch.

The Apache server offers you a way out of this trap. It is a freely distributed, full-featured web server that runs on Unix and Windows NT systems. Derived from the popular NCSA httpd server, Apache dominates the web, currently accounting for more than half of the servers reachable from the Internet. Like its commercial cousins from Microsoft and Netscape, Apache supports an application programming interface (API), allowing you to extend the server with extension modules of your own design. Modules can behave like CGI scripts, creating interactive pages on the fly, or they can make much more fundamental changes in the operation of the server, such as implementing a single sign-on security system or logging web accesses to a relational database. Regardless of whether they're simple or complex, Apache modules provide performance many times greater than the fastest conventional CGI scripts.

The best thing about Apache modules, however, is the existence of mod_perl. mod_perl is a fully functional Perl interpreter embedded directly in Apache. With mod_perl you can take your existing Perl CGI scripts and plug them in, usually without making any source code changes whatsoever. The scripts will run exactly as before but many times faster (nearly as fast as fetching static HTML pages in many cases). Better yet, mod_perl offers a Perl interface to the Apache API, allowing you full access to Apache internals. Instead of writing Perl scripts, you can write Perl extension modules that control every aspect of the Apache server.

Move your existing Perl scripts over to mod_perl to get the immediate performance boost. As you need to, add new features to your scripts that take advantage of the Apache API (or don't, if you wish to maintain portability with other servers). When you absolutely need to drag out the last little bit of performance, you can bite the bullet and rewrite your Perl modules as C modules. Surprisingly enough, the performance of Apache/Perl is so good that you won't need to do this as often as you expect.

This book will show you how to write Apache modules. Because you can get so much done with Perl modules, the focus of the book is on the Apache API through the eyes of the Perl programmer. We cover techniques for creating dynamic HTML documents, interfacing to databases, maintaining state across multiple user sessions, implementing access control and authentication schemes, supporting advanced HTTP methods such as server publish, and implementing custom logging systems. If you are a C programmer, don't despair. Two chapters on writing C-language modules point out the differences between the Perl and C APIs and lead you through the process of writing, compiling, and installing C-language modules. This book includes complete reference guides to both the Perl and C APIs and multiple appendixes covering the more esoteric aspects of writing Apache modules.

We think you'll find developing Apache modules to be an eye-opening experience. With any luck, you won't have to worry about switching web application development environments for a long time to come.

What You Need to Know to Get the Most out of This Book

This book was designed for application developers who already have some experience with web programming. We assume that you understand CGI scripting, know how to produce HTML pages dynamically, and can create fill-out forms and process their contents. We also assume that you know the basics of web server administration--if not with the Apache server itself, then with another Unix or Microsoft Windows-based web server.

A knowledge of the Perl programming language is definitely required! We use the Perl version of the Apache API to illustrate the central concepts of module design and implementation, and most of our example code is written in Perl as well. We chose to do it this way because we think there are more people who are comfortable developing web applications in Perl than in C or C++. You don't have to be a Perl guru to read this book, but there will be places where you'll find the going tough if you don't understand Perl syntax. We make particularly heavy use of the current features of Perl (Version 5.004 and higher), particularly in regard to Perl's object-oriented syntax. If you know Perl Version 4 but haven't gotten around to reading about the Version 5 features, now's the time to start learning about hash references, blessed objects, and method calls.

If you're an experienced C programmer, you can probably get what you need from the Perl chapters without necessarily understanding every line of the example code. Be forewarned, however, that our discussion of the C-language API tends toward terseness since it builds on the framework established by earlier chapters on the Perl API.

Apache and mod_perl both run on Unix machines and Windows NT systems, and we have endeavored to give equal time to both groups of programmers. However, both authors are primarily Unix developers, and if our bias leaks through here and there, please try to forgive us.

We've used the following books for background reading and reference information. We hope they will be useful to you as well:

Web site administration, maintenance, and security

How to Set Up and Maintain a Web Site: The Guide for Information Providers, 2nd ed., by Lincoln Stein (Addison-Wesley Longman, 1997).

Web Security: A Step-by-Step Reference Guide, by Lincoln Stein (Addison-Wesley Longman, 1998). Web Security and Electronic Commerce, by Simpson Garfinkle with Gene Spafford (O'Reilly & Associates, 1997).

The Apache web server

Apache: The Definitive Guide, by Ben Laurie and Peter Laurie (O'Reilly & Associates, 1997).

Apache Server for Dummies, by Ken Coar (IDE, 1998).

CGI scripting

The Official Guide to CGI.pm, by Lincoln Stein (John Wiley & Sons, 1998).

CGI/Perl Cookbook, by Craig Patchett and Matthew Wright (John Wiley & Sons, 1998).

The HTTP protocol

The HTTP/1.0 and HTTP/1.1 protocols page at the WWW Consortium site: http:// www.w3.org/Protocols.

Web client programming

Web Client Programming with Perl, by Clinton Wong (O'Reilly & Associates, 1997).

Perl programming

Programming Perl, 2nd ed., by Tom Christiansen, Larry Wall, and Randal Schwartz (O'Reilly & Associates, 1996).

Perl Cookbook, by Tom Christiansen and Nathan Torkington (O'Reilly & Associates, 1998).

Advanced Perl Programming, by Srinam Srinivasan (O'Reilly & Associates, 1997).

Effective Perl Programming, by Joseph Hall (Addison-Wesley Longman, 1998).

C programming

The C Programming Language, 2nd ed., by Brian Kernighan and Dennis Ritchie (Prentice- Hall, 1988).

C: A Reference Manual, by Samuel Harbison and Guy Steele (Prentice-Hall, 1987).

HTML

HTML: The Definitive Guide, 3rd ed., by Chuck Musciano and Bill Kennedy (O'Reilly & Associates, 1998).

HTML 3, by Dave Raggett, Jenny Lam, and Ian Alexander (Addison-Wesley Longman, 1996).