By Stas Bekman, Eric Cholet
Book Price: $49.95 USD
£35.50 GBP
PDF Price: $34.99

Cover | Table of Contents | Colophon

Table of Contents

Chapter 1: Introducing CGI and mod_perl

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This chapter provides the foundations on which the rest of the book builds. In this chapter, we give you:

• A history of CGI and the HTTP protocol.
• An explanation of the Apache 1.3 Unix model, which is crucial to understanding how mod_perl 1.0 works.
• An overall picture of mod_perl 1.0 and its development.
• An overview of the difference between the Apache C API, the Apache Perl API (i.e., the mod_perl API), and CGI compatibility. We will also introduce the Apache::Registry and Apache::PerlRun modules.
• An introduction to the mod_perl API and handlers.

When the World Wide Web was born, there was only one web server and one web client. The httpd web server was developed by the Centre d'Etudes et de Recherche Nucléaires (CERN) in Geneva, Switzerland. httpd has since become the generic name of the binary executable of many web servers. When CERN stopped funding the development of httpd, it was taken over by the Software Development Group of the National Center for Supercomputing Applications (NCSA). The NCSA also produced Mosaic, the first web browser, whose developers later went on to write the Netscape client.

Mosaic could fetch and view static documents and images served by the httpd server. This provided a far better means of disseminating information to large numbers of people than sending each person an email. However, the glut of online resources soon made search engines necessary, which meant that users needed to be able to submit data (such as a search string) and servers needed to process that data and return appropriate content.

Search engines were first implemented by extending the web server, modifying its source code directly. Rewriting the source was not very practical, however, so the NCSA developed the Common Gateway Interface (CGI) specification. CGI became a standard for interfacing external applications with web servers and other information servers and generating dynamic information.

A CGI program can be written in virtually any language that can read from

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

A Brief History of CGI

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

When the World Wide Web was born, there was only one web server and one web client. The httpd web server was developed by the Centre d'Etudes et de Recherche Nucléaires (CERN) in Geneva, Switzerland. httpd has since become the generic name of the binary executable of many web servers. When CERN stopped funding the development of httpd, it was taken over by the Software Development Group of the National Center for Supercomputing Applications (NCSA). The NCSA also produced Mosaic, the first web browser, whose developers later went on to write the Netscape client.

Mosaic could fetch and view static documents and images served by the httpd server. This provided a far better means of disseminating information to large numbers of people than sending each person an email. However, the glut of online resources soon made search engines necessary, which meant that users needed to be able to submit data (such as a search string) and servers needed to process that data and return appropriate content.

Search engines were first implemented by extending the web server, modifying its source code directly. Rewriting the source was not very practical, however, so the NCSA developed the Common Gateway Interface (CGI) specification. CGI became a standard for interfacing external applications with web servers and other information servers and generating dynamic information.

A CGI program can be written in virtually any language that can read from STDIN and write to STDOUT, regardless of whether it is interpreted (e.g., the Unix shell), compiled (e.g., C or C++), or a combination of both (e.g., Perl). The first CGI programs were written in C and needed to be compiled into binary executables. For this reason, the directory from which the compiled CGI programs were executed was named cgi-bin, and the source files directory was named cgi-src. Nowadays most servers come with a preconfigured directory for CGI programs called, as you have probably guessed, cgi-bin.

Interaction between the browser and the server is governed by the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

The Apache 1.3 Server Model

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Now that you know how CGI works, let's talk about how Apache implements mod_cgi. This is important because it will help you understand the limitations of mod_cgi and why mod_perl is such a big improvement. This discussion will also build a foundation for the rest of the performance chapters of this book.

Apache 1.3 on all Unix flavors uses the forking model. When you start the server, a single process, called the parent process , is started. Its main responsibility is starting and killing child processes as needed. Various Apache configuration directives let you control how many child processes are spawned initially, the number of spare idle processes, and the maximum number of processes the parent process is allowed to fork.

Each child process has its own lifespan, which is controlled by the configuration directive MaxRequestsPerChild . This directive specifies the number of requests that should be served by the child before it is instructed to step down and is replaced by another process. Figure 1-3 illustrates.

Figure 1-3: The Apache 1.3 server lifecycle

When a client initiates a request, the parent process checks whether there is an idle child process and, if so, tells it to handle the request. If there are no idle processes, the parent checks whether it is allowed to fork more processes. If it is, a new process is forked to handle the request. Otherwise, the incoming request is queued until a child process becomes available to handle it.

The maximum number of queued requests is configurable by the ListenBacklog configuration directive. When this number is reached, a client issuing a new request will receive an error response informing it that the server is unreachable.

This is how requests for static objects, such as HTML documents and images, are processed. When a CGI request is received, an additional step is performed: mod_cgi in the child Apache process forks a new process to execute the CGI script. When the script has completed processing the request, the forked process exits.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

The Development of mod_perl 1.0

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Of the various attempts to improve on mod_cgi's shortcomings, mod_perl has proven to be one of the better solutions and has been widely adopted by CGI developers. Doug MacEachern fathered the core code of this Apache module and licensed it under the Apache Software License, which is a certified open source license.

mod_perl does away with mod_cgi's forking by embedding the Perl interpreter into Apache's child processes, thus avoiding the forking mod_cgi needed to run Perl programs. In this new model, the child process doesn't exit when it has processed a request. The Perl interpreter is loaded only once, when the process is started. Since the interpreter is persistent throughout the process's lifetime, all code is loaded and compiled only once, the first time it is needed. All subsequent requests run much faster, because everything is already loaded and compiled. Response processing is reduced to simply running the code, which improves response times by a factor of 10-100, depending on the code being executed.

But Doug's real accomplishment was adding a mod_perl API to the Apache core. This made it possible to write complete Apache modules in Perl, a feat that used to require coding in C. From then on, mod_perl enabled the programmer to handle all phases of request processing in Perl.

The mod_perl API also allows complete server configuration in Perl. This has made the lives of many server administrators much easier, as they now benefit from dynamically generating the configuration and are freed from hunting for bugs in huge configuration files full of similar directives for virtual hosts and the like.

To provide backward compatibility for plain CGI scripts that used to be run under mod_cgi, while still benefiting from a preloaded Perl interpreter and modules, a few special handlers were written, each allowing a different level of proximity to pure mod_perl functionality. Some take full advantage of mod_perl, while others do not.

mod_perl embeds a copy of the Perl interpreter into the Apache httpd executable, providing complete access to Perl functionality within Apache. This enables a set of mod_perl-specific configuration directives, all of which start with the string

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Apache 1.3 Request Processing Phases

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

To understand mod_perl, you should understand how request processing works within Apache. When Apache receives a request, it processes it in 11 phases. For every phase, a standard default handler is supplied by Apache. You can also write your own Perl handlers for each phase; they will override or extend the default behavior. The 11 phases (illustrated in Figure 1-4) are:

Figure 1-4: Apache 1.3 request processing phases

Post-read-request

This phase occurs when the server has read all the incoming request's data and parsed the HTTP header. Usually, this stage is used to perform something that should be done once per request, as early as possible. Modules' authors usually use this phase to initialize per-request data to be used in subsequent phases.

URI translation

In this phase, the requested URI is translated to the name of a physical file or the name of a virtual document that will be created on the fly. Apache performs the translation based on configuration directives such as ScriptAlias. This translation can be completely modified by modules such as mod_rewrite, which register themselves with Apache to be invoked in this phase of the request processing.

Header parsing

During this phase, you can examine and modify the request headers and take a special action if needed—e.g., blocking unwanted agents as early as possible.

Access control

This phase allows the server owner to restrict access to specific resources based on various rules, such as the client's IP address or the day of week.

Authentication

Sometimes you want to make sure that a user really is who he claims to be. To verify his identity, challenge him with a question that only he can answer. Generally, the question is a login name and password, but it can be any other challenge that allows you to distinguish between users.

Authorization

The service might have various restricted areas, and you might want to allow the user to access some of these areas. Once a user has passed the authentication process, it is easy to check whether a specific location can be accessed by that user.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

References

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

• The CGI specification: http://hoohoo.ncsa.uiuc.edu/cgi/
• The HTTP/1.1 standard: http://www.w3.org/Protocols/rfc2616/rfc2616.html
• Various information about CGI at the W3C site: http://www.w3.org/CGI/
• MIME Media Types: http://www.ietf.org/rfc/rfc2046.txt
• The Apache Modules Registry: http://modules.apache.org/
• Writing Apache Modules with Perl and C, by Lincoln Stein and Doug MacEachern (O'Reilly); selected chapters available online at http://www.modperl.com/
• mod_perl Developer's Cookbook, by Geoffrey Young, Paul Lindner, and Randy Kobes (Sams Publishing); selected chapters available online at http://www.modperlcookbook.org/.
• CGI Programming with Perl, by Scott Guelich, Shishir Gundavaram, Gunther Birznieks (O'Reilly)

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Chapter 2: Getting Started Fast

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

This chapter is about getting started with mod_perl, for the very impatient. If all you want is to run your existing CGI scripts in a mod_perl-enabled environment, we'll try to make this as easy for you as possible. Of course, we hope that you'll read the rest of the book too. But first, we want to show you how simple it is to harness the power of mod_perl.

On a decent machine, it should take half an hour or less to compile and configure a mod_perl-based Apache server and get it running. Although there are binary distributions of mod_perl-enabled Apache servers available for various platforms, we recommend that you always build mod_perl from source. It's simple to do (provided you have all the proper tools on your machine), and building from source circumvents possible problems with binary distributions, such as those reported for the RPM packages built for Red Hat Linux.

The mod_perl installation that follows has been tested on many mainstream Unix and Linux platforms. Unless you're using a very nonstandard system, you should have no problems when building the basic mod_perl server.

For Windows users, the simplest solution is to use the binary package available from http://perl.apache.org/download/binaries.html. Windows users may skip to Section 2.4.

Before we continue, however, we have one important bit of advice: while you're learning mod_perl, be sure that you experiment on a private machine and not on a production server.

You can install mod_perl in three easy steps: obtain the source files required to build mod_perl, build mod_perl, and install it.

Building mod_perl from source requires a machine with basic development tools. In particular, you will need an ANSI-compliant C compiler (such as gcc) and the make utility. All standard Unix-like distributions include these tools. If a required tool is not already installed, you can install it with the package manager that is provided with the system (rpm, apt, yast, etc.).

A recent version of Perl (5.004 or higher) is also required. Perl is available as an installable package, although most Unix-like distributions will have Perl installed by default. To check that the tools are available and to learn about their version numbers, try:

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Installing mod_perl 1.0 in Three Steps

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

You can install mod_perl in three easy steps: obtain the source files required to build mod_perl, build mod_perl, and install it.

Building mod_perl from source requires a machine with basic development tools. In particular, you will need an ANSI-compliant C compiler (such as gcc) and the make utility. All standard Unix-like distributions include these tools. If a required tool is not already installed, you can install it with the package manager that is provided with the system (rpm, apt, yast, etc.).

A recent version of Perl (5.004 or higher) is also required. Perl is available as an installable package, although most Unix-like distributions will have Perl installed by default. To check that the tools are available and to learn about their version numbers, try:

panic% make -v
panic% gcc -v
panic% perl -v

If any of these responds with Command not found, the utility will need to be installed.

Once all the tools are in place, the installation can begin. Experienced Unix users will need no explanation of the commands that follow and can simply type them into a terminal window.

Get the source code distrubutions of Apache and mod_perl using your favorite web browser or a command-line client such as wget or lwp-download. These two distributions are available from http://www.apache.org/dist/httpd/ and http://perl.apache.org/dist/, respectively.

The two packages are named apache_1.3.xx.tar.gz and mod_perl-1.xx.tar.gz, where 1.3.xx and 1.xx should be replaced with the real version numbers of Apache and mod_perl, respectively. Although 2.0 development versions of Apache and mod_perl are available, this book covers the mod_perl 1.0 and Apache 1.3 generation, which were the stable versions when this book was written. See Chapter 24 and Chapter 25 for more information on the Apache 2.0 and mod_perl 2.0 generation.

Move the downloaded packages into a directory of your choice (for example, /home/stas/src/), proceed with the following steps, and mod_perl will be installed:

panic% cd /home/stas/src
panic% tar -zvxf apache_1.3.xx.tar.gz
panic% tar -zvxf mod_perl-1.xx.tar.gz
panic% cd mod_perl-1.xx
panic% perl Makefile.PL APACHE_SRC=../apache_1.3.xx/src \
    APACHE_PREFIX=/home/httpd DO_HTTPD=1 USE_APACI=1 EVERYTHING=1
panic% make && make test
panic% su
panic# make install

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Installing mod_perl on Unix Platforms

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Now let's go over the installation again, this time with each step explained in detail and with some troubleshooting advice. If the build worked and you are in a hurry to boot your new httpd, you may skip to Section 2.4.

Before installing Apache and mod_perl, you usually have to become root so that the files can be installed in a protected area. However, users without root access can still install all files under their home directories by building Apache in an unprivileged location; you need root access only to install it. We will talk about the nuances of this approach in Chapter 3.

The first step is to obtain the source code distributions of Apache and mod_perl. These distributions can be retrieved from http://www.apache.org/dist/httpd/ and http://perl.apache.org/dist/ and are also available from mirror sites. Even if you have the Apache server running on your machine, you'll need its source distribution to rebuild it from scratch with mod_perl.

The source distributions of Apache and mod_perl should be downloaded into a directory of your choice. For the sake of consistency, we assume throughout the book that all builds are being done in the /home/stas/src directory. Just remember to substitute /home/stas/src in the examples with the actual path being used.

The next step is to move to the directory containing the source archives:

panic% cd /home/stas/src

Uncompress and untar both sources. GNU tar allows this using a single command per file:

panic% tar -zvxf apache_1.3.xx.tar.gz
panic% tar -zvxf mod_perl-1.xx.tar.gz

For non-GNU tars, you may need to do this with two steps (which you can combine via a pipe):

panic% gzip -dc apache_1.3.xx.tar.gz | tar -xvf -
panic% gzip -dc mod_perl-1.xx.tar.gz | tar -xvf -

Linux distributions supply tar and gzip and install them by default. If your machine doesn't have these utilities already installed, you can get tar and gzip from http://www.gnu.org/, among other sources. The GNU versions are available for every platform that Apache supports.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Configuring and Starting the mod_perl Server

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Once you have mod_perl installed, you need to configure the server and test it.

The first thing to do is ensure that Apache was built correctly and that it can serve plain HTML files. This helps to minimize the number of possible problem areas: once you have confirmed that Apache can serve plain HTML files, you know that any problems with mod_perl are related to mod_perl itself.

Apache should be configured just as you would configure it without mod_perl. Use the defaults as suggested, customizing only when necessary. Values that will probably need to be customized are ServerName, Port, User, Group, ServerAdmin, DocumentRoot, and a few others. There are helpful hints preceding each directive in the configuration files themselves, with further information in Apache's documentation. Follow the advice in the files and documentation if in doubt.

When the configuration file has been edited, start the server. One of the ways to start and stop the server is to use the apachectl utility. To start the server with apachectl, type:

panic# /usr/local/apache/bin/apachectl start

To stop the server, type:

panic# /usr/local/apache/bin/apachectl stop

Note that if the server will listen on port 80 or another privileged port, the user executing apachectl must be root.

After the server has started, check in the error_log file (/usr/local/apache/logs/error_log, by default) to see if the server has indeed started. Do not rely on the apachectl status reports. The error_log should contain something like the following:

[Thu Jun 22 17:14:07 2000] [notice] Apache/1.3.12 (Unix) 
mod_perl/1.24 configured -- resuming normal operations

Now point your browser to http://localhost/ or http://example.com/, as configured with the ServerName directive. If the Port directive has been set with a value other than 80, add this port number to the end of the server name. For example, if the port is 8080, test the server with http://localhost:8080/ or http://example.com:8080/. The "It Worked!" page, which is an index.html file that is installed automatically when running

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Installing mod_perl for Windows

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Apache runs on many flavors of Unix and Unix-like operating systems. Version 1.3 introduced a port to the Windows family of operating systems, often named Win32 after the name of the common API. Because of the many differences between Unix and Windows, the Win32 port of Apache is still branded as beta quality—it hasn't yet reached the stability and performance levels of the native Unix counterpart.

Another hindrance to using mod_perl on Windows is that current versions of Perl are not thread-safe on Win32. As a consequence, mod_perl calls to the embedded Perl interpreter must be serialized (i.e., executed one at a time). For these reasons, we recommend that mod_perl on Windows be used only for testing purposes, not in production.

Building mod_perl from source on Windows is a bit of a challenge. Development tools such as a C compiler are not bundled with the operating system, and most users expect a point-and-click installation, as with most Windows software. Additionally, all software packages need to be built with the same compiler and compile options. This means building Perl, Apache, and mod_perl from source, which is quite a daunting task.

Fortunately, Randy Kobes maintains a Windows distribution of mod_perl that includes all the necessary tools, including Perl, Apache, and a host of useful CPAN modules. Using this distribution provides an out-of-the-box Apache + mod_perl combo in minutes.

The distribution comes with extensive documentation. Take the time to read it, particularly if you want to install the software in a location different from the default. In the following installation, we'll use the default locations and options.

Here are the steps for installing mod_perl:

1. Download the Windows distribution. Download perl-win32-bin-x.x.exe from http://perl.apache.org/download/binaries.html. This self-extracting archive yields four directories: Apache/, Perl/, openssl/, and readmes/.
2. Install the software. Move the Apache/ and Perl/ directories to C:\. Edit C:\AUTOEXEC.BAT to install the Perl executable directories in your system's search path:

   SET PATH=C:\Perl\5.6.1\bin;C:\Perl\5.6.1\bin\MSWin32-x86;"%PATH%"

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Preparing the Scripts Directory

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Now you have to select a directory where all the mod_perl scripts and modules will be placed. We usually create a directory called modperl under our home directory for this purpose (e.g., /home/stas/modperl), but it is also common to create a directory called perl under your Apache server root, such as /usr/local/apache/perl.

First create this directory if it doesn't yet exist:

panic% mkdir /home/stas/modperl

Next, set the file permissions. Remember that when scripts are executed from a shell, they are being executed with the permissions of the user's account. Usually, you want to have read, write, and execute access for yourself, but only read and execute permissions for the server. When the scripts are run by Apache, however, the server needs to be able to read and execute them. Apache runs under an account specified by the User directive, typically nobody. You can modify the User directive to run the server under your username, for example:

User stas

Since the permissions on all files and directories should usually be rwx------, set the directory permissions to:

panic% chmod 0700 /home/stas/modperl

Now no one but you and the server can access the files in this directory. You should set the same permissions for all the files you place under this directory.

If the server is running under the nobody account, you have to set the permissions to rwxr-xr-x or 0755 for your files and directories. This is insecure, because other users on the same machine can read your files.

panic# chmod 0755  /home/stas/modperl

If you aren't running the server with your username, you have to set these permissions for all the files created under this directory so Apache can read and execute them.

In the following examples, we assume that you run the server under your username, and hence we set the scripts' permissions to 0700.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

A Sample Apache::Registry Script

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

One of mod_perl's benefits is that it can run existing CGI scripts written in Perl that were previously used under mod_cgi (the standard Apache CGI handler). Indeed, mod_perl can be used for running CGI scripts without taking advantage of any of mod_perl's special features, while getting the benefit of the potentially huge performance boost. Example 2-1 gives an example of a very simple CGI-style mod_perl script.

Example 2-1. mod_perl_rules1.pl

print "Content-type: text/plain\n\n";
print "mod_perl rules!\n";

Save this script in the /home/stas/modperl/mod_perl_rules1.pl file. Notice that the #! line (colloquially known as the shebang line) is not needed with mod_perl, although having one causes no problems, as can be seen in Example 2-2.

Example 2-2. mod_perl_rules1.pl with shebang line

#!/usr/bin/perl
print "Content-type: text/plain\n\n";
print "mod_perl rules!\n";

Now make the script executable and readable by the server, as explained in the previous section:

panic% chmod 0700 /home/stas/modperl/mod_perl_rules1.pl

The mod_perl_rules1.pl script can be tested from the command line, since it is essentially a regular Perl script:

panic% perl /home/stas/modperl/mod_perl_rules1.pl

This should produce the following output:

Content-type: text/plain

mod_perl rules!

Make sure the server is running and issue these requests using a browser:

http://localhost/perl/mod_perl_rules1.pl

If the port being used is not 80 (e.g., 8080), the port number should be included in the URL:

http://localhost:8080/perl/mod_perl_rules1.pl

Also, the localhost approach will work only if the browser is running on the same machine as the server. If not, use the real server name for this test. For example:

http://example.com/perl/mod_perl_rules1.pl

The page rendered should be similar to the one in Figure 2-1.

Figure 2-1: Testing the newly configured server

If you see it, congratulations! You have a working mod_perl server.

If something went wrong, go through the installation process again, making sure that none of the steps are missed and that each is completed successfully. You might also look at the

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

A Simple mod_perl Content Handler

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

As we mentioned in the beginning of this chapter, mod_perl lets you run both scripts and handlers. The previous example showed a script, which is probably the most familiar approach to web programming, but the more advanced use of mod_perl involves writing handlers. Have no fear; writing handlers is almost as easy as writing scripts and offers a level of access to Apache's internals that is simply not possible with conventional CGI scripts.

To create a mod_perl handler module, all that is necessary is to wrap the code that would have been the body of a script into a handler subroutine, add a statement to return the status to the server when the subroutine has successfully completed, and add a package declaration at the top of the code.

Just as with scripts, the familiar CGI API may be used. Example 2-4 shows an example.

Example 2-4. ModPerl/Rules1.pm

package ModPerl::Rules1;
use Apache::Constants qw(:common);

sub handler {
    print "Content-type: text/plain\n\n";
    print "mod_perl rules!\n";
    return OK; # We must return a status to mod_perl
}
1; # This is a perl module so we must return true to perl

Alternatively, the mod_perl API can be used. This API provides almost complete access to the Apache core. In the simple example used here, either approach is fine, but when lower-level access to Apache is required, the mod_perl API shown in Example 2-5 must be used.

Example 2-5. ModPerl/Rules2.pm

package ModPerl::Rules2;
use Apache::Constants qw(:common);

sub handler {
    my $r = shift;
    $r->send_http_header('text/plain');
    $r->print("mod_perl rules!\n");
    return OK; # We must return a status to mod_perl
}
1; # This is a perl module so we must return true to perl

Create a directory called ModPerl under one of the directories in @INC (e.g., under /usr/lib/perl5/site_perl/5.6.1), and put Rules1.pm and Rules2.pm into it. (Note that you will need root access in order to do this.) The files should include the code from the above examples. To find out what the @INC directories are, execute:

panic% perl -le 'print join "\n", @INC'

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Is This All We Need to Know About mod_perl?

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

So do you need to know more about mod_perl? The answer is, "Yes and no."

Just as with Perl, effective scripts can be written even with very little mod_perl knowledge. With the basic unoptimized setup presented in this chapter, visitor counters and guestbooks and any other CGI scripts you use will run much faster and amaze your friends and colleagues, usually without your changing a single line of code.

However, although a 50 times improvement in guestbook response times is great, a very heavy service with thousands of concurrent users will suffer under a delay of even a few milliseconds. You might lose a customer, or even many of them.

When testing a single script with the developer as the only user, squeezing yet another millisecond from the response time seems unimportant. But it becomes a real issue when these milliseconds add up at the production site, with hundreds or thousands of users concurrently generating requests to various scripts on the site. Users are not merciful nowadays. If there is another site that provides the same kind of service significantly faster, chances are that users will switch to the competing site.

Testing scripts on an unloaded machine can be very misleading—everything might seem so perfect. But when they are moved into a production environment, chances are that the scripts will not behave as well as they did on the development box. For example, the production machine may run out of memory on very busy services. In Chapter 10, we will explain how to optimize code to use less memory and how to make as much memory as possible shared.

Debugging is something that some developers prefer not to think about, because the process can be very tedious. Learning how to make the debugging process simpler and more efficient is essential for web programmers. This task can be difficult enough when debugging CGI scripts, but it can be even more complicated with mod_perl. Chapter 21 explains how to approach debugging in the mod_perl environment.

mod_perl has many features unavailable under mod_cgi for working with databases. Some of the most important are persistent database connections. Persistent database connections require a slightly different approach, explained in Chapter 20.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

References

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

• The Apache home page: http://www.apache.org/.
• The mod_perl home page: http://perl.apache.org/.
• The CPAN home page: http://cpan.org/
  CPAN is the Comprehensive Perl Archive Network. Its aim is to contain all the Perl material you will need. The archive is close to a gigabyte in size at the time of this writing, and CPAN is mirrored at more than 100 sites around the world.
• The libwww-perl home page: http://www.linpro.no/lwp/.
  The libwww-perl distribution is a collection of Perl modules and programs that provide a simple and consistent programming interface (API) to the World Wide Web. The main focus of the library is to provide classes and functions that facilitate writing WWW clients; thus, libwww-perl is said to be a WWW client library. The library also contains modules that are of more general use, as well as some useful programs.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Chapter 3: Installing mod_perl

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

In Chapter 2, we presented a basic mod_perl installation. In this chapter, we will talk about various ways in which mod_perl can be installed (using a variety of installation parameters), as well as prepackaged binary installations, and more.

Chapter 2 showed you the following commands to build and install a basic mod_perl-enabled Apache server on almost any standard flavor of Unix.

First, download http://www.apache.org/dist/httpd/apache_1.3.xx.tar.gz and http://perl.apache.org/dist/mod_perl-1.xx.tar.gz. Then, issue the following commands:

panic% cd /home/stas/src
panic% tar xzvf apache_1.3.xx.tar.gz
panic% tar xzvf mod_perl-1.xx.tar.gz
panic% cd mod_perl-1.xx
panic% perl Makefile.PL APACHE_SRC=../apache_1.3.xx/src \
  DO_HTTPD=1 USE_APACI=1 EVERYTHING=1
panic% make && make test
panic# make install
panic# cd ../apache_1.3.xx
panic# make install

As usual, replace 1.xx and 1.3.xx with the real version numbers of mod_perl and Apache, respectively.

You can then add a few configuration lines to httpd.conf (the Apache configuration file), start the server, and enjoy mod_perl. This should work just fine. Why, then, are you now reading a 50-page chapter on installing mod_perl?

You're reading this chapter for the same reason you bought this book. Sure, the instructions above will get you a working version of mod_perl. But the average reader of this book won't want to stop there. If you're using mod_perl, it's because you want to improve the performance of your web server. And when you're concerned with performance, you're always looking for ways to eke a little bit more out of your server. In essence, that's what this book is about: getting the most out of your mod_perl-enabled Apache server. And it all starts at the beginning, with the installation of the software.

In the basic mod_perl installation, the parameter EVERYTHING=1 enables a lot of options for you, whether you actually need them or not. You may want to enable only the required options, to squeeze even more juice out of mod_perl. You may want to build mod_perl as a loadable object instead of compiling it into Apache, so that it can be upgraded without rebuilding Apache itself. You may also want to install other Apache components, such as PHP or mod_ssl, alongside mod_perl.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Configuring the Source

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Before building and installing mod_perl you will have to configure it, as you would configure any other Perl module:

panic% perl Makefile.PL [parameters].

Make sure you have Perl installed! Use the latest stable version, if possible. To determine your version of Perl, run the following command on the command line:

panic% perl -v

You will need at least Perl Version 5.004. If you don't have it, install it. Follow the instructions in the distribution's INSTALL file. The only thing to watch for is that during the configuration stage (while running ./Configure) you make sure you can dynamically load Perl module extensions. That is, answer YES to the following question:

Do you wish to use dynamic loading? [y]

In this section, we will explain each of the parameters accepted by the Makefile.PL file for mod_perl First, however, lets talk about how the mod_perl configuration dovetails with Apache's configuration. The source configuration mechanism in Apache 1.3 provides four major features (which of course are available to mod_perl):

• Apache modules can use per-module configuration scripts to link themselves into the Apache configuration process. This feature lets you automatically adjust the configuration and build parameters from the Apache module sources. It is triggered by ConfigStart/ConfigEnd sections inside modulename.module files (e.g., see the file libperl.module in the mod_perl distribution).
• The APache AutoConf-style Interface (APACI) is the top-level configure script from Apache 1.3; it provides a GNU Autoconf-style interface to the Apache configuration process. APACI is useful for configuring the source tree without manually editing any src/Configuration files. Any parameterization can be done via command-line options to the configure script. Internally, this is just a nifty wrapper over the old src/Configure script.
  Since Apache 1.3, APACI is the best way to install mod_perl as cleanly as possible. However, the complete Apache 1.3 source configuration mechanism is available only under Unix at this writing—it doesn't work on Win32.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Building mod_perl (make)

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

After completing the configuration, it's time to build the server by simply calling:

panic% make

The make program first compiles the source files and creates a mod_perl library file. Then, depending on your configuration, this library is either linked with httpd (statically) or not linked at all, allowing you to dynamically load it at runtime.

You should avoid putting the mod_perl source directory inside the Apache source directory, as this confuses the build process. The best choice is to put both source directories under the same parent directory.

All Perl modules that use C extensions must be compiled using the compiler with which your copy of Perl was built.

When you run perl Makefile.PL, a Makefile is created. This Makefile includes the same compilation options that were used to build Perl itself. They are stored in the Config.pm module and can be displayed with the Perl -V command. All these options are reapplied when compiling Perl modules.

If you use a different compiler to build Perl extensions, chances are that the options this compiler uses won't be the same, or they might be interpreted in a completely different way. So the code may not compile, may dump core, or may behave in unexpected ways.

Since Perl, Apache, and third-party modules all work together under mod_perl, it's essential to use the same compiler while building each of the components.

If you compile a non-Perl component separately, you should make sure to use both the same compiler and the same options used to build Perl. You can find much of this information by running perl -V.

The following errors are the ones that frequently occur during the make process when building mod_perl.

Section 3.2.2.1: Undefined reference to `Perl_newAV'

This and similar error messages may show up during the make process. Generally it happens when you have a broken Perl installation. If it's installed from a broken rpm or another precompiled binary package, build Perl from source or use another properly built binary package. Run perl -V to learn what version of Perl you are using and other important details.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Testing the Server (make test)

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

After building the server, it's a good idea to test it throughly by calling:

panic% make test

Fortunately, mod_perl comes with a big collection of tests, which attempt to exercise all the features you asked for at the configuration stage. If any of the tests fails, the make test step will fail.

Running make test will start the freshly built httpd on port 8529 (an unprivileged port), running under the UID (user ID) and GID (group ID) of the perl Makefile.PL process. The httpd will be terminated when the tests are finished.

To change the default port (8529) used for the tests, do this:

panic% perl Makefile.PL PORT=xxxx

Each file in the testing suite generally includes more than one test, but when you do the testing, the program will report only how many tests were passed and the total number of tests defined in the test file. To learn which ones failed, run the tests in verbose mode by using the TEST_VERBOSE parameter:

panic% make test TEST_VERBOSE=1

As of mod_perl v1.23, you can use the environment variables APACHE_USER and APACHE_GROUP to override the default User and Group settings in the httpd.conf file used for make test. These two variables should be set before the Makefile is created to take effect during the testing stage. For example, if you want to set them to httpd, you can do the following in the Bourne-style shell:

panic% export APACHE_USER=httpd
panic% export APACHE_GROUP=httpd
panic% perl Makefile.PL ...

Tests are invoked by running the ./TEST script located in the ./t directory. Use the -v option for verbose tests. You might run an individual test like this:

panic% perl t/TEST -v modules/file.t

or all tests in a test subdirectory:

panic% perl t/TEST modules

The TEST script starts the server before the test is executed. If for some reason it fails to start, use make start_httpd to start it manually:

panic% make start_httpd

To shut down Apache when the testing is complete, use make kill_httpd:

panic% make kill_httpd

The following sections cover problems that you may encounter during the testing stage.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Installation (make install)

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

After testing the server, the last step is to install it. First install all the Perl files (usually as root):

panic# make install

Then go to the Apache source tree and complete the Apache installation (installing the configuration files, httpd, and utilities):

panic# cd ../apache_1.3.xx
panic# make install

Of course, if you have used the APACHE_PREFIX option as explained earlier in this chapter, you can skip this step.

Now the installation should be considered complete. You may now configure your server and start using it.

If you want to build httpd separately from mod_perl, you should use the NO_HTTPD=1 option during the perl Makefile.PL (mod_perl build) stage. Then you will have to configure various things by hand and proceed to build Apache. You shouldn't run perl Makefile.PL before following the steps described in this section.

If you choose to manually build mod_perl, there are three things you may need to set up before the build stage:

mod_perl's Makefile

When perl Makefile.PL is executed, $APACHE_SRC/modules/perl/Makefile may need to be modified to enable various options (e.g., ALL_HOOKS=1).

Optionally, instead of tweaking the options during the perl Makefile.PL stage, you can edit mod_perl-1.xx/src/modules/perl/Makefile before running perl Makefile.PL.

Configuration

Add the following to apache_1.3.xx/src/Configuration:

AddModule modules/perl/libperl.a

We suggest you add this entry at the end of the Configuration file if you want your callback hooks to have precedence over core handlers.

Add the following to EXTRA_LIBS:

EXTRA_LIBS=`perl -MExtUtils::Embed -e ldopts`

Add the following to EXTRA_CFLAGS:

EXTRA_CFLAGS=`perl -MExtUtils::Embed -e ccopts`

mod_perl source files

Return to the mod_perl directory and copy the mod_perl source files into the Apache build directory:

panic% cp -r src/modules/perl apache_1.3.xx/src/modules/

When you are done with the configuration parts, run:

panic% perl Makefile.PL NO_HTTPD=1 DYNAMIC=1  EVERYTHING=1 \
    APACHE_SRC=../apache_1.3.xx/src

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Installation Scenarios for Standalone mod_perl

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

When building mod_perl, the mod_perl C source files that have to be compiled into the httpd executable usually are copied to the subdirectory src/modules/perl/ in the Apache source tree. In the past, to integrate this subtree into the Apache build process, a lot of adjustments were done by mod_perl's Makefile.PL. Makefile.PL was also responsible for the Apache build process.

This approach is problematic in several ways. It is very restrictive and not very clean, because it assumes that mod_perl is the only third-party module that has to be integrated into Apache.

A new hybrid build environment was therefore created for the Apache side of mod_perl, to avoid these problems. It prepares only the src/modules/perl/ subtree inside the Apache source tree, without adjusting or editing anything else. This way, no conflicts can occur. Instead, mod_perl is activated later (via APACI calls when the Apache source tree is configured), and then it configures itself.

There are various ways to build Apache with the new hybrid build environment (using USE_APACI=1):

• Build Apache and mod_perl together, using the default configuration.
• Build Apache and mod_perl separately, allowing you to plug in other third-party Apache modules as needed.
• Build mod_perl as a DSO inside the Apache source tree using APACI.
• Build mod_perl as a DSO outside the Apache source tree with APXS.

If your goal is just to build and install Apache with mod_perl out of their source trees, and you have no interest in further adjusting or enhancing Apache, proceed as we described in Chapter 2:

panic% tar xzvf apache_1.3.xx.tar.gz
panic% tar xzvf mod_perl-1.xx.tar.gz
panic% cd mod_perl-1.xx
panic% perl Makefile.PL APACHE_SRC=../apache_1.3.xx/src \
    DO_HTTPD=1 USE_APACI=1 EVERYTHING=1
panic% make && make test
panic# make install
panic# cd ../apache_1.3.xx
panic# make install

This builds Apache statically with mod_perl, installs Apache under the default /usr/local/apache tree, and installs mod_perl into the site_perl hierarchy of your existing Perl installation.

However, sometimes you might need more flexibility while building mod_perl. If you build mod_perl into the Apache binary (

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Building mod_perl with Other Components

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

mod_perl is often used with other components that plug into Apache, such as PHP and SSL. In this section, we'll show you a build combining mod_perl with PHP. We'll also show how to build a secure version of Apache with mod_perl support using each of the SSL options available for Apache today (mod_ssl, Apache-SSL, Stronghold, and Covalent).

Since you now understand how the build process works, we'll present these scenarios without much explanation (unless they involve something we haven't discussed yet).

All these scenarios were tested on a Linux platform. You might need to refer to the specific component's documentation if something doesn't work for you as described here. The intention of this section is not to show you how to install other non-mod_perl components alone, but how to do this in a bundle with mod_perl.

Also, notice that the links we've used are very likely to have changed by the time you read this document. That's why we have used the x.xx convention instead of using hardcoded version numbers. Remember to replace the x.xx placeholders with the version numbers of the distributions you are going to use. To find out the latest stable version number, visit the components' sites—e.g., if we say http://perl.apache.org/dist/mod_perl-1.xx.tar.gz, go to http://perl.apache.org/download/ to learn the version number of the latest stable release of mod_perl 1, and download the appropriate file.

Unless otherwise noted, all the components install themselves into a default location. When you run make install, the installation program tells you where it's going to install the files.

The following is a simple installation scenario of a combination mod_perl and PHP build for the Apache server. We aren't going to use a custom installation directory, so Apache will use the default /usr/local/apache directory.

1. Download the latest stable source releases:

   Apache:   http://www.apache.org/dist/httpd/
   mod_perl: http://perl.apache.org/download/
   PHP:      http://www.php.net/downloads.php

2. Unpack them:

   panic% tar xvzf mod_perl-1.xx
   panic% tar xvzf apache_1.3.xx.tar.gz
   panic% tar xvzf php-x.x.xx.tar.gz

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Installing mod_perl with the CPAN.pm Interactive Shell

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Installation of mod_perl and all the required packages is much easier with the help of the CPAN.pm module, which provides, among other features, a shell interface to the CPAN repository (see the Preface).

First, download the Apache source code and unpack it into a directory (the name of which you will need very soon).

Now execute:

panic% perl -MCPAN -eshell

You will see the cpan prompt:

cpan>

All you need to do to install mod_perl is to type:

cpan> install mod_perl

You will see something like the following:

Running make for DOUGM/mod_perl-1.xx.tar.gz
Fetching with LWP:
http://www.cpan.org/authors/id/DOUGM/mod_perl-1.xx.tar.gz

CPAN.pm: Going to build DOUGM/mod_perl-1.xx.tar.gz

(As with earlier examples in this book, we use x.xx as a placeholder for real version numbers, because these change very frequently.)

CPAN.pm will search for the latest Apache