mod_perl logo perl icon
no previous pagepage up: User's guidenext page: Overview of mod_perl 2.0

Getting Your Feet Wet with mod_perl






mod_perl Pocket Reference

mod_perl Pocket Reference

By Andrew Ford
Writing Apache Modules with Perl and C

Writing Apache Modules with Perl and C

By Lincoln Stein, Doug MacEachern
Embedding Perl in HTML with Mason

Embedding Perl in HTML with Mason

By Dave Rolsky, Ken Williams
mod_perl2 User's Guide

mod_perl2 User's Guide

By Stas Bekman, Jim Brandt
Practical mod_perl

Practical mod_perl

By Stas Bekman, Eric Cholet
The mod_perl Developer's Cookbook

The mod_perl Developer's Cookbook

By Geoffrey Young, Paul Lindner, Randy Kobes


Table of Contents

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.



TOP

Installation

If you are a Win32 user, please refer to the Win32 installation document.

First, download the mod_perl 2.0 source.

Before installing mod_perl, you need to check that you have the mod_perl 2.0 prerequisites installed. Apache and the right Perl version have to be built and installed before you can proceed with building mod_perl.

In this chapter we assume that httpd and all helper files were installed under $HOME/httpd/prefork, if your distribution doesn't install all the files under the same tree, please refer to the complete installation instructions.

Now, configure mod_perl:

  % tar -xvzf mod_perl-2.x.xx.tar.gz
  % cd modperl-2.0
  % perl Makefile.PL MP_APXS=$HOME/httpd/prefork/bin/apxs

where MP_APXS is the full path to the apxs executable, normally found in the same directory as the httpd executable, but could be put in a different path as well.

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.



TOP

Configuration

If you are a Win32 user, please refer to the Win32 configuration document.

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

  LoadModule perl_module modules/mod_perl.so

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 Apache2::compat

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



TOP

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:

  [Fri Jul 22 09:39:55 2005] [notice] Apache/2.0.55-dev (Unix)
  mod_ssl/2.0.55-dev OpenSSL/0.9.7e DAV/2 mod_perl/2.0.2-dev
  Perl/v5.8.7 configured -- resuming normal operations


TOP

Registry Scripts

To enable registry scripts add the following to httpd.conf:

  Alias /perl/ /home/httpd/httpd-2.0/perl/
  <Location /perl/>
      SetHandler perl-script
      PerlResponseHandler ModPerl::Registry
      PerlOptions +ParseHeaders
      Options +ExecCGI
      Order allow,deny
      Allow from all 
  </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.

For more information on the registry scripts refer to the ModPerl::Registry manpage. (XXX: one day there will a tutorial on registry, should port it from 1.0's docs).



TOP

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:

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

Save the code in the file MyApache2/Rocks.pm, somewhere where mod_perl can find it. For example let's put it under /home/httpd/httpd-2.0/perl/MyApache2/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);
  1;

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  MyApache2::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.



TOP

Troubleshooting

If after reading the complete installation and configuration chapters you are still having problems, take a look at the troubleshooting sections. If the problem persist, please report them using the following guidelines.



TOP

Maintainers

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



TOP

Authors

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






TOP
no previous pagepage up: User's guidenext page: Overview of mod_perl 2.0