This will be something of an oversimplification because it is not necessary that the full details of mod_perl be explained for the purposes of an Apache administrator. But some points made in this chapter will make more sense if you understand something about the way mod_perl works.

mod_perl embeds a Perl interpreter in the main parent Apache process. Each Apache child then contains its own memory space that is used in conjunction with the Perl interpreter to execute Perl code. This means that data (and code) that is in the main Perl interpreter can be used by all the child processes. However, data that is only in one child process is not accessible to the others.

First, download the latest Apache distribution, and the latest mod_perl distribution. You will find these at http://httpd.apache.org/ and http://perl.apache.org/, respectively.

Unpack these distributions somewhere convenient. /usr/src is a recommended location, so that you'll know where all your installed packages live.

Change into the mod_perl directory, and type something like the following:

perl Makefile.PL 
APACHE_PREFIX=/usr/local/apache 
APACHE_SRC=../apache-1.3.20/src 
DO_HTTPD=1 
USE_APACI=1 
EVERYTHING=1 
APACI_ARGS='—enable-module=rewrite,—enable-module=speling'

Note that those backslashes at the end of each line are continuation characters. That means that you can either type them, if you like, or just type the entire command as one single line.

After this has finished doing things, you should then type:

make && make install

To back up a little, here's a blow-by-blow of what that long command line did.

The first line, perl Makefile.PL, is the command that starts the process that builds and installs mod_perl and Apache on your server. Perl comes with a set of utilities that assist in the generation of makefiles, which are scripts that automate a build process. Makefile.PL is a Perl program that generates a makefile.

When running Makefile.PL, a number of arguments can be passed in, which affect the behavior of the build.

The first such argument is APACHE_PREFIX, which is the location Apache is to be installed. This is the equivalent to the -prefix argument that we used when building Apache earlier in the book.

APACHE_SRC gives the location of the Apache source code, which you have presumably unpacked in the same directory where you unpacked the mod_perl code. In the given example, we are building with Apache version 1.3.20, and so the source code for Apache is in the directory ../apache-1.3.20/src relative to the current location.

The DO_HTTPD argument tells mod_perl to build and install Apache when it builds itself. By default, it will just build the mod_perl portion, but not rebuild Apache.

USE_APACI causes the build process to use APACI to configure and build Apache. This was discussed in Chapter 2, “Acquiring and Installing Your Apache Server,” and is the Apache autoconf tool.

EVERYTHING=1 tells mod_perl to build and install everything that came with it, including all the Perl modules and support programs.

Finally, perhaps the most important part of the command, the APACI_ARGS argument lists the arguments that we want passed on to APACI to build Apache. This is where you put all the arguments that you would have passed to ./configure if you were building Apache without mod_perl. In my example, I have added the modules mod_rewrite and mod_speling by using the -enable-module argument, which is passed directly to the Apache configuration.

Typing make && make install compiles the mod_perl and Apache source code into binary form, and installs it in all the correct locations, as we discussed in Chapter 2.

After you have typed the previous commands, you can restart your Apache server with the apachectl utility. Using this procedure, you can have a new Apache installation in place in just a few minutes. If you already have Apache installed and configured, the build and installation process will preserve your existing configuration files, and just install the various binaries over the ones that are already there. Consequently, unless you are removing modules that you had installed before, you should be able to install a new Apache and continue using your existing configuration files with no ill effects.

The PerlRequire directive specifies the location of a Perl script that is to be run when the server starts up. Because the Perl interpreter is in the main Apache parent process, and any Perl code that is cached in that parent process is available to all child processes, Perl code executed at server start time is always available to the child processes.

So, any code that is run by the server at run time will be cached in the parent process, and available to the children.

PerlRequire should be used to load modules or constants that will be used by all the child processes. This will save memory because it is loaded into memory only once for the parent process, rather than having one copy in memory for each child process.

For example, in your main server configuration, you might have the following:

PerlRequire /usr/local/apache/vhosts/clueful/conf/preload.pl

Then, in the file preload.pl you would have the following:

use Apache::DBI;
use DBI;
use CGI qw(:Standard);
use MyCompany::Utils;
1;

Any child process that tries to load DBI will get it from the parent Apache process, rather than having to load it from a disk each time.

Note that the file loaded by PerlRequire needs to return a true value to tell Perl that it was successfully loaded. This is accomplished by putting a 1; as the last statement of the file. This is a no-op, but returns a true value.

Actually, DBI is a special case. mod_perl comes with a special-purpose module called Apache::DBI, which is a wrap-around DBI and provides persistent database connections. The first time you make a connection to a database, Apache::DBI intercepts calls to DBI and caches that connection so that all future database connections are made through the connection that is already open. This results in yet another enormous performance improvement, as you never have to wait for a database connection except for the first time. You will still make your DBI calls exactly as before, and Apache::DBI will automatically take over as needed.

Make sure that your PerlRequire script has Apache::DBI in it before DBI. You might also want to add a call to connect_on_init, which establishes the database handle during server startup, so that all the Apache children can share the database connection. It will look like this:

Apache::DBI->connect_on_init( $database, $username, $password );

The arguments $database, $username, and $password are the same as in the DBI connect method. See the DBI documentation for additional details.

Apache::Registry is the preferred of the two methods, because it gives you all the benefits of using mod_perl, and removes all the things that make CGI unpleasant.

Apache::Registry works by compiling your CGI program once, the first time that it is run, and then storing that compiled form for future reference. The next time that the resource is requested, mod_perl loads it out of the cache, and executes the version that it has already compiled, saving the two most expensive parts of CGI execution—launching Perl in the first place, and compiling your CGI program. The first person to request the resource after a server restart (or after a new Apache child has been spawned) will get CGI-speed performance, but everyone after that will experience the speedup.

Alias /perl/  /usr/local/apache/cgi-bin/

<Location /perl>
  SetHandler  perl-script
  PerlHandler Apache::Registry
  Options +ExecCGI
</Location>

use strict;
use warnings;

#!/usr/bin/perl -w

If you have existing Perl CGI programs that work under mod_cgi, and you really don't want to spend the time to make them work under mod_perl, there is a halfway solution. Apache::PerlRun gives you some of the benefits of mod_perl, but without having to make sure that your code is strict safe.

This is only recommended as an interim solution while you whip your CGI programs into place, or for programs that you have acquired from some other source and don't really understand where you can make modifications.

Alias /cgi-perl/  /usr/local/apache/cgi-bin/

<Location /cgi-perl>
  SetHandler  perl-script
  PerlHandler Apache::PerlRun
  Options +ExecCGI
  PerlSendHeader on
</Location>

With the configurations previously shown, and with a ScriptAlias directive also pointing at the same directory, you can do a direct head-to-head comparison of performance on the same CGI program. The URLs http:://your.server.name/cgi-bin/test.cgi, http://your.server.name/cgi-perl/test.cgi, and http://your.server.name/perl/test.cgi should all be pointing to exactly the same CGI program, but executed in three different ways, and executed in progressively better time, in the order listed here. The exact performance improvement will depend on the complexity of the code, but you should see a noticeable improvement.

It is important to note, as discussed in more detail in the “Common Problems” section that follows, each Apache child will have to cache the CGI program before you start seeing an improvement in performance. So, if you have 10 Apache child processes running, you will have to hit reload 10 times (on average) before you start seeing a child that has the code cached and gives you better performance.

A mod_perl handler is an Perl module that contains a handler method. This method gets called by Apache, and passed an Apache::Session object. The method is expected to generate content that is sent to the client.

The Apache::Session object, which is passed to your method, is useful for things such as cookies, environment variables, authentication information, and so on—the sorts of things that you got from the environment when using CGI. It can also be used to make calls directly to the Apache API. This can be used to get form contents, to redirect to another location, or for a wide variety of other tasks.

This chapter does not attempt to be comprehensive with regard to mod_perl, so you should check out some of the resources listed in section “Where to Get More Information” to get more details.

As in Chapter 15, we'll start with a very simple example to show you what a mod_perl handler looks like. The following code example displays the text mod_perl in your browser window.

Note again that the use warnings; should be removed if you are running a version of Perl earlier than 5.6.

package ApacheAdmin::ExampleOne;
use strict;
use warnings;

sub handler {
    my $r = shift;
    $r->content_type('text/html'),
    $r->status(200);
    $r->send_http_header;

    print "mod_perl";
}

When Apache calls your handler it loads the module and calls the handler method, sending any output to the browser.

The argument passed in, which is referred to in this example as $r, is the Apache::Session object. It is traditionally represented as $r because it is usually a request or response object. Also, the Apache code itself always refers to the Apache session object with the variable r, you will see it represented this way in many examples as well as a lot of the documentation.

Also note that the line use warning; will not work if you are using a version of Perl earlier than 5.6. You are encouraged to upgraded to at least that version of Perl.

mod_perl handlers are Perl modules, and are found by mod_perl in the same way that Perl finds modules. That is, it looks through directories listed in the special variable @INC, which is a list of directories where Perl can find modules.

So, to install your new mod_perl handler, you need to either put it in a directory listed in @INC, or put it's location into @INC. For the moment, we'll do the latter.

The name of our module is ApacheAdmin::ExampleOne. When Perl looks for this module, it will look for a file called ExampleOne.pm, in a directory called ApacheAdmin, a subdirectory of one of the directories listed in @INC.

Perl provides an easy way to add directories to @INC with the use lib pragma. The syntax of this function is as follows:

use lib '/path/to/directory';

Save the example Perl code in a file called ExampleOne.pm, and put it in a directory called ApacheAdmin, in some convenient location. For example, you might place this in your home directory, so that the full path to the file is /home/rbowen/ApacheAdmin/ExampleOne.pm.

Then, in the file that you have noted in your PerlRequire directive add the following directive:

use lib '/home/rbowen/';

This directive added the specified directory to @INC so that Perl knows to look there for Perl modules, and therefore can find your module. Now you're ready to configure mod_perl to run your handler.

Now that you have the handler installed so that Perl can find it, you need to tell Apache how to use it. As with other handlers, mod_perl handlers are configured via a section directive in the main server configuration file. Because these handlers are not related to file-system resources, they will be configured with a Location section. You just need to tell Apache what module to call when asked for the particular resource.

This configuration will look like the following:

<Location /apacheadmintest>
    SetHandler perl-script
    PerlHandler ApacheAdmin::ExampleOne
</Location>

If you want to call a function in your module that is called something other than handler, you will need to specify this explicitly in the configuration, as shown here:

<Location /apacheadmintest>
    SetHandler perl-script
    PerlModule ApacheAdmin::ExampleOne
    PerlHandler ApacheAdmin::ExampleOne::other_method
</Location>

This enables you to have several different locations fielded by several different functions within a single module.

The previous example did not actually do anything useful. The example that follows, although it does not do much more, contains a useful element that will be part of most handlers that you write—the capability to acquire the contents of a form that was sent to you. Rather than having to rely on a CGI library to get this content, you can request it directly from mod_perl, as shown here.

package ApacheAdmin::ExampleTwo;
use strict;
use warnings;

sub handler {
    my $r = shift;

    my %form = $r->method eq 'POST' ? $r->content : $r->args;

    $r->content_type('text/html'),
    $r->status(200);
    $r->send_http_header;

    foreach my $key ( keys %form ) {
        print $key . ' => ' . $form{ $key}  . '<br>';
    }
}

This rather inelegant example prints to the browser the contents of either any form posted to it or any arguments passed on the URL command line via the ?key=value&key=value syntax. See Chapter 15 for more information about the format of this syntax.

For further discussion of the code shown here, please see Appendix D, “mod_perl Example Code.”

Perl programs have a tendency to call exit when they are done. This indicates where the program ends, and nothing more is to be done. The exit function causes the Perl interpreter to stop immediately.

Remember, however, that the entire point of mod_perl is that the interpreter does not stop, ever. Consequently, calling exit is a very bad thing. The Perl interpreter exits, causing the particular mod_perl child to lose its mind. This has a number of results. The client does not get a complete document most of the time, because the Apache child never gets a message that the generated content is complete. And typically, that particular child becomes useless for future mod_perl-generated resources, often serving the same content (whatever it saw last) repeatedly, until the child is killed, or the Apache server is restarted.

So don't use exit in your handlers, for any reason.

When you change a handler that you are working on, your changes will not be seen immediately because they are with CGI programs. Because mod_perl loads the modules into the Perl interpreter memory, and caches them there forever, your new version of the module will not be seen until the server is restarted.

Note that you usually will have to stop the Apache process, and start it again, rather than just doing a restart, to actually get all the cached modules reloaded.

You can overcome this with the directive PerlFreshRestart on in your main server configuration file. With PerlFreshRestart on all modules will get reloaded on a server restart. This will generate a lot of function was redefined warnings in your error log on server restart. This is normal, and should not unduly concern you.

If you find that some values are unexpected sometimes, you might be using global values carelessly. Remember that all global values are shared across all accesses to a given Apache child process.

This problem can be rather elusive if you are not very careful in testing. Because a normal Apache server will have many child processes at a time you need to make sure to test a condition sufficiently after a server restart. You should go through all the server children at least once, so that you are actually using a child that you had used before. It is a good idea to set MinSpareServers, MaxSpareServers, and StartServers very low for testing purposes so that you are dealing with a very small server pool and problems related to reusing child processes will show up more rapidly.