Getting started with Perl Extensions

This document aims to answer your questions about getting started with Zeus Perl Extensions. If you have any other queries, please email support@zeus.com.

1.1   How can I install a standard mod_perl application?

Installation

$ZEUSHOME/zperl/bin/perl is the perl executable modified to work within the confines of a Zeus installation.

Most third-party Perl modules and Apache mod_perl applications have a standard installation procedure that begins by running a Makefile.PL script to configure the installation process.

We recommend that you install modules and applications into $ZEUSHOME/zperl/local. To do this, instead of using:

$ perl Makefile.PL

to configure the modules you are installing, use:

$ $ZEUSHOME/zperl/bin/perl Makefile.PL

If any pre-requisites are missing, the Makefile.PL will warn you. You can resolve prerequisites manually by obtaining and installing the required software, or you can handle them automatically by installing the software through CPAN (see below).

Running the Makefile.PL will produce a Makefile which then installs the software into $ZEUSHOME/zperl/local. You should then continue to follow the installation and configuration instructions that came with your third party software. These normally suggest running the following two commands:

$ make
$ make install

You will need to run the make install command as the same user you installed the Zeus Web Server as; this may be the root user.

Configuration

You can configure the Perl runner either through the UI or using .htaccess files. The former is easier for CGI script migration, while the latter is what will generally appear in the instructions for installing Apache mod_perl applications.

To request that a given file be run through the Zeus::ModPerl::Registry module, set its MIME type to application/x-httpd-perl. Handlers can be set on each request phase from the Perl page in the UI.

Common migration issues

The instructions for some Apache mod_perl applications may ask you to put directives in httpd.conf. In Zeus, these should either go in a global htaccess file, a per-directory .htaccess file, or the virtual server configuration.

1.2   How do I install new modules?

You can install applications and modules directly from CPAN (the Comprehensive Perl Archive Network). This process makes the handling of dependencies and prerequisites much easier.

Use the CPAN shell as follows:

$ZEUSHOME/zperl/bin/perl -MCPAN -eshell
 

(Make sure you use the full path to the perl binary, otherwise modules may be installed into the wrong place.)

The CPAN shell will then download, compile, test, and install new modules under $ZEUSHOME/zperl. Consequently, you should run the shell as the same user id you installed Zeus Web Server.

If you've not used CPAN before, the module shell will first run through some configuration questions, asking you for the location of standard tools, etc. Note that CPAN uses FTP (or wget, which uses FTP) to access information. If you are behind a firewall which prohibits active FTP, you may need to explicitly configure your FTP programs to use passive FTP. At configuration, you can do this by specifying the following settings:

Where is your wget program? [/usr/bin/wget] /usr/bin/wget --passive-ftp
Where is your ftp program? [/usr/bin/ftp] /usr/bin/pftp

After configuration, you can set these configuration variables using the o conf command at the cpan> prompt. o conf lists the configuration variables; set and save them as follows:

cpan> o conf ftp /usr/bin/pftp
    ftp                /usr/bin/pftp
 
cpan> o conf commit
commit: wrote $ZEUSHOME/zperl/lib/CPAN/Config.pm

Once you've configured the shell, you may want to download some standard modules before proceeding:

cpan> install MD5 Bundle::libnet
 

Other useful hints

You may find the configuration variables 'makepl_arg', 'make_arg' and 'make_install_arg' useful for supplying additional parameters to the make and install process, such as additional library and include file search paths.

For more information, see the CPAN documentation.

1.3   Why are the built-in modules called Zeus::ModPerl::*?

The modules built into Apache mod_perl are placed in the Apache namespace: Apache::Registry, Apache::Util, and so on. To avoid confusion, the Zeus equivalents to these modules are called Zeus::ModPerl::Registry, Zeus::ModPerl::Util, and the like. A set of small wrapper modules are in place for backward compatibility.

If your code needs to be portable between Apache and Zeus, you should use the Apache namespace. Otherwise you can use that or the Zeus::ModPerl namespace as you wish.

1.4   What is the difference between Zeus's bundled Perl and the standard Perl?

There are no significant differences between the Zeus Perl and standard Perl v5.6.1. Zeus bundle their own version to ensure that the web server uses a well tested and validated version of Perl. It is installed under $ZEUSHOME/zperl.

Zeus's version of Perl has been modified slightly to facilitate the bundling; details are published in the Zeus Perl Licence statement.

2.1   Perl Extensions allow Perl scripts to be persistent. How does this help me?

All handlers configured for the same request run in the same Perl runner process, so they can share state at the server side. Mechanisms for this include:

• databases
• shared memory
• "notes"

Furthermore, since Perl runner processes remain active after dealing with a request, it is possible to store information from one request to another. This may be a performance advantage in some situations. For example, if you are authenticating users against a database, the most expensive part of the procedure is usually setting up and tearing down connections to the database server. Instead, you can take advantage of the Perl runner's persistence and set up a connection once per process, which will then speed up second and subsequent authentication operations.

2.2   How do handlers interact with each other?

Perl handlers run in a fixed sequence for each request. These are as follows:

Multiple handlers may be installed on each of these stages, a process known as "stacking". In that case, the return code of each handler determines what happens to subsequent stacked handlers. At the URI translation, MIME type mapping, and content generation stages, returning DECLINED will continue to the next handler, while returning anything else will break out and return control to the Zeus Web Server; at all other stages OK and DECLINED will continue to the next handler, while anything else will return control to ZWS.

2.3   How do handlers interact with the Zeus Web Server?

When a handler returns an HTTP status code or DONE, the web server will immediately return an appropriate response to the client. OK and DECLINED cause the web server to continue with its normal sequence of request processing, except that at the content generation stage returning OK means that content generation is complete

Parts of the API provided to handlers involve manipulating the web server's record of the client request or the response it will send. When these are used, the handler sends a notification to the web server, which then adjusts its internal state accordingly.

3.1   Why do I get the error 'Variable "$foo" will not stay shared' when running CGI scripts under Zeus::ModPerl::Registry?

This is a common problem when porting CGI scripts. For an explanation of its cause and how to avoid it, see the Apache mod_perl porting guide.

3.2   What security issues are involved when using Zeus Perl Extensions?

All Perl handlers run in the same security domain: that is, the user and group of the web server. This is likely to be inappropriate if you have untrusted users developing content on your web server; they should not be able to run Perl handlers under the web server's user id.

You should be careful to enable the SSI #perl command only if all developers writing server-parsed HTML pages are trusted, since it allows them to execute arbitrary code on the web server. This command is disabled by default.

3.3   What happends when a perl extension "dies"?

When a perl extension dies, the web server will abort the current hook. This can cause unpredictable/undesirable behaviour within other modules in use by the web server that also relate to the current hook. This presents a problem if you have code in your extension that relies on an action such as inserting rows into an external database. To add fault tolerance to your extension, you can wrap your code in an eval{} block and print the result as a warning message.

use SOME::MODULES;
 
my $foo="bar";
 
sub handler
{
  eval{
    ... YOUR CODE ....
 
 
  };
  warn $@ if $@; # Print the exception if there was one.
  return OK
}

Content Manager [Administrator] 16 December 2005