Recipe 8.13 Installing a mod_perl Handler from CPAN

Problem

You want to install one of the many mod_perl handler modules available on CPAN. For example, you want to install the Apache::Perldoc module, which generates HTML documentation for any Perl module you happen to have installed.

Solution

Assuming you already have mod_perl installed, you'll just need to install the module from CPAN, and then add a few lines to your Apache configuration file.

To install the module, run the following command from the shell as root:

# perl -MCPAN -e 'install Apache::Perldoc'

Then, in your Apache configuration file, add:

<Location /perldoc>
    SetHandler perl-script
    PerlHandler Apache::Perldoc
</Location>

After restarting Apache, you can access the handler by going to a URL such as http://example.com/perldoc/Apache/Perldoc.

Discussion

The CPAN shell, which is installed when Perl is installed, gives you an easy way to install Perl modules from CPAN. CPAN, if you're not familiar with it, is the Comprehensive Perl Archive Network, at http://cpan.org, a comprehensive archive of Perl stuff, including Perl modules for every purpose you can imagine and several you can't. This includes a substantial number of mod_perl handlers.

The module specified in this recipe is a very simple one that gives you HTML documentation for any Perl module you have installed, accessible via your Apache server. Other ones provide photo albums, weblog handlers, and DNS zone management, among other things.

The first time you run the CPAN shell, you will need to answer a series of questions about your configuration, what CPAN server you want to get modules from, where it should find your FTP clients, and so on. This only happens once, then it just works.

The specific way that you need to configure Apache to use your newly-installed module will vary from one module to another, but many of them will look like the example given. The SetHandler perl-script directive tells Apache that the content will be handled by mod_perl, while the PerlHandler directive specifies what Perl module contains the actual handler code.

See Also

• http://cpan.org/

• http://search.cpan.org/author/RBOW/Apache-Perldoc/

• http://apachegallery.dk/

• http://dnszone.org/