On Wed, 19 Apr 2000, J. J. Horner wrote:
> On Wed, 19 Apr 2000, w trillich wrote:
>
> > having seen the possibilities from
> > /usr/share/doc/libapache-mod-perl/examples/perl_sections.txt
> > (schwartz's neat virtual host setup) i thought i'd give it
> > a whirl.
> >
>
> I don't have this. Can someone point me to a link, or maybe send it via
> email to either [EMAIL PROTECTED] or [EMAIL PROTECTED]?
mod_perl-x.xx/eg/perl_sections.txt
and this was written by Rob Hartill and not Randal, unless we are talking
about different files.
As for the original question from w trillich <[EMAIL PROTECTED]>, here is
a rewritten not yet released section about <Perl> section that might solve
your problem. The most relevant to the question sections are 'Caveats',
'Verifying' and 'Debugging':
=head1 Apache Configuration in Perl
With C<<Perl>>...C<</Perl>> sections, it is possible to configure your
server entirely in Perl.
=head2 Usage
C<<Perl>> sections can contain I<any> and as much Perl code as you
wish. These sections are compiled into a special package whose symbol
table mod_perl can then walk and grind the names and values of Perl
variables/structures through the Apache core configuration gears.
Most of the configuration directives can be represented as scalars
(C<$scalar>) or lists (C<@list>). A C<@List> inside these sections is
simply converted into a space delimited string for you. Here is an
example:
httpd.conf
------------
<Perl>
@PerlModule = qw(Mail::Send Devel::Peek);
#run the server as whoever starts it
$User = getpwuid($>) || $>;
$Group = getgrgid($)) || $);
$ServerAdmin = $User;
</Perl>
Block sections such as C<<Location>>..C<</Location>> are represented
in a C<%Location> hash, e.g.:
<Perl>
$Location{"/~dougm/"} = {
AuthUserFile => '/tmp/htpasswd',
AuthType => 'Basic',
AuthName => 'test',
DirectoryIndex => [qw(index.html index.htm)],
Limit => {
METHODS => 'GET POST',
require => 'user dougm',
},
};
</Perl>
If an Apache directive can take two or three arguments you may push
strings (the lowest number of arguments will be shifted off the
C<@List>) or use an array reference to handle any number greater than
the minimum for that directive:
push @Redirect, "/foo", "http://www.foo.com/";
push @Redirect, "/imdb", "http://www.imdb.com/";
push @Redirect, [qw(temp "/here" "http://www.there.com")];
Other section counterparts include C<%VirtualHost>, C<%Directory> and
C<%Files>.
To pass all environment variables to the children with a single
configuration directive, rather than listing each one via C<PassEnv>
or C<PerlPassEnv>, a C<<Perl>> section could read in a file and:
push @PerlPassEnv, [$key => $val];
or
Apache->httpd_conf("PerlPassEnv $key $val");
These are somewhat simple examples, but they should give you the basic
idea. You can mix in any Perl code you desire. See I<eg/httpd.conf.pl>
and I<eg/perl_sections.txt> in the mod_perl distribution for more
examples.
Assume that you have a cluster of machines with similar configurations
and only small distinctions between them: ideally you would want to
maintain a single configuration file, but because the configurations
aren't I<exactly> the same (e.g. the C<ServerName> directive) it's not
quite that simple.
C<<Perl>> sections come to rescue. Now you have a single configuration
file and the full power of Perl to tweak the local configuration. For
example to solve the problem of the C<ServerName> directive you might
have this C<<Perl>> section:
<Perl>
$ServerName = `hostname`;
</Perl>
For example if you want to allow personal directories on all machines
except the ones whose names start with I<secure>:
<Perl>
$ServerName = `hostname`;
if ( $ServerName !~ /^secure/) {
$UserDir = "public.html";
} else {
$UserDir = "DISABLED";
}
</Perl>
Behind the scenes, mod_perl defines a package called
C<Apache::ReadConfig>. Here it keeps all the variables that you
define inside the C<<Perl>> sections. Therefore it's not necessarily
to configure the server within the C<<Perl>> sections. Actually what
you can do is to write the Perl code to configure the server just like
you'd do in the C<<Perl>> sections, but instead place it into a
separate file that should be called during the configuration parsing
with either C<PerlModule> or C<PerlRequire> directives, or from within
the startup file. All you have to do is to declare the package
C<Apache::ReadConfig> within this file. Using the last example:
apache_config.pl
----------------
package Apache::ReadConfig;
$ServerName = `hostname`;
if ( $ServerName !~ /^secure/) {
$UserDir = "public.html";
} else {
$UserDir = "DISABLED";
}
1;
httpd.conf
----------
PerlRequire /home/httpd/perl/lib/apache_config.pl
=head2 Enabling
To enable C<<Perl>> sections you should build mod_perl with S<perl
Makefile.PL PERL_SECTIONS=1 [ ... ]>.
=head2 Caveats
Be careful when you declare package names inside C<<Perl>> sections,
for example this code has a problem:
<Perl>
package My::Trans;
use Apache::Constants qw(:common);
sub handler{ OK }
$PerlTransHandler = "My::Trans";
</Perl>
When you put code inside a C<<Perl>> section, by default it actually
goes into the C<Apache::ReadConfig> package, which is already declared
for you. This means that the C<PerlTransHandler> we have tried to
define above is actually undefined. If you define a different package
name within a C<<Perl>> section you must make sure to close the scope
of that package and return to the C<Apache::ReadConfig> package when
you want to define the configuration directives, like this:
<Perl>
package My::Trans;
use Apache::Constants qw(:common);
sub handler{ OK }
package Apache::ReadConfig;
$PerlTransHandler = "My::Trans";
</Perl>
=head2 Verifying
This section shows how to check and dump the configuration you have
made with the help of C<<Perl>> sections in I<httpd.conf>.
To check the C<<Perl>> section syntax outside of httpd, we make it
look like a Perl script:
<Perl>
# !perl
# ... code here ...
__END__
</Perl>
Now you may run:
perl -cx httpd.conf
In a running httpd you can see how you have configured the C<<Perl>>
sections through the URI
L</perl-status|debug/Apache_Status_Embedded_Inter>, by choosing I<Perl
Section Configuration> from the menu. In order to make this item show
up in the menu you should set C<$Apache::Server::SaveConfig> to a true
value. When you do that the I<Apache::ReadConfig> namespace (in which
the configuration data is stored) will not be flushed, making
configuration data available to Perl modules at request time.
Example:
<Perl>
$Apache::Server::SaveConfig = 1;
$DocumentRoot = ...
...
</Perl>
At request time, the value of B<$DocumentRoot> can be accessed with
the fully qualified name B<$Apache::ReadConfig::DocumentRoot>.
You can dump the configuration of C<<Perl>> sections like this:
<Perl>
use Apache::PerlSections();
...
# Configuration Perl code here
...
print STDERR Apache::PerlSections->dump();
</Perl>
Alternatively you can store it in a file:
Apache::PerlSections->store("httpd_config.pl");
You can then require() that file in some other C<<Perl>> section.
=head2 Strict <Perl> Sections
If the Perl code doesn't compile, the server won't start. If the
generated Apache config is invalid, C<<Perl>> sections have always
just logged an error and carried on, since there might be globals in
the section that are not intended for the config.
The variable C<$Apache::Server::StrictPerlSections> has been added in
mod_perl version 1.22. If you set this variable to a true value, for
example
$Apache::Server::StrictPerlSections = 1;
then mod_perl will not tolerate invalid Apache configuration syntax
and will croak (die) if this is the case. At the time of writing the
default value is C<0>.
=head2 Debugging
If you compile modperl with C<PERL_TRACE=1> and set the environment
variable L<MOD_PERL_TRACE|debug/Debug_Tracing> then you should see
some useful diagnostics when mod_perl is processing <Perl> sections.
______________________________________________________________________
Stas Bekman | JAm_pH -- Just Another mod_perl Hacker
http://stason.org/ | mod_perl Guide http://perl.apache.org/guide
mailto:[EMAIL PROTECTED] | http://perl.org http://stason.org/TULARC/
http://singlesheaven.com| http://perlmonth.com http://sourcegarden.org
----------------------------------------------------------------------
