You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by st...@apache.org on 2002/04/18 20:13:05 UTC
cvs commit: modperl-docs/src/docs/1.0/guide Changes.pod
stas 02/04/18 11:13:05
Modified: src/docs/1.0/faqs Changes.pod cgi_to_mod_perl.pod config.cfg
mod_perl.pod mod_perl_api.pod mod_perl_cgi.pod
mod_perl_cvs.pod mod_perl_faq.pod
mod_perl_method_handlers.pod mod_perl_traps.pod
mod_perl_tuning.pod perl_myth.pod
src/docs/1.0/guide Changes.pod
Added: src/docs/1.0/faqs httpd+perl.conf.txt httpd.conf.txt
Log:
+* Re-arranged the order of the FAQs.
+
+* Changed titles of documents to not include underscores, and of
+ headings inside documents to not be upper-case.
+
+* Corrected links and removed stale ones.
+
+* Fixed authors where needed.
+
+* Did some slight content review, added C<CE<lt>E<gt>>, C<BE<lt>E<gt>>
+ ... on many places to make it more readable.
Submitted by: Per Einar Ellefsen <pe...@skynet.be>
Revision Changes Path
1.2 +16 -0 modperl-docs/src/docs/1.0/faqs/Changes.pod
Index: Changes.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/Changes.pod,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Changes.pod 20 Mar 2002 17:42:05 -0000 1.1
+++ Changes.pod 18 Apr 2002 18:13:05 -0000 1.2
@@ -9,6 +9,22 @@
The most recent changes are listed first.
+=head1 Thu Apr 18 09:10:00 CET 2002
+
+Per Einar Ellefsen E<lt>per.einar (at) skynet.beE<gt>
+
+* Re-arranged the order of the FAQs.
+
+* Changed titles of documents to not include underscores, and of
+ headings inside documents to not be upper-case.
+
+* Corrected links and removed stale ones.
+
+* Fixed authors where needed.
+
+* Did some slight content review, added C<CE<lt>E<gt>>, C<BE<lt>E<gt>>
+ ... on many places to make it more readable.
+
=head1 Sat Sep 15 19:45:41 SGT 2001
* docs ported from the old site
1.4 +16 -13 modperl-docs/src/docs/1.0/faqs/cgi_to_mod_perl.pod
Index: cgi_to_mod_perl.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/cgi_to_mod_perl.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- cgi_to_mod_perl.pod 20 Mar 2002 17:42:05 -0000 1.3
+++ cgi_to_mod_perl.pod 18 Apr 2002 18:13:05 -0000 1.4
@@ -1,22 +1,25 @@
=head1 NAME
-cgi_to_mod_perl - First steps needed to use mod_perl as a CGI replacement
+First steps needed to use mod_perl as a CGI replacement
-=head1 DESCRIPTION
+=head1 Description
-As the README and other mod_perl documents explain, mod_perl as
+As the I<README> and other mod_perl documents explain, mod_perl as
a CGI replacement is only a small piece of what the package offers.
However, it is the most popular use of mod_perl, this document is here
so you can cut to the chase.
-=head1 INSTALLATION
+META: cgi_to_mod_perl and mod_perl_cgi should probably be integrated into
+one FAQ.
-Read the INSTALL document, in most cases, nothing more is required
+=head1 Installation
+
+Read the I<INSTALL> document, in most cases, nothing more is required
than:
perl Makefile.PL && make && make install
-=head1 CONFIGURATION
+=head1 Configuration
For using mod_perl as a CGI replacement, the recommended configuration
is as follows:
@@ -49,7 +52,7 @@
Note that `ScriptAlias' does _not_ work for mod_perl.
-=head1 PORTING CGI SCRIPTS
+=head1 Porting CGI scripts
=over 4
@@ -60,7 +63,7 @@
C<print()> functions do not work as they do under CGI. If you're
using CGI.pm, use C<$query-E<gt>print> instead of plain 'ol C<print()>.
-=item HEADERS
+=item Headers
By default, mod_perl does not send any headers by itself, however, you
may wish to change this:
@@ -76,7 +79,7 @@
If you're using CGI.pm and 'print $q-E<gt>header' you do
_not_ need C<PerlSendHeader On>.
-=item NPH SCRIPTS
+=item NPH Scripts
To run a CGI `nph' script under mod_perl, simply add to your code:
@@ -88,7 +91,7 @@
PerlSendHeader Off
</Files>
-=item PROGRAMMING PRACTICE
+=item Programming Practice
CGI lets you get away with sloppy programming, mod_perl does not.
Why? CGI scripts have the lifetime of a single HTTP request as a
@@ -105,17 +108,17 @@
in the long run. And, of course, clean scripts will still run under
CGI!
-=item TRAPS
+=item Traps
See L<common/known mod_perl traps|faqs::mod_perl_traps>.
=back
-=head1 REPORTING PROBLEMS
+=head1 Reporting problems
Read the I<SUPPORT> file.
-=head1 SEE ALSO
+=head1 See Also
Apache::PerlRun(3)
1.5 +7 -5 modperl-docs/src/docs/1.0/faqs/config.cfg
Index: config.cfg
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/config.cfg,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- config.cfg 20 Mar 2002 17:42:05 -0000 1.4
+++ config.cfg 18 Apr 2002 18:13:05 -0000 1.5
@@ -7,21 +7,23 @@
abstract => 'Miscellaneous mod_perl 1.x documentation',
chapters => [qw(
+ mod_perl.pod
+ mod_perl_faq.pod
cgi_to_mod_perl.pod
mod_perl_cgi.pod
- mod_perl_cvs.pod
- mod_perl_faq.pod
- mod_perl.pod
mod_perl_traps.pod
- mod_perl_tuning.pod
mod_perl_api.pod
- mod_perl_method_handlers.pod
+ mod_perl_tuning.pod
perl_myth.pod
+ mod_perl_method_handlers.pod
+ mod_perl_cvs.pod
Changes.pod
)],
copy_glob => [
qw(
mjtg-news.txt
+ httpd.conf.txt
+ httpd+perl.conf.txt
)
],
);
1.4 +156 -117 modperl-docs/src/docs/1.0/faqs/mod_perl.pod
Index: mod_perl.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- mod_perl.pod 20 Mar 2002 17:42:05 -0000 1.3
+++ mod_perl.pod 18 Apr 2002 18:13:05 -0000 1.4
@@ -3,7 +3,7 @@
mod_perl - Embed a Perl interpreter in the Apache HTTP server
-=head1 DESCRIPTION
+=head1 Description
The Apache/Perl integration project brings together the full power of
the Perl programming language and the Apache HTTP server. This is
@@ -17,14 +17,14 @@
penalty of Perl start-up (compile) time.
Without question, the most popular Apache/Perl module is
-Apache::Registry module. This module emulates the CGI environment,
+C<Apache::Registry> module. This module emulates the CGI environment,
allowing programmers to write scripts that run under CGI or
mod_perl without change. Existing CGI scripts may require some
changes, simply because a CGI script has a very short lifetime of one
HTTP request, allowing you to get away with "quick and dirty"
-scripting. Using mod_perl and Apache::Registry requires you to be
+scripting. Using mod_perl and C<Apache::Registry> requires you to be
more careful, but it also gives new meaning to the work "quick"!
-Apache::Registry maintains a cache of compiled scripts, which happens
+C<Apache::Registry> maintains a cache of compiled scripts, which happens
the first time a script is accessed by a child server or once again if
the file is updated on disk.
@@ -37,16 +37,18 @@
=head1 FAQ
The mod_perl FAQ is maintained by Frank Cringle
-E<lt>fdc@cliwe.ping.deE<gt>: http://perl.apache.org/faq/
+E<lt>fdc (at) cliwe.ping.deE<gt>: L<Frequently Asked Questions about
+mod_perl|faqs::mod_perl_faq>.
=head1 Apache/Perl API
-See 'perldoc Apache' for info on how to use the Perl-Apache API.
+See 'C<perldoc Apache>' for info on how to use the Perl-Apache API.
See the I<lib/> directory for example modules and
-L<products::apache-modlist> for a comprehensive list.
+L<The Apache/Perl module list|products::apache-modlist> for a
+comprehensive list.
-See the eg/ directory for example scripts.
+See the I<eg/> directory for example scripts.
=head1 mod_perl
@@ -74,29 +76,29 @@
PerlHandler sub_routine_name
-This is the name of the subroutine to call to handle each request.
-e.g.
-in the PerlModule Apache::Registry this is "Apache::Registry::handler".
+This is the name of the subroutine to call to handle each request.
+e.g. in C<PerlModule Apache::Registry> this is
+C<Apache::Registry::handler>.
If PerlHandler is not a defined subroutine, mod_perl assumes it is a
package name which defines a subroutine named "handler".
PerlHandler Apache::Registry
-Would load Registry.pm (if it is not already) and call it's subroutine
-"handler".
+Would load I<Registry.pm> (if it is not already) and call its
+subroutine C<handler>.
There are several stages of a request where the Apache API allows a
module to step in 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, see the INSTALL
+By default, these hooks are disabled at compile time, see the I<INSTALL>
document for information on enabling these hooks.
The following configuration directives take one argument, which is the name
of the subroutine to call. If the value is not a subroutine name, mod_perl
assumes it is a package name which implements a 'handler' subroutine.
- PerlChildInitHandler (requires apache_1.3.0 or higher)
- PerlPostReadRequestHandler (requires apache_1.3.0 or higher)
+ PerlChildInitHandler (requires Apache 1.3.0 or higher)
+ PerlPostReadRequestHandler (requires Apache 1.3.0 or higher)
PerlInitHandler
PerlTransHandler
PerlHeaderParserHandler
@@ -108,24 +110,24 @@
PerlHandler
PerlLogHandler
PerlCleanupHandler
- PerlChildExitHandler (requires apache_1.3.0 or higher)
+ PerlChildExitHandler (requires Apache 1.3.0 or higher)
Only ChildInit, ChildExit, PostReadRequest and Trans handlers are not
allowed in .htaccess files.
Modules can check if the code is being run in the parent server during
-startup by checking the $Apache::Server::Starting variable.
+startup by checking the C<$Apache::Server::Starting> variable.
-=head1 RESTARTING
+=head1 Restarting
=over 4
=item PerlFreshRestart
By default, if a server is restarted
-(ala kill -USR1 `cat logs/httpd.pid`), Perl scripts and modules are
+(ala C<kill -USR1 `cat logs/httpd.pid`>), Perl scripts and modules are
not reloaded. To reload B<PerlRequire>'s, B<PerlModule>'s, other
-use()'d modules and flush the B<Apache::Registry> cache, enable with
+C<use()>'d modules and flush the B<Apache::Registry> cache, enable with
this command:
PerlFreshRestart On
@@ -133,7 +135,7 @@
=item PERL_DESTRUCT_LEVEL
With Apache versions 1.3.0 and higher, mod_perl will call the
-perl_destruct() Perl API function during the child exit phase.
+C<perl_destruct()> Perl API function during the child exit phase.
This will cause proper execution of B<END> blocks found during server
startup along with invoking the B<DESTROY> method on global objects
who are still alive. It is possible that this operation may take a
@@ -144,7 +146,7 @@
=back
-=head1 ENVIRONMENT
+=head1 Environment
Under CGI the Perl hash C<%ENV> is magical in that it inherits
environment variables from the parent process and will set them should
@@ -166,7 +168,7 @@
=over 4
-=item CONFIGURATION
+=item Configuration
The C<PerlSetVar> and C<PerlAddVar> directives provide a simple
mechanism for passing information from configuration files to Perl
@@ -234,19 +236,56 @@
Modules and files pulled in via require/use which contain C<BEGIN>
blocks will be executed:
- - only once, if pulled in by the parent process
- - once per-child process if not pulled in by the parent process
- - an additional time, once per-child process if the module is pulled in off of disk again via Apache::StatINC
- - an additional time, in the parent process on each restart if PerlFreshRestart is On
- - unpredictable if you fiddle with C<%INC> yourself
+
+=over
+
+=item *
+
+only once, if pulled in by the parent process
+
+=item *
+
+once per-child process if not pulled in by the parent process
+
+=item *
+
+an additional time, once per-child process if the module is pulled in off
+of disk again via C<Apache::StatINC>
+
+=item *
+
+an additional time, in the parent process on each restart if
+I<PerlFreshRestart> is I<On>
+
+=item *
+
+unpredictable if you fiddle with C<%INC> yourself
+
+=back
B<Apache::Registry> scripts which contain C<BEGIN> blocks will be
executed:
- - only once, if pulled in by the parent process via B<Apache::RegistryLoader>
- - once per-child process if not pulled in by the parent process
- - an additional time, once per-child process if the script file has changed on disk
- - an additional time, in the parent process on each restart if pulled in by the
- parent process via B<Apache::RegistryLoader> and PerlFreshRestart is On
+
+=over
+
+=item *
+
+only once, if pulled in by the parent process via B<Apache::RegistryLoader>
+
+=item *
+
+once per-child process if not pulled in by the parent process
+
+=item *
+
+an additional time, once per-child process if the script file has changed on disk
+
+=item *
+
+an additional time, in the parent process on each restart if pulled in by the
+parent process via B<Apache::RegistryLoader> and PerlFreshRestart is On
+
+=back
=head1 END blocks
@@ -272,9 +311,9 @@
Module authors may be wish to use C<$r-E<gt>register_cleanup> as an
alternative to C<END> blocks if this behavior is not desirable.
-=head1 MEMORY CONSUMPTION
+=head1 Memory consumption
-Don't be alarmed by the size of your httpd after you've linked with
+Don't be alarmed by the size of your I<httpd> after you've linked with
mod_perl. No matter what, your httpd will be larger than normal to start,
simply because you've linked with perl's runtime.
@@ -291,28 +330,28 @@
10545 dougm 49 0 3732K 3340K run 0:05 54.59% 21.48% perl
-Here's my httpd linked with libperl.a, not having served a single request:
+Here's my I<httpd> linked with I<libperl.a>, not having served a single request:
10386 dougm 5 0 1032K 324K sleep 0:00 0.12% 0.11% httpd-a
You can reduce this if you configure perl 5.004+ with -Duseshrplib.
-Here's my httpd linked with libperl.sl, not having served a single request:
+Here's my I<httpd> linked with I<libperl.sl>, not having served a single request:
10393 dougm 5 0 476K 368K sleep 0:00 0.12% 0.10% httpd-s
Now, once the server starts receiving requests, the embedded
-interpreter will compile code for each 'require' file it has not seen
-yet, each new Apache::Registry subroutine that's compiled, along with
+interpreter will compile code for each 'C<require>' file it has not seen
+yet, each new B<Apache::Registry> subroutine that's compiled, along with
whatever modules it's use'ing or require'ing. Not to mention
-AUTOLOADing. (Modules that you 'use' will be compiled when the server
-starts unless they are inside an eval block.) httpd will grow just as
-big as our /usr/bin/perl would, or a CGI process for that matter, it
+AUTOLOADing. (Modules that you 'C<use>' will be compiled when the server
+starts unless they are inside an eval block.) I<httpd> will grow just as
+big as our I</usr/bin/perl> would, or a CGI process for that matter, it
all depends on your setup. The L<mod_perl
tuning|faqs::mod_perl_tuning> document gives advice on how to best
setup your mod_perl server environment.
-The mod_perl INSTALL document explains how to build the Apache::
-extensions as shared libraries (with 'perl Makefile.PL DYNAMIC=1').
+The mod_perl I<INSTALL> document explains how to build the C<Apache::>
+extensions as shared libraries (with 'C<perl Makefile.PL DYNAMIC=1>').
This may save you some memory, however, it doesn't work on a few
systems such as aix and unixware.
@@ -322,7 +361,7 @@
the same time. See the L<mod_perl tuning|faqs::mod_perl_tuning>
document for details.
-=head2 MEMORY TIPS
+=head2 Memory tips
=over 4
@@ -335,14 +374,14 @@
=item Perl Options
Newer Perl versions also have other options to reduce runtime memory
-consumption. See Perl's INSTALL file for details on C<-DPACK_MALLOC>
+consumption. See Perl's I<INSTALL> file for details on C<-DPACK_MALLOC>
and C<-DTWO_POT_OPTIMIZE>. With these options, my httpd shrinks down
~150K.
=item Server Startup
Use the B<PerlRequire> and B<PerlModule> directives to load commonly
-used modules such as CGI.pm, DBI, etc., when the server is started.
+used modules such as C<CGI.pm>, C<DBI>, etc., when the server is started.
On most systems, server children will be able to share this space.
=item Importing Functions
@@ -350,15 +389,15 @@
When possible, avoid importing of a module functions into your
namespace. The aliases which are created can take up quite a bit of
space. Try to use method interfaces and fully qualified
-Package::function names instead.
-Here's a freshly started httpd who's served one request for a script
-using the CGI.pm method interface:
+C<Package::function> names instead. Here's a freshly started httpd
+who's served one request for a script using the C<CGI.pm> method
+interface:
TTY PID USERNAME PRI NI SIZE RES STATE TIME %WCPU %CPU COMMAND
p4 5016 dougm 154 20 3808K 2636K sleep 0:01 9.62 4.07 httpd
Here's a freshly started httpd who's served one request for the same
-script using the CGI.pm function interface:
+script using the C<CGI.pm> function interface:
TTY PID USERNAME PRI NI SIZE RES STATE TIME %WCPU %CPU COMMAND
p4 5036 dougm 154 20 3900K 2708K sleep 0:01 3.19 2.18 httpd
@@ -371,7 +410,7 @@
It's always a good idea to stay away from global variables when
possible. Some variables must be global so Perl can see them, such as
-a module's B<@ISA> or B<$VERSION> variables. In common practice, a
+a module's C<@ISA> or C<$VERSION> variables. In common practice, a
combination of C<use strict> and C<use vars> keeps modules clean and
reduces a bit of noise. However, B<use vars> also creates aliases as
the B<Exporter> does, which eat up more space. When possible, try to
@@ -392,16 +431,16 @@
=item Further Reading
-In case I forgot to mention, read Vivek Khera's L<mod_perl
+In case I forgot to mention it, read Vivek Khera's L<mod_perl
tuning|faqs::mod_perl_tuning> document for more tips on improving
Apache/mod_perl performance.
=back
-=head1 SWITCHES
+=head1 Switches
Normally when you run perl from the command line or have the shell
-invoke it with `#!', you may choose to pass perl switch arguments such
+invoke it with C<`#!'>, you may choose to pass perl switch arguments such
as C<-w> or C<-T>. Since the command line is only parsed once, when
the server starts, these switches are unavailable to mod_perl scripts.
However, most command line arguments have a perl special variable
@@ -424,9 +463,9 @@
perl startup flags such as B<-d> and B<-D>. See the I<perlrun>
manpage.
-=head1 PERSISTENT DATABASE CONNECTIONS
+=head1 Persistent Database Connections
-Another popular use of mod_perl is to take advantage of it's
+Another popular use of mod_perl is to take advantage of its
persistance to maintain open database connections. The basic idea
goes like so:
@@ -440,7 +479,7 @@
keeping the connection open for the lifetime of a server process,
establishing it during the script's first request for that process.
-It's recommended that you use one of the Apache::* database connection
+It's recommended that you use one of the C<Apache::*> database connection
wrappers. Currently for DBI users there is C<Apache::DBI> and for
Sybase users C<Apache::Sybase::DBlib>. These modules hide the
peculiar code example above. In addition, different scripts may share
@@ -453,7 +492,7 @@
my $dbh = DBI->connect(...);
Although B<$dbh> shown here will go out of scope when the script ends,
-the Apache::DBI module's reference to it does not, keep the connection
+the C<Apache::DBI> module's reference to it does not, keep the connection
open.
B<WARNING:> Do not attempt to open a persistent database connection in
@@ -462,21 +501,21 @@
handle is used by two processes at the same time. Each child must
have it's own unique connection handle.
-=head1 STACKED HANDLERS
+=head1 Stacked Handlers
With the mod_perl stacked handlers mechanism, it is possible for more
-than one Perl*Handler to be defined and run during each stage of a
+than one C<Perl*Handler> to be defined and run during each stage of a
request.
-Perl*Handler directives can define any number of subroutines,
+C<Perl*Handler> directives can define any number of subroutines,
e.g. (in config files)
PerlTransHandler OneTrans TwoTrans RedTrans BlueTrans
-With the method, Apache-E<gt>push_handlers, callbacks can be added to
+With the method, C<Apache-E<gt>push_handlers>, callbacks can be added to
the stack by scripts at runtime by mod_perl scripts.
-Apache-E<gt>push_handlers takes the callback hook name as it's first
+C<Apache-E<gt>push_handlers> takes the callback hook name as it's first
argument and a subroutine name or reference as it's second. e.g.:
Apache->push_handlers("PerlLogHandler", \&first_one);
@@ -489,54 +528,54 @@
After each request, this stack is cleared out.
All handlers will be called unless a handler returns a status other than
-OK or DECLINED, this needs to be considered more. Post apache-1.2 will
-have a DONE return code to signal termiation of a stage, which Rob and
+C<OK> or C<DECLINED>, this needs to be considered more. Post apache-1.2 will
+have a C<DONE> return code to signal termiation of a stage, which Rob and
I came up with while back when first discussing the idea of stacked
handlers. 2.0 won't come for quite sometime, so mod_perl will most
likely handle this before then.
example uses:
-CGI.pm maintains a global object for it's plain function interface.
-Since the object is global, it does not go out of scope, DESTROY is
-never called. CGI-E<gt>new can call:
+C<CGI.pm> maintains a global object for it's plain function interface.
+Since the object is global, it does not go out of scope, C<DESTROY> is
+never called. C<CGI-E<gt>new> can call:
Apache->push_handlers("PerlCleanupHandler", \&CGI::_reset_globals);
This function will be called during the final stage of a request,
-refreshing CGI.pm's globals before the next request comes in.
+refreshing C<CGI.pm>'s globals before the next request comes in.
-Apache::DCELogin establishes a DCE login context which must exist for
-the lifetime of a request, so the DCE::Login object is stored in a
+C<Apache::DCELogin> establishes a DCE login context which must exist for
+the lifetime of a request, so the C<DCE::Login> object is stored in a
global variable. Without stacked handlers, users must set
PerlCleanupHandler Apache::DCELogin::purge
in the configuration files to destroy the context. This is not
-"user-friendly". Now, Apache::DCELogin::handler can call:
+"user-friendly". Now, C<Apache::DCELogin::handler> can call:
Apache->push_handlers("PerlCleanupHandler", \&purge);
-Persistent database connection modules such as Apache::DBI could push
-a PerlCleanupHandler handler that iterates over %Connected, refreshing
-connections or just checking that ones have not gone stale. Remember,
-by the time we get to PerlCleanupHandler, the client has what it wants
-and has gone away, we can spend as much time as we want here without
-slowing down response time to the client.
+Persistent database connection modules such as C<Apache::DBI> could push
+a C<PerlCleanupHandler> handler that iterates over C<%Connected>,
+refreshing connections or just checking that ones have not gone stale.
+Remember, by the time we get to C<PerlCleanupHandler>, the client has
+what it wants and has gone away, we can spend as much time as we want
+here without slowing down response time to the client.
PerlTransHandlers may decide, based or uri or other condition, whether
-or not to handle a request, e.g. Apache::MsqlProxy. Without stacked
+or not to handle a request, e.g. C<Apache::MsqlProxy>. Without stacked
handlers, users must configure:
PerlTransHandler Apache::MsqlProxy::translate
PerlHandler Apache::MsqlProxy
-PerlHandler is never actually invoked unless translate() sees the
-request is a proxy request ($r-E<gt>proxyreq), if it is a proxy request,
-translate() set $r-E<gt>handler("perl-script"), only then will PerlHandler
-handle the request. Now, users do not have to specify 'PerlHandler
-Apache::MsqlProxy', the translate() function can set it with
-push_handlers().
+PerlHandler is never actually invoked unless C<translate()> sees the
+request is a proxy request (C<$r-E<gt>proxyreq)>, if it is a proxy request,
+C<translate()> set C<$r-E<gt>handler("perl-script")>, only then will
+PerlHandler handle the request. Now, users do not have to specify
+'C<PerlHandler Apache::MsqlProxy>', the C<translate()> function can set
+it with C<push_handlers()>.
Includes, footers, headers, etc., piecing together a document,
imagine (no need for SSI parsing!):
@@ -576,7 +615,7 @@
PerlHandler OutputParser AnotherApp
</Location>
-Now, OutputParser goes first, but it untie's *STDOUT and re-tie's to
+Now, OutputParser goes first, but it unties C<*STDOUT> and re-ties to
it's own package like so:
package OutputParser;
@@ -607,20 +646,20 @@
% perl Makefile.PL PERL_STACKED_HANDLERS=1 [PERL_FOO_HOOK=1,etc]
-Another method 'Apache-E<gt>can_stack_handlers' will return TRUE if
+Another method 'C<Apache-E<gt>can_stack_handlers>' will return TRUE if
mod_perl was configured with PERL_STACKED_HANDLERS=1, FALSE
otherwise.
-=head1 PERL METHOD HANDLERS
+=head1 Perl Method Handlers
See L<How to use mod_perl's MethodHandlers|faqs::mod_perl_method_handlers>.
-=head1 PERL SECTIONS
+=head1 Perl Section
-With E<lt>PerlE<gt>E<lt>/PerlE<gt> sections, it is possible to
+With C<E<lt>PerlE<gt>E<lt>/PerlE<gt>> sections, it is possible to
configure your server entirely in Perl.
-E<lt>PerlE<gt> sections can contain *any* and as much Perl code as you
+E<lt>PerlE<gt> sections can contain C<any> and as much Perl code as you
wish. These sections are compiled into a special package who's symbol
table mod_perl can then walk and grind the names and values of Perl
variables/structures through the Apache core config gears. Most of
@@ -671,7 +710,7 @@
These are somewhat boring examples, but they should give you the basic
idea. You can mix in any Perl code your heart desires.
-See eg/httpd.conf.pl and eg/perl_sections.txt for some examples.
+See I<eg/httpd.conf.pl> and I<eg/perl_sections.txt> for some examples.
A tip for syntax checking outside of httpd:
@@ -687,26 +726,28 @@
It may be the case that E<lt>PerlE<gt> sections are not completed or
an oversight was made in an certain area. If they do not behave as
-you expect, please send a report to the modperl mailing list.
+you expect, please send a report to the L<modperl mailing
+list|maillist::list-modperl>.
To configure this feature build with
+
'perl Makefile.PL PERL_SECTIONS=1'
=head1 mod_perl and mod_include integration
As of apache 1.2.0, mod_include can handle Perl callbacks.
-A `sub' key value may be anything a Perl*Handler can be:
-subroutine name, package name (defaults to package::handler),
-Class-E<gt>method call or anonymous sub {}
+A `C<sub>' key value may be anything a C<Perl*Handler> can be:
+subroutine name, package name (defaults to C<package::handler>),
+C<Class-E<gt>method> call or anonymous C<sub { }>
Example:
Child <!--#perl sub="sub {print $$}" --> accessed
<!--#perl sub="sub {print ++$Access::Cnt }" --> times. <br>
-
+
<!--#perl sub="Package::handler" arg="one" arg="two" -->
-
+
#don't forget to escape double quotes!
Perl is
<!--#perl sub="sub {for (0..10) {print \"very \"}}"-->
@@ -719,11 +760,11 @@
<!--#perl sub="Apache::Include" arg="/perl/ssi.pl" -->
-You can also use 'virtual include' to include Apache::Registry scripts
-of course. However, using #perl will save the overhead of making
+You can also use 'C<virtual include>' to include C<Apache::Registry> scripts
+of course. However, using C<#perl> will save the overhead of making
Apache go through the motions of creating/destroying a subrequest and
making all the necessary access checks to see that the request would
-be allowed outside of a 'virtual include' context.
+be allowed outside of a 'C<virtual include>' context.
To enable perl in mod_include parsed files, when building apache the
following must be present in the Configuration file:
@@ -735,17 +776,20 @@
perl Makefile.PL PERL_SSI=1
If you're interested in sprinkling Perl code inside your HTML
-documents, you'll also want to look at the Apache::Embperl
-(http://perl.apache.org/embperl/), Apache::ePerl and Apache::SSI modules.
+documents, you'll also want to look at the C<Apache::Embperl>
+(http://perl.apache.org/embperl/), C<Apache::ePerl>
+(http://www.engelschall.com/sw/eperl/), C<Apache::ASP>
+(http://www.apache-asp.org/), C<HTML::Mason> (http://www.masonhq.com/)
+and C<Apache::SSI> modules.
-=head1 DEBUGGING
+=head1 Debugging
=over 4
=item MOD_PERL_TRACE
To enable mod_perl debug tracing configure mod_perl with the
-PERL_TRACE option:
+C<PERL_TRACE> option:
perl Makefile.PL PERL_TRACE=1
@@ -774,7 +818,7 @@
=back
-=head1 PROFILING
+=head1 Profiling
It is possible to profile code run under mod_perl with the
B<Devel::DProf> module available on CPAN. However, you must have
@@ -793,18 +837,18 @@
See also: B<Apache::DProf>
-=head1 BENCHMARKING
+=head1 Benchmarking
How much faster is mod_perl that CGI? There are many ways to
-benchmark the two, see the C<benchmark/> directory for some examples.
+benchmark the two, see the I<benchmark/> directory for some examples.
See also: B<Apache::Timeit>
-=head1 WARNINGS
+=head1 Warnings
See L<common/known mod_perl traps|faqs::mod_perl_traps>.
-=head1 SUPPORT
+=head1 Support
See the I<SUPPORT> file.
@@ -817,10 +861,6 @@
http://perl.apache.org/distributions/
-=head1 REVISION
-
-$Id: mod_perl.pod,v 1.3 2002/03/20 17:42:05 stas Exp $
-
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
@@ -846,6 +886,5 @@
Only the major authors are listed above. For contributors see the
Changes file.
-
=cut
1.3 +7 -7 modperl-docs/src/docs/1.0/faqs/mod_perl_api.pod
Index: mod_perl_api.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_api.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- mod_perl_api.pod 20 Mar 2002 17:42:05 -0000 1.2
+++ mod_perl_api.pod 18 Apr 2002 18:13:05 -0000 1.3
@@ -1,8 +1,8 @@
=head1 NAME
-Mod_perl_api - accessing the Apache API via mod_perl
+Accessing the Apache API via mod_perl
-=head1 DESCRIPTION
+=head1 Description
This part of the mod_perl FAQ deals with the Apache Application
Programmer's Interface and how to access it from perl via mod_perl.
@@ -11,7 +11,7 @@
=head2 Did you enable the required hook?
-As described in the mod_perl/INSTALL document, the only callback hook
+As described in the I<mod_perl/INSTALL> document, the only callback hook
enabled by default is PerlHandler. If you want to intervene at a
different stage of request processing you must enable the relevant
hook. So to add a special authentication handler, for instance, you
@@ -29,8 +29,8 @@
If this directive is put in access.conf outside of any restrictive
context, your handler will be called during the given phase of each
request processed by the server. You can make it more selective by
-restricting it to a directory (-hierarchy) in a E<lt>Directory ...E<gt>
-section of access.conf or by putting it in a .htaccess file.
+restricting it to a directory (-hierarchy) in a C<E<lt>Directory ...E<gt>>
+section of access.conf or by putting it in a I<.htaccess> file.
Here is an example of the directives needed to call a handler during
Apache's URI to filename translation phase:
@@ -38,7 +38,7 @@
PerlRequire /full/path/to/script/Trans.pl
PerlTransHandler Trans::handler
-Trans.pl would start with the statement C<Package Trans;> and define a
+I<Trans.pl> would start with the statement C<package Trans;> and define a
subroutine called C<handler>.
=head1 Where can I find examples to get me started?
@@ -105,7 +105,7 @@
Ralf Engelschall writes:
When you compiled one httpd with and the other without mod_perl, then
-you can simply use E<lt>IfModule mod_perl.cE<gt>...E<lt>/IfModuleE<gt>
+you can simply use C<E<lt>IfModule mod_perl.cE<gt>...E<lt>/IfModuleE<gt>>
to surround the stuff for the httpd compiled with mod_perl. The other
then ignores these lines. Example:
1.5 +8 -8 modperl-docs/src/docs/1.0/faqs/mod_perl_cgi.pod
Index: mod_perl_cgi.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_cgi.pod,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- mod_perl_cgi.pod 20 Mar 2002 17:42:05 -0000 1.4
+++ mod_perl_cgi.pod 18 Apr 2002 18:13:05 -0000 1.5
@@ -1,8 +1,8 @@
=head1 NAME
-Mod_perl_cgi - running CGI scripts under mod_perl
+Running CGI scripts under mod_perl
-=head1 DESCRIPTION
+=head1 Description
This part of the mod_perl FAQ deals with questions surrounding CGI
scripts.
@@ -37,8 +37,8 @@
perl -c /path/to/my/mod_perl/scripts/foo
-says it is OK, you have probably used __END__ or __DATA__. Sorry.
-Mod_perl's Apache::Registry can't deal with that.
+says it is OK, you have probably used C<__END__> or C<__DATA__>. Sorry.
+Mod_perl's C<Apache::Registry> can't deal with that.
=head1 My CGI script behaves strangely under mod_perl. Why?
@@ -80,7 +80,7 @@
C<exit()> with C<goto label;>
See also what mod_perl_traps says about C<Apache::exit()> and the way
-that Apache::Registry causes it to terminate the script but not the
+that C<Apache::Registry> causes it to terminate the script but not the
httpd child.
There may be exceptional circumstances in which you explicitly want to
@@ -107,7 +107,7 @@
It is good for you! It will make perl point out all variables that you
have not explicitly declared. You can then think about whether they need
to be global or if they can be lexical. Try to declare things lexically,
-with my(). These variables disappear when the block they are declared in
+with C<my()>. These variables disappear when the block they are declared in
ends, so they don't occupy memory when they are not in use and they also
do not need a run-time symbol table entry.
@@ -158,8 +158,8 @@
=head2 Variables B<still> retain their value from one request to the next
CGI.pm must pull some extra tricks when it is being used via
-Apache::Registry. Versions of CGI.pm before 2.35 did not know this,
-and Apache::Registry will complain if you try to use an earlier
+C<Apache::Registry>. Versions of CGI.pm before 2.35 did not know this,
+and C<Apache::Registry> will complain if you try to use an earlier
version.
CGI.pm detects that it is running under Apache::Registry by looking
1.4 +9 -9 modperl-docs/src/docs/1.0/faqs/mod_perl_cvs.pod
Index: mod_perl_cvs.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_cvs.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- mod_perl_cvs.pod 25 Mar 2002 03:39:00 -0000 1.3
+++ mod_perl_cvs.pod 18 Apr 2002 18:13:05 -0000 1.4
@@ -1,14 +1,14 @@
=head1 NAME
-mod_perl_cvs - Access to the mod_perl CVS development tree
+Access to the mod_perl CVS development tree
-=head1 DESCRIPTION
+=head1 Description
-The mod_perl development tree lives on cvs.apache.org. This tree
+The mod_perl development tree lives on C<cvs.apache.org>. This tree
contains the latest mod_perl bug fixes and developments that have not
made it to CPAN yet. Welcome to the bleeding edge.
-=head1 SYNOPSIS
+=head1 Synopsis
Just as cvs access to the Apache development tree, the mod_perl code
pulled from cvs is not guaranteed to do anything, especially not
@@ -19,7 +19,7 @@
welcome, simply testing the latest snapshots is just as, if not more
helpful.
-It's recommended to subscribe to the I<mo...@perl.apache.org> list,
+It's recommended to subscribe to the L<modperl-cvs|maillist::list-cvs> list,
which is the place cvs commit logs and diffs are mailed to; at least
if you're going to work on the code.
@@ -31,7 +31,7 @@
Cvsup has come out of the FreeBSD group. It's a client/server
beast that offers an efficient way to sync collections of files over
-the net, and it is very CVS aware, allowing syncronisation of repositories
+the net, and it is very CVS aware, allowing synchronisation of repositories
or checked out files using the cvs deltas to bring the client side
files up to date with minimal data transfer.
@@ -72,7 +72,7 @@
cvs -d ":pserver:anoncvs@cvs.apache.org:/home/cvspublic" co modperl
-For a basic introduction to anoncvs see http://dev.apache.org/anoncvs.txt
+For a basic introduction to anoncvs see http://httpd.apache.org/dev/anoncvs.txt
=item from-cvs
@@ -85,11 +85,11 @@
A snapshot of the Apache development tree is also rolled every 6 hours
and placed here:
-http://cvs.apache.org/snapshots/
+http://cvs.apache.org/snapshots/apache-1.3/
=back
-=head1 SEE ALSO
+=head1 See Also
cvs(1)
1.6 +38 -47 modperl-docs/src/docs/1.0/faqs/mod_perl_faq.pod
Index: mod_perl_faq.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_faq.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- mod_perl_faq.pod 20 Mar 2002 17:42:05 -0000 1.5
+++ mod_perl_faq.pod 18 Apr 2002 18:13:05 -0000 1.6
@@ -1,15 +1,15 @@
=head1 NAME
-Mod_perl_faq - frequently asked questions about mod_perl
+Frequently Asked Questions about mod_perl
-=head1 DESCRIPTION
+=head1 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.
-=head1 QUESTIONS & ANSWERS
+=head1 Questions & Answers
=head2 What is mod_perl?
@@ -47,48 +47,45 @@
=item Perl
-http://www.perl.com/CPAN/src/latest.tar.gz
-
-Win32 users note: at the time of writing, ActiveState's Perl cannot be
-used with mod_perl, because it is based on an old version of perl
-(perl-5.003_07, build 316).
+http://www.cpan.org/src/latest.tar.gz
=item Apache
-http://www.apache.org/dist/
+http://httpd.apache.org/dist/
=back
=head2 How do I install it?
Here is the easiest way to proceed. Let's assume you have the latest
-version of perl (5.004) installed. Unpack the Apache and Mod_perl
+version of perl installed. Unpack the Apache and Mod_perl
tarballs next to one another under a common directory: e.g.
% cd /usr/local/src
- % zcat apache_1.2.0.tar.gz | tar xf -
- % zcat mod_perl-0.98_12.tar.gz | tar xf -
+ % zcat apache_1.3.24.tar.gz | tar xf -
+ % zcat mod_perl-1.26.tar.gz | tar xf -
You probably do not need to change anything in the apache configuration
before compiling. Only if you want to enable additional non-standard
-modules do you need to edit apache_1.2.0/src/Configuration. There is no
+modules do you need to edit apache_1.3.24/src/Configuration. There is no
need to set CC, CFLAGS, etc., because mod_perl will override them with the
values that were used to compile your perl.
Now go to the mod_perl directory and follow the instructions in the
-INSTALL file there. If "make test" and "make install" are successful, you
-will find the new web server in apache_1.2.0/src/httpd. Move it to a
+I<INSTALL> file there. If "make test" and "make install" are successful, you
+will find the new web server in apache_1.3.24/src/httpd. Move it to a
suitable location, make sure it has access to the correct configuration
files, and fire it up.
=head2 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: C<perldoc mod_perl>.
+mod_perl you can read it with the command:
+L<perldoc mod_perl|faqs::mod_perl>.
If you are using mod_perl to extend the server functionality, you will
need to read C<perldoc Apache> and the Apache API notes, which can be
-found in apache_1.2.0/htdocs/manual/misc/API.html.
+found in apache_1.3.24/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
@@ -126,23 +123,24 @@
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 Apache-1.2.
+documentation about suEXEC in Apache-1.3.
Alternatively, pre-process the request with mod_perl and fork a suid
helper process to handle the privileged part of the task.
=head2 Why is httpd using so much memory?
-Read the section on "Memory Consumption" in the mod_perl.pod.
+Read the section on "Memory Consumption" in the
+L<mod_perl.pod|faqs::mod_perl/Memory_Consumption>.
Make sure that your scripts are not leaking memory. Global variables
-stay around indefinitely, lexical variables (declared with my()) are
+stay around indefinitely, lexical variables (declared with C<my()>) are
destroyed when they go out of scope, provided there are no references
to them from outside of that scope.
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 a configuration file (e.g. access.conf);
+symbol-tables, use the C<Apache::Status> module. It is enabled by adding
+these lines to a configuration file (e.g. I<httpd.conf>);
<Location /perl-status>
SetHandler perl-script
@@ -165,20 +163,10 @@
=head2 Do I have to restart the server when I change my Perl code?
-Apache::Registry checks the timestamp of scripts that it has loaded
+C<Apache::Registry> checks the timestamp of scripts that it has loaded
and reloads them if they change. This does not happen for other
-handlers, unless you program it yourself. One way to do this is in a
-PerlInitHandler. If you define
-
- sub MY::init {
- delete $INC{"YourModule.pm"};
- require YourModule;
- }
-
-as an init handler, it will unconditionally reload YourModule at the
-start of each request, which may be useful while you are developing a
-new module. It can be made more efficient by storing the timestamp of
-the file in a global variable and only reloading when necessary.
+handlers, unless you program it yourself. You should look into the module
+C<Apache::StatINC> to do this.
=head2 So how do I use mod_perl in conjunction with ErrorDocument?
@@ -268,8 +256,8 @@
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?
+setting for those? How do these cooperate with C<CGI.pm>, C<Apache.pm>,
+C<Apache::Registry>?
=back
@@ -336,7 +324,7 @@
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.
+no-op because that file is already in C<%INC>.
The solution is simple, set up your require'd file something along
these lines:
@@ -345,7 +333,7 @@
sub sub_foo {...}
-Now, have scripts call SomeName::sub_foo() instead of sub_foo().
+Now, have scripts call C<SomeName::sub_foo()> instead of C<sub_foo()>.
=head2 What could be causing sporadic errors "in cleanup"?
@@ -356,10 +344,10 @@
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."
+ "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 C<sub DESTROY { }> in the module that
@@ -373,8 +361,8 @@
$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
+The C<MOD_PERL> variable gets set immediately when the perl interpreter
+starts up, whereas C<GATEWAY_INTERFACE> may not be set yet when C<BEGIN>
blocks are being processed.
=head1 Maintainers
@@ -386,8 +374,11 @@
=item *
-Frank D. Cringle E<lt>fdc@cliwe.ping.deE<gt> or the L<modperl docs
-list|maillist::list-docs-dev>
+Frank D. Cringle E<lt>fdc@cliwe.ping.deE<gt>
+
+=item *
+
+the L<modperl docs list|maillist::list-docs-dev>
=back
1.5 +27 -25 modperl-docs/src/docs/1.0/faqs/mod_perl_method_handlers.pod
Index: mod_perl_method_handlers.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_method_handlers.pod,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- mod_perl_method_handlers.pod 20 Mar 2002 17:42:05 -0000 1.4
+++ mod_perl_method_handlers.pod 18 Apr 2002 18:13:05 -0000 1.5
@@ -1,42 +1,43 @@
=head1 NAME
-mod_perl_method_handlers - How to use mod_perl's MethodHandlers
+How to use mod_perl's MethodHandlers
-=head1 DESCRIPTION
+=head1 Description
Described here are a few examples and hints how to use MethodHandlers
-with modperl.
+with mod_perl.
This document assumes familiarity with at least the I<perltoot>
-manpage and "normal" usage of the Perl*Handlers.
+manpage and "normal" usage of the C<Perl*Handlers>.
-It isn't strictly modperl related, more like "what I use objects for
-in my modperl environment".
+It isn't strictly mod_perl related, more like "what I use objects for
+in my mod_perl environment".
-=head1 SYNOPSIS
+=head1 Synopsis
-If a Perl*Handler is prototyped with '$$', this handler will be
+If a B<Perl*Handler> is prototyped with 'C<$$>', this handler will be
invoked as method, being passed a class name or blessed object as its
first argument and the blessed I<request_rec> as the second argument,
e.g.
package My;
@ISA = qw(BaseClass);
-
+
sub handler ($$) {
my($class, $r) = @_;
...;
}
-
+
package BaseClass;
-
+
sub method ($$) {
my($class, $r) = @_;
...;
}
-
+
__END__
+
Configuration:
PerlHandler My
@@ -50,13 +51,13 @@
PerlHandler My->method
-In this case, the 'My' class inherits this method from 'BaseClass'.
+In this case, the 'C<My>' class inherits this method from 'C<BaseClass>'.
To build in this feature, configure with:
% perl Makefile.PL PERL_METHOD_HANDLERS=1 [PERL_FOO_HOOK=1,etc]
-=head1 WHY?
+=head1 Why?
The short version: For pretty much the same reasons we're using OO
perl everywhere else. :-) See the I<perltoot> manpage.
@@ -64,7 +65,7 @@
The slightly longer version would include some about code reusage and
more clean interface between modules.
-=head1 SIMPLE EXAMPLE
+=head1 Simple example
Let's start with a simple example.
@@ -92,14 +93,14 @@
This::Class=HASH(0x8411edc) isa This::Class
-=head1 A LITTLE MORE ADVANCED
+=head1 A little more advanced
That wasn't really useful, so let's try something little more advanced.
I've a little module which creates a graphical 'datebar' for a client.
-(See C<http://www.hip.dk/date_bar>). It's reading a lot of small gifs
-with numbers and weekdays, and keeping them in memory in GD.pm's native
-format, ready to be copied together and served as gifs.
+It's reading a lot of small gifs with numbers and weekdays, and keeping
+them in memory in GD.pm's native format, ready to be copied together and
+served as gifs.
Now I wanted to use it at another site too, but with a different
look. Obviously something to do with a object. Hence I changed the
@@ -117,7 +118,7 @@
-elements => 'wday hour min',
);
-And then use $Client1::Datebar and $Client2::Datebar as PerlHandlers in my
+And then use C<$Client1::Datebar> and C<$Client2::Datebar> as PerlHandlers in my
Apache configuration. Remember to pass them in literal quotes ('') and not
"" which will be interpolated!
@@ -146,7 +147,7 @@
Very very useful!
-=head1 TRAPS
+=head1 Traps
mod_perl expects object handlers to be in the form of a string, which it
will thaw for you. That means that something like
@@ -166,7 +167,7 @@
}
);
-=head1 AUTHOR
+=head1 Author
This document is written by Ask Bjoern Hansen E<lt>ask@netcetera.dkE<gt> or
E<lt>ask@apache.orgE<gt>. Corrections and suggestions are most
@@ -176,9 +177,9 @@
Some codesnippets is from Doug MacEachern.
-=head1 SEE ALSO
+=head1 See Also
-The L<faqs::mod_perl>, the I<Apache>, the I<perltoot> manpages (also
+The L<mod_per|faqs::mod_perl>, the I<Apache>, the I<perltoot> manpages (also
available at C<http://www.perl.com/CPAN/doc/FMTEYEWTK/perltoot.html>)
=head1 Maintainers
@@ -200,7 +201,8 @@
=item *
-Doug MacEachern
+Ask Bjoern Hansen, E<lt>ask (at) netcetera.dkE<gt> or E<lt>ask (at)
+apache.orgE<gt>.
=back
1.4 +37 -33 modperl-docs/src/docs/1.0/faqs/mod_perl_traps.pod
Index: mod_perl_traps.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_traps.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- mod_perl_traps.pod 20 Mar 2002 17:42:05 -0000 1.3
+++ mod_perl_traps.pod 18 Apr 2002 18:13:05 -0000 1.4
@@ -1,8 +1,11 @@
=head1 NAME
-mod_perl_traps - common/known mod_perl traps
+Common/Known mod_perl traps
-=head1 DESCRIPTION
+=head1 Description
+
+All the features of mod_perl bring with them some common traps. This
+document tries to tell you what they are and how to avoid them.
In the CGI environment, the server starts a single external process
(Perl interpreter) per HTTP request which runs single script in that
@@ -35,7 +38,8 @@
=item *
-Apache::Registry scripts cannot contain __END__ or __DATA__ tokens
+C<Apache::Registry> scripts cannot contain C<__END__> or C<__DATA__>
+tokens.
=item *
@@ -44,15 +48,15 @@
=item *
-Perl's exit() built-in function cannot be used in mod_perl scripts.
-The Apache::exit() function should be used instead. Apache::exit()
-automatically overrides the built-in exit() for Apache::Registry
-and Apache::PerlRun scripts.
+Perl's C<exit()> built-in function cannot be used in mod_perl scripts.
+The C<Apache::exit()> function should be used instead. C<Apache::exit()>
+automatically overrides the built-in C<exit()> for Apache::Registry
+and C<Apache::PerlRun> scripts.
=item *
-Your script *will not* run from the command line if your script makes
-any direct calls to Apache-E<gt>methods. See Apache::FakeRequest.
+Your script B<will not> run from the command line if your script makes
+any direct calls to C<Apache-E<gt>methods>. See C<Apache::FakeRequest>.
=back
@@ -60,7 +64,7 @@
=over 4
-=item undefined subroutine &Apache::Registry::handler
+=item undefined subroutine C<&Apache::Registry::handler>
Interaction with certain modules causes the shortcut configuration to
break, if you see this message change your configuration from this:
@@ -86,13 +90,13 @@
=item *
-CGI.pm users B<must> have version B<2.39> of the package or higher,
+C<CGI.pm> users B<must> have version B<2.39> of the package or higher,
earlier versions will not work under mod_perl.
=item *
If you use the C<SendHeaders()> function, be sure to call
-$req_obj-E<gt>cgi-E<gt>done when you are done with a request, just as you
+C<$req_obj-E<gt>cgi-E<gt>done> when you are done with a request, just as you
would under I<CGI::MiniSrv>.
=back
@@ -105,7 +109,7 @@
=item *
Files pulled in via C<use> or C<require> statements are not
-automatically reloaded when changed on disk. See the Apache::StatINC
+automatically reloaded when changed on disk. See the C<Apache::StatINC>
module to add this functionality.
=item Undefined subroutines
@@ -133,17 +137,17 @@
#required_file.pl
package Test;
-
+
sub some_function {...}
-
+
...
-
+
__END__
Now, have your scripts say:
require "required_file.pl";
-
+
Test::some_function();
@@ -170,17 +174,17 @@
"Out of memory!" message and or "Callback called exit". A common
cause of this are never-ending loops, deep recursion or calling an
undefined subroutine. Here's one way to catch the problem:
-See Perl's INSTALL document for this item:
+See Perl's I<INSTALL> document for this item:
=item -DPERL_EMERGENCY_SBRK
-If PERL_EMERGENCY_SBRK is defined, running out of memory need not be a
+If C<PERL_EMERGENCY_SBRK> is defined, running out of memory need not be a
fatal error: a memory pool can allocated by assigning to the special
-variable $^M. See perlvar(1) for more details.
+variable C<$^M>. See perlvar(1) for more details.
-If you compile with that option and add 'use Apache::Debug level =E<gt> 4;'
-to your PerlScript, it will allocate the $^M emergency pool and the
-$SIG{__DIE__} handler will call Carp::confess, giving you a stack
+If you compile with that option and add 'C<use Apache::Debug level =E<gt> 4;>'
+to your PerlScript, it will allocate the C<$^M> emergency pool and the
+C<$SIG{__DIE__}> handler will call C<Carp::confess>, giving you a stack
trace which should reveal where the problem is.
See the B<Apache::Resource> module for prevention of spinning httpds.
@@ -191,7 +195,7 @@
Perl, it must be listed in static_ext in Perl's Config.pm to be linked
with httpd during the mod_perl build.
-=item Can't load '$Config{sitearchexp}/auto/Foo/Foo.so' for module Foo...
+=item Can't load 'C<$Config{sitearchexp}/auto/Foo/Foo.so>' for module Foo...
When starting httpd some people have reported seeing an error along
the lines of:
@@ -203,7 +207,7 @@
Perl_sv_undef: referenced symbol not found at
/usr/local/ap/lib/perl5/sun4-solaris/5.00404/DynaLoader.pm line 166.
-Or similar for the IO module or whatever dynamic module mod_perl tries
+Or similar for the C<IO> module or whatever dynamic module mod_perl tries
to pull in first. The solution is to re-configure, re-build and
re-install Perl and dynamic modules with the following flags when
Configure asks for "additional LD flags":
@@ -220,7 +224,7 @@
OS distributions that ship with a (broken) binary Perl installation.
-The `perl' program and `libperl.a' library are somehow built with
+The `I<perl>' program and `I<libperl.a>' library are somehow built with
different binary compatiblity flags.
The solution to these problems is to rebuild Perl and extension
@@ -230,7 +234,7 @@
% ./Configure -des -Dcc=gcc ... && make test && make install
-Read Perl's INSTALL doc for more details.
+Read Perl's I<INSTALL> doc for more details.
=back
@@ -258,7 +262,7 @@
libs='-lnet -lnsl_s -lgdbm -lndbm -ldb -ldld -lm -lc -lndir -lcrypt';
-Edit B<Config.pm> and move C<-lgdbm> and C<-ldb> to the end of the
+Edit C<Config.pm> and move C<-lgdbm> and C<-ldb> to the end of the
list. Here's how to find B<Config.pm>:
% perl -MConfig -e 'print "$Config{archlibexp}/Config.pm\n"'
@@ -268,7 +272,7 @@
Solaris already provides its own DBM and NDBM, and there's no reason
to build GDBM with them (for us anyway).
-In our Makefile for GDBM, we changed
+In our I<Makefile> for GDBM, we changed
OBJS = $(DBM_OF) $(NDBM_OF) $(GDBM_OF)
@@ -276,13 +280,13 @@
OBJS = $(GDBM_OF)
-Rebuild libgdbm, then Apache/mod_perl.
+Rebuild I<libgdbm>, then Apache/mod_perl.
=back
-=head1 REGULAR EXPRESSIONS
+=head1 Regular expressions
-=head2 COMPILED REGULAR EXPRESSIONS
+=head2 Compiled regular expressions
When using a regular expression that contains an interpolated Perl variable,
if it is known that the variable (or variables) will not vary during the
@@ -343,7 +347,7 @@
The only gotcha is that the dummy match that boots the regular expression
engine must absolutely, positively succeed, otherwise the pattern will not
-be cached, and the // will match everything. If you can't count on fixed
+be cached, and the C<//> will match everything. If you can't count on fixed
text to ensure the match succeeds, you have two possibilities.
If you can guaranteee that the pattern variable contains no meta-characters
1.5 +22 -23 modperl-docs/src/docs/1.0/faqs/mod_perl_tuning.pod
Index: mod_perl_tuning.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/mod_perl_tuning.pod,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- mod_perl_tuning.pod 20 Mar 2002 17:42:05 -0000 1.4
+++ mod_perl_tuning.pod 18 Apr 2002 18:13:05 -0000 1.5
@@ -1,8 +1,8 @@
=head1 NAME
-mod_perl_tuning - mod_perl performance tuning
+mod_perl performance tuning
-=head1 DESCRIPTION
+=head1 Description
Described here are examples and hints on how to configure a mod_perl
enabled Apache server, concentrating on tips for configuration for
@@ -22,16 +22,16 @@
such as The Weather Channel's "Blimp Site-ings" game, the MSIE 4.0
"Subscribe to Win" game, and the MSN Million Dollar Madness game.
-=head1 BASIC CONFIGURATION
+=head1 Basic Configuration
The basic configuration for mod_perl is as follows. In the
F<httpd.conf> file, I add configuration parameters to make the
C<http://www.example.com/programs> URL be the base location for all
mod_perl programs. Thus, access to
C<http://www.example.com/programs/printenv> will run the printenv
-script, as we'll see below. Also, any *.perl file will be interpreted
+script, as we'll see below. Also, any I<*.perl> file will be interpreted
as a mod_perl program just as if it were in the programs directory,
-and *.rperl will be mod_perl, but I<without> any HTTP headers
+and I<*.rperl> will be mod_perl, but I<without> any HTTP headers
automatically sent; you must do this explicitly. If you don't want
these last two, just leave it out of your configuration.
@@ -158,7 +158,7 @@
When you run this, check the value of the GATEWAY_INTERFACE variable
to see that you are indeed running mod_perl.
-=head1 REDUCING MEMORY USE
+=head1 Reducing Memory Use
As a side effect of using mod_perl, your HTTPD processes will be
larger than without it. There is just no way around it, as you have
@@ -196,7 +196,7 @@
have set the C<PerlFreshRestart> configuration parameter in
F<httpd.conf> to be "On".
-=head1 REDUCING THE NUMBER OF LARGE PROCESSES
+=head1 Reducing the Number of Large Processes
Unfortunately, simply reducing the size of each HTTPD process is not
enough on a very busy site. You also need to reduce the quantity of
@@ -224,7 +224,7 @@
of a challenge when you have multiple servers running on the same
host, since you must log to different files.
-=head2 TWO MACHINES
+=head2 Two Machines
The simplest way is to put all static content on one machine, and all
mod_perl programs on another. The only trick is to make sure all
@@ -237,7 +237,7 @@
The drawback is that you must maintain two machines, and this can get
expensive. For extremely large projects, this is the best way to go.
-=head2 TWO IP ADDRESSES
+=head2 Two IP Addresses
Similar to above, but one HTTPD runs bound to one IP address, while
the other runs bound to another IP address. The only difference is
@@ -250,7 +250,7 @@
to make each HTTPD respond only to one IP address on this host. One
will have mod_perl enabled, and the other will not.
-=head2 TWO PORT NUMBERS
+=head2 Two Port Numbers
If you cannot get two IP addresses, you can also split the HTTPD
processes as above by putting one on the standard port 80, and the
@@ -269,7 +269,7 @@
Thanks to Gerd Knops for this idea.
-=head2 USING ProxyPass WITH TWO SERVERS
+=head2 Using ProxyPass with two servers
To overcome the limitation of the alternate port above, you can use
dual Apache HTTPD servers with just slight difference in
@@ -284,21 +284,21 @@
that you have included the mod_proxy module in your server when it was
built.
-Now, when you access http://www.example.com/programs/printenv it will
+Now, when you access I<http://www.example.com/programs/printenv> it will
internally be passed through to your HTTPD running on port 8042 as the
-URL http://localhost:8042/programs/printenv and the result relayed
+URL I<http://localhost:8042/programs/printenv> and the result relayed
back transparently. To the client, it all seems as if it is just one
server running. This can also be used on the dual-host version to
hide the second server from view if desired.
-=begin html
-<P>
+=for html
+<p>
A complete configuration example of this technique is provided by
two HTTPD configuration files.
-<A HREF="httpd.conf.txt">httpd.conf</A> is for the main server for all
-regular pages, and <A HREF="httpd%2bperl.conf.txt">httpd+perl.conf</A> is
-for the mod_perl programs accessed in the <CODE>/programs</CODE> URL.
-</P>
+<a href="httpd.conf.txt">httpd.conf</a> is for the main server for all
+regular pages, and <a href="httpd%2bperl.conf.txt">httpd+perl.conf</a> is
+for the mod_perl programs accessed in the <code>/programs</code> URL.
+</p>
The directory structure assumes that F</var/www/documents> is the
C<DocumentRoot> directory, and the the mod_perl programs are in
@@ -308,15 +308,14 @@
daemon httpd
daemon httpd -f conf/httpd+perl.conf
-=end html
Thanks to Bowen Dwelle for this idea.
-=head2 SQUID ACCELERATOR
+=head2 Squid Accelerator
Another approach to reducing the number of large HTTPD processes on
one machine is to use an accelerator such as Squid (which can be found
-at http://squid.nlanr.net/Squid/ on the web) between the clients and
+at http://www.squid-cache.org/ on the web) between the clients and
your large mod_perl HTTPD processes. The idea here is that squid will
handle the static objects from its cache while the HTTPD processes
will handle mostly just the mod_perl requests once the cache is
@@ -384,7 +383,7 @@
ftp://ftp.netcetera.dk/pub/apache/ to make it insert the
C<X-Forwarded-For> header.
-=head1 SUMMARY
+=head1 Summary
To gain maximal performance of mod_perl on a busy site, one must
reduce the amount of resources used by the HTTPD to fit within what
1.6 +6 -6 modperl-docs/src/docs/1.0/faqs/perl_myth.pod
Index: perl_myth.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/faqs/perl_myth.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- perl_myth.pod 20 Mar 2002 17:42:05 -0000 1.5
+++ perl_myth.pod 18 Apr 2002 18:13:05 -0000 1.6
@@ -13,11 +13,11 @@
=item *
-M = Misconception or Myth
+B<M> = Misconception or Myth
=item *
-R = Response
+B<R> = Response
=back
@@ -109,11 +109,11 @@
=item *
-B<Vivek Khera's mod_perl performance tuning guide>( http://perl.apache.org/tuning/ )
+L<Vivek Khera's mod_perl performance tuning guide|faqs::mod_perl_tuning>
=item *
-B<Stas Bekman's Performance Guide>( http://perl.apache.org/guide/performance.html )
+L<Stas Bekman's Performance Guide|guide::performance>
=back
@@ -243,7 +243,7 @@
=back
-=head1 CREDITS
+=head1 Credits
Thanks to the mod_perl list for all of the good information and
criticism. I'd especially like to thank,
@@ -303,7 +303,7 @@
=item *
-Contact the L<modperl docs list|maillist::list-docs-dev>
+Contact the L<mod_perl docs list|maillist::list-docs-dev>
=back
1.1 modperl-docs/src/docs/1.0/faqs/httpd+perl.conf.txt
Index: httpd+perl.conf.txt
===================================================================
# This is the main server configuration file. See URL http://www.apache.org/
# for instructions.
# This configuration only handles the mod_perl requests in /programs and
# /rprograms under directory /var/www. Assumes it is redirected from
# httpd running on port 80 via ProxyPass.
ServerType standalone
Port 8042
HostnameLookups off
User www
Group www
# The following directive disables keepalives and HTTP header flushes for
# Netscape 2.x and browsers which spoof it. There are known problems with
# these
BrowserMatch Mozilla/2 nokeepalive
# work around bugs in MSIE 4.0
BrowserMatch "MSIE 4\.0b2;" nokeepalive force-response-1.0 downgrade-1.0
# ServerAdmin: Your address, where problems with the server should be
# e-mailed.
ServerAdmin webmaster@www.domain.com
# ServerRoot: The directory the server's config, error, and log files
# are kept in
ServerRoot /var/www
# ErrorLog: The location of the error log file. If this does not start
# with /, ServerRoot is prepended to it.
ErrorLog /var/log/httpd/error_log_perl
# TransferLog: The location of the transfer log file. If this does not
# start with /, ServerRoot is prepended to it.
TransferLog /var/log/httpd/access_log_perl
# PidFile: The file the server should log its pid to
PidFile /var/run/httpd+perl.pid
ServerName www.domain.com
# CacheNegotiatedDocs: By default, Apache sends Pragma: no-cache with each
# document that was negotiated on the basis of content. This asks proxy
# servers not to cache the document. Uncommenting the following line disables
# this behavior, and proxies will be allowed to cache the documents.
#CacheNegotiatedDocs
# Timeout: The number of seconds before receives and sends time out
Timeout 300
# KeepAlive: Whether or not to allow persistent connections (more than
# one request per connection). Set to "Off" to deactivate.
KeepAlive Off
# Server-pool size regulation. Rather than making you guess how many
# server processes you need, Apache dynamically adapts to the load it
# sees --- that is, it tries to maintain enough server processes to
# handle the current load, plus a few spare servers to handle transient
# load spikes (e.g., multiple simultaneous requests from a single
# Netscape browser).
# It does this by periodically checking how many servers are waiting
# for a request. If there are fewer than MinSpareServers, it creates
# a new spare. If there are more than MaxSpareServers, some of the
# spares die off. These values are probably OK for most sites ---
MinSpareServers 5
MaxSpareServers 10
# Number of servers to start --- should be a reasonable ballpark figure.
StartServers 5
# Limit on total number of servers running, i.e., limit on the number
# of clients who can simultaneously connect --- if this limit is ever
# reached, clients will be LOCKED OUT, so it should NOT BE SET TOO LOW.
# It is intended mainly as a brake to keep a runaway server from taking
# Unix with it as it spirals down...
MaxClients 30
# MaxRequestsPerChild: the number of requests each child process is
# allowed to process before the child dies.
# The child will exit so as to avoid problems after prolonged use when
# Apache (and maybe the libraries it uses) leak. On most systems, this
# isn't really needed, but a few (such as Solaris) do have notable leaks
# in the libraries.
MaxRequestsPerChild 50
# combine access.conf right here
AccessConfig /dev/null
# access.conf: Global access configuration
# Online docs at http://www.apache.org/
# prevent Apache from searching for htaccess.conf files below document root
<Directory />
AllowOverride None
order deny,allow
deny from all
</Directory>
# put mod_perl programs here
# startup.perl loads all functions that we want to use within mod_perl
PerlScript /var/www/perllib/startup.perl
<Directory /var/www/programs>
AllowOverride None
Options ExecCGI FollowSymLinks
SetHandler perl-script
PerlHandler Apache::Registry
PerlSendHeader On
order allow,deny
allow from all
</Directory>
# like above but no HTTP headers
<Directory /var/www/rprograms>
AllowOverride None
Options ExecCGI FollowSymLinks
SetHandler perl-script
PerlHandler Apache::Registry
order allow,deny
allow from all
</Directory>
# allow arbitrary *.perl files to be scattered throughout the site.
<Files *.perl>
SetHandler perl-script
PerlHandler Apache::Registry
PerlSendHeader On
Options ExecCGI
</Files>
# like *.perl, but no PerlSendHeader
<Files *.rperl>
SetHandler perl-script
PerlHandler Apache::Registry
PerlSendHeader Off
Options ExecCGI
</Files>
<Location /perl-status>
SetHandler perl-script
PerlHandler Apache::Status
order deny,allow
deny from all
allow from allow from 204.117.82.
</Location>
<Location /server-status>
SetHandler server-status
order deny,allow
deny from all
allow from allow from 204.117.82.
</Location>
<Location /server-info>
SetHandler server-info
order deny,allow
deny from all
allow from allow from 204.117.82.
</Location>
# combine srm.conf here
ResourceConfig /dev/null
DocumentRoot /var/www
UserDir disable
# DirectoryIndex: Name of the file or files to use as a pre-written HTML
# directory index. Separate multiple entries with spaces.
DirectoryIndex index.html
# FancyIndexing is whether you want fancy directory indexing or standard
FancyIndexing on
# AddIcon tells the server which icon to show for different files or filename
# extensions
AddIconByEncoding (CMP,/icons/compressed.gif) x-compress x-gzip
AddIconByType (TXT,/icons/text.gif) text/*
AddIconByType (IMG,/icons/image2.gif) image/*
AddIconByType (SND,/icons/sound2.gif) audio/*
AddIconByType (VID,/icons/movie.gif) video/*
AddIcon /icons/binary.gif .bin .exe
AddIcon /icons/binhex.gif .hqx
AddIcon /icons/tar.gif .tar
AddIcon /icons/world2.gif .wrl .wrl.gz .vrml .vrm .iv
AddIcon /icons/compressed.gif .Z .z .tgz .gz .zip
AddIcon /icons/a.gif .ps .ai .eps
AddIcon /icons/layout.gif .html .shtml .htm .pdf
AddIcon /icons/text.gif .txt
AddIcon /icons/c.gif .c
AddIcon /icons/p.gif .pl .py
AddIcon /icons/f.gif .for
AddIcon /icons/dvi.gif .dvi
AddIcon /icons/uuencoded.gif .uu
AddIcon /icons/script.gif .conf .sh .shar .csh .ksh .tcl
AddIcon /icons/tex.gif .tex
AddIcon /icons/bomb.gif core
AddIcon /icons/back.gif ..
AddIcon /icons/hand.right.gif README
AddIcon /icons/folder.gif ^^DIRECTORY^^
AddIcon /icons/blank.gif ^^BLANKICON^^
# DefaultIcon is which icon to show for files which do not have an icon
# explicitly set.
DefaultIcon /icons/unknown.gif
# AddDescription allows you to place a short description after a file in
# server-generated indexes.
# Format: AddDescription "description" filename
ReadmeName README
HeaderName HEADER
IndexIgnore */.??* *~ *# */HEADER* */README* */RCS *.conf
AccessFileName htaccess.conf
DefaultType text/plain
AddEncoding x-compress Z
AddEncoding x-gzip gz
Alias /icons/ /var/www/icons/
# To use CGI scripts:
AddHandler cgi-script .cgi
# To use server-parsed HTML files
AddType text/html .shtml
AddHandler server-parsed .shtml
# Uncomment the following line to enable Apache's send-asis HTTP file
# feature
#AddHandler send-as-is asis
# If you wish to use server-parsed imagemap files, use
AddHandler imap-file map
# To enable type maps, you might want to use
#AddHandler type-map var
# Action lets you define media types that will execute a script whenever
# a matching file is called. This eliminates the need for repeated URL
# pathnames for oft-used CGI file processors.
# Format: Action media/type /cgi-script/location
# Format: Action handler-name /cgi-script/location
# Customizable error response (Apache style)
# these come in three flavors
#
# 1) plain text
#ErrorDocument 500 "The server made a boo boo.
# n.b. the (") marks it as text, it does not get output
#
# 2) local redirects
#ErrorDocument 404 /missing.html
# to redirect to local url /missing.html
#ErrorDocument 404 /cgi-bin/missing_handler.pl
# n.b. can redirect to a script or a document using server-side-includes.
#
# 3) external redirects
#ErrorDocument 402 http://some.other_server.com/subscription_info.html
#
1.1 modperl-docs/src/docs/1.0/faqs/httpd.conf.txt
Index: httpd.conf.txt
===================================================================
# This is the main server configuration file. See URL http://www.apache.org/
# for instructions.
ServerType standalone
Port 80
HostnameLookups off
User www
Group www
# The following directive disables keepalives and HTTP header flushes for
# Netscape 2.x and browsers which spoof it. There are known problems with
# these
BrowserMatch Mozilla/2 nokeepalive
# work around bugs in MSIE 4.0
BrowserMatch "MSIE 4\.0b2;" nokeepalive force-response-1.0 downgrade-1.0
# ServerAdmin: Your address, where problems with the server should be
# e-mailed.
ServerAdmin webmaster@www.domain.com
# ServerRoot: The directory the server's config, error, and log files
# are kept in
ServerRoot /var/www
# ErrorLog: The location of the error log file. If this does not start
# with /, ServerRoot is prepended to it.
ErrorLog /var/log/httpd/error_log
# TransferLog: The location of the transfer log file. If this does not
# start with /, ServerRoot is prepended to it.
TransferLog /var/log/httpd/access_log
# PidFile: The file the server should log its pid to
PidFile /var/run/httpd.pid
ServerName www.domain.com
# CacheNegotiatedDocs: By default, Apache sends Pragma: no-cache with each
# document that was negotiated on the basis of content. This asks proxy
# servers not to cache the document. Uncommenting the following line disables
# this behavior, and proxies will be allowed to cache the documents.
#CacheNegotiatedDocs
# Timeout: The number of seconds before receives and sends time out
Timeout 300
# KeepAlive: Whether or not to allow persistent connections (more than
# one request per connection). Set to "Off" to deactivate.
KeepAlive On
# MaxKeepAliveRequests: The maximum number of requests to allow
# during a persistent connection. Set to 0 to allow an unlimited amount.
# We reccomend you leave this number high, for maximum performance.
MaxKeepAliveRequests 100
# KeepAliveTimeout: Number of seconds to wait for the next request
KeepAliveTimeout 15
# Server-pool size regulation. Rather than making you guess how many
# server processes you need, Apache dynamically adapts to the load it
# sees --- that is, it tries to maintain enough server processes to
# handle the current load, plus a few spare servers to handle transient
# load spikes (e.g., multiple simultaneous requests from a single
# Netscape browser).
# It does this by periodically checking how many servers are waiting
# for a request. If there are fewer than MinSpareServers, it creates
# a new spare. If there are more than MaxSpareServers, some of the
# spares die off. These values are probably OK for most sites ---
MinSpareServers 5
MaxSpareServers 10
# Number of servers to start --- should be a reasonable ballpark figure.
StartServers 5
# Limit on total number of servers running, i.e., limit on the number
# of clients who can simultaneously connect --- if this limit is ever
# reached, clients will be LOCKED OUT, so it should NOT BE SET TOO LOW.
# It is intended mainly as a brake to keep a runaway server from taking
# Unix with it as it spirals down...
MaxClients 100
# MaxRequestsPerChild: the number of requests each child process is
# allowed to process before the child dies.
# The child will exit so as to avoid problems after prolonged use when
# Apache (and maybe the libraries it uses) leak. On most systems, this
# isn't really needed, but a few (such as Solaris) do have notable leaks
# in the libraries.
MaxRequestsPerChild 400
# combine access.conf right here
AccessConfig /dev/null
# access.conf: Global access configuration
# Online docs at http://www.apache.org/
# prevent Apache from searching for htaccess.conf files below document root
<Directory />
AllowOverride None
order deny,allow
deny from all
</Directory>
# main directory access
<Directory /var/www/documents>
Options Includes FollowSymLinks
AllowOverride All
order allow,deny
allow from all
</Directory>
#<Directory /var/www/documents/cgi-bin>
# AllowOverride None
# Options +ExecCGI
# DefaultType application/x-httpd-cgi
#</Directory>
<Location /server-status>
SetHandler server-status
order deny,allow
deny from all
allow from allow from 204.117.82.
</Location>
<Location /server-info>
SetHandler server-info
order deny,allow
deny from all
allow from allow from 204.117.82.
</Location>
# if we get request for program, just pass to perl-enabled httpd
ProxyPass /programs http://localhost:8042/programs
ProxyPass /rprograms http://localhost:8042/rprograms
# combine srm.conf here
ResourceConfig /dev/null
DocumentRoot /var/www/documents
#UserDir www
# DirectoryIndex: Name of the file or files to use as a pre-written HTML
# directory index. Separate multiple entries with spaces.
DirectoryIndex index.html index.shtml
# FancyIndexing is whether you want fancy directory indexing or standard
FancyIndexing on
# AddIcon tells the server which icon to show for different files or filename
# extensions
AddIconByEncoding (CMP,/icons/compressed.gif) x-compress x-gzip
AddIconByType (TXT,/icons/text.gif) text/*
AddIconByType (IMG,/icons/image2.gif) image/*
AddIconByType (SND,/icons/sound2.gif) audio/*
AddIconByType (VID,/icons/movie.gif) video/*
AddIcon /icons/binary.gif .bin .exe
AddIcon /icons/binhex.gif .hqx
AddIcon /icons/tar.gif .tar
AddIcon /icons/world2.gif .wrl .wrl.gz .vrml .vrm .iv
AddIcon /icons/compressed.gif .Z .z .tgz .gz .zip
AddIcon /icons/a.gif .ps .ai .eps
AddIcon /icons/layout.gif .html .shtml .htm .pdf
AddIcon /icons/text.gif .txt
AddIcon /icons/c.gif .c
AddIcon /icons/p.gif .pl .py
AddIcon /icons/f.gif .for
AddIcon /icons/dvi.gif .dvi
AddIcon /icons/uuencoded.gif .uu
AddIcon /icons/script.gif .conf .sh .shar .csh .ksh .tcl
AddIcon /icons/tex.gif .tex
AddIcon /icons/bomb.gif core
AddIcon /icons/back.gif ..
AddIcon /icons/hand.right.gif README
AddIcon /icons/folder.gif ^^DIRECTORY^^
AddIcon /icons/blank.gif ^^BLANKICON^^
# DefaultIcon is which icon to show for files which do not have an icon
# explicitly set.
DefaultIcon /icons/unknown.gif
# AddDescription allows you to place a short description after a file in
# server-generated indexes.
# Format: AddDescription "description" filename
ReadmeName README
HeaderName HEADER
IndexIgnore */.??* *~ *# */HEADER* */README* */RCS *.conf
AccessFileName htaccess.conf
DefaultType text/plain
AddEncoding x-compress Z
AddEncoding x-gzip gz
Alias /icons/ /var/www/icons/
# To use CGI scripts:
AddHandler cgi-script .cgi
# To use server-parsed HTML files
AddType text/html .shtml
AddHandler server-parsed .shtml
# Uncomment the following line to enable Apache's send-asis HTTP file
# feature
#AddHandler send-as-is asis
# If you wish to use server-parsed imagemap files, use
AddHandler imap-file map
# To enable type maps, you might want to use
#AddHandler type-map var
# Action lets you define media types that will execute a script whenever
# a matching file is called. This eliminates the need for repeated URL
# pathnames for oft-used CGI file processors.
# Format: Action media/type /cgi-script/location
# Format: Action handler-name /cgi-script/location
# Customizable error response (Apache style)
# these come in three flavors
#
# 1) plain text
#ErrorDocument 500 "The server made a boo boo.
# n.b. the (") marks it as text, it does not get output
#
# 2) local redirects
#ErrorDocument 404 /missing.html
# to redirect to local url /missing.html
#ErrorDocument 404 /cgi-bin/missing_handler.pl
# n.b. can redirect to a script or a document using server-side-includes.
#
# 3) external redirects
#ErrorDocument 402 http://some.other_server.com/subscription_info.html
#
1.12 +1 -1 modperl-docs/src/docs/1.0/guide/Changes.pod
Index: Changes.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/1.0/guide/Changes.pod,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- Changes.pod 17 Apr 2002 04:34:45 -0000 1.11
+++ Changes.pod 18 Apr 2002 18:13:05 -0000 1.12
@@ -1,6 +1,6 @@
=head1 NAME
-CHANGES
+Changes
=head1 Description
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org