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.

Chapter 2 - A First Module
Installing mod_perl

In this section...

Introduction The Installation Process Win32 Installation The mod_perl Mailing List

Introduction

In order to use the Perl API, you'll need to download and install mod_perl if you haven't done so already. This section will describe the simplest way to do this. If you've already installed mod_perl you'll want to skip this section or jump directly to Appendix B, Building and Installing mod_perl, where we give you the lowdown on mod_perl's advanced installation options.

If you are a Win32 user, you can skip to the section "Win32 Installation" and download the precompiled ApacheModulePerl.dll loadable module. We'll show you how to activate ApacheModulePerl.dll at the end of the section.

The Installation Process

mod_perl is part of the CPAN archive. FTP to a CPAN site close to you and enter the directory modules/by-module/Apache/. Download the file mod_perl-X.XX.tar.gz, where X.XX is the highest version number you find.

It is easiest to build mod_perl when it is located at the same level as the Apache source tree. Change your working directory to the source directory of the server root, and unpack the mod_perl distribution using the gunzip and tar tools:⁴

  % cd ~www/build
 % gunzip -c mod_perl-X.XX.tar.gz | tar xvf -
 mod_perl-/t/
 mod_perl-/t/docs/
 mod_perl-/t/docs/env.iphtml
 mod_perl-/t/docs/content.shtml
 mod_perl-/t/docs/error.txt
  ....
 % cd mod_perl-X.XX

Now, peruse the README and INSTALL files located in the mod_perl directory. These files contain late-breaking news, installation notes, and other information.

The next step is to configure, build, and install mod_perl. Several things happen during this process. First, an installation script named Makefile.PL generates a top-level Makefile and runs Apache's configure script to add mod_perl to the list of C modules compiled into the server. After this, you run make to build the mod_perl object file and link it into a new version of the Apache server executable. The final steps of the install process are to test this new executable and, if it checks out, to move mod_perl's support files and documentation into the Perl library directory.

If you have other third-party modules to add to Apache, such as PHP, you can add them during the mod_perl build process by providing arguments to the installation script that will be passed through to Apache's configure. Alternatively, you can separate the mod_perl build from the Apache build and run configure yourself.

The outline of the whole process is as follows:

 perl Makefile.PL                 # run installation script
make                                    # make httpd executable
make test                               # run tests (optional)
make install                            # install mod_perl

The perl Makefile.PL line is supplemented by a series of tag=value pairs that control a bewildering array of options. The full list of options is given in Appendix B. Most options are concerned with activating handlers for various phases of the HTTP transaction. For example, to enable the handlers for the authentication and log phases (which we explain in more detail later), you would configure mod_perl with this command:

perl Makefile.PL PERL_LOG=1 PERL_AUTHEN=1

You'll probably want to enable all the handlers in order to get access to the full Apache API. The easiest way to do this is by issuing this command:

perl Makefile.PL EVERYTHING=1 APACHE_PREFIX=/usr/local/apache

EVERYTHING=1 enables all the handlers and activates a variety of other neat features, including server-side includes written in Perl and support for <Perl> sections in the Apache configuration files. Providing an APACHE_PREFIX option with the location of the server root allows the install script to automatically copy the new version of the Apache server and its support files into the server root. If you don't provide this option, you can still copy the files manually after they're built. More details on these options can be found in the mod_perl manual pages and in Appendix B.

Other configuration options are not involved in building mod_perl itself, but are passed through to Apache's configure script to control other aspects of Apache's configuration. The most frequently used of these is ADD_MODULE, which accepts a comma-delimited list of additional modules to compile into Apache. Use this if there are optional modules such as the mod_status and mod_proxy that you wish to build Apache with.

When run, Makefile.PL will search the immediate vicinity for the Apache source tree. When it finds it, it will print the path and ask you for confirmation. If the search fails, Makefile.PL will prompt you to type in the path. You should type in the full path to the Apache src directory. Next you'll be asked whether httpd should be built during the make. You should answer "y" to this question. At this point, Makefile.PL will run Apache's own configure script and you'll see a series of messages from configure.

After running configure, Makefile.PL will display a list of the options that are enabled. Then it checks for the presence of the LWP and CGI.pm packages and warns you if one or both are absent or outdated. Neither package is essential to successfully install mod_perl, but LWP is required to run the regression tests. If you wish, you can install mod_perl without running the tests. If at some later date you wish to run the regression tests, just install LWP and run Makefile.PL again.

Here's an example configuration session:

% perl Makefile.PL EVERYTHING=1 APACHE_PREFIX=/usr/local/apache
 ReadLine support enabled
 Configure mod_perl with ../apache_1.3.3/src ? [y] y
 Shall I build httpd in ../apache_1.3.3/src for you? [y] y
 cp src/modules/perl/perl_PL.h ../apache_1.3.3/src/modules/perl/perl_PL.h
  ... many similar lines deleted ...
 Will run tests as User: 'johnd' Group: 'users'
 Configuring for Apache, Version 1.3.3
  + activated perl module (modules/perl/libperl.a)
 Creating Makefile
 Creating Configuration.apaci in src
       + id: mod_perl/1.16
       + id: Perl/5.00404 (linux) [perl]
 ... many similar lines deleted ...

  PerlDispatchHandler.........enabled
  PerlChildInitHandler........enabled
  PerlChildExitHandler........enabled
  PerlPostReadRequestHandler..enabled
  PerlTransHandler............enabled
  ... many similar lines deleted ...

  Writing Makefile for Apache
  Writing Makefile for Apache::Connection
  Writing Makefile for Apache::Constants
  Writing Makefile for Apache::File
  Writing Makefile for Apache::Log
  Writing Makefile for Apache::ModuleConfig
  Writing Makefile for Apache::Server
  Writing Makefile for Apache::Symbol
  Writing Makefile for Apache::Tie
  Writing Makefile for Apache::URI
  Writing Makefile for Apache::Util
  Writing Makefile for mod_perl

If something goes wrong during configuration, there should be a diagnostic warning that will point to the problem (for example, "no Apache source directory found"). Correct the problem and try again. If you need to pass a long series of configuration options, you will probably find it convenient to turn the configuration command into a short shell script along these lines:

 #!/bin/sh

 # mod_perl configuration 9/28/98

 perl Makefile.PL EVERYTHING=1 \

    ADD_MODULE=unique_id,status,proxy,info \

    APACHE_PREFIX=/usr/local/apache

This makes it easy to edit the configuration and run the command again. Plus, you'll have a record of the configuration you used the next time you upgrade Apache or mod_perl.

The next step is to run make. A new Apache server with an integrated mod_perl will now be built in front of your eyes. At the end of the process you'll find a brand-new httpd in the Apache source tree. It will look just like the old one, except significantly larger (fourfold increases in size are not uncommon). This is because the Perl interpreter has just been made part of httpd. It's unlikely that you'll encounter any problems during the make if you were previously successful in compiling both Apache and Perl, but if the make process does abort because of a fatal error, you'll have to do some detective work to determine where things went wrong. It helps to redirect the messages from the build process into a file for later perusal:

% make |& tee make.out

You can now run the optional tests. This step is recommended. During the tests the newly built server will be launched and a series of scripts will barrage it with requests to determine whether it produces the expected answers. Because the server listens to a nonstandard port during the tests, you can run the tests on the same machine that already hosts a web server. You do not need to be the super-user (or Administrator) in order to run the tests; however, you do need to have the LWP library installed. Otherwise, the tests will abort at an early stage.

To run the tests, run make test from within the mod_perl directory:

% make test
cp t/conf/mod_perl_srm.conf t/conf/srm.conf
../apache-1.3/src/httpd -f `pwd`/t/conf/httpd.conf -X -d `pwd`/t &
httpd listening on port 8529
will write error_log to: t/logs/error_log
letting apache warm up...done
/opt/perl5/bin/perl t/TEST 0
modules/actions.....ok
modules/cgi.........ok
modules/constants...ok
modules/embperl.....ok
modules/eperl.......ok
... many similar lines deleted ...

All tests successful.
Files=35,  Tests=350, 35 secs (26.13 cusr  2.56 csys = 28.69 cpu)
kill `cat t/logs/httpd.pid`
rm -f t/logs/httpd.pid
rm -f t/logs/error_log

Don't worry about any tests that are skipped. This just indicates that you haven't installed one of the optional mod_perl features. You can always install the feature and rerun the tests later. Any messages about failed tests, however, are cause for concern. If you see such a message, you should rerun the tests with the verbose flag (make test TEST_VERBOSE=1). You can try to track down the problem yourself, or post the results to the mod_perl mailing list (which we'll discuss presently).

Provided that all goes well, you can now finish the installation. You may need to have super-user or Administrator privileges in order to do this. Run make install to move mod_perl's support files and documentation to the main Perl library directory. You will see a long series of copy commands. If you specified the APACHE_PREFIX option, then make install will also install the Apache side of things, including httpd, its configuration files, document, and log trees. Otherwise, change to the Apache source directory and copy the new httpd by hand to your server root directory. Make sure to keep a copy of the old httpd binary around, just in case.

Win32 Installation

For Windows users, download the ApacheModulePerl binary distribution from CPAN, in the subdirectory authors/Jeffrey_Baker/. The Win32 distribution file uses a very long name, following the CPAN conventions for binary distribution file names.⁵ Make sure you download the one with the highest version number, and unpack it with your favorite ZIP file extractor.

Now copy the contents of the lib subdirectory into your Perl library tree, usually C:\perl5\lib (be careful to copy the contents of lib, not the directory itself, or you run the risk of clobbering your Perl library tree!). Next, move the file Apache-Mod-ule-Perl.dll to the Apache loadable modules directory, usually C:\Apache\modules. Open httpd.conf with your favorite text editor and add the following line:

LoadModule perl_module modules/ApacheModulePerl.dll

Kill and restart the server if it's already running. mod_perl should now be installed. Should you wish to build mod_perl from source code, consult the INSTALL.win32 file located at the top of the mod_perl distribution directory.