/ 
mod_perl-1.30
River stage three • 156 direct dependents • 184 total dependents
/ Mod_perl_faq

NAME

Mod_perl_faq - frequently asked questions about mod_perl ($Date: 2002-03-24 18:57:59 -0800 (Sun, 24 Mar 2002) $)

DESCRIPTION

Mod_perl allows an Apache Web Server to directly execute perl code. This document is designed to answer questions that arise when designing new applications, and converting existing applications, to run in the mod_perl environment.

QUESTIONS & ANSWERS

What is mod_perl?

The Apache/Perl integration project brings together the full power of the Perl programming language and the Apache HTTP server. This is achieved by linking the Perl runtime library into the server and providing an object-oriented Perl interface to the server's C language API.

Mod_perl is a bundle of software. One part of the bundle is designed to be compiled and linked together with Apache and Perl. The remainder is perl code that provides the object-oriented interface to the "perl-enabled" web server.

The primary advantages of mod_perl are power and speed. You have full access to the inner-workings of the web server and can intervene at any stage of request-processing. This allows for customized processing of (to name just a few of the phases) URI->filename translation, authentication, response generation and logging. There is very little run-time overhead. In particular, it is not necessary to start a separate process, as is often done with web-server extensions. The most wide-spread such extension mechanism, the Common Gateway Interface (CGI), can be replaced entirely with perl-code that handles the response generation phase of request processing. Mod_perl includes a general purpose module for this purpose (Apache::Registry) that can transparently run existing perl CGI scripts.

Where can I get mod_perl?

Mod_perl can be found at http://www.perl.com/CPAN/modules/by-module/Apache/

What else do I need?

Perl

http://www.perl.com/CPAN/src/latest.tar.gz

Win32 users note: mod_perl compiles cleanly and works with ActivePerl (build 626, June 2001). In http://www.mail-archive.com/modperl@apache.org/msg11513.html Randy Kobes wrote:

A ppd for mod_perl, suitable for use with ActivePerls 
based on Perl-5.6.0, is now available. Installation is as ppm
install

http://theoryx5.uwinnipeg.ca/ppmpackages/mod_perl.ppd

or in ftp://theoryx5.uwinnipeg.ca/pub/ppmpackages/.
A post-install script will subsequently be run which
will download and install the required ApacheModulePerl.dll;
this should be placed in your Apache modules directory.
If for some reason the script fails, this dll can be
obtained from http://theoryx5.uwinnipeg.ca/ppmpackages/.
Also available in this directory is a sample Apache
httpd.conf suitable to test mod_perl on Win32.
Apache

http://www.apache.org/dist/

How do I install it?

Configuring and installing apache with mod_perl is a complex process, so it is really not a good idea to attempt to do it manually. If you are used to configuring third-party modules into Apache using the apache configuration process, please realize that running mod_perl's Makefile.PL with the right parameters does this for you.

Read the INSTALL* files in the top-level mod_perl distribution directory and then choose one of the INSTALL.simple* recipes that is close to your requirements, as a starting point. When you succeed in compiling and linking an httpd, a quick way to check that everything is configured according to plan is to run it with the -l (list compiled-in modules) and -V (show paths) flags.

What documentation should I read?

The mod_perl documentation in mod_perl.pod. After you have installed mod_perl you can read it with the command: perldoc mod_perl.

The complete list of available documentation can be found at the end of mod_perl's README file.

If you are using mod_perl to extend the server functionality, you will need to read perldoc Apache and the Apache API notes, which can be found in apache_x.x.x/htdocs/manual/misc/API.html.

Existing (perl-) CGI scripts should run as-is under mod_perl. There are a number of reasons why they may need to be adjusted, and these are discussed later in this FAQ. If you are developing a new CGI script it is probably best to use CGI.pm. It is part of the standard perl distribution and its documentation can be read with the command: perldoc CGI.

How do I run CGI scripts under mod_perl?

Refer to mod_perl_cgi for tips on writing and converting CGI scripts for mod_perl.

How do I access the Apache API from mod_perl?

Interfacing with Apache is discussed in mod_perl_api.

How secure are mod_perl scripts?

Because mod_perl runs within an httpd child process, it runs with the user-id and group-id specified in the httpd.conf file. This user/group should have the lowest possible privileges. It should only have access to world readable files. Even so, careless scripts can give away information. You would not want your /etc/passwd file to be readable over the net, for instance.

Different mod_perl scripts run successively using the same Perl interpreter instance. So, in addition to classical CGI mischiefs, a malicious mod_perl script can redefine any Perl object and change the behavior of other mod_perl scripts.

If you turn on tainting checks, perl can help you to avoid the pitfalls of using data received from the net. Setting the -T switch on the first line of the script is not sufficient to enable tainting checks under mod_perl. You have to include the directive PerlTaintCheck On in the httpd.conf file.

What if my script needs higher privileges?

You will have to start a new process that runs under a suitable user-id (or group-id). If all requests handled by the script will need the higher privileges, you might as well write it as a suid CGI script. Read the documentation about suEXEC in the Apache documentation.

Alternatively, pre-process the request with mod_perl and fork a suid helper process to handle the privileged part of the task.

Why is httpd using so much memory?

Read the section on "Memory Consumption" in the mod_perl.pod.

Make sure that your scripts are not leaking memory. Global variables stay around indefinitely, lexical variables (declared with my()) are destroyed when they go out of scope, provided there are no references to them from outside of that scope. The Apache::Leak module can warn about some types of memory leak.

To get information about the modules that have been loaded and their symbol-tables, use the Apache::Status module. It is enabled by adding these lines to the httpd configuration file.

<Location /perl-status>
SetHandler  perl-script
PerlHandler Apache::Status
</Location>

Then look at the URL http://www.your.host/perl-status

Joel Wagner reports that calling an undefined subroutine in a module can cause a tight loop that consumes all memory. Here is a way to catch such errors. Define an autoload subroutine

sub UNIVERSAL::AUTOLOAD {
	  my $class = shift;
	  warn "$class can't `$UNIVERSAL::AUTOLOAD'!\n";
}

It will produce a nice error in error_log, giving the line number of the call and the name of the undefined subroutine.

Do I have to restart the server when I change my Perl code?

Apache::Registry checks the timestamp of scripts that it has loaded and reloads them if they change. Other handlers and library modules are not automatically reloaded by mod_perl, but you can use the Apache::StatINC module to do this for you.

So how do I use mod_perl in conjunction with ErrorDocument?

Andreas Koenig writes:

  • Set up your testing engine:

    LWP comes with debugging capabilities that are sometimes better than your browser, sometimes your browser is the better testing device. Make sure you can call lwp-request from the command line and have your browser ready before you start. I find the -x switch (extended debugging) and the -d switch (do not display content) most useful.

  • Test your server with

    lwp-request -xd http://your.server/test/file.not_there

    Carefully examine if the status is 404 and if the headers look good.

    If you try 'lwp-request -es', the HTML output will not be the one you are sending, instead lwp-request will send its own cooked HTML text (as of version libwww-perl-5.09). Check the real text either with the -x switch or with telnet or your browser.

  • Set up your Errordocument configuration in the testing area. I have this in my .htaccess file:

    ErrorDocument 404 /perl/errors/err404-01

    The /perl/ directory is configured to

    <Location /perl>
SetHandler perl-script
PerlHandler Apache::Registry::handler
Options ExecCGI
</Location>

    I have no PerlSendHeader and no PerlNewSendHeader directive in any configuration file.

  • Repeat step 2 (Test your server)

  • Write your error handler in mod_perl. You have to be prepared that you have to tell both apache *and* the browser the right thing. Basically you have to tell the browser what the error is, but you have to pretend to apache that everything was OK. If you tell apache the error condition, it will handle the situation on its own and add some unwanted stuff to the output that goes to the browser.

    The following works fine for me:

    my $r = Apache->request;
$r->content_type('text/html; charset=ISO-8859-1');
$r->send_http_header;
$r->status(200);
...send other HTML stuff...

    At the time of the send_http_header we have an error condition of type 404--this is what gets sent to the browser. After that I set status to 200 to silence the apache engine.

    I was not successful in trying to do the same with CGI.pm, but I didn't try very hard.

  • Repeat step 2 (Test your server)

  • The above is tested with mod_perl/0.98 and 0.99

  • Open questions I could not find documentation for (except RTFS): what exactly is PerlSendHeaders and PerlNewSendHeaders. What is the default setting for those? How do these cooperate with CGI.pm, Apache.pm, Apache::Registry?

How can I reference private library modules?

If you put your modules into one of the directories on perl's search path (the @INC array), they will be found automatically. Traditionally, site-specific modules go in /usr/lib/perl5/site_perl/. Newer versions of mod_perl add the directory $ServerRoot/lib/perl to @INC on startup so that is a good place for modules that are only used by mod_perl scripts.

If you need to load files from other non-standard locations, you can add directories to the @INC array with a 'use lib' statement in a startup script. See mod_perl_tuning for an example.

How can I pass arguments to a SSI script?

Following the documentation, I have put the following in the html file:

<!--#perl sub="Apache::Include" arg="/perl/ssi.pl" -->

I want to send an argument to the ssi.pl script. How?

It won't work with Apache::Include. Instead of a script, define a subroutine that's pulled in with PerlRequire or PerlModule, like so:

sub My::ssi {
   my($r, $one, $two, $three) = @_;
   ...
}

In the html file:

<!--#perl sub="My::ssi" arg="one" arg="two" arg="three" -->

Why is image-file loading so slow when testing with httpd -X ?

If you use Netscape while your server is running in single-process mode, the "KeepAlive" feature gets in the way. Netscape tries to open multiple connections and keep them open. Because there is only one server process listening, each connection has to time-out before the next succeeds. Turn off KeepAlive in httpd.conf to avoid this effect.

What can cause a subroutine or variable to be sporadically undefined?

If you sometimes see error messages like this:

[Thu Sep 11 11:03:06 1997] Undefined subroutine
&Apache::ROOT::perl::script1::sub_foo called at
/some/path/perl/script2 line 42.

despite the fact that script2 normally works just fine, it looks like you have a namespace problem in a library file. If sub_foo is located in a file that is pulled in by 'require' and both script1 and script2 require it, you need to be sure that the file containing sub_foo sets a package name. Otherwise, sub_foo gets defined in the namespace that is active the first time it is required, and the next require is a no-op because that file is already in %INC. The same problem can happen with global variables.

The solution is simple, set up your require'd file something along these lines:

package SomeName;

sub sub_foo {...}

Now, have scripts call SomeName::sub_foo() instead of sub_foo().

Is there a bug that causes httpd processes to crash?

You may see httpd child processes crashing with segmentation fault when you restart the server with a HUP or USR1 signal. This is not a bug in mod_perl. If you have 'PerlFreshRestart On' in the configuration, the main httpd daemon reloads all the perl modules that it has preloaded when it gets a HUP or USR1 signal. Unfortunately, not all perl modules are robust enough to survive this, for them, unusual situation.

What could be causing sporadic errors "in cleanup"?

Some people have seen error messages such as this:

[Fri Sep 26 10:50:08 1997]      (in cleanup) no dbproc key in hash
at /usr/lib/perl5/site_perl/Apache/Registry.pm line 119.

Doug writes:

"I have yet to figure out why, but there have been a few arbitrary cases where Perl (in mod_perl) _insists_ on finding and/or calling a DESTROY method for an object. Defining an empty sub DESTROY has been the bandaid for these few cases."

If the specific error message gives you a hint about which object is causing difficulty, put the sub DESTROY { } in the module that defines that object class.

How can I test that my script is running under mod_perl?

There are 2 environment variables you can test.

exists $ENV{"MOD_PERL"}   # if running under mod_perl

$ENV{"GATEWAY_INTERFACE"} eq "CGI-Perl/1.1"

The MOD_PERL variable gets set immediately when the perl interpreter starts up, whereas GATEWAY_INTERFACE may not be set yet when BEGIN blocks are being processed.

Why don't "format" and "write" work under mod_perl?

The Perl tie'd filehandle interface is not complete, format/write is one of the missing pieces. If you configure Perl with sfio, write() should work just fine.

Where can I get help that I did not find in here?

There is a mailing-list dedicated to mod_perl. It is archived at http://outside.organic.com/mail-archives/modperl/ and at http://forum.swarthmore.edu/epigone/modperl (which has a search engine) and also at http://www.progressive-comp.com/Lists/?l=apache-modperl&r=1#apache-modperl (threaded and indexed).

You can subscribe to the list by sending a mail to modperl-subscribe@perl.apache.org and responding to the confirmation message that you will receive. To unsubscribe, send mail to modperl-unsubscribe@perl.apache.org from the address you are subscribed at and reply to the confirmation message. Look at the full headers of mails that you receive from the list to see the address that they were sent to. The address is embedded in the Return-Path header (you will probably have to activate a "show full headers" function in your mail reader to see it). To find the address, delete modperl-return-nnnn- from the front of the return path and @perl.apache.org from the back, then replace the = with @.

Remember: the mailing list is for questions about and discussion of mod_perl. Quetions about perl programming in general should be asked in the newsgroup comp.lang.perl.misc, after consulting the fine perl faqs. There is a whole set of newsgroups dedicated to web authoring, web servers etc.: comp.infosystems.www.*

The mod_perl homepage http://perl.apache.org/ has links to other mod_perl resources.

The pod source of this FAQ is available at http://www.ping.de/~fdc/mod_perl/mod_perl_faq.tar.gz

Where do I send suggestions and corrections concerning this FAQ?

mailto:fdc@cliwe.ping.de