2.3 Configuring and Starting the mod_perl Server

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,^[1] the user executing apachectl must be root.

^[1] Privileged ports are 0-1023. Only the programs running as root are allowed to bind to these.

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 make install in the Apache source tree, should appear in the browser. If this page does not appear, something went wrong and the contents of the logs/error_log file should be checked. The path to the error log file is specified by the ErrorLog directive in httpd.conf. (It is usually specified relative to the ServerRoot, so a value of logs/error_log usually means /usr/local/apache/logs/error_log if Apache is installed into /usr/local/apache.)

If everything works as expected, shut down the server, open httpd.conf with a text editor, and scroll to the end of the file. The mod_perl configuration directives are conventionally added to the end of httpd.conf. It is possible to place mod_perl's configuration directives anywhere in httpd.conf, but adding them at the end seems to work best in practice.

Assuming that all the scripts that should be executed by the mod_perl-enabled server are located in the /home/stas/modperl directory, add the following configuration directives:

Alias /perl/ /home/stas/modperl/

PerlModule Apache::Registry
<Location /perl/>
    SetHandler perl-script
    PerlHandler Apache::Registry
    Options +ExecCGI
    PerlSendHeader On
    Allow from all
</Location>

Save the modified file.

This configuration causes every URI starting with /perl to be handled by the Apache mod_perl module with the handler from the Perl module Apache::Registry.