=head1 NAME
mod_perl 2.0 Server Configuration
=head1 Description
This chapter provides an in-depth mod_perl 2.0 configuration details.
=head1 mod_perl configuration directives
Similar to mod_perl 1.0, in order to use mod_perl 2.0 a few
configuration settings should be added to I. They are
quite similar to 1.0 settings but some directives were renamed and new
directives were added.
=head1 Enabling mod_perl
To enable mod_perl built as DSO add to I:
LoadModule perl_module modules/mod_perl.so
This setting specifies the location of the mod_perl module relative to
the C setting, therefore you should put it somewhere after
C is specified.
If mod_perl has been statically linked it's automatically enabled.
For Win32 specific details, see the documentation on
L.
Remember that you can't use mod_perl until you have configured Apache
to use it. You need to configure L or
L.
=head1 Server Configuration Directives
=head2 CPerlE> Sections
With CPerlE>...C/PerlE> sections, it is possible
to configure your server entirely in Perl.
Please refer to the
L manpage
for more information.
META: a dedicated chapter with examples?
See also: L.
=head2 C<=pod>, C<=over> and C<=cut>
It's known that anything written between tokens C<=pod> and C<=cut> is
ignored by the Perl parser. mod_perl allows you to use the same
technique to make Apache ignore things in F (similar to #
comments). With an exception to C<=over apache> and C<=over httpd>
sections which are visible to Apache.
For example the following configuration:
#file: httpd.conf
=pod
PerlSetVar A 1
=over apache
PerlSetVar B 2
=back
PerlSetVar C 3
=cut
PerlSetVar D 4
Apache will see:
PerlSetVar B 2
PerlSetVar D 4
but not:
PerlSetVar A 1
PerlSetVar C 3
C<=over httpd> is just an alias to C<=over apache>. Remember that
C<=over> requires a corresponding C<=back>.
=head2 C
C is useful if you need to pass in multiple values into the
same variable emulating arrays and hashes. For example:
PerlAddVar foo bar
PerlAddVar foo bar1
PerlAddVar foo bar2
You would retrieve these values with:
my @foos = $r->dir_config('foo');
This would fill the I<@foos> array with 'bar', 'bar1', and 'bar2'.
To pass in hashed values you need to ensure that you use an even number
of directives per key. For example:
PerlAddVar foo key1
PerlAddVar foo value1
PerlAddVar foo key2
PerlAddVar foo value2
You can then retrieve these values with:
my %foos = $r->dir_config('foo');
Where I<%foos> will have a structure like:
%foos = (
key1 => 'value1',
key2 => 'value2',
);
See also: L.
=head2 C
C does the same thing as
C>, but it is
executed as soon as it is encountered, i.e. during the configuration
phase.
You should be using this directive to load only files that introduce
new configuration directives, used later in the configuration
file. For any other purposes (like preloading modules) use
C>.
One of the reasons for avoding using the C
directive, is that the C stream is not available during the
restart phase, therefore the errors will be not reported. It is not a
bug in mod_perl but an Apache limitation. Use
C> if you can, and
there you have the C stream sent to the error_log file (by
default).
See also: L.
=head2 C
The C directive is similar to
C>, in a sense that it loads a
module. The difference is that it's used to triggers L. This can
be useful for modules that need to be loaded early, as is the case
for modules that implement L, which are needed during
the configuration phase.
See also: L.
=head2 C
PerlModule Foo::Bar
is equivalent to Perl's:
require Foo::Bar;
C is used to load modules using their package names.
You can pass one or more module names as arguments to C:
PerlModule Apache::DBI CGI DBD::Mysql
Notice, that normally, the Perl startup is
L until
after the configuration phase.
See also: C>.
See also: L.
=head2 C
The directive C provides fine-grained configuration for
what were compile-time only options in the first mod_perl generation.
It also provides control over what class of Perl interpreter pool is
used for a CVirtualHostE> or location configured with
CLocationE>, CDirectoryE>, etc.
L<$r-Eis_perl_option_enabled($option)|docs::2.0::api::Apache2::RequestUtil/C_is_perl_option_enabled_>
and
L<$s-Eis_perl_option_enabled($option)|docs::2.0::api::Apache2::ServerUtil/C_is_perl_option_enabled_>
can be used at run-time to check whether a certain C<$option> has been
enabled. (META: probably need to add/move this to the coding chapter)
Options are enabled by prepending C<+> and disabled with C<->.
See also: L.
The available options are:
=head3 C
On by default, can be used to disable mod_perl for a given
C. For example:
PerlOptions -Enable
=head3 C
Share the parent Perl interpreter, but give the C its own
interpreter pool. For example should you wish to fine tune interpreter
pools for a given virtual host:
PerlOptions +Clone
PerlInterpStart 2
PerlInterpMax 2
This might be worthwhile in the case where certain hosts have their
own sets of large-ish modules, used only in each host. By tuning each
host to have its own pool, that host will continue to reuse the Perl
allocations in their specific modules.
=head3 C
Off by default, can be used to have a C inherit the value
of the C from the parent server.
For instance, when cloning a Perl interpreter, to inherit the base Perl
interpreter's C use:
PerlOptions +Clone +InheritSwitches
...
=head3 C
Create a new parent Perl interpreter for the given C and
give it its own interpreter pool (implies the C option).
A common problem with mod_perl 1.0 was the shared namespace between
all code within the process. Consider two developers using the same
server and each wants to run a different version of a module with the
same name. This example will create two I Perl interpreters,
one for each CVirtualHostE>, each with its own namespace and
pointing to a different paths in C<@INC>:
META: is -Mlib portable? (problems with -Mlib on Darwin/5.6.0?)
ServerName dev1
PerlOptions +Parent
PerlSwitches -Mlib=/home/dev1/lib/perl
ServerName dev2
PerlOptions +Parent
PerlSwitches -Mlib=/home/dev2/lib/perl
Remember that C<+Parent> gives you a completely new Perl interpreters
pool, so all your modifications to C<@INC> and preloading of the
modules should be done again. Consider using L if you want to inherit from the parent Perl
interpreter.
Or even for a given location, for something like "dirty" cgi scripts:
PerlOptions +Parent
PerlInterpMaxRequests 1
PerlInterpStart 1
PerlInterpMax 1
PerlResponseHandler ModPerl::Registry
will use a fresh interpreter with its own namespace to handle each
request.
=head3 C
Disable Cs, all compiled-in handlers are enabled by
default. The option name is derived from the C name, by
stripping the C and C parts of the word. So
C becomes C which can be used to disable
C:
PerlOptions -Log
Suppose one of the hosts does not want to allow users to configure
C, C, C and
EPerlE sections:
PerlOptions -Authen -Authz -Access -Sections
Or maybe everything but the response handler:
PerlOptions None +Response
=head3 C
Resolve C at startup time, which includes loading the
modules from disk if not already loaded.
In mod_perl 1.0, configured C which are not a fully
qualified subroutine names are resolved at request time, loading the
handler module from disk if needed. In mod_perl 2.0, configured
C are resolved at startup time. By default, modules
are not auto-loaded during startup-time resolution. It is possible to
enable this feature with:
PerlOptions +Autoload
Consider this configuration:
PerlResponseHandler Apache::Magick
In this case, C is the package name, and the
subroutine name will default to I. If the C
module is not already loaded, C will attempt to
pull it in at startup time. With this option enabled you don't have to
explicitly load the handler modules. For example you don't need to
add:
PerlModule Apache::Magick
in our example.
Another way to preload only specific modules is to add + when
configuring those, for example:
PerlResponseHandler +Apache::Magick
will automatically preload the C module.
=head3 C
Setup the global C> object
for use with
Crequest|docs::2.0::api::Apache2::RequestUtil/C_request_>>.
This setting is enabled by default during the
C>
phase for sections configured as:
SetHandler perl-script
...
but is not enabled by default for sections configured as:
SetHandler modperl
....
And can be disabled with:
SetHandler perl-script
PerlOptions -GlobalRequest
...
Notice that if you need the global request object during other phases,
you will need to explicitly enable it in the configuration file.
You can also set that global object from the handler code, like so:
sub handler {
my $r = shift;
Apache2::RequestUtil->request($r);
...
}
The C<+GlobalRequest> setting is needed for example if you use older
versions of C to process the incoming request. Starting from
version 2.93, C optionally accepts C<$r> as an argument to
C, like so:
sub handler {
my $r = shift;
my $q = CGI->new($r);
...
}
Remember that inside registry scripts you can always get C<$r> at the
beginning of the script, since it gets wrapped inside a subroutine and
accepts C<$r> as the first and the only argument. For example:
#!/usr/bin/perl
use CGI;
my $r = shift;
my $q = CGI->new($r);
...
of course you won't be able to run this under mod_cgi, so you may need
to do:
#!/usr/bin/perl
use CGI;
my $q = $ENV{MOD_PERL} ? CGI->new(shift @_) : CGI->new();
...
in order to have the script running under mod_perl and mod_cgi.
=head3 C
Scan output for HTTP headers, same functionality as mod_perl 1.0's
C, but more robust. This option is usually needs to
be enabled for registry scripts which send the HTTP header with:
print "Content-type: text/html\n\n";
=head3 C
Turn on merging of C arrays. For example with a setting:
PerlFixupHandler Apache2::FixupA
PerlFixupHandler Apache2::FixupB
a request for I only runs C (mod_perl 1.0
behavior). But with this configuration:
PerlFixupHandler Apache2::FixupA
PerlOptions +MergeHandlers
PerlFixupHandler Apache2::FixupB
a request for I will run both C and
C handlers.
=head3 C
Set up environment variables for each request ala mod_cgi.
When this option is enabled, I fiddles with the environment
to make it appear as if the code is called under the mod_cgi handler.
For example, the C<$ENV{QUERY_STRING}> environment variable is
initialized with the contents of I, and the value
returned by I is put into
C<$ENV{SERVER_NAME}>.
But C<%ENV> population is expensive. Those who have moved to the Perl
Apache API no longer need this extra C<%ENV> population, and can gain
by disabling it. A code using the C module require
C because that module relies on a properly populated
CGI environment table.
This option is enabled by default for sections configured as:
SetHandler perl-script
...
Since this option adds an overhead to each request, if you don't need
this functionality you can turn it off for a certain section:
SetHandler perl-script
PerlOptions -SetupEnv
...
or globally:
PerlOptions -SetupEnv
...
and then it'll affect the whole server. It can still be enabled for
sections that need this functionality.
When this option is disabled you can still read environment variables
set by you. For example when you use the following configuration:
PerlOptions -SetupEnv
PerlModule ModPerl::Registry
PerlSetEnv TEST hi
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
Options +ExecCGI
and you issue a request for this script:
setupenvoff.pl
--------------
use Data::Dumper;
my $r = Apache2::RequestUtil->request();
$r->content_type('text/plain');
print Dumper(\%ENV);
you should see something like this:
$VAR1 = {
'GATEWAY_INTERFACE' => 'CGI-Perl/1.1',
'MOD_PERL' => 'mod_perl/2.0.1',
'PATH' => 'bin:/usr/bin',
'TEST' => 'hi'
};
Notice that we have got the value of the environment variable I.
=head2 C
C instructs mod_perl to pass the environment variables you
specify to your mod_perl handlers. This is useful if you need to set
the same environment variables for your shell as well as mod_perl. For
example if you had this in your .bash_profile:
export ORACLE_HOME=/oracle
And defined the following in your I:
PerlPassEnv ORACLE_HOME
The your mod_perl handlers would have access to the value via the standard
Perl mechanism:
my $oracle_home = $ENV{'ORACLE_HOME'};
See also: L.
=head2 C
PerlPostConfigRequire /home/httpd/perl/lib/startup.pl
is equivalent to Perl's:
require "/home/httpd/perl/lib/startup.pl";
A C filename argument can be absolute or relative to
C or a filepath in Perl's C<@INC>.
You can pass one or more filenames as arguments to
C:
PerlPostConfigRequire path1/startup.pl path2/startup.pl
C is used to load files with Perl code to be
run at the server startup. It's not executed as soon as it is
encountered, but L
during the server startup.
Most of the time you should be using this directive. For example to
preload some modules or run things at the server startup). Only if you
need to load modules that introduce new configuration directives, used
later in the configuration file you should use
C>.
As with any file with Perl code that gets C'd or
C'd, it must return a I value. To ensure that this
happens don't forget to add C<1;> at the end of
F>.
See also: C> and
C>.
See also: L.
=head2 C
C does the same thing as
C>, but you have
almost no control of L.
Therefore you should be using either
C> (executes immediately)
or C> (executes
just before the end of the server startup) instead. Most of the time
you want to use the latter.
See also: L.
=head2 C
C allows you to specify system environment variables and pass
them into your mod_perl handlers. These values are then available through
the normal perl C<%ENV> mechanisms. For example:
PerlSetEnv TEMPLATE_PATH /usr/share/templates
would create C<$ENV{'TEMPLATE_PATH'}> and set it to I.
See also: L.
=head2 C
C allows you to pass variables into your mod_perl handlers from
your I. This method is preferable to using C or
Apache's C and C methods because of the overhead of having
to populate C<%ENV> for each request. An example of how this can be used is:
PerlSetVar foo bar
To retrieve the value of that variable in your Perl code you would use:
my $foo = $r->dir_config('foo');
In this example C<$foo> would then hold the value 'bar'. B that these
directives are parsed at request time which is a slower method than using
L
See also: L.
=head2 C
Now you can pass any Perl's command line switches in I
using the C directive. For example to enable warnings
and Taint checking add:
PerlSwitches -wT
As an alternative to using C