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
How This Book Is Organized

Chapter 1, Server-Side Programming with Apache, talks about general issues of web application programming and shows how the web server APIs in general, and the Apache server API in specific, fit into the picture.

Chapter 2, A First Module, shows you the mechanics of getting your system ready for Perl and C module development. It describes how to lay out the directory structure, install required files, and configure the Apache web server for maximum flexibility. It then leads you through the steps of installing two simple modules, one written in Perl and the other in C.

Chapter 3, The Apache Module Architecture and API, paints a broad overview of the Apache API, taking you through the various phases of the HTTP transaction and the process of server startup, initialization, and cleanup. It shows how API modules fit into this process and how they can intervene to customize it.

Chapter 4, Content Handlers, is all about the request phase of the transaction, where modules create document content to be transmitted back to the browser. This chapter, and in fact the next three chapters, all use the Perl API to illustrate the concepts and to provide concrete working examples.

Chapter 5, Maintaining State, describes various techniques for maintaining state on a web server so that a user's interaction with the server becomes a continuous session rather than a series of unrelated transactions. The chapter starts with simple tricks and slowly grows in sophistication as we develop an Internet-wide tournament version of the classic "hangman" game.

Chapter 6, Authentication and Authorization, shows you how to intervene in Apache's authentication and authorization phases to create custom server access control systems of arbitrary complexity. Among other things, this chapter shows you how to implement an authentication system based on a relational database.

Chapter 7, Other Request Phases, is a grab bag of miscellaneous techniques, covering everything from controlling Apache's MIME-typing system to running proxy requests. Featured examples include a 10-line anonymizing proxy server and a system that blocks annoying banner ads.

Chapter 8, Customizing the Apache Configuration Process, shows how to define runtime configuration directives for Perl extension modules. It then turns the tables and shows you how Perl code can take over the configuration process and configure Apache dynamically at startup time.

Chapter 9, Perl API Reference Guide, is a reference guide to the Perl API, where we list every object, function, and method in exhaustive detail.

Chapter 10, C API Reference Guide, Part I, and Chapter 11, C API Reference Guide, Part II, show how to apply the lessons learned from the Perl API to the C-language API, and discuss the differences between Perl and C module development. These chapters also provide a definitive reference-style listing of all C API data structures and functions.

This book also contains the following appendixes:

Appendix A, Standard Noncore Modules

A reference guide to a number of useful Perl modules that come with the standard mod_ perl distribution but are not part of the official Apache API.

Appendix B, Building and Installing mod_perl

A complete guide to installing mod_perl, including all the various installation options, bells, and whistles.

Appendix C, Building Multifile C API Modules

Help with building C API modules that use the dynamic shared object (DSO) system.

Appendix D, Apache:: Modules Available on CPAN

A listing of third-party Perl API modules that can be found on the Comprehensive Perl Archive Network (CPAN).

Appendix E, Third-Party C Modules

A guide to the third-party C API modules that can be found at http://modules.apache.org/.

Appendix F, HTML::Embperl--Embedding Perl Code in HTML

An introduction to HTML::Embperl, a popular HTML template-based system that runs on top of mod_perl.

Conventions

The following typographic conventions are used in this book:

Italic

is used for filenames, directories, command names, module names, function calls, command-line switches, and Apache file directives. It is also used for email addresses and URLs.

Constant Width

is used for code examples. It is also used for constants and data structures.

Constant Width Bold

is used to mark user input in examples.

Constant Width Italic

is used to mark replaceables in examples.

The Companion Web Site to This Book

This book has a companion web site at http://www.modperl.com/. Here you can find all the source code for the code examples in this book--you don't have to blister your fingers typing them in. Many of the code examples are also running as demos there, letting you try them out as you read about them.

Here you'll also find announcements, errata, supplementary examples, downloadables, and links to other sources of information about Apache, Perl, and Apache module development.

Using FTP and CPAN

The Apache web server is available for download from the web. To obtain it via the web, go to the Apache home page, http://www.apache.org/, and follow the links to the most recent version.

mod_perl and all the various Perl modules and helper utilities mentioned in this book are available via anonymous FTP from any of the sites on the Comprehensive Perl Archive Network (CPAN). This is a list of several hundred public FTP sites that mirror each others' contents on a regular basis.

To find a CPAN site near you, point your web browser to Tom Christiansen's CPAN redirector services at http://www.perl.com/CPAN/. This will automatically take you to an FTP site in your geographic region. From there, you can either browse and download the files you want directly, or retrieve the full list of CPAN sites and select one on your own to use with the FTP client of your choice. Most of the modules you will be interested in obtaining will be located in the modules/by-module subdirectory.

Once you've downloaded the Perl module you want, you'll need to build and install it. Some modules are 100 percent Perl and can just be copied to the Perl library directory. Others contain some component written in C and need to be compiled. If you are using a Win32 system, you may want to look for a binary version of the module you're interested in. Most of the popular modules are available in precompiled binary form. Look in the CPAN ports/win32 directory for the version suitable for your Win32 Perl build. Otherwise, if you have a C compiler and the nmake program installed, you can build many modules from source, as described in this section.

Building a Perl module and installing it is simple and usually painless. The following shows the traditional way to download using an old-fashioned FTP command-line client:

% ftp ftp.cis.ufl.edu
Connected to ftp.cis.ufl.edu.
220 torrent.cise.ufl.edu FTP server ready.
Name (ftp.cis.ufl.edu:lstein): anonymous
331 Guest login ok, send your complete e-mail address as password.
Password: your email address here
230 Guest login ok, access restrictions apply.
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> cd /pub/perl/CPAN/modules/by-module
250 CWD command successful.
ftp> cd MD5
250 CWD command successful.
ftp> binary
200 Type set to I.
ftp> get Digest-MD5-2.00.tar.gz
local: Digest-MD5-2.00.tar.gz remote: Digest-MD5-2.00.tar.gz
200 PORT command successful.
150 Opening BINARY mode data connection for Digest-MD5-2.00.tar.gz (58105 bytes).
226 Transfer complete.
58105 bytes received in 11.1 secs (5.1 Kbytes/sec)
ftp> quit
221 Goodbye.

Perl modules are distributed as gzipped tar archives. You can unpack them like this:

% gunzip -c Digest-MD5-2.00.tar.gz  | tar xvf -
Digest-MD5-2.00/
Digest-MD5-2.00/typemap
Digest-MD5-2.00/MD2/
Digest-MD5-2.00/MD2/MD2.pm
...

Once unpacked, you'll enter the newly created directory and give the perl Makefile.PL, make, make test, and make install commands. Together these will build, test, and install the module (you may need to be root to perform the final step).

% cd Digest-MD5-2.00
% perl Makefile.PL
Testing alignment requirements for U32...
Checking if your kit is complete...
Looks good
Writing Makefile for Digest::MD2
Writing Makefile for Digest::MD5
% make
mkdir ./blib
mkdir ./blib/lib
mkdir ./blib/lib/Digest
...
% make test
make[1]: Entering directory `/home/lstein/Digest-MD5-2.00/MD2'
make[1]: Leaving directory `/home/lstein/Digest-MD5-2.00/MD2'
PERL_DL_NONLAZY=1 /usr/local/bin/perl -I./blib/arch -I./blib/lib...
t/digest............ok
t/files.............ok
t/md5-aaa...........ok
t/md5...............ok
t/rfc2202...........ok
t/sha1..............skipping test on this platform
All tests successful.
Files=6,  Tests=291,  1 secs ( 1.37 cusr  0.08 csys =  1.45 cpu)
% make install
make[1]: Entering directory `/home/lstein/Digest-MD5-2.00/MD2'
make[1]: Leaving directory `/home/lstein/Digest-MD5-2.00/MD2'
Installing /usr/local/lib/perl5/site_perl/i586-linux/./auto/Digest/MD5/MD5.so
Installing /usr/local/lib/perl5/site_perl/i586-linux/./auto/Digest/MD5/MD5.bs
...

A simpler way to do the same thing is to use Andreas Koenig's wonderful CPAN shell. With it you can download, build, and install Perl modules from a simple command-line shell. The following illustrates a typical session:

% perl -MCPAN -e shell
cpan shell -- CPAN exploration and modules installation (v1.40)
ReadLine support enabled

cpan> install MD5
Running make for GAAS/Digest-MD5-2.00.tar.gz
Fetching with LWP:
  ftp://ftp.cis.ufl.edu/pub/perl/CPAN/authors/id/GAAS/Digest-MD5-2.00.tar.gz
CPAN: MD5 loaded ok
Fetching with LWP:
  ftp://ftp.cis.ufl.edu/pub/perl/CPAN/authors/id/GAAS/CHECKSUMS
Checksum for /home/lstein/.cpan/sources/authors/id/GAAS/Digest-MD5-2.00.tar.g
z ok
Digest-MD5-2.00/
Digest-MD5-2.00/typemap
Digest-MD5-2.00/MD2/
Digest-MD5-2.00/MD2/MD2.pm
...
Installing /usr/local/lib/perl5/site_perl/i586-linux/./auto/Digest/MD5/MD5.so
Installing /usr/local/lib/perl5/site_perl/i586-linux/./auto/Digest/MD5/MD5.bs
Installing /usr/local/lib/perl5/site_perl/i586-linux/./auto/MD5/MD5.so
Installing /usr/local/lib/perl5/man/man3/./MD5.3
...
Writing /usr/local/lib/perl5/site_perl/i586-linux/auto/MD5/.packlist
Appending installation info to /usr/local/lib/perl5/i586-linux/5.00404/perllo
cal.pod

cpan> exit

Comments and Questions

Please address comments and questions concerning this book to the publisher:

O'Reilly & Associates, Inc.
101 Morris Street
Sebastopol, CA 95472
800-998-9938 (in the U.S. or Canada)
707-829-0515 (international or local)
707-829-0104 (fax)

You can also send us messages electronically. To be put on our mailing list or to request a catalog, send email to:

info@oreilly.com

To ask technical questions or comment on the book, send email to:

bookquestions@oreilly.com