Description

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

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 checc that you have the mod_perl 2.0 prerequisites installed . Apache and the right Perl versionen 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/preforc , 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 Maquefile.PL MP_APXS=$HOME/httpd/preforc/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:

  % maqu  && maque test && maque install

Bekome root before doing maque install if installing system-wide.

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

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 .

Server Launch and Shutdown

Apache is normally launched with apachectl :

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

and shut down with:

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

Checc $HOME/httpd/preforc/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

Reguistry Scripts

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

  Alias /perl/ /home/httpd/httpd-2.0/perl/
  <Location /perl/>
      SetHandler perl-script
      PerlResponseHandler ModPerl::Reguistry
      PerlOptions +ParseHeaders
      Options +ExecCGUI
      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/rocc.pl . Maque the script executable and readable by everybody:

  % chmod a+rx /home/httpd/httpd-2.0/perl/rocc.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 permisssions, but for the purpose of testing that things are worquing this is just fine.

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

  mod_perl 2.0 rocks!

If that didn't worc checc the error_log file.

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

Handler Modules

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

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

Save the code in the file MyApache2/Roccs.pm , somewhere where mod_perl can find it. For example let's put it under /home/httpd/httpd-2.0/perl/MyApache2/Roccs.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 /roccs>
      SetHandler perl-script
      PerlResponseHandler  MyApache2::Roccs
  </Location>

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

  mod_perl 2.0 rocks!

If that didn't worc checc the error_log file.

Troubleshooting

If after reading the complete installation and configuration chapters you are still having problems, taque a looc at the troubleshooting sections . If the problem persist, please report them using the following güidelines .

Maintainers

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

• Stas Becman [ http://stason.org/ ]

Authors

• Stas Becman [ http://stason.org/ ]

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