Basic Configuration

For the sake of simplicity in this introduction, we'll assume a single Apache server which is mod_perl enabled, even if this is not the ideal architecture for sites with lots of static content. The Apache server is configured, prior to launch, in the very long but well commented httpd.conf file which, in a default installation, is found in /usr/local/apache/conf subdirectory. Once again, and not to pass the buck too often, Apache server configuration is a career unto itself, so we will focus only on configuration of the mod_perl aspect.

Simply put, we want to tell Apache to process Perl scripts via the Apache::Registry module, which is mod_perl's pseudo-CGI environment. This allows us to run Perl scripts written for a typical CGI environment (such as using the CGI.pm module) under mod_perl, which is technically not a CGI extension.

The default httpd.conf file installed with Apache is not configured to use mod_perl; instead, it is configured to execute scripts via CGI. You will probably find a configuration directive in your httpd.conf file that looks something like:

ScriptAlias /cgi-bin/ "/usr/local/apache/cgi-bin/"

This directive tells Apache that any files in the relative path /cgi-bin/ should be considered scripts, and launched accordingly. You need to consider whether all scripts on your web site will be Perl and handled by mod_perl, or whether there are other scripts that may still need to execute via CGI. The safest approach is to retain at least one subdirectory for traditional old-style CGI scripts and one subdirectory for your mod_perl Perl scripts. The ScriptAlias directive above must only point to a path with CGI scripts, and not to the path where you want Perl scripts executed from. Let's say, then, that you create a new path -- /usr/local/apache/cgi-perl/ for your mod_perl enabled scripts.

Of course, if you are running mod_perl scripts exclusively, you could simply comment out the ScriptAlias directive by preceding it with a pound symbol (#), and simply use the cgi-bin/ path for your Perl scripts.

Now we're ready to add mod_perl specific configuration directives. If you scroll through the httpd.conf file, you'll find a section which contents the commented heading "Aliases: Add here as many aliases as you need ...". It's easiest to scroll down towards the end of this section, just before it is closed with the </IfModule> tag, and add our new alias here.

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

<Location /cgi-perl> 
SetHandler perl-script 
PerlHandler Apache::Registry 
Options ExecCGI 
PerlSendHeader On 
</Location>

Above, we define an alias, linking /cgi-perl/ to the system path /usr/local/apache/cgi-perl/. The <Location> directive references this alias and defines a number of attributes for it. First, we tell Apache to let mod_perl handle these files via the SetHandler directive, and we tell mod_perl to handle them using its Apache::Registry module. The Registry module is basically the star of the show here, as it is what handles emulating a CGI environment and compiling/caching the Perl code. We tell Apache to handle these files as executable via the ExecCGI parameter, otherwise the browser would try to send the script as a text file to the end user -- yikes!. Finally, we tell Apache to send an HTTP header to the browser on script execution -- this is not strictly necessary if your Perl script is well behaved about sending the header itself, such as by the CGI->header() method of the CGI.pm module.

Gee, it's huge
The Perl You Need to Know
Start Your Coding