FAQ
---
Patrick Kane <modus@enews.com> maintains the mod_perl FAQ available at:
http://chaos.dc.enews.com/mod_perl/

Apache/Perl API
---------------
Type 'perldoc Apache' for info on how to use the Perl-Apache API.
See the lib/ directory for example modules.
See the eg/ directory for example scripts.

mod_perl
-------------
To tell Apache you want mod_perl to handle your scripts add to
your srm.conf:

    AddHandler perl-script .fpl

Now, any file with the extension '.fpl' will be executed by mod_perl.
However, if your PerlHandler is Apache::Registry::handler, this module
will check to see if 'ExecCGI' is allowed in that directory before
executing it.
See the Apache::Registry module for details.
 
You may perl load modules via

    PerlModule Apache::Registry Apache::SSI SomeOther::Module

Optionally:

    PerlScript  /full/path/to/script_to_load_at_startup.pl

This script will be loaded when the server starts. See eg/mpf_eg.pl
for an example to start with.

In an access.conf <Directory /foo> or .htaccess you need:

    PerlHandler sub_routine_name

This is the name of the subroutine to call to handle each request. 
e.g. 
in the PerlScript mpf_eg.pl this is "main::handler".
in the PerlModule Apache::Registry this is "Apache::Registry::handler".

The recommended configuration is as follows:

#srm.conf
Alias /perl/  /real/path/to/perl-scripts/
PerlModule Apache::Registry

#access.conf 
<Location /perl>
SetHandler perl-script
PerlHandler Apache::Registry::handler
Options ExecCGI
</Location>

By default, mod_perl does not send any headers by itself, however, you
may wish to change this:

    PerlSendHeader On	

By default, mod_perl does not setup %ENV, you may wish to change this:

    PerlSetupEnv On

With the recommended configuration, these options and Perl linked with sfio 
(see INSTALL), scripts running under Apache::Registry will look just like 
"normal" CGI scripts.  See eg/perlio.pl as an example.

There are several stages of a request where the Apache API allows a module
to step and do something.  The Apache documentation will tell you all about
those stages and what your modules can do.  
By default, these hooks are disabled at compile time, to change the defaults,
simply edit mod_perl's Makefile (src/modules/perl/Makefile).  
The following configuration directives take one argument, which is the name
of the subroutine to call. 

    PerlTransHandler    
    PerlAuthenHandler
    PerlAuthzHandler
    PerlAccessHandler
    PerlTypeHandler
    PerlFixupHandler
    PerlLogHandler

WARNINGS
--------

Your scripts *cannot* be in a ScriptAlias(ed) (which is usually /cgi-bin) directory.

Your scripts *will not* run from the command line (yet).

Support
-------

For comments, questions, bug-reports, announcements, etc., send mail
to majordomo@listproc.itribe.net with the string "subscribe modperl"
in the body.  


