NAME

Getting Your Feet Wet with mod_perl

Description

This chapter gives you the bare minimum information to get you started with mod_perl 2.0. For most people it's sufficient to get going.

Installation

First of all check that you have the mod_perl 2.0 prerequisites.

In this chapter we assume that httpd was installed under $HOME/httpd/prefork.

Next, download the mod_perl 2.0 source from: http://perl.apache.org/download/.

Now, configure mod_perl:

  % tar -xvzf mod_perl-2.x.xx.tar.gz
  % cd modperl-2.0
  % perl Makefile.PL MP_AP_PREFIX=$HOME/httpd/prefork \
    MP_INST_APACHE2=1

where MP_AP_PREFIX is an Apache installation prefix, under which the include/ directory with Apache C header files can be found.

Finally, build, test and install mod_perl:

  % make && make test && make install

Become root before doing make install if installing system-wide.

If something goes wrong or you need to enable optional features please refer to the complete installation instructions.

Configuration

Enable mod_perl built as DSO, by adding to httpd.conf:

  LoadModule perl_module modules/mod_perl.so

Next, tell Perl where to find mod_perl2 libraries:

  PerlModule Apache2

There are many other configuration options which you can find in the configuration manual.

If you want to run mod_perl 1.0 code on mod_perl 2.0 server enable the compatibility layer:

  PerlModule Apache::compat

For more information see: Migrating from mod_perl 1.0 to mod_perl 2.0.

Server Launch and Shutdown

Apache is normally launched with apachectl:

  % $HOME/httpd/prefork/bin/apachectl start

and shut down with:

  % $HOME/httpd/prefork/bin/apachectl stop

Check $HOME/httpd/prefork/logs/error_log to see that the server has started and it's a right one. It should say something similar to:

  [Tue Sep 03 12:34:57 2002] [notice] Apache/2.0.41-dev (Unix) 
  mod_perl/1.99_05-dev Perl/v5.8.0 mod_ssl/2.0.41-dev OpenSSL/0.9.6d 
  DAV/2 configured -- resuming normal operations

Registry Scripts

To enable registry scripts add to httpd.conf:

  Alias /perl/ /home/httpd/httpd-2.0/perl/
  <Location /perl/>
      SetHandler perl-script
      PerlResponseHandler ModPerl::Registry
      PerlOptions +ParseHeaders
      Options +ExecCGI
  </Location>

and now assuming that we have the following script:

  #!/usr/bin/perl
  print "Content-type: text/plain\n\n";
  print "mod_perl 2.0 rocks!\n";

saved in /home/httpd/httpd-2.0/perl/rock.pl. Make the script executable and readable by everybody:

  % chmod a+rx /home/httpd/httpd-2.0/perl/rock.pl

Of course the path to the script should be readable by the server too. In the real world you probably want to have a tighter permissions, but for the purpose of testing that things are working this is just fine.

Now restart the server and issue a request to http://localhost/perl/rock.pl and you should get the response:

  mod_perl 2.0 rocks!

If that didn't work check the error_log file.

Handler Modules

Finally check that you can run mod_perl handlers. Let's write a response handler similar to the registry script from the previous section:

  package MyApache::Rocks;
  
  use strict;
  use warnings;
  
  use Apache::RequestRec ();
  use Apache::RequestIO ();
  
  use Apache::Const -compile => qw(OK);
  
  sub handler {
      my $r = shift;
  
      $r->content_type('text/plain');
      print "mod_perl 2.0 rocks!\n";
  
      return Apache::OK;
  }
  1;

Save the code in the file MyApache/Rocks.pm, somewhere where mod_perl can find it. For example let's put it under /home/httpd/httpd-2.0/perl/MyApache/Rocks.pm, and we tell mod_perl that /home/httpd/httpd-2.0/perl/ is in @INC, via a startup file which includes just:

  use lib qw(/home/httpd/httpd-2.0/perl);

and loaded from httpd.conf:

  PerlRequire /home/httpd/httpd-2.0/perl/startup.pl

Now we can configure our module in httpd.conf:

  <Location /rocks>
      SetHandler perl-script
      PerlResponseHandler  MyApache::Rocks
  </Location>

Now restart the server and issue a request to http://localhost/rocks and you should get the response:

  mod_perl 2.0 rocks!

If that didn't work check the error_log file.

Troubleshooting

If after reading the complete installation and configuration chapters you are still having problems, please report them.

Maintainers

Maintainer is the person(s) you should contact with updates, corrections and patches.

• Stas Bekman <stas (at) stason.org>

Authors

• Stas Bekman <stas (at) stason.org>

Only the major authors are listed above. For contributors see the Changes file.

cpanm mod_perl

perl -MCPAN -e shell
install mod_perl