- What mod_perl Is and How It Works
- mod_perl Configuration
- Writing mod_perl Scripts
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
mod_perl Configuration
Apache uses a standard protocol, the Common Gateway Interface (CGI), to communicate with externally executed scripts such as those we put in the cgi-bin directory in the preceding chapter.When a CGI script begins executing, it can assume that Apache has set up certain environment variables. For example, REMOTE_ADDR and REQUEST_URI indicate the client’s host IP number and the request path.When Apache uses mod_perl to execute a script directly, it doesn’t set up the CGI environment. In principle, there
mod_perl Configuration 5
is no need, because a script that has direct access to Apache’s internals obviously can extract that information itself if it wants. But the practical implication of this is that Perl CGI scripts won’t function properly under mod_perl unless they are rewritten to use the Apache API or unless something else sets up the CGI environment for them.
Obviously, the latter alternative is preferable. If you already have a bunch of CGI scripts, you don’t want to rewrite them all specifically for mod_perl. Fortunately, there is an easy solution to this problem. mod_perl includes an Apache::Registry module that sets up the CGI environment for you. If we use it to run our CGI scripts, mod_perl becomes transparent to them so that (for the most part) they don’t need to know or care whether they’re being run by a standalone Perl process or by mod_perl. This enables you to move your scripts between the standalone and mod_perl execution environments easily.1
Oh, you noticed that “for the most part” in the preceding paragraph, did you? That disclaimer was necessary because scripts containing certain constructs need modification for mod_perl.We’ll get to this in the section titled “Writing mod_perl Scripts.”
The rest of this section describes how to configure Apache to use mod_perl and Apache::Registry for running Perl scripts.The steps are as follows:
-
Create a directory for mod_perl scripts.
-
Verify that mod_perl is installed.
-
Configure httpd.conf to tell Apache how to execute mod_perl scripts.
-
Test your configuration.
-
Set up a mod_perl startup file (optional, but useful).
Before following these instructions, verify that you have recent enough versions of Perl and CGI.pm.You should have Perl 5.005 or later.You should also have CGI.pm 2.36 or later, because earlier versions don’t work with mod_perl. If your versions aren’t recent enough, you’ll need to upgrade. See Appendix A,“Obtaining Software,” for instructions.
Create a Directory for mod_perl Scripts
Chapter 2 covered general Apache directory layout issues, including how to configure Apache to execute scripts found in the server’s cgi-bin directory. Here we’ll use a different directory for scripts that we intend to be executed by mod_perl.The examples in this chapter assume the use of cgi-perl under your Apache server’s root, so the first thing you need to do is create that directory:
% cd /usr/local/apache
% mkdir cgi-perl
If you’re using a different layout, make the appropriate substitutions in these commands and in the configuration instructions throughout the rest of this section.
Verify That mod_perl Is Installed
To use mod_perl, it needs to be compiled into the Apache httpd binary or loaded as an Apache dynamic shared object (DSO).Try running httpd –l to get a list of compiled-in modules. If mod_perl is among them, it’s already installed. If mod_perl isn’t compiled in, check whether it’s available as a DSO. (Look in the modules directory under the server root directory to see whether there’s a file with mod_perl in its name.) If not, you’ll need to install mod_perl before proceeding to the next step. For instructions, refer to Appendix A.
Configure httpd.conf
If you’re using a DSO version of mod_perl, you need to tell Apache where to find it by adding a LoadModule directive to your httpd.conf file. (If the name of the file is different from mod_perl.so on your system, make the appropriate adjustment to the line shown here.)
LoadModule perl_module modules/mod_perl.so
Next (for both compiled-in and DSO installations), tell Apache to associate mod_perl with scripts located in the cgi-perl directory by adding the following lines to httpd.conf:
Alias /cgi-perl/ /usr/local/apache/cgi-perl/ <Location /cgi-perl>
SetHandler perl-script
PerlHandler Apache::Registry
PerlSendHeader on
Options ExecCGI
</Location>
The Alias line specifies that when a URL begins with /cgi-perl/ after the host name part (for example, http://www.snake.net/cgi-perl/myscript.pl), Apache should look in the /usr/local/apache/cgi-perl/ directory to find the script. (You must use Alias; don’t use ScriptAlias, because it won’t work with mod_perl.) The <Location> block provides the specifics about how to handle scripts found in the cgi-perl directory.The SetHandler and PerlHandler directives specify that we want to run them using Apache::Registry so that a CGI environment gets set up before they start executing. PerlSendHeader tells Apache that we want it to generate the HTTP header that precedes script output sent to the client.The Options line turns on CGI script-execution capability for the cgi-perl directory.
It’s also possible to associate mod_perl with scripts based on their filenames rather than on their location. (You might do this if you want to put scripts in the document tree rather than in the cgi-perl directory.) To execute scripts having names ending in .pl as mod_perl CGI scripts, for example, add these lines to httpd.conf:
<Files *.pl>One drawback to associating .pl scripts with mod_perl this way is that the association will apply not only to new scripts that you write, but also to scripts that are already present in your document tree—scripts that may not have been written with mod_perl in mind. If that’s a problem, you might want to consider using a <mod_perl-specific extension such as .mpl instead. (Don’t forget to change the <Files> line from *.pl to *.mpl if you do this.)
SetHandler perl-script PerlHandler Apache::Registry
PerlSendHeader on
Options ExecCGI
</Files>
As long as you’re modifying httpd.conf, add the following lines, too.They provide access to Apache::Status, a handler that displays all kinds of diagnostic information about your mod_perl setup when you send a perl-status request to Apache. Add the lines as shown, except that you should change the IP number on the allow from line to the name or IP number of the host on which you run your Web browser:
<Location /perl-status>
SetHandler perl-script
PerlHandler Apache::Status
order deny,allow
deny from all
allow from 192.168.1.15
</Location>
Test Your mod_perl Configuration
Each time you modify the configuration file, as in the preceding section, you must restart Apache. (See Chapter 2 for instructions on doing so.)
Do that right now, and then you’ll be ready to test your setup.To begin, request the perl-status “page” from your site:
http://www.snake.net/perl-status
In your browser, you should see something similar to Figure 3.1, where the initial part of the display shows some overall configuration information and the items below the line provide links to pages listing more specific information about mod_perl itself. Select a few of the links to get a feel for the kinds of information they provide.
){kind=link}
Figure 3.1 Output from the perl-status handler.
Next, create the following short script in the cgi-bin directory (that’s right, cgi-bin, not cgi-perl):
#! /usr/bin/perl
print “Content-Type: text/html\n\n”;
print “<html><head><title>Script
Environment</title></head><body>\n”;
print map { “$_ = $ENV{$_}<br>\n” } sort (keys (%ENV));
print “</body></html>\n”;
Name the script perltest.pl, make it executable, and request it through your browser (http://www.snake.net/cgi-bin/perltest.pl).The script should print the names and values of its environment variables. One of the output lines will show the value of the GATEWAY_INTERFACE environment variable, which should begin with CGI:
GATEWAY_INTERFACE = CGI/1.1
Now copy perltest.pl to the cgi-perl directory and request http://www.snake.net/cgi-perl/perltest.pl so that the script is executed by mod_perl rather than by a standalone Perl process.The output should be similar, but the value of GATEWAY_INTERFACE should begin with CGI-Perl, not CGI.This indicates that the CGI environment has been set up by the mod_perl Apache::Registry module. In addition, the output should show a variable mod_perl containing your mod_perl version number:
GATEWAY_INTERFACE = CGI-Perl/1.1
mod_perl = mod_perl/1.24
This exercise with perltest.pl shows how you can run a script either as a standalone CGI program or using mod_perl. It also shows what you need to do if you have a script that needs to know whether it’s running under mod_perl—that is, you can use either of the following tests:
if (exists ($ENV{mod_perl})) { print “mod_perl yes\n”; }
if ($ENV{GATEWAY_INTERFACE} =~ /^CGI-Perl/) { print “mod_perl yes\n”; }
Set Up a mod_perl Startup File
The Apache::Registry handler automatically sets up the CGI environment for your Perl scripts.You can augment the information that Apache::Registry provides by setting up a mod_perl startup file to be read during Apache’s initialization process. (The file is written in Perl, of course.) To do this, use a PerlRequire directive. If you want to call the file startup.pl and put it with the other Apache configuration files in the conf directory under the server root, for instance, add this line to httpd.conf:
PerlRequire conf/startup.pl
If you want to put the startup file in lib/perl with the other Perl library files, use this line instead:
PerlRequire lib/perl/startup.pl
After configuring httpd.conf to specify the location of the startup file, what should you put in it? That’s up to you. One way to use the file is to set up additional information in the standard environment under which you want your scripts to run. If many of your scripts include a use lib pathname line to add a given directory to the Perl search path, you can add the directory to the path in the startup file instead.Then it’s added automatically, and your scripts don’t need to do it for themselves.
Another use for the startup file is to preload common Perl modules to improve performance.When Apache starts up, it reads and processes its configuration file (which includes processing the mod_perl startup file).Then it spawns a bunch of child httpd processes to handle client requests. In general, the more work you can get done in the parent httpd process before it starts spawning children, the more efficient your system will be.This is true not only for script execution speed, but also for system resource consumption, particularly memory use. Let’s see why this is.
Each child httpd begins executing as a copy of the parent, and, due to the way virtual memory works, it shares the address space of the parent rather than doubling the amount of memory used. As the processes run, the amount of shared address space tends to decrease. (If the child changes a data structure, for instance, any memory pages containing that data can no longer be shared with the parent.The system duplicates those pages and marks them as unshared—unique to and owned by the child.) Nevertheless, a large amount of address space generally continues to be shared between the parent and its children; this is a big win for memory management and for system performance in general.
You can use the mod_perl startup file to influence your system’s performance by exploiting the address space sharing provided by virtual memory. If you tend to use certain Perl modules in many of your scripts, you can name them in the startup file to preload them into the parent httpd process.The code of these modules then becomes part of that process and thus part of its address space that can be shared with the child processes.The parent process becomes larger, but overall memory use goes down, compared to having those modules loaded by each individual child and becoming part of their unshared address space.
An additional benefit of code preloading is that the code is compiled only once, by the parent.The children receive the code precompiled. Any module that isn’t preloaded must be loaded and compiled by each child individually when scripts that are run by the child request it; therefore more processor time is used.
With the preceding discussion in mind, let’s look at an example startup file. Suppose you want to give your scripts access to Perl library files in the /usr/local/
apache/lib/perl and /var/lib/perl directories without having to put use lib statements for those directories in every single script. Suppose also that most of your scripts use the CGI.pm and DBI modules, so you want to preload them.You can accomplish these goals by writing your startup file as follows:
use strict;Here are some things to note about this startup file, because they aren’t particularly obvious:
use lib qw(/usr/local/apache/lib/perl);
use lib qw(/var/lib/perl);
use CGI (); CGI->compile (‘:all’);
use DBI ();
use DBD::mysql ();
1; # return true
You might not actually need to include the use lib line for the lib/perl directory. Recent versions of mod_perl search that directory automatically.
The () after the names of the modules that are preloaded prevents method names from being imported.This saves a little memory during Apache startup, and importing the names can wait until your scripts execute.
The call to CGI->compile() forces preloading of the CGI.pm methods that otherwise are autoloaded on demand.Without this call, these methods won’t be loaded until later, and the code will go into the unshared address space of individual httpd children.
Normally DBI locates and loads the DBD::mysql driver when you’re using the DBI module to access MySQL. But that doesn’t happen until later, when you actually attempt to connect to the MySQL server.To get the advantage of preloading for the driver and not just the main DBI module, you have to load the driver explicitly at startup time.
The final line is required; don’t leave it out.When Perl reads the startup file, it expects a return value of true or false to indicate whether the file executed suc-cessfully.The final line evaluates to 1 (true), which becomes the return value. If you omit the line,Apache startup fails after writing a line like this to the error log:
[error] conf/startup.pl did not return a true value
You must restart Apache each time you modify the startup file, just as when you modify httpd.conf. However, there’s a slight complication in that the startup file won’t be read under certain circumstances. If mod_perl is loaded as a DSO, it’s torn down completely and reloaded from scratch whenever Apache restarts. In this case, you don’t have anything to worry about; the startup file will be reread when mod_perl is reinitialized. On the other hand, if mod_perl is compiled in to httpd, Apache doesn’t reread the startup file by default.You have a couple of options here. First, you can restart with apachectl stop followed by apachectl start.That brings the server all the way down and starts a new one, causing the entire initialization sequence to be performed. Alternatively, you can add the following directive to httpd.conf:
PerlFreshRestart on
PerlFreshRestart on explicitly tells Apache to reread the mod_perl startup file when it restarts, even for apachectl restart and apachectl graceful. However, the mod_perl Guide cautions that PerlFreshRestart can cause problems on some systems. Before deciding whether to use it, read the section in the Guide titled “Evil Things Might Happen When Using PerlFreshRestart.” If you decide against it, you’ll need to go the route of using apachectl stop and apachectl start to restart the server after startup file changes.
After restarting Apache, you can check whether it reloaded the startup file by requesting the perl-status page described in the section “Test Your mod_perl Configuration.” If you change the Perl search path, for example, this should be reflected in the value of the @INC array at the bottom of the perl-status “Loaded Modules” page.
Alternatives to the Startup File
Some of the work that you do in the mod_perl startup file can be accomplished directly in httpd.conf.You can add directories to Perl’s search path using a PerlSetEnv directive in httpd.conf to set the PERL5LIB variable.The value can be a single directory pathname or a list of colon-separated pathnames:
PerlSetEnv PERL5LIB /usr/local/apache/lib/perl:/var/lib/perl
However, this is less efficient than using the startup file because it adds a little overhead for each script run by mod_perl.When you set the path in the startup file, it’s done once and affects all scripts automatically.
You can preload Perl modules using the PerlModule directive.This is equivalent to loading the modules in the startup file. One or more modules can be named:
PerlModule CGI DBI DBD::mysql