The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Real World Scenarios

Description

This chapter provides step by step installation guide for the various setups discussed in Choosing the Right Strategy.

Assumptions

I will assume for this section that you are familiar with plain (not mod_perl enabled) Apache, its compilation and configuration. In all configuration and code examples I will use localhost or www.example.com as a hostname. For the testing on a local machine, localhost would be just fine. If you are using the real name of your machine make sure to replace www.example.com with the name of your machine.

Standalone mod_perl Enabled Apache Server

Installation in 10 lines

The Installation is very simple. This example shows installation on the Linux operating system.

  % cd /usr/src
  % lwp-download http://www.apache.org/dist/apache_x.x.x.tar.gz
  % lwp-download http://perl.apache.org/dist/mod_perl-x.xx.tar.gz
  % tar xzvf apache_x.x.x.tar.gz
  % tar xzvf mod_perl-x.xx.tar.gz
  % cd mod_perl-x.xx
  % perl Makefile.PL APACHE_SRC=../apache_x.x.x/src \
    DO_HTTPD=1 USE_APACI=1 EVERYTHING=1
  % make && make test && make install
  % cd ../apache_x.x.x
  % make install

That's all!

Notes: Replace x.xx and x.x.x with the real version numbers of mod_perl and Apache respectively. The z flag tells Gnu tar to uncompress the archive as well as extract the files. You might need superuser permissions to do the make install steps.

Installation in 10 paragraphs

If you have the lwp-download utility installed, you can use it to download the sources of both packages:

  % lwp-download http://www.apache.org/dist/apache_x.x.x.tar.gz
  % lwp-download http://perl.apache.org/dist/mod_perl-x.xx.tar.gz

lwp-download is a part of the LWP module (from the libwww package), and you will need to have it installed in order for mod_perl's make test step to pass.

Extract both sources. Usually I open all the sources in /usr/src/, but your mileage may vary. So move the sources and chdir to the directory that you want to put the sources in. If you have a non-GNU tar utility it will be unable to decompress so you will have to unpack in two steps: first uncompress the packages with:

  gzip -d apache_x.x.x.tar.gz
  gzip -d mod_perl-x.xx.tar.gz

then un-tar them with:

  tar xvf apache_x.x.x.tar 
  tar xvf mod_perl-x.xx.tar

You can probably use gunzip instead of gzip -d if you prefer.

  % cd /usr/src
  % tar xzvf apache_x.x.x.tar.gz
  % tar xzvf mod_perl-x.xx.tar.gz

chdir to the mod_perl source directory:

  % cd mod_perl-x.xx

Now build the Makefile. For your first installation and most basic work the parameters in the example below are the only ones you will need. APACHE_SRC tells the Makefile.PL where to find the Apache src directory. If you have followed my suggestion and have extracted both sources under the directory /usr/src, then issue the command:

  % perl Makefile.PL APACHE_SRC=../apache_x.x.x/src \
    DO_HTTPD=1 USE_APACI=1 EVERYTHING=1

There are many additional optional parameters. You can find some of them later in this section and in the Server Configuration section.

While running perl Makefile.PL ... the process will check for prerequisites and tell you if something is missing. If you are missing some of the perl packages or other software, you will have to install them before you proceed.

Next make the project. The command make builds the mod_perl extension and also calls make in the Apache source directory to build httpd. Then we run the test suite, and finally install the mod_perl modules in their proper places.

  % make && make test && make install

Note that if make fails, neither make test nor make install will be executed. If make test fails, make install will be not executed.

Now change to the Apache source directory and run make install. This will install Apache's headers, default configuration files, build the Apache directory tree and put httpd in it.

  % cd ../apache_x.x.x
  % make install

When you execute the above command, the Apache installation process will tell you how to start a freshly built webserver (you need to know the path of apachectl, more about that later) and where to find the configuration files. Write down both, since you will need this information very soon. On my machine the two important paths are:

  /usr/local/apache/bin/apachectl
  /usr/local/apache/conf/httpd.conf

Now the build and installation processes are complete.

Configuration

First, a simple configuration. Configure Apache as you usually would (set Port, User, Group, ErrorLog, other file paths etc).

Start the server and make sure it works, then shut it down. The apachectl utility can be used to start and stop the server:

  % /usr/local/apache/bin/apachectl start
  % /usr/local/apache/bin/apachectl stop

Now we will configure Apache to run perl CGI scripts under the Apache::Registry handler.

You can put configuration directives in a separate file and tell httpd.conf to include it, but for now we will simply add them to the main configuration file. We will add the mod_perl configuration directives to the end of httpd.conf. In fact you can place them anywhere in the file, but they are easier to find at the end.

For the moment we will assume that you will put all the scripts which you want to be executed by the mod_perl enabled server under the directory /home/httpd/perl. We will alias this directory to the URI /perl

Add the following configuration directives to httpd.conf:

  Alias /perl/ /home/httpd/perl/
  
  PerlModule Apache::Registry
  <Location /perl>
    SetHandler perl-script
    PerlHandler Apache::Registry
    Options ExecCGI
    PerlSendHeader On
    allow from all
  </Location>

Now create a four-line test script in /home/httpd/perl/:

  test.pl
  -------
  #!/usr/bin/perl -w
  use strict;
  print "Content-type: text/html\r\n\r\n";
  print "It worked!!!\n";

Note that the server is probably running as a user with a restricted set of privileges, perhaps as user nobody or www. Look for the User directive in httpd.conf to find the userid of the server.

Make sure that you have read and execute permissions for test.pl.

  % chmod u+rx /home/httpd/perl/test.pl

Test that the script works from the command line, by executing it:

  % /home/httpd/perl/test.pl

You should see:

  Content-type: text/html
  
  It worked!!!

Assuming that the server's userid is nobody, make the script owned by this user. We already made it executable and readable by user.

  % chown nobody /home/httpd/perl/test.pl

Now it is time to test that mod_perl enabled Apache can execute the script.

Start the server ('apachectl start'). Check in logs/error_log to see that the server has indeed started--verify the correct date and time of the log entry.

To get Apache to execute the script we simply fetch its URI. Assuming that your httpd.conf has been configured with the directive Port 80, start your favorite browser and fetch the following URI:

  http://www.example.com/perl/test.pl

If you have the loop-back device (127.0.0.1) configured, you can use the URI:

  http://localhost/perl/test.pl

In either case, you should see:

  It worked!!!

If your server is listening on a port other than 80, for example 8000, then fetch the URI:

  http://www.example.com:8000/perl/test.pl

or whatever is appropriate.

If something went wrong, go through the installation process again, and make sure you didn't make a mistake. If that doesn't help, read the INSTALL pod document (perlpod INSTALL) in the mod_perl distribution directory.

Now that your mod_perl server is working, copy some of your Perl CGI scripts into the directory /home/httpd/perl/ or below it.

If your programming techniques are good, chances are that your scripts will work with no modifications at all. With the mod_perl enabled server you will see them working very much faster.

If your programming techniques are sloppy, some of your scripts will not work and they may exhibit strange behaviour. Depending on the degree of sloppiness they may need anything from minor tweaking to a major rewrite to make them work properly. (See Sometimes My Script Works, Sometimes It Does Not )

The above setup is very basic, but as with Perl, you can start to benefit from mod_perl from the very first moment you try it. As you become more familiar with mod_perl you will want to start writing Apache handlers and make more use of its power.

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.