You are viewing a plain text version of this content. The canonical link for it is here.
Posted to modperl-cvs@perl.apache.org by sb...@hyperreal.org on 1999/05/08 19:46:49 UTC
cvs commit: modperl-site/guide CHANGES all.html config.html control.html debug.html frequent.html guide-src.tar.gz guide.tar.gz help.html index.html intro.html modules.html multiuser.html obvious.html performance.html perl.html porting.html scenario.html snippets.html start.html status.html style.css warnings.html
sbekman 99/05/08 10:46:46
Modified: guide CHANGES all.html config.html control.html
debug.html frequent.html guide-src.tar.gz
guide.tar.gz help.html index.html intro.html
modules.html multiuser.html obvious.html
performance.html perl.html porting.html
scenario.html snippets.html start.html status.html
style.css warnings.html
Log:
* control.pod: SUID start-up scripts (Lincoln Stein)
* porting.pod: Forking subprocesses from mod_per (Philp Gwyn)
* added to performance.pod: CGI.pm\'s object methods calls
vs. function calls
* new pod: browserbugs.pod - Workarounds for some known bugs in browsers.
added: Preventing QUERY_STRING to get corrupted with &entity key
names.
added: IE 4.x does not re-post data to a non-port-80 URL
* strategy.pod: updated notes about squid (Andreas J. Koenig)
* strategy.pod and scenario.pod started the ProxyPass sections (Mark
Mills, Ken Williams, Ask Bjoern Hansen)
* wrote a code to validate a pod L<> directive, by first building a
hash of all available achors and hash of all L<> directives, then
reporting the broken links! This is cool! TomC will never accept the
patch to his Pod2Html.pm :( So there is no broken links anymore,
unless I forgot to run the checker :)
* start.pod now contains an overview of the guide. The previous
content migrated to install.pod and download.pod. Part of the
scenario.pod moved to install.pod.
* people still report problems with CSS I use, I made more tweaking by
deleting almost all styles. Seems people are missing some basic
fonts families and complaining about being unable to read the text.
* strategy.pod: using thttpd instead of plain apache (Rauznitz Balazs)
* scenario.pod: was splitted into strategy.pod and
scenario.pod. strategy.pod now only talks about different
approaches, while scenario.pod provides the building and
configuration details. strategy.pod tries clearly to state the pros
and cons of each approach (please review)
* Introduced a new dbm.pod: mod_perl and dbm files (please review)
* Introduced a new databases.pod: mod_perl and Relational Databases
(please review)
* The whole expanded table of contents now can be found in index.html
- (index.html now being generated by script). Should make
navigation much easier.
* The last html sources file has gone, now all src files are pods.
* Improved search engines requirements: Extended <META
NAME="Description"> and <META NAME="keywords">
* Improved navigation : added Next, Main. Previous links.
* Improved navigation : now index.html includes a linked Table Of
Contents of the whole guide, not only the page titles.
* Added another list archive (help.html):
http://www.geocrawler.com/lists/3/web/182/0/ (Eric Cholet)
* obvious.pod: "Setting environment variables for scripts called from
CGI." (Lincoln Stein, Doug MacEachern)
* extended the "Using $|=1 under mod_perl and better print()
techniques" at performace.pod.
Revision Changes Path
1.10 +85 -114 modperl-site/guide/CHANGES
Index: CHANGES
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/CHANGES,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- CHANGES 1999/04/19 19:53:27 1.9
+++ CHANGES 1999/05/08 17:46:26 1.10
@@ -1,169 +1,197 @@
This is a CHANGES file for mod_perl guide
+05.08.99 ver 1.10
-04.19.99
+* control.pod: SUID start-up scripts (Lincoln Stein)
+* porting.pod: Forking subprocesses from mod_per (Philp Gwyn)
+* added to performance.pod: CGI.pm\'s object methods calls
+ vs. function calls
+
+* new pod: browserbugs.pod - Workarounds for some known bugs in browsers.
+ added: Preventing QUERY_STRING to get corrupted with &entity key
+ names.
+ added: IE 4.x does not re-post data to a non-port-80 URL
+
+* strategy.pod: updated notes about squid (Andreas J. Koenig)
+
+* strategy.pod and scenario.pod started the ProxyPass sections (Mark
+ Mills, Ken Williams, Ask Bjoern Hansen)
+
+* wrote a code to validate a pod L<> directive, by first building a
+ hash of all available achors and hash of all L<> directives, then
+ reporting the broken links! This is cool! TomC will never accept the
+ patch to his Pod2Html.pm :( So there is no broken links anymore,
+ unless I forgot to run the checker :)
+
+* start.pod now contains an overview of the guide. The previous
+ content migrated to install.pod and download.pod. Part of the
+ scenario.pod moved to install.pod.
+
+* people still report problems with CSS I use, I made more tweaking by
+ deleting almost all styles. Seems people are missing some basic
+ fonts families and complaining about being unable to read the text.
+
+* strategy.pod: using thttpd instead of plain apache (Rauznitz Balazs)
+
+* scenario.pod: was splitted into strategy.pod and
+ scenario.pod. strategy.pod now only talks about different
+ approaches, while scenario.pod provides the building and
+ configuration details. strategy.pod tries clearly to state the pros
+ and cons of each approach (please review)
+
+* Introduced a new dbm.pod: mod_perl and dbm files (please review)
+
+* Introduced a new databases.pod: mod_perl and Relational Databases
+ (please review)
+
+* The whole expanded table of contents now can be found in index.html
+ - (index.html now being generated by script). Should make
+ navigation much easier.
+
+* The last html sources file has gone, now all src files are pods.
+
+* Improved search engines requirements: Extended <META
+ NAME="Description"> and <META NAME="keywords">
+
+* Improved navigation : added Next, Main. Previous links.
+
+* Improved navigation : now index.html includes a linked Table Of
+ Contents of the whole guide, not only the page titles.
+
+* Added another list archive (help.html):
+ http://www.geocrawler.com/lists/3/web/182/0/ (Eric Cholet)
+
+* obvious.pod: "Setting environment variables for scripts called from
+ CGI." (Lincoln Stein, Doug MacEachern)
+
+* extended the "Using $|=1 under mod_perl and better print()
+ techniques" at performace.pod.
+
+04.19.99 ver 1.09 (1/2)
+
+* guide.tar.gz and guide-src.tar.gz were outdated, now they are synced
+
* Fixed a huge number of typos (with help of speller :), I'm sure
- there are still many that speller didn't caught - guess people are
+ there are still many that speller didn't catch - guess people are
regular to read badly written textbooks, since just a few told me
about them :( If you spot such, please, do not hesitate and tell me!
-
* Lupe Christoph suggested to apply changes to the main page. It's
done. Also as suggested by Lupe linked the text "Writing Apache
Modules with Perl and C" a link to http://www.modperl.com/ .
-
* Numerous typos were spotted by Andreas J. Koenig and gave me an
idea to run speller :)
+04.17.99 ver 1.09
-04.17.99
-
-
* added to warnings.pod: explained "incorrect line number reporting in
error/warn log messages"
-
* added to scenario.pod: clarification about 2 different config files
in the 2 servers scenario (David Livingstone)
-
* added to scenario.pod: started "mod_perl as DSO" section - almost
empty yet :( anyone with DSO experience?
-
* added to config.pod: started the mod_perl as DSO section
-
* updated config.pod: added how $Apache::Registry::NameWithVirtualHost
bug in older versions can be turned into a feature (Doug)
-
* added to performance.pod : Memory sharing (Leslie Mikesell)
-
* updated warning.pod: server reached MaxClients setting
-
* updated performance.pod : MaxClients reached ( Nick Tonkin )
-
* updated start.pod: "How can I tell whether mod_perl is really
installed" - added httpd -l
-
* modified scenario.pod: Made little changes to make the installation
process less confusing (Pete Harlan)
-
* obvious.pod: updated "Handling the server timeout cases" -
$SIG{ALRM} to not restore the original underlying C handler. Pointed
to try a Sys::Signal as a remedy (Doug)
-
* new in multiuser.pod: ISPs providing mod_perl services - a fantasy
or reality. (Notes from Mark Mills, Russell D. Weiss)
-
* new in multiuser.pod: Virtual Hosts in the guide
-
* new pod : multiuser.pod - mod_perl for ISPs. mod_perl and Virtual
Hosts.
-
* Added a link to the new book to the O'Reilly and Amazon.com sites.
-
* debug.pod: added Apache::DB coverage
-
* performance.pod: "Why you should not use $|=1 under mod_perl" (Doug,
Randal)
-
* debug.pod: "gdb says there are no debugging symbols" (Michael Hall)
-
* config.pod: "the server no longer retrieves the DirectoryIndex files
for a directory" (Andreas Grupp)
-
* scenario.pod: added 'make test fails' when people use PREP_HTTPD=1
or don't use DO_HTTPD=1 (Doug)
-
* removed the 'Mini' part from the guide's name, since it's growned
enough to be not called mini any more.
-
* modules.pod: added Apache::Request
-
* modules.pod: added Apache::DBI
-
* modules.pod: added Apache::Session (Jeffrey Baker)
-
* new pod: modules.pod - to introduce Apache::* modules with small
examples to rise curiosity to read the whole man page
-
* new in scenario.pod: "mod_perl and proxy server"
-
Incentives
Squid proxy server in httpd accelerator mode
Running a squid and 2 webservers scenario
Running a squid and 1 mod_perl apache server scenario
-
(Reviewed and modified according to notes by
Richard Dice, Andreas J. Koenig, Eric Cholet, Jeremy Bailin, David
Landgren)
-
* Added to scenario.pod: 'Publishing port numbers different from 80'
(originally by Ken Williams, forwarded by Eric Strovink)
-
* config.pod: new section "Configuring Apache + mod_perl with mod_macro"
contributed entirely by Eric Cholet (I have edited it a bit :).
04.03.99
-
* Rewritten the CREDITS section of the intro.html. I hope I didn't miss
anyone, if I did please tell. Lets feed the ego :)
-
* The guide now looks much better with StyleSheets (Nathan Vonnahme)
-
* added to porting.pod : Filehandlers and locks leakages (Ken Williams, Doug)
-
* added to obvious.pod: Handling the server timeout cases (Doug)
-
* created new pod: perl.pod to cover some too frequently asked pure
perl questions: opened up with "Using global variables and sharing
them between modules/packages"
-
* Now the pod sources available online along with the resulting htmls
and the scripts that generates them.
-
* Added a summary of various mod_perl deploying schemas (1/1, 2/2, DSO
and proxy). /scenario.html#More_mod_perl_deploying_schemas (Mark
Mills)
-
* created new frequent.pod for "Frequent mod_perl problems" as
suggested by Eric Cholet, who said that problems like 'my() scoped
variable in nested subroutines' come up so often on the list that
@@ -171,186 +199,138 @@
read/beware of. Since now it has only a few problems please suggest
what other ones should go here.
-
* obvious.pod rewritten : my() scoped variable in nested subroutines
(Eric Cholet)
-
* some typos fixes in intro.html, start.pod and scenario.pod (Garr
Updegraff)
-
* snippets.pod: Cookie handling code (Ed Park)
-
* obvious.pod updated: Handling the 'User pressed Stop button'
case. More hints (Eric Strovink) and apache 1.3.6 news (Henrique
Pantarotto)
-
* scenario.pod added : Is it possible to determine which options were
given to modperl's Makefile.PL
-
* More pods has been purified by Steve Reppucci (warning.pod,
obvious.pod and porting.pod). He did so much work to make them
readable, that I'm afraid to apply new changes to break all the
beauty he made :) Thanks, Steve!
-
03.15.99
-
* Added a downloadable guide.tar.gz as someone requested
-
* snippets.pod: Accessing variables from the caller's package (Ken
Williams)
-
* porting.pod: Redirecting mod_perl error_log messages to the browser
- added an extensive example
-
* control.pod: added hints - Preventing from modperl process to eat up
all the disk's space, when it goes wild. (Andreas J. Koenig, Ulrich
Pfeifer)
-
* performance.pod: cleared out where one can get the 'ab' Apache
Benchmark utility
-
* warning.pod: covered - Evil things might happen when using
PerlFreshRestart (Doug)
-
* status.pod: covered - Compiled Registry Scripts section seems to be
empty (Radu Greab)
-
* warning.pod: covered - RegistryLoader: Cannot translate the URI...
-
* scenario.pod: added a note: when using USE_APACI and APACHE_PREFIX,
make install will run also the make install at Apache's source
tree... (Doug)
-
* debug.pod Getting some decent debug info when running under mod_perl
(Doug)
-
* ScriptAlias vs. Alias updated and explaned in config.pod. (Doug, Ask
and Eric)
-
* scenario.pod, intro.html, config.pod, control.pod and start.pod were
purified by Steve Reppucci. Steve has fixed my incorrect English
expressions and tenses, corrected some technical details! Enormous
help, Steve! Thanks!
-
If you see some incorrect English in the guide, don't hesitate to send
an email to me. Thanks!
-
01.22.99
-
* new obvious.pod: Where do the warnings/errors go?
-
* new index.html: added a search box
-
* new snippets.pod: added error_log.pl script to fetch the latest logs
from the server without telneting there
-
* new snippets.pod: How to avoid printing the header more than once.
-
* new snippets.pod: More on relative paths
-
* upd start.pod: removed all 'latest version is', so the guide will
not misguide people (Ken Williams)
-
* upd config.html: removed redundant ;; (Ken Williams)
-
* upd config.html: fixed the question/answer 'Is there a way to
provide a different startup.pl file for each individual virtual'
(Ken Williams)
-
* upd help.html: a few links fixed (Peter Skov (UNIT))
-
* upd porting.pod: CORE::exit vs Apache::exit section update (Doug)
-
* upd scenario.pod: note about importance make clean execution,
because of possible binary incompability (1.3.3 vs 1.3.4) (Doug)
-
* upd porting.pod: switches -w, -T in the shebang line (Doug)
-
* upd debug.pod: tracing the PerlRequire's and PerlModule's as they
are loaded (Doug)
-
* add config.pod: Sometimes script from one virtual host calls the
script with the same path from the second virtual host (Doug)
-
* add performance.pod: how can I find if my modperl scripts have memory leaks (and where). (Doug)
-
* help.html: added a section for DBI help (Jeffrey W. Baker)
-
12.28.98
-
* Updated the "Client hit STOP or Netscrape bit it" section, with new
warning "[modperl] caught SIGPIPE in process" for ver 1.17 (new
Apache::SIG)
-
* Richard A. Soderberg spotted a few problems with name anchors in
start.html (pod converter doesn't resolve the problem correctly) and
ScriptAlias typos at config.html.
-
* broken link to www-security-faq was spotted by Gunther Birznieks
-
12.20.98
-
* fixed: @INC vs %INC obvious.html#Using_Apache_StatINC (thank to Ken Williams)
-
* new: Apache::SpeedLimit added to
performance.html#Limiting_the_request_rate_speed_
-
* modified: register_cleanup in Registry scripts (END{} blocks)
based on the last week tread
-
* new: obvious.html#Handling_the_User_pressed_Stop_
-
* Found a bug in Pod::Html - it tries to convert HTTP::Foo alike
tokens into hypertext link which breaks the code in the resulting
html. Applied the patch to Pod::Html::VERSION 1.01
-
1119a1120
> (?! :) # don't convert HTTP::Foo and alike
@@ -358,22 +338,18 @@
* Discovered that the guide is being searchable thru the
http://www.apache.org/search.html added a link to index.html
-
* Extended the control|Log_Rotation section (+Script from Randal)
-
* control: HUP vs TERM vs USR1. I have asked for validation of this
section, but received none... Added a note about slowness of
termination (Robin Berjon) and possible way to speed it up (Frank
D. Cringle). Added a mneumonics => numbers for SIGs (Marshall Dudley)
-
* added the missing USE_APACI=1 in start.html#Mod_Perl (Thanks to Tzvetan Stoyanov)
12.13.98
-
* covered warning: rwrite returned -1
* covered warning: Client hit STOP or Netscrape bit it!
* covered warning: Can't load '.../auto/DBI/DBI.so' for module DBI
@@ -381,14 +357,11 @@
* covered warning: child process 30388 did not exit, sending another SIGHUP
* extended warning: Callback called exit
-
All the above are based on the Doug's answers this weekend :)
-
* new: config: Tuning MinSpareServers MaxSpareServers StartServers
MaxClients MaxRequestsPerChild (actually a pointer to the next item)
-
* new: performance:
Tuning the Apache's configuration variables for the best performance
Tuning with ab - ApacheBench
@@ -398,53 +371,51 @@
Choosing MinSpareServers, MaxSpareServers and StartServers
Summary of Benchmarking to tune all 5 parameters
-
##########################################################################
12.08.98
-
-* Lot's of "little typos" fixed. Thanks to Evan A. Zacks,
+* Lots of "little typos" fixed. Thanks to Evan A. Zacks,
Eric Cholet and Nancy Lin !
-
* added a quote from DBI page, why $sth-rows; can't be used for rows counting.
-
* fixed obvious.html#Compiled_Regular_Expressions href at porting.html
Thanks to Richard Dice!
-
* lots of little changes and add ons...
-
12.07.98
-
* Run a spell check. ispell and WWWebster were quite helpful :)
-
* Added Richard Dice's notes about ways to see whether or not mod_perl
is actually compiled into the server and working. "check the
error_log file" (installation)
-
* Added 'Is it possible to install mod_perl without root access?'
section into Server Installation (scenario) page.
-
* Added Perrin Harkins and Jonathan Peterson's notes about
apache/mod_perl/embperl/DBI vs IIS/ASP/ADO
-
* Added a CHANGES file (this one)
-
* Added an 'all in one page', suitable for printing. Currently it's
just an ordered cat(). In the future it might change :)
-
12.03.98
-
* First Release
+
+
+
+
+
+
+
+
+
+
+
+
1.11 +8839 -5259modperl-site/guide/all.html
Index: all.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/all.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- all.html 1999/04/19 19:53:28 1.10
+++ all.html 1999/05/08 17:46:26 1.11
@@ -4,71 +4,465 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>Mod Perl Developer's Guide</TITLE>
- <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
- <META NAME="Author" CONTENT="Bekman Stas">
+ <TITLE>mod_perl Guide</TITLE>
+ <META NAME="Author" CONTENT="Stas Bekman">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl cgi apache webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
+ <META NAME="Classification" CONTENT="information">
</HEAD>
+
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-<H1 ALIGN=CENTER>Mod Perl Developer's Guide</H1>
+<H1 ALIGN=CENTER>mod_perl Guide</H1>
<CENTER><P><B>Deploying mod_perl technology to give a rocket speed
-to your perl cgi-bin scripts.</B></P></CENTER>
+to your CGI/perl scripts.</B></P></CENTER>
-<CENTER><P><B>Version 1.09 (+1/2) Apr, 19 1999</B></P></CENTER>
+<CENTER><P><B>Version 1.10
+ May, 8 1999</B></P></CENTER>
<P>
<HR WIDTH="100%"></P>
+
+<H3>Table of Contents:</H3>
+
+<UL>
+
+<LI><A HREF="intro.html"><B><FONT SIZE=+1>Introduction. Incentives. Credits.</FONT></B></A></LI><P>
+<UL>
+
+ <LI><A HREF="intro.html#What_is_mod_perl">What is mod_perl</A>
+ <LI><A HREF="intro.html#What_is_covered_in_this_document">What is covered in this document</A>
+ <LI><A HREF="intro.html#References_and_Acknowledgments">References and Acknowledgments</A>
+</UL>
+<P><LI><A HREF="start.html"><B><FONT SIZE=+1>Guide's Overview</FONT></B></A></LI><P>
+<UL>
+
+ <LI><A HREF="start.html#What_s_inside_">What's inside?</A>
+</UL>
+<P><LI><A HREF="strategy.html"><B><FONT SIZE=+1>Picking the Right Strategy</FONT></B></A></LI><P>
+<UL>
+
+ <LI><A HREF="strategy.html#Do_it_like_me_">Do it like me?!</A>
+ <LI><A HREF="strategy.html#mod_perl_Deploying_Schemas_Overv">mod_perl Deploying Schemas Overview</A>
+ <LI><A HREF="strategy.html#Stand_alone_mod_perl_Enabled_Apa">Stand alone mod_perl Enabled Apache Server</A>
+ <LI><A HREF="strategy.html#One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl enabled Apache Servers</A>
+ <LI><A HREF="strategy.html#One_light_non_Apache_and_One_mod">One light non-Apache and One mod_perl enabled Apache Servers</A>
+ <LI><A HREF="strategy.html#Adding_a_Proxy_Server_in_http_Ac">Adding a Proxy Server in http Accelerator Mode</A>
+ <LI><A HREF="strategy.html#squid_server">squid server</A>
+ <LI><A HREF="strategy.html#apache_s_mod_proxy">apache's mod_proxy</A>
+</UL>
+<P><LI><A HREF="scenario.html"><B><FONT SIZE=+1>Real World Scenarios of Implementing Various Strategies</FONT></B></A></LI><P>
+<UL>
+
+ <LI><A HREF="scenario.html#Before_you_dive_into_the_gory_de">Before you dive into the gory details</A>
+ <LI><A HREF="scenario.html#One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl enabled Apache Servers</A>
+ <UL>
+
+ <LI><A HREF="scenario.html#Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A>
+ <UL>
+
+ <LI><A HREF="scenario.html#Building_the_httpd_docs_Server">Building the httpd_docs Server</A>
+ <LI><A HREF="scenario.html#Building_the_httpd_perl_Server_">Building the httpd_perl Server (mod_perl):</A>
+ </UL>
+
+ <LI><A HREF="scenario.html#Configuration_of_the_servers">Configuration of the servers</A>
+ <UL>
+
+ <LI><A HREF="scenario.html#Basic_httpd_docs_Server_s_Config">Basic httpd_docs Server's Configuration</A>
+ <LI><A HREF="scenario.html#Basic_httpd_perl_Server_s_Config">Basic httpd_perl Server's Configuration</A>
+ </UL>
+
+ </UL>
+
+ <LI><A HREF="scenario.html#Running_2_webservers_and_squid_i">Running 2 webservers and squid in httpd accelerator mode</A>
+ <LI><A HREF="scenario.html#Running_1_webserver_and_squid_in">Running 1 webserver and squid in httpd accelerator mode</A>
+ <LI><A HREF="scenario.html#Using_mod_proxy">Using mod_proxy</A>
+ <LI><A HREF="scenario.html#mod_perl_server_as_DSO">mod_perl server as DSO</A>
+</UL>
+<P><LI><A HREF="install.html"><B><FONT SIZE=+1>Installation Notes</FONT></B></A></LI><P>
+<UL>
+
+ <LI><A HREF="install.html#Configuration_and_Installation">Configuration and Installation</A>
+ <UL>
+
+ <LI><A HREF="install.html#Perl">Perl</A>
+ <LI><A HREF="install.html#Apache">Apache</A>
+ <LI><A HREF="install.html#Mod_Perl">Mod_Perl</A>
+ </UL>
+
+ <LI><A HREF="install.html#How_can_I_tell_whether_mod_perl_">How can I tell whether mod_perl is really installed</A>
+ <UL>
+
+ <LI><A HREF="install.html#Testing_by_checking_the_error_lo">Testing by checking the error_log file</A>
+ <LI><A HREF="install.html#Testing_by_viewing_perl_status">Testing by viewing /perl-status</A>
+ <LI><A HREF="install.html#Testing_via_telnet">Testing via telnet</A>
+ <LI><A HREF="install.html#Testing_via_a_CGI_script">Testing via a CGI script</A>
+ <LI><A HREF="install.html#Testing_via_lwp_request">Testing via lwp-request</A>
+ </UL>
+
+ <LI><A HREF="install.html#Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A>
+ <LI><A HREF="install.html#Is_it_possible_to_determine_whic">Is it possible to determine which options were given to modperl's Makefile.PL</A>
+ <LI><A HREF="install.html#Server_Installation">Server Installation</A>
+ <UL>
+
+ <LI><A HREF="install.html#make_test_fails">make test fails</A>
+ </UL>
+
+</UL>
+<P><LI><A HREF="config.html"><B><FONT SIZE=+1>Server Configuration</FONT></B></A></LI><P>
+<UL>
+
+ <LI><A HREF="config.html#mod_perl_Specific_Configuration">mod_perl Specific Configuration</A>
+ <UL>
+
+ <LI><A HREF="config.html#Alias_Configurations">Alias Configurations</A>
+ <LI><A HREF="config.html#Location_Configuration">Location Configuration</A>
+ <LI><A HREF="config.html#PerlFreshRestart">PerlFreshRestart</A>
+ <LI><A HREF="config.html#_perl_status_location">/perl-status location</A>
+ <LI><A HREF="config.html#perl_startup_file">perl-startup file</A>
+ <UL>
+
+ <LI><A HREF="config.html#Sample_perl_startup_file">Sample perl-startup file</A>
+ <LI><A HREF="config.html#What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A>
+ <LI><A HREF="config.html#Is_it_possible_to_preopen_a_DB_c">Is it possible to preopen a DB connection at the server startup?</A>
+ </UL>
+
+ </UL>
+
+ <LI><A HREF="config.html#Perl_behavior_controls">Perl behavior controls</A>
+ <LI><A HREF="config.html#Tuning_MinSpareServers_MaxSpareS">Tuning MinSpareServers MaxSpareServers StartServers MaxClients</A>
+ <LI><A HREF="config.html#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>
+ <LI><A HREF="config.html#Perl_Sections">Perl Sections</A>
+ <LI><A HREF="config.html#Configuring_Apache_mod_perl_wi">Configuring Apache + mod_perl with mod_macro</A>
+ <LI><A HREF="config.html#General_pitfalls">General pitfalls</A>
+ <UL>
+
+ <LI><A HREF="config.html#My_cgi_perl_code_is_being_return">My cgi/perl code is being returned as a plain text instead of being executed by the webserver?</A>
+ <LI><A HREF="config.html#My_script_works_under_cgi_bin_b">My script works under cgi-bin, but when called via mod_perl I see A 'Save-As' prompt</A>
+ <LI><A HREF="config.html#Is_there_a_way_to_provide_a_diff">Is there a way to provide a different startup.pl file for each individual virtual host</A>
+ <LI><A HREF="config.html#Is_there_a_way_to_modify_INC_on">Is there a way to modify @INC on a per-virtual-host basis. </A>
+ <LI><A HREF="config.html#Sometimes_the_script_from_one_vi">Sometimes the script from one virtual host calls a script with</A>
+ <LI><A HREF="config.html#the_server_no_longer_retrieves_t">the server no longer retrieves the DirectoryIndex files for a directory</A>
+ </UL>
+
+</UL>
+<P><LI><A HREF="frequent.html"><B><FONT SIZE=+1>Frequent mod_perl problems</FONT></B></A></LI><P>
+<UL>
+
+ <LI><A HREF="frequent.html#Coverage">Coverage</A>
+ <LI><A HREF="frequent.html#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>
+ <LI><A HREF="frequent.html#Segfaults_caused_by_PerlFreshRes">Segfaults caused by PerlFreshRestart</A>
+</UL>
+<P><LI><A HREF="porting.html"><B><FONT SIZE=+1>CGI to mod_perl Porting. mod_perl Coding guidelines.</FONT></B></A></LI><P>
+<UL>
+
+ <LI><A HREF="porting.html#Document_Coverage">Document Coverage</A>
+ <LI><A HREF="porting.html#Before_you_start_to_code">Before you start to code</A>
+ <LI><A HREF="porting.html#Coding_with_mod_perl">Coding with mod_perl</A>
+ <UL>
+
+ <LI><A HREF="porting.html#What_s_different_about_modperl">What's different about modperl</A>
+ <UL>
+
+ <LI><A HREF="porting.html#Script_s_name_space">Script's name space</A>
+ <LI><A HREF="porting.html#Name_collisions_with_Modules_and">Name collisions with Modules and libs</A>
+ <LI><A HREF="porting.html#_END_or_DATA_tokens">__END__ or __DATA__ tokens</A>
+ <LI><A HREF="porting.html#Output_from_system_calls">Output from system calls</A>
+ <LI><A HREF="porting.html#Using_format_">Using format()</A>
+ <LI><A HREF="porting.html#Using_exit_">Using exit()</A>
+ <LI><A HREF="porting.html#Running_from_shell">Running from shell</A>
+ <LI><A HREF="porting.html#I_O_is_different">I/O is different</A>
+ <LI><A HREF="porting.html#HTTP_MIME_Headers_PerlSendHea">HTTP + MIME Headers (PerlSendHeader)</A>
+ <LI><A HREF="porting.html#NPH_Non_Parsed_Headers_scripts">NPH (Non Parsed Headers) scripts</A>
+ <LI><A HREF="porting.html#BEGIN_blocks">BEGIN blocks </A>
+ <LI><A HREF="porting.html#END_blocks">END blocks </A>
+ <LI><A HREF="porting.html#Switches_w_T">Switches -w, -T</A>
+ </UL>
+
+ <LI><A HREF="porting.html#strict_pragma">strict pragma</A>
+ <LI><A HREF="porting.html#Turning_warnings_ON">Turning warnings ON</A>
+ <LI><A HREF="porting.html#diagnostics_pragma">diagnostics pragma</A>
+ <LI><A HREF="porting.html#Global_Variables">Global Variables</A>
+ <LI><A HREF="porting.html#Code_has_been_changed_but_it_se">Code has been changed, but it seems the script is running the old code</A>
+ <LI><A HREF="porting.html#Memory_leakage">Memory leakage</A>
+ </UL>
+
+ <LI><A HREF="porting.html#Filehandlers_and_locks_leakages">Filehandlers and locks leakages</A>
+ <UL>
+
+ <LI><A HREF="porting.html#Sometimes_it_Works_Sometimes_Not">Sometimes it Works Sometimes Not (Very important!)</A>
+ <LI><A HREF="porting.html#The_Script_is_too_dirty_It_does">The Script is too dirty, It does the job and I can't afford rewriting it.</A>
+ <LI><A HREF="porting.html#Apache_PerlRun_a_closer_look">Apache::PerlRun - a closer look</A>
+ </UL>
+
+ <LI><A HREF="porting.html#Redirecting_Errors_to_Client_ins">Redirecting Errors to Client instead of error_log</A>
+ <LI><A HREF="porting.html#Finding_the_line_number_the_erro">Finding the line number the error/warning has been triggered at</A>
+ <LI><A HREF="porting.html#Forking_subprocesses_from_mod_pe">Forking subprocesses from mod_perl</A>
+</UL>
+<P><LI><A HREF="performance.html"><B><FONT SIZE=+1>Performance. Benchmarks.</FONT></B></A></LI><P>
+<UL>
+
+ <LI><A HREF="performance.html#Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A>
+ <UL>
+
+ <LI><A HREF="performance.html#Preload_Perl_modules_Real_Numb">Preload Perl modules - Real Numbers</A>
+ </UL>
+
+ <LI><A HREF="performance.html#Preopen_DB_connection_at_server_">Preopen DB connection at server startup</A>
+ <LI><A HREF="performance.html#Memory_sharing">Memory sharing</A>
+ <LI><A HREF="performance.html#Preload_Registry_Scripts">Preload Registry Scripts</A>
+ <LI><A HREF="performance.html#Avoid_Importing_Functions">Avoid Importing Functions</A>
+ <LI><A HREF="performance.html#Reducing_the_Memory_Usage">Reducing the Memory Usage</A>
+ <LI><A HREF="performance.html#how_can_I_find_if_my_modperl_scr">how can I find if my modperl scripts have memory leaks (and where)</A>
+ <LI><A HREF="performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>
+ <LI><A HREF="performance.html#Limiting_the_resources_used_by_h">Limiting the resources used by httpd children</A>
+ <LI><A HREF="performance.html#Limiting_the_request_rate_speed_">Limiting the request rate speed (robots blocking)</A>
+ <LI><A HREF="performance.html#Benchmarks_Impressing_your_Boss">Benchmarks. Impressing your Boss and Colleagues.</A>
+ <UL>
+
+ <LI><A HREF="performance.html#Developers_Talk">Developers Talk</A>
+ <LI><A HREF="performance.html#Benchmarking_a_Graphic_hits_coun">Benchmarking a Graphic hits counter with Persistent DB Connection</A>
+ <LI><A HREF="performance.html#Benchmarking_scripts_with_execut">Benchmarking scripts with execution times below 1 second :)</A>
+ <LI><A HREF="performance.html#PerlHandler_s_Benchmarking">PerlHandler's Benchmarking</A>
+ </UL>
+
+ <LI><A HREF="performance.html#Tuning_the_Apache_s_configuratio">Tuning the Apache's configuration variables for the best performance</A>
+ <UL>
+
+ <LI><A HREF="performance.html#Tuning_with_ab_ApacheBench">Tuning with ab - ApacheBench </A>
+ <LI><A HREF="performance.html#Tuning_with_crashme_script">Tuning with crashme script</A>
+ <LI><A HREF="performance.html#Choosing_MaxClients">Choosing MaxClients</A>
+ <LI><A HREF="performance.html#Choosing_MaxRequestsPerChild">Choosing MaxRequestsPerChild</A>
+ <LI><A HREF="performance.html#Choosing_MinSpareServers_MaxSpa">Choosing MinSpareServers, MaxSpareServers and StartServers</A>
+ <LI><A HREF="performance.html#Summary_of_Benchmarking_to_tune_">Summary of Benchmarking to tune all 5 parameters</A>
+ </UL>
+
+ <LI><A HREF="performance.html#Persistent_DB_Connections">Persistent DB Connections</A>
+ <LI><A HREF="performance.html#Using_1_under_mod_perl_and_be">Using $|=1 under mod_perl and better print() techniques.</A>
+ <LI><A HREF="performance.html#Profiling">Profiling</A>
+ <LI><A HREF="performance.html#CGI_pm_s_object_methods_calls_vs">CGI.pm's object methods calls vs. function calls</A>
+</UL>
+<P><LI><A HREF="obvious.html"><B><FONT SIZE=+1>Things obvious to others, but not to you</FONT></B></A></LI><P>
+<UL>
+
+ <LI><A HREF="obvious.html#Coverage">Coverage</A>
+ <LI><A HREF="obvious.html#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>
+ <UL>
+
+ <LI><A HREF="obvious.html#The_poison">The poison</A>
+ <LI><A HREF="obvious.html#The_diagnosis">The diagnosis</A>
+ <LI><A HREF="obvious.html#The_remedy">The remedy</A>
+ </UL>
+
+ <LI><A HREF="obvious.html#Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A>
+ <UL>
+
+ <LI><A HREF="obvious.html#Restarting_the_server">Restarting the server</A>
+ <LI><A HREF="obvious.html#Using_Apache_StatINC">Using Apache::StatINC</A>
+ <LI><A HREF="obvious.html#Reloading_only_specific_files">Reloading only specific files</A>
+ </UL>
+
+ <LI><A HREF="obvious.html#Compiled_Regular_Expressions">Compiled Regular Expressions </A>
+ <LI><A HREF="obvious.html#Debugging_your_code_in_Single_Se">Debugging your code in Single Server Mode</A>
+ <LI><A HREF="obvious.html#_M_and_other_time_file_tests_u">-M and other time() file tests under mod_perl</A>
+ <LI><A HREF="obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>
+ <LI><A HREF="obvious.html#Handling_the_server_timeout_case">Handling the server timeout cases</A>
+ <LI><A HREF="obvious.html#Where_do_the_warnings_errors_go_">Where do the warnings/errors go?</A>
+ <LI><A HREF="obvious.html#Setting_environment_variables_fo">Setting environment variables for scripts called from CGI.</A>
+</UL>
+<P><LI><A HREF="warnings.html"><B><FONT SIZE=+1>Warnings and Errors: Where and Why.</FONT></B></A></LI><P>
+<UL>
+
+ <LI><A HREF="warnings.html#General_Advice">General Advice </A>
+ <LI><A HREF="warnings.html#Incorrect_line_number_reporting_">Incorrect line number reporting in error/warn log messages</A>
+ <LI><A HREF="warnings.html#Value_of_x_will_not_stay_shared">Value of $x will not stay shared at - line 5</A>
+ <LI><A HREF="warnings.html#Value_of_x_may_be_unavailable_a">Value of $x may be unavailable at - line 5.</A>
+ <LI><A HREF="warnings.html#mod_perl_rwrite_returned_1">mod_perl: rwrite returned -1</A>
+ <LI><A HREF="warnings.html#caught_SIGPIPE_in_process">caught SIGPIPE in process</A>
+ <LI><A HREF="warnings.html#Client_hit_STOP_or_Netscape_bit_">Client hit STOP or Netscape bit it!</A>
+ <LI><A HREF="warnings.html#Constant_subroutine_redefine">Constant subroutine ... redefined</A>
+ <LI><A HREF="warnings.html#Global_symbol_foo_requires_ex">Global symbol "$foo" requires explicit package name</A>
+ <LI><A HREF="warnings.html#Can_t_undef_active_subroutine">Can't undef active subroutine</A>
+ <LI><A HREF="warnings.html#Use_of_uninitialized_value_at_e">Use of uninitialized value at (eval 80) line 12.</A>
+ <LI><A HREF="warnings.html#Undefined_subroutine_Apache_RO">Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function called at</A>
+ <LI><A HREF="warnings.html#Can_t_load_auto_DBI_DBI_so_">Can't load '.../auto/DBI/DBI.so' for module DBI</A>
+ <LI><A HREF="warnings.html#Callback_called_exit">Callback called exit</A>
+ <LI><A HREF="warnings.html#Out_of_memory_">Out of memory!</A>
+ <LI><A HREF="warnings.html#_warn_child_process_30388_did_n">[warn] child process 30388 did not exit, sending another SIGHUP</A>
+ <LI><A HREF="warnings.html#RegistryLoader_Cannot_translate">RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl</A>
+ <LI><A HREF="warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>
+ <LI><A HREF="warnings.html#server_reached_MaxClients_settin">server reached MaxClients setting, consider raising the MaxClients setting</A>
+</UL>
+<P><LI><A HREF="databases.html"><B><FONT SIZE=+1>mod_perl and Relational Databases</FONT></B></A></LI><P>
+<UL>
+
+ <LI><A HREF="databases.html#Why_Relational_SQL_Databases">Why Relational (SQL) Databases</A>
+ <LI><A HREF="databases.html#Apache_DBI_Initiate_a_persist">Apache::DBI - Initiate a persistent database connection</A>
+ <UL>
+
+ <LI><A HREF="databases.html#Introduction">Introduction</A>
+ <LI><A HREF="databases.html#Configuration">Configuration</A>
+ <LI><A HREF="databases.html#Preopening_DBI_connections">Preopening DBI connections</A>
+ <LI><A HREF="databases.html#Debugging_Apache_DBI">Debugging Apache::DBI</A>
+ <LI><A HREF="databases.html#Problems_and_solutions">Problems and solutions</A>
+ <UL>
+
+ <LI><A HREF="databases.html#The_morning_bug">The morning bug</A>
+ <LI><A HREF="databases.html#Cannot_find_the_DBI_handler">Cannot find the DBI handler</A>
+ <LI><A HREF="databases.html#Apache_DBI_does_not_work">Apache:DBI does not work</A>
+ </UL>
+
+ <LI><A HREF="databases.html#Some_useful_code_snippets_to_be_">Some useful code snippets to be used with relational Databases</A>
+ <UL>
+
+ <LI><A HREF="databases.html#Turning_the_SQL_queries_writing_">Turning the SQL queries writing into an short and simple task</A>
+ <LI><A HREF="databases.html#My_DB_module">My::DB module</A>
+ <LI><A HREF="databases.html#My_DB_Module_s_Usage_Examples">My::DB Module's Usage Examples</A>
+ </UL>
+
+ </UL>
-<H3><FONT SIZE=-1>Table of Contents:</FONT></H3>
+</UL>
+<P><LI><A HREF="dbm.html"><B><FONT SIZE=+1>mod_perl and dbm files</FONT></B></A></LI><P>
+<UL>
+ <LI><A HREF="dbm.html#Where_and_Why_to_use_dbm_files">Where and Why to use dbm files</A>
+ <LI><A HREF="dbm.html#mod_perl_and_dbm">mod_perl and dbm</A>
+ <LI><A HREF="dbm.html#Locking_dbm_handlers">Locking dbm handlers</A>
+ <LI><A HREF="dbm.html#Tie_DB_Lock">Tie::DB_Lock</A>
+ <LI><A HREF="dbm.html#Code_snippets">Code snippets</A>
+</UL>
+<P><LI><A HREF="multiuser.html"><B><FONT SIZE=+1>mod_perl for ISPs. mod_perl and Virtual Hosts.</FONT></B></A></LI><P>
<UL>
-<LI><A HREF="intro.html">Introduction. Incentives. Credits.</A></LI>
-<LI><A HREF="start.html">Getting Started with mod_perl. Overview.</A></LI>
+ <LI><A HREF="multiuser.html#ISPs_providing_mod_perl_services">ISPs providing mod_perl services - a fantasy or reality.</A>
+ <LI><A HREF="multiuser.html#Virtual_Hosts_in_the_guide">Virtual Hosts in the guide</A>
+</UL>
+<P><LI><A HREF="control.html"><B><FONT SIZE=+1>Controlling and Monitoring the Server</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="scenario.html">Server Installation. Real World scenarios</A></LI>
+ <LI><A HREF="control.html#Restarting_techniques">Restarting techniques</A>
+ <LI><A HREF="control.html#Implications_of_sending_TERM_HU">Implications of sending TERM, HUP, and USR1 to the server</A>
+ <LI><A HREF="control.html#Using_apachectl_to_control_the_s">Using apachectl to control the server</A>
+ <LI><A HREF="control.html#SUID_start_up_scripts">SUID start-up scripts</A>
+ <LI><A HREF="control.html#Monitoring_the_Server_A_watchdo">Monitoring the Server. A watchdog.</A>
+ <LI><A HREF="control.html#Running_server_in_a_single_mode">Running server in a single mode</A>
+ <LI><A HREF="control.html#Starting_a_personal_server_for_e">Starting a personal server for each developer</A>
+ <LI><A HREF="control.html#Wrapper_to_emulate_the_server_en">Wrapper to emulate the server environment</A>
+ <LI><A HREF="control.html#Log_Rotation">Log Rotation</A>
+ <LI><A HREF="control.html#Preventing_from_modperl_process_">Preventing from modperl process to eat up all the disk's space, when it goes wild.</A>
+</UL>
+<P><LI><A HREF="status.html"><B><FONT SIZE=+1>mod_perl Status. Peeking into the Server's Perl Innards</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="config.html">Server Configuration</A>.</LI>
+ <LI><A HREF="status.html#Watching_the_server">Watching the server</A>
+ <UL>
-<LI><A HREF="control.html">Server Controlling and Monitoring</A></LI>
+ <LI><A HREF="status.html#Configuration">Configuration</A>
+ <LI><A HREF="status.html#Usage">Usage</A>
+ <LI><A HREF="status.html#Compiled_Registry_Scripts_sectio">Compiled Registry Scripts section seems to be empty.</A>
+ </UL>
-<LI><A HREF="frequent.html">Frequent mod_perl problems</A></LI>
+</UL>
+<P><LI><A HREF="debug.html"><B><FONT SIZE=+1>Debugging mod_perl</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="porting.html">CGI to mod_perl Porting. mod_perl Coding guidelines.</A></LI>
+ <LI><A HREF="debug.html#Sometimes_script_works_Sometime">Sometimes script works, Sometimes Not</A>
+ <LI><A HREF="debug.html#Apache_DB_Run_the_interactive">Apache::DB - Run the interactive Perl debugger under mod_perl</A>
+ <LI><A HREF="debug.html#Debug_Tracing">Debug Tracing</A>
+ <LI><A HREF="debug.html#Getting_some_decent_debug_info_w">Getting some decent debug info when running under mod_perl</A>
+ <LI><A HREF="debug.html#gdb_says_there_are_no_debugging_">gdb says there are no debugging symbols</A>
+</UL>
+<P><LI><A HREF="browserbugs.html"><B><FONT SIZE=+1>Workarounds for some known bugs in browsers.</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="obvious.html">What is obvious for others but not for you</A>.</LI>
+ <LI><A HREF="browserbugs.html#Preventing_QUERY_STRING_to_get_c">Preventing QUERY_STRING to get corrupted with &entity key names.</A>
+ <LI><A HREF="browserbugs.html#IE_4_x_does_not_re_post_data_to_">IE 4.x does not re-post data to a non-port-80 URL</A>
+</UL>
+<P><LI><A HREF="modules.html"><B><FONT SIZE=+1>Apache::* modules</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="warnings.html">Warnings and Errors: Where and Why.</A>? </LI>
+ <LI><A HREF="modules.html#Apache_Session_Maintain_sessi">Apache::Session - Maintain session state across HTTP requests</A>
+ <LI><A HREF="modules.html#Apache_DBI_Initiate_a_persist">Apache::DBI - Initiate a persistent database connection</A>
+ <LI><A HREF="modules.html#Apache_Request_libapreq_Gen">Apache::Request (libapreq) - Generic Apache Request Library</A>
+ <LI><A HREF="modules.html#Apache_PerlRun_Run_unaltered_">Apache::PerlRun - Run unaltered CGI scripts under mod_perl</A>
+</UL>
+<P><LI><A HREF="perl.html"><B><FONT SIZE=+1>Perl Reference</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="performance.html">Performance. Benchmarks.</A> </LI>
+ <LI><A HREF="perl.html#Coverage">Coverage</A>
+ <LI><A HREF="perl.html#Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A>
+ <UL>
-<LI><A HREF="status.html">mod_perl Status. Peeking into the Server's Perl Innards</A></LI>
+ <LI><A HREF="perl.html#Making_the_variables_global">Making the variables global</A>
+ <LI><A HREF="perl.html#Making_the_variables_global_with">Making the variables global with strict pragma On</A>
+ <LI><A HREF="perl.html#Using_Exporter_pm_to_share_globa">Using Exporter.pm to share global variables</A>
+ <LI><A HREF="perl.html#Using_aliasing_perl_feature_to_s">Using aliasing perl feature to share global variables</A>
+ </UL>
-<LI><A HREF="debug.html">Debugging mod_perl</A></LI>
+</UL>
+<P><LI><A HREF="snippets.html"><B><FONT SIZE=+1>Code Snippets</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="modules.html">Apache::* modules</A></LI>
+ <LI><A HREF="snippets.html#Sending_MIME_headers">Sending MIME headers</A>
+ <LI><A HREF="snippets.html#How_to_avoid_printing_the_header">How to avoid printing the header more than once.</A>
+ <LI><A HREF="snippets.html#More_on_relative_paths">More on relative paths</A>
+ <LI><A HREF="snippets.html#Watching_the_error_log_file_with">Watching the error_log file without telneting to the server.</A>
+ <LI><A HREF="snippets.html#Accessing_variables_from_the_cal">Accessing variables from the caller's package</A>
+ <LI><A HREF="snippets.html#Handling_cookies">Handling cookies</A>
+</UL>
+<P><LI><A HREF="help.html"><B><FONT SIZE=+1>Getting Helped and Further Learning</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="multiuser.html">mod_perl for ISPs. mod_perl and Virtual
-Hosts.</A></LI>
+ <LI><A HREF="help.html#READ_ME_FIRST">READ ME FIRST</A>
+ <LI><A HREF="help.html#This_document_s_Author">This document's Author</A>
+ <LI><A HREF="help.html#Get_helped_with_mod_perl">Get helped with mod_perl</A>
+ <LI><A HREF="help.html#Get_helped_with_Perl">Get helped with Perl</A>
+ <LI><A HREF="help.html#Get_helped_with_Perl_CGI">Get helped with Perl/CGI</A>
+ <LI><A HREF="help.html#Get_helped_with_Apache">Get helped with Apache </A>
+ <LI><A HREF="help.html#Get_helped_with_DBI">Get helped with DBI</A>
+</UL>
+<P><LI><A HREF="download.html"><B><FONT SIZE=+1>Appendix A: Downloading software and documentation</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="perl.html">Perl Reference</A></LI>
+ <LI><A HREF="download.html#Coverage">Coverage</A>
+ <LI><A HREF="download.html#perl">perl</A>
+ <LI><A HREF="download.html#apache">apache</A>
+ <LI><A HREF="download.html#mod_perl">mod_perl</A>
+ <LI><A HREF="download.html#Squid">Squid</A>
+ <LI><A HREF="download.html#thttpd">thttpd</A>
+ <LI><A HREF="download.html#mod_proxy_add_forward">mod_proxy_add_forward</A>
+</UL>
+<P>
-<LI><A HREF="snippets.html">Code Snippets</A></LI>
+</UL>
-<LI><A HREF="help.html">Help. Further Learning.</A></LI>
+<HR>
-<LI> <HR WIDTH=200 SIZE=5 ALIGN="left">
+<UL>
-<LI><A HREF="all.html">Guide All in One. Ready for Printing</A></LI>
+<LI><A HREF="all.html"><B>Guide All in One. Ready for Printing</B></A></LI>
-<LI><A HREF="CHANGES">CHANGES</A></LI>
+<LI><A HREF="CHANGES"><B>CHANGES</B></A></LI>
-<LI><A HREF="#search">Search perl.apache.org along with this guide</A></LI>
+<LI><A HREF="#search"><B>Search perl.apache.org along with this guide</B></A></LI>
-<LI>Download all files <A HREF="guide.tar.gz">guide.tar.gz</A>
+<LI><B>Download all files <A HREF="guide.tar.gz">guide.tar.gz</A>
or sources and build scripts
-<A HREF="guide-src.tar.gz">guide-src.tar.gz</A></LI>
+<A HREF="guide-src.tar.gz">guide-src.tar.gz</A></B></LI>
</UL>
@@ -109,8 +503,8 @@
<TR ALIGN=CENTER VALIGN=TOP>
<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A
-HREF="help.html#author">Stas Bekman</A>.<BR> Last Modified at
-04/17/1999 </FONT></B></TD>
+HREF="help.html#This_document_s_Author">Stas Bekman</A>.<BR> Last Modified at 05/08/1999
+</FONT></B></TD>
<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" BORDER=0 ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
</TD>
@@ -130,11 +524,14 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: Apache::* modules</TITLE>
+ <TITLE>mod_perl guide: Introduction. Incentives. Credits.</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -145,39 +542,23 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Apache::* modules</H1>
+Introduction. Incentives. Credits.</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="index.html">Main Page</A> | <A HREF="start.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
-
- <LI><A HREF="#Apache_Session_Maintain_sessi">Apache::Session - Maintain session state across HTTP requests</A>
- <LI><A HREF="#Apache_DBI_Initiate_a_persist">Apache::DBI - Initiate a persistent database connection</A>
- <UL>
-
- <LI><A HREF="#Introduction">Introduction</A>
- <LI><A HREF="#Configuration">Configuration </A>
- <LI><A HREF="#Preopening_DBI_connections">Preopening DBI connections</A>
- <LI><A HREF="#Debugging_Apache_DBI">Debugging Apache::DBI</A>
- <LI><A HREF="#Problems_and_solutions">Problems and solutions</A>
- <UL>
-
- <LI><A HREF="#The_morning_bug">The morning bug</A>
- <LI><A HREF="#Cannot_find_the_DBI_handler">Cannot find the DBI handler</A>
- <LI><A HREF="#Apache_DBI_does_not_work">Apache:DBI does not work</A>
- </UL>
- </UL>
-
- <LI><A HREF="#Apache_Request_libapreq_Gen">Apache::Request (libapreq) - Generic Apache Request Library</A>
+ <LI><A HREF="#What_is_mod_perl">What is mod_perl</A>
+ <LI><A HREF="#What_is_covered_in_this_document">What is covered in this document</A>
+ <LI><A HREF="#References_and_Acknowledgments">References and Acknowledgments</A>
</UL>
<!-- INDEX END -->
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -187,274 +568,226 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<CENTER><H1><A NAME="Apache_Session_Maintain_sessi">Apache::Session - Maintain session state across HTTP requests</A></H1></CENTER>
+<CENTER><H1><A NAME="What_is_mod_perl">What is mod_perl</A></H1></CENTER>
<P>
-This module provides the Apache/mod_perl user a mechanism for storing
-persistent user data in a global hash, which is independent of its real
-storage mechanism. Currently you can choose from these storage mechanisms <CODE>Apache::Session::DBI</CODE>, <CODE>Apache::Session::Win32</CODE>,
-<CODE>Apache::Session::File</CODE>, <CODE>Apache::Session::IPC</CODE>. Read the man page of the mechanism you want to use for a complete
-reference.
+The Apache/Perl integration project brings together the full power of the
+Perl programming language and the Apache HTTP server. With mod_perl it is
+possible to write Apache modules entirely in Perl, this lets you easily do
+things that are more difficult or impossible in regular CGI programs, such
+as running sub requests for example. In addition, the persistent
+interpreter embedded in the server saves the overhead of starting an
+external perl interpreter, the penalty of Perl start-up time. A not least
+important feature is code caching, the modules and scripts are being loaded
+and compiled only once, then for the rest of the server's life the scripts
+are being served from the cache, thus server spends its time only to run
+the already loaded and compiled code, which is very fast.
<P>
-Using Apache::Session is easy: simply tie a hash to the session object,
-stick any data structure into the hash, and the data you put in
-automatically persists until the next invocation. Here is a quick example
-which uses cookies to track the user's session.
+The primary advantages of mod_perl are power and speed. You have full
+access to the inner-workings of the web server and can intervene at any
+stage of request-processing. This allows for customized processing of (to
+name just a few of the phases) URI-&gt;filename translation,
+authentication, response generation and logging. There is very little
+run-time overhead. In particular, it is not necessary to start a separate
+process, as is often done with web-server extensions. The most wide-spread
+such extension mechanism, the Common Gateway Interface (CGI), can be
+replaced entirely with perl-code that handles the response generation phase
+of request processing. Mod_perl includes 2 general purpose modules for this
+purpose: <CODE>Apache::Registry</CODE>, which can transparently run existing perl CGI scripts and
+<CODE>Apache::PerlRun</CODE>, which does a similar job but allows you to run ``dirtier'' (to some
+extent) scripts.
+
+<P>
+You can configure your httpd server and handlers in Perl (using
+<CODE>PerlSetVar</CODE>, and <CODE>lt</CODE>Perl<CODE>gt</CODE> sections). You can even define your own configuration directives.
+
+<P>
+Many people wonder and ask ``How much of a performance improvement does
+mod_perl give?''. Well, it all depends on what you are doing with mod_perl
+and possibly who you ask. Developers report speed boosts from 200% to
+2000%. The best way to measure is to try it and see for yourself! (see <A
+HREF="http://perl.apache.org/tidbits.html">http://perl.apache.org/tidbits.html</A>
+and <A
+HREF="http://perl.apache.org/stories/">http://perl.apache.org/stories/</A>
+for the facts)
-<P>
-<PRE> # Pull in the require packages
- use Apache::Session::DBI;
- use Apache;
-
- use strict;
-
- # Read in the cookie if this is an old session
- my $r = Apache->request;
- my $cookie = $r->header_in('Cookie');
- $cookie =~ s/SESSION_ID=(\w*)/$1/;
-
- # Create a session object based on the cookie we got from the
- # browser, or a new session if we got no cookie
- my %session;
- tie %session, 'Apache::Session::DBI', $cookie,
- {DataSource => 'dbi:mysql:sessions',
- UserName => $db_user,
- Password => $db_pass
- };
-
- # Might be a new session, so lets give them their cookie back
- my $session_cookie = "SESSION_ID=$session{_session_id};";
- $r->header_out("Set-Cookie" => $session_cookie);
-</PRE>
<P>
-After setting this up, you can stick anything you want into
-<CODE>%session</CODE> (except file handles), and it will still be there
-when the user invokes the next page.
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="What_is_covered_in_this_document">What is covered in this document</A></H1></CENTER>
+<P>
+This document was written in an effort to help one to start using Apache's
+mod_perl extension as quickly and easily as possible. It includes
+information about installation and configuration of perl and the Apache web
+server and delves deeply into issues of writing and porting existing perl
+scripts to run under mod_perl. Note that it does not attempt to enter the
+big world of using the Perl API or C API. You will find the pointers
+covering these topics at <A HREF="././help.html#">Getting Helped and Further Learning</A> section of this document. This guide tries to cover the most of the <CODE>Apache::Registry</CODE> and <CODE>Apache::PerlRun</CODE>
+modules. Along with mod_perl related topics, there are many more issues
+related to administrating apache servers, debugging scripts, using
+databases, perl reference, code snippets and more. <A HREF="././start.html#">Guide's Overview</A> will help you to find your way through the guide.
<P>
-It is possible to write an Apache authen handler using Apache::Session. You
-can put your authentication token into the session. When a user invokes a
-page, you open their session, check to see if they have a valid token, and
-approve or deny their authorization based on that.
+It is assumed that you know at least the basics of building and installing
+perl and Apache (If you do not, just read the INSTALL docs coming with
+distribution of each package). However you will find in the document
+specific perl and Apache related installation and configuration notes,
+which will help you to successfully complete the mod_perl installation and
+get the running server in a short time.
<P>
-As for IIS, let's compare. IIS's sessions are only valid on the same web
-server as the one that issued the session. Apache::Session's session
-objects can be shared amongst a farm of many machines running different
-operating systems, including even Win32. IIS stores session information in
-RAM. Apache::Session stores sessions in databases, file systems, or RAM.
-IIS's sessions are only good for storing scalars or arrays.
-Apache::Session's sessions allow you to store arbitrarily complex objects.
-IIS sets up the session and automatically tracks it for you. With
-Apache::Session, you setup and track the session yourself. IIS is
-proprietary. Apache::Session is open-source. Apache::Session::DBI can issue
-400+ session requests per second on light Celeron 300A running Linux. IIS?
+If after reading this guide and other documents listed at <A HREF="././help.html#">Help section</A>, you feel that your question is yet not answered, please ask the
+apache/mod_perl mailing list to help you. But first try to browse the
+mailing list archive (located at <A
+HREF="http://forum.swarthmore.edu/epigone/modperl">http://forum.swarthmore.edu/epigone/modperl</A>
+). Often you will find the answer to your question by searching the mailing
+archive, since there is a good chance someone else has already encountered
+the problem and found a solution for it. If you ignore this advice, do not
+be surprised if your question goes unanswered - it bores people to answer
+the same question more than once (twice?). This does not mean that you
+should avoid asking questions, just do not abuse the available help and <STRONG>RTFM</STRONG>before you call for <STRONG>HELP</STRONG>. (You have certainly heard the infamous fable of the shepherd boy and the
+wolves...)
<P>
-An alternative to Apache::Session is Apache::ASP, which has session
-tracking abilities. HTML::Embperl hooks into Apache::Session for you.
+If you find incorrect details, my grammar mistakes or you want to
+contribute to this document please feel free to send me an email at <A
+HREF="mailto:sbekman@iname.com">sbekman@iname.com</A> .
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Apache_DBI_Initiate_a_persist">Apache::DBI - Initiate a persistent database connection</A></H1></CENTER>
+<CENTER><H1><A NAME="References_and_Acknowledgments">References and Acknowledgments</A></H1></CENTER>
<P>
-This module initiates a persistent database connection. It is possible only
-with mod_perl.
+I have used the following references while writing this guide:
+<UL>
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl FAQ</A></STRONG>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Introduction">Introduction</A></H2></CENTER>
+by Frank Cringle at <A
+HREF="http://perl.apache.org/faq/">http://perl.apache.org/faq/</A> .
+
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl performance tuning guide</A></STRONG>
<P>
-When loading the DBI module (do not confuse this with the Apache::DBI
-module) it looks if the environment variable GATEWAY_INTERFACE starts with
-'CGI-Perl' and if the module Apache::DBI has been loaded. In this case
-every connect request will be forwarded to the Apache::DBI module. This
-looks if a database handle from a previous connect request is already
-stored and if this handle is still valid using the ping method. If these
-two conditions are fulfilled it just returns the database handle. If there
-is no appropriate database handle or if the ping method fails, a new
-connection is established and the handle is stored for later re-use. In
-other words when the script is run again from a child that has already (and
-is still) connected, the host/username/password is checked against the
-cache of open connections, and if one is available, uses that one. There is
-no need to delete the disconnect statements from your code. They won't do
-anything because the Apache::DBI module overloads the disconnect method
-with a NOP.
-
-<P>
-You want to use this module if you are opening a <STRONG>few</STRONG> DB connections to the server. <CODE>Apache::DBI</CODE> will make them persistent per child, so if you have 10 children and each
-opens 2 different connections you will have in total 20 opened persistent
-connections. Thus after initial connect you will save up the connection
-time for every connect request from your DBI module. Which is a huge
-benefit for the mod_perl apache server with high traffic of users deploying
-the relational DB.
-
-<P>
-As you understand you must NOT use this module if you are opening a special
-connection for each of your users, since each of them will stay persistent
-and in a short time the number of connections will be so big that your
-machine will scream and die. If you want to use
-<CODE>Apache::DBI</CODE> in both situations, as of this moment the only available solution is to run
-2 mod_perl servers, one using
-<CODE>Apache::DBI</CODE> and one not.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Configuration">Configuration</A></H2></CENTER>
-<P>
-After installing this module, the configuration is simple - add to the
-<CODE>httpd.conf</CODE> the following directive.
-
-<P>
-<PRE> PerlModule Apache::DBI
-</PRE>
-<P>
-Note that it is important, to load this module before any other ApacheDBI
-module !
-
-<P>
-You can skip preloading <CODE>DBI</CODE>, since <CODE>Apache::DBI</CODE> does that. But there is no harm if you leave it in.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Preopening_DBI_connections">Preopening DBI connections</A></H2></CENTER>
-<P>
-If you want that when you call the script after server restart, the
-connection will be already preopened, you should use
-<CODE>connect_on_init()</CODE> method in the startup file to preload every connection you are going to
-use. For example:
-
-<P>
-<PRE> Apache::DBI->connect_on_init
- ("DBI:mysql:myDB::myserver",
- "username",
- "passwd",
- {
- PrintError => 1, # warn() on errors
- RaiseError => 0, # don't die on error
- AutoCommit => 1, # commit executes immediately
- }
- );
-</PRE>
-<P>
-As noted before, it is wise to you this method only if you only want all of
-apache to be able to connect to the database server as one user (or few
-users).
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Debugging_Apache_DBI">Debugging Apache::DBI</A></H2></CENTER>
-<P>
-If you are not sure this module is working as advertised, you should enable
-the Debug mode in the startup script by:
-
-<P>
-<PRE> $Apache::DBI::DEBUG = 1;
-</PRE>
-<P>
-Since now on you will see in the <CODE>error.log</CODE> file when Apache::DBI initializes a connection and when it just returns it
-from its cache. Use the following command to see it in the real time (your
-<CODE>error.log</CODE> file might be locate at a different path):
-
-<P>
-<PRE> tail -f /usr/local/apache/logs/error_log
-</PRE>
-<P>
-I use <CODE>alias</CODE> so I will not have to remember the path:
-
-<P>
-<PRE> alias err "tail -f /usr/local/apache/logs/error_log"
-</PRE>
-<P>
-Another approach is to add to <CODE>httpd.conf</CODE> (which does the same):
-
-<P>
-<PRE> PerlModule Apache::DebugDBI
-</PRE>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Problems_and_solutions">Problems and solutions</A></H2></CENTER>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="The_morning_bug">The morning bug</A></H3></CENTER>
-<P>
-SQL server keeps the connection to the client open for a limited period of
-time. So many developers were bitten by so called <STRONG>Morning
-bug</STRONG> when every morning the first users to use the site were receiving: <CODE>No Data Returned</CODE> message, but then everything worked as usual. The error caused by <CODE>Apache::DBI</CODE> returning a handle of the invalid connection (server closed it because of
-timeout), and the script was dying on that error. The infamous and well
-documented in the man page, <CODE>ping()</CODE> method was introduced to solve this problem. But seems that people are
-still being beaten by this problem. Another solution was found - to rise
-the timeout parameter at the SQL server startup. Currently I startup <CODE>mySQL</CODE> server with
-<CODE>safe_mysql</CODE> script, so I have updated it to use this option:
+by Vivek Khera at <A
+HREF="http://perl.apache.org/tuning/">http://perl.apache.org/tuning/</A> .
-<P>
-<PRE> nohup $ledir/mysqld [snipped other options] -O wait_timeout=172800
-</PRE>
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl plugin reference guide</A></STRONG>
<P>
-Where 172800 secs equal to 48 hours. And it works.
+by Doug MacEachern at <A
+HREF="http://perl.apache.org/src/mod_perl.html">http://perl.apache.org/src/mod_perl.html</A>
+.
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="Cannot_find_the_DBI_handler">Cannot find the DBI handler</A></H3></CENTER>
+<P><LI><STRONG><A NAME="item_Quick">Quick guide for moving from CGI to mod_perl</A></STRONG>
<P>
-Q: I cannot find the handler name with which to manipulate my connection;
-hence I seem to be unable to do anything to my database.
+at <A
+HREF="http://perl.apache.org/dist/cgi_to_mod_perl.html">http://perl.apache.org/dist/cgi_to_mod_perl.html</A>
+.
+<P><LI><STRONG><A NAME="item_mod_perl_traps">mod_perl_traps, common traps and solutions for mod_perl users</A></STRONG>
<P>
-A: You did not use <CODE>DBI::connect()</CODE> as with usual DBI usage to get your <CODE>$dbh</CODE> database handler.
-Using the <CODE>Apache::DBI</CODE> does not eliminate the need to write a proper <CODE>DBI</CODE> code. As the man page states - you should program as if you did not use <CODE>Apache::DBI</CODE> at all. <CODE>Apache::DBI</CODE> will override and return you a cached connection. And in case of <CODE>disconnect()</CODE> call it will be just ignored.
+at <A
+HREF="http://perl.apache.org/dist/mod_perl_traps.html">http://perl.apache.org/dist/mod_perl_traps.html</A>
+.
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="Apache_DBI_does_not_work">Apache:DBI does not work</A></H3></CENTER>
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl mailing list emails</A></STRONG>
<P>
-Make sure you have it installed.
+Answers to some of the questions posted to <A
+HREF="mailto:modperl@apache.org">modperl@apache.org</A> Apache/Perl mailing
+list.
+<P><LI><STRONG><A NAME="item_My">My personal experience with mod_perl.</A></STRONG>
+</UL>
<P>
-Make sure you configured mod_perl with EVERYTHING=1.
+As I said, I have quoted many information snippets from FAQs and emails,
+and I did not credit people after each quote in the guide. I did not mean
+to take the credits for myself, it's just that I have tried to keep track
+of names, and became lost, so I preferred not to credit at all in the
+guide, but to centralize it here. If you think that you want your name to
+show up under your original quote that I have used, please tell me and I'll
+add it for you.
<P>
-Use the example script eg/startup.pl (remove the comment from the line
+Major contributors:
-<P>
-<PRE> #use Apache::DebugDBI;
-</PRE>
+<UL>
+<P><LI><STRONG><A NAME="item_Doug">Doug MacEachern</A></STRONG>
<P>
-and adapt the connect string. Do not change anything in your scripts, for
-using Apache::DBI.
+a big part of this guide is build upon his email replies to the users'
+questions
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Apache_Request_libapreq_Gen">Apache::Request (libapreq) - Generic Apache Request Library</A></H1></CENTER>
+<P><LI><STRONG><A NAME="item_Frank">Frank Cringle</A></STRONG>
<P>
-This package contains modules for manipulating client request data via the
-Apache API with Perl and C. Functionality includes:
+parts of his mod_perl FAQ has been used in the guide.
+<P><LI><STRONG><A NAME="item_Vivek">Vivek Khera</A></STRONG>
<P>
-- parsing of application/x-www-form-urlencoded data
+for his mod_perl performance tuning guide.
+<P><LI><STRONG><A NAME="item_Steve">Steve Reppucci</A></STRONG>
<P>
-- parsing of multipart/form-data
+who made a thorough review of the stuff I wrote. Fixed lots of spelling and
+grammar errors, and made the guide readable to English speakers :)
+<P><LI><STRONG><A NAME="item_Eric">Eric Cholet</A></STRONG>
<P>
-- parsing of HTTP Cookies
+who wrote complete sections for the guide, and pointed out the errors the
+guide carried away.
+<P><LI><STRONG><A NAME="item_Ken">Ken Williams</A></STRONG>
<P>
-The Perl modules are simply a thin xs layer on top of libapreq, making them
-a lighter and faster alternative to CGI.pm and CGI::Cookie. See the
-Apache::Request and Apache::Cookie documentation for more details and
-eg/perl/ for examples.
+who reviewed a lot of stuff in the guide, and many snippets from his emails
+are included in the guide.
+</UL>
<P>
-Apache::Request and the libapreq are tied tight to the Apache API, which
-there is no access to in a process running under mod_cgi.
+Credits of course go to ( alphabetically sorted ):
+<UL>
+<P><LI><STRONG><A NAME="item_Andreas">Andreas J. Koenig</A></STRONG>
+<P><LI><STRONG><A NAME="item_Ask">Ask Bjoern Hansen</A></STRONG>
+<P><LI><STRONG><A NAME="item_Brian">Brian Moseley</A></STRONG>
+<P><LI><STRONG><A NAME="item_Chad">Chad K. Lewis</A></STRONG>
+<P><LI><STRONG><A NAME="item_David">David Landgren</A></STRONG>
+<P><LI><STRONG><A NAME="item_Doug">Doug Bagley</A></STRONG>
+<P><LI><STRONG><A NAME="item_Ed">Ed Park</A></STRONG>
+<P><LI><STRONG><A NAME="item_Edmund">Edmund Mergl</A></STRONG>
+<P><LI><STRONG><A NAME="item_Evan">Evan A. Zacks</A></STRONG>
+<P><LI><STRONG><A NAME="item_G">G.Richter</A></STRONG>
+<P><LI><STRONG><A NAME="item_Garr">Garr Updegraff</A></STRONG>
+<P><LI><STRONG><A NAME="item_Gunther">Gunther Birznieks</A></STRONG>
+<P><LI><STRONG><A NAME="item_Henrique">Henrique Pantarotto</A></STRONG>
+<P><LI><STRONG><A NAME="item_Howard">Howard Jones</A></STRONG>
+<P><LI><STRONG><A NAME="item_Jeff">Jeff Baker</A></STRONG>
+<P><LI><STRONG><A NAME="item_Jeff">Jeff Rowe</A></STRONG>
+<P><LI><STRONG><A NAME="item_Jon">Jon Orwant</A></STRONG>
+<P><LI><STRONG><A NAME="item_Jonathan">Jonathan Peterson</A></STRONG>
+<P><LI><STRONG><A NAME="item_Leslie">Leslie Mikesell</A></STRONG>
+<P><LI><STRONG><A NAME="item_Lincoln">Lincoln Stein</A></STRONG>
+<P><LI><STRONG><A NAME="item_Mark">Mark Mills</A></STRONG>
+<P><LI><STRONG><A NAME="item_Marshall">Marshall Dudley</A></STRONG>
+<P><LI><STRONG><A NAME="item_Mike">Mike Fletcher</A></STRONG>
+<P><LI><STRONG><A NAME="item_Nancy">Nancy Lin</A></STRONG>
+<P><LI><STRONG><A NAME="item_Nathan">Nathan Torkington</A></STRONG>
+<P><LI><STRONG><A NAME="item_Nathan">Nathan Vonnahme</A></STRONG>
+<P><LI><STRONG><A NAME="item_Perrin">Perrin Harkins</A></STRONG>
+<P><LI><STRONG><A NAME="item_Peter">Peter Skov</A></STRONG>
+<P><LI><STRONG><A NAME="item_Radu">Radu Greab</A></STRONG>
+<P><LI><STRONG><A NAME="item_Ralf">Ralf Engelschall</A></STRONG>
+<P><LI><STRONG><A NAME="item_Randal">Randal Schwartz</A></STRONG>
+<P><LI><STRONG><A NAME="item_Richard">Richard Dice</A></STRONG>
+<P><LI><STRONG><A NAME="item_Tzvetan">Tzvetan Stoyanov</A></STRONG>
+<P><LI><STRONG><A NAME="item_Ulrich">Ulrich Pfeifer</A></STRONG>
+<P><LI>
+<P><LI><STRONG><A NAME="item_Did">Did I miss you? Tell me!</A></STRONG>
+</UL>
<P>
-Get it from CPAN at $CPAN/authors/id/DOUGM/libapreq-x.xx.tar.gz or from <A
-HREF="http://perl.apache.org/dist/libapreq-x.xx.tar.gz">http://perl.apache.org/dist/libapreq-x.xx.tar.gz</A>
-. (replace x.xx with the current version)
+I want to thank all the people who donated their time and efforts to make
+this amazing idea of mod_perl a reality. This includes Doug MacEachern, the
+author of mod_perl and all the developers who contributed bug patches,
+modules and help. And of course the numerous unseen users who helped to
+find the bugs and advocate mod_perl around the world.
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
@@ -465,7 +798,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="index.html">Main Page</A> | <A HREF="start.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -477,8 +811,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
@@ -505,258 +839,223 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl mini-guide: Introduction. Incentives. Credits. </TITLE>
+ <TITLE>mod_perl guide: Guide's Overview</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+<A NAME="toc"></A>
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+Guide's Overview</H1>
+<HR WIDTH="100%">
+ [ <A HREF="intro.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="strategy.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+<UL>
+
+ <LI><A HREF="#What_s_inside_">What's inside?</A>
+</UL>
+<!-- INDEX END -->
+
+<HR>
+
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
-<H1 ALIGN=CENTER><A HREF="http://perl.apache.org">
-<IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30
- WIDTH=90 ALIGN=LEFT></A>
-<A HREF="http://perl.apache.org">
-<IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30
- WIDTH=90 ALIGN=RIGHT></A>Introduction. Incentives. Credits.</H1>
+ <HR>
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="What_s_inside_">What's inside?</A></H1></CENTER>
+<P>
+Before you begin to install the mod_perl, you should have an overall
+picture. There are more then one way you set your mod_perl enabled
+webserver. You have to decide what mod_perl schema you want to use. <A HREF="././strategy.html#">Picking the Right Strategy</A> chapter presents various approaches, discusses the pros and cons of each
+one.
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+<P>
+Once you know what fits your requirements the best, you should proceed to <A HREF="././scenario.html#">Real World Scenarios of Implementing Various Strategies</A>. This chapter provides a very detailed scenarios of the schemas discussed
+in the <A HREF="././strategy.html#">Picking the Right Strategy</A> chapter.
-<UL>
-<LI><A HREF="#1">What is mod_perl</A></LI>
+<P>
+<A HREF="././install.html#">Server Installation</A> chapter completes the <A HREF="././scenario.html#">Real World Scenarios of Implementing Various Strategies</A> by providing more installation details.
-<LI><A HREF="#2">What is covered in this document</A></LI>
+<P>
+<A HREF="././config.html#">Server Configuration</A> extends the basic configurations presented in the <A HREF="././scenario.html#">Real World Scenarios of Implementing Various Strategies</A> with extended configurations and solutions to various configuration
+pitfalls.
-<LI><A HREF="#3">Sources and Acknowledgments</LI>
-</UL>
+<P>
+<A HREF="././frequent.html#">Frequent mod_perl problems</A> chapter just collects links to other chapters. It is an attempt to stress
+some of the most frequently mod_perl problems. So this is the first place
+you should check if you have got a problem.
<P>
-<HR WIDTH="100%"></P>
+Probably the most important chapter is <A HREF="././porting.html#">CGI to mod_perl Porting. mod_perl Coding guidelines</A>. It explains what are the differences between scripts running under
+mod_cgi and mod_perl. What should be done in order to make the existent
+scripts work under mod_perl. The proper mod_perl coding guidelines.
-<H3 ALIGN=CENTER><A NAME="1"></A>What is mod_perl</H3>
+<P>
+<A HREF="././performance.html#">Performance. Benchmarks</A> is the biggest and very important chapter. It explains the details of
+tuning the mod_perl and the scripts running under mod_perl, so you can
+squeeze every ounce of the power from your server. A big part of it are the
+benchmarks. The numbers that IT managers love to see. But those are
+different - these benchmarks are comparing mod_perl with other technologies
+but compare different configurations of mod_perl servers, to guide you in
+the tuning process. I have to admit - performance tuning is a very hard
+task, and demands a lot of understanding and experience, but once you get
+this knowledge - you can make magic with your server.
-<P>The Apache/Perl integration project brings together the full power of
-the Perl programming language and the Apache HTTP server. With mod_perl
-it is possible to write Apache modules entirely in Perl. In addition,
-the persistent interpreter embedded in the server avoids the overhead of
-starting an external interpreter, the penalty of Perl start-up time and
-loading and compiling the modules and the scripts. </P>
+<P>
+<A HREF="././obvious.html#">Things obvious to others, but not to you</A> is exactly what it claims to be. Some people are too long into this
+business, and many things have become obvious to them. This is not true for
+a newbie, this chapter tries to talk about such things.
-<P>The primary advantages of mod_perl are power and speed. You have full
-access to the inner-workings of the web server and can intervene at any
-stage of request-processing. This allows for customized processing of
-(to name just a few of the phases) URI->filename translation,
-authentication, response generation and logging. There is very little
-run-time overhead. In particular, it is not necessary to start a
-separate process, as is often done with web-server extensions. The most
-wide-spread such extension mechanism, the Common Gateway Interface
-(CGI), can be replaced entirely with perl-code that handles the response
-generation phase of request processing. Mod_perl includes 2 general
-purpose modules for this purpose: Apache::Registry, which can
-transparently run existing perl CGI scripts and Apache::PerlRun, which
-does a similar job but allows you to run "dirtier" (to some extent)
-scripts.</P>
-
-<P>Many people wonder and ask "How much of a performance
-improvement does mod_perl give?". Well, it all depends on what
-you're doing with mod_perl and possibly who you ask. People report speed
-boosts from 200% to 2000%. The best way to measure is to try it and
-see for yourself! (see <A
-HREF="http://perl.apache.org/tidbits.html">Tidbit </A>and <A
-HREF="http://perl.apache.org/stories/">Stories </A>pages for the
-facts)</P>
+<P>
+While developing your mod_perl applications, you are beginning to
+understand that an <CODE>error_log</CODE> file is your best friend. It tells you all the intimate details of what is
+happening to your scripts, but the problem that it talks in a secret
+language. To learn the alphabet and the grammar of this language, refer to
+a <A HREF="././warnings.html#">Warnings and Errors: Where and Why</A>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
+<P>
+If you are into driving relational databases with your cgi scripts, the <A HREF="././databases.html#">mod_perl and Relational Databases</A> chapter will tell you all about what database related goodies mod_perl
+prepared for you.
-<H3 ALIGN=CENTER><A NAME="2"></A>What is covered in this document</H3>
+<P>
+If you are using the good old dbm files for your databases, <A HREF="././dbm.html#">mod_perl and dbm files</A> explains how to utilize them better under mod_perl.
-<P>This document was written in an effort to help one to start using
-Apache's mod_perl extension as quickly and easily as possible. It
-includes information about installation and configuration of perl and
-the Apache web server and delves deeply into issues of writing and
-porting existing perl scripts to run under mod_perl. Note that it
-doesn't attempt to enter the big world of using the Perl API or C API.
-You will find the Pointers covering these topics at <A
-HREF="help.html">Help Seek and Learning more</A> section of this
-document.<B> This guide tries to cover the most of the Apache::Registry
-and Apache::PerlRun modules.</B></P>
+<P>
+More and more ISPs are evaluating a possibility to give the mod_perl
+services to their users. Is it possible? Is it secure? Will it work? How
+much resources? <A HREF="././multiuser.html#">mod_perl for ISPs. mod_perl and Virtual Hosts</A> chapter answers all these questions. If you want to run a mod_perl enabled
+server, but do not have a root access read it as well, either to learn how
+do it by yourself, or maybe to persuade your ISP to provide you this
+service.
-<P>It is assumed that you know the basics of building and installing
-perl and Apache (If you don't, just read the INSTALL docs coming with
-distribution of each package). However you will find in the document
-specific perl and Apache related installation and configuration notes,
-which will help you to successfully complete the mod_perl
-installation.</P>
+<P>
+If you have to administrate your apache mod_perl server - the
+<A HREF="././control.html#">Controlling and Monitoring the Server</A> chapter is for you. It includes the restarting and monitoring techniques.
+And very important - how to prevent from server to finish up your disk
+space in a matter of minutes.
-<P>If after reading this guide and other documents listed at <A
-HREF="help.html">Help section</A>, you feel that your question is yet
-not answered, please ask the apache/mod_perl mailing list to help you.
-But first try to browse the mailing list archive (located at <A
-HREF="http://forum.swarthmore.edu/epigone/modperl">
-http://forum.swarthmore.edu/epigone/modperl</A>). Often you will find
-the answer to your question by searching the mailing archive, since
-there is a good chance someone else has already encountered the problem
-and found a solution for it. If you ignore this advice, don't be
-surprised if your question goes unanswered - it bores people to answer
-the same question more than once (twice?). This doesn't mean that you
-should avoid asking questions, just don't abuse the available help and
-<B>RTFM</B>before you call for <B>HELP</B>. (You have certainly heard
-the infamous fable of the shepherd boy and the wolves...)</P>
-
-<P>If you find incorrect details, my grammar mistakes or you want to
-contribute to this document please feel free to send me an <A
-HREF="mailto:sbekman@iname.com">email</A> at
-<B>sbekman@iname.com</B>.</P>
+<P>
+<A HREF="././status.html#">mod_perl Status. Peeking into the Server's Perl Innards</A>
+chapter shows you the ways you can peek into what is going on in the server
+while it is running. Like looking what are the value of some global
+variable. What database connections are open, and much more.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
+<P>
+Every programmer need to know how to debug the program. It is _easy_ with
+perl, you invoke the script with <CODE>-d</CODE> flag and you start debugging it. Is it possible to do under mod_perl, after
+all you cannot debug every script by running it from the command line?
+<A HREF="././debug.html#">Debugging mod_perl</A> chapter tells exactly how to do it.
-<H3 ALIGN=CENTER><A NAME="3"></A>Sources and Acknowledgments</H3>
+<P>
+Sometimes browsers that interact with our servers have bugs, creating real
+problems to the CGI developers. How to prevent this bugs from happening
+discussed in <A HREF="././browserbugs.html#">Workarounds for some known bugs in browsers</A> chapter.
-<P>This document is based on:</P>
+<P>
+There many modules were written to extend the mod_perl's core
+functionality. Some of the important modules are being covered in <A HREF="././modules.html#">Apache::* modules</A>.
-<UL>
-<LI>Frank Cringle's <A HREF="http://perl.apache.org/faq/">mod_perl FAQ</A></LI>
+<P>
+Some folks decides to go mod_perl, but they miss the basic understanding of
+the perl, which is not tolerant by mod_perl. if you are such a person,
+there is nothing to be ashamed of, we all went thru this. Get a good perl
+book and start reading. <A HREF="././perl.html#">Perl Reference</A> - gives some basic perl lessons, providing the information you cannot start
+to program mod_perl scripts without.
-<LI>Vivek Khera's <A HREF="http://perl.apache.org/tuning/">mod_perl performance
-tuning guide</A></LI>
-
-<LI>Doug MacEachern's <A HREF="http://perl.apache.org/src/mod_perl.html">mod_perl
-plugin reference guide</A>. </LI>
-
-<LI><A HREF="http://perl.apache.org/dist/cgi_to_mod_perl.html">Quick guide
-</A>for moving from CGI to mod_perl. </LI>
-
-<LI><A HREF="http://perl.apache.org/dist/mod_perl_traps.html">mod_perl_traps,</A>
-common traps and solutions for mod_perl users. </LI>
-
-<LI>Answers to some of the questions posted to <A
-HREF="mailto:modperl@apache.org">Apache/Perl mailing
-list</A>. (Subscription information is in the <a
-href="http://perl.apache.org/src/mod_perl-1.16/SUPPORT">SUPPORT</a>
-file in the distribution)</LI>
-
-<LI>My personal experience with mod_perl</LI>
-</UL>
-
-<P>As I said, I've quoted many information snippets from FAQs and emails,
- and I didn't credit people after each quote in the guide.
- I didn't mean to
- take the credits for myself, it's just that I've tried to keep
- track of names, and became lost, so I preferred not to credit at
- all in the guide, but to centralize it here. If you think that
- you want your name to show up under your original quote that I
- have used, please tell me and I'll add it for you.<P>
-
-<P>Major contributors:
-
-<UL>
- <LI><B>Doug MacEachern</B> - a big part of this guide is build upon his
- email replies to the users' questions
-
- <LI><B>Frank Cringle</B> - whose mod_perl FAQ lays in the basis of the guide.
-
- <LI><B>Vivek Khera</B> - for his mod_perl performance tuning guide.
-
- <LI><B>Steve Reppucci</B> - who made a thorough review of the stuff I
- wrote. Fixed lots of spelling and grammar errors, and made
- the guide readable to English speakers :)
-
- <LI><B>Eric Cholet</B> - who wrote complete sections for the guide, and
- pointed out the errors the guide carried away.
-
- <LI><B>Ken Williams</B> - who reviewed a lot of stuff in the guide, and
- many snippets from his emails are included in the guide.
-
-</UL>
-
-<P> Credits go of course to ( alphabetically sorted ):
- <UL>
- <LI><B>Andreas J. Koenig</B>
- <LI><B>Ask Bjoern Hansen</B>
- <LI><B>Brian Moseley </B>
- <LI><B>Chad K. Lewis</B>
- <LI><B>David Landgren</B>
- <LI><B>Doug Bagley</B>
- <LI><B>Ed Park</B>
- <LI><B>Edmund Mergl</B>
- <LI><B>Evan A. Zacks</B>
- <LI><B>G.Richter</B>
- <LI><B>Garr Updegraff</B>
- <LI><B>Gunther Birznieks</B>
- <LI><B>Henrique Pantarotto</B>
- <LI><B>Howard Jones</B>
- <LI><B>Jeff Baker</B>
- <LI><B>Jeff Rowe</B>
- <LI><B>Jon Orwant</B>
- <LI><B>Jonathan Peterson</B>
- <LI><B>Leslie Mikesell</B>
- <LI><B>Lincoln Stein</B>
- <LI><B>Mark Mills</B>
- <LI><B>Marshall Dudley</B>
- <LI><B>Mike Fletcher</B>
- <LI><B>Nancy Lin</B>
- <LI><B>Nathan Torkington</B>
- <LI><B>Nathan Vonnahme</B>
- <LI><B>Perrin Harkins</B>
- <LI><B>Peter Skov</B>
- <LI><B>Radu Greab</B>
- <LI><B>Ralf Engelschall</B>
- <LI><B>Randal Schwartz</B>
- <LI><B>Richard Dice</B>
- <LI><B>Tzvetan Stoyanov</B>
- <LI><B>Ulrich Pfeifer</B>
- <LI>
- <LI>Did I miss you? Tell me!
- </UL>
-</P>
-
-<P>I want to thank all the people who donated their time and efforts
-to make this amazing idea of mod_perl a reality. This includes Doug
-MacEachern, the author of mod_perl and all the developers who
-contributed bug patches, modules and help. And of course the numerous
-unseen users who helped to find the bugs and advocate mod_perl around
-the world.</P>
+<P>
+<A HREF="././snippets.html#">Code Snippets</A> chapter is just a collection of code snippets I have found useful while
+writing the scripts.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
+<P>
+<A HREF="././help.html#">Getting Helped and Further Learning</A> points you to other information sources, like perl programming, security,
+databases and more.
+
+<P>
+<A HREF="././download.html#">Appendix A: Downloading software and documentation</A>
+includes pointers to the software that was explained and/or mentioned in
+this guide.
+
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main page]</A></P>
+ <HR>
+ [ <A HREF="intro.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="strategy.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
-<TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
-<HR></TD>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
</TR>
-
-<TR ALIGN=CENTER VALIGN=TOP> <TD ALIGN=CENTER VALIGN=CENTER><B><FONT
-SIZE=-1>Written by <A HREF="help.html#author">Stas Bekman</A>.<BR> Last
-Modified at 04/17/1999 </FONT></B></TD>
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
+ </FONT>
+ </B>
+ </TD>
-<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg"
-BORDER=0 ALT="Mod Perl Icon" HEIGHT=59 WIDTH=150></A> </TD>
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
-<TD><FONT SIZE=-2>Use of the Camel for Perl is <BR>
-a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
-and is used by permission. </FONT> </TD>
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
</TR>
</TABLE></CENTER>
</BODY>
</HTML>
-
+
<HR SIZE=6>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: Getting Started with mod_perl. Overview.</TITLE>
+ <TITLE>mod_perl guide: Picking the Right Strategy</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -767,48 +1066,28 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Getting Started with mod_perl. Overview.</H1>
+Picking the Right Strategy</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="start.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="scenario.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
- <LI><A HREF="#Coverage">Coverage</A>
- <LI><A HREF="#Downloading_the_needed_component">Downloading the needed components.</A>
- <UL>
-
- <LI><A HREF="#Perl_Download">Perl Download</A>
- <LI><A HREF="#Apache_Download">Apache Download</A>
- <LI><A HREF="#Mod_Perl_Download">Mod_Perl Download</A>
- </UL>
-
- <LI><A HREF="#Configuration_and_Installation">Configuration and Installation</A>
- <UL>
-
- <LI><A HREF="#Perl">Perl</A>
- <LI><A HREF="#Apache">Apache</A>
- <LI><A HREF="#Mod_Perl">Mod_Perl</A>
- </UL>
-
- <LI><A HREF="#How_can_I_tell_whether_mod_perl_">How can I tell whether mod_perl is really installed</A>
- <UL>
-
- <LI><A HREF="#Testing_by_checking_the_error_lo">Testing by checking the error_log file</A>
- <LI><A HREF="#Testing_by_viewing_perl_status">Testing by viewing /perl-status</A>
- <LI><A HREF="#Testing_via_telnet">Testing via telnet</A>
- <LI><A HREF="#Testing_via_a_CGI_script">Testing via a CGI script</A>
- <LI><A HREF="#Testing_via_lwp_request">Testing via lwp-request</A>
- </UL>
-
- <LI><A HREF="#Starting_to_use_the_server">Starting to use the server</A>
+ <LI><A HREF="#Do_it_like_me_">Do it like me?!</A>
+ <LI><A HREF="#mod_perl_Deploying_Schemas_Overv">mod_perl Deploying Schemas Overview</A>
+ <LI><A HREF="#Stand_alone_mod_perl_Enabled_Apa">Stand alone mod_perl Enabled Apache Server</A>
+ <LI><A HREF="#One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl enabled Apache Servers</A>
+ <LI><A HREF="#One_light_non_Apache_and_One_mod">One light non-Apache and One mod_perl enabled Apache Servers</A>
+ <LI><A HREF="#Adding_a_Proxy_Server_in_http_Ac">Adding a Proxy Server in http Accelerator Mode</A>
+ <LI><A HREF="#squid_server">squid server</A>
+ <LI><A HREF="#apache_s_mod_proxy">apache's mod_proxy</A>
</UL>
<!-- INDEX END -->
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -818,313 +1097,557 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<P>
-<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
-<P>
-These sections give a quick review of configuration and installation of the
-required tools. For a quick-start tutorial, which will allow you make to
-make a copy-and-paste slick installation, see
-<A HREF="././scenario.html#">Real World Scenario</A>
+ <HR>
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Downloading_the_needed_component">Downloading the needed components.</A></H1></CENTER>
+<CENTER><H1><A NAME="Do_it_like_me_">Do it like me?!</A></H1></CENTER>
<P>
-In order to start using mod_perl you will first need to get Perl, the
-Apache webserver, and mod_perl itself. Below you will find the needed
-information.
+There is no such a thing as a <STRONG>RIGHT</STRONG> strategy in web server business, though there are the wrong ones. Never
+believe a person, saying: <EM>"Do it this way, this is the best!"</EM>. As the old saying says: <EM>"Trust but verify"</EM>. There are too many technologies out there to pick from, and it might take
+an enormous investment of time and money to try to validate each one,
+before deciding what is your favorite one. Keeping this idea in mind, I
+will try to present different combinations of other technologies and
+mod_perl or just stand alone mod_perl. How these things work together, what
+are the good and what are the bad properties of each one, how hard to
+install and maintain them, when a specific approach should be picked and
+when it should be avoided.
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Perl_Download">Perl Download</A></H2></CENTER>
+To make myself clear, I would not talk about any technologies but the ones
+useful in tandem with mod_perl.
+
<P>
-Perl is most likely already installed on your machine, but you should at
-least check the version you using. It is highly recommended that you have
-at least perl version 5.004 or higher. You can get the latest perl version
-from <A HREF="http://www.perl.com/">http://www.perl.com/</A> . Try the
-direct download link <A
-HREF="http://www.perl.com/pace/pub/perldocs/latest.html">http://www.perl.com/pace/pub/perldocs/latest.html</A>
-.
+Please let me stress it again: <STRONG>DO NOT</STRONG> blindly copy someone's setup and hope for a good. Choose what is best for
+your situation.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Apache_Download">Apache Download</A></H2></CENTER>
+<CENTER><H1><A NAME="mod_perl_Deploying_Schemas_Overv">mod_perl Deploying Schemas Overview</A></H1></CENTER>
<P>
-Get the latest apache webserver from <A
-HREF="http://www.apache.org">http://www.apache.org</A> . Try the direct
-download link <A
-HREF="http://www.apache.org/dist/">http://www.apache.org/dist/</A> .
+There are several different ways to build, configure and deploy your
+mod_perl enabled site. Some of the ways are:
+<OL>
+<P><LI>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Mod_Perl_Download">Mod_Perl Download</A></H2></CENTER>
+1 binary and 1 config file (one big binary for mod_perl)
+
+<P><LI>
<P>
-Get the latest mod_perl from <A
-HREF="http://perl.apache.org">http://perl.apache.org</A> . Try the direct
-download link <A
-HREF="http://perl.apache.org/dist/">http://perl.apache.org/dist/</A> .
+2 binaries and 2 config files (one big binary for mod_perl and one small
+for static object like images)
+<P><LI>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Configuration_and_Installation">Configuration and Installation</A></H1></CENTER>
+1 DSO style compile and 2 config files (Dynamic linking lets you compile
+once and have a big and a small binary in memory BUT you have to deal with
+a freshly made solution that has week documentation and is still subject to
+change and is rather more complex)
+
+<P><LI>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Perl">Perl</A></H2></CENTER>
+Any of the 3 approaches above plus proxy server in the http accelerator
+mode.
+
+</OL>
<P>
-First install perl. Follow the instructions in the distribution's INSTALL
-file. During the configuration stage (while running
-<CODE>./Configure</CODE>), make sure you answer <CODE>YES</CODE> to:
+If you are a newbie, I would recommend you to start with the first option
+and work on getting your feet wet with apache and mod_perl, then decide
+whether to move to a second one for production work or move up to the more
+state-of-the-art-yet-suspiciously-new DSO system (third) or/and proven to
+be good forth option from above.
<P>
-<PRE> Do you wish to use dynamic loading? [y]
-</PRE>
+Option 1 will kill you in production if you load out a lot of static data
+with a 2-12 MB webserver process. On the other hand while testing you will
+have no other server interaction to mask or add to your errors.
+
<P>
-You will want this feature on to dynamically load the Perl
-Modules/extensions.
+Option 2 means keeping two compiles but lets you seriously tune the two
+binaries to their exact purpose. On the other hand you have to deal with
+proxying or fancy site design to keep the two servers in step. Choose
+serving on multiple ports, multiple IPs, etc...
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Apache">Apache</A></H2></CENTER>
+Option 3 (DSO) -- as mentioned above -- means playing with the bleeding
+edge. Also the <CODE>mod_so</CODE> adds size and complexity to your binaries. The benefit being that modules
+can be added and removed with out recompiling and even shared amongst
+multiple servers. Again, it is bleeding edge and still sort of platform
+wonky so YMMV. See
+<A HREF="././scenario.html#mod_perl_server_as_DSO">mod_perl server as DSO</A>.
+
<P>
-It is a good idea to try to install the Apache webserver without mod_perl
-first. This way, if something going wrong, you will know that it's not the
-Apache server's problem. But you can skip this stage if you already have a
-working (non-mod_perl) Apache server, or if you're just the daring type. In
-any case you should unpack the Apache source distribution, preferably at
-the same level as the mod_perl distribution.
+Option 4 (proxy in http accelerator mode) - should make you lots of good
+things, once correctly configured and tuned.
<P>
-<PRE> % ls -l /usr/src
- drwxr-xr-x 8 stas bar 2048 Oct 6 09:46 apache_1.3.2/
- drwxr-xr-x 19 stas bar 4096 Oct 2 14:33 mod_perl-1.16/
-</PRE>
+The rest of this chapter discuss the pros and the cons of each of the
+presented schemas. <A HREF="././scenario.html#">Real World Scenarios of Implementing Various Strategies</A> describes the implementation techniques of described schemas.
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Mod_Perl">Mod_Perl</A></H2></CENTER>
+<CENTER><H1><A NAME="Stand_alone_mod_perl_Enabled_Apa">Stand alone mod_perl Enabled Apache Server</A></H1></CENTER>
<P>
-Now we come to the main point of this document.
+The first approach is to implement a straightforward mod_perl server. Just
+take your plain apache server and add to it the mod_perl, like you add any
+other apache module. You continue to run it at the port it was running
+before. You probably want to try this before you proceed to more
+sophisticated and complex techniques.
<P>
-Here I'll give only a short example of mod_perl installation. You should
-read the real world scenarios for a more complete description.
+The Advantages:
+<UL>
+<P><LI>
<P>
-As with any perl package, the installation of mod_perl is very easy and
-standard. <CODE>perldoc INSTALL</CODE> will guide you thru the configuration and installation process.
+Simplicity of installation. You just follow the installation instructions,
+configure it, restart the server and you have finished.
+<P><LI>
<P>
-The fastest way to install would be:
+You do not have to think about using additional ports as we will see later.
-<P>
-<PRE> % perl Makefile.PL APACHE_SRC=../apache_1.3.2/src \
- DO_HTTPD=1 USE_APACI=1 PERL_MARK_WHERE=1 EVERYTHING=1
- % make && make test && make install
-</PRE>
<P>
-(Note: if you use an apache version different then apache_1.3.2, change the
-version number in the example above and in all later examples
-appropriately)
+You get a very fast server, you see an enormous speedup from the first
+moment you have started to use it.
+</UL>
<P>
-To change the installation target (either if you aren't <CODE>root</CODE> or you need to install a second copy for testing purposes), assuming you
-use /foo/server as a base directory root, you have to run this:
+The Disadvantages:
-<P>
-<PRE> % perl Makefile.PL APACHE_SRC=../apache_1.3.2/src \
- DO_HTTPD=1 PERL_MARK_WHERE=1 EVERYTHING=1 \
- APACHE_PREFIX=/foo/server PREFIX=/foo/server
-</PRE>
+<UL>
+<P><LI>
<P>
-Where <CODE>PREFIX</CODE> specifies where to install the perl modules,
-<CODE>APACHE_PREFIX</CODE> - the same for the apache files.
+A mod_perl process' size is huge compared to the plain apache you have got
+used to (starting from 4Mb at the startup and growing to 10Mb and more,
+depending on what and how do you use it). You probably have a few tens of
+children processes. The memory adds up. Your memory demands are growing in
+an order of magnitude. But this is something you will have to live with, if
+you are in the mod_perl boat. Memory is cheap nowadays and the performance
+boost mod_perl gives to your services worths every 100Mb of RAM you add.
+
+<P>
+While you are calm to have these monsters to serve you scripts with the
+monsters' speed, you should be very worried about them serving your static
+objects, like images and html files. It means that if you will need more
+processes to serve these - more memory, the real overhead depends on static
+objects request rate. Remember that if your mod_perl code produces HTML
+code, which includes images each one will turn into a static object request
+(or only one request if you have the
+<CODE>KeepAlive</CODE> directive turned <CODE>ON</CODE>). Having another plain webserver to serve the static objects solves this
+not pleasant obstacle. Having a proxy server as a front end, caching the
+static objects and freeing the mod_perl processes from this burden is
+another solution. We will discuss both below.
+<P><LI>
<P>
-The next step is to configure the mod_perl sections of the apache conf
-files. See <A HREF="././config.html#">ModPerlConfiguration</A>
+Another drawback that you cannot afford is having the huge process to wait
+till the client with slow connection will receive the whole response. While
+it might take a few milliseconds for your script to complete the request,
+there is a chance it will be still busy for another 5 seconds or even
+minutes if the request has come from the slow connection client. As in the
+previous drawback, proxy comes to solve this problem. More on proxies
+later.
<P>
-Fire up the server with <CODE>/foo/server/sbin/apachectl start</CODE>, Watch the error log file if server doesn't start up (No error message
-will be printed to the console!)
+Proxying dynamic content is not going to help much if all the clients are
+on a fast local net. For example if you are an administrator of the
+Intranet. On opposite, it can make things worse. But still remember that
+some of your Intranet users might work from home through the slow modem
+links.
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="How_can_I_tell_whether_mod_perl_">How can I tell whether mod_perl is really installed</A></H1></CENTER>
+</UL>
<P>
-There a few ways. In older versions of apache ( < 1.3.2 ?) you could check that by running <CODE>httpd -v</CODE>, it no longer works. Now you should use <CODE>httpd -l</CODE>. Please notice that it is not enough to have it installed - you should of
-course configure it and restart the server.
+If you are new to mod_perl, this is probably the best way to get yourself
+started.
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Testing_by_checking_the_error_lo">Testing by checking the error_log file</A></H2></CENTER>
+Of course if your site is serving only the mod_perl scripts, this might be
+the most perfect choice for you!
+
<P>
-<PRE> [Thu Dec 3 17:27:52 1998] [notice] Apache/1.3.1 (Unix) mod_perl/1.15 configured -- resuming normal operations
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-</PRE>
+For implementation notes see :
+<A HREF="././scenario.html#One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl enabled Apache Servers</A>
+
+
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Testing_by_viewing_perl_status">Testing by viewing /perl-status</A></H2></CENTER>
+<CENTER><H1><A NAME="One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl enabled Apache Servers</A></H1></CENTER>
<P>
-Assuming that you have configured the <CODE><Location /perl-status</CODE>> Section in the server configuration file (refer to
-<A HREF="././config.html#">ModPerlConfiguration</A>), fetch: <A
-HREF="http://www.yourserver.com/perl-status">http://www.yourserver.com/perl-status</A>
-using your favorite Netscape browser :-)
+As I have mentioned before, when running your scripts under mod_perl, you
+will notice that the httpd processes consume a huge amount of memory, from
+5M to 25M and more. That is the price you pay for the enormous speed
+improvements under mod_perl.
<P>
-You should see something like this:
+It is an overkill to serve static objects like images and html documents
+with these large processes. The best approach is to run two servers: a very
+light plain apache server to serve static objects and a heavier mod_perl
+enabled apache server to take care of requests to dynamic (generated)
+objects (aka CGI).
-<P>
-<PRE> Embedded Perl version 5.00502 for Apache/1.3.1 (Unix) mod_perl/1.16
- process 50880, running since Tue Oct 6 14:31:45 1998
-</PRE>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Testing_via_telnet">Testing via telnet</A></H2></CENTER>
<P>
-Knowing the port you've configured Apache to listen on, you can use <CODE>telnet</CODE> to talk directly to the web server.
+Since now on, I will refer to these two servers as <STRONG>httpd_docs</STRONG>
+(vanilla apache) and <STRONG>httpd_perl</STRONG> (mod_perl enabled apache).
<P>
-Assume that you set <CODE>Port 8080</CODE> in the httpd.conf for your mod_perl enabled server. Telnet to your server
-at port 8080, and type <CODE>HEAD / HTTP/1.0</CODE> then press the <ENTER> key TWICE!
+The Advantages:
-<P>
-<PRE> % telnet yourserver.com 8080<ENTER>
- HEAD / HTTP/1.0<ENTER><ENTER>
-</PRE>
+<UL>
+<P><LI>
<P>
-You should see a response like this:
+Heavy mod_perl processes serving only dynamic requests. So we need much
+less servers - memory requirements are drastically going down. While this
+is always correct for static HTML object, you might still have a problem
+with static object requests from the generated HTML. You must use a fully
+qualified URL and not a relative one! When you generate an HTML which has
+relative references to images or other static object - client's browser
+sets its base url to point to
+<CODE>httpd_perl</CODE> server's. And all the image requests will go to the heavy <CODE>httpd_perl</CODE>. Be aware! You solve this by either using a full URLs to the <CODE>httpd_docs</CODE> server (the fastest) or rewriting the requests back to <CODE>httpd_docs</CODE> (much slower). This is not a problem if you hide the internal
+implementations, so client sees only one server running on port <CODE>80</CODE>. (<A HREF="././config.html#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>)
+<P><LI>
<P>
-<PRE> HTTP/1.1 200 OK
- Date: Tue, 01 Dec 1998 12:27:52 GMT
- Server: Apache/1.3.2 (Unix) mod_perl/1.16_01
- Connection: close
- Content-Type: text/html
-
- Connection closed.
-</PRE>
+<CODE>MaxClients</CODE>, <CODE>MaxRequestsPerChild</CODE> and related parameters now can be optimally tuned for both <CODE>httpd_docs</CODE> and <CODE>httpd_perl</CODE> servers, something we could not do before. This allows us to fine tune the
+memory usage and get a better server performance.
+
<P>
-So you see <CODE>Server: Apache/1.3.2 (Unix) mod_perl/1.16_01</CODE> - which says that you <STRONG>do</STRONG> have mod_perl installed and it is version 1.16_01. Of course in your case
-it would be the version you have installed.
+Now we can spawn many light weighted <CODE>httpd_docs</CODE> servers and just a few heavy <CODE>httpd_perl</CODE> servers.
+</UL>
<P>
-However, just because you've got mod_perl linked in there, that doesn't
-meant that you have your server configured to use mod_perl to handle Perl
-scripts. You will find the configuration assistance at
-<A HREF="././config.html#">ModPerlConfiguration</A>
+The Disadvantages:
+<UL>
+<P><LI>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Testing_via_a_CGI_script">Testing via a CGI script</A></H2></CENTER>
+An administration overhead.
+
+<UL>
+<P><LI>
<P>
-Another method is to invoke a CGI script which dumps the server's
-environment.
+A need for 2 different configuration files, 2 log files sets and etc. We
+need a special directories layout to manage these. While some directories
+can be shared between the two servers, like <CODE>include</CODE>
+directory, storing the apache include files (assuming that both are built
+from the same source distribution), most of them should be separated and
+configuration files updated to reflect the changes.
+<P><LI>
<P>
-Copy and paste the script below (no need for perl line!). Let's say you
-called it test.pl, you saved it into the root of the cgi scripts, and cgi
-root is mapped directly to /perl of your server.
+A need for 2 sets of controlling scripts (startup/shutdown)
+<P><LI>
<P>
-<PRE> print "Content-type: text/html\n\n";
- print "Server's environment<P>\n";
- print "<TABLE>";
- foreach ( keys %ENV ) {
- print "<TR><TD>$_ </TD><TD>$ENV{$_}</TR></TD>";
- }
- print "</TABLE>";
-</PRE>
+If you are processing log files, now you probably will have to merge the 2
+separate log files.
+
+</UL>
+<P><LI>
<P>
-Make it executable:
+We still have the problem of mod_perl process spending its precious time to
+server slow clients, when the request was processed long time ago, exactly
+like in 1 server approach. Proxy solves this, and will be covered in the
+next sections.
<P>
-<PRE> % chmod a+x test.pl
-</PRE>
+Exactly as with only one server approach, this is not a disadvantage if you
+are on the fast local Intranet. Most chances that you do not want a
+buffering server on your way.
+
+</UL>
<P>
-Now fetch the URL <A
-HREF="http://www.you.com:8080/perl/test.pl">http://www.you.com:8080/perl/test.pl</A>
-. You should see something like this (part of the output was snipped).
+For implementation notes see :
+<A HREF="././scenario.html#One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl enabled Apache Servers</A>
+
+
<P>
-<PRE> SERVER_SOFTWARE Apache/1.3.2 (Unix) mod_perl/1.16_01
- GATEWAY_INTERFACE CGI-Perl/1.1
- REQUEST_METHOD GET
- HTTP_ACCEPT image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
- MOD_PERL 1.16_01
- REQUEST_URI /perl/test.pl
- SCRIPT_NAME /perl/test.pl
- [...snipped]
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="One_light_non_Apache_and_One_mod">One light non-Apache and One mod_perl enabled Apache Servers</A></H1></CENTER>
<P>
-Now if I run the same script in mod_cgi mode (configured with /cgi-bin)
-(you'll need to add the perl line #!/bin/perl for the above script) and
-fetch <A
-HREF="http://www.you.com/cgi-bin/test.pl">http://www.you.com/cgi-bin/test.pl</A>
-.
+If the only functionality needed from the the light server is static
+objects serving, you can get away with non-apache servers, whose memory
+footprint is even smaller. <CODE>thttpd</CODE> has been reported to be about 5 times faster then apache (especially under
+a heavy load), since it is very simple and uses almost no memory (260k) and
+does not spawn child processes.
-<P>
-<PRE> SERVER_SOFTWARE Apache/1.3.2 (Unix)
- GATEWAY_INTERFACE CGI/1.1
- [...snipped]
-</PRE>
<P>
-You will see that two variables, <CODE>SERVER_SOFTWARE</CODE> and
-<CODE>GATEWAY_INTERFACE</CODE>, are different from the case above. This gives you a hint of how to tell
-in what mode you are running in your cgi scripts. I start all my cgi
-scripts that are mod_perl aware with:
+The Advantages:
+<UL>
+<P><LI>
<P>
-<PRE> BEGIN {
- # Auto-detect if we are running under mod_perl or CGI.
- $USE_MOD_PERL = ((exists $ENV{'GATEWAY_INTERFACE'}
- and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
- or exists $ENV{'MOD_PERL'} );
- # perl5.004 is a must under mod_perl
- require 5.004 if $USE_MOD_PERL;
- }
-</PRE>
+All the advantages of the 2 servers scenario.
+
+<P><LI>
<P>
-You might wonder why in the world you would need to know in what mode you
-are running. For example you will want to use <CODE>Apache::exit()</CODE>
-and not <CODE>CORE::exit()</CODE> in your scripts, but if you think that your script might be used in both
-environments (mod_cgi vs mod_perl), you will have to override the <CODE>exit()</CODE> subroutine and to make the runtime decision of what method you will use.
-For reasons and implementations see: <A HREF="././porting.html#using_exit_">Using exit()</A> and the whole
-<A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs to it</A> page.
+More memory saving. Apache is about 4 times bigger then <STRONG>thttpd</STRONG>, it if you spawn 30 children you use about 30M of memory, while <STRONG>thttpd</STRONG>
+uses only 260k - 100 times less! You could use the saved 30M to run more
+mod_perl servers.
+<P><LI>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Testing_via_lwp_request">Testing via lwp-request</A></H2></CENTER>
+Reported to be about 5 times faster then plain apache serving static
+objects.
+
+</UL>
<P>
-Yet another one. Why do I show all these approaches? While here they are
-serving a very simple purpose, they can be helpful in other situations.
+The Disadvantages:
+<UL>
+<P><LI>
<P>
-Assuming you have the libwww-perl (LWP) package installed (you will need it
-installed in order to pass mod_perl's <CODE>make test</CODE> anyway):
+Not that I know of :)
+</UL>
<P>
-<PRE> % lwp-request -e -d www.site.com
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Adding_a_Proxy_Server_in_http_Ac">Adding a Proxy Server in http Accelerator Mode</A></H1></CENTER>
<P>
-Will show you all the headers. (The <CODE>-d</CODE> option disables printing the response content.)
+At the beginning there were 2 servers: one - plain apache server, which was
+_very_ light, and configured to serve static objects, the other - mod_perl
+enabled, which was _very_ heavy and aimed to serve mod_perl scripts. We
+named them: <CODE>httpd_docs</CODE> and <CODE>httpd_perl</CODE>
+appropriately. The two servers coexisted at the same <CODE>IP(DNS)</CODE>
+by listening to different ports: 80 - for httpd_docs (e.g. <A
+HREF="http://www.nowhere.com/images/test.gif">http://www.nowhere.com/images/test.gif</A>
+) and 8080 for httpd_perl (e.g. <A
+HREF="http://www.nowhere.com:8080/perl/test.pl">http://www.nowhere.com:8080/perl/test.pl</A>
+). Note that I did not write <A
+HREF="http://www.nowhere.com:80">http://www.nowhere.com:80</A> for the
+first example, since port 80 is a default http port. (Note that later on, I
+will be moving the httpd_docs server to port 81.)
<P>
-<PRE> % lwp-request -e -d www.site.com | egrep '^Server:'
-</PRE>
+Now I am going to convince you that you _want_ to use a proxy server (in
+the http accelerator mode). The reasons are:
+
+<UL>
+<P><LI>
<P>
-To see the server's version only.
+Allow serving of static objects from the proxy's cache (objects that
+previously were entirely served by the httpd_docs server).
+
+<P>
+You get less I/O activity to read the object from the disk (proxy serves
+the most ``popular'' objects from the RAM memory - of course you benefit
+more if you allow the proxy server to consume more RAM). Since you do not
+wait for the I/O to be completed you serve the static objects faster. (I/O
++1 points, faster static object serving +1 point)
+
+<P><LI>
+<P>
+The proxy server acts as a sort of output buffer for the dynamic content.
+The mod_perl server sends the entire response to the proxy and is then free
+to deal with other requests. The proxy server is responsible for getting
+the response to the browser. So if the transfer is over a slow link, the
+mod_perl server is not waiting around for the data to move.
+
+<P>
+Using numbers is always more convincing :) Let's take a user connected to
+your site with 28.8 kbps (bps == bits/sec) modem. It means that a speed of
+user's link is 28.8/8 = 3.6 kbytes/sec. I assume an average generated HTML
+page to be of 10kb (kb == kilobytes) and pretty average script that
+generates this output in 0.5 secs. How much time the server will wait
+before user will get the whole output down his way? A simple calculation
+reveals pretty scaring numbers - it will have to wait for another 6 secs
+(20kb/3.6kb), when it could serve another 12 (6/0.5) requests at the time
+it was stalled. This very simple example shows us that we need 12 times
+less children running, which means you will need 12 fold times less memory
+(which is not quite true because some parts of the code are being shared).
+But you know that nowadays scripts return pages which sometimes are being
+blown up with javascript code and similar, which makes them of 100kb size
+and download time to be of... (This calculation was left to the reader as
+an exercise :)
+
+<P>
+To make your numbers of download time even worse let me remind you that
+many users like to open many browser windows and do many things at once
+(download files and visit _heavy_ sites). So the speed of 3.6kb/sec I was
+talking about before, many times 5-10 times smaller.
+
+<P>
+(+3 point for memory cut up, I give it 3 times more points for the savings
+we get with this most important functionality)
+
+<P><LI>
+<P>
+Also we are going to hide the details of the server's implementation. Users
+will never see ports in the URLs (more on that topic later). And you can
+have a few boxes serving the requests, and only one serves as a front end,
+which spreads the jobs between the servers in a way you configured it too.
+So you can actually put down one server down for upgrade, but end user will
+never notice that because the front end server will dispatch the jobs to
+other servers. (of course this is pretty big topic, and it would not be
+included in the scope of this document)
+
+<P>
+(+1 point for flexibility to change things at the background and making
+user to bookmark only one URL)
+
+<P><LI>
+<P>
+Of course there are drawbacks. Luckily, these are not functionality
+drawbacks, but more of administration hassle. Yes, you add another program
+to worry about, while proxies are generally stable you have to make sure to
+prepare proper startup and shutdown scripts, which are being run at the
+boot and reboot appropriately. May be a watchdog script running at the
+crontab.
+
+<P>
+Proxy servers can be configured to be light or heavy, admin must decide
+what gives the highest performance for his application. Proxy server like
+squid is light in the concept of having only one process serving all
+requests. But it can appear pretty heavy when it loads objects into memory
+for faster serving.
+
+<P>
+(-1 point for administration overhead, very small but overhead. -1 point
+for memory consuming)
+
+</UL>
+<P>
+So let's sum up the points. We have 4 (6-2) points for the proxy server and
+I believe I have succeeded to convince you, that you want it :)
+
+<P>
+If you are on the local network, then the big benefit of proxy buffering
+the output and feeding a slow client is gone. You are probably better off
+sticking with a straight mod_perl server in this case.
+
+<P>
+As of this writing 2 proxy implementations are known to be used in bundle
+with mod_perl - <STRONG>squid</STRONG> proxy server and <STRONG>mod_proxy</STRONG> which is a part of the apache server. Let's compare the 2 of them.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="squid_server">squid server</A></H1></CENTER>
+<P>
+The Advantages:
+
+<UL>
+<P><LI>
+<P>
+Caching of static objects. So these are being served much faster taking
+that your cache size is big enough to keep the most requested objects in
+the cache.
+
+<P><LI>
+<P>
+Buffering of dynamic content, by taking the burden of returning the
+generated by mod_perl server content to the slow clients, thus freeing
+mod_perl servers from wasteful waiting for the slow clients to download the
+data. Freed servers immediately switch to serve other requests, thus your
+number of required servers goes drastically down.
+
+<P><LI>
+<P>
+Non-linear URL space / server setup. You can use Squid to play some tricks
+with the URL space and/or domain based virtual server support.
+
+</UL>
+<P>
+The Disadvantages:
+
+<UL>
+<P><LI>
+<P>
+Proxying dynamic content is not going to help much if all the clients are
+on a fast local net. Also, a message on the squid mailing list implied that
+squid only buffers in 16k chunks so it would not allow a mod_perl to
+complete immediately if the output is larger.
+<P><LI>
+<P>
+Speed. Squid is not very fast today when compared to plain file based web
+servers available. Only if you are using a lot of dynamic features such as
+mod_perl or similar speed is a reason to use Squid, and then only if the
+application and server is designed with caching in mind.
+
+<P><LI>
+<P>
+Memory usage. Squid uses quite a bit of memory.
+
+<P><LI>
+<P>
+HTTP protocol level. Squid is pretty much a HTTP/1.0 server, which
+seriously limits the deployment of HTTP/1.1 features.
+
+<P><LI>
+<P>
+HTTP headers / dates, freshness. Your server will be giving out ``old''
+pages, which might confuse downstream/client caches. Also chances are that
+you will be giving out stale pages.
+
+<P><LI>
+<P>
+Stability. Compared to plain web servers Squid is not the most stable.
+
+</UL>
<P>
+The presented pros and cons lead to an idea, that probably you might want
+squid more for its dynamic content buffering features, if your server
+serves mostly dynamic requests. So in this situation it is better to have a
+plain apache server serving static objects, and squid proxying the mod_perl
+enabled server only. At least when performance is the goal.
+
+<P>
+For implementation details see: <A HREF="././scenario.html#Running_1_webserver_and_squid_in">Running 1 webserver and squid in httpd accelerator mode</A> and
+<A HREF="././scenario.html#Running_2_webservers_and_squid_i">Running 2 webservers and squid in httpd accelerator mode</A>
+
+
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Starting_to_use_the_server">Starting to use the server</A></H1></CENTER>
+<CENTER><H1><A NAME="apache_s_mod_proxy">apache's mod_proxy</A></H1></CENTER>
+<P>
+I do not think the difference in speed between apache's <CODE>ProxyPass</CODE>
+and squid is relevant for most sites, since the real value of what they do
+is buffering for slow client connections. However squid runs as a single
+process and probably consumes fewer system resources. The trade-off is that
+mod_rewrite is easy to use if you want to spread parts of the site across
+different back end servers, and mod_proxy knows how to fix up redirects
+containing the back-end server's idea of the location. With squid you can
+run a redirector process to proxy to more than one back end, but there is a
+problem to fix redirects in a way that keeps the client's view of both
+server names and port numbers in all cases. The difficult case being where
+you have DNS aliases that map to the same IP address for an alias and you
+want the redirect to use port 80 (when the server is really on a different
+port) but you want it to keep the specific name the browser sent so it does
+not change in the client's 'location' window.
+
+<P>
+The Advantages:
+
+<UL>
+<P><LI>
+<P>
+No additional server is needed. We keep the 1 plain plus 1 mod_perl enabled
+apache servers. All you need is to enable the <CODE>mod_proxy</CODE> in
+<CODE>httpd_docs</CODE> and add a few lines to <CODE>httpd.conf</CODE> file.
+
+<P><LI>
+<P>
+<CODE>ProxyPass</CODE> and <CODE>ProxyPassReverse</CODE> directives allows you to hide the internal redirects, so if <CODE>http://nowhere.com/modperl/</CODE> is actually
+<CODE>http://localhost:81/modperl/</CODE>, it will be absolutely transparent for user. <CODE>ProxyPass</CODE> redirects the request to the mod_perl server, and when it gets the respond, <CODE>ProxyPassReverse</CODE> rewrites the URL back to the original one, e.g:
+
+<P>
+<PRE> ProxyPass /modperl/ <A HREF="http://localhost:81/modperl/">http://localhost:81/modperl/</A>
+ ProxyPassReverse /modperl/ <A HREF="http://localhost:81/modperl/">http://localhost:81/modperl/</A>
+</PRE>
+<P><LI>
+</UL>
+<P>
+The Disadvantages:
+
+<UL>
+<P><LI>
+</UL>
<P>
-Now you are ready to start writing CGIs. Note here -- you better start
-writing your scripts with an eye towards making them clean (i.e., <CODE>use strict;</CODE>), and with understanding of the new running environment. You have to learn
-how to write correctly for mod_perl. There is nothing new, the major item
-to remember is that your script would not die after it finishes serving the
-request, but will stay in memory and might affect all other scripts running
-under the same server process (child). You will read more about it in the
-following sections: <A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs</A>
+For implementation see <A HREF="././scenario.html#Using_mod_proxy">Using mod_proxy</A>.
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
@@ -1135,7 +1658,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="start.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="scenario.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -1147,8 +1671,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/17/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
@@ -1175,11 +1699,14 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: Server Installation. Real World scenarios</TITLE>
+ <TITLE>mod_perl guide: Real World Scenarios of Implementing Various Strategies</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -1190,53 +1717,44 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Server Installation. Real World scenarios</H1>
+Real World Scenarios of Implementing Various Strategies</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="strategy.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="install.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
-
- <LI><A HREF="#Making_a_Strategic_Decision">Making a Strategic Decision</A>
- <LI><A HREF="#Deciding_on_a_Directory_Layout">Deciding on a Directory Layout</A>
- <LI><A HREF="#Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A>
- <UL>
-
- <LI><A HREF="#httpd_docs_Server">httpd_docs Server</A>
- <LI><A HREF="#httpd_perl_Server_mod_perl_">httpd_perl Server (mod_perl):</A>
- <LI><A HREF="#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>
- </UL>
- <LI><A HREF="#More_mod_perl_deploying_schemas">More mod_perl deploying schemas</A>
- <LI><A HREF="#mod_perl_and_proxy_server">mod_perl and proxy server</A>
+ <LI><A HREF="#Before_you_dive_into_the_gory_de">Before you dive into the gory details</A>
+ <LI><A HREF="#One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl enabled Apache Servers</A>
<UL>
- <LI><A HREF="#Incentives">Incentives</A>
- <LI><A HREF="#Squid_proxy_server_in_httpd_acce">Squid proxy server in httpd accelerator mode</A>
+ <LI><A HREF="#Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A>
<UL>
- <LI><A HREF="#Running_a_squid_and_2_webservers">Running a squid and 2 webservers scenario</A>
- <LI><A HREF="#Running_a_squid_and_1_mod_perl_a">Running a squid and 1 mod_perl apache server scenario</A>
+ <LI><A HREF="#Building_the_httpd_docs_Server">Building the httpd_docs Server</A>
+ <LI><A HREF="#Building_the_httpd_perl_Server_">Building the httpd_perl Server (mod_perl):</A>
</UL>
- </UL>
+ <LI><A HREF="#Configuration_of_the_servers">Configuration of the servers</A>
+ <UL>
- <LI><A HREF="#Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A>
- <LI><A HREF="#Is_it_possible_to_determine_whic">Is it possible to determine which options were given to modperl's Makefile.PL</A>
- <LI><A HREF="#mod_perl_as_DSO">mod_perl as DSO</A>
- <LI><A HREF="#Installation_problems">Installation problems</A>
- <UL>
+ <LI><A HREF="#Basic_httpd_docs_Server_s_Config">Basic httpd_docs Server's Configuration</A>
+ <LI><A HREF="#Basic_httpd_perl_Server_s_Config">Basic httpd_perl Server's Configuration</A>
+ </UL>
- <LI><A HREF="#make_test_fails">make test fails</A>
</UL>
+ <LI><A HREF="#Running_2_webservers_and_squid_i">Running 2 webservers and squid in httpd accelerator mode</A>
+ <LI><A HREF="#Running_1_webserver_and_squid_in">Running 1 webserver and squid in httpd accelerator mode</A>
+ <LI><A HREF="#Using_mod_proxy">Using mod_proxy</A>
+ <LI><A HREF="#mod_perl_server_as_DSO">mod_perl server as DSO</A>
</UL>
<!-- INDEX END -->
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -1246,25 +1764,33 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<CENTER><H1><A NAME="Making_a_Strategic_Decision">Making a Strategic Decision</A></H1></CENTER>
+<CENTER><H1><A NAME="Before_you_dive_into_the_gory_de">Before you dive into the gory details</A></H1></CENTER>
<P>
-When running your scripts under mod_perl, you will notice that the httpd
-processes consume a huge amount of memory, from 5M to 25M and more. That is
-the price you pay for the great speed improvements under mod_perl -- the
-function of Perl embedded in the Apache server binary.
+There are many implementation schemes, each one has its benefits and
+drawbacks. Please take your time to read the <A HREF="././strategy.html#">Picking the Right Strategy</A> chapter before you proceed. This section
+<EM>merely</EM> details the implementation, installation and configuration. It hardly
+mentions the pros and cons of each scheme detailed here.
<P>
-It is overkill to serve the static objects like images and html docs with
-these larger processes. The best approach is to run two servers: a light
-Apache server with no mod_perl compiled in serving the static pages, and a
-heavy Apache/mod_perl server serving the CGIs in mod_perl mode only. This
-section describes a real world example ready for copy and paste to start
-with. You will probably will want to change the base directories, but
+This section describes a real world scenarios ready for almost blindly copy
+and paste, you may think of it as a kick start. You will probably will want
+to change the directories and some parameters like your hostname, but
basically you can use it as it is.
<P>
+<STRONG>Important:</STRONG> Since both apache and mod_perl tend to release new versions so often (which
+is good :), I will be not able to update the version numbers I present
+here. So make sure to work with the latest version, even if you see me
+using some older one. I prefer to use the real version number instead of <CODE>x.xx.xx</CODE>.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl enabled Apache Servers</A></H1></CENTER>
+<P>
Since we run two apache servers we will need two different configuration
files, log files and etc. We need a special directory layout. While some of
the directories can be shared between the two servers (assuming that both
@@ -1273,185 +1799,195 @@
(Apache/mod_perl).
<P>
-Of course there are more ways to use mod_perl. Please read <A HREF="././scenario.html#More_mod_perl_deploying_schemas">More mod_perl deploying schemas</A>.
+For this illustration, we will use <CODE>/usr/local</CODE> as our <EM>root</EM>
+directory. The Apache installation directories will be stored under this
+root (<CODE>/usr/local/bin</CODE>, <CODE>/usr/local/etc</CODE> and etc...)
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Deciding_on_a_Directory_Layout">Deciding on a Directory Layout</A></H1></CENTER>
<P>
-For this illustration, we will use <CODE>/usr/apps</CODE> as our <STRONG>root</STRONG> directory. The Apache installation directories will be stored under this
-root (<CODE>/usr/apps/bin</CODE>, <CODE>/usr/apps/etc</CODE> and etc...)
+First let's prepare the sources. We will assume that all the sources go
+into <CODE>/usr/src</CODE> dir. It is better when you use two separate copies of apache sources. Since
+you probably will want to tune each apache version at separate and to do
+some modifications and recompilations as the time goes. Having two
+independent source trees will prove helpful, unless you use <CODE>DSO</CODE>, which is covered in this section.
<P>
-First let's prepare the sources. We will assume that all the sources go to
-/usr/apps/usr/src dir. First let's make two subdirectories:
+Make two subdirectories:
<P>
-<PRE> % mkdir /usr/apps/usr/src/httpd_docs
- % mkdir /usr/apps/usr/src/httpd_perl
+<PRE> % mkdir /usr/src/httpd_docs
+ % mkdir /usr/src/httpd_perl
</PRE>
<P>
-Now we will put the Apache source into <CODE>/usr/apps/usr/src/httpd_docs</CODE>:
+Now we will put the Apache source into <CODE>/usr/src/httpd_docs</CODE>:
<P>
-<PRE> % cd /usr/apps/usr/src/httpd_docs
- % gzip -dc /path/to/tarfile/apache.tar.gz | tar xvf -
+<PRE> % cd /usr/src/httpd_docs
+ % gzip -dc /path/to/tarfile/apache.tar.gz | tar xvf -
</PRE>
<P>
-(Replace '<CODE>/path/to/tarfile</CODE>' with the location where you've downloaded the file in all examples.)
-Let's check:
+If you have a gnu tar:
<P>
-<PRE> % ls -l
- drwxr-xr-x 8 stas stas 2048 Oct 29 17:38 apache_1.3.2/
+<PRE> % tar xvzf /path/to/apache.tar.gz
</PRE>
<P>
-Now we will prepare the httpd_perl server sources:
+Replace everywhere <CODE>/path/to/tarfile</CODE> with a path to a downloaded file.
<P>
-<PRE> % cd /usr/apps/usr/src/httpd_perl
- % gzip -dc /path/to/tarfile/apache.tar.gz | tar xvf -
- % gzip -dc /path/to/tarfile/modperl.tar.gz | tar xvf -
+<PRE> % cd /usr/src/httpd_docs
+ % ls -l
+ drwxr-xr-x 8 stas stas 2048 Apr 29 17:38 apache_1.3.6/
</PRE>
<P>
-Let's check:
+Now we will prepare the <CODE>httpd_perl</CODE> server sources:
<P>
-<PRE> % ls -l
- drwxr-xr-x 8 stas stas 2048 Oct 29 17:38 apache_1.3.2/
- drwxr-xr-x 8 stas stas 2048 Oct 29 17:38 modperl-1.16/
+<PRE> % cd /usr/src/httpd_perl
+ % gzip -dc /path/to/apache.tar.gz | tar xvf -
+ % gzip -dc /path/to/modperl.tar.gz | tar xvf -
+ % ls -l
+ drwxr-xr-x 8 stas stas 2048 Apr 29 17:38 apache_1.3.6/
+ drwxr-xr-x 8 stas stas 2048 Apr 29 17:38 modperl-1.19/
</PRE>
<P>
Time to decide on the desired directory structure layout (where the apache
files go):
<P>
-<PRE> ROOT = /usr/apps
+<PRE> ROOT = /usr/local
</PRE>
<P>
The two servers can share the following directories (so we will not
duplicate data):
<P>
-<PRE> /usr/apps/bin/
- /usr/apps/lib
- /usr/apps/include/
- /usr/apps/man/
- /usr/apps/share/
+<PRE> /usr/local/bin/
+ /usr/local/lib
+ /usr/local/include/
+ /usr/local/man/
+ /usr/local/share/
</PRE>
<P>
<STRONG>Important:</STRONG> we assume that both servers are built from the same Apache source version.
<P>
-Servers store their specific files either in httpd_docs or httpd_perl:
+Servers store their specific files either in <CODE>httpd_docs</CODE> or
+<CODE>httpd_perl</CODE> sub-directories:
<P>
-<PRE> /usr/apps/etc/httpd_docs/
- httpd_perl/
-
- /usr/apps/sbin/httpd_docs/
- httpd_perl/
+<PRE> /usr/local/etc/httpd_docs/
+ httpd_perl/
- /usr/apps/var/httpd_docs/logs/
- proxy/
- run/
- httpd_perl/logs/
- proxy/
- run/
+ /usr/local/sbin/httpd_docs/
+ httpd_perl/
+
+ /usr/local/var/httpd_docs/logs/
+ proxy/
+ run/
+ httpd_perl/logs/
+ proxy/
+ run/
</PRE>
<P>
After you will complete the compilation and installation of the both
servers, you will have to configure them. To make things clear before we
proceed into details, you should configure the
-<CODE>/usr/apps/etc/httpd_docs/httpd.conf</CODE> as a plain apache (something that is not covered here, but which is very
-simple) and <CODE>Port</CODE>
+<CODE>/usr/local/etc/httpd_docs/httpd.conf</CODE> as a plain apache and <CODE>Port</CODE>
directive to be 80 for example. And
-<CODE>/usr/apps/etc/httpd_perl/httpd.conf</CODE> to configure for mod_perl server (which is covered in <A HREF="././config.html#">Server Configuration</A> section) and of course whose <CODE>Port</CODE> should be different then the one
-<CODE>httpd_docs</CODE> server listens to (e.g. 8080). I will discuss the port numbers issue later.
+<CODE>/usr/local/etc/httpd_perl/httpd.conf</CODE> to configure for mod_perl server and of course whose <CODE>Port</CODE> should be different then the one
+<CODE>httpd_docs</CODE> server listens to (e.g. 8080). The port numbers issue will be discussed
+later.
<P>
The next step is to configure and compile the sources: Below are the
-procedures to compile both servers taking into account the above directory
-layout:
+procedures to compile both servers taking into account the directory layout
+we have just decided to use.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A></H1></CENTER>
+<CENTER><H2><A NAME="Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A></H2></CENTER>
<P>
Important note: In the installation scenario I have used apache and
mod_perl release numbers. As you understand I would not change these
numbers every time a new version of either apache or mod_perl will be
-released. So please if you see <CODE>apache_1.3.2</CODE> it does not mean
-<CODE>1.3.2</CODE> is the latest apache version. Thank you!
+released. So please if you see <CODE>apache_1.3.6</CODE> it does not mean
+<CODE>1.3.6</CODE> is the latest apache version.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="httpd_docs_Server">httpd_docs Server</A></H2></CENTER>
+<CENTER><H3><A NAME="Building_the_httpd_docs_Server">Building the httpd_docs Server</A></H3></CENTER>
<DL>
-<P><DT><STRONG><A NAME="item_Configuration">Configuration</A></STRONG><DD>
+<P><DT><STRONG><A NAME="item_Sources">Sources Configuration</A></STRONG><DD>
<P>
-<PRE> % cd /usr/apps/usr/src/httpd_docs/apache_1.3.2
-
- % make clean
-
- # gcc - compiles httpd by 100K+ smaller then cc on AIX!
-
- % env CC=gcc \
- ./configure --prefix=/usr/apps \
- --sbindir=/usr/apps/sbin/httpd_docs \
- --sysconfdir=/usr/apps/etc/httpd_docs \
- --localstatedir=/usr/apps/var/httpd_docs \
- --runtimedir=/usr/apps/var/httpd_docs/run \
- --logfiledir=/usr/apps/var/httpd_docs/logs \
- --proxycachedir=/usr/apps/var/httpd_docs/proxy \
- --enable-module=include --enable-module=rewrite
+<PRE> % cd /usr/src/httpd_docs/apache_1.3.6
+ % make clean
+ % env CC=gcc \
+ ./configure --prefix=/usr/local \
+ --sbindir=/usr/local/sbin/httpd_docs \
+ --sysconfdir=/usr/local/etc/httpd_docs \
+ --localstatedir=/usr/local/var/httpd_docs \
+ --runtimedir=/usr/local/var/httpd_docs/run \
+ --logfiledir=/usr/local/var/httpd_docs/logs \
+ --proxycachedir=/usr/local/var/httpd_docs/proxy
</PRE>
<P>
-Note: add --layout to see the resulting directories' layout without
-actually making the configuration.
+If you need some other modules, like mod_rewrite and mod_include (SSI), add
+them here as well:
-<P><DT><STRONG><A NAME="item_Compilation">Compilation:</A></STRONG><DD>
<P>
-<PRE> % make
-
- % make install
+<PRE> --enable-module=include --enable-module=rewrite
+</PRE>
+<P>
+Note: gcc - compiles httpd by 100K+ smaller then cc on AIX, remove the
+<CODE>env CC=gcc</CODE> if you want to use the default compiler.
+
+<P>
+Note: add <CODE>--layout</CODE> to see the resulting directories' layout without actually making the
+configuration.
+
+<P><DT><STRONG>Sources Compilation:</STRONG><DD>
+<P>
+<PRE> % make
+ % make install
</PRE>
<P>
-Rename 'httpd' to 'http_docs'
+Rename <CODE>httpd</CODE> to <CODE>http_docs</CODE>
+
+
<P>
-<PRE> % mv /usr/apps/sbin/httpd_docs/httpd /usr/apps/sbin/httpd_docs/httpd_docs
+<PRE> % mv /usr/local/sbin/httpd_docs/httpd \
+ /usr/local/sbin/httpd_docs/httpd_docs
</PRE>
<P>
-Now update the apachectl utility to point to the new httpd name (via your
-favorite text editor or by using perl)
+Now update an <STRONG>apachectl</STRONG> utility to point to the renamed httpd via your favorite text editor or by
+using perl:
<P>
-<PRE> % perl -p -i -e 's|httpd_docs/httpd|httpd_docs/httpd_docs|' \
- /usr/apps/sbin/httpd_docs/apachectl
+<PRE> % perl -p -i -e 's|httpd_docs/httpd|httpd_docs/httpd_docs|' \
+ /usr/local/sbin/httpd_docs/apachectl
</PRE>
</DL>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="httpd_perl_Server_mod_perl_">httpd_perl Server (mod_perl):</A></H2></CENTER>
+<CENTER><H3><A NAME="Building_the_httpd_perl_Server_">Building the httpd_perl Server (mod_perl):</A></H3></CENTER>
<P>
Before you start to configure the mod_perl sources, you should be aware
that there are a few Perl modules that have to be installed before building
mod_perl. You will be alerted if any required modules are missing when you
-run the <CODE>perl Makefile.PL</CODE> command line below. If you discover that you do not have these, go to your
-nearest CPAN repository (if you do not know what is it, go to <A
-HREF="http://www.perl.com/CPAN">http://www.perl.com/CPAN</A> ) or run the
-CPAN interactive shell via the command line <CODE>perl -MCPAN -e
-shell</CODE> .
+run the <CODE>perl Makefile.PL</CODE> command line below. If you discover that some are missing, pick them from
+your nearest CPAN repository (if you do not know what is it, make a visit
+to <A HREF="http://www.perl.com/CPAN">http://www.perl.com/CPAN</A> ) or run
+the <CODE>CPAN</CODE> interactive shell via the command line <CODE>perl -MCPAN -e shell</CODE>.
<P>
-Now back to installation.
+Make sure the sources are clean:
<P>
-<PRE> % cd /usr/apps/usr/src/httpd_perl/apache_1.3.2
- % make clean
- % cd /usr/apps/usr/src/httpd_perl/mod_perl-1.16
- % make clean
+<PRE> % cd /usr/src/httpd_perl/apache_1.3.6
+ % make clean
+ % cd /usr/src/httpd_perl/mod_perl-1.19
+ % make clean
</PRE>
<P>
It is important to <STRONG>make clean</STRONG> since some of the versions are not binary compatible (e.g apache 1.3.3 vs
@@ -1459,42 +1995,54 @@
1.3.4 header files.
<P>
-Here I did not find a way to compile with gcc (but perl was compiled with
-cc so we have to compile with the same compiler!!!
+Here I did not find a way to compile with gcc (my perl was compiled with cc
+so we have to compile with the same compiler!!!
<P>
-Notice that <STRONG>ALL</STRONG> <CODE>APACI_ARGS</CODE> (below) must be passed as one long line!!!
+Notice that <STRONG>ALL</STRONG> <CODE>APACI_ARGS</CODE> (below) must be passed as one long line!!! I have wrapped them to allow
+easier reading.
+<P>
+<PRE> % cd /usr/src/httpd_perl/mod_perl-1.19
+</PRE>
<P>
-<PRE> % cd /usr/apps/usr/src/httpd_perl/mod_perl-1.16
+<PRE> % /usr/local/bin/perl Makefile.PL \
+ APACHE_PREFIX=/usr/local/ \
+ APACHE_SRC=../apache_1.3.6/src \
+ DO_HTTPD=1 \
+ USE_APACI=1 \
+ PERL_MARK_WHERE=1 \
+ PERL_STACKED_HANDLERS=1 \
+ ALL_HOOKS=1 \
+ APACI_ARGS=--sbindir=/usr/local/sbin/httpd_perl,
+ --sysconfdir=/usr/local/etc/httpd_perl,
+ --localstatedir=/usr/local/var/httpd_perl,
+ --runtimedir=/usr/local/var/httpd_perl/run,
+ --logfiledir=/usr/local/var/httpd_perl/logs,
+ --proxycachedir=/usr/local/var/httpd_perl/proxy
</PRE>
<P>
-<PRE> % /usr/apps/bin/perl Makefile.PL \
- APACHE_PREFIX=/usr/apps/ \
- APACHE_SRC=../apache_1.3.2/src \
- DO_HTTPD=1 \
- USE_APACI=1 \
- PERL_MARK_WHERE=1 \
- PERL_STACKED_HANDLERS=1 \
- ALL_HOOKS=1 \
- APACI_ARGS=--sbindir=/usr/apps/sbin/httpd_perl,
- --sysconfdir=/usr/apps/etc/httpd_perl,
- --localstatedir=/usr/apps/var/httpd_perl,
- --runtimedir=/usr/apps/var/httpd_perl/run,
- --logfiledir=/usr/apps/var/httpd_perl/logs,
- --proxycachedir=/usr/apps/var/httpd_perl/proxy,
- --enable-module=rewrite
+As with <CODE>httpd_docs</CODE> you might need other modules like
+<CODE>mod_rewrite</CODE>, so add them here:
+
+<P>
+<PRE> --enable-module=rewrite
</PRE>
+<P>
+Note: <CODE>PERL_STACKED_HANDLERS=1</CODE> is needed for <CODE>Apache::DBI</CODE>
+
+
+
<P>
-Notes: <CODE>-DPERL_STACKED_HANDLERS</CODE> needed for <CODE>Apache::DBI</CODE>
+Now, build, test and install the <CODE>httpd_perl</CODE>.
<P>
-<PRE> % make && make test && make install
+<PRE> % make && make test && make install
</PRE>
<P>
-Note: Apache puts a stripped version of httpd at
-/usr/apps/sbin/httpd_perl/httpd the original version sits at
-/usr/apps/usr/src/httpd_perl/apache_1.3.2/src/httpd
+Note: Apache puts a stripped version of <CODE>httpd</CODE> at
+<CODE>/usr/local/sbin/httpd_perl/httpd</CODE>. The original version including debugging symbols (if you need to run a
+debugger on this executable) is located at <CODE>/usr/src/httpd_perl/apache_1.3.6/src/httpd</CODE>.
<P>
Note: You may have noted that we did not go to the apache's source dir and
@@ -1505,247 +2053,151 @@
the configuration, log and document trees.
<P>
-If make test fails, look into t/logs and see what is in there. Also see <A HREF="././scenario.html#make_test_fails">make test fails</A>.
+If <CODE>make test</CODE> fails, look into <CODE>t/logs</CODE> and see what is in there. Also see <A HREF="././install.html#make_test_fails">make test fails</A>.
<P>
While doing <CODE>perl Makefile.PL ...</CODE> mod_perl might complain by warning you about missing <CODE>libgdbm</CODE>. Users reported that it is actually crucial, and you must have it in order
-to successfully complete the mod_perl build process.
+to successfully complete the mod_perl building process.
<P>
-Rename the 'httpd' to 'httpd_perl'
+Now rename the <CODE>httpd</CODE> to <CODE>httpd_perl</CODE>:
<P>
-<PRE> % mv /usr/apps/sbin/httpd_perl/httpd \
- /usr/apps/sbin/httpd_perl/httpd_perl
+<PRE> % mv /usr/local/sbin/httpd_perl/httpd \
+ /usr/local/sbin/httpd_perl/httpd_perl
</PRE>
<P>
-Now update the apachectl utility to point to a new httpd name (by hand or
-by using perl)
+Update the apachectl utility to point to renamed httpd name:
<P>
-<PRE> % perl -p -i -e 's|httpd_perl/httpd|httpd_perl/httpd_perl|' \
- /usr/apps/sbin/httpd_perl/apachectl
+<PRE> % perl -p -i -e 's|httpd_perl/httpd|httpd_perl/httpd_perl|' \
+ /usr/local/sbin/httpd_perl/apachectl
</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Configuration_of_the_servers">Configuration of the servers</A></H2></CENTER>
<P>
-Now proceed to the <A HREF="././config.html#">Server Configuration</A> section.
+Now when we have completed the building process, the last stage before
+running the servers, is to configure them.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Publishing_port_numbers_differen">Publishing port numbers different from 80</A></H2></CENTER>
+<CENTER><H3><A NAME="Basic_httpd_docs_Server_s_Config">Basic httpd_docs Server's Configuration</A></H3></CENTER>
<P>
-It is advised not to publish the 8080 (or alike) port number in URLs, but
-rather using a proxying rewrite rule in the thin (httpd_docs) server:
+Configuring of <CODE>httpd_docs</CODE> server is a very easy task. Open
+<CODE>/usr/local/etc/httpd_docs/httpd.conf</CODE> into your favorite editor (starting from version 1.3.4 of Apache - there is
+only one file to edit). And configure it as you always do. Make sure you
+configure the log files and other pathes according to the directory layout
+we decided to use.
-<P>
-<PRE> RewriteRule .*/perl/(.*) <A HREF="http://my.url:8080/perl/">http://my.url:8080/perl/</A>$1 [P]
-</PRE>
<P>
-One problem with publishing 8080 port numbers is that I was told that IE
-4.x has a bug when re-posting data to a non-port-80 url. It drops the port
-designator, and uses port 80 anyway.
+Start the server with:
<P>
+<PRE> /usr/local/sbin/httpd_docs/apachectl start
+</PRE>
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="More_mod_perl_deploying_schemas">More mod_perl deploying schemas</A></H1></CENTER>
+<CENTER><H3><A NAME="Basic_httpd_perl_Server_s_Config">Basic httpd_perl Server's Configuration</A></H3></CENTER>
<P>
-There are several different ways to build, configure and deploy your
-mod_perl enabled site. Some of the ways are:
+Here we will make a basic configuration of the <CODE>httpd_perl</CODE> server. We edit the <CODE>/usr/local/etc/httpd_perl/httpd.conf</CODE> file. As with
+<CODE>httpd_docs</CODE> server configuration, make sure that log and other files directives are set
+to point to the right places, according to the chosen directory layout.
-<OL>
-<P><LI>
<P>
-1 binary and 1 config file (suffer a big binary for all kind of objects)
+One first thing to do is to set a <CODE>Port</CODE> directive - it should be different from <CODE>80</CODE> since we cannot bind 2 servers to use the same port number on the same
+machine. Here we will use <8080>. Some developers use port <CODE>81</CODE>, but you can bind to it, only if you have root permissions. If you are
+running on multiuser machine, there is a chance someone already uses that
+port, or will start using it in the future - which as you understand might
+cause a collision. If you are the only user on your machine, basically you
+can pick any not used port number. Port number choosing is a controversial
+topic, for many organizations use firewalls, which may block some of the
+ports, or enable only a known ones. From my experience the most used port
+numbers are: <CODE>80</CODE>, <CODE>81</CODE>, <CODE>8000</CODE> and <CODE>8080</CODE>. Personally, I prefer the port <CODE>8080</CODE>. Of course with 2 server scenario you can hide the nonstandard port number
+from users, by either using the mod_proxy's
+<CODE>ProxyPass</CODE> or proxy server like squid.
-<P><LI>
<P>
-2 binaries and 2 config files (one big binary for mod_perl and one small
-for static object like images)
+For more details see <A HREF="././config.html#Publishing_port_numbers_differen">Publishing port numbers different from 80 </A>, <A HREF="././scenario.html#Running_1_webserver_and_squid_in">Running 1 webserver and squid in httpd accelerator mode</A>,
+<A HREF="././scenario.html#Running_2_webservers_and_squid_i">Running 2 webservers and squid in httpd accelerator mode</A>
+and <A HREF="././scenario.html#Using_mod_proxy">Using mod_proxy</A>.
-<P><LI>
<P>
-1 DSO style compile and 2 configs (Dynamic linking lets you compile once
-and have a big and a small binary in memory BUT you have to deal with a
-freshly made solution that has week documentation and is still subject to
-change and is rather more complex)
+Now we proceed to mod_perl specific directives. A good idea will be to add
+them all at the end of the <CODE>httpd.conf</CODE>, since you are going to fiddle a lot of them.
-<P><LI>
<P>
-Any of the 3 approaches above plus proxy server in the http accelerator
-mode (squid was reported to be the best as of this writing).
+First, you need to specify the location where all mod_perl scripts will be
+located.
-</OL>
<P>
-If you are a newbie, I would recommend you to start with the first option
-and work on getting your feet wet with apache and mod_perl, then decide
-whether to move to a second one for production work or move up to the more
-state-of-the-art-yet-suspiciously-new DSO system (third) )or/and proven to
-be good forth option from above.
+Add the following configuration directive:
<P>
-Option 1 will kill you in production if you load out a lot of static data
-with a 2-12 MB webserver process. On the other hand while testing you will
-have no other server interaction to mask or add to your errors.
+<PRE> # mod_perl scripts will be called from
+ Alias /perl/ /usr/local/myproject/perl/
+</PRE>
+<P>
+From now on, all requests starting with <CODE>/perl</CODE> will be executed under <CODE>mod_perl</CODE> and will be mapped to the files in
+<CODE>/usr/local/myproject/perl/</CODE>.
<P>
-Option 2 means keeping two compiles but lets you seriously tune the two
-binaries to their exact purpose. On the other hand you have to deal with
-proxying or fancy site design to keep the two servers in step. Choose
-serving on multiple ports, multiple IPs, etc...
+Now we should configure the <CODE>/perl</CODE> location.
<P>
-Option 3 (DSO) -- as mentioned above -- means playing with the bleeding
-edge. Also the <CODE>mod_so</CODE> adds size and complexity to your binaries. The benefit being that modules
-can be added and removed with out recompiling and even shared amongst
-multiple servers. Again, it is bleeding edge and still sort of platform
-wonky so YMMV. See
-<A HREF="././scenario.html#mod_perl_as_DSO">mod_perl as DSO</A>
-
-<P>
-Option 4 (proxy in http accelerator mode) - should make you lots of good
-things, once correctly configured and tuned. Stay tuned for more
-information.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="mod_perl_and_proxy_server">mod_perl and proxy server</A></H1></CENTER>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Incentives">Incentives</A></H2></CENTER>
-<P>
-At the beginning there were 2 apache servers: one - plain apache server,
-which was _very_ light, and configured to serve static objects, the other -
-mod_perl enabled, which was _very_ heavy and aimed to serve mod_perl
-scripts. We named them: httpd_docs and httpd_perl appropriately. The two
-servers coexisted at the same <CODE>IP(DNS)</CODE> by listening to
-different ports: 80 - for httpd_docs (e.g. <A
-HREF="http://www.nowhere.com/images/test.gif">http://www.nowhere.com/images/test.gif</A>
-) and 8080 for httpd_perl (e.g. <A
-HREF="http://www.nowhere.com:8080/perl/test.pl">http://www.nowhere.com:8080/perl/test.pl</A>
-). Note that I did not write <A
-HREF="http://www.nowhere.com:80">http://www.nowhere.com:80</A> for the
-first example, since port 80 is a default http port. (Note that later on, I
-will be moving the httpd_docs server to port 81.)
-
-<P>
-Now I am going to convince you that you _want_ to use a proxy server (in
-the http accelerator mode). The reasons are:
-
-<UL>
-<P><LI>
-<P>
-Allow serving of static objects from the proxy's cache (objects that
-previously were entirely served by the httpd_docs server).
-
-<P>
-You get less I/O activity to read the object from the disk (proxy serves
-the most ``popular'' objects from the RAM memory - of course you benefit
-more if you allow the proxy server to consume more RAM). Since you do not
-wait for the I/O to be completed you serve the static objects faster. (I/O
-+1 points, faster static object serving +1 point)
-
-<P><LI>
-<P>
-The proxy server acts as a sort of output buffer for the dynamic content.
-The mod_perl server sends the entire response to the proxy and is then free
-to deal with other requests. The proxy server is responsible for getting
-the response to the browser. So if the transfer is over a slow link, the
-mod_perl server is not waiting around for the data to move.
-
-<P>
-Using numbers is always more convincing :) Let's take a user connected to
-your site with 28.8 kbps (bps == bits/sec) modem. It means that a speed of
-user's link is 28.8/8 = 3.6 kbytes/sec. I assume an average generated HTML
-page to be of 10kb (kb == kilobytes) and pretty average script that
-generates this output in 0.5 secs. How much time the server will wait
-before user will get the whole output down his way? A simple calculation
-reveals pretty scaring numbers - it will have to wait for another 6 secs
-(20kb/3.6kb), when it could serve another 12 (6/0.5) requests at the time
-it was stalled. This very simple example shows us that we need 12 times
-less children running, which means you will need 12 fold times less memory
-(which is not quite true because some parts of the code are being shared).
-But you know that nowadays scripts return pages which sometimes are being
-blown up with javascript code and similar, which makes them of 100kb size
-and download time to be of... (This calculation was left to the reader as
-an exercise :)
-
-<P>
-To make your numbers of download time even worse let me remind you that
-many users like to open many browser windows and do many things at once
-(download files and visit _heavy_ sites). So the speed of 3.6kb/sec I was
-talking about before, many times 5-10 times smaller.
-
-<P>
-(+3 point for memory cut up, I give it 3 times more points for the savings
-we get with this most important functionality)
-
-<P><LI>
-<P>
-Also we are going to hide the details of the server's implementation. Users
-will never see ports in the URLs (more on that topic later). And you can
-have a few boxes serving the requests, and only one serves as a front end,
-which spreads the jobs between the servers in a way you configured it too.
-So you can actually put down one server down for upgrade, but end user will
-never notice that because the front end server will dispatch the jobs to
-other servers. (of course this is pretty big topic, and it would not be
-included in the scope of this document)
-
+<PRE> PerlModule Apache::Registry
+</PRE>
<P>
-(+1 point for flexibility to change things at the background and making
-user to bookmark only one URL)
-
-<P><LI>
+<PRE> <Location /perl>
+ #AllowOverride None
+ SetHandler perl-script
+ PerlHandler Apache::Registry
+ Options ExecCGI
+ allow from all
+ PerlSendHeader On
+ </Location>
+</PRE>
<P>
-Of course there are drawbacks. Luckily, these are not functionality
-drawbacks, but more of administration hassle. Yes, you add another program
-to worry about, while proxies are generally stable you have to make sure to
-prepare proper startup and shutdown scripts, which are being run at the
-boot and reboot appropriately. May be a watchdog script running at the
-crontab.
+This configuration causes all scripts that are called with a <STRONG>/perl</STRONG>
+path prefix to be executed under the <STRONG>Apache::Registry</STRONG> module and as a CGI (so the <STRONG>ExecCGI</STRONG>, if you omit this option the script will be printed to the caller's
+browser as a plain text or will possibly will trigger a 'Save-As' window). <STRONG>Apache::Registry</STRONG> module lets you run almost unaltered CGI/perl scripts under <CODE>mod_perl</CODE>. <CODE>PerlModule</CODE>
+directive is an equivalent of perl's <CODE>require()</CODE>. We load the
+<STRONG>Apache::Registry</STRONG> module before we use it in the <CODE>PerlHandler</CODE> in the <CODE>Location</CODE> configuration.
<P>
-Proxy servers can be configured to be light or heavy, admin must decide
-what gives the highest performance for his application. Proxy server like
-squid is light in the concept of having only one process serving all
-requests. But it can appear pretty heavy when it loads objects into memory
-for faster serving.
+<STRONG>PerlSendHeader On</STRONG> tells the server to send an HTTP header to the browser on every script
+invocation. You will want to turn this off for nph (non-parsed-headers)
+scripts.
<P>
-(-1 point for administration overhead, very small but overhead. -1 point
-for memory consuming)
+This is only a very basic configuration. <A HREF="././config.html#">Server Configuration</A> section covers the rest of the details.
-</UL>
<P>
-So let's sum up the points. We have 4 (6-2) points for the proxy server and
-I believe I have succeeded to convince you, that you want it :)
+Start the server with:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Squid_proxy_server_in_httpd_acce">Squid proxy server in httpd accelerator mode</A></H2></CENTER>
+<PRE> /usr/local/sbin/httpd_perl/apachectl start
+</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="Running_a_squid_and_2_webservers">Running a squid and 2 webservers scenario</A></H3></CENTER>
+<CENTER><H1><A NAME="Running_2_webservers_and_squid_i">Running 2 webservers and squid in httpd accelerator mode</A></H1></CENTER>
<P>
-OK, Now when you are convinced that you must have a proxy server, let's
-proceed. As many people suggested using the squid server as the best, we
-will go for it. While I have detailed the mod_perl server installation, you
-are on your own with installing the squid server. I run linux, so I have
-got the rpm package, installed it, configured the
-<CODE>/etc/squid/squid.conf</CODE>, fired off the server and was all set. Basically once you have the squid
-installed, you just need to modify the default <CODE>squid.conf</CODE> the way I will explain below and you are done.
+While I have detailed the mod_perl server installation, you are on your own
+with installing the squid server (See <A HREF="././help.html#">Getting Helped</A> for more details). I run linux, so I have got the rpm package, installed
+it, configured the <CODE>/etc/squid/squid.conf</CODE>, fired off the server and was all set. Basically once you have the squid
+installed, you just need to modify the default <CODE>squid.conf</CODE> the way I will explain below, then you are ready to run the server.
<P>
First, lets understand what do we have in hands and what do we want from
-squid. We have an httpd_docs and httpd_perl servers listening on ports 81
-and 8080 accordingly (we have to move the httpd_docs server to port 81,
-since port 80 will be taken over by squid). Both reside on the same machine
-as squid. We want squid to listen on port 80, forward a single static
-object request to the port httpd_docs server listens to, and dynamic
-request to httpd_perl's port. Both servers return the data to the proxy
-server (unless it is already cached in the squid), so user never sees the
-ports and never knows that there might be more then one server running.
-Proxy server makes all the magic behind it transparent to user. Do not
-confuse it with
-<STRONG>mod_rewrite</STRONG>, where a server redirects the request somewhere according to the rules and
+squid. We have an <CODE>httpd_docs</CODE> and <CODE>httpd_perl</CODE> servers listening on ports 81 and 8080 accordingly (we have to move the
+httpd_docs server to port 81, since port 80 will be taken over by squid).
+Both reside on the same machine as squid. We want squid to listen on port
+80, forward a single static object request to the port httpd_docs server
+listens to, and dynamic request to httpd_perl's port. Both servers return
+the data to the proxy server (unless it is already cached in the squid), so
+user never sees the ports and never knows that there might be more then one
+server running. Proxy server makes all the magic behind it transparent to
+user. Do not confuse it with <STRONG>mod_rewrite</STRONG>, where a server redirects the request somewhere according to the rules and
forgets about it. The described functionality is being known as <CODE>httpd accelerator mode</CODE> in proxy dialect.
<P>
@@ -1837,9 +2289,9 @@
<P>
Even if you insert user-ID and date in your page, caching can save
-resources when you set the expiration time to 1 second. A user might
-doubleclick where a single click would do, thus sending two requests in
-parallel, squid could serve the second.
+resources when you set the expiration time to 1 second. A user might double
+click where a single click would do, thus sending two requests in parallel,
+squid could serve the second.
<P>
But if you are lazy, or just have too many things to deal with, you can
@@ -1938,11 +2390,11 @@
$|=1;
while (<>) {
- # redirect to mod_perl server
+ # redirect to mod_perl server
print($_), next if
- s|<A HREF="http://127">http://127</A>\.0\.0\.1:81/perl|<A HREF="http://www.nowhere.com:8080/perl">http://www.nowhere.com:8080/perl</A>|o;
+ s|<A HREF="http://127">http://127</A>\.0\.0\.1:81/perl|<A HREF="http://www.nowhere.com:8080/perl">http://www.nowhere.com:8080/perl</A>|o;
- # default - static server
+ # default - static server
print;
}
</PRE>
@@ -1995,6 +2447,8 @@
<P>
Modify the <CODE>squid.conf</CODE>
+
+
<P>
<PRE> http_port 80
tcp_incoming_address 123.123.123.3
@@ -2010,7 +2464,7 @@
I think that you must also have in the /etc/hosts an entry:
<P>
-<PRE> 127.0.0.1 localhost.localdomain localhost
+<PRE> 127.0.0.1 localhost.localdomain localhost
</PRE>
<P>
But generally it is always there in first place.
@@ -2029,16 +2483,20 @@
you have one, or to leave a note on your pages asking users to update their
bookmarks. You could avoid this problem if you did not publish this non-80
port. See
-<A HREF="#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>.
+<A HREF="././config.html#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>.
<P>
<META> Need to write up a section about server logging with squid.
-X-Forward-Host header. One thing I sure would like to know is how requests
-are logged with this setup. I have, as most everyone I imagine, log
-rotation, analysis, archiving scripts and they all assume a single log.
-Does one have different logs that have to be merged (up to 3 for each
-server + squid) ? Even when squid responds to a request out of its cache
-I'd still want the thing to be logged. </META>
+One thing I sure would like to know is how requests are logged with this
+setup. I have, as most everyone I imagine, log rotation, analysis,
+archiving scripts and they all assume a single log. Does one have different
+logs that have to be merged (up to 3 for each server + squid) ? Even when
+squid responds to a request out of its cache I'd still want the thing to be
+logged. </META>
+
+<P>
+See <A HREF="././scenario.html#Using_mod_proxy">Using mod_proxy</A> for information about
+<CODE>X-Forwarded-For</CODE>.
<P>
To save you keystrokes, here is the whole modified <CODE>squid.conf</CODE>:
@@ -2093,7 +2551,7 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="Running_a_squid_and_1_mod_perl_a">Running a squid and 1 mod_perl apache server scenario</A></H3></CENTER>
+<CENTER><H1><A NAME="Running_1_webserver_and_squid_in">Running 1 webserver and squid in httpd accelerator mode</A></H1></CENTER>
<P>
When I was first told about the squid, I thought: ``Hey I can drop now the <CODE>httpd_docs</CODE> server and to have only squid and <CODE>httpd_perl</CODE>
servers``. Since all my static objects will be cached by squid, I do not
@@ -2114,10 +2572,10 @@
So I have decided to have even more administration overhead and to stick to
the squid, httpd_docs and httpd_perl scenario, where I can optimize and
fine tune everything. Of course this can be not your case. If you are
-feeling like that the scenario from the previous section is too complicated
-for you make it simpler. Have only one server with mod_perl built in and
-let the squid to do most of the job that plain light apache used to do. As
-I have explained in the last paragraph, you should pick this lighter setup
+feeling that the scenario from the previous section is too complicated for
+you, make it simpler. Have only one server with mod_perl built in and let
+the squid to do most of the job that plain light apache used to do. As I
+have explained in the last paragraph, you should pick this lighter setup
only if you can make squid cache most of your static objects. If it cannot,
your mod_perl server will do the work we do not want it to.
@@ -2126,7 +2584,7 @@
squid. Then use a similar configuration from the previous section, but now
httpd_docs is not there anymore. Also we do not need the redirector anymore
and we specify <CODE>httpd_accel_host</CODE> as a name of the server and not <CODE>virtual</CODE>. We also do not need to bind two servers on the same port anymore because
-we do not redirect anymore (do there is no need for <CODE>Bind</CODE> and <CODE>Listen</CODE> directives in the httpd.conf).
+we do not redirect anymore (There is no more need for <CODE>Bind</CODE> and <CODE>Listen</CODE> directives in the httpd.conf).
<P>
The modified configuration (see the explanations in the previous section):
@@ -2175,82 +2633,75 @@
</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A></H1></CENTER>
+<CENTER><H1><A NAME="Using_mod_proxy">Using mod_proxy</A></H1></CENTER>
<P>
-Yes, no problem with that. Follow the instructions above and when you
-encounter APACI_ARGS use your home directory (or some other directory which
-you have write access to as a prefix, for example,
-<CODE>/home/stas/www</CODE>) and everything will be installed there. There is a chance that some perl
-libs will be not installed on your server by root and you will have to
-install these locally too. See the <A
-HREF="http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html#7">http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html#7</A>
-for more information on local perl installations.
+The server on port 80 answers html requests directly and proxies the
+modperl enabled directory like this:
<P>
-You will not be able to have the server listen to a port lower then 1024 if
-you are not starting it as <CODE>root</CODE>, so choose a port number above 1024. (I use 8080 in most cases). Note that
-you will have to use a URL like <CODE>http://www.you.com:8080</CODE> in that case, but that is not a problem since generally users do not
-directly access URLs to CGI scripts, but rather are directed to them from a
-link on a web page or as the '<CODE>ACTION</CODE>' of an HTML form, so they should not know at all that the port is
-different from the default port 80.
-
+<PRE> ProxyPass /modperl/ <A HREF="http://localhost:81/modperl/">http://localhost:81/modperl/</A>
+ ProxyPassReverse /modperl/ <A HREF="http://localhost:81/modperl/">http://localhost:81/modperl/</A>
+</PRE>
<P>
-If you want your Apache server to start automatically on system reboot, you
-will need to invoke the server startup script from somewhere within the
-init scripts on your host. (This is often somewhere under <CODE>/etc/rc.d</CODE>, but this path can vary depending upon the flavor of Unix you are using.)
+<CODE>PPR</CODE> is the saving grace here, that makes Apache a win for me over Squid. That
+cleans up redirects and stuff to remove the :81 from the URIs. Very nice.
<P>
-One more important thing to keep in mind is system resources. Mod_perl is
-memory hungry -- if you run a lot of mod_perl processes on that machine
-(and it's not your own host...), most likely the system administrator of
-the host will ask you to shutdown your mod_perl server, or to find another
-home for it. You have a few solutions:
+Ask Bjoern Hansen has written a <CODE>mod_proxy_add_forward.c</CODE> module for Apache, that sets the <CODE>X-Forwarded-For</CODE> field when doing a <CODE>ProxyPass</CODE>, similar to what Squid can do. His patch is at: <A
+HREF="http://modules.apache.org/search?id=124">http://modules.apache.org/search?id=124</A>
+or at <A
+HREF="ftp://ftp.netcetera.dk/pub/apache/">ftp://ftp.netcetera.dk/pub/apache/</A>
+. Basically, that module adds an extra HTTP header to proxying requests.
+You can access that header in the mod_perl-enabled server, and set the IP
+of the remote server. You won't need to compile anything into the back-end
+server, just put something like the following into your mod_perl handler:
<P>
-<STRONG>a</STRONG>. Reduce resource usage - see <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>
-
+<PRE> my $real_client;
+ if (defined($real_client = $::r->header_in('X-Forwarded-For'))) {
+ $::r->connection->remote_ip($real_client);
+ }
+</PRE>
<P>
-<STRONG>b</STRONG>. Ask your ISP if you can put a dedicated machine into their computer room
-and be root there.
+See how it works? From that point on, the remote IP address is correct.You
+should be able to access REMOTE_ADDR as usual.
<P>
-<STRONG>c</STRONG>. Look for another ISP with lots of resources or one that supports mod_perl
-(not likely)
+IF you are using Apache::{Registry,PerlRun} - do it like this:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Is_it_possible_to_determine_whic">Is it possible to determine which options were given to modperl's Makefile.PL</A></H1></CENTER>
-<P>
-It is possible to determine which options were given to modperl's
-<CODE>Makefile.PL</CODE> during the configuration stage, so to be used later in recreating the same
-build tree when rebuilding the server. This is relevant only if did not use
-the default config parameters and altered some of them during the
-configuration stage.
+in startup.pl:
<P>
-I was into this problem many times. I am going to build something by
-passing some non default parameters to the config script and then later
-when I need to rebuild the tool either to upgrade it or to make an
-identical copy at some other machine, I have found that I do not remember
-what parameters did I altered.
-
+<PRE> sub My::ProxyRemoteAddr ($) {
+ my $r = shift;
+
+ # we'll only look at the X-Forwarded-For header if the requests
+ # comes from our proxy at localhost
+ return OK unless ($r->connection->remote_ip eq "127.0.0.1");
+
+ my @ip = split(/,\s*/, $r->header_in('X-Forwarded-For'));
+ if (my $ip = pop(@ip)) {
+ $r->connection->remote_ip($ip);
+ }
+
+ return OK;
+ }
+</PRE>
<P>
-The best solution for this problem is to prepare the run file with all the
-parameters that are about to be used and then run it instead of typing it
-all by hand. So later I will have the script handy to be reused.
+And in <CODE>httpd.conf</CODE>:
<P>
-mod_perl suggests using the <CODE>makepl_args.mod_perl</CODE> file which comes with mod_perl distribution. This is the file you specify
-all the parameters you are going to use.
-
+<PRE> PerlPostReadRequestHandler My::ProxyRemoteAddr
+</PRE>
<P>
-But if you have found yourself with a compiled tool and no traces of the
-specified parameters left, you can still find them out if the sources were
-not <CODE>make clean</CODE>'d. So you will find the apache specific parameters in <CODE>apache_x.x.x/config.status</CODE> and modperl's at in <CODE>mod_perl_x.xx/apaci/mod_perl.config</CODE>.
+You could do the same thing with other environment variables (though I
+think several of them are preserved, you will want to run some tests to see
+which ones).
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="mod_perl_as_DSO">mod_perl as DSO</A></H1></CENTER>
+<CENTER><H1><A NAME="mod_perl_server_as_DSO">mod_perl server as DSO</A></H1></CENTER>
<P>
To build the mod_perl as DSO add <CODE>USE_DSO=1</CODE> to the rest of configuration parameters, like:
@@ -2266,39 +2717,6 @@
<P>
<META> Incomplete </META>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Installation_problems">Installation problems</A></H1></CENTER>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="make_test_fails">make test fails</A></H2></CENTER>
-<P>
-There are two configuration parameters <CODE>PREP_HTTPD</CODE> and <CODE>DO_HTTPD</CODE>
-you can use in <CODE>perl Makefile.PL [options]</CODE>.
-
-<P>
-<CODE>DO_HTTPD=1</CODE> means default to 'y' for the two prompts (which source tree to configure
-against and to build the httpd in that tree).
-<CODE>PREP_HTTPD=1</CODE> just means default 'n' to the second prompt, meaning, do not build httpd
-(make) in the Apache source tree.
-
-<P>
-In other words if you use <CODE>PREP_HTTPD=1</CODE> the httpd will be not build. It will be build only if you use <CODE>DO_HTTPD=1</CODE> option and not use
-<CODE>PREP_HTTPD=1</CODE>.
-
-<P>
-If you did not build the httpd, chdir to the apache source, and execute:
-
-<P>
-<PRE> make
-</PRE>
-<P>
-Then return to the mod_perl source and run:
-
-<P>
-<PRE> make test
- make install
-</PRE>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -2308,7 +2726,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="strategy.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="install.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -2320,8 +2739,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
@@ -2348,11 +2767,14 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: Server Configuration</TITLE>
+ <TITLE>mod_perl guide: Installation Notes</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -2363,47 +2785,46 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Server Configuration</H1>
+Installation Notes</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="scenario.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="config.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
- <LI><A HREF="#Configuration">Configuration</A>
+ <LI><A HREF="#Configuration_and_Installation">Configuration and Installation</A>
<UL>
- <LI><A HREF="#Alias_Configurations">Alias Configurations</A>
+ <LI><A HREF="#Perl">Perl</A>
+ <LI><A HREF="#Apache">Apache</A>
+ <LI><A HREF="#Mod_Perl">Mod_Perl</A>
</UL>
- <LI><A HREF="#Location_Configuration">Location Configuration</A>
- <LI><A HREF="#_perl_status_location">/perl-status location </A>
- <LI><A HREF="#perl_startup_file">perl-startup file</A>
- <LI><A HREF="#PerlFreshRestart">PerlFreshRestart</A>
- <LI><A HREF="#What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A>
- <LI><A HREF="#Is_it_possible_to_preopen_a_DB_c">Is it possible to preopen a DB connection at the server startup?</A>
- <LI><A HREF="#Perl_behavior_controls">Perl behavior controls</A>
- <LI><A HREF="#Tuning_MinSpareServers_MaxSpareS">Tuning MinSpareServers MaxSpareServers StartServers MaxClients MaxRequestsPerChild </A>
- <LI><A HREF="#Perl_Sections">Perl Sections</A>
- <LI><A HREF="#Configuring_Apache_mod_perl_wi">Configuring Apache + mod_perl with mod_macro</A>
- <LI><A HREF="#General_pitfalls">General pitfalls</A>
+ <LI><A HREF="#How_can_I_tell_whether_mod_perl_">How can I tell whether mod_perl is really installed</A>
<UL>
- <LI><A HREF="#My_cgi_perl_code_is_being_return">My cgi/perl code is being returned as a plain text instead of being executed by the webserver?</A>
- <LI><A HREF="#My_script_works_under_cgi_bin_b">My script works under cgi-bin, but when called via mod_perl I see A 'Save-As' prompt</A>
- <LI><A HREF="#Is_there_a_way_to_provide_a_diff">Is there a way to provide a different startup.pl file for each individual virtual host</A>
- <LI><A HREF="#Is_there_a_way_to_modify_INC_on">Is there a way to modify @INC on a per-virtual-host basis. </A>
- <LI><A HREF="#Sometimes_the_script_from_one_vi">Sometimes the script from one virtual host calls a script with</A>
- <LI><A HREF="#the_server_no_longer_retrieves_t">the server no longer retrieves the DirectoryIndex files for a directory</A>
+ <LI><A HREF="#Testing_by_checking_the_error_lo">Testing by checking the error_log file</A>
+ <LI><A HREF="#Testing_by_viewing_perl_status">Testing by viewing /perl-status</A>
+ <LI><A HREF="#Testing_via_telnet">Testing via telnet</A>
+ <LI><A HREF="#Testing_via_a_CGI_script">Testing via a CGI script</A>
+ <LI><A HREF="#Testing_via_lwp_request">Testing via lwp-request</A>
+ </UL>
+
+ <LI><A HREF="#Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A>
+ <LI><A HREF="#Is_it_possible_to_determine_whic">Is it possible to determine which options were given to modperl's Makefile.PL</A>
+ <LI><A HREF="#Server_Installation">Server Installation</A>
+ <UL>
+
+ <LI><A HREF="#make_test_fails">make test fails</A>
</UL>
</UL>
<!-- INDEX END -->
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -2413,567 +2834,367 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<CENTER><H1><A NAME="Configuration">Configuration</A></H1></CENTER>
+<CENTER><H1><A NAME="Configuration_and_Installation">Configuration and Installation</A></H1></CENTER>
<P>
-The next step after building and installing your new mod_perl-enabled
-Apache server, is to configure the server's configuration files. To learn
-how to modify Apache's configuration files, please refer to the
-documentation included with the Apache distribution. or just view the files
-in conf directory and follow the instructions in these files - the embedded
-comments within the file do a good job of explaining the options.
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Perl">Perl</A></H2></CENTER>
<P>
-Before you start the mod_perl configuration, configure Apache, and see that
-it works. When done, return here to continue...
+First install perl. Follow the instructions in the distribution's INSTALL
+file. During the configuration stage (while running
+<CODE>./Configure</CODE>), make sure you answer <CODE>YES</CODE> to:
<P>
-[ Note that prior to version 1.3.4, the default Apache install used three
-configuration files -- <STRONG>httpd.conf</STRONG>, <STRONG>srm.conf</STRONG>, and <STRONG>access.conf</STRONG>. The 1.3.4 version began distributing the configuration directives in a
-single file -- <STRONG>httpd.conf</STRONG>. The remainder of this chapter refers to the location of the configuration
-directives using their historical location. ]
+<PRE> Do you wish to use dynamic loading? [y]
+</PRE>
+<P>
+You will want this feature on to dynamically load the Perl
+Modules/extensions.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Alias_Configurations">Alias Configurations</A></H2></CENTER>
-<P>
-First, you need to specify the location where all mod_perl scripts will be
-located.
-
+<CENTER><H2><A NAME="Apache">Apache</A></H2></CENTER>
<P>
-Add the following configuration directives to srm.conf:
+It is a good idea to try to install the Apache webserver without mod_perl
+first. This way, if something going wrong, you will know that it's not the
+Apache server's problem. But you can skip this stage if you already have a
+working (non-mod_perl) Apache server, or if you are just the daring type.
+In any case you should unpack the Apache source distribution, preferably at
+the same level as the mod_perl distribution.
<P>
-<PRE> # plain cgi-bin:
- ScriptAlias /cgi-bin/ /usr/apps/myproject/cgi/
-
- # Apache::Registry mode
- Alias /perl/ /usr/apps/myproject/cgi/
-
- # Apache::PerlRun mode
- Alias /cgi-perl/ /usr/apps/myproject/cgi/
+<PRE> % ls -l /usr/src
+ drwxr-xr-x 8 stas bar 2048 Oct 6 09:46 apache_1.3.6/
+ drwxr-xr-x 19 stas bar 4096 Oct 2 14:33 mod_perl-1.19/
</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Mod_Perl">Mod_Perl</A></H2></CENTER>
<P>
-Alias provides a mapping of URL to file system object.
+Now we come to the main point of this document.
<P>
-Alias defines the start of the URL path to the script you are referencing.
-For example, using the above configuration, fetching
-<STRONG>http://www.you.com/perl/test.pl</STRONG>, will cause the server to look for the file <STRONG>test.pl</STRONG> at <STRONG>/usr/apps/myproject/cgi</STRONG>, and execute it as an <STRONG>Apache::Registry</STRONG> script. The URL
-<STRONG>http://www.you.com/perl/test.pl</STRONG> will be mapped to
-<STRONG>/usr/apps/myproject/cgi/test.pl</STRONG>. This means you can have all your CGIs located at the same place at file
-system, and call the script in any of three modes simply by changing the
-directory name component of the URL (cgi-bin|perl|cgi-perl) - is not that
-cool? (That is the configuration you see above - all three Aliases point to
-the same directory within your file system, but of course they can be
-different). If your script does not seem to be working while running under
-mod_perl, you can easily call the script in straight mod_cgi mode without
-making any script changes (in most cases), but rather by changing the URL
-you invoke it by.
+Here I will give only a short example of mod_perl installation. You should
+read the real world scenarios for a more complete description.
<P>
-FYI: for modperl ScriptAlias is the same thing as an Alias command +
-'sethandler cgi-handler'. The latter will be overwritten if you enable
-Apache::Registry. In other words, ``ScriptAlias does not work for
-mod_perl'', it only appears to work when the additional configuration is in
-there. If the Apache::Registry configuration came before the ScriptAlias,
-scripts would be run under mod_cgi. While handy, ScriptAlias is a known
-kludge, always better to use 'Alias' and 'SetHandler'.
+As with any perl package, the installation of mod_perl is very easy and
+standard. <CODE>perldoc INSTALL</CODE> will guide you thru the configuration and installation process.
<P>
-Of course you can choose any other alias (you will use it later in
-http.conf), you can choose to use all three modes or only one of these (It
-is undesirable to run plain cgi-bin scripts from a mod_perl-enabled server
-- the price is too high, it is better to run these on plain Apache server.
-See <A HREF="././scenario.html#Making_a_strategic_decision">Real World scenario</A> for details.)
+The fastest way to install would be:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Location_Configuration">Location Configuration</A></H1></CENTER>
+<PRE> % perl Makefile.PL APACHE_SRC=../apache_1.3.6/src \
+ DO_HTTPD=1 USE_APACI=1 PERL_MARK_WHERE=1 EVERYTHING=1
+ % make && make test && make install
+</PRE>
<P>
-Now we will work with the httpd.conf file. I add all the mod_perl stuff at
-the end of the file, after the native Apache configurations.
+(Note: if you use an apache version different then apache_1.3.6, change the
+version number in the example above and in all later examples
+appropriately)
<P>
-First we add:
+To change the installation target (either if you are not <CODE>root</CODE> or you need to install a second copy for testing purposes), assuming you
+use /foo/server as a base directory root, you have to run this:
<P>
-<PRE> <Location /perl>
- #AllowOverride None
- SetHandler perl-script
- PerlHandler Apache::Registry
- Options ExecCGI
- allow from all
- PerlSendHeader On
- </Location>
+<PRE> % perl Makefile.PL APACHE_SRC=../apache_1.3.6/src \
+ DO_HTTPD=1 PERL_MARK_WHERE=1 EVERYTHING=1 \
+ APACHE_PREFIX=/foo/server PREFIX=/foo/server
</PRE>
<P>
-This configuration causes all scripts that are called with a <STRONG>/perl</STRONG>
-path prefix to be executed under the <STRONG>Apache::Registry</STRONG> module and as a CGI (so the <STRONG>ExecCGI</STRONG>, if you omit this option the script will be printed to the caller's
-browser as a plain text or will possibly will trigger a 'Save-As' window).
+Where <CODE>PREFIX</CODE> specifies where to install the perl modules,
+<CODE>APACHE_PREFIX</CODE> - the same for the apache files.
<P>
-<STRONG>PerlSendHeader On</STRONG> tells the server to send an HTTP header to the browser on every script
-invocation. You will want to turn this off for nph (non-parsed-headers)
-scripts.
+The next step is to configure the mod_perl sections of the apache conf
+files. See <A HREF="././config.html#">ModPerlConfiguration</A>
-<P>
-Remember the <STRONG>Alias</STRONG> from the section above? We must use the same Alias here, if you use
-Location that does not have the same Alias defined in srm.conf, the server
-will fail to locate the script in the file system. (We are talking about
-script execution here -- there are cases where Location is something that
-is being executed by the server itself, without having the corresponding
-file, like <A HREF="#perl_status">perl-status</A>.)
-<P>
-Note that sometimes you will have to add : PerlModule Apache::Registry
<P>
-before you specify the location that uses Apache::Registry as a
-PerlHandler. Basically you can start running the scripts in the
-Apache::Registry mode...
+Fire up the server with <CODE>/foo/server/sbin/apachectl start</CODE>, Watch the error log file if server does not start up (No error message
+will be printed to the console!)
<P>
-You have to do nothing about /cgi-bin (mod_cgi), since it has nothing to do
-with mod_perl
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="How_can_I_tell_whether_mod_perl_">How can I tell whether mod_perl is really installed</A></H1></CENTER>
<P>
-Here is a similar location configuration for Apache::PerlRun. (More about
-<A HREF="././porting.html#Apache_PerlRun_a_closer_look">Apache::PerlRun</A>)
+There a few ways. In older versions of apache ( < 1.3.6 ?) you could check that by running <CODE>httpd -v</CODE>, it no longer works. Now you should use <CODE>httpd -l</CODE>. Please notice that it is not enough to have it installed - you should of
+course configure it and restart the server.
<P>
-<PRE> <Location /cgi-perl>
- #AllowOverride None
- SetHandler perl-script
- PerlHandler Apache::PerlRun
- Options ExecCGI
- allow from all
- PerlSendHeader On
- </Location>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Testing_by_checking_the_error_lo">Testing by checking the error_log file</A></H2></CENTER>
+<P>
+<PRE> [Thu Dec 3 17:27:52 1998] [notice] Apache/1.3.1 (Unix) mod_perl/1.15 configured -- resuming normal operations
+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="_perl_status_location">/perl-status location</A></H1></CENTER>
+<CENTER><H2><A NAME="Testing_by_viewing_perl_status">Testing by viewing /perl-status</A></H2></CENTER>
<P>
-Adding a directive to enable a <STRONG>/perl-status</STRONG> location allows you to see many things about your server. See /<A HREF="././status.html#Configuration">perl-status</A>
+Assuming that you have configured the <CODE><Location /perl-status</CODE>> Section in the server configuration file (refer to
+<A HREF="././config.html#">ModPerlConfiguration</A>), fetch: <A
+HREF="http://www.yourserver.com/perl-status">http://www.yourserver.com/perl-status</A>
+using your favorite Netscape browser :-)
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="perl_startup_file">perl-startup file</A></H1></CENTER>
<P>
-Since many times you have to add many perl directives to the configuration
-file, it can be a good idea to put all of these into one file, so the
-configuration file will be cleaner, also you can call <STRONG>perl -c perl-startup</STRONG>
-to test the file's syntax. What does this take? Add this line to
-httpd.conf:
+You should see something like this:
<P>
-<PRE> # startup.perl loads all functions that we want to use within mod_perl
- Perlrequire /path/to/startup.pl
+<PRE> Embedded Perl version 5.00502 for Apache/1.3.1 (Unix) mod_perl/1.19
+ process 50880, running since Tue Oct 6 14:31:45 1998
</PRE>
<P>
-An example of perl-startup file:
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Testing_via_telnet">Testing via telnet</A></H2></CENTER>
+<P>
+Knowing the port you have configured Apache to listen on, you can use
+<CODE>telnet</CODE> to talk directly to the web server.
<P>
-<PRE> use strict;
-
- #modify @INC if needed
- use lib qw(/some/other/dir /some/bar/dir);
-
- # make sure we are in a sane environment.
- $ENV{GATEWAY_INTERFACE} =~ /^CGI-Perl/ or die "GATEWAY_INTERFACE not Perl!";
-
- # for things in the "/perl" URL
- use Apache::Registry;
-
- #load perl modules of your choice here
- #this code is interpreted *once* when the server starts
- use LWP::UserAgent ();
- use DBI ();
-
- # tell me more about warnings
- use Carp ();
- $SIG{__WARN__} = \&Carp::cluck;
-
- # Load CGI.pm and call its compile() method to precompile
- # (but not to import) its autoloaded methods.
- use CGI ();
- CGI->compile(':all');
+Assume that you set <CODE>Port 8080</CODE> in the httpd.conf for your mod_perl enabled server. Telnet to your server
+at port 8080, and type <CODE>HEAD / HTTP/1.0</CODE> then press the <ENTER> key TWICE!
+
+<P>
+<PRE> % telnet yourserver.com 8080<ENTER>
+ HEAD / HTTP/1.0<ENTER><ENTER>
</PRE>
<P>
-Note that starting with CGI::VERSION 2.46, the recommended method to
-precompile the code in CGI.pm is:
+You should see a response like this:
<P>
-<PRE> use CGI qw(-compile :all);
+<PRE> HTTP/1.1 200 OK
+ Date: Tue, 01 Dec 1998 12:27:52 GMT
+ Server: Apache/1.3.6 (Unix) mod_perl/1.19
+ Connection: close
+ Content-Type: text/html
+
+ Connection closed.
</PRE>
<P>
-But the old method is still available for backward compatibility.
+So you see <CODE>Server: Apache/1.3.6 (Unix) mod_perl/1.19</CODE> - which says that you <STRONG>do</STRONG> have mod_perl installed and it is version 1.19. Of course in your case it
+would be the version you have installed.
<P>
-See also <A HREF="././status.html#Configuration">Apache::Status</A>
+However, just because you have got mod_perl linked in there, that does not
+meant that you have your server configured to use mod_perl to handle Perl
+scripts. You will find the configuration assistance at
+<A HREF="././config.html#">ModPerlConfiguration</A>
+
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="PerlFreshRestart">PerlFreshRestart</A></H1></CENTER>
+<CENTER><H2><A NAME="Testing_via_a_CGI_script">Testing via a CGI script</A></H2></CENTER>
<P>
-To reload <STRONG>PerlRequire</STRONG>, <STRONG>PerlModule</STRONG>, other <CODE>use()'d</CODE> modules and flush the Apache::Registry cache
-on server restart, add:
+Another method is to invoke a CGI script which dumps the server's
+environment.
<P>
-<PRE> PerlFreshRestart On
+Copy and paste the script below (no need for perl line!). Let's say you
+called it test.pl, you saved it into the root of the cgi scripts, and cgi
+root is mapped directly to /perl of your server.
+
+<P>
+<PRE> print "Content-type: text/html\n\n";
+ print "Server's environment<P>\n";
+ print "<TABLE>";
+ foreach ( keys %ENV ) {
+ print "<TR><TD>$_ </TD><TD>$ENV{$_}</TR></TD>";
+ }
+ print "</TABLE>";
</PRE>
<P>
-Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
+Make it executable:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A></H1></CENTER>
+<PRE> % chmod a+x test.pl
+</PRE>
<P>
-Modules that are being loaded at the server startup will be shared among
-server children, so only one copy of each module will be loaded, thus
-saving a lot of RAM for you.
+Now fetch the URL <CODE>http://www.you.com:8080/perl/test.pl</CODE>. You should see something like this (part of the output was snipped).
<P>
-See <A HREF="././performance.html#Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A>
-
-
+<PRE> SERVER_SOFTWARE Apache/1.3.6 (Unix) mod_perl/1.19
+ GATEWAY_INTERFACE CGI-Perl/1.1
+ REQUEST_METHOD GET
+ HTTP_ACCEPT image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
+ MOD_PERL 1.19
+ REQUEST_URI /perl/test.pl
+ SCRIPT_NAME /perl/test.pl
+ [...snipped]
+</PRE>
+<P>
+Now if I run the same script in mod_cgi mode (configured with /cgi-bin)
+(you will need to add the perl line <CODE>#!/bin/perl</CODE> for the above script) and fetch <CODE>http://www.you.com/cgi-bin/test.pl</CODE>.
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Is_it_possible_to_preopen_a_DB_c">Is it possible to preopen a DB connection at the server startup?</A></H1></CENTER>
+<PRE> SERVER_SOFTWARE Apache/1.3.6 (Unix)
+ GATEWAY_INTERFACE CGI/1.1
+ [...snipped]
+</PRE>
<P>
-Yes! See <A HREF="././performance.html#Persistent_DB_Connections">Persistent DB Connections</A>
+You will see that two variables, <CODE>SERVER_SOFTWARE</CODE> and
+<CODE>GATEWAY_INTERFACE</CODE>, are different from the case above. This gives you a hint of how to tell
+in what mode you are running in your cgi scripts. I start all my cgi
+scripts that are mod_perl aware with:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Perl_behavior_controls">Perl behavior controls</A></H1></CENTER>
+<PRE> BEGIN {
+ # Auto-detect if we are running under mod_perl or CGI.
+ $USE_MOD_PERL = ((exists $ENV{'GATEWAY_INTERFACE'}
+ and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
+ or exists $ENV{'MOD_PERL'} );
+ # perl5.004 is a must under mod_perl
+ require 5.004 if $USE_MOD_PERL;
+ }
+</PRE>
<P>
-For <STRONG>PerlWarn</STRONG> and <STRONG>PerlTaintCheck</STRONG> see <A HREF="././porting.html#Switches_w_T">Switches -w, -T</A>
+You might wonder why in the world you would need to know in what mode you
+are running. For example you will want to use <CODE>Apache::exit()</CODE>
+and not <CODE>CORE::exit()</CODE> in your scripts, but if you think that your script might be used in both
+environments (mod_cgi vs. mod_perl), you will have to override the <CODE>exit()</CODE> subroutine and to make the runtime decision of what method you will use.
+For reasons and implementations see: <A HREF="././porting.html#Using_exit_">Using exit()</A> and the whole <A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs to it</A> page.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Tuning_MinSpareServers_MaxSpareS">Tuning MinSpareServers MaxSpareServers StartServers MaxClients MaxRequestsPerChild</A></H1></CENTER>
+<CENTER><H2><A NAME="Testing_via_lwp_request">Testing via lwp-request</A></H2></CENTER>
<P>
-See <A HREF="././performance.html#Tuning_the_Apache_s_configuratio">Tuning the Apache's configuration variables for the best performance</A>
+Yet another one. Why do I show all these approaches? While here they are
+serving a very simple purpose, they can be helpful in other situations.
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Perl_Sections">Perl Sections</A></H1></CENTER>
+Assuming you have the libwww-perl (LWP) package installed (you will need it
+installed in order to pass mod_perl's <CODE>make test</CODE> anyway):
+
<P>
-With <STRONG><Perl></Perl></STRONG> sections, it is possible to configure your server entirely in Perl.
+<PRE> % lwp-request -e -d www.site.com
+</PRE>
+<P>
+Will show you all the headers. (The <CODE>-d</CODE> option disables printing the response content.)
<P>
-<STRONG><Perl></STRONG> sections can contain *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 configurations
-directives can be represented as scalars (<STRONG>$scalar</STRONG>) or lists (<STRONG>@list</STRONG>). An <CODE>@List</CODE> inside these sections is simply converted into a space delimited string for
-you inside. Here is an example:
-
-<P>
-<PRE> #httpd.conf
- <Perl>
- @PerlModule = qw(Mail::Send Devel::Peek);
-
- #run the server as whoever starts it
- $User = getpwuid($>) || $>;
- $Group = getgrgid($)) || $);
-
- $ServerAdmin = $User;
-
- </Perl>
+<PRE> % lwp-request -e -d www.site.com | egrep '^Server:'
</PRE>
<P>
-Block sections such as <Location></Location> are represented in
-a %Hash, e.g.:
+To see the server's version only.
<P>
-<PRE> $Location{"/~dougm/"} = {
- AuthUserFile => '/tmp/htpasswd',
- AuthType => 'Basic',
- AuthName => 'test',
- DirectoryIndex => [qw(index.html index.htm)],
- Limit => {
- METHODS => 'GET POST',
- require => 'user dougm',
- },
- };
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A></H1></CENTER>
<P>
-If a Directive can take two *or* three arguments you may push strings and
-the lowest number of arguments will be shifted off the
-<CODE>@List</CODE> or use array reference to handle any number greater than the minimum for
-that directive:
+Yes, no problem with that. Follow the instructions above and when you
+encounter APACI_ARGS use your home directory (or some other directory which
+you have write access to as a prefix, for example,
+<CODE>/home/stas/www</CODE>) and everything will be installed there. There is a chance that some perl
+libs will be not installed on your server by root and you will have to
+install these locally too. See the <A
+HREF="http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html#7">http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html#7</A>
+for more information on local perl installations.
-<P>
-<PRE> push @Redirect, "/foo", "<A HREF="http://www.foo.com/"">http://www.foo.com/"</A>;;
-
- push @Redirect, "/imdb", "<A HREF="http://www.imdb.com/"">http://www.imdb.com/"</A>;;
-
- push @Redirect, [qw(temp "/here" "<A HREF="http://www.there.com"">http://www.there.com"</A>;)];
-</PRE>
<P>
-Other section counterparts include <STRONG>%VirtualHost</STRONG>,
-<STRONG>%Directory</STRONG> and <STRONG>%Files</STRONG>.
+You will not be able to have the server listen to a port lower then 1024 if
+you are not starting it as <CODE>root</CODE>, so choose a port number above 1024. (I use 8080 in most cases). Note that
+you will have to use a URL like <CODE>http://www.you.com:8080</CODE> in that case, but that is not a problem since generally users do not
+directly access URLs to CGI scripts, but rather are directed to them from a
+link on a web page or as the '<CODE>ACTION</CODE>' of an HTML form, so they should not know at all that the port is
+different from the default port 80.
<P>
-To pass all environment variables to the children with a single
-configuration directive, rather than listing each one via PassEnv or
-PerlPassEnv, a <STRONG><Perl></STRONG> section could read in a file and:
+If you want your Apache server to start automatically on system reboot, you
+will need to invoke the server startup script from somewhere within the
+init scripts on your host. (This is often somewhere under <CODE>/etc/rc.d</CODE>, but this path can vary depending upon the flavor of Unix you are using.)
<P>
-<PRE> push @PerlPassEnv, [$key => $val];
-</PRE>
-<P>
-or
+One more important thing to keep in mind is system resources. Mod_perl is
+memory hungry -- if you run a lot of mod_perl processes on that machine
+(and it's not your own host...), most likely the system administrator of
+the host will ask you to shutdown your mod_perl server, or to find another
+home for it. You have a few solutions:
-<P>
-<PRE> Apache->httpd_conf("PerlPassEnv $key $val");
-</PRE>
<P>
-These are somewhat simple 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 in mod_perl distribution for some examples.
+<STRONG>a</STRONG>. Reduce resource usage - see <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>
-<P>
-A tip for syntax checking outside of httpd:
-<P>
-<PRE> <Perl>
- #!perl
-
- #... code here ...
-
- __END__
- </Perl>
-</PRE>
+
<P>
-Now you may run <STRONG>perl -cx httpd.conf</STRONG>.
+<STRONG>b</STRONG>. Ask your ISP if you can put a dedicated machine into their computer room
+and be root there.
<P>
-To configure this feature build with <STRONG>perl Makefile.PL
-PERL_SECTIONS=1</STRONG>
+<STRONG>c</STRONG>. Look for another ISP with lots of resources or one that supports mod_perl
+(not likely)
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Configuring_Apache_mod_perl_wi">Configuring Apache + mod_perl with mod_macro</A></H1></CENTER>
+<CENTER><H1><A NAME="Is_it_possible_to_determine_whic">Is it possible to determine which options were given to modperl's Makefile.PL</A></H1></CENTER>
<P>
-mod_macro is an Apache module written by Fabien Coelho that lets you define
-and use macros in the Apache configuration file.
+It is possible to determine which options were given to modperl's
+<CODE>Makefile.PL</CODE> during the configuration stage, so to be used later in recreating the same
+build tree when rebuilding the server. This is relevant only if did not use
+the default config parameters and altered some of them during the
+configuration stage.
<P>
-mod_macro proved really useful when you have many virtual hosts, each
-virtual host has a number of scripts/modules, most of them with a
-moderately complex configuration setup.
+I was into this problem many times. I am going to build something by
+passing some non default parameters to the config script and then later
+when I need to rebuild the tool either to upgrade it or to make an
+identical copy at some other machine, I have found that I do not remember
+what parameters did I altered.
<P>
-First download the latest version of mod_macro from <A
-HREF="http://www.cri.ensmp.fr/~coelho/mod_macro/,">http://www.cri.ensmp.fr/~coelho/mod_macro/,</A>
-and configure your Apache server to use this module.
+The best solution for this problem is to prepare the run file with all the
+parameters that are about to be used and then run it instead of typing it
+all by hand. So later I will have the script handy to be reused.
<P>
-Here are some useful macros for mod_perl users:
+mod_perl suggests using the <CODE>makepl_args.mod_perl</CODE> file which comes with mod_perl distribution. This is the file you specify
+all the parameters you are going to use.
-<P>
-<PRE> # set up a registry script
- <Macro registry>
- SetHandler "perl-script"
- PerlHandler Apache::Registry
- Options +ExecCGI
- </Macro>
-</PRE>
-<P>
-<PRE> # example
- Alias /stuff /usr/www/scripts/stuff
- <Location /stuff>
- Use registry
- </Location>
-</PRE>
<P>
-If your registry scripts are all located in the same directory, and your
-aliasing rules consistent, you can use this macro:
+But if you have found yourself with a compiled tool and no traces of the
+specified parameters left, you can still find them out if the sources were
+not <CODE>make clean</CODE>'d. So you will find the apache specific parameters in <CODE>apache_x.x.x/config.status</CODE> and modperl's at in <CODE>mod_perl_x.xx/apaci/mod_perl.config</CODE>.
<P>
-<PRE> # set up a registry script for a specific location
- <Macro registry $location $script>
- Alias /script /usr/www/scripts/$script
- <Location $location>
- SetHandler "perl-script"
- PerlHandler Apache::Registry
- Options +ExecCGI
- </Location>
- </Macro>
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Server_Installation">Server Installation</A></H1></CENTER>
<P>
-<PRE> # example
- Use registry stuff stuff.pl
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="make_test_fails">make test fails</A></H2></CENTER>
<P>
-If you're using content handlers packaged as modules, you can use the
-following macro:
+There are two configuration parameters <CODE>PREP_HTTPD</CODE> and <CODE>DO_HTTPD</CODE>
+you can use in <CODE>perl Makefile.PL [options]</CODE>.
-<P>
-<PRE> # set up a mod_perl content handler module
- <Macro modperl $module>
- SetHandler "perl-script"
- Options +ExecCGI
- PerlHandler $module
- </Macro>
-</PRE>
-<P>
-<PRE> #examples
- <Location /perl-status>
- PerlSetVar StatusPeek On
- PerlSetVar StatusGraph On
- PerlSetVar StatusDumper On
- Use modperl Apache::Status
- </Location>
-</PRE>
<P>
-The following macro sets up a Location for use with HTML::Embperl. Here we
-define all ``.html'' files to be processed by Embperl.
+<CODE>DO_HTTPD=1</CODE> means default to 'y' for the two prompts (which source tree to configure
+against and to build the httpd in that tree).
+<CODE>PREP_HTTPD=1</CODE> just means default 'n' to the second prompt, meaning, do not build httpd
+(make) in the Apache source tree.
-<P>
-<PRE> <Macro embperl>
- SetHandler "perl-script"
- Options +ExecCGI
- PerlHandler HTML::Embperl
- PerlSetEnv EMBPERL_FILESMATCH \.html$
- </Macro>
-</PRE>
-<P>
-<PRE> # examples
- <Location /mrtg>
- Use embperl
- </Location>
-</PRE>
<P>
-Macros are also very useful for things that tend to be verbose, such as
-setting up Basic Authentication:
+In other words if you use <CODE>PREP_HTTPD=1</CODE> the httpd will be not build. It will be build only if you use <CODE>DO_HTTPD=1</CODE> option and not use
+<CODE>PREP_HTTPD=1</CODE>.
-<P>
-<PRE> # Sets up Basic Authentication
- <Macro BasicAuth $realm $group>
- Order deny,allow
- Satisfy any
- AuthType Basic
- AuthName $realm
- AuthGroupFile /usr/www/auth/groups
- AuthUserFile /usr/www/auth/users
- Require group $group
- Deny from all
- </Macro>
-</PRE>
-<P>
-<PRE> # example of use
- <Location /stats>
- Use BasicAuth WebStats Admin
- </Location>
-</PRE>
<P>
-Finally, here is a complete example that uses macros to set up simple
-virtual hosts. It uses the BasicAuth macro defined previously (yes, macros
-can be nested!).
+If you did not build the httpd, chdir to the apache source, and execute:
-<P>
-<PRE> <Macro vhost $ip $domain $docroot $admingroup>
- <VirtualHost $ip>
- ServerAdmin webmaster@$domain
- DocumentRoot /usr/www/htdocs/$docroot
- ServerName www.$domain
- <Location /stats>
- Use BasicAuth Stats-$domain $admingroup
- </Location>
- </VirtualHost>
- </Macro>
-</PRE>
<P>
-<PRE> # define some virtual hosts
- Use vhost 10.1.1.1 example.com example example-admin
- Use vhost 10.1.1.2 example.net examplenet examplenet-admin
+<PRE> make
</PRE>
<P>
-mod_macro also useful in a non vhost setting. Some sites for example have
-lots of scripts where people use to view various statistics, email settings
-and etc. It is much easier to read things like:
+Then return to the mod_perl source and run:
<P>
-<PRE> use /forwards email/showforwards
- use /webstats web/showstats
+<PRE> make test
+ make install
</PRE>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="General_pitfalls">General pitfalls</A></H1></CENTER>
-<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="My_cgi_perl_code_is_being_return">My cgi/perl code is being returned as a plain text instead of being executed by the webserver?</A></H2></CENTER>
-<P>
-Check your configuration files and make sure that the ``ExecCGI'' is turned
-on in your configurations.
-
-<P>
-<PRE> <Location /perl>
- SetHandler perl-script
- PerlHandler Apache::Registry
- Options ExecCGI
- allow from all
- PerlSendHeader On
- </Location>
-</PRE>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="My_script_works_under_cgi_bin_b">My script works under cgi-bin, but when called via mod_perl I see A 'Save-As' prompt</A></H2></CENTER>
-<P>
-Did you put <STRONG>PerlSendHeader On</STRONG> in the configuration part of the <Location foo></Location>?
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Is_there_a_way_to_provide_a_diff">Is there a way to provide a different startup.pl file for each individual virtual host</A></H2></CENTER>
-<P>
-No. Any virtual host will be able to see the routines from a startup.pl
-loaded for any other virtual host.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Is_there_a_way_to_modify_INC_on">Is there a way to modify @INC on a per-virtual-host basis.</A></H2></CENTER>
-<P>
-You can use 'PerlSetEnv PERL5LIB ...' or a PerlFixupHandler w/ the lib
-pragma.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Sometimes_the_script_from_one_vi">Sometimes the script from one virtual host calls a script with
-the same path from the second virtual host</A></H2></CENTER>
-<P>
-This has been a bug before, last fixed in 1.15_01, i.e. if you are running
-1.15, that could be the problem. You should set this variable in a startup
-file (PerlRequire):
-
-<P>
-<PRE> $Apache::Registry::NameWithVirtualHost = 1;
-</PRE>
-<P>
-But, as we know sometimes bug turns into a feature. If there is the same
-script running for more than one Virtual host on the same machine, this can
-be a waste, right? Set it to 0 in a startup script if you want to turn it
-off and have this bug as a feature. (Only makes sense if you are sure that
-there will be no <STRONG>other</STRONG> scripts named by the same path/name)
-
-<P>
-<PRE> $Apache::Registry::NameWithVirtualHost = 0;
-</PRE>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="the_server_no_longer_retrieves_t">the server no longer retrieves the DirectoryIndex files for a directory</A></H2></CENTER>
-<P>
-The problem was reported by users who declared mod_perl configuration
-inside a <Directory> section for all files matching to *.pl. The
-problem has gone away after placing the usage of mod_perl in a
-<File>- section.
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -2982,7 +3203,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="scenario.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="config.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -2994,8 +3216,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
@@ -3022,11 +3244,14 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: Controlling and Monitoring the Server</TITLE>
+ <TITLE>mod_perl guide: Server Configuration</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -3037,29 +3262,53 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Controlling and Monitoring the Server</H1>
+Server Configuration</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="install.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="frequent.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
- <LI><A HREF="#Restarting_techniques">Restarting techniques</A>
- <LI><A HREF="#Implications_of_sending_TERM_HU">Implications of sending TERM, HUP, and USR1 to the server</A>
- <LI><A HREF="#Using_apachectl_to_control_the_s">Using apachectl to control the server</A>
- <LI><A HREF="#Monitoring_the_Server_A_watchdo">Monitoring the Server. A watchdog.</A>
- <LI><A HREF="#Running_in_Single_Mode">Running in Single Mode</A>
- <LI><A HREF="#Starting_a_personal_server_for_e">Starting a personal server for each developer</A>
- <LI><A HREF="#Wrapper_to_emulate_the_server_en">Wrapper to emulate the server environment</A>
- <LI><A HREF="#Log_Rotation">Log Rotation</A>
- <LI><A HREF="#Preventing_from_modperl_process_">Preventing from modperl process to eat up all the disk's space, when it goes wild.</A>
+ <LI><A HREF="#mod_perl_Specific_Configuration">mod_perl Specific Configuration</A>
+ <UL>
+
+ <LI><A HREF="#Alias_Configurations">Alias Configurations</A>
+ <LI><A HREF="#Location_Configuration">Location Configuration</A>
+ <LI><A HREF="#PerlFreshRestart">PerlFreshRestart</A>
+ <LI><A HREF="#_perl_status_location">/perl-status location</A>
+ <LI><A HREF="#perl_startup_file">perl-startup file</A>
+ <UL>
+
+ <LI><A HREF="#Sample_perl_startup_file">Sample perl-startup file</A>
+ <LI><A HREF="#What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A>
+ <LI><A HREF="#Is_it_possible_to_preopen_a_DB_c">Is it possible to preopen a DB connection at the server startup?</A>
+ </UL>
+
+ </UL>
+
+ <LI><A HREF="#Perl_behavior_controls">Perl behavior controls</A>
+ <LI><A HREF="#Tuning_MinSpareServers_MaxSpareS">Tuning MinSpareServers MaxSpareServers StartServers MaxClients</A>
+ <LI><A HREF="#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>
+ <LI><A HREF="#Perl_Sections">Perl Sections</A>
+ <LI><A HREF="#Configuring_Apache_mod_perl_wi">Configuring Apache + mod_perl with mod_macro</A>
+ <LI><A HREF="#General_pitfalls">General pitfalls</A>
+ <UL>
+
+ <LI><A HREF="#My_cgi_perl_code_is_being_return">My cgi/perl code is being returned as a plain text instead of being executed by the webserver?</A>
+ <LI><A HREF="#My_script_works_under_cgi_bin_b">My script works under cgi-bin, but when called via mod_perl I see A 'Save-As' prompt</A>
+ <LI><A HREF="#Is_there_a_way_to_provide_a_diff">Is there a way to provide a different startup.pl file for each individual virtual host</A>
+ <LI><A HREF="#Is_there_a_way_to_modify_INC_on">Is there a way to modify @INC on a per-virtual-host basis. </A>
+ <LI><A HREF="#Sometimes_the_script_from_one_vi">Sometimes the script from one virtual host calls a script with</A>
+ <LI><A HREF="#the_server_no_longer_retrieves_t">the server no longer retrieves the DirectoryIndex files for a directory</A>
+ </UL>
+
</UL>
<!-- INDEX END -->
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -3068,833 +3317,722 @@
and <a
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<P>
-<CENTER><H1><A NAME="Restarting_techniques">Restarting techniques</A></H1></CENTER>
-<P>
-All of these techniques require that you know the server PID (Process ID).
-The easiest way to find the PID is to look it up in the httpd.pid file.
-With my configuration it exists as
-<CODE>/usr/apps/var/httpd_perl/run/httpd.pid</CODE>. It's easy to discover where to look at, by checking out the httpd.conf
-file. Open the file and locate the entry <CODE>PidFile</CODE>:
-<P>
-<PRE> PidFile /usr/apps/var/httpd_perl/run/httpd.pid
-</PRE>
-<P>
-Another way is to use the <CODE>ps</CODE> and <CODE>grep</CODE> utilities:
+ <HR>
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<PRE> % ps auxc | grep httpd_perl
-</PRE>
+<CENTER><H1><A NAME="mod_perl_Specific_Configuration">mod_perl Specific Configuration</A></H1></CENTER>
<P>
-or maybe:
+The next step after building and installing your new mod_perl-enabled
+Apache server, is to configure the server's configuration files. To learn
+how to modify Apache's configuration files, please refer to the
+documentation included with the Apache distribution. or just view the files
+in conf directory and follow the instructions in these files - the embedded
+comments within the file do a good job of explaining the options.
-<P>
-<PRE> % ps -ef | grep httpd_perl
-</PRE>
<P>
-This will produce a list of all httpd_perl (the parent and the children)
-processes. You are looking for the parent process. If you run your server
-as root - you will easily locate it, since it belongs to root. If you run
-the server as user (when you <A HREF="././scenario.html#Is_it_possible_to_install_mod_pe">don't have a root access</A>, most likely all the processes will belong to that user (unless defined
-differently in the httpd.conf), but it's still easy to know 'who is the
-parent' -- the one of the smallest size...
+Before you start the mod_perl configuration, configure Apache, and see that
+it works. When done, return here to continue...
<P>
-You will notice many httpd_perl executables running on your system, but you
-should not send signals to any of them except the parent, whose pid is in
-the <CODE>PidFile</CODE>. That is to say you shouldn't ever need to send signals to any process
-except the parent. There are three signals that you can send the parent:
-TERM, HUP, and USR1.
+[ Note that prior to version 1.3.4, the default Apache install used three
+configuration files -- <STRONG>httpd.conf</STRONG>, <STRONG>srm.conf</STRONG>, and
+<STRONG>access.conf</STRONG>. The 1.3.4 version began distributing the configuration directives in a
+single file -- <STRONG>httpd.conf</STRONG>. The remainder of this chapter refers to the location of the configuration
+directives using their historical location. ]
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Implications_of_sending_TERM_HU">Implications of sending TERM, HUP, and USR1 to the server</A></H1></CENTER>
+<CENTER><H2><A NAME="Alias_Configurations">Alias Configurations</A></H2></CENTER>
<P>
-We will concentrate here on the implications of sending these signals to a
-mod_perl-enabled server. For documentation on the implications of sending
-these signals to a plain Apache server see <A
-HREF="http://www.apache.org/docs/stopping.html">http://www.apache.org/docs/stopping.html</A>
-.
+First, you need to specify the location where all mod_perl scripts will be
+located.
-<DL>
-<P><DT><STRONG><A NAME="item_TERM">TERM Signal: stop now</A></STRONG><DD>
<P>
-Sending the TERM signal to the parent causes it to immediately attempt to
-kill off all of its children. This process may take several seconds to
-complete, following which the parent itself exits. Any requests in progress
-are terminated, and no further requests are served.
+Add the following configuration directives:
<P>
-That's the moment that the accumulated END{} blocks will be executed! Note
-that if you use <STRONG>Apache::Registry</STRONG> or <STRONG>Apache::PerlRun</STRONG>, then END {} blocks are being executed upon each request (at the end).
-
-<P><DT><STRONG><A NAME="item_HUP">HUP Signal: restart now</A></STRONG><DD>
+<PRE> # for plain cgi-bin:
+ ScriptAlias /cgi-bin/ /usr/local/myproject/cgi/
+
+ # for Apache::Registry mode
+ Alias /perl/ /usr/local/myproject/cgi/
+
+ # Apache::PerlRun mode
+ Alias /cgi-perl/ /usr/local/myproject/cgi/
+</PRE>
<P>
-Sending the HUP signal to the parent causes it to kill off its children
-like in TERM (Any requests in progress are terminated) but the parent
-doesn't exit. It re-reads its configuration files, and re-opens any log
-files. Then it spawns a new set of children and continues serving hits.
+<CODE>Alias</CODE> provides a mapping of URL to file system object under
+<CODE>mod_perl</CODE>. <CODE>ScriptAlias</CODE> is being used for <CODE>mod_cgi</CODE>.
<P>
-The server will reread its configuration files, flush all the compiled and
-preloaded modules, and rerun any startup files. It's equivalent to
-stopping, then restarting a server.
+Alias defines the start of the URL path to the script you are referencing.
+For example, using the above configuration, fetching
+<STRONG>http://www.you.com/perl/test.pl</STRONG>, will cause the server to look for the file <STRONG>test.pl</STRONG> at <STRONG>/usr/local/myproject/cgi</STRONG>, and execute it as an <STRONG>Apache::Registry</STRONG> script if we define Apache::Register to be the handler of <CODE>/perl</CODE> location (see below). The URL
+<STRONG>http://www.you.com/perl/test.pl</STRONG> will be mapped to
+<STRONG>/usr/local/myproject/cgi/test.pl</STRONG>. This means you can have all your CGIs located at the same place at file
+system, and call the script in any of three modes simply by changing the
+directory name component of the URL (cgi-bin|perl|cgi-perl) - is not this
+cool? (That is the configuration you see above - all three Aliases point to
+the same directory within your file system, but of course they can be
+different). If your script does not seem to be working while running under
+mod_perl, you can easily call the script in straight mod_cgi mode without
+making any script changes (in most cases), but rather by changing the URL
+you invoke it by.
<P>
-Note: If your configuration file has errors in it when you issue a restart
-then your parent will not restart but exit with an error. See below for a
-method of avoiding this.
+FYI: for modperl <CODE>ScriptAlias</CODE> is the same thing as an <CODE>Alias</CODE>
+directive + <CODE>sethandler cgi-handler</CODE>. The latter will be overwritten if you enable <CODE>Apache::Registry</CODE>. In other words, <CODE>ScriptAlias</CODE> does not work for mod_perl, it only appears to work when the additional
+configuration is in there. If the <CODE>Apache::Registry</CODE> configuration came before the <CODE>ScriptAlias</CODE>, scripts would be run under mod_cgi. While handy, <CODE>ScriptAlias</CODE> is a known kludge, always better to use
+<CODE>Alias</CODE> and <CODE>SetHandler</CODE>.
-<P><DT><STRONG><A NAME="item_USR1">USR1 Signal: graceful restart</A></STRONG><DD>
<P>
-The USR1 signal causes the parent process to advise the children to exit
-after their current request (or to exit immediately if they're not serving
-anything). The parent re-reads its configuration files and re-opens its log
-files. As each child dies off the parent replaces it with a child from the
-new generation of the configuration, which begins serving new requests
-immediately.
+Of course you can choose any other alias (you will use it later in
+http.conf), you can choose to use all three modes or only one of these (It
+is undesirable to run plain cgi-bin scripts from a mod_perl-enabled server
+- the price is too high, it is better to run these on plain Apache server.
+(META: add link to strategies)
<P>
-The only difference between USR1 and HUP is that USR1 allows children to
-complete any in-progress request prior to killing them off.
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Location_Configuration">Location Configuration</A></H2></CENTER>
+<P>
+Now we will work with the <CODE>httpd.conf</CODE> file. I add all the mod_perl stuff at the end of the file, after the native
+Apache configurations.
<P>
-By default, if a server is restarted (ala <CODE>kill -USR1 `cat
-logs/httpd.pid`</CODE> or with HUP signal), Perl scripts and modules are not reloaded. To reload <STRONG>PerlRequire</STRONG>'s, <STRONG>PerlModule</STRONG>'s, other <CODE>use()'d</CODE> modules and flush the Apache::Registry
-cache, enable with this command:
+First we add:
<P>
-<PRE> PerlFreshRestart On (in httpd.conf)
+<PRE> <Location /perl>
+ #AllowOverride None
+ SetHandler perl-script
+ PerlHandler Apache::Registry
+ Options ExecCGI
+ allow from all
+ PerlSendHeader On
+ </Location>
</PRE>
<P>
-Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
+This configuration causes all scripts that are called with a <STRONG>/perl</STRONG>
+path prefix to be executed under the <STRONG>Apache::Registry</STRONG> module and as a CGI (so the <STRONG>ExecCGI</STRONG>, if you omit this option the script will be printed to the caller's
+browser as a plain text or will possibly will trigger a 'Save-As' window).
-</DL>
<P>
-It's worth mentioning that restart or termination can sometimes take quite
-a lot of time. Check out the PERL_DESTRUCT_LEVEL=-1 option during the
-mod_perl ./Configure stage, which speeds this up and leads to more robust
-operation in the face of problems, like running out of memory. It is only
-usable if no significant cleanup has to be done by perl END{} blocks and
-DESTROY methods when the child terminates, of course. What constitutes
-significant cleanup? Any change of state outside of the current process
-that would not be handled by the operating system itself. So committing
-database transactions is significant but closing an ordinary file isn't.
+<STRONG>PerlSendHeader On</STRONG> tells the server to send an HTTP header to the browser on every script
+invocation. You will want to turn this off for nph (non-parsed-headers)
+scripts.
<P>
-Some folks prefer to specify signals using numerical values, rather than
-symbolics. If you are looking for these, check out your
-<CODE>kill(3)</CODE> man page. My page points to
-<CODE>/usr/include/sys/signal.h</CODE>, the relevant entries are:
+Remember the <STRONG>Alias</STRONG> from the section above? We must use the same Alias here, if you use
+Location that does not have the same Alias defined in srm.conf, the server
+will fail to locate the script in the file system. (We are talking about
+script execution here -- there are cases where Location is something that
+is being executed by the server itself, without having the corresponding
+file, like <A HREF="#_perl_status_location">perl-status location</A>.)
-<P>
-<PRE> #define SIGHUP 1 /* hangup, generated when terminal disconnects */
- #define SIGTERM 15 /* software termination signal */
- #define SIGUSR1 30 /* user defined signal 1 */
-</PRE>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Using_apachectl_to_control_the_s">Using apachectl to control the server</A></H1></CENTER>
+Note that sometimes you will have to add : PerlModule Apache::Registry
+
<P>
-Apache's distribution provides a nice script to control the server. It's
-called <STRONG>apachectl</STRONG> and it's installed into the same location with httpd. In our scenario -
-it's /usr/apps/sbin/httpd_perl/apachectl
+before you specify the location that uses Apache::Registry as a
+PerlHandler. Basically you can start running the scripts in the
+Apache::Registry mode...
<P>
-Start httpd
+You have to do nothing about /cgi-bin (mod_cgi), since it has nothing to do
+with mod_perl
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl start
+Here is a similar location configuration for Apache::PerlRun. (More about
+<A HREF="././porting.html#Apache_PerlRun_a_closer_look">Apache::PerlRun</A>)
+
+<P>
+<PRE> <Location /cgi-perl>
+ #AllowOverride None
+ SetHandler perl-script
+ PerlHandler Apache::PerlRun
+ Options ExecCGI
+ allow from all
+ PerlSendHeader On
+ </Location>
</PRE>
<P>
-Stop httpd
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="PerlFreshRestart">PerlFreshRestart</A></H2></CENTER>
+<P>
+To reload <STRONG>PerlRequire</STRONG>, <STRONG>PerlModule</STRONG>, other <CODE>use()'d</CODE> modules and flush the Apache::Registry cache
+on server restart, add:
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl stop
+<PRE> PerlFreshRestart On
</PRE>
<P>
-Restart httpd if running by sending a SIGHUP or start if not running
+Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl restart
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="_perl_status_location">/perl-status location</A></H2></CENTER>
+<P>
+Adding a directive to enable a <STRONG>/perl-status</STRONG> location allows you to see many things about your server. See
+<A HREF="././status.html#Configuration">perl-status</A>
+
+
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="perl_startup_file">perl-startup file</A></H2></CENTER>
+<P>
+Since many times you have to add many perl directives to the configuration
+file, it can be a good idea to put all of these into one file, so the
+configuration file will be cleaner, also you can call
+<STRONG>perl -c perl-startup</STRONG> to test the file's syntax. What does this take? Add this line to
+httpd.conf:
+
+<P>
+<PRE> # startup.perl loads all functions that we want to use within
+ # mod_perl
+ Perlrequire /path/to/startup.pl
</PRE>
<P>
-Do a graceful restart by sending a SIGUSR1 or start if not running
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H3><A NAME="Sample_perl_startup_file">Sample perl-startup file</A></H3></CENTER>
+<P>
+An example of perl-startup file:
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl graceful
+<PRE> use strict;
+
+ #modify @INC if needed
+ use lib qw(/some/other/dir /some/bar/dir);
+
+ # make sure we are in a sane environment.
+ $ENV{GATEWAY_INTERFACE} =~ /^CGI-Perl/
+ or die "GATEWAY_INTERFACE not Perl!";
+
+ # for things in the "/perl" URL
+ use Apache::Registry;
+
+ #load perl modules of your choice here
+ #this code is interpreted *once* when the server starts
+ use LWP::UserAgent ();
+ use DBI ();
+
+ # tell me more about warnings
+ use Carp ();
+ $SIG{__WARN__} = \&Carp::cluck;
+
+ # Load CGI.pm and call its compile() method to precompile
+ # (but not to import) its autoloaded methods.
+ use CGI ();
+ CGI->compile(':all');
</PRE>
<P>
-Do a configuration syntax test:
+Note that starting with CGI::VERSION 2.46, the recommended method to
+precompile the code in CGI.pm is:
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl configtest
+<PRE> use CGI qw(-compile :all);
</PRE>
<P>
-See the next section for the implication of the above calls.
+But the old method is still available for backward compatibility.
<P>
-Replace 'httpd_perl' with 'httpd_docs' in the above calls to control the
-httpd_docs server.
+See also <A HREF="././status.html#Configuration">Apache::Status</A>
+
+
<P>
-There are other options for <STRONG>apachectl</STRONG>, use 'help' option to see them all.
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H3><A NAME="What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A></H3></CENTER>
+<P>
+Modules that are being loaded at the server startup will be shared among
+server children, so only one copy of each module will be loaded, thus
+saving a lot of RAM for you.
<P>
-It's important to understand that this script is based on the PID file
-which is PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid. If you delete the
-file by hand - <STRONG>apachectl</STRONG> will fail to run.
+See <A HREF="././performance.html#Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A>
+
+
<P>
-Also, note that <STRONG>apachectl</STRONG> is suitable to use from within your Unix system's startup files so that
-your web server is automatically restarted upon system reboot. Either copy
-the <STRONG>apachectl</STRONG> file to the appropriate location (<CODE>/etc/rc.d/rc3.d/S99apache</CODE> works on my RedHat Linux system) or create a symlink with that name
-pointing to the the canonical location. (If you do this, make certain that
-the script is writable only by root -- the startup scripts have root
-privileges during init processing, and you don't want to be opening any
-security holes.)
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H3><A NAME="Is_it_possible_to_preopen_a_DB_c">Is it possible to preopen a DB connection at the server startup?</A></H3></CENTER>
+<P>
+Yes! See <A HREF="././performance.html#Persistent_DB_Connections">Persistent DB Connections</A>
+
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Monitoring_the_Server_A_watchdo">Monitoring the Server. A watchdog.</A></H1></CENTER>
+<CENTER><H1><A NAME="Perl_behavior_controls">Perl behavior controls</A></H1></CENTER>
<P>
-With mod_perl many things can happen to your server. The worst one is the
-possibility that the server will die when you will be not around. As with
-any other critical service you need to run some kind of watchdog.
+For <STRONG>PerlWarn</STRONG> and <STRONG>PerlTaintCheck</STRONG> see <A HREF="././porting.html#Switches_w_T">Switches -w, -T</A>
+
+
<P>
-One simple solution is to use a slightly modified <STRONG>apachectl</STRONG> script which I called apache.watchdog and to put it into the crontab to be
-called every 30 minutes or even every minute - if it's so critical to make
-sure the server will be up all the time.
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Tuning_MinSpareServers_MaxSpareS">Tuning MinSpareServers MaxSpareServers StartServers MaxClients
+MaxRequestsPerChild</A></H1></CENTER>
+<P>
+See <A HREF="././performance.html#Tuning_the_Apache_s_configuratio">Tuning the Apache's configuration variables for the best performance</A>
+
+
<P>
-Crontab entry:
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Publishing_port_numbers_differen">Publishing port numbers different from 80</A></H1></CENTER>
+<P>
+It is advised not to publish the 8080 (or alike) port number in URLs, but
+rather using a proxying rewrite rule in the thin (httpd_docs) server:
<P>
-<PRE> 0,30 * * * * /path/to/the/apache.watchdog >/dev/null 2>&1
+<PRE> RewriteRule .*/perl/(.*) <A HREF="http://my.url:8080/perl/">http://my.url:8080/perl/</A>$1 [P]
</PRE>
<P>
-The script:
+One problem with publishing 8080 port numbers is that I was told that IE
+4.x has a bug when re-posting data to a non-port-80 url. It drops the port
+designator, and uses port 80 anyway.
<P>
-<PRE> #!/bin/sh
-
- # this script is a watchdog to see whether the server is online
- # It tries to restart the server if it's
- # down and sends an email alert to admin
-
- # admin's email
- EMAIL=webmaster@somewhere.far
- #EMAIL=root@localhost
-
- # the path to your PID file
- PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid
-
- # the path to your httpd binary, including options if necessary
- HTTPD=/usr/apps/sbin/httpd_perl/httpd_perl
-
- # check for pidfile
- if [ -f $PIDFILE ] ; then
- PID=`cat $PIDFILE`
-
- if kill -0 $PID; then
- STATUS="httpd (pid $PID) running"
- RUNNING=1
- else
- STATUS="httpd (pid $PID?) not running"
- RUNNING=0
- fi
- else
- STATUS="httpd (no pid file) not running"
- RUNNING=0
- fi
-
- if [ $RUNNING -eq 0 ]; then
- echo "$0 $ARG: httpd not running, trying to start"
- if $HTTPD ; then
- echo "$0 $ARG: httpd started"
- mail $EMAIL -s "$0 $ARG: httpd started" </dev/null >& /dev/null
- else
- echo "$0 $ARG: httpd could not be started"
- mail $EMAIL -s "$0 $ARG: httpd could not be started" </dev/null >& /dev/null
- fi
- fi
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Perl_Sections">Perl Sections</A></H1></CENTER>
+<P>
+With <STRONG><Perl></Perl></STRONG> sections, it is possible to configure your server entirely in Perl.
+
+<P>
+<STRONG><Perl></STRONG> sections can contain *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 configurations
+directives can be represented as scalars (<STRONG>$scalar</STRONG>) or lists (<STRONG>@list</STRONG>). An <CODE>@List</CODE> inside these sections is simply converted into a space delimited string for
+you inside. Here is an example:
+
+<P>
+<PRE> #httpd.conf
+ <Perl>
+ @PerlModule = qw(Mail::Send Devel::Peek);
+
+ #run the server as whoever starts it
+ $User = getpwuid($>) || $>;
+ $Group = getgrgid($)) || $);
+
+ $ServerAdmin = $User;
+
+ </Perl>
</PRE>
<P>
-Another approach, probably even more practical, is to use the Cool LWP perl
-package , to test the server by trying to fetch some document (script)
-served by the server. Why is it more practical? While server can be up as a
-process, it can be stuck and not working (SYN_RECV state - anyone??? Am I
-getting a SYNC flood attack), So failing to get the document will trigger
-restart, and ``probably'' the problem will go away. (Just replace
-<CODE>start</CODE> with <CODE>restart</CODE> in the <CODE>$restart_command</CODE> below.
+Block sections such as <Location></Location> are represented in
+a %Hash, e.g.:
+<P>
+<PRE> $Location{"/~dougm/"} = {
+ AuthUserFile => '/tmp/htpasswd',
+ AuthType => 'Basic',
+ AuthName => 'test',
+ DirectoryIndex => [qw(index.html index.htm)],
+ Limit => {
+ METHODS => 'GET POST',
+ require => 'user dougm',
+ },
+ };
+</PRE>
<P>
-Again we put this script into a crontab to call it every 30 minutes.
+If a Directive can take two *or* three arguments you may push strings and
+the lowest number of arguments will be shifted off the <CODE>@List</CODE> or use array reference to handle any number greater than the minimum for
+that directive:
<P>
-<PRE> #!/usr/local/bin/perl -w
+<PRE> push @Redirect, "/foo", "<A HREF="http://www.foo.com/"">http://www.foo.com/"</A>;;
- use strict;
- use diagnostics;
- use URI::URL;
- use LWP::MediaTypes qw(media_suffix);
+ push @Redirect, "/imdb", "<A HREF="http://www.imdb.com/"">http://www.imdb.com/"</A>;;
- my $VERSION = '0.01';
- use vars qw($ua $proxy);
+ push @Redirect, [qw(temp "/here" "<A HREF="http://www.there.com"">http://www.there.com"</A>;)];
+</PRE>
+<P>
+Other section counterparts include <STRONG>%VirtualHost</STRONG>, <STRONG>%Directory</STRONG> and
+<STRONG>%Files</STRONG>.
+
+<P>
+To pass all environment variables to the children with a single
+configuration directive, rather than listing each one via PassEnv or
+PerlPassEnv, a <STRONG><Perl></STRONG> section could read in a file and:
+
+<P>
+<PRE> push @PerlPassEnv, [$key => $val];
+</PRE>
+<P>
+or
+
+<P>
+<PRE> Apache->httpd_conf("PerlPassEnv $key $val");
+</PRE>
+<P>
+These are somewhat simple examples, but they should give you the basic
+idea. You can mix in any Perl code your heart desires. See
+<CODE>eg/httpd.conf.pl</CODE> and <CODE>eg/perl_sections.txt</CODE> in mod_perl distribution for some examples.
+
+<P>
+A tip for syntax checking outside of httpd:
+
+<P>
+<PRE> <Perl>
+ # !perl
- require LWP::UserAgent;
- use HTTP::Status;
+ #... code here ...
- ###### Config ########
- my $test_script_url = '<A HREF="http://www.stas.com:81/perl/test.pl">http://www.stas.com:81/perl/test.pl</A>';
- my $monitor_email = 'root@localhost';
- my $restart_command = '/usr/apps/sbin/httpd_perl/apachectl start';
- my $mail_program = '/usr/lib/sendmail -t -n';
- ######################
-
- $ua = new LWP::UserAgent;
- $ua->agent("$0/Stas " . $ua->agent);
- # Uncomment the proxy if you don't use it!
- # $proxy="<A HREF="http://www-proxy.com"">http://www-proxy.com"</A>;;
- $ua->proxy('http', $proxy) if $proxy;
-
- # If returns '1' it's we are alive
- exit 1 if checkurl($test_script_url);
-
- # We have got the problem - the server seems to be down. Try to
- # restart it.
- my $status = system $restart_command;
- # print "Status $status\n";
-
- my $message = ($status == 0)
- ? "Server was down and successfully restarted!"
- : "Server is down. Can't restart.";
-
- my $subject = ($status == 0)
- ? "Attention! Webserver restarted"
- : "Attention! Webserver is down. can't restart";
-
- # email the monitoring person
- my $to = $monitor_email;
- my $from = $monitor_email;
- send_mail($from,$to,$subject,$message);
-
- # input: URL to check
- # output: 1 if success, o for fail
- #######################
- sub checkurl{
- my ($url) = @_;
-
- # Fetch document
- my $res = $ua->request(HTTP::Request->new(GET => $url));
-
- # Check the result status
- return 1 if is_success($res->code);
-
- # failed
- return 0;
- } # end of sub checkurl
-
- # sends email about the problem
- #######################
- sub send_mail{
- my($from,$to,$subject,$messagebody) = @_;
-
- open MAIL, "|$mail_program"
- or die "Can't open a pipe to a $mail_program :$!\n";
-
- print MAIL <<__END_OF_MAIL__;
- To: $to
- From: $from
- Subject: $subject
-
- $messagebody
-
- __END_OF_MAIL__
-
- close MAIL;
- }
-
+ __END__
+ </Perl>
</PRE>
<P>
-<PRE> <META>
- Is it possible to make the server do something when it dies? e.g
- restart itself :) NO, really when it dies , (killed in improper way?)
- is it possible to trigger some action?
-</PRE>
+Now you may run <STRONG>perl -cx httpd.conf</STRONG>.
+
<P>
-<PRE> Ideas?
- </META>
-</PRE>
+To configure this feature build with <STRONG>perl Makefile.PL
+PERL_SECTIONS=1</STRONG>
+
+
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Running_in_Single_Mode">Running in Single Mode</A></H1></CENTER>
+<CENTER><H1><A NAME="Configuring_Apache_mod_perl_wi">Configuring Apache + mod_perl with mod_macro</A></H1></CENTER>
<P>
-Often while developing new code, you will want to run the server in single
-process mode. See <A HREF="././porting.html#Sometimes_it_works_Sometimes_Not">Sometimes it works Sometimes Not</A> and <A HREF="././porting.html#Names_collisions_with_Modules_an">Names collisions with Modules and libs</A>
-Running in single process mode inhibits the server from ``daemonizing'',
-allowing you to run it more easily under debugger control.
+mod_macro is an Apache module written by Fabien Coelho that lets you define
+and use macros in the Apache configuration file.
-<P>
-<PRE> % /usr/apps/sbin/httpd_perl/httpd_perl -X
-</PRE>
<P>
-When you execute the above the server will run in the fg (foreground) of
-the shell you have called it from. So to kill you just kill it with Ctrl-C.
+mod_macro proved really useful when you have many virtual hosts, each
+virtual host has a number of scripts/modules, most of them with a
+moderately complex configuration setup.
<P>
-Note that in -X mode the server will run very slowly while fetching images.
-If you use Netscape while your server is running in single-process mode,
-HTTP's ``KeepAlive'' feature gets in the way. Netscape tries to open
-multiple connections and keep them open. Because there is only one server
-process listening, each connection has to time-out before the next
-succeeds. Turn off KeepAlive in httpd.conf to avoid this effect while
-developing or you can press <STRONG>STOP</STRONG> after a few seconds (assuming you use the image size params, so the
-Netscape will be able to render the rest of the page).
+First download the latest version of mod_macro from <A
+HREF="http://www.cri.ensmp.fr/~coelho/mod_macro/">http://www.cri.ensmp.fr/~coelho/mod_macro/</A>
+, and configure your Apache server to use this module.
<P>
-In addition you should know that when running with -X you will not see any
-control messages that the parent server normally writes to the error_log.
-(Like ``server started, server stopped and etc''.) Since <CODE>httpd -X</CODE> causes the server to handle all requests itself, without forking any
-children, there is no controlling parent to write status messages.
+Here are some useful macros for mod_perl users:
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Starting_a_personal_server_for_e">Starting a personal server for each developer</A></H1></CENTER>
<P>
-If you are the only developer working on the specific server:port - you
-have no problems, since you have a complete control over the server.
-However, many times you have a group of developers who need to concurrently
-develop their own mod_perl scripts. This means that each one will want to
-have control over the server - to kill it, to run it in single server mode,
-to restart it again, etc., as well to have control over the location of the
-log files and other configuration settings like <STRONG>MaxClients</STRONG>, etc. You can work around this problem by preparing a few httpd.conf file
-and forcing each developer to use:
-
+<PRE> # set up a registry script
+ <Macro registry>
+ SetHandler "perl-script"
+ PerlHandler Apache::Registry
+ Options +ExecCGI
+ </Macro>
+</PRE>
<P>
-<PRE> httpd_perl -f /path/to/httpd.conf
+<PRE> # example
+ Alias /stuff /usr/www/scripts/stuff
+ <Location /stuff>
+ Use registry
+ </Location>
</PRE>
<P>
-I've approached it in other way. I have used the -Dparameter startup option
-of the server. I call my version of the server
+If your registry scripts are all located in the same directory, and your
+aliasing rules consistent, you can use this macro:
<P>
-<PRE> % http_perl -Dsbekman
+<PRE> # set up a registry script for a specific location
+ <Macro registry $location $script>
+ Alias /script /usr/www/scripts/$script
+ <Location $location>
+ SetHandler "perl-script"
+ PerlHandler Apache::Registry
+ Options +ExecCGI
+ </Location>
+ </Macro>
</PRE>
-<P>
-At the end of the httpd.conf I wrote:
-
<P>
-<PRE> # Personal development Server for sbekman
- # sbekman use the server running on port 8000
- <IfDefine sbekman>
- Port 8000
- PidFile /usr/apps/var/httpd_perl/run/httpd.pid.sbekman
- ErrorLog /usr/apps/var/httpd_perl/logs/error_log.sbekman
- Timeout 300
- KeepAlive On
- MinSpareServers 2
- MaxSpareServers 2
- StartServers 1
- MaxClients 3
- MaxRequestsPerChild 15
- </IfDefine>
-
- # Personal development Server for userfoo
- # userfoo use the server running on port 8001
- <IfDefine userfoo>
- Port 8001
- PidFile /usr/apps/var/httpd_perl/run/httpd.pid.userfoo
- ErrorLog /usr/apps/var/httpd_perl/logs/error_log.userfoo
- Timeout 300
- KeepAlive Off
- MinSpareServers 1
- MaxSpareServers 2
- StartServers 1
- MaxClients 5
- MaxRequestsPerChild 0
- </IfDefine>
+<PRE> # example
+ Use registry stuff stuff.pl
</PRE>
<P>
-What we have achieved with this technique: Full control over start/stop,
-number of children, separate error log file, and port selection. This saves
-me from getting called every few minutes - ``Stas, I'm going to restart the
-server''.
+If you're using content handlers packaged as modules, you can use the
+following macro:
<P>
-To make things even easier. (In the above technique, you have to discover
-the PID of your parent httpd_perl process - written in
-/usr/apps/var/httpd_perl/run/httpd.pid.userfoo) . We change the
-<STRONG>apachectl</STRONG> script to do the work for us. We make a copy for each developer called <STRONG>apachectl.username</STRONG> and we change 2 lines in script:
-
+<PRE> # set up a mod_perl content handler module
+ <Macro modperl $module>
+ SetHandler "perl-script"
+ Options +ExecCGI
+ PerlHandler $module
+ </Macro>
+</PRE>
<P>
-<PRE> PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid.sbekman
- HTTPD='/usr/apps/sbin/httpd_perl/httpd_perl -Dsbekman'
+<PRE> #examples
+ <Location /perl-status>
+ PerlSetVar StatusPeek On
+ PerlSetVar StatusGraph On
+ PerlSetVar StatusDumper On
+ Use modperl Apache::Status
+ </Location>
</PRE>
<P>
-Of course you think you can use only one control file and know who is
-calling by using uid, but since you have to be root to start the server -
-it's not so simple.
+The following macro sets up a Location for use with HTML::Embperl. Here we
+define all ``.html'' files to be processed by Embperl.
<P>
-The last thing was to let developers an option to run in single process
-mode by:
-
+<PRE> <Macro embperl>
+ SetHandler "perl-script"
+ Options +ExecCGI
+ PerlHandler HTML::Embperl
+ PerlSetEnv EMBPERL_FILESMATCH \.html$
+ </Macro>
+</PRE>
<P>
-<PRE> /usr/apps/sbin/httpd_perl/httpd_perl -Dsbekman -X
+<PRE> # examples
+ <Location /mrtg>
+ Use embperl
+ </Location>
</PRE>
<P>
-In addition to making life easier, we decided to use relative links
-everywhere in the static docs (including the calls to CGIs). You may ask
-how using the relative link you will get to the right server? Very simple -
-we have utilized the mod_rewrite to solve our problems:
+Macros are also very useful for things that tend to be verbose, such as
+setting up Basic Authentication:
<P>
-In access.conf of the httpd_docs server we have the following code: (you
-have to configure your httpd_docs server with --enable-module=rewrite )
-
+<PRE> # Sets up Basic Authentication
+ <Macro BasicAuth $realm $group>
+ Order deny,allow
+ Satisfy any
+ AuthType Basic
+ AuthName $realm
+ AuthGroupFile /usr/www/auth/groups
+ AuthUserFile /usr/www/auth/users
+ Require group $group
+ Deny from all
+ </Macro>
+</PRE>
<P>
-<PRE> # sbekman' server
- # port = 8000
- RewriteCond %{REQUEST_URI} ^/(perl|cgi-perl)
- RewriteCond %{REMOTE_ADDR} 123.34.45.56
- RewriteRule ^(.*) <A HREF="http://ourserver.com:8000/">http://ourserver.com:8000/</A>$1 [R,L]
-
- # userfoo's server
- # port = 8001
- RewriteCond %{REQUEST_URI} ^/(perl|cgi-perl)
- RewriteCond %{REMOTE_ADDR} 123.34.45.57
- RewriteRule ^(.*) <A HREF="http://ourserver.com:8001/">http://ourserver.com:8001/</A>$1 [R,L]
-
- # all the rest
- RewriteCond %{REQUEST_URI} ^/(perl|cgi-perl)
- RewriteRule ^(.*) <A HREF="http://ourserver.com:81/">http://ourserver.com:81/</A>$1 [R]
-
+<PRE> # example of use
+ <Location /stats>
+ Use BasicAuth WebStats Admin
+ </Location>
</PRE>
<P>
-where IP numbers are the IPs of the developers' client machine (where they
-are running their web browser.) (I have tried to use REMOTE_USER since we
-have all the users authenticated but it didn't work for me)
-
-<P>
-So if I have a relative URL like /perl/test.pl written in some html or even
-<A
-HREF="http://ourserver.com/perl/test.pl">http://ourserver.com/perl/test.pl</A>
-in my case (user at machine of sbekman) it will be redirected by httpd_docs
-to <A
-HREF="http://ourserver.com:8000/perl/test.pl">http://ourserver.com:8000/perl/test.pl</A>
-
+Finally, here is a complete example that uses macros to set up simple
+virtual hosts. It uses the BasicAuth macro defined previously (yes, macros
+can be nested!).
<P>
-Of course you have another problem: The cgi generates some html, which
-should be called again. If it generates a URL with hard coded PORT the
-above scheme will not work. There 2 solutions:
-
+<PRE> <Macro vhost $ip $domain $docroot $admingroup>
+ <VirtualHost $ip>
+ ServerAdmin webmaster@$domain
+ DocumentRoot /usr/www/htdocs/$docroot
+ ServerName www.$domain
+ <Location /stats>
+ Use BasicAuth Stats-$domain $admingroup
+ </Location>
+ </VirtualHost>
+ </Macro>
+</PRE>
<P>
-First, generate relative URL so it will reuse the technique above, with
-redirect (which is transparent for user) but it will not work if you have
-something to POST (redirect looses all the data!).
-
+<PRE> # define some virtual hosts
+ Use vhost 10.1.1.1 example.com example example-admin
+ Use vhost 10.1.1.2 example.net examplenet examplenet-admin
+</PRE>
<P>
-Second, use a general configuration module which generates a correct full
-URL according to REMOTE_USER, so if $ENV{REMOTE_USER} eq 'sbekman', I
-return <A
-HREF="http://ourserver.com:8000/perl/">http://ourserver.com:8000/perl/</A>
-as cgi_base_url. Again this will work if the user is authenticated.
+mod_macro also useful in a non vhost setting. Some sites for example have
+lots of scripts where people use to view various statistics, email settings
+and etc. It is much easier to read things like:
<P>
-All this is good for development. It's better to use the full URLs in
-production, since if you have a static form and the Action is relative but
-the static document sits on another server, pressing the form's submit will
-cause a redirect to mod_perl server, but all the form's data will be lost
-during the redirect.
-
+<PRE> use /forwards email/showforwards
+ use /webstats web/showstats
+</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Wrapper_to_emulate_the_server_en">Wrapper to emulate the server environment</A></H1></CENTER>
-<P>
-Many times you start off debugging your script by running it from your
-favorite shell. Sometimes you encounter a very weird situation when script
-runs from the shell but dies when called as a CGI. The real problem lies in
-the difference between the environment that's being used by your server and
-your shell. An example can be a different perl path or having PERL5LIB env
-variable which includes paths that aren't in the <CODE>@INC</CODE> of the
-perl compiled with mod_perl server and configured during the startup.
-
+<CENTER><H1><A NAME="General_pitfalls">General pitfalls</A></H1></CENTER>
<P>
-The best debugging approach is to write a wrapper that emulates the exact
-environment of the server, by first deleting the environment variables like
-PERL5LIB and calling the same perl binary that it's being used by the
-server. Next, set the environment identical to the server's by copying the
-perl run directives from server startup and configuration files. It'll also
-allow you to remove completely the first line of the script - since
-mod_perl skips it and the wrapper knows how to call the script.
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="My_cgi_perl_code_is_being_return">My cgi/perl code is being returned as a plain text instead of being executed by the webserver?</A></H2></CENTER>
<P>
-Below is the example of such a script. Note that we force the -Tw when we
-call the real script. (I have also added the ability to pass params, which
-will not happen when you call the cgi from the web)
+Check your configuration files and make sure that the ``ExecCGI'' is turned
+on in your configurations.
<P>
-<PRE> #!/usr/apps/bin/perl -w
-
- # This is a wrapper example
-
- # It simulates the web server environment by setting the @INC and other
- # stuff, so what will run under this wrapper will run under web and
- # vice versa.
-
- #
- # Usage: wrap.pl some_cgi.pl
- #
-
- BEGIN{
- use vars qw($basedir);
- $basedir = "/usr/apps";
-
- # we want to make a complete emulation, so we must remove the
- # user's environment
- @INC = ();
-
- # local perl libs
- push @INC, ("$basedir/lib/perl5/5.00502/aix",
- "$basedir/lib/perl5/5.00502",
- "$basedir/lib/perl5/site_perl/5.005/aix",
- "$basedir/lib/perl5/site_perl/5.005",
- );
- }
-
- use strict;
- use File::Basename;
-
- # process the passed params
- my $cgi = shift || '';
- my $params = (@ARGV) ? join(" ", @ARGV) : '';
-
- die "Usage:\n\t$0 some_cgi.pl\n" unless $cgi;
-
- # Set the environment
- my $PERL5LIB = join ":", @INC;
-
- # if the path includes the directory we extract it and chdir there
- if ($cgi =~ m|/|) {
- my $dirname = dirname($cgi);
- chdir $dirname or die "Can't chdir to $dirname: $! \n";
- $cgi =~ m|$dirname/(.*)|;
- $cgi = $1;
- }
-
- # run the cgi from the script's directory
- # Note that we invoke warnings and Taintness ON!!!
- system qq{$basedir/bin/perl -I$PERL5LIB -Tw $cgi $params};
+<PRE> <Location /perl>
+ SetHandler perl-script
+ PerlHandler Apache::Registry
+ Options ExecCGI
+ allow from all
+ PerlSendHeader On
+ </Location>
</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Log_Rotation">Log Rotation</A></H1></CENTER>
+<CENTER><H2><A NAME="My_script_works_under_cgi_bin_b">My script works under cgi-bin, but when called via mod_perl I see A 'Save-As' prompt</A></H2></CENTER>
<P>
-A little bit off topic but good to know and use with mod_perl where your
-error_log can grow at a 10-100Mb per day rate if your scripts spit out lots
-of warnings...
+Did you put <STRONG>PerlSendHeader On</STRONG> in the configuration part of the <Location foo></Location>?
<P>
-To rotate the logs do:
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Is_there_a_way_to_provide_a_diff">Is there a way to provide a different startup.pl file for each individual virtual host</A></H2></CENTER>
+<P>
+No. Any virtual host will be able to see the routines from a startup.pl
+loaded for any other virtual host.
<P>
-<PRE> mv access_log access_log.renamed
- kill -HUP `cat httpd.pid`
- sleep 10; # allow some children to complete requests and logging
- # now it's safe to use access_log.renamed
- .....
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Is_there_a_way_to_modify_INC_on">Is there a way to modify @INC on a per-virtual-host basis.</A></H2></CENTER>
<P>
-The effect of SIGUSR1 and SIGHUP is detailed in: <A
-HREF="http://www.apache.org/docs/stopping.html">http://www.apache.org/docs/stopping.html</A>
+You can use 'PerlSetEnv PERL5LIB ...' or a PerlFixupHandler w/ the lib
+pragma.
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Sometimes_the_script_from_one_vi">Sometimes the script from one virtual host calls a script with
+the same path from the second virtual host</A></H2></CENTER>
<P>
-<META>I tried to kill -USR1 and it didn't reset the logs!!! kill -HUP
-did work</META>
+This has been a bug before, last fixed in 1.15_01, i.e. if you are running
+1.15, that could be the problem. You should set this variable in a startup
+file (PerlRequire):
<P>
-I use this script:
+<PRE> $Apache::Registry::NameWithVirtualHost = 1;
+</PRE>
+<P>
+But, as we know sometimes bug turns into a feature. If there is the same
+script running for more than one Virtual host on the same machine, this can
+be a waste, right? Set it to 0 in a startup script if you want to turn it
+off and have this bug as a feature. (Only makes sense if you are sure that
+there will be no <STRONG>other</STRONG>scripts named by the same path/name)
<P>
-<PRE> #!/usr/apps/bin/perl -Tw
-
- # this script does a log rotation. Called from crontab.
-
- use strict;
- $ENV{PATH}='/bin:/usr/bin';
-
- ### configuration
- my @logfiles = qw(access_log error_log);
- umask 0;
- my $server = "httpd_perl";
- my $logs_dir = "/usr/apps/var/$server/logs";
- my $restart_command = "/usr/apps/sbin/$server/apachectl restart";
- my $gzip_exec = "/usr/intel/bin/gzip";
-
- my ($sec,$min,$hour,$mday,$mon,$year) = localtime(time);
- my $time = sprintf "%0.2d.%0.2d.%0.2d-%0.2d.%0.2d.%0.2d", $year,++$mon,$mday,$hour,$min,$sec;
- $^I = ".".$time;
-
- # rename log files
- chdir $logs_dir;
- @ARGV = @logfiles;
- while (<>) {
- close ARGV;
- }
-
- # now restart the server so the logs will be restarted
- system $restart_command;
-
- # compress log files
- foreach (@logfiles) {
- system "$gzip_exec $_.$time";
- }
+<PRE> $Apache::Registry::NameWithVirtualHost = 0;
</PRE>
<P>
-Randal L. Schwartz contributed this:
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="the_server_no_longer_retrieves_t">the server no longer retrieves the DirectoryIndex files for a directory</A></H2></CENTER>
+<P>
+The problem was reported by users who declared mod_perl configuration
+inside a <Directory> section for all files matching to *.pl. The
+problem has gone away after placing the usage of mod_perl in a
+<File>- section.
-<BLOCKQUOTE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
-<P>
-Cron fires off setuid script called log-roller that looks like this:
+ <HR>
+ [ <A HREF="install.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="frequent.html">Next</A> ]
-<P>
-<PRE> #!/usr/bin/perl -Tw
- use strict;
- use File::Basename;
-
- $ENV{PATH} = "/usr/ucb:/bin:/usr/bin";
-
- my $ROOT = "/WWW/apache"; # names are relative to this
- my $CONF = "$ROOT/conf/httpd.conf"; # master conf
- my $MIDNIGHT = "MIDNIGHT"; # name of program in each logdir
-
- my ($user_id, $group_id, $pidfile); # will be set during parse of conf
- die "not running as root" if $>;
-
- chdir $ROOT or die "Cannot chdir $ROOT: $!";
-
- my %midnights;
- open CONF, "<$CONF" or die "Cannot open $CONF: $!";
- while (<CONF>) {
- if (/^User (\w+)/i) {
- $user_id = getpwnam($1);
- next;
- }
- if (/^Group (\w+)/i) {
- $group_id = getgrnam($1);
- next;
- }
- if (/^PidFile (.*)/i) {
- $pidfile = $1;
- next;
- }
- next unless /^ErrorLog (.*)/i;
- my $midnight = (dirname $1)."/$MIDNIGHT";
- next unless -x $midnight;
- $midnights{$midnight}++;
- }
- close CONF;
-
- die "missing User definition" unless defined $user_id;
- die "missing Group definition" unless defined $group_id;
- die "missing PidFile definition" unless defined $pidfile;
-
- open PID, $pidfile or die "Cannot open $pidfile: $!";
- <PID> =~ /(\d+)/;
- my $httpd_pid = $1;
- close PID;
- die "missing pid definition" unless defined $httpd_pid and $httpd_pid;
- kill 0, $httpd_pid or die "cannot find pid $httpd_pid: $!";
-
-
- for (sort keys %midnights) {
- defined(my $pid = fork) or die "cannot fork: $!";
- if ($pid) {
- ## parent:
- waitpid $pid, 0;
- } else {
- my $dir = dirname $_;
- ($(,$)) = ($group_id,$group_id);
- ($<,$>) = ($user_id,$user_id);
- chdir $dir or die "cannot chdir $dir: $!";
- exec "./$MIDNIGHT";
- die "cannot exec $MIDNIGHT: $!";
- }
- }
-
- kill 1, $httpd_pid or die "Cannot sighup $httpd_pid: $!";
-</PRE>
-<P>
-And then individual MIDNIGHT scripts can look like this:
+<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
+</TR>
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
+ </FONT>
+ </B>
+ </TD>
+
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
+
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
+</TR>
+</TABLE></CENTER>
+
+</BODY>
+</HTML>
+
+
+<HR SIZE=6>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+ <TITLE>mod_perl guide: Frequent mod_perl problems</TITLE>
+ <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
+ <META NAME="Author" CONTENT="Bekman Stas">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
+</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
+<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+<A NAME="toc"></A>
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+Frequent mod_perl problems</H1>
+<HR WIDTH="100%">
+ [ <A HREF="config.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="porting.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+<UL>
+
+ <LI><A HREF="#Coverage">Coverage</A>
+ <LI><A HREF="#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>
+ <LI><A HREF="#Segfaults_caused_by_PerlFreshRes">Segfaults caused by PerlFreshRestart</A>
+</UL>
+<!-- INDEX END -->
+
+<HR>
+
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+
+ <HR>
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<PRE> #!/usr/bin/perl -Tw
- use strict;
-
- die "bad guy" unless getpwuid($<) =~ /^(root|nobody)$/;
- my @LOGFILES = qw(access_log error_log);
- umask 0;
- $^I = ".".time;
- @ARGV = @LOGFILES;
- while (<>) {
- close ARGV;
- }
-</PRE>
+<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
<P>
-Can you spot the security holes? Our trusted user base can't or won't. :)
-But these shouldn't be used in hostile situations.
-
-</BLOCKQUOTE>
+This new document was born because some problems come up so often on the
+mailing list that should be stressed in the guide as one of the most
+important things to read/beware of. So I have tried to enlist them in this
+document. If you think some important problem that is being reported
+frequently on the list and covered in the guide but not included below,
+please tell.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Preventing_from_modperl_process_">Preventing from modperl process to eat up all the disk's space, when it goes wild.</A></H1></CENTER>
+<CENTER><H1><A NAME="my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A></H1></CENTER>
<P>
-Sometimes an error happens and causes the server to write millions of lines
-into your error_log file and in a few minutes to put your server down on
-its knees. For example I get an error <CODE>Callback called exit</CODE>
-show up in my error_log file many times. The error_log files grows to 300
-Mbytes in size in a few minutes. You should run a cron job to make sure
-this doesn't happen and if it does to take care of it. Andreas J. Koenig is
-running this shell script every minute:
+See <A HREF="././obvious.html#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>.
<P>
-<PRE> S=`ls -s /usr/local/apache/logs/error_log | awk '{print $1}'`
- if [ "$S" -gt 100000 ] ; then
- /etc/rc.d/init.d/httpd restart
- date | /bin/mail -s "error_log $S kB on inx" myemail@domain.com
- fi
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Segfaults_caused_by_PerlFreshRes">Segfaults caused by PerlFreshRestart</A></H1></CENTER>
<P>
-It seems that his script will trigger restart every minute, since once the
-logfile grows to be of 100000 lines, it'll stay of this size, unless you
-remove or rename it, before you do restart. On my server I run a watchdog
-every five minutes which restarts the server if it's getting stuck (it
-always works since when some modperl child process goes wild, the I/O it
-causes is so heavy that other brother processes can't normally to serve the
-requests.) See <A HREF="././control.html#Monitoring_the_Server_A_watchdo">Monitoring the Server</A> for more hints.
+See <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>
-<P>
-Ulrich Pfeifer told us this: You may also look at the daemontools from D.
-J. Bernstein - <A
-HREF="ftp://koobera.math.uic.edu/www/daemontools.html">ftp://koobera.math.uic.edu/www/daemontools.html</A>
-<P>
-<PRE> ,-----
- | cyclog writes a log to disk. It automatically synchronizes the log
- | every 100KB (by default) to guarantee data integrity after a crash. It
- | automatically rotates the log to keep it below 1MB (by default). If
- | the disk fills up, cyclog pauses and then tries again, without losing
- | any data.
- `-----
-</PRE>
+
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -3904,7 +4042,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="config.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="porting.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -3916,8 +4055,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
@@ -3947,8 +4086,11 @@
<TITLE>mod_perl guide: CGI to mod_perl Porting. mod_perl Coding guidelines.</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -3959,14 +4101,14 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
CGI to mod_perl Porting. mod_perl Coding guidelines.</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="frequent.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="performance.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Document_Coverage">Document Coverage</A>
@@ -3985,8 +4127,8 @@
<LI><A HREF="#Using_exit_">Using exit()</A>
<LI><A HREF="#Running_from_shell">Running from shell</A>
<LI><A HREF="#I_O_is_different">I/O is different</A>
- <LI><A HREF="#HTTP_MIME_Headers">HTTP (MIME) Headers</A>
- <LI><A HREF="#NPH_Non_Parsed_Headers_scripts">NPH (Non Parsed Headers) scripts </A>
+ <LI><A HREF="#HTTP_MIME_Headers_PerlSendHea">HTTP + MIME Headers (PerlSendHeader)</A>
+ <LI><A HREF="#NPH_Non_Parsed_Headers_scripts">NPH (Non Parsed Headers) scripts</A>
<LI><A HREF="#BEGIN_blocks">BEGIN blocks </A>
<LI><A HREF="#END_blocks">END blocks </A>
<LI><A HREF="#Switches_w_T">Switches -w, -T</A>
@@ -4009,10 +4151,12 @@
</UL>
<LI><A HREF="#Redirecting_Errors_to_Client_ins">Redirecting Errors to Client instead of error_log</A>
+ <LI><A HREF="#Finding_the_line_number_the_erro">Finding the line number the error/warning has been triggered at</A>
+ <LI><A HREF="#Forking_subprocesses_from_mod_pe">Forking subprocesses from mod_perl</A>
</UL>
<!-- INDEX END -->
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -4022,7 +4166,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Document_Coverage">Document Coverage</A></H1></CENTER>
<P>
@@ -4065,6 +4211,7 @@
maintaining Perl modules. <A
HREF="http://world.std.com/~swmcd/steven/perl/module_mechanics.html">http://world.std.com/~swmcd/steven/perl/module_mechanics.html</A>
+
<P><LI><STRONG><A NAME="item_Mod">Mod Perl Book</A></STRONG>
<P>
A must have book! See the details at <A
@@ -4104,6 +4251,8 @@
if your URI is <STRONG>/perl/test.pl</STRONG> the package will be called
<STRONG>Apache::ROOT::perl::test_2epl;</STRONG>
+
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H3><A NAME="Name_collisions_with_Modules_and">Name collisions with Modules and libs</A></H3></CENTER>
@@ -4146,7 +4295,7 @@
<P>
And both scripts do: <CODE>use Foo;</CODE> only the first one called will know about Foo, when you will call the
second script it will not know about Foo at all - it's like you've
-forgotten to write <CODE>use Foo;</CODE>. Run the server in <A HREF="././control.html#Single_Mode_Running">single server mode</A> to solve that kind of bug immediately.
+forgotten to write <CODE>use Foo;</CODE>. Run the server in <A HREF="././control.html#Running_server_in_a_single_mode">single server mode</A> to solve that kind of bug immediately.
<P>
You will see the following in the error_log file:
@@ -4385,7 +4534,7 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="HTTP_MIME_Headers">HTTP (MIME) Headers</A></H3></CENTER>
+<CENTER><H3><A NAME="HTTP_MIME_Headers_PerlSendHea">HTTP + MIME Headers (PerlSendHeader)</A></H3></CENTER>
<P>
By default, mod_perl does not send any headers by itself, however, you may
wish to change this (in httpd.conf):
@@ -4402,7 +4551,7 @@
<PRE> print "Content-type: text/html\r\n\r\n";
</PRE>
<P>
-If you're using CGI.pm or CGI::Switch and <STRONG>print $q->header</STRONG> you do _not_ need PerlSendHeader On.
+If you are using CGI.pm or CGI::Switch and <STRONG>print $q->header</STRONG> you do _not_ need PerlSendHeader On.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -4439,50 +4588,50 @@
Modules and files pulled in via require/use which contain BEGIN blocks will
be executed:
-<DL>
-<P><DT><STRONG><A NAME="item__">-</A></STRONG><DD>
+<UL>
+<P><LI>
<P>
only once, if pulled in by the parent process.
-<P><DT><STRONG>-</STRONG><DD>
+<P><LI>
<P>
once per-child process if not pulled in by the parent process.
-<P><DT><STRONG>-</STRONG><DD>
+<P><LI>
<P>
an additional time, once per-child process if the module is pulled in off
of disk again via Apache::StatINC.
-<P><DT><STRONG>-</STRONG><DD>
+<P><LI>
<P>
an additional time, in the parent process on each restart if
PerlFreshRestart is On.
-<P><DT><STRONG>-</STRONG><DD>
+<P><LI>
<P>
unpredictable if you fiddle with <CODE>%INC</CODE> yourself.
-</DL>
+</UL>
<P>
Apache::Registry scripts which contain BEGIN blocks will be executed:
-<DL>
-<P><DT><STRONG>-</STRONG><DD>
+<UL>
+<P><LI>
<P>
only once, if pulled in by the parent process via Apache::RegistryLoader -
once per-child process if not pulled in by the parent process.
-<P><DT><STRONG>-</STRONG><DD>
+<P><LI>
<P>
an additional time, once per-child process if the script file has changed
on disk.
-<P><DT><STRONG>-</STRONG><DD>
+<P><LI>
<P>
an additional time, in the parent process on each restart if pulled in by
the parent process via Apache::RegistryLoader and PerlFreshRestart is On.
-</DL>
+</UL>
<P>
Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
@@ -4515,7 +4664,7 @@
desirable.
<P>
-The last paragraph is very important for the <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>
+The last paragraph is very important for the <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -4558,14 +4707,15 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="strict_pragma">strict pragma</A></H2></CENTER>
<P>
-It's absolutely mandatory to start all your scripts with:
+It's _absolutely_ mandatory (at least for development) to start all your
+scripts with:
<P>
-<PRE> use strict; (at least for development)
+<PRE> use strict;
</PRE>
<P>
-If needed, you can always turn off the 'strict' pragma inside the block,
-e.g:
+If needed, you can always turn off the 'strict' pragma or a part of it
+inside the block, e.g:
<P>
<PRE> {
@@ -4657,6 +4807,8 @@
<P>
Also see <A HREF="././perl.html#Using_global_variables_and_shari">Using global variables and sharing them</A>
+
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Code_has_been_changed_but_it_se">Code has been changed, but it seems the script is running the old code</A></H2></CENTER>
@@ -4727,6 +4879,8 @@
<P>
For more see <CODE>perldoc perlref</CODE>
+
+
<P>
Another approach would be to directly use the <CODE>@_</CODE> variable.
Using directly the <CODE>@_</CODE> array serves the job of passing by
@@ -4984,7 +5138,7 @@
the more it runs without a restart, the more it screws up. Many times you
can resolve this problem very easily. You have to test your script under
with Server running as a
-<A HREF="././control.html#Single_Mode_Running">single process</A>.
+<A HREF="././control.html#Running_server_in_a_single_mode">single process</A>.
<P>
Generally the problem you have is using global variables. Since global
@@ -5057,7 +5211,7 @@
<P>
To make sure you don't miss these bugs always test your CGI in
-<A HREF="././control.html#Single_Mode_Running">single process</A>. To solve this particular <STRONG>/o</STRONG> problem refer to <A HREF="././obvious.html#Compiled_Regular_Expressions">Compiled Regular Expressions</A>.
+<A HREF="././control.html#Running_server_in_a_single_mode">single process</A>. To solve this particular <STRONG>/o</STRONG> problem refer to <A HREF="././obvious.html#Compiled_Regular_Expressions">Compiled Regular Expressions</A>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -5087,6 +5241,8 @@
<P>
See <A HREF="#">Apache::PerlRun - a closer look</A>
+
+
<P>
Another ``bad'', but working method is to set MaxRequestsPerChild to 1,
which will force each child to exit after serving only one request, so
@@ -5302,6 +5458,118 @@
method to print the errors and wouldn't <CODE>die()</CODE> unless you want
it.
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Finding_the_line_number_the_erro">Finding the line number the error/warning has been triggered at</A></H1></CENTER>
+<P>
+If you compile with the experimental <STRONG>PERL_MARK_WHERE=1</STRONG>, it shows you ``exactly'' where this is happening. many times compiler
+makes a shift for ``unknown'' reasons in its line counter. You can always
+stuff your code with special compiler directives, to reset its counter to
+the value you will tell. At the beginning of the line you should write (the
+'#' in column 1):
+
+<P>
+<PRE> #line 298 myscript.pl
+ or
+ #line 890 some_label_to_be_used_in_the_error_message
+</PRE>
+<P>
+The label is optional - the filename of the script will be used by default.
+This specifies the line number of the <STRONG>following</STRONG> line, not the line the directive is on. You can use a little script to
+stuff every N lines of your code with these directives, but then you will
+have to rerun this script every time you add or remove code lines. The
+script:
+
+<P>
+<PRE> <META>
+ This example was double incrementing $counter.
+ I took the second increment out -- sgr.
+ </META>
+</PRE>
+<P>
+<PRE> #!/usr/bin/perl
+ # Puts Perl line markers in a Perl program for debugging purposes.
+ # Also takes out old line markers.
+ die "No filename to process.\n" unless @ARGV;
+ my $filename = $ARGV[0];
+ my $lines = 100;
+ open IN, $filename or die "Cannot open file: $filename: $!\n";
+ open OUT, ">$filename.marked"
+ or die "Cannot open file: $filename.marked: $!\n";
+ my $counter = 1;
+ while (<IN>) {
+ print OUT "#line $counter\n" unless $counter++ % $lines;
+ next if $_ =~ /^#line /;
+ print OUT $_;
+ }
+ close OUT;
+ close IN;
+ chmod 0755, "$filename.marked";
+</PRE>
+<P>
+To have a complete trace of calls add:
+
+<P>
+<PRE> use Carp ();
+ local $SIG{__WARN__} = \&Carp::cluck;
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Forking_subprocesses_from_mod_pe">Forking subprocesses from mod_perl</A></H1></CENTER>
+<P>
+Generally you should not fork from your mod_perl scripts, since when you do
+you are forking the entire apache web server, lock, stock and barrel. Not
+only is your perl code being duplicated, but so is mod_ssl, mod_rewrite,
+mod_log, mod_proxy, mod_speling or whatever modules you have used in your
+server, all the core routines and so on. A much wiser approche would be to
+spawn a sub-process, hand it the information it needs to do the task, and
+have it detach (close x3 + <CODE>setsid()).</CODE> This is wise only if the
+parent who spawns this process, immediately continue, you do not wait for
+the sub process to complete. This approach is suitable for a situation when
+you want to trigger a long time taking process through the web interface,
+like processing some data, sending email to thousands of subscribed users
+and etc. Otherwise, you should convert the code into a module, and use its
+function or methods to call from CGI script. Just making a
+<CODE>system()</CODE> call defeats the whole idea behind mod_perl, perl interpreter and modules
+should be loaded again for this extenal program to run.
+
+<P>
+Basically, you would do:
+
+<P>
+<PRE> $params=FreezeThaw::freeze(
+ [all data to pass to the other process]
+ );
+ system("program.pl $params");
+</PRE>
+<P>
+and in <CODE>program.pl</CODE> :
+
+<P>
+<PRE> @params=FreezeThaw::thaw(shift @ARGV);
+ # check that @params is ok
+ close STDIN;
+ close STDOUT;
+ open STDERR, ">/dev/null";
+ setsid(); # to detach
+</PRE>
+<P>
+At this point, <CODE>program.pl</CODE> is running in the ``background'' while the <CODE>system()</CODE> returns
+and permits apache to get on with life.
+
+<P>
+This has obvious problems. Not the least of which is that
+<CODE>$params</CODE> must not be bigger then whatever your architecture's
+limit is (could depend on your shell).
+
+<P>
+Also, the communication is only one way.
+
+<P>
+However, you might want be trying to do the ``wrong thing''. If what you
+want is to send information to the browser and then do some
+post-processing, look into <CODE>PerlCleanupHandler</CODE>.
+
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -5311,7 +5579,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="frequent.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="performance.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -5323,8 +5592,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
@@ -5351,11 +5620,14 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: Frequent mod_perl problems</TITLE>
+ <TITLE>mod_perl guide: Performance. Benchmarks.</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -5366,156 +5638,59 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Frequent mod_perl problems</H1>
+Performance. Benchmarks.</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="porting.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="obvious.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
- <LI><A HREF="#Coverage">Coverage</A>
- <LI><A HREF="#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>
- <LI><A HREF="#Segfaults_caused_by_PerlFreshRes">Segfaults caused by PerlFreshRestart</A>
-</UL>
-<!-- INDEX END -->
-
- <P><A HREF="index.html">[Back to the main index]</A></P>
-
- The <a href="http://www.modperl.com/">
- <B>Writing Apache Modules with Perl and C</B></a>
- book can be purchased online from <a
- href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
- and <a
- href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
- Amazon.com</a>.
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<P>
-<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
-<P>
-This new document was born because some problems come up so often on the
-mailing list that should be stressed in the guide as one of the most
-important things to read/beware of. So I have tried to enlist them in this
-document. If you think some important problem that is being reported
-frequently on the list and covered in the guide but not included below,
-please tell.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A></H1></CENTER>
-<P>
-<A HREF="././obvious.html#my_scoped_variable_in_nested_s">More info</A>
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Segfaults_caused_by_PerlFreshRes">Segfaults caused by PerlFreshRestart</A></H1></CENTER>
-<P>
-<A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
- The <a href="http://www.modperl.com/">
- <B>Writing Apache Modules with Perl and C</B></a>
- book can be purchased online from <a
- href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
- and <a
- href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
- Amazon.com</a>.
-
-<P><A HREF="index.html">[Back to the main index]</A></P>
-
-<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
-<TR ALIGN=CENTER VALIGN=TOP>
- <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
- <HR>
- </TD>
-</TR>
-<TR ALIGN=CENTER VALIGN=TOP>
- <TD ALIGN=CENTER VALIGN=CENTER>
- <B>
- <FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/02/99
- </FONT>
- </B>
- </TD>
-
- <TD>
- <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
- </TD>
-
- <TD>
- <FONT SIZE=-2>
- Use of the Camel for Perl is <BR>
- a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
- and is used by permission.
- </FONT>
- </TD>
-</TR>
-</TABLE></CENTER>
-
-</BODY>
-</HTML>
-
-
-<HR SIZE=6>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
-<HTML>
-<HEAD>
- <TITLE>mod_perl guide: Things obvious to others, but not to you</TITLE>
- <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
- <META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
-</HEAD>
- <LINK REL=STYLESHEET TYPE="text/css"
- HREF="style.css" TITLE="refstyle">
- <style type="text/css">
- <!--
- @import url(style.css);
- -->
-
- </style>
-<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+ <LI><A HREF="#Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A>
+ <UL>
-<H1 ALIGN=CENTER>
-<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
-<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Things obvious to others, but not to you</H1>
-<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
-<UL>
+ <LI><A HREF="#Preload_Perl_modules_Real_Numb">Preload Perl modules - Real Numbers</A>
+ </UL>
- <LI><A HREF="#Coverage">Coverage</A>
- <LI><A HREF="#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>
+ <LI><A HREF="#Preopen_DB_connection_at_server_">Preopen DB connection at server startup</A>
+ <LI><A HREF="#Memory_sharing">Memory sharing</A>
+ <LI><A HREF="#Preload_Registry_Scripts">Preload Registry Scripts</A>
+ <LI><A HREF="#Avoid_Importing_Functions">Avoid Importing Functions</A>
+ <LI><A HREF="#Reducing_the_Memory_Usage">Reducing the Memory Usage</A>
+ <LI><A HREF="#how_can_I_find_if_my_modperl_scr">how can I find if my modperl scripts have memory leaks (and where)</A>
+ <LI><A HREF="#Limiting_the_size_of_the_process">Limiting the size of the processes</A>
+ <LI><A HREF="#Limiting_the_resources_used_by_h">Limiting the resources used by httpd children</A>
+ <LI><A HREF="#Limiting_the_request_rate_speed_">Limiting the request rate speed (robots blocking)</A>
+ <LI><A HREF="#Benchmarks_Impressing_your_Boss">Benchmarks. Impressing your Boss and Colleagues.</A>
<UL>
- <LI><A HREF="#The_poison">The poison</A>
- <LI><A HREF="#The_diagnosis">The diagnosis</A>
- <LI><A HREF="#The_remedy">The remedy</A>
+ <LI><A HREF="#Developers_Talk">Developers Talk</A>
+ <LI><A HREF="#Benchmarking_a_Graphic_hits_coun">Benchmarking a Graphic hits counter with Persistent DB Connection</A>
+ <LI><A HREF="#Benchmarking_scripts_with_execut">Benchmarking scripts with execution times below 1 second :)</A>
+ <LI><A HREF="#PerlHandler_s_Benchmarking">PerlHandler's Benchmarking</A>
</UL>
- <LI><A HREF="#Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A>
+ <LI><A HREF="#Tuning_the_Apache_s_configuratio">Tuning the Apache's configuration variables for the best performance</A>
<UL>
- <LI><A HREF="#Restarting_the_server">Restarting the server</A>
- <LI><A HREF="#Using_Apache_StatINC">Using Apache::StatINC</A>
- <LI><A HREF="#Reloading_only_specific_files">Reloading only specific files</A>
+ <LI><A HREF="#Tuning_with_ab_ApacheBench">Tuning with ab - ApacheBench </A>
+ <LI><A HREF="#Tuning_with_crashme_script">Tuning with crashme script</A>
+ <LI><A HREF="#Choosing_MaxClients">Choosing MaxClients</A>
+ <LI><A HREF="#Choosing_MaxRequestsPerChild">Choosing MaxRequestsPerChild</A>
+ <LI><A HREF="#Choosing_MinSpareServers_MaxSpa">Choosing MinSpareServers, MaxSpareServers and StartServers</A>
+ <LI><A HREF="#Summary_of_Benchmarking_to_tune_">Summary of Benchmarking to tune all 5 parameters</A>
</UL>
- <LI><A HREF="#Compiled_Regular_Expressions">Compiled Regular Expressions </A>
- <LI><A HREF="#Debugging_your_code_in_Single_Se">Debugging your code in Single Server Mode</A>
- <LI><A HREF="#_M_and_other_time_file_tests_u">-M and other time() file tests under mod_perl</A>
- <LI><A HREF="#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>
- <LI><A HREF="#Handling_the_server_timeout_case">Handling the server timeout cases</A>
- <LI><A HREF="#Where_do_the_warnings_errors_go_">Where do the warnings/errors go?</A>
+ <LI><A HREF="#Persistent_DB_Connections">Persistent DB Connections</A>
+ <LI><A HREF="#Using_1_under_mod_perl_and_be">Using $|=1 under mod_perl and better print() techniques.</A>
+ <LI><A HREF="#Profiling">Profiling</A>
+ <LI><A HREF="#CGI_pm_s_object_methods_calls_vs">CGI.pm's object methods calls vs. function calls</A>
</UL>
<!-- INDEX END -->
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -5525,1115 +5700,2893 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<P>
-<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
-<P>
-This document describes ``special'' traps you may encounter when running
-your plain CGIs under Apache::Registry and Apache::PerlRun.
+ <HR>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A></H1></CENTER>
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="The_poison">The poison</A></H2></CENTER>
+<CENTER><H1><A NAME="Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A></H1></CENTER>
<P>
-In a non modperl script (stand alone or CGI), there is no problem writing
-code like this:
+Use the PerlRequire and PerlModule directives to load commonly used modules
+such as CGI.pm, DBI, etc., when the server is started. On most systems,
+server children will be able to share this space.
<P>
-<PRE> use CGI qw/param/;
- my $x = param('x');
- sub printit {
- print "$x\n";
- }
-</PRE>
+You can also put the standard <CODE>use Foo;</CODE> into the startup-file.
+
<P>
-However, the script is run under Apache::Registry, it will in fact be
-repackaged into something like this:
+CGI.pm is a special one. Ordinarily CGI.pm autoloads most of its functions
+on an as-needed basis. This speeds up the loading time by deferring the
+compilation phase. However, if you are using mod_perl, FastCGI or another
+system that uses a persistent Perl interpreter, you will want to precompile
+the methods at initialization time. To accomplish this, call the package
+function <CODE>compile()</CODE> like this:
<P>
-<PRE> package $mangled_package_name;
- sub handler {
- #line1 $original_filename
- use CGI qw/param/;
- my $x = param('x');
- sub printit {
- print "$x\n";
- }
- }
+<PRE> use CGI ();
+ CGI->compile(':all');
</PRE>
<P>
-Now <CODE>printit</CODE> is an inner named subroutine. Because it is referencing a lexical variable
-from an enclosing scope, a closure is created.
+The arguments to <CODE>compile()</CODE> are a list of method names or sets, and are identical to those accepted by
+the use operator.
<P>
-The first time the script is run, the correct value of <CODE>$x</CODE> will
-be printed. However on subsequent runs, <CODE>printit</CODE> will retain the initial value of <CODE>$x</CODE> -- not what you want.
+You can also preload the Registry scripts. See <A HREF="#Preload_Registry_Scripts">Preload Registry Scripts</A>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="The_diagnosis">The diagnosis</A></H2></CENTER>
+<CENTER><H2><A NAME="Preload_Perl_modules_Real_Numb">Preload Perl modules - Real Numbers</A></H2></CENTER>
<P>
-Always use -w (or/and PerlWarn ON)! Perl will then emit a warning like:
+I have conducted a few tests to benchmark the memory usage when some
+modules are preloaded. First set of tests checks the memory use with
+Library Perl Module preload (only CGI.pm). The second set checks the
+compile method of CGI.pm. The third test checks benefit the the Library
+Perl Module preload but a few of them (too see more memory saved) and also
+the effect of precompiling the Registry modules with
+Apache::RegistryLoader.
-<P>
-<PRE> Value of $x will not stay shared at - line 5.
-</PRE>
<P>
-NOTE: Subroutines defined inside <STRONG>BEGIN{}</STRONG> and <STRONG>END{}</STRONG> cannot trigger this message, since each <STRONG>BEGIN{}</STRONG> and <STRONG>END{}</STRONG> is defined to be called exactly once. (To understand why, read about the
-closures at
-<CODE>perlref</CODE> or <CODE>perlfaq</CODE> 13.12)
+Summary:
<P>
-PERLDIAG manpage says:
+1. Library Perl Modules Preloading gave a good results everywhere.
<P>
-<PRE> An inner (nested) named subroutine is referencing a lexical variable
- defined in an outer subroutine.
-</PRE>
+2. compile method of CGI seems to make things worse (may be the speed is
+better?)
+
<P>
-When the inner subroutine is called, it will probably see the value of the
-outer subroutine's variable as it was before and during the *first* call to
-the outer subroutine; in this case, after the first call to the outer
-subroutine is complete, the inner and outer subroutines will no longer
-share a common value for the variable. In other words, the variable will no
-longer be shared.
+3. Apache::RegistryLoader might made the script load faster on the first
+request after the child has just started but the memory usage was worse!!!
+See the numbers by yourself.
<P>
-Check your code by running Apache in single-child mode (httpd -X). Since
-the value of a my variable retain its initial value <CODE>per
-child process</CODE>, the closure problem can be difficult to track down in multi-user mode. It
-will appear to work fine until you have cycled through all the httpd
-children.
+HW/SW: The server is apache 1.3.2, mod_perl 1.16 running on AIX 4.1.5
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="The_remedy">The remedy</A></H2></CENTER>
+--------------------------------------------------------------------------------
+
+
<P>
-If a variable needs file scope, use a global variable:
+1. In the first test was used a script:
<P>
-<PRE> use vars qw/$x/;
- use CGI qw/param/;
- $x = param('x');
- sub printit {
- print "$x\n";
- }
+<PRE> use strict;
+ use CGI ();
+ my $q = new CGI;
+ print $q->header;
+ print $q->start_html,$q->p("Hello");
</PRE>
<P>
-You can safely use a <CODE>my()</CODE> scoped variable if its value is constant:
+<Server restarted>
<P>
-<PRE> use vars qw/$x/;
- use CGI qw/param/;
- $x = param('x');
- my $y = 5;
- sub printit {
- print "$x, $y\n";
- }
+Before the CGI.pm preload: (No other modules preloaded)
+
+<P>
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 87004 0.0 0.0 1060 1524 - A 16:51:14 0:00 httpd
+ httpd 240864 0.0 0.0 1304 1784 - A 16:51:13 0:00 httpd
</PRE>
<P>
-Also see the clarification of <CODE>my()</CODE> vs. <CODE>use vars</CODE> - Ken Williams writes:
+After running a script which uses CGI's methods (no imports):
<P>
-<PRE> Yes, there is quite a bit of difference! With use vars(), you are
- making an entry in the symbol table, and you are telling the
- compiler that you are going to be referencing that entry without an
- explicit package name.
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 188068 0.0 0.0 1052 1524 - A 17:04:16 0:00 httpd
+ httpd 86952 0.0 1.0 2520 3052 - A 17:04:16 0:00 httpd
</PRE>
<P>
-<PRE> With my(), NO ENTRY IS PUT IN THE SYMBOL TABLE. The compiler
- figures out _at_ _compile_time_ which my() variables (i.e. lexical
- variables) are the same as each other, and once you hit execute time
- you can not go looking those variables up in the symbol table.
-</PRE>
+Observation: child httpd has grown up by 1268K
+
<P>
-And <CODE>my()</CODE> vs. <CODE>local()</CODE> - Randal Schwartz writes:
+<Server restarted>
<P>
-<PRE> local() creates a temporal-limited package-based scalar, array,
- hash, or glob -- when the scope of definition is exited at runtime,
- the previous value (if any) is restored. References to such a
- variable are *also* global... only the value changes. (Aside: that
- is what causes variable suicide. :)
-</PRE>
+After the CGI.pm preload:
+
<P>
-<PRE> my() creates a lexically-limited non-package-based scalar, array, or
- hash -- when the scope of definition is exited at compile-time, the
- variable ceases to be accessible. Any references to such a variable
- at runtime turn into unique anonymous variables on each scope exit.
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 240796 0.0 0.0 1456 1552 - A 16:55:30 0:00 httpd
+ httpd 86944 0.0 0.0 1688 1800 - A 16:55:30 0:00 httpd
</PRE>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A></H1></CENTER>
+after running a script which uses CGI's methods (no imports):
+
<P>
-When you develop plain CGI scripts, you can just change the code, and rerun
-the CGI from your browser. Since the script isn't cached in memory, the
-next time you call it the server starts up a new perl process, which
-recompiles it from scratch. The effects of any modifications you've applied
-are immediately present.
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 86872 0.0 0.0 1448 1552 - A 17:02:56 0:00 httpd
+ httpd 187996 0.0 1.0 2808 2968 - A 17:02:56 0:00 httpd
+</PRE>
+<P>
+Observation: child httpd has grown up by 1168K, 100K less then without
+preload - good!
<P>
-The situation is different with Apache::Registry, since the whole idea is
-to get maximum performance from the server. By default, the server won't
-spend the time to check whether any included library modules have been
-changed. It assumes that they weren't, thus saving a few milliseconds to <CODE>stat()</CODE> the source file (multiplied by however many modules/libraries you are
-<STRONG>use</STRONG>/<STRONG>require</STRONG>-ing in your script.) The only check that is being done is whether your
-main script has been changed. So if you have only one script that doesn't <STRONG>use</STRONG> (or <STRONG>require</STRONG>) other perl modules (or packages), there is nothing new about it. If
-however, you are developing a script that includes other modules, the files
-you <STRONG>use()</STRONG> or <STRONG>require()</STRONG> aren't being checked to see if they have been modified.
+<Server restarted>
<P>
-Acknowledging this, how do we get our modperl-enabled server to recognize
-changes in any library modules? Well, there are a couple of techniques:
+After CGI.pm preloaded and compiled with CGI->compile(':all');
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Restarting_the_server">Restarting the server</A></H2></CENTER>
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 86980 0.0 0.0 2836 1524 - A 17:05:27 0:00 httpd
+ httpd 188104 0.0 0.0 3064 1768 - A 17:05:27 0:00 httpd
+</PRE>
<P>
-See <A HREF="././control.html#Restarting_techniques">Server Restarting techniques</A>.
+After running a script which uses CGI's methods (no imports):
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Using_Apache_StatINC">Using Apache::StatINC</A></H2></CENTER>
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 86980 0.0 0.0 2828 1524 - A 17:05:27 0:00 httpd
+ httpd 188104 0.0 1.0 4188 2940 - A 17:05:27 0:00 httpd
+</PRE>
<P>
-After restarting the server about 100 times, you will be tired and will
-look for another solutions. Help comes from the Apache::StatINC module.
+Observation: child httpd has grown up by 1172K No change! So what does
+CGI->compile(':all') helps? I guess it helps if you import the symbols
+(subs) rather you use the methods
<P>
-Read its pod pages, but beware of the following note: Only the modules
-located in <STRONG>@INC</STRONG> are being reloaded on change, and you can change the <STRONG>@INC</STRONG> only before the server has been started. Whatever you do in your
-scripts/modules which are being <CODE>required()</CODE> after the server
-startup will not have any effect on <STRONG>@INC</STRONG>.
+--------------------------------------------------------------------------------
+
<P>
-When you do <STRONG>use lib qw(foo/bar);</STRONG>, the <STRONG>@INC</STRONG> is being changed only for the time the code is being parsed. When it's over
-the <STRONG>@INC</STRONG> is being reset to its original value. To make sure that you have set a
-correct <STRONG>@INC</STRONG> fetch <A
-HREF="http://your.perl.server/perl-status?inc">http://your.perl.server/perl-status?inc</A>
-and watch the bottom of the page. (I assume you have configured the
-<Location /perl-status> section in httpd.conf as the mod_perl docs
-show.)
+2. I have tried the second test to find it. I run the script:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Reloading_only_specific_files">Reloading only specific files</A></H2></CENTER>
+use strict; use CGI <CODE>qw(:all);</CODE> print
+header,start_html,p(``Hello'');
+
<P>
-Checking all the Modules in <STRONG>%INC</STRONG> can add some (large?) overhead to server response times, and you certainly
-wouldn't want Apache::StatINC module to be enabled in your production
-site's configuration. But sometimes you want to have some Configuration
-file (module) be reloaded without restarting the whole server. For this you
-will have to add something like this in your code:
+<Server restarted>
<P>
-Assume that you started your scripts with:
+After CGI.pm preloaded and NOT compiled with CGI->compile(':all');
<P>
-<PRE> use lib "/some/private/path";
- use Foo::Bar qw(:subs);
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 17268 0.0 0.0 1456 1552 - A 18:02:49 0:00 httpd
+ httpd 86904 0.0 0.0 1688 1800 - A 18:02:49 0:00 httpd
</PRE>
<P>
-Now to make a modification test and reload at runtime you have to use
-something like this:
+After running a script which imports symbols, all of them
<P>
-<PRE> # child's global variable to keep the timestamps
- use vars qw(%MODIFIED);
-
- my $my_lib_root = "/some/private/path";
- my $conf = "Foo/Bar.pm";
- my $conf_path = "$my_lib_root/$conf";
-
- # set modification time if it wasn't set before
- # Note: Use (stat $conf_path)[9] instead of -M test, if you reset
- # time with $^M=time
- $MODIFIED{$conf} ||= -M $conf_path;
-
- # now check whether it was changed (assuming the above wasn't
- # performed in this session
- if ($MODIFIED{$conf} != -M $conf_path){
- # only if deleted from %INC the require will be called below
- delete $INC{$conf};
-
- # this should be safe since @INC is being reset after we leave
- # the script, or you can skip this stage and require the script
- # with full path, remember that @INC now is different from the
- # one you have had when the script has been called at first time
- unshift @INC,$my_lib_root;
-
- # reread the file : use() wouldn't work here since it's compile time directive
- require Foo::Bar;
-
- # now export the symbols (if you need them back :)
- import Foo::Bar qw(:subs);
-
- # Update the MODIFICATION times
- $MODIFIED{$conf} = -M $conf_path;
- }
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 17268 0.0 0.0 1448 1552 - A 18:02:49 0:00 httpd
+ httpd 86904 0.0 1.0 2952 3112 - A 18:02:49 0:00 httpd
</PRE>
<P>
-You may want to add debug print statements to test this code in your
-application.
+Observation: child httpd has grown up by 1264K
<P>
-Read the ``use versus require'' article for more info.
-(http://www.perl.com/CPAN-local/doc/FMTEYEWTK/use_vs_require)
+<Server restarted>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Compiled_Regular_Expressions">Compiled Regular Expressions</A></H1></CENTER>
+After CGI.pm preloaded and compiled with CGI->compile(':all');
+
<P>
-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 execution of the program, a standard optimization technique
-consists of adding the <STRONG>/o</STRONG> modifier to the regexp pattern. This directs the compiler to build the
-internal table once, for the entire lifetime of the script, rather than
-every time the pattern is executed. Consider:
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 86812 0.0 0.0 2836 1524 - A 17:59:52 0:00 httpd
+ httpd 99104 0.0 0.0 3064 1768 - A 17:59:52 0:00 httpd
+</PRE>
+<P>
+After running a script which imports symbols, all of them
<P>
-<PRE> my $pat = '^foo$'; # likely to be input from an HTML form field
- foreach( @list ) {
- print if /$pat/o;
- }
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 86812 0.0 0.0 2832 1436 - A 17:59:52 0:00 httpd
+ httpd 99104 0.0 1.0 4884 3636 - A 17:59:52 0:00 httpd
</PRE>
<P>
-This is usually a big win in loops over lists, or when using
-<STRONG>grep</STRONG> or <STRONG>map</STRONG>.
+Observation: child httpd has grown up by 1868K. Why? Isn't
+CGI->compile(':all') supposed to make children to share the compiled
+code with parent?
<P>
-In long-lived mod_perl scripts, however, this can pose a problem if the
-variable changes according to the invocation. The first invocation of a
-fresh httpd child will compile the regex and perform the search correctly.
-However, all subsequent uses by the httpd child will continue to match the
-original pattern, regardless of the current contents of the Perl variables
-the pattern is dependent on. Your script will appear broken.
+--------------------------------------------------------------------------------
+
<P>
-There are two solutions to this problem.
+3. The third script
<P>
-The first is to use <STRONG>eval q//</STRONG>, to force the code to be evaluated each time. Just make sure that the eval
-block covers the entire loop of processing, and not just the pattern match
-itself.
+<PRE> use strict;
+ use CGI;
+ use Data::Dumper;
+ use Storable;
+ [and many lines of code, lots of globals - so the code is huge!]
+</PRE>
+<P>
+<Server restarted>
<P>
-The above code fragment would be rewritten as:
+Nothing preloaded at startup
<P>
-<PRE> my $pat = '^foo$';
- eval q{
- foreach( @list ) {
- print if /$pat/o;
- }
- }
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 90962 0.0 0.0 1060 1524 - A 17:16:45 0:00 httpd
+ httpd 86870 0.0 0.0 1304 1784 - A 17:16:45 0:00 httpd
</PRE>
<P>
-Just saying:
+Script using CGI (methods), Storable, Data::Dumper called
<P>
-<PRE> eval q{ print if /$pat/o; };
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 90962 0.0 0.0 1064 1436 - A 17:16:45 0:00 httpd
+ httpd 86870 0.0 1.0 4024 4548 - A 17:16:45 0:00 httpd
</PRE>
<P>
-is going to be a horribly expensive proposition.
+Observation: child httpd has grown up by 2764K
<P>
-You can use this approach if you require more than one pattern match
-operator in a given section of code. If the section contains only one
-operator (be it an <STRONG>m//</STRONG> or <STRONG>s///</STRONG>), you can rely on the property of the null pattern, that reuses the last
-pattern seen. This leads to the second solution, which also eliminates the
-use of eval.
+<Server restarted>
<P>
-The above code fragment becomes:
+Preloaded CGI (compiled), Storable, Data::Dumper at startup
<P>
-<PRE> my $pat = '^foo$';
- "something" =~ /$pat/; # dummy match (MUST NOT FAIL!)
- foreach( @list ) {
- print if //;
- }
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 26792 0.0 0.0 3120 1528 - A 17:19:21 0:00 httpd
+ httpd 91052 0.0 0.0 3340 1764 - A 17:19:21 0:00 httpd
</PRE>
<P>
-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 <STRONG>//</STRONG> will match everything. If you can't count on fixed text to ensure the match
-succeeds, you have two possibilities.
-
-<P>
-If you can guarantee that the pattern variable contains no meta-characters
-(things like *, +, ^, $...), you can use the dummy match:
-
-<P>
-<PRE> "$pat" =~ /\Q$pat\E/; # guaranteed if no meta-characters present
-</PRE>
-<P>
-If there is a possibility that the pattern can contain meta-characters, you
-should search for the pattern or the unsearchable \377 character as
-follows:
+Script using CGI (methods), Storable, Data::Dumper called
<P>
-<PRE> "\377" =~ /$pat|^[\377]$/; # guaranteed if meta-characters present
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 26792 0.0 0.0 3124 1440 - A 17:19:21 0:00 httpd
+ httpd 91052 0.0 1.0 6568 5040 - A 17:19:21 0:00 httpd
</PRE>
<P>
-Phil. Chu contributed this:
+Observation: child httpd has grown up by 3276K. Great different: 512K
+less!!!
<P>
-It depends on the complexity of the regexp you apply this technique to. One
-common usage where compiled regexp is usually more efficient is to ``match
-any one of a group of patterns'' over and over again.
+<Server restarted>
<P>
-Maybe with some helper routine, it's easier to remember. Here is one
-slightly modified from Jeffery Friedl's example in his book ``Mastering
-Regex.''. I find it quite useful:
+All the above modules + the above script PreCompiled with
+Apache::RegistryLoader at startup
<P>
-<PRE> #####################################################
- # Build_MatchMany_Function
- # -- Input: list of patterns
- # -- Output: A code ref which matches its $_[0]
- # against ANY of the patterns given in the
- # "Input", efficiently.
- #
- sub Build_MatchMany_Function {
- my @R = @_;
- my $expr = join '||', map { "\$_[0] =~ m/\$R[$_]/o" } ( 0..$#R );
- my $matchsub = eval "sub { $expr }";
- die "Failed in building regex @R: $@" if $@;
- $matchsub;
- }
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 43224 0.0 0.0 3256 1528 - A 17:23:12 0:00 httpd
+ httpd 26844 0.0 0.0 3488 1776 - A 17:23:12 0:00 httpd
</PRE>
<P>
-Example usage:
+Script using CGI (methods), Storable, Data::Dumper called
<P>
-<PRE> @some_browsers = qw(Mozilla Lynx MSIE AmigaVoyager lwp libwww);
- $Known_Browser=Build_MatchMany_Function(@some_browsers);
+<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
+ root 43224 0.0 0.0 3252 1440 - A 17:23:12 0:00 httpd
+ httpd 26844 0.0 1.0 6748 5092 - A 17:23:12 0:00 httpd
</PRE>
<P>
-<PRE> while (<ACCESS_LOG>) {
- # ...
- $browser = get_browser_field($_);
- if ( ! &$Known_Browser($browser) ) {
- print STDERR "Unknown Browser: $browser\n";
- }
- # ...
- }
-</PRE>
+Observation: child httpd has grown even more 3316K ! Does not seem to be
+good!
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Debugging_your_code_in_Single_Se">Debugging your code in Single Server Mode</A></H1></CENTER>
-<P>
-Running in httpd -X mode. (good only for testing during development phase).
-
+<CENTER><H1><A NAME="Preopen_DB_connection_at_server_">Preopen DB connection at server startup</A></H1></CENTER>
<P>
-You want to test that your application correctly handles global variables
-(if you have any - the less you have of them the better, but sometimes you
-just can't without them). It's hard to test with multiple servers serving
-your cgi since each child has a different value for its global variables.
-Imagine that you have a <CODE>random()</CODE> sub that returns a random
-number and you have the following script.
+If you use DBI for DB connections, you can preopen a connections to DB for
+each child with Apache::DBI.
<P>
-<PRE> use vars qw($num);
- $num ||= random();
- print ++$num;
+<PRE> use Apache::DBI ();
+ Apache::DBI->connect_on_init("DBI:mysql:test", 'login','passwd',
+ {
+ RaiseError => 1,
+ PrintError => 1,
+ AutoCommit => 1,
+ };
</PRE>
<P>
-This script initializes the variable <STRONG>$num</STRONG> with a random value, then increments it on each request and prints it out.
-Running this script in multiple server environments will result in
-something like 1,9,4,19 (number per reload), since each time your script
-will be served by a different child. (On some OSes, the parent httpd
-process will assign all of the requests to the same child process if all of
-the children are idle... AIX...). But if you run in httpd -X single server
-mode you will get 2,3,4,5... (taken that the <CODE>random()</CODE> returned
-1 at the first call)
+See also <A HREF="#Persistent_DB_Connections">Persistent DB Connections</A>
-<P>
-But do not get too obsessive with this mode, since working only in single
-server mode sometimes hides problems that show up when you switch to multi
-server mode. Consider an application that allows you to change the
-configuration at run time.
+
<P>
-Let's say the script produces a form to change the background color of the
-page. It's not a good design, but for the sake of demonstrating the
-potential problem, we will assume that our script doesn't write the changed
-background color to the disk, but simply changes it in memory.
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Memory_sharing">Memory sharing</A></H1></CENTER>
+<P>
+Another important point is memory sharing. If you OS supports this, and
+most of systems do, you might save more memory by sharing it between child
+processes. This is only possible when you preload code at the server
+startup. However during child process' life its memory pages becomes
+unshared and there is no way we can control perl to make it allocate memory
+so (dynamic) variables land on different memory pages than constants so the
+copy-on-write effect will hit almost at random. If you are pre-loading many
+modules you might be able to balance the memory that stays shared against
+the time for an occasional fork by tuning the <CODE>MaxRequestsperChild</CODE> to a point where you restart before too much becomes unshared. In this case
+the
+<CODE>MaxRequestsPerChild</CODE> is very specific to your scenario. You should do some measurements and you
+might see if this really makes a difference and what a reasonable number
+might be. Each time a child reaches this upper limit and restarts it should
+release the unshared copies and the new child will inherit pages that are
+shared until it scribbles on them.
<P>
-So you have typed in a new color, and in response, your script prints back
-the html with a new color - you think that's it! It was so simple. And if
-you keep running in single server mode you will never notice that you have
-a problem...
+It is very important to understand that your goal is not to have
+<CODE>MaxRequestsperChild</CODE> to be of 10000. Having a child to serve 300 requests on precompiled code is
+already a huge speedup, so if it is 100 or 10000 it does not really matter
+if it saves you the RAM by sharing. Do not forget that if you preload most
+of your code at the server startup, the fork to spawn a new child will be
+very very fast, cause it inherits most of the preloaded code and the perl
+interpreter from the parent process.
<P>
-If you run the same code in the multi server environment, after you submit
-the color change you will get the result as expected, but when you will
-call the same URL again (not reload!) chances are that you will get back
-the old color, since except the child who processed the color change
-request no one knows about their global variable change. Just remember that
-children can't share information, other than that which they inherited from
-their parent on their load.
+The conclusion is that <CODE>MaxRequestsperChild</CODE> should not be too big, otherwise you loose the benefits of the memory
+sharing.
<P>
-Also note that since the server is running in single mode, if the output
-returns HTML with IMG tags, then the load of these will take a lot of time
-(read apache docs of httpd -X to learn why).
+See <A HREF="././performance.html#Choosing_MaxRequestsPerChild">Choosing MaxRequestsPerChild</A> for more about tuning the <CODE>MaxRequestsperChild</CODE> parameter.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="_M_and_other_time_file_tests_u">-M and other time() file tests under mod_perl</A></H1></CENTER>
+<CENTER><H1><A NAME="Preload_Registry_Scripts">Preload Registry Scripts</A></H1></CENTER>
<P>
-Under mod_perl, files that have been created after the server's (child?)
-startup are being reported with negative age with -M (-C -A) test. This is
-obvious if you remember that you will get the negative result if the server
-was started before the file was created and it's a normal behavior with any
-perl.
+Apache::RegistryLoader compiles Apache::Registry scripts at server startup.
+It can be a good idea to preload these as well. So the code will be shared
+among the child servers.
<P>
-If you want to have -M test to count the time relative to the current
-request, you should reset the $^T variable as with any other perl script.
-Just add <CODE>$^T = time;</CODE> at the beginning of the scripts.
+example of use at modperl.com in a PerlRequire'd file:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A></H1></CENTER>
+<PRE> use File::Find 'finddepth';
+ use Apache::RegistryLoader ();
+ {
+ my $perl_dir = "perl/";
+ my $rl = Apache::RegistryLoader->new;
+ finddepth(sub {
+ return unless /\.pl$/;
+ my $url = "/$File::Find::dir/$_";
+ print "pre-loading $url\n";
+
+ my $status = $rl->handler($url);
+ unless($status == 200) {
+ warn "pre-load of `$url' failed, status=$status\n";
+ }
+ }, $perl_dir);
+ }
+</PRE>
<P>
-When a user presses the stop button, Apache will detect that via
-SIG{'PIPE'} and will cease the script execution. When we are talking about
-mod_cgi, there is generally no problem, since all opened files will be
-closed and all the resources will be freed (almost all -- if you happened
-to use external lock files, most likely the resources that are being locked
-by these will be left blocked and non-usable by any others who use this
-advisory locking scheme.)
+Note that we don't use here the second argument to the
+<CODE>handler().</CODE> You might need to provide a <CODE>trans()</CODE>
+method, since it's very dependent on your server's configuration. See <CODE>perldoc Apache::RegistryLoader</CODE> for the complete information.
<P>
-Important to notice that when the user hits ``stop'' on the browser, the
-mod_perl script is blissfully unaware until it tries to send some data to
-the browser. At that point, Apache realizes that the browser is gone, and
-all the good cleanup stuff happens.
+You have to check whether it makes any good for you though, I did some
+testing [ <A HREF="#Preload_Perl_modules_Real_Numb">Preload Perl modules - Real Numbers</A> ], and it seems that it takes more memory than when the scripts is being
+called from the child - This is only a first impression and needs better
+investigation. If you aren't concerned about few scripts invocations which
+will take some time to respond while they load the code, you might not need
+it all!
<P>
-Starting from apache 1.3.6 apache will not catch SIGPIPE anymore and
-modperl will do it much better. Here is something from CHANGES from Apache
-1.3.6.
+See also <A HREF="././porting.html#BEGIN_blocks">BEGIN blocks</A>
+
+
<P>
-<PRE> *) SIGPIPE is now ignored by the server core. The request write
- routines (ap_rputc, ap_rputs, ap_rvputs, ap_rwrite, ap_rprintf,
- ap_rflush) now correctly check for output errors and mark the
- connection as aborted.
- Replaced many direct (unchecked) calls to ap_b* routines with the
- analogous ap_r* calls. [Roy Fielding]
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Avoid_Importing_Functions">Avoid Importing Functions</A></H1></CENTER>
<P>
-What happens if your mod_perl script has some global variables, that are
-being used for resource locking?
+When possible, avoid importing of a module functions into your name space.
+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.
<P>
-It's possible not to notice the pitfall if the critical code section
-between lock and unlock is very short and finishes fast, so you never see
-this happens (you aren't fast enough to stop the code in the middle). But
-look at the following scenario:
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Reducing_the_Memory_Usage">Reducing the Memory Usage</A></H1></CENTER>
+<P>
+One of the important issues in improving the performance is memory usage
+reduce - the less memory server uses - the more server processes you can
+start - the more performance you have (from the user point of view - the
+respond speed )
<P>
-<PRE> 1. lock resource
- <b><critical section starts>
- 2. sleep 20 (== do some time consuming processing)
- <critical section ends></b>
- 3. unlock resource
-</PRE>
+See <A HREF="././porting.html#Global_Variables">Global Variables</A>
+
+
+
<P>
-If user presses 'Stop' and Apache sends SIGPIPE before step 3, since we are
-in the mod_perl mode and we want the lock variable to be cached, it will be
-not unlocked. A kind of ``deadlock'' exists.
+See <A HREF="././porting.html#Memory_leakage">Memory "leakages"</A>
+
+
<P>
-Here is the working example. Run the server with -X, Press 'Stop' before
-the countup to 10 has been finished. Then rerun the script, it'll hang in
-<CODE>while(1)!</CODE> The resource is not available anymore.
+Joel Wagner reports that calling an undefined subroutine in a module can
+cause a tight loop that consumes all memory. Here is a way to catch such
+errors. Define an autoload subroutine:
<P>
-<PRE> -------------------------------------------------------------
- use vars qw(%CACHE);
- use CGI;
- $|=1;
- my $q = new CGI;
- print $q->header,$q->start_html;
-
- print $q->p("$$ Going to lock!\n");
-
- # actually the while loop below is not needed
- # (since it's an internal lock and accessible only
- # by the same process and it if it's locked... it's locked for the
- # whole child's life
- while (1) {
- unless (defined $CACHE{LOCK} and $CACHE{LOCK} == 1) {
- $CACHE{LOCK} = 1;
- print $q->p("Got the lock!\n");
- last;
- }
- }
- print $q->p("Going to sleep (I mean working)!");
- my $c=0;
- foreach (1..10) {
- sleep 1;
- print $c++,"\n<BR>";
+<PRE> sub UNIVERSAL::AUTOLOAD {
+ my $class = shift;
+ warn "$class can't \$UNIVERSAL::AUTOLOAD!\n";
}
-
- print $q->p("Going to unlock!");
- $CACHE{LOCK} = 0;
- print $q->p("Unlock!\n");
- -------------------------------------------------------------
</PRE>
<P>
-You may ask, what is the solution for this problem? As noted in the
-<A HREF="././porting.html#END_blocks">END blocks</A> any END blocks that are encountered during compilation of Apache::Registry
-scripts are called after the script done is running, including subsequent
-invocations when the script is cached in memory. So if you are running in
-Apache::Registry mode, the following is your remedy:
+It will produce a nice error in error_log, giving the line number of the
+call and the name of the undefined subroutine.
<P>
-<PRE> END {
- $CACHE{LOCK} = 0;
- }
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="how_can_I_find_if_my_modperl_scr">how can I find if my modperl scripts have memory leaks (and where)</A></H1></CENTER>
<P>
-Notice that the END block will be run after the Apache::Registry::handler
-is finished (not during the cleanup phase though).
+Apache::Leak (derived from Devel::Leak) should help you with this task.
+Example:
<P>
-If you are into a perl API, use the <STRONG>register_cleanup()</STRONG> method of Apache.
+<PRE> use Apache::Leak;
+
+ my $global = "FooAAA";
+
+ leak_test {
+ $$global = 1;
+ ++$global;
+ };
+</PRE>
+<P>
+The argument to <CODE>leak_test()</CODE> is an anonymous sub, so you can
+just throw it around any code you suspect might be leaking. beware, it will
+run the code twice, because the first time in, new SVs are created, but
+does not mean you are leaking, the second pass will give better evidence.
+you do not need to be inside mod_perl to use it, from the command line, the
+above script outputs:
<P>
-<PRE> $r->register_cleanup(sub {$CACHE{LOCK} = 0;});
+<PRE> ENTER: 1482 SVs
+ new c28b8 : new c2918 :
+ LEAVE: 1484 SVs
+ ENTER: 1484 SVs
+ new db690 : new db6a8 :
+ LEAVE: 1486 SVs
+ !!! 2 SVs leaked !!!
</PRE>
<P>
-If you are into Apache API <CODE>Apache-</CODE>request->connection->aborted()> construct can be used to test for
-the aborted connection.
+Build a debuggable perl to see dumps of the SVs. the simple way to have
+both a normal perl and debuggable perl, is to follow hints in the SUPPORT
+doc for building libperld.a, when that is built copy the `perl' from that
+directory to your perl bin directory, but name it `dperl'.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Handling_the_server_timeout_case">Handling the server timeout cases</A></H1></CENTER>
+<CENTER><H1><A NAME="Limiting_the_size_of_the_process">Limiting the size of the processes</A></H1></CENTER>
<P>
-A similar situation to <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Pressed Stop button disease</A> happens when client (browser) timeouts the connection (is it about 2
-minutes?) . There are cases when your script is about to perform a very
-long operation and there is a chance that its duration will be longer than
-the client's timeout. One case I can think about is the DataBase
-interaction, where the DB engine hangs or needs a lot of time to return
-results. If this is the case, use <CODE>$SIG{ALRM}</CODE> to prevent the timeouts:
+Apache::SizeLimit allows you to kill off Apache httpd processes if they
+grow too large. see perldoc Apache::SizeLimit for more details.
<P>
-<PRE> eval {
- local $SIG{ALRM} = sub { die "timeout\n" };
- alarm $timeout;
- ... db stuff ...
- alarm 0;
- };
-
- die $@ if $@;
-</PRE>
+By using this module, you should be able to discontinue using the Apache
+configuration directive MaxRequestsPerChild, although for some folks, using
+both in combination does the job.
+
<P>
-But, as lately it was discovered <CODE>local $SIG{'ALRM'}</CODE> does not restore the original underlying C handler. Look at <CODE>Sys::Signal</CODE>
-module, which should solve this problem.
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Limiting_the_resources_used_by_h">Limiting the resources used by httpd children</A></H1></CENTER>
+<P>
+Apache::Resource uses the BSD::Resource module, which uses the C function
+setrlimit to set limits on system resources such as memory and cpu usage.
<P>
-<CODE>Sys::Signal</CODE> - Set signal handlers with restoration of existing C sighandler
+See perldoc Apache::Resource for more info.
<P>
-Now use this code:
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Limiting_the_request_rate_speed_">Limiting the request rate speed (robots blocking)</A></H1></CENTER>
+<P>
+A limitation of using pattern matching to identify robots is that it only
+catches the robots that you know about, and only those that identify
+themselves by name. A few devious robots masquerade as users by using user
+agent strings that identify themselves as conventional browsers. To catch
+such robots, you'll have to be more sophisticated.
<P>
-<PRE> use Sys::Signal ();
- eval {
- my $h = Sys::Signal->set(ALRM => sub { die "timeout\n" });
- alarm $timeout;
- ... do something thay may timeout ...
- alarm 0;
- };
- die $@ if $@;
-</PRE>
+Apache::SpeedLimit comes for you to help, see:
+
<P>
-As of this writing it is still not entered CPAN and you can find it at <A
-HREF="http://www.modperl.com/~dougm/perl/Sys-Signal-0.01.tar.gz">http://www.modperl.com/~dougm/perl/Sys-Signal-0.01.tar.gz</A>
-. (But check the CPAN for the latest version anyway)
+<A
+HREF="http://www.modperl.com/chapters/ch6.html#Blocking_Greedy_Clients">http://www.modperl.com/chapters/ch6.html#Blocking_Greedy_Clients</A>
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Where_do_the_warnings_errors_go_">Where do the warnings/errors go?</A></H1></CENTER>
+<CENTER><H1><A NAME="Benchmarks_Impressing_your_Boss">Benchmarks. Impressing your Boss and Colleagues.</A></H1></CENTER>
<P>
-Your CGI does not work and you want to see what the problem is. The best
-idea is to check out any errors that the server may be reporting. Where I
-can find these errors?
+How much faster is mod_perl that CGI? There are many ways to benchmark the
+two. See a few examples and numbers below, also checkout the benchmark/
+directory of mod_perl dist for more examples.
<P>
-Generally all errors are logged into an error_log file. The exact file
-location and name are defined in the http.conf file. Look for the <CODE>ErrorLog</CODE> parameter. My httpd.conf says:
+If you write a benchmarks from your own for heavy scripts use
+<CODE>Benchmark</CODE> and for very fast scripts use <CODE>Time::HiRes</CODE> modules.
<P>
-<PRE> ErrorLog var/logs/error_log
-</PRE>
+There is no need to write a special benchmark, if you want to impress your
+boss or colleagues, just take the heaviest cgi script you have, open 2
+xterms and call the same script in mod_perl mode in one xterm and in
+mod_cgi mode in the other. You can use lwp-get from LWP package to emulate
+the web agent (browser). (benchmark/ directory of mod_perl dist includes
+such an example)
+
<P>
-Hey, where is the beginning of the path? There is another Apache parameter
-called <CODE>ServerRoot</CODE>. Every time apache sees a value of the parameter with no absolute path
-(e.g <CODE>/tmp/my.txt</CODE>) but with relative path (e.g <CODE>my.txt</CODE>) it prepends the value of the <CODE>ServerRoot</CODE> to this value. I have:
+See also 2 tools for benchmarking:
+<A HREF="././performance.html#Tuning_with_ab_ApacheBench">ApacheBench</A> and <A HREF="././performance.html#Tuning_with_crashme_script">crashme test</A>
+
+
<P>
-<PRE> ServerRoot /usr/local/apache
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Developers_Talk">Developers Talk</A></H2></CENTER>
<P>
-So I will look for error_log file at
-<CODE>/usr/local/apache/var/logs/error_log</CODE>. Of course you can also use an absolute path to define the file's location
-at the file system.
+Perrin Harkins writes on benchmarks or comparisons, official or unofficial:
-<P>
-<META>: is this 100% correct?
+<BLOCKQUOTE>
<P>
-But there are cases when errors don't go to the error_log file. For example
-some errors are being printed to the console (tty) you have executed the
-httpd from (unless you redirected the httpd's stderr flow). This happens
-when the server didn't open the error_log file for writing yet.
+I have used some of the platforms you mentioned and researched others. What
+I can tell you for sure, is that no commercially available system offers
+the depth, power, and ease of use that mod_perl has. Either they don't let
+you access the web server internals, or they make you use less productive
+languages than Perl, sometimes forcing you into restrictive and confusing
+APIs and/or GUI development environments. None of them offer the level of
+support available from simply posting a message to this list, at any price.
<P>
-For example, if you have mistakenly entered a non-existent directory path
-in your <STRONG>ErrorLog</STRONG> directive, the error message will be printed on the controlling tty. Or, if
-the error happens when server executes PerlRequire or PerlModule directive
-you might see the errors here also.
+As for performance, beyond doing several important things (code-caching,
+pre-forking/threading, and persistent database connections) there isn't
+much these tools can do, and it's mostly in your hands as the developer to
+see that the things which really take the time (like database queries) are
+optimized.
<P>
-You are probably wonder where all the errors go when you are running the
-server in single mode (httpd -X). They go to the console. That is because
-when running in the single mode there is no parent httpd process to perform
-all the logging. It includes all the status messages that generally show up
-in the error_log file.
+The downside of all this is that most manager types seem to be unable to
+believe that web development software available for free could be better
+than the stuff that cost $25,000 per CPU. This appears to be the major
+reason most of the web tools companies are still in business. They send a
+bunch of suits to give PowerPoint presentations and hand out glossy
+literature to your boss, and you end up with an expensive disaster and an
+approaching deadline.
<P>
-</META>
+But I'm not bitter or anything...
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
- The <a href="http://www.modperl.com/">
- <B>Writing Apache Modules with Perl and C</B></a>
- book can be purchased online from <a
- href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
- and <a
- href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
- Amazon.com</a>.
+</BLOCKQUOTE>
-<P><A HREF="index.html">[Back to the main index]</A></P>
+<P>
+Jonathan Peterson adds:
-<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
-<TR ALIGN=CENTER VALIGN=TOP>
- <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
- <HR>
- </TD>
-</TR>
-<TR ALIGN=CENTER VALIGN=TOP>
- <TD ALIGN=CENTER VALIGN=CENTER>
- <B>
- <FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
- </FONT>
- </B>
- </TD>
+<BLOCKQUOTE>
- <TD>
- <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
- </TD>
+<P>
+Most of the major solutions have something that they do better than the
+others, and each of them has faults. Microsoft's ASP has a very nice
+objects model, and has IMO the best data access object (better than DBI to
+use - but less portable) It has the worst scripting language. PHP has many
+of the advantages of Perl-based solutions, but is less complicated for
+developers. Netscape's Livewire has a good object model too, and provides
+good server-side Java integration - if you want to leverage Java skills,
+it's good. Also, it has a compiled scripting language - which is great if
+you aren't selling your clients the source code (and a pain otherwise).
- <TD>
- <FONT SIZE=-2>
- Use of the Camel for Perl is <BR>
- a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
- and is used by permission.
- </FONT>
- </TD>
-</TR>
-</TABLE></CENTER>
-
-</BODY>
-</HTML>
-
-
-<HR SIZE=6>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
-<HTML>
-<HEAD>
- <TITLE>mod_perl guide: Warnings and Errors: Where and Why.</TITLE>
- <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
- <META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
-</HEAD>
- <LINK REL=STYLESHEET TYPE="text/css"
- HREF="style.css" TITLE="refstyle">
- <style type="text/css">
- <!--
- @import url(style.css);
- -->
-
- </style>
-<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+<P>
+mod_perl's advantage is that it is the most powerful. It offers the
+greatest degree of control with one of the more powerful languages. It also
+offers the greatest granularity. You can use an embedding module (eg eperl)
+from one place, a session module (Session) from another, and your data
+access module from yet another.
-<H1 ALIGN=CENTER>
-<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
-<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Warnings and Errors: Where and Why.</H1>
-<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
-<UL>
+<P>
+I think the Apache::ASP module looks very promising. It has very easy to
+use and adequately powerful state maintenance, a good embedding system, and
+a sensible object model (that emulates the Microsoft ASP one). It doesn't
+replicate MS's ADO for data access, but DBI is fine for that.
- <LI><A HREF="#General_Advice">General Advice </A>
- <LI><A HREF="#Incorrect_line_number_reporting_">Incorrect line number reporting in error/warn log messages</A>
- <LI><A HREF="#Value_of_x_will_not_stay_shared">Value of $x will not stay shared at - line 5</A>
- <LI><A HREF="#Value_of_x_may_be_unavailable_a">Value of $x may be unavailable at - line 5.</A>
- <LI><A HREF="#mod_perl_rwrite_returned_1">mod_perl: rwrite returned -1</A>
- <LI><A HREF="#caught_SIGPIPE_in_process">caught SIGPIPE in process</A>
- <LI><A HREF="#Client_hit_STOP_or_Netscape_bit_">Client hit STOP or Netscape bit it!</A>
- <LI><A HREF="#Constant_subroutine_redefine">Constant subroutine ... redefined</A>
- <LI><A HREF="#Global_symbol_foo_requires_ex">Global symbol "$foo" requires explicit package name</A>
- <LI><A HREF="#Can_t_undef_active_subroutine">Can't undef active subroutine</A>
- <LI><A HREF="#Use_of_uninitialized_value_at_e">Use of uninitialized value at (eval 80) line 12.</A>
- <LI><A HREF="#Undefined_subroutine_Apache_RO">Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function called at</A>
- <LI><A HREF="#Can_t_load_auto_DBI_DBI_so_">Can't load '.../auto/DBI/DBI.so' for module DBI</A>
- <LI><A HREF="#Callback_called_exit">Callback called exit</A>
- <LI><A HREF="#Out_of_memory_">Out of memory!</A>
- <LI><A HREF="#_warn_child_process_30388_did_n">[warn] child process 30388 did not exit, sending another SIGHUP</A>
- <LI><A HREF="#RegistryLoader_Cannot_translate">RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl</A>
- <LI><A HREF="#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>
- <LI><A HREF="#server_reached_MaxClients_settin">server reached MaxClients setting, consider raising the MaxClients setting</A>
-</UL>
-<!-- INDEX END -->
+<P>
+I have always found that the developers available make the greatest impact
+on the decision. If you have a team with no Perl experience, and a small or
+medium task, using something like PHP, or Microsoft ASP, makes more sense
+than driving your staff into the vertical learning curve they'll need to
+use mod_perl.
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<P>
+For very large jobs, it may be worth finding the best technical solution,
+and then recruiting the team with the necessary skills.
- The <a href="http://www.modperl.com/">
- <B>Writing Apache Modules with Perl and C</B></a>
- book can be purchased online from <a
- href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
- and <a
- href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
- Amazon.com</a>.
+</BLOCKQUOTE>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<CENTER><H1><A NAME="General_Advice">General Advice</A></H1></CENTER>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Benchmarking_a_Graphic_hits_coun">Benchmarking a Graphic hits counter with Persistent DB Connection</A></H2></CENTER>
<P>
-Enabling <CODE>use diagnostics;</CODE> generally helps you to determine the source of the problem and how to solve
-it. See <A HREF="././porting.html#diagnostics_pragma">diagnostics pragma</A> for more info.
+Here are the numbers from Michael Parker's mod_perl presentation at Perl
+Conference (Aug, 98) <A
+HREF="http://www.realtime.net/~parkerm/perl/conf98/index.htm">http://www.realtime.net/~parkerm/perl/conf98/index.htm</A>
+. The script is a standard hits counter, but it logs the counts into the
+mysql relational DataBase:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Incorrect_line_number_reporting_">Incorrect line number reporting in error/warn log messages</A></H1></CENTER>
+<PRE> Benchmark: timing 100 iterations of cgi, perl... [rate 1:28]
+
+ cgi: 56 secs ( 0.33 usr 0.28 sys = 0.61 cpu)
+ perl: 2 secs ( 0.31 usr 0.27 sys = 0.58 cpu)
+
+ Benchmark: timing 1000 iterations of cgi,perl... [rate 1:21]
+
+ cgi: 567 secs ( 3.27 usr 2.83 sys = 6.10 cpu)
+ perl: 26 secs ( 3.11 usr 2.53 sys = 5.64 cpu)
+
+ Benchmark: timing 10000 iterations of cgi, perl [rate 1:21]
+
+ cgi: 6494 secs (34.87 usr 26.68 sys = 61.55 cpu)
+ perl: 299 secs (32.51 usr 23.98 sys = 56.49 cpu)
+</PRE>
<P>
-See <A HREF="././warnings.html#Use_of_uninitialized_value_at_e">Use of uninitialized value at (eval 80) line 12.</A>
-=head1 Incorrect line number reporting in error/warn log messages
+We don't know what server configurations was used for these testing, but I
+guess the numbers talks for themselves.
+
+<P>
+The source code of the script at <A
+HREF="http://www.realtime.net/~parkerm/perl/conf98/sld006.htm">http://www.realtime.net/~parkerm/perl/conf98/sld006.htm</A>
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Value_of_x_will_not_stay_shared">Value of $x will not stay shared at - line 5</A></H1></CENTER>
+<CENTER><H2><A NAME="Benchmarking_scripts_with_execut">Benchmarking scripts with execution times below 1 second :)</A></H2></CENTER>
<P>
-See <A HREF="././obvious.html#my_scoped_variable_in_the_nest">my() scoped variable in the nested subroutine</A>
+As noted before for very fast scripts you will have to use Time::HiRes
+module, it's usage is similar to the Benchmark's.
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Value_of_x_may_be_unavailable_a">Value of $x may be unavailable at - line 5.</A></H1></CENTER>
+<PRE> use Time::HiRes qw(gettimeofday tv_interval);
+ my $start_time = [ gettimeofday ];
+ &sub_that_takes_a_teeny_bit_of_time()
+ my $end_time = [ gettimeofday ];
+ my $elapsed = tv_interval($start_time,$end_time);
+ print "the sub took $elapsed secs."
+</PRE>
<P>
-See <A HREF="././obvious.html#my_scoped_variable_in_the_nest">my() scoped variable in the nested subroutine</A>
+See also <A HREF="././performance.html#Tuning_with_crashme_script">crashme test</A>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="mod_perl_rwrite_returned_1">mod_perl: rwrite returned -1</A></H1></CENTER>
+<CENTER><H2><A NAME="PerlHandler_s_Benchmarking">PerlHandler's Benchmarking</A></H2></CENTER>
<P>
-That message happens when the client breaks the connection while your
-script is trying to write to the client. With Apache 1.3.x, you should only
-see the rwrite messages if LogLevel is set to debug.
+At <A
+HREF="http://perl.apache.org/dist/contrib/">http://perl.apache.org/dist/contrib/</A>
+you will find Apache::Timeit package which does PerlHandler's Benchmarking.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="caught_SIGPIPE_in_process">caught SIGPIPE in process</A></H1></CENTER>
+<CENTER><H1><A NAME="Tuning_the_Apache_s_configuratio">Tuning the Apache's configuration variables for the best performance</A></H1></CENTER>
<P>
-<PRE> [modperl] caught SIGPIPE in process 1234
- [modperl] process 1234 going to Apache::exit with status...
-</PRE>
+It's very important to make a correct configuration of the
+<CODE>MinSpareServers MaxSpareServers StartServers MaxClients
+MaxRequestsPerChild</CODE> parameters. There are no defaults, the values of these variable are very
+important, as if too ``low'' you will not use the system for its full
+ability, and if too ``high'' chances your server will bring the machine to
+its knees.
+
<P>
-That's the <STRONG>$SIG{PIPE}</STRONG> handler installed by mod_perl/Apache::SIG, called if a connection timesout
-or Client presses the 'Stop' button. It gives you an opportunity to do
-cleanups if the script was aborted in the middle of its execution. See <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A> for more info.
+All the above parameters should be specified on the basis of the resources
+you have. While with plain apache server, there is no big deal if you run
+too many servers (not too many of course) since the processes are of ~1Mb
+and aren't eating a lot of your RAM. The situation is different with
+mod_perl. I have seen mod_perl processes of 20Mb and more. Now if you have
+MaxClients set to 50: 50x20Mb = 1Gb - do you have 1Gb of RAM? Probably not.
+So how do you tune these numbers? Generally by trying different
+combinations and testing the server.
<P>
-If your mod_perl version < 1.17 you might get the message in the
-following section...
+Before you start this task you should be armed with the proper weapon. You
+need a crashme script, which will load your server with all kinds of
+mod_perl scripts you can think you have in your repository. There are
+commercial solutions for that, when you have free ones that do the same job
+(but for free :). You can use an
+<A HREF="././performance.html#Tuning_with_ab_ApacheBench">ApacheBench</A> <STRONG><CODE>ab</CODE></STRONG> utility that comes with apache distribution or use a <A HREF="././performance.html#Tuning_with_crashme_script">crashme test</A> which uses LWP::Parallel::UserAgent. You need these to have an ability to
+emulate multiuser environment and to generate multiply clients which will
+call the mod_perl scripts at your server simultaneously.
+
+<P>
+See also 2 tools for benchmarking:
+<A HREF="././performance.html#Tuning_with_ab_ApacheBench">ApacheBench</A> and <A HREF="././performance.html#Tuning_with_crashme_script">crashme test</A>
+
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Client_hit_STOP_or_Netscape_bit_">Client hit STOP or Netscape bit it!</A></H1></CENTER>
+<CENTER><H2><A NAME="Tuning_with_ab_ApacheBench">Tuning with ab - ApacheBench</A></H2></CENTER>
<P>
-<PRE> Client hit STOP or Netscape bit it!
- Process 2493 going to Apache::exit with status=-2
-</PRE>
+<STRONG>ab</STRONG> is a tool for benchmarking your Apache HTTP server. It is designed to give
+you an impression on how much performance your current Apache installation
+can give. Particularly it shows you how much requests per secs your Apache
+server is capable to serve. The
+<STRONG>ab</STRONG> comes bundled with apache source distribution (and it's free :).
+
<P>
-You will see this message in mod_perl < 1.17. See <A HREF="././warnings.html#caught_SIGPIPE_in_process">caught SIGPIPE in process</A>.
+Lets try it. We will simulate 10 users concurrently requesting the script <CODE>www.you.com:81/test/test.pl</CODE> which a very light one. Each one does it for 10 times.
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Constant_subroutine_redefine">Constant subroutine ... redefined</A></H1></CENTER>
+<PRE> % ./ab -n 100 -c 10 www.you.com:81/test/test.pl
+
+ Concurrency Level: 10
+ Time taken for tests: 0.715 seconds
+ Complete requests: 100
+ Failed requests: 0
+ Non-2xx responses: 100
+ Total transferred: 60700 bytes
+ HTML transferred: 31900 bytes
+ Requests per second: 139.86
+ Transfer rate: 84.90 kb/s received
+
+ Connection Times (ms)
+ min avg max
+ Connect: 0 0 3
+ Processing: 13 67 71
+ Total: 13 67 74
+</PRE>
<P>
-That's a mandatory warning inside Perl. It happens only if you modify your
-script and Apache::Registry reloads it. Perl is warning you that the
-<CODE>subroutine(s)</CODE> were redefined. It is mostly harmless. If you
-don't like seeing those, just <CODE>kill -USR2</CODE> (graceful restart) apache when you modify your scripts.
+The only numbers we are really care about are:
<P>
-<PRE> <META>
- Someone said:
- You won't see that warning in this case with 5.004_05 or 5.005+.
+<PRE> Complete requests: 100
+ Failed requests: 0
+ Requests per second: 139.86
</PRE>
<P>
-<PRE> I'm running perl5.00502 and I still get these warnings???
-</PRE>
+Lets rise the load of requests to 100 x 10 (10 users each 100 requests
+
<P>
-<PRE> Who is right?
- </META>
+<PRE> % ./ab -n 1000 -c 10 www-pais:81/perl/access/access.cgi
+ Concurrency Level: 10
+ Complete requests: 1000
+ Failed requests: 0
+ Requests per second: 139.76
</PRE>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Global_symbol_foo_requires_ex">Global symbol "$foo" requires explicit package name</A></H1></CENTER>
<P>
-The script below will print a warning like above, moreover it will print
-the whole script as a part of the warning message:
+As expected nothing changes (Since the situation didn't changed, we have
+the same 10 concurrent users). Now lets rise the number of concurrent
+users:
<P>
-<PRE> #!/usr/bin/perl -w
- use strict;
- print "Content-type: text/html\n\n";
- print "Hello $undefined";
+<PRE> % ./ab -n 1000 -c 50 www-pais:81/perl/access/access.cgi
+ Complete requests: 1000
+ Failed requests: 0
+ Requests per second: 133.01
</PRE>
<P>
-The warning:
+We see that the server is capable to serve 50 concurrent users at amazing
+133 req/sec! Lets find the upper bound. Using <CODE>-n 10000 -c
+1000</CODE> failed to get results (Broken Pipe?). Using <CODE>-n 10000 -c
+500</CODE> derived 94.82 req/sec. It went down with the high load.
<P>
-<PRE> Global symbol "$undefined" requires explicit package name at /usr/apps/foo/cgi/tmp.pl line 4.
- eval 'package Apache::ROOT::perl::tmp_2epl;use Apache qw(exit);sub handler {
- #line 1 /usr/apps/foo/cgi/tmp.pl
- BEGIN {$^W = 1;}#!/usr/bin/perl -w
- use strict;
- print "Content-type: text/html\\n\\n";
- print "Hello $undefined";
-
-
- }
- ;' called at /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm line 168
- Apache::Registry::compile('package
- Apache::ROOT::perl::tmp_2epl;use Apache qw(exit);sub han...')
- called at /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm line 121
- Apache::Registry::handler('Apache=SCALAR(0x205026c0)') called at /usr/apps/foo/cgi/tmp.pl line 4
- eval {...} called at /usr/apps/foo/cgi/tmp.pl line 4
- [Sun Nov 15 15:15:30 1998] [error] Undefined subroutine &Apache::ROOT::perl::tmp_2epl::handler called at /
- usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm line 135.
-
- [Sun Nov 15 15:15:30 1998] [error] Goto undefined subroutine &Apache::Constants::SERVER_ERROR at /usr/apps
- /lib/perl5/site_perl/5.005/aix/Apache/Constants.pm line 23.
-</PRE>
-<P>
-The error is simple to fix. When you use the <CODE>use strict;</CODE> pragma (and you should...), all variables should be defined before being
-used.
-
-<P>
-The bad thing is that sometimes the whole script (possibly, thousands of
-lines) is printed to error_log file as a code that the server has tried to <STRONG>eval()</STRONG>uate.
-
-<P>
-As Doug answered to this question:
+This test was performed with the following configuration:
<P>
-<PRE> Looks like you have a $SIG{__DIE__} handler installed (Carp::confess?).
- That's what's expected if so
+<PRE> MinSpareServers 8
+ MaxSpareServers 6
+ StartServers 10
+ MaxClients 50
+ MaxRequestsPerChild 1500
</PRE>
-<P>
-It wasn't in my case, but may be yours
-
<P>
-Bryan Miller said:
+Now let's try this:
<P>
-<PRE> You might wish to try something more terse such as
- "local $SIG{__WARN__} = \&Carp::cluck;" The confess method is _very_
- verbose and will tell you more than you might wish to know including
- full source.
+<PRE> MinSpareServers 8
+ MaxSpareServers 6
+ StartServers 10
+ MaxClients 100
+ MaxRequestsPerChild 1
</PRE>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Can_t_undef_active_subroutine">Can't undef active subroutine</A></H1></CENTER>
-<P>
-<PRE> Can't undef active subroutine at /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm line 102.
- Called from package Apache::Registry, filename /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm, line 102
+<PRE> % ./ab -n 1000 -c 50 www-pais:81/perl/access/access.cgi
</PRE>
<P>
-This problem is caused when, a client drops the connection while httpd is
-in the middle of a write, httpd timeout happens, sending a SIGPIPE, and
-Perl in that child is stuck in the middle of its eval context. This is
-fixed by the Apache::SIG module which is called by default. This should not
-happen unless you have code that is messing with <STRONG>$SIG{PIPE}</STRONG>. It's also triggered only when you've changed your script on disk and
-mod_perl is trying to reload it.
+The benchmark time outed with the above configuration.... I watched the
+output of ps as I run it, the parent process just wasn't capable to respawn
+the killed children in that rate...When I raised the MaxRequestsPerChild to
+10 I've got 8.34 req/sec - very bad (18 times slower!) (You can't benchmark
+the importance of the MinSpareServers, MaxSpareServers and StartServers
+with this kind of test).
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Use_of_uninitialized_value_at_e">Use of uninitialized value at (eval 80) line 12.</A></H1></CENTER>
<P>
-If you compile with the experimental <STRONG>PERL_MARK_WHERE=1</STRONG>, it shows you ``exactly'' where this is happening. many times compiler
-makes a shift for ``unknown'' reasons in its line counter. You can always
-stuff your code with special compiler directives, to reset its counter to
-the value you will tell. At the beginning of the line you should write (the
-'#' in column 1):
+Now let's try to return MaxRequestsPerChild to 1500, but to lower the
+MaxClients to 10 and run the same test:
<P>
-<PRE> #line 298 myscript.pl
+<PRE> MinSpareServers 8
+ MaxSpareServers 6
+ StartServers 10
+ MaxClients 10
+ MaxRequestsPerChild 1500
</PRE>
<P>
-(myscript.pl is optional.) This specifies the line number of the
-<STRONG>following</STRONG> line, not the line the directive is on. You can use a little script to
-stuff every N lines of your code with these directives, but then you will
-have to rerun this script every time you add or remove code lines. The
-script:
+I have got 27.12 req/sec, which is better but still 4-5 times slower (133
+with MaxClients of 50)
-<P>
-<PRE> <META>
- This example was double incrementing $counter.
- I took the second increment out -- sgr.
- </META>
-</PRE>
-<P>
-<PRE> #!/usr/bin/perl
- # Puts Perl line markers in a Perl program for debugging purposes.
- # Also takes out old line markers.
- die "No filename to process.\n" unless @ARGV;
- my $filename = $ARGV[0];
- my $lines = 100;
- open IN, $filename or die "Cannot open file: $filename: $!\n";
- open OUT, ">$filename.marked"
- or die "Cannot open file: $filename.marked: $!\n";
- my $counter = 1;
- while (<IN>) {
- print OUT "# line $counter\n" unless $counter++ % $gap;
- next if $_ =~ /^# line /;
- print OUT $_;
- }
- close OUT;
- close IN;
- chmod 0755, "$filename.marked";
-</PRE>
<P>
-You can also add:
+<STRONG>Summary:</STRONG> I have tested a few combinations of server configuration variables
+(MinSpareServers MaxSpareServers StartServers MaxClients
+MaxRequestsPerChild). And the results we have received are as follows:
<P>
-<PRE> use Carp ();
- local $SIG{__WARN__} = \&Carp::cluck;
-</PRE>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Undefined_subroutine_Apache_RO">Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function called at</A></H1></CENTER>
-<P>
-See <A HREF="././porting.html#Names_collisions_with_Modules_an">Names collisions with Modules and libs</A>
+MinSpareServers, MaxSpareServers and StartServers are only important for
+user respond times (sometimes user will have to wait a bit).
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Can_t_load_auto_DBI_DBI_so_">Can't load '.../auto/DBI/DBI.so' for module DBI</A></H1></CENTER>
<P>
-Check that all your modules are compiled with the same perl that is being
-compiled into mod_perl. perl 5.005 and 5.004 are not binary compatible by
-default.
+The important parameters are MaxClients and MaxRequestsPerChild. MaxClients
+should be not to big so it will not abuse your machine's memory resources
+and not too small, when users will be forced to wait for the children to
+become free to come serve them. MaxRequestsPerChild should be as big as
+possible, to take the full benefit of the mod_perl, but watch your server
+at the beginning to make sure your scripts are not leaking memory causing
+your server (and your service) to die very fast.
<P>
-Other known causes of this problem: OS distributions that ship with a
-(broken) binary Perl installation. The `perl' program and `libperl.a'
-library are somehow built with different binary compatibility flags.
+Also it is important to understand that we didn't test the respond times in
+the tests above, but the ability of the server to respond. If the script
+that was used to test was heavier, the numbers would be different but the
+conclusions are very similar.
<P>
-The solution to these problems is to rebuild Perl and any extension modules
-from a fresh source tree. Tip for running Perl's Configure script: use the
-`-des' flags to accepts defaults and `-D' flag to override certain
-attributes:
+The benchmarks were run at:
<P>
-<PRE> % ./Configure -des -Dcc=gcc ... && make test && make install
-
-Read Perl's INSTALL doc for more details.
+<PRE> HW: RS6000, 1Gb RAM
+ SW: AIX 4.1.5 . mod_perl 1.16, apache 1.3.3
+ Machine running only mysql service, httpd docs and mod_perl servers.
+ Machine was completely unloaded during the benchmarking.
</PRE>
-<P>
-Solaris OS specific:
-
<P>
-Can't load DBI or similar Error for the 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'': -Xlinker --export-dynamic
-or
+After each server restart when I did changes to server's configurations, I
+made sure the scripts were preloaded by fetching a script at least one time
+by each child.
<P>
-<PRE> -Xlinker -E
-</PRE>
-<P>
-This problem is only known to be caused by installing gnu ld under Solaris.
+It is important to notice that None of requests time outed even if was kept
+in server's queue form more than 1 minute! (That is the way <STRONG>ab</STRONG>
+works, which is OK for the test but will not for the real world - user will
+not wait for more than 5-10 secs for a request to complete, and the browser
+will timeout in a 30 secs or so)
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Callback_called_exit">Callback called exit</A></H1></CENTER>
<P>
-See <A HREF="#Out_of_memory_">Out_of_memory!</A>
+Now let me take a real code whose execution time is bigger than a few
+msecs. Will will do real testing and collect the data in tables for easier
+view.
<P>
-I've just discovered that my server is not responding and its error log has
-filled up the remaining space on the file system (about a gig's worth). The
-error_log includes millions of lines:
+I will use the following abbreviations
<P>
-<PRE> Callback called exit at -e line 33, <HTML> chunk 1.
+<PRE> NR = Number of Request Total
+ NC = Number of multiple requests to make
+ MC = MaxClients
+ MRPC = MaxRequestsPerChild
+ RPS = Requests per second
</PRE>
<P>
-Why the looping?
+Running a mod_perl script with lots of mysql queries (script mysqld
+bounded) (http://www:81/perl/access/access.cgi?do_sub=query_form)
<P>
-Perl can get *very* confused inside an endless loop in your code, it
-doesn't mean your code called 'exit', but Perl's malloc went haywire and
-called <CODE>croak(),</CODE> but no memory is left to properly report the
-error, so Perl is stuck in a loop writing that same message to stderr.
-
+<PRE> MinSpareServers 8
+ MaxSpareServers 16
+ StartServers 10
+ MaxClients 50
+ MaxRequestsPerChild 5000
+</PRE>
<P>
-Perl 5.005+ plus is recommended for its improved malloc.c and features
-mentioned in mod_perl_traps.pod on by default.
-
+<PRE> NR NC RPS comment
+ ------------------------------------------------
+ 10 10 3.33 # not a reliable stats
+ 100 10 3.94
+ 1000 10 4.62
+ 1000 50 4.09
+</PRE>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Out_of_memory_">Out of memory!</A></H1></CENTER>
+Conclusions: Here I wanted to show that when the application is slow not
+because of perl loading, script compiling and execution, but bounded to
+some external operation like mysqld querying which made the bottleneck - it
+almost does not matter what is the load we make - the RPS (Requests per
+second) is almost the same (taken that all the requested has been served,
+you have an ability to queue the clients, but be aware that something that
+goes to queue means a waiting client and browser can get time outed!)
+
<P>
-If something goes really wrong with your code, Perl may die with an ``Out
-of memory!'' message and/or ``Callback called exit''. Common causes 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:
+Now we will benchmark the same script without using the mysql (perl only
+bounded) (http://www.you.com:81/perl/access/access.cgi)
<P>
-<PRE> =item -DPERL_EMERGENCY_SBRK
+<PRE> MinSpareServers 8
+ MaxSpareServers 16
+ StartServers 10
+ MaxClients 50
+ MaxRequestsPerChild 5000
</PRE>
<P>
-<PRE> If 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.
+<PRE> NR NC RPS comment
+ ------------------------------------------------
+ 10 10 26.95 # not a reliable stats
+ 100 10 30.88
+ 1000 10 29.31
+ 1000 50 28.01
+ 1000 100 29.74
+ 10000 200 24.92
+ 100000 400 24.95
</PRE>
-<P>
-If you compile with that option and add '<CODE>use Apache::Debug level =&gt;
-4;</CODE>' to your PerlScript, it will allocate the $^M emergency pool and the
-$SIG{__DIE__} handler will call Carp::confess, giving you a stack trace
-which should reveal where the problem is. See the Apache::Resource module
-for prevention of spinning httpds.
-
<P>
+Conclusions: This time the script we executed was a pure perl (not bounded
+to I/O or mysql), so we see that the server serves the requests much
+faster. You can see the RequestPerSecond (RPS) is almost the same for any
+load, but goes lower when the number of concurrent clients goes beyond the
+MaxClients. With 25 RPS, the client in load of 400 concurrent clients will
+be served in 16 secs. But to get more realistic and assume the max
+concurrency of 100, with 30 RPS, the client will be served in 3.5 secs,
+which is pretty good for a highly loaded server.
+
+<P>
+Now we will use the server for its full capacity, by keeping all MaxClients
+alive all the time and having a big MaxRequestsPerChild, so no server will
+be killed during the benchmarking.
+
+<P>
+<PRE> MinSpareServers 50
+ MaxSpareServers 50
+ StartServers 50
+ MaxClients 50
+ MaxRequestsPerChild 5000
+
+ NR NC RPS comment
+ ------------------------------------------------
+ 100 10 32.05
+ 1000 10 33.14
+ 1000 50 33.17
+ 1000 100 31.72
+ 10000 200 31.60
+</PRE>
+<P>
+Conclusion: In this scenario there is no overhead for parent server to load
+new children, all the servers are available, and the only bottleneck is a
+rival over the CPU
+
+<P>
+Now we will try to change the MaxClients and to watch the results: Let's
+reduce MC to 10.
+
+<P>
+<PRE> MinSpareServers 8
+ MaxSpareServers 10
+ StartServers 10
+ MaxClients 10
+ MaxRequestsPerChild 5000
+
+ NR NC RPS comment
+ ------------------------------------------------
+ 10 10 23.87 # not a reliable stats
+ 100 10 32.64
+ 1000 10 32.82
+ 1000 50 30.43
+ 1000 100 25.68
+ 1000 500 26.95
+ 2000 500 32.53
+</PRE>
+<P>
+Conclusions: Very little difference! Almost no change! 10 servers were able
+to serve almost with the same throughput as 50 servers. Why? My guess it's
+because of CPU , Seems that 10 servers were serving 5 times faster the
+requests then when in the test above we worked with 50 servers. In the case
+above each child received its CPU time slice 5 times less frequently. So
+having a big value for MaxClients, doesn't mean that the performance will
+be better. You have just saw the numbers!
+
+<P>
+Now we will start to reduce drastically the MaxRequestsPerClient
+
+<P>
+<PRE> MinSpareServers 8
+ MaxSpareServers 16
+ StartServers 10
+ MaxClients 50
+
+ NR NC MRPC RPS comment
+ ------------------------------------------------
+ 100 10 10 5.77
+ 100 10 5 3.32
+ 1000 50 20 8.92
+ 1000 50 10 5.47
+ 1000 50 5 2.83
+ 1000 100 10 6.51
+</PRE>
+<P>
+Conclusions: When we reduce drastically the MaxRequestsPerClient, the
+performance starts to become closer to the plain mod_cgi. Just for compare
+with mod_cgi, here are the numbers of run with mod_cgi:
+
+<P>
+<PRE> MinSpareServers 8
+ MaxSpareServers 16
+ StartServers 10
+ MaxClients 50
+
+ NR NC RPS comment
+ ------------------------------------------------
+ 100 10 1.12
+ 1000 50 1.14
+ 1000 100 1.13
+</PRE>
+<P>
+Conclusion: mod_cgi is much slower :) in test NReq/NClients 100/10 the RPS
+in mod_cgi 1.12 and in mod_perl 32 => 30 times faster !!! In the first
+test each child waited about 100 secs to be served. In the second and third
+1000 secs!
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Tuning_with_crashme_script">Tuning with crashme script</A></H2></CENTER>
+<P>
+This is another crashme suite originally written by Michael Schilli and
+located at <A
+HREF="http://www.linux-magazin.de/ausgabe.1998.08/Pounder/pounder.html">http://www.linux-magazin.de/ausgabe.1998.08/Pounder/pounder.html</A>
+. I did a few modifications (mostly adding <CODE>my()</CODE> ops :). I also
+allowed it to accept more then one url, since sometimes you want to test
+overall and not just one script.
+
+<P>
+The tool provides the same results as <STRONG>ab</STRONG> above but it also allows you to set the timeout value, so requests will
+fail if not served before time outed. You also get Latency (secs/Request)
+and Throughput (Requests/sec) numbers. It can give you a better picture and
+make a complete simulation of your favorite Netscape browser :)
+
+<P>
+I have noticed while running these 2 benchmarking suites - <STRONG>ab</STRONG> gave me results 2.5-3.0 times better. Both suites run on the same machine
+with the same load with the same parameters. Weird ha? Any ideas why? Again
+C vs Perl question :(
+
+<P>
+Sample output:
+
+<P>
+<PRE> URL(s): <A HREF="http://www.you.com:81/perl/access/access.cgi">http://www.you.com:81/perl/access/access.cgi</A>
+ Total Requests: 100
+ Parallel Agents: 10
+ Succeeded: 100 (100.00%)
+ Errors: NONE
+ Total Time: 9.39 secs
+ Throughput: 10.65 Requests/sec
+ Latency: 0.85 secs/Request
+</PRE>
+<P>
+And the code:
+
+<P>
+<PRE> #!/usr/apps/bin/perl -w
+
+ use LWP::Parallel::UserAgent;
+ use Time::HiRes qw(gettimeofday tv_interval);
+ use strict;
+
+ ###
+ # Configuration
+ ###
+
+ my $nof_parallel_connections = 10;
+ my $nof_requests_total = 100;
+ my $timeout = 10;
+ my @urls = (
+ '<A HREF="http://www.you.com:81/perl/faq_manager/faq_manager.pl">http://www.you.com:81/perl/faq_manager/faq_manager.pl</A>',
+ '<A HREF="http://www.you.com:81/perl/access/access.cgi">http://www.you.com:81/perl/access/access.cgi</A>',
+ );
+
+
+ ##################################################
+ # Derived Class for latency timing
+ ##################################################
+
+ package MyParallelAgent;
+ @MyParallelAgent::ISA = qw(LWP::Parallel::UserAgent);
+ use strict;
+
+ ###
+ # Is called when connection is opened
+ ###
+ sub on_connect {
+ my ($self, $request, $response, $entry) = @_;
+ $self->{__start_times}->{$entry} = [Time::HiRes::gettimeofday];
+ }
+
+ ###
+ # Are called when connection is closed
+ ###
+ sub on_return {
+ my ($self, $request, $response, $entry) = @_;
+ my $start = $self->{__start_times}->{$entry};
+ $self->{__latency_total} += Time::HiRes::tv_interval($start);
+ }
+
+ sub on_failure {
+ on_return(@_); # Same procedure
+ }
+
+ ###
+ # Access function for new instance var
+ ###
+ sub get_latency_total {
+ return shift->{__latency_total};
+ }
+
+ ##################################################
+ package main;
+ ##################################################
+ ###
+ # Init parallel user agent
+ ###
+ my $ua = MyParallelAgent->new();
+ $ua->agent("pounder/1.0");
+ $ua->max_req($nof_parallel_connections);
+ $ua->redirect(0); # No redirects
+
+ ###
+ # Register all requests
+ ###
+ foreach (1..$nof_requests_total) {
+ foreach my $url (@urls) {
+ my $request = HTTP::Request->new('GET', $url);
+ $ua->register($request);
+ }
+ }
+
+ ###
+ # Launch processes and check time
+ ###
+ my $start_time = [gettimeofday];
+ my $results = $ua->wait($timeout);
+ my $total_time = tv_interval($start_time);
+
+ ###
+ # Requests all done, check results
+ ###
+
+ my $succeeded = 0;
+ my %errors = ();
+
+ foreach my $entry (values %$results) {
+ my $response = $entry->response();
+ if($response->is_success()) {
+ $succeeded++; # Another satisfied customer
+ } else {
+ # Error, save the message
+ $response->message("TIMEOUT") unless $response->code();
+ $errors{$response->message}++;
+ }
+ }
+
+ ###
+ # Format errors if any from %errors
+ ###
+ my $errors = join(',', map "$_ ($errors{$_})", keys %errors);
+ $errors = "NONE" unless $errors;
+
+ ###
+ # Format results
+ ###
+
+ #@urls = map {($_,".")} @urls;
+ my @P = (
+ "URL(s)" => join("\n\t\t ", @urls),
+ "Total Requests" => "$nof_requests_total",
+ "Parallel Agents" => $nof_parallel_connections,
+ "Succeeded" => sprintf("$succeeded (%.2f%%)\n",
+ $succeeded * 100 / $nof_requests_total),
+ "Errors" => $errors,
+ "Total Time" => sprintf("%.2f secs\n", $total_time),
+ "Throughput" => sprintf("%.2f Requests/sec\n",
+ $nof_requests_total / $total_time),
+ "Latency" => sprintf("%.2f secs/Request",
+ $ua->get_latency_total() /
+ $nof_requests_total),
+ );
+
+
+ my ($left, $right);
+ ###
+ # Print out statistics
+ ###
+ format STDOUT =
+ @<<<<<<<<<<<<<<< @*
+ "$left:", $right
+ .
+
+ while(($left, $right) = splice(@P, 0, 2)) {
+ write;
+ }
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Choosing_MaxClients">Choosing MaxClients</A></H2></CENTER>
+<P>
+The <CODE>MaxClients</CODE> directive sets the limit on the number of simultaneous requests that can be
+supported; not more than this number of child server processes will be
+created. To configure more than 256 clients, you must edit the
+HARD_SERVER_LIMIT entry in httpd.h and recompile. In our case we want to
+set this variable to as little as possible number, this way we can
+virtually bound the resources used by the server children. If we know that
+we have X Mb of RAM, each child consumes a maximum of Y Mb of RAM (we can
+restrict each child See
+<A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>) and we have the all these X Mb dedicated for the webserver. Then
+calculation of
+<CODE>MaxClients</CODE> is pretty straightforward :
+
+<P>
+<PRE> MaxClients = Total Available to the webserver RAM / MAX child's size
+</PRE>
+<P>
+So If I have 400Mb left for the the webserver to run . I can set the
+<CODE>MaxClients</CODE> to be of 40 if I know that each child is bounded to the 10Mb of memory
+(with Apache::SizeLimit, See the reference above)
+
+<P>
+Certainly you will wander what happens to your server if there are more
+than <CODE>MaxClients</CODE> concurrent users at some moment. This situation is accompanied by the
+following warning message into the <CODE>error.log</CODE>
+file:
+
+<P>
+<PRE> [Sun Jan 24 12:05:32 1999] [error] server reached MaxClients setting,
+ consider raising the MaxClients setting
+</PRE>
+<P>
+No problem - any connection attempts over the <CODE>MaxClients</CODE> limit will normally be queued, up to a number based on the ListenBacklog
+directive. Once a child process is freed at the end of a different request,
+the connection will then be serviced.
+
+<P>
+It <STRONG>is</STRONG> an error because clients are being put in the queue rather than getting
+serviced at once, but they do not get an error response. The error can be
+allowed to persist to balance available system resources and response time,
+but sooner or later you will need to get more RAM so you can start more
+children. The best thing is not to have this condition reached at all.
+
+<P>
+It's important to understand what is child's memory size? If your children
+can share some memory (when OS supports that and you worry to let the
+sharing happen - See <A HREF="././performance.html#Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A>). If this is the case chances that your <CODE>MaxClients</CODE> can be even higher. But seems that it's not so simple to calculate the
+absolute number. (If you come up with solution please let me know)
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Choosing_MaxRequestsPerChild">Choosing MaxRequestsPerChild</A></H2></CENTER>
+<P>
+The <CODE>MaxRequestsPerChild</CODE> directive sets the limit on the number of requests that an individual child
+server process will handle. After
+<CODE>MaxRequestsPerChild</CODE> requests, the child process will die. If
+<CODE>MaxRequestsPerChild</CODE> is 0, then the process will never expire.
+
+<P>
+Setting <CODE>MaxRequestsPerChild</CODE> to a non-zero limit has two beneficial effects: solves memory leakages and
+helps reduce the number of processes when the server load reduces.
+
+<P>
+The first reason is the most crucial for mod_perl, since dirty programming
+will cause a child process to consume more memory after each request. If
+left unbounded after a certain number of requests children will it up all
+the available memory and leave the server to die in memory starvation :).
+Note, that sometimes some standard modules leaks memory, on OSes where
+memory managements is bad (Solaris 2.5 on x86 ?)
+
+<P>
+If this is your case you can set <CODE>MaxRequestsPerChild</CODE> to a small number, which will allow the parent to kill the memory greedy
+son after <CODE>MaxRequestsPerChild</CODE> requests. But then you loose all the speed bonuses you receive with
+mod_perl, and you better fall back to run in plain mod_cgi, since the
+overhead of reloading the script and the perl on each request will be too
+high. Consider using Apache::PerlRun if this is your case. Also setting
+MaxSpareServers to number close to
+<CODE>MaxClients</CODE>, will make the respond time faster (but your parent process will be busy
+to respawn new children all the time!)
+
+<P>
+Another approach is to use Apache::SizeLimit (See <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>). By using this module, you should be able to discontinue using the
+<CODE>MaxRequestsPerChild</CODE>, although for some folks, using both in combination does the job.
+
+<P>
+See also <A HREF="././performance.html#Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A> and
+<A HREF="././performance.html#Memory_sharing">Memory sharing</A>.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Choosing_MinSpareServers_MaxSpa">Choosing MinSpareServers, MaxSpareServers and StartServers</A></H2></CENTER>
+<P>
+With mod_perl it might take up to a 30-50 secs before the new server is
+ready to serve the requests. It depends on OS, number of preloaded modules
+and the load of the machine. So you better set <CODE>StartServers</CODE>
+and <CODE>MinSpareServers</CODE> to a big numbers so if you get a high load after the server has been just
+restarted, the fresh servers will be ready to serve on the first demand.
+It's good for mod_perl to raise all 3 variables up, Since with mod_perl you
+don't want to kill the servers when not in use, on opposite you want them
+to stay up. (For the same reason of the heavy and slow load). I think an
+ideal configuration is with <CODE>MinSpareServers</CODE> and <CODE>MaxSpareServers</CODE> of similar values, even the same. Having the <CODE>MaxSpareServers</CODE> close to
+<CODE>MaxClients</CODE> will use completely all of your resources (if <CODE>MaxClients</CODE>
+has been chosen to take the full advantage of the resources), but it'll
+make sure that in any given moment your system will be capable of
+responding to request with the maximum speed (taken that number of
+concurrent requests is not higher then <CODE>MaxClients</CODE>)
+
+<P>
+Let me try some numbers. For the heavily loaded web site and the dedicated
+machine I would think of (note 400Mb is just for the show case):
+
+<P>
+<PRE> Available to webserver RAM: 400Mb
+ Child's memory size bounded: 10Mb
+ MaxClients: 400/10 = 40
+ StartServers: 20
+ MinSpareServers: 20
+ MaxSpareServers: 35
+</PRE>
+<P>
+However if I want to use the server for many other tasks but make it
+capable of the high load, I'd think of:
+
+<P>
+<PRE> Available to webserver RAM: 400Mb
+ Child's memory size bounded: 10Mb
+ MaxClients: 400/10 = 40
+ StartServers: 5
+ MinSpareServers: 5
+ MaxSpareServers: 10
+</PRE>
+<P>
+(These numbers are taken from the head and it shouldn't be used as rule,
+but to show you some possible scenarios. Use this information wisely!)
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Summary_of_Benchmarking_to_tune_">Summary of Benchmarking to tune all 5 parameters</A></H2></CENTER>
+<P>
+OK, we run various benchmarks and what are the conclusions:
+
+<UL>
+<P><LI><STRONG><A NAME="item_MaxRequestsPerChild">MaxRequestsPerChild</A></STRONG>
+<P>
+If your scripts are clean and don't leak the memory set this variable to a
+number as big as possible (10000?). If you use Apache::SizeLimit, you can
+set this parameter to 0 (equal to infinity).
+
+<P><LI><STRONG><A NAME="item_StartServers">StartServers</A></STRONG>
+<P>
+If you keep a little number of servers most of the time, keep this number
+low. Especially if MaxSpareServers is low and it'll kill the just loaded
+servers before they were utilized at all (if there is no load). If your
+service is heavily loaded make this number close to
+<CODE>MaxClients</CODE> (and keep MaxSpareServers equal to <CODE>MaxClients</CODE> as well)
+
+<P><LI><STRONG><A NAME="item_MinSpareServers">MinSpareServers</A></STRONG>
+<P>
+If your server performs other work except web serving, make it low so the
+memory will be freed when there is no big load. If you server's load is
+like a wave (you get a load in bursts) and you want a fast respond for all
+clients at any time you will want to make it high, so new children will be
+respawned in advance.
+
+<P><LI><STRONG><A NAME="item_MaxSpareServers">MaxSpareServers</A></STRONG>
+<P>
+The logic is the same as of MinSpareServers - low if need the machine for
+other tasks, high if it's web dedicated and you want the minimal delay on
+responses.
+
+<P><LI><STRONG><A NAME="item_MaxClients">MaxClients</A></STRONG>
+<P>
+Not too low, so you don't get a situation where clients are waiting for
+server to start serving them. (they might wait, but not too long). Don't
+make it high, since if you get a high load and all requests will be
+immediately granted your CPU will have a hard times and if child's size *
+number of running children is bigger than the total available RAM, your
+server will start swapping (which will slow down everything, which in turn
+will make things even more slower, until eventually your machine will die).
+It's important that you make sure that no swap will be normally used. Swap
+is an emergency pool, not a resource to be used on the constant basis. If
+you low on memory and you badly need it - buy it, the memory is amazingly
+cheap these days. But based on the test I conducted above, even if you have
+a plenty of memory like I have (1Gb), pulling <CODE>MaxClients</CODE> sometimes will give you no speedup. The more clients are running the more
+CPU will be utilized, the less CPU time slices each process will receive,
+the latency (the to process the request) will grow, so you didn't get an
+improve. The best approach is to find the minimum requirement for your kind
+of service and the maximum capability of your machine, then start at the
+minimum and start testing like I did, by raising this parameter, until you
+find the point where the curve on the latency or throughput graph stops to
+raise or the ramp becomes smaller. Stop there and use it. Of course when
+you use these parameters in production server, you will have the ability to
+tune them more precisely. Also don't forget that if you add more scripts,
+most probably that the parameters need to be recalculated, since the
+processes will grow in size as you compile in more code.
+
+</UL>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Persistent_DB_Connections">Persistent DB Connections</A></H1></CENTER>
+<P>
+Another popular use of mod_perl is to take advantage of it's persistence to
+maintain open database connections. The basic idea goes like so:
+
+<P>
+<PRE> #Apache::Registry script
+ use strict;
+ use vars qw($dbh);
+
+ $dbh ||= SomeDbPackage->connect(...);
+</PRE>
+<P>
+Since <CODE>$dbh</CODE> is a global variable for the child, once the child
+has opened the connection it will use it over and over again, unless you
+perform <CODE>disconnect().</CODE>
+
+<P>
+Be careful to use different names for handlers if you open connection to
+different Databases!
+
+<P>
+Apache::DBI - allows to make a persistent database connection. With this
+module enabled every connect request to plain DBI module will be forwarded
+to the Apache::DBI module. This looks if a database handle from a previous
+connect request is already stored and if this handle is still valid using
+the ping method. If these two conditions are fulfilled it just returns the
+database handle. If there is no appropriate database handle or if the ping
+method fails, a new connection is established and the handle is stored for
+later re-use. <STRONG>There is no need to delete the disconnect statements from
+your code</STRONG>. They would not do anything because the Apache::DBI module overloads the
+disconnect method with a NOP. On child exit there is no explicit
+disconnect, the child dies and so does the database connection.
+
+<P>
+The usage is simple:
+
+<P>
+<PRE> httpd.conf
+ ----------
+ PerlModule Apache::DBI
+</PRE>
+<P>
+It is important, to load this module before any other ApacheDBI module !
+
+<P>
+<PRE> a script.perl
+ ------------
+ use DBI;
+ use strict;
+
+ my $dbh = DBI->connect( 'DBI:mysql:database', 'user', 'password',
+ { autocommit => 0 }
+ ) || die $DBI::errstr;
+
+ ...rest of program
+</PRE>
+<P>
+The module provides the additional method:
+
+<P>
+<PRE> Apache::DBI->connect_on_init($data_source, $username, $auth, \%attr)
+</PRE>
+<P>
+This can be used as a simple way to have apache children establish
+connections on server startup. This call should be in a startup file
+(PerlModule, <Perl> or PerlRequire). It will establish a connection
+when a child is started in that child process. See the Apache::DBI manpage
+to see the requirements for this method.
+
+<P>
+However be warned that some old DBD drivers are not supporting this feature
+(ping method), so check the documentation of the driver you use.
+
+<P>
+Another problem are timeouts: some databases disconnect the client after a
+certain time of inactivity. ping method ensures that this will not happen.
+Some DBD drivers don't have this method, check the Apache::DBI manpage to
+see how to write a ping method.
+
+<P>
+Also some folks at list suggested to change the timeout of the server (they
+talked specifically about mysql). So starting from 3.22.x you can set a
+wait_timeout option at mysqld server startup to change the default value,
+setting it to 24 hours probably will fix the timeout problem.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Using_1_under_mod_perl_and_be">Using $|=1 under mod_perl and better print() techniques.</A></H1></CENTER>
+<P>
+As you know <CODE>$|=1;</CODE> disables the buffering of the currently selected file handle (default is
+STDOUT). If you enable it, <CODE>ap_rflush()</CODE> is being called after
+each <CODE>print()</CODE>, unbuffering Apache's IO.
+
+<P>
+If you are using a _bad_ style of output generating, which consist of
+multiply <CODE>print()</CODE> calls or you just have too many of them, you will experience a degradation
+in performance. The severity depends on the number of the calls.
+
+<P>
+Many old CGIs were written in style of:
+
+<P>
+<PRE> print "<BODY BGCOLOR=\"black\" TEXT=\"white\">";
+ print "<H1>";
+ print "Hello";
+ print "</H1>";
+ print "<A HREF=\"foo.html\"> foo </A>";
+ print "</BODY>";
+</PRE>
+<P>
+which reveals the following drawbacks: multiply <CODE>print()</CODE> calls - performance degradation with $|=1, backslashism which makes the
+code unreadable and difficulty to format the HTML to be easily readable as
+CGI's output. The code below solves them all:
+
+<P>
+<PRE> print qq{
+ <BODY BGCOLOR="black" TEXT="white">
+ <H1>
+ Hello
+ </H1>
+ <A HREF="foo.html"> foo </A>
+ </BODY>
+ };
+</PRE>
+<P>
+I guess you see the difference. Be careful though, when printing the
+<CODE>&lt;HTML&gt;</CODE> tag. The correct way is:
+
+<P>
+<PRE> print qq{<HTML>
+ <HEAD></HEAD>
+ <BODY>
+ }
+</PRE>
+<P>
+If you use the approach bellow:
+
+<P>
+<PRE> print qq{
+ <HTML>
+ <HEAD></HEAD>
+ <BODY>
+ }
+</PRE>
+<P>
+Some older browsers might not accept the output as HTML, and print it as a
+plain text, since they expect the first characters after the headers and
+empty line to be <CODE>&lt;HTML&gt;</CODE> and not spaces and/or additional newline and then <CODE>&lt;HTML&gt;</CODE>. Even if it works in your browser it might not work in other.
+
+<P>
+Now let's go back to the <CODE>$|=1</CODE> topic. I still disable the buffering, for 2 reasons: I use few <CODE>print()</CODE> calls and I want my users to get the output immediately. So if I am about
+to produce the results of the DB query, which might take some time to
+complete, I want user to get some headers which improves the usability of
+my site. Recall yourself - what do you like better: getting the output
+``slowly'' but steadily or having to watch the ``falling stars'' for awhile
+and then getting the whole output at once (if browser did not timeout till
+then).
+
+<P>
+Conclusion: Do not follow blind suggestions but think what is best for you
+in every given case.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Profiling">Profiling</A></H1></CENTER>
+<P>
+Profiling will help you to determine which subroutines are using the most
+time and which subroutines are being called most often, then you will
+probably will want to optimize those, if your code is a way heavy.
+
+<P>
+It is possible to profile code run under mod_perl with the Devel::DProf
+module available on CPAN. However, you must have apache version 1.3b3 or
+higher and the PerlChildExitHandler enabled. When the server is started,
+Devel::DProf installs an END block to write the tmon.out file, which will
+be run when the server is shutdown. Here is how to start and stop a server
+with the profiler enabled:
+
+<P>
+<PRE> % setenv PERL5OPT -d:DProf
+ % httpd -X -d `pwd` &
+ ... make some requests to the server here ...
+ % kill `cat logs/httpd.pid`
+ % unsetenv PERL5OPT
+ % dprofpp
+</PRE>
+<P>
+The Devel::DProf package is a Perl code profiler. This will collect
+information on the execution time of a Perl script and of the subs in that
+script. This information can be used to determine which subroutines are
+using the most time and which subroutines are being called most often.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="CGI_pm_s_object_methods_calls_vs">CGI.pm's object methods calls vs. function calls</A></H1></CENTER>
+<P>
+What approach is better?
+
+<P>
+<PRE> use CGI;
+ my $q = new CGI;
+ print $q->param('x');
+</PRE>
+<P>
+versus
+
+<P>
+<PRE> use CGI (:standard);
+ print param('x');
+</PRE>
+<P>
+There is not any performance benefit of using the object calls rather than
+the function calls, but there is a real memory hit when you import all of
+CGI.pm's function calls into the process memory. This can be significant,
+particularly when there are many child daemons.
+
+<P>
+I strongly endorse <A HREF="././modules.html#Apache_Request_libapreq_Gen">Apache::Request (libapreq) - Generic Apache Request Library</A>. Its guts are all written in C, giving it a significant memory and
+performance benefit.
+
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+
+ <HR>
+ [ <A HREF="porting.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="obvious.html">Next</A> ]
+
+<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
+</TR>
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
+ </FONT>
+ </B>
+ </TD>
+
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
+
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
+</TR>
+</TABLE></CENTER>
+
+</BODY>
+</HTML>
+
+
+<HR SIZE=6>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+ <TITLE>mod_perl guide: Things obvious to others, but not to you</TITLE>
+ <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
+ <META NAME="Author" CONTENT="Bekman Stas">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
+</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
+<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+<A NAME="toc"></A>
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+Things obvious to others, but not to you</H1>
+<HR WIDTH="100%">
+ [ <A HREF="performance.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="warnings.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+<UL>
+
+ <LI><A HREF="#Coverage">Coverage</A>
+ <LI><A HREF="#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>
+ <UL>
+
+ <LI><A HREF="#The_poison">The poison</A>
+ <LI><A HREF="#The_diagnosis">The diagnosis</A>
+ <LI><A HREF="#The_remedy">The remedy</A>
+ </UL>
+
+ <LI><A HREF="#Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A>
+ <UL>
+
+ <LI><A HREF="#Restarting_the_server">Restarting the server</A>
+ <LI><A HREF="#Using_Apache_StatINC">Using Apache::StatINC</A>
+ <LI><A HREF="#Reloading_only_specific_files">Reloading only specific files</A>
+ </UL>
+
+ <LI><A HREF="#Compiled_Regular_Expressions">Compiled Regular Expressions </A>
+ <LI><A HREF="#Debugging_your_code_in_Single_Se">Debugging your code in Single Server Mode</A>
+ <LI><A HREF="#_M_and_other_time_file_tests_u">-M and other time() file tests under mod_perl</A>
+ <LI><A HREF="#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>
+ <LI><A HREF="#Handling_the_server_timeout_case">Handling the server timeout cases</A>
+ <LI><A HREF="#Where_do_the_warnings_errors_go_">Where do the warnings/errors go?</A>
+ <LI><A HREF="#Setting_environment_variables_fo">Setting environment variables for scripts called from CGI.</A>
+</UL>
+<!-- INDEX END -->
+
+<HR>
+
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<P>
+<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
+<P>
+This document describes ``special'' traps you may encounter when running
+your plain CGIs under Apache::Registry and Apache::PerlRun.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A></H1></CENTER>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="The_poison">The poison</A></H2></CENTER>
+<P>
+In a non modperl script (stand alone or CGI), there is no problem writing
+code like this:
+
+<P>
+<PRE> use CGI qw/param/;
+ my $x = param('x');
+ sub printit {
+ print "$x\n";
+ }
+</PRE>
+<P>
+However, the script is run under Apache::Registry, it will in fact be
+repackaged into something like this:
+
+<P>
+<PRE> package $mangled_package_name;
+ sub handler {
+ #line1 $original_filename
+ use CGI qw/param/;
+ my $x = param('x');
+ sub printit {
+ print "$x\n";
+ }
+ }
+</PRE>
+<P>
+Now <CODE>printit</CODE> is an inner named subroutine. Because it is referencing a lexical variable
+from an enclosing scope, a closure is created.
+
+<P>
+The first time the script is run, the correct value of <CODE>$x</CODE> will
+be printed. However on subsequent runs, <CODE>printit</CODE> will retain the initial value of <CODE>$x</CODE> -- not what you want.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="The_diagnosis">The diagnosis</A></H2></CENTER>
+<P>
+Always use -w (or/and PerlWarn ON)! Perl will then emit a warning like:
+
+<P>
+<PRE> Value of $x will not stay shared at - line 5.
+</PRE>
+<P>
+NOTE: Subroutines defined inside <STRONG>BEGIN{}</STRONG> and <STRONG>END{}</STRONG> cannot trigger this message, since each <STRONG>BEGIN{}</STRONG> and <STRONG>END{}</STRONG> is defined to be called exactly once. (To understand why, read about the
+closures at
+<CODE>perlref</CODE> or <CODE>perlfaq</CODE> 13.12)
+
+<P>
+PERLDIAG manpage says:
+
+<P>
+<PRE> An inner (nested) named subroutine is referencing a lexical variable
+ defined in an outer subroutine.
+</PRE>
+<P>
+When the inner subroutine is called, it will probably see the value of the
+outer subroutine's variable as it was before and during the *first* call to
+the outer subroutine; in this case, after the first call to the outer
+subroutine is complete, the inner and outer subroutines will no longer
+share a common value for the variable. In other words, the variable will no
+longer be shared.
+
+<P>
+Check your code by running Apache in single-child mode (httpd -X). Since
+the value of a my variable retain its initial value <CODE>per
+child process</CODE>, the closure problem can be difficult to track down in multi-user mode. It
+will appear to work fine until you have cycled through all the httpd
+children.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="The_remedy">The remedy</A></H2></CENTER>
+<P>
+If a variable needs file scope, use a global variable:
+
+<P>
+<PRE> use vars qw/$x/;
+ use CGI qw/param/;
+ $x = param('x');
+ sub printit {
+ print "$x\n";
+ }
+</PRE>
+<P>
+You can safely use a <CODE>my()</CODE> scoped variable if its value is constant:
+
+<P>
+<PRE> use vars qw/$x/;
+ use CGI qw/param/;
+ $x = param('x');
+ my $y = 5;
+ sub printit {
+ print "$x, $y\n";
+ }
+</PRE>
+<P>
+Also see the clarification of <CODE>my()</CODE> vs. <CODE>use vars</CODE> - Ken Williams writes:
+
+<P>
+<PRE> Yes, there is quite a bit of difference! With use vars(), you are
+ making an entry in the symbol table, and you are telling the
+ compiler that you are going to be referencing that entry without an
+ explicit package name.
+
+ With my(), NO ENTRY IS PUT IN THE SYMBOL TABLE. The compiler
+ figures out _at_ _compile_time_ which my() variables (i.e. lexical
+ variables) are the same as each other, and once you hit execute time
+ you can not go looking those variables up in the symbol table.
+</PRE>
+<P>
+And <CODE>my()</CODE> vs. <CODE>local()</CODE> - Randal Schwartz writes:
+
+<P>
+<PRE> local() creates a temporal-limited package-based scalar, array,
+ hash, or glob -- when the scope of definition is exited at runtime,
+ the previous value (if any) is restored. References to such a
+ variable are *also* global... only the value changes. (Aside: that
+ is what causes variable suicide. :)
+
+ my() creates a lexically-limited non-package-based scalar, array, or
+ hash -- when the scope of definition is exited at compile-time, the
+ variable ceases to be accessible. Any references to such a variable
+ at runtime turn into unique anonymous variables on each scope exit.
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A></H1></CENTER>
+<P>
+When you develop plain CGI scripts, you can just change the code, and rerun
+the CGI from your browser. Since the script isn't cached in memory, the
+next time you call it the server starts up a new perl process, which
+recompiles it from scratch. The effects of any modifications you've applied
+are immediately present.
+
+<P>
+The situation is different with Apache::Registry, since the whole idea is
+to get maximum performance from the server. By default, the server won't
+spend the time to check whether any included library modules have been
+changed. It assumes that they weren't, thus saving a few milliseconds to <CODE>stat()</CODE> the source file (multiplied by however many modules/libraries you are
+<STRONG>use</STRONG>/<STRONG>require</STRONG>-ing in your script.) The only check that is being done is whether your
+main script has been changed. So if you have only one script that doesn't <STRONG>use</STRONG> (or <STRONG>require</STRONG>) other perl modules (or packages), there is nothing new about it. If
+however, you are developing a script that includes other modules, the files
+you <STRONG>use()</STRONG> or <STRONG>require()</STRONG> aren't being checked to see if they have been modified.
+
+<P>
+Acknowledging this, how do we get our modperl-enabled server to recognize
+changes in any library modules? Well, there are a couple of techniques:
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Restarting_the_server">Restarting the server</A></H2></CENTER>
+<P>
+See <A HREF="././control.html#Restarting_techniques">Server Restarting techniques</A>.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Using_Apache_StatINC">Using Apache::StatINC</A></H2></CENTER>
+<P>
+After restarting the server about 100 times, you will be tired and will
+look for another solutions. Help comes from the Apache::StatINC module.
+
+<P>
+Read its pod pages, but beware of the following note: Only the modules
+located in <STRONG>@INC</STRONG> are being reloaded on change, and you can change the <STRONG>@INC</STRONG> only before the server has been started. Whatever you do in your
+scripts/modules which are being <CODE>required()</CODE> after the server
+startup will not have any effect on <STRONG>@INC</STRONG>.
+
+<P>
+When you do <STRONG>use lib qw(foo/bar);</STRONG>, the <STRONG>@INC</STRONG> is being changed only for the time the code is being parsed. When it's over
+the <STRONG>@INC</STRONG> is being reset to its original value. To make sure that you have set a
+correct <STRONG>@INC</STRONG> fetch <A
+HREF="http://your.perl.server/perl-status?inc">http://your.perl.server/perl-status?inc</A>
+and watch the bottom of the page. (I assume you have configured the
+<Location /perl-status> section in httpd.conf as the mod_perl docs
+show.)
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Reloading_only_specific_files">Reloading only specific files</A></H2></CENTER>
+<P>
+Checking all the Modules in <STRONG>%INC</STRONG> can add some (large?) overhead to server response times, and you certainly
+wouldn't want Apache::StatINC module to be enabled in your production
+site's configuration. But sometimes you want to have some Configuration
+file (module) be reloaded without restarting the whole server. For this you
+will have to add something like this in your code:
+
+<P>
+Assume that you started your scripts with:
+
+<P>
+<PRE> use lib "/some/private/path";
+ use Foo::Bar qw(:subs);
+</PRE>
+<P>
+Now to make a modification test and reload at runtime you have to use
+something like this:
+
+<P>
+<PRE> # child's global variable to keep the timestamps
+ use vars qw(%MODIFIED);
+
+ my $my_lib_root = "/some/private/path";
+ my $conf = "Foo/Bar.pm";
+ my $conf_path = "$my_lib_root/$conf";
+
+ # set modification time if it wasn't set before
+ # Note: Use (stat $conf_path)[9] instead of -M test, if you reset
+ # time with $^M=time
+ $MODIFIED{$conf} ||= -M $conf_path;
+
+ # now check whether it was changed (assuming the above wasn't
+ # performed in this session
+ if ($MODIFIED{$conf} != -M $conf_path){
+ # only if deleted from %INC the require will be called below
+ delete $INC{$conf};
+
+ # this should be safe since @INC is being reset after we leave
+ # the script, or you can skip this stage and require the script
+ # with full path, remember that @INC now is different from the
+ # one you have had when the script has been called at first time
+ unshift @INC,$my_lib_root;
+
+ # reread the file : use() wouldn't work here since it's compile time directive
+ require Foo::Bar;
+
+ # now export the symbols (if you need them back :)
+ import Foo::Bar qw(:subs);
+
+ # Update the MODIFICATION times
+ $MODIFIED{$conf} = -M $conf_path;
+ }
+</PRE>
+<P>
+You may want to add debug print statements to test this code in your
+application.
+
+<P>
+Read the ``use versus require'' article for more info.
+(http://www.perl.com/CPAN-local/doc/FMTEYEWTK/use_vs_require)
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Compiled_Regular_Expressions">Compiled Regular Expressions</A></H1></CENTER>
+<P>
+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 execution of the program, a standard optimization technique
+consists of adding the <STRONG>/o</STRONG> modifier to the regexp pattern. This directs the compiler to build the
+internal table once, for the entire lifetime of the script, rather than
+every time the pattern is executed. Consider:
+
+<P>
+<PRE> my $pat = '^foo$'; # likely to be input from an HTML form field
+ foreach( @list ) {
+ print if /$pat/o;
+ }
+</PRE>
+<P>
+This is usually a big win in loops over lists, or when using
+<STRONG>grep</STRONG> or <STRONG>map</STRONG>.
+
+<P>
+In long-lived mod_perl scripts, however, this can pose a problem if the
+variable changes according to the invocation. The first invocation of a
+fresh httpd child will compile the regex and perform the search correctly.
+However, all subsequent uses by the httpd child will continue to match the
+original pattern, regardless of the current contents of the Perl variables
+the pattern is dependent on. Your script will appear broken.
+
+<P>
+There are two solutions to this problem.
+
+<P>
+The first is to use <STRONG>eval q//</STRONG>, to force the code to be evaluated each time. Just make sure that the eval
+block covers the entire loop of processing, and not just the pattern match
+itself.
+
+<P>
+The above code fragment would be rewritten as:
+
+<P>
+<PRE> my $pat = '^foo$';
+ eval q{
+ foreach( @list ) {
+ print if /$pat/o;
+ }
+ }
+</PRE>
+<P>
+Just saying:
+
+<P>
+<PRE> eval q{ print if /$pat/o; };
+</PRE>
+<P>
+is going to be a horribly expensive proposition.
+
+<P>
+You can use this approach if you require more than one pattern match
+operator in a given section of code. If the section contains only one
+operator (be it an <STRONG>m//</STRONG> or <STRONG>s///</STRONG>), you can rely on the property of the null pattern, that reuses the last
+pattern seen. This leads to the second solution, which also eliminates the
+use of eval.
+
+<P>
+The above code fragment becomes:
+
+<P>
+<PRE> my $pat = '^foo$';
+ "something" =~ /$pat/; # dummy match (MUST NOT FAIL!)
+ foreach( @list ) {
+ print if //;
+ }
+</PRE>
+<P>
+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 <STRONG>//</STRONG> will match everything. If you can't count on fixed text to ensure the match
+succeeds, you have two possibilities.
+
+<P>
+If you can guarantee that the pattern variable contains no meta-characters
+(things like *, +, ^, $...), you can use the dummy match:
+
+<P>
+<PRE> "$pat" =~ /\Q$pat\E/; # guaranteed if no meta-characters present
+</PRE>
+<P>
+If there is a possibility that the pattern can contain meta-characters, you
+should search for the pattern or the unsearchable \377 character as
+follows:
+
+<P>
+<PRE> "\377" =~ /$pat|^[\377]$/; # guaranteed if meta-characters present
+</PRE>
+<P>
+Phil. Chu contributed this:
+
+<P>
+It depends on the complexity of the regexp you apply this technique to. One
+common usage where compiled regexp is usually more efficient is to ``match
+any one of a group of patterns'' over and over again.
+
+<P>
+Maybe with some helper routine, it's easier to remember. Here is one
+slightly modified from Jeffery Friedl's example in his book ``Mastering
+Regex.''. I find it quite useful:
+
+<P>
+<PRE> #####################################################
+ # Build_MatchMany_Function
+ # -- Input: list of patterns
+ # -- Output: A code ref which matches its $_[0]
+ # against ANY of the patterns given in the
+ # "Input", efficiently.
+ #
+ sub Build_MatchMany_Function {
+ my @R = @_;
+ my $expr = join '||', map { "\$_[0] =~ m/\$R[$_]/o" } ( 0..$#R );
+ my $matchsub = eval "sub { $expr }";
+ die "Failed in building regex @R: $@" if $@;
+ $matchsub;
+ }
+</PRE>
+<P>
+Example usage:
+
+<P>
+<PRE> @some_browsers = qw(Mozilla Lynx MSIE AmigaVoyager lwp libwww);
+ $Known_Browser=Build_MatchMany_Function(@some_browsers);
+</PRE>
+<P>
+<PRE> while (<ACCESS_LOG>) {
+ # ...
+ $browser = get_browser_field($_);
+ if ( ! &$Known_Browser($browser) ) {
+ print STDERR "Unknown Browser: $browser\n";
+ }
+ # ...
+ }
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Debugging_your_code_in_Single_Se">Debugging your code in Single Server Mode</A></H1></CENTER>
+<P>
+Running in httpd -X mode. (good only for testing during development phase).
+
+<P>
+You want to test that your application correctly handles global variables
+(if you have any - the less you have of them the better, but sometimes you
+just can't without them). It's hard to test with multiple servers serving
+your cgi since each child has a different value for its global variables.
+Imagine that you have a <CODE>random()</CODE> sub that returns a random
+number and you have the following script.
+
+<P>
+<PRE> use vars qw($num);
+ $num ||= random();
+ print ++$num;
+</PRE>
+<P>
+This script initializes the variable <STRONG>$num</STRONG> with a random value, then increments it on each request and prints it out.
+Running this script in multiple server environments will result in
+something like 1,9,4,19 (number per reload), since each time your script
+will be served by a different child. (On some OSes, the parent httpd
+process will assign all of the requests to the same child process if all of
+the children are idle... AIX...). But if you run in httpd -X single server
+mode you will get 2,3,4,5... (taken that the <CODE>random()</CODE> returned
+1 at the first call)
+
+<P>
+But do not get too obsessive with this mode, since working only in single
+server mode sometimes hides problems that show up when you switch to multi
+server mode. Consider an application that allows you to change the
+configuration at run time.
+
+<P>
+Let's say the script produces a form to change the background color of the
+page. It's not a good design, but for the sake of demonstrating the
+potential problem, we will assume that our script doesn't write the changed
+background color to the disk, but simply changes it in memory.
+
+<P>
+So you have typed in a new color, and in response, your script prints back
+the html with a new color - you think that's it! It was so simple. And if
+you keep running in single server mode you will never notice that you have
+a problem...
+
+<P>
+If you run the same code in the multi server environment, after you submit
+the color change you will get the result as expected, but when you will
+call the same URL again (not reload!) chances are that you will get back
+the old color, since except the child who processed the color change
+request no one knows about their global variable change. Just remember that
+children can't share information, other than that which they inherited from
+their parent on their load.
+
+<P>
+Also note that since the server is running in single mode, if the output
+returns HTML with IMG tags, then the load of these will take a lot of time
+(read apache docs of httpd -X to learn why).
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="_M_and_other_time_file_tests_u">-M and other time() file tests under mod_perl</A></H1></CENTER>
+<P>
+Under mod_perl, files that have been created after the server's (child?)
+startup are being reported with negative age with -M (-C -A) test. This is
+obvious if you remember that you will get the negative result if the server
+was started before the file was created and it's a normal behavior with any
+perl.
+
+<P>
+If you want to have -M test to count the time relative to the current
+request, you should reset the $^T variable as with any other perl script.
+Just add <CODE>$^T = time;</CODE> at the beginning of the scripts.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A></H1></CENTER>
+<P>
+When a user presses the stop button, Apache will detect that via
+SIG{'PIPE'} and will cease the script execution. When we are talking about
+mod_cgi, there is generally no problem, since all opened files will be
+closed and all the resources will be freed (almost all -- if you happened
+to use external lock files, most likely the resources that are being locked
+by these will be left blocked and non-usable by any others who use this
+advisory locking scheme.)
+
+<P>
+Important to notice that when the user hits ``stop'' on the browser, the
+mod_perl script is blissfully unaware until it tries to send some data to
+the browser. At that point, Apache realizes that the browser is gone, and
+all the good cleanup stuff happens.
+
+<P>
+Starting from apache 1.3.6 apache will not catch SIGPIPE anymore and
+modperl will do it much better. Here is something from CHANGES from Apache
+1.3.6.
+
+<P>
+<PRE> *) SIGPIPE is now ignored by the server core. The request write
+ routines (ap_rputc, ap_rputs, ap_rvputs, ap_rwrite, ap_rprintf,
+ ap_rflush) now correctly check for output errors and mark the
+ connection as aborted.
+ Replaced many direct (unchecked) calls to ap_b* routines with the
+ analogous ap_r* calls. [Roy Fielding]
+</PRE>
+<P>
+What happens if your mod_perl script has some global variables, that are
+being used for resource locking?
+
+<P>
+It's possible not to notice the pitfall if the critical code section
+between lock and unlock is very short and finishes fast, so you never see
+this happens (you aren't fast enough to stop the code in the middle). But
+look at the following scenario:
+
+<P>
+<PRE> 1. lock resource
+ <b><critical section starts>
+ 2. sleep 20 (== do some time consuming processing)
+ <critical section ends></b>
+ 3. unlock resource
+</PRE>
+<P>
+If user presses 'Stop' and Apache sends SIGPIPE before step 3, since we are
+in the mod_perl mode and we want the lock variable to be cached, it will be
+not unlocked. A kind of ``deadlock'' exists.
+
+<P>
+Here is the working example. Run the server with -X, Press 'Stop' before
+the count-up to 10 has been finished. Then rerun the script, it'll hang in
+<CODE>while(1)!</CODE> The resource is not available anymore.
+
+<P>
+<PRE> -------------------------------------------------------------
+ use vars qw(%CACHE);
+ use CGI;
+ $|=1;
+ my $q = new CGI;
+ print $q->header,$q->start_html;
+
+ print $q->p("$$ Going to lock!\n");
+
+ # actually the while loop below is not needed
+ # (since it's an internal lock and accessible only
+ # by the same process and it if it's locked... it's locked for the
+ # whole child's life
+ while (1) {
+ unless (defined $CACHE{LOCK} and $CACHE{LOCK} == 1) {
+ $CACHE{LOCK} = 1;
+ print $q->p("Got the lock!\n");
+ last;
+ }
+ }
+ print $q->p("Going to sleep (I mean working)!");
+ my $c=0;
+ foreach (1..10) {
+ sleep 1;
+ print $c++,"\n<BR>";
+ }
+
+ print $q->p("Going to unlock!");
+ $CACHE{LOCK} = 0;
+ print $q->p("Unlock!\n");
+ -------------------------------------------------------------
+</PRE>
+<P>
+You may ask, what is the solution for this problem? As noted in the
+<A HREF="././porting.html#END_blocks">END blocks</A> any END blocks that are encountered during compilation of Apache::Registry
+scripts are called after the script done is running, including subsequent
+invocations when the script is cached in memory. So if you are running in
+Apache::Registry mode, the following is your remedy:
+
+<P>
+<PRE> END {
+ $CACHE{LOCK} = 0;
+ }
+</PRE>
+<P>
+Notice that the END block will be run after the Apache::Registry::handler
+is finished (not during the cleanup phase though).
+
+<P>
+If you are into a perl API, use the <STRONG>register_cleanup()</STRONG> method of Apache.
+
+<P>
+<PRE> $r->register_cleanup(sub {$CACHE{LOCK} = 0;});
+</PRE>
+<P>
+If you are into Apache API <CODE>Apache-</CODE>request->connection->aborted()> construct can be used to test for
+the aborted connection.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Handling_the_server_timeout_case">Handling the server timeout cases</A></H1></CENTER>
+<P>
+A similar situation to <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Pressed Stop button disease</A> happens when client (browser) timeouts the connection (is it about 2
+minutes?) . There are cases when your script is about to perform a very
+long operation and there is a chance that its duration will be longer than
+the client's timeout. One case I can think about is the DataBase
+interaction, where the DB engine hangs or needs a lot of time to return
+results. If this is the case, use <CODE>$SIG{ALRM}</CODE> to prevent the timeouts:
+
+<P>
+<PRE> eval {
+ local $SIG{ALRM} = sub { die "timeout\n" };
+ alarm $timeout;
+ ... db stuff ...
+ alarm 0;
+ };
+
+ die $@ if $@;
+</PRE>
+<P>
+But, as lately it was discovered <CODE>local $SIG{'ALRM'}</CODE> does not restore the original underlying C handler. Look at <CODE>Sys::Signal</CODE>
+module, which should solve this problem.
+
+<P>
+<CODE>Sys::Signal</CODE> - Set signal handlers with restoration of existing C sighandler
+
+<P>
+Now use this code:
+
+<P>
+<PRE> use Sys::Signal ();
+ eval {
+ my $h = Sys::Signal->set(ALRM => sub { die "timeout\n" });
+ alarm $timeout;
+ ... do something thay may timeout ...
+ alarm 0;
+ };
+ die $@ if $@;
+</PRE>
+<P>
+As of this writing it is still not entered CPAN and you can find it at <A
+HREF="http://www.modperl.com/~dougm/perl/Sys-Signal-0.01.tar.gz">http://www.modperl.com/~dougm/perl/Sys-Signal-0.01.tar.gz</A>
+. (But check the CPAN for the latest version anyway)
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Where_do_the_warnings_errors_go_">Where do the warnings/errors go?</A></H1></CENTER>
+<P>
+Your CGI does not work and you want to see what the problem is. The best
+idea is to check out any errors that the server may be reporting. Where I
+can find these errors?
+
+<P>
+Generally all errors are logged into an error_log file. The exact file
+location and name are defined in the http.conf file. Look for the <CODE>ErrorLog</CODE> parameter. My httpd.conf says:
+
+<P>
+<PRE> ErrorLog var/logs/error_log
+</PRE>
+<P>
+Hey, where is the beginning of the path? There is another Apache parameter
+called <CODE>ServerRoot</CODE>. Every time apache sees a value of the parameter with no absolute path
+(e.g <CODE>/tmp/my.txt</CODE>) but with relative path (e.g <CODE>my.txt</CODE>) it prepends the value of the <CODE>ServerRoot</CODE> to this value. I have:
+
+<P>
+<PRE> ServerRoot /usr/local/apache
+</PRE>
+<P>
+So I will look for error_log file at
+<CODE>/usr/local/apache/var/logs/error_log</CODE>. Of course you can also use an absolute path to define the file's location
+at the file system.
+
+<P>
+<META>: is this 100% correct?
+
+<P>
+But there are cases when errors don't go to the error_log file. For example
+some errors are being printed to the console (tty) you have executed the
+httpd from (unless you redirected the httpd's stderr flow). This happens
+when the server didn't open the error_log file for writing yet.
+
+<P>
+For example, if you have mistakenly entered a non-existent directory path
+in your <STRONG>ErrorLog</STRONG> directive, the error message will be printed on the controlling tty. Or, if
+the error happens when server executes PerlRequire or PerlModule directive
+you might see the errors here also.
+
+<P>
+You are probably wonder where all the errors go when you are running the
+server in single mode (httpd -X). They go to the console. That is because
+when running in the single mode there is no parent httpd process to perform
+all the logging. It includes all the status messages that generally show up
+in the error_log file.
+
+<P>
+</META>
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Setting_environment_variables_fo">Setting environment variables for scripts called from CGI.</A></H1></CENTER>
+<P>
+Perl uses <CODE>sh()</CODE> for its iteractions for <CODE>system()</CODE> and <CODE>open()</CODE>
+calls. So when you want to set a temporary variable when you call a script
+from your CGI you do:
+
+<P>
+<PRE> open UTIL, "USER=stas ; script.pl | " or die "...: $!\n";
+</PRE>
+<P>
+or
+
+<P>
+<PRE> system "USER=stas ; script.pl";
+</PRE>
+<P>
+This is useful for example if you need to invoke a script that uses CGI.pm
+from within a mod_perl script. We are tricking the perl script to think
+it's a simple CGI, which is not running under mod_perl.
+
+<P>
+<PRE> open(PUBLISH, "GATEWAY_INTERFACE=CGI/1.1 ; script.cgi
+ \"param1=value1&param2=value2\" |") or die "...: $!\n";
+</PRE>
+<P>
+Make sure, that the parameters you pass are shell safe (All ``unsafe''
+characters like single-tick should be properly escaped).
+
+<P>
+However you are fork-ing to run a Perl script, so you have thrown the so
+hardly gained performance out the window. Whatever script.cgi is now, it
+should be moved to a module with a subroutine you can call directly from
+your script, to avoid the fork.
+
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+
+ <HR>
+ [ <A HREF="performance.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="warnings.html">Next</A> ]
+
+<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
+</TR>
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
+ </FONT>
+ </B>
+ </TD>
+
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
+
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
+</TR>
+</TABLE></CENTER>
+
+</BODY>
+</HTML>
+
+
+<HR SIZE=6>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+ <TITLE>mod_perl guide: Warnings and Errors: Where and Why.</TITLE>
+ <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
+ <META NAME="Author" CONTENT="Bekman Stas">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
+</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
+<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+<A NAME="toc"></A>
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+Warnings and Errors: Where and Why.</H1>
+<HR WIDTH="100%">
+ [ <A HREF="obvious.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="databases.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+<UL>
+
+ <LI><A HREF="#General_Advice">General Advice </A>
+ <LI><A HREF="#Incorrect_line_number_reporting_">Incorrect line number reporting in error/warn log messages</A>
+ <LI><A HREF="#Value_of_x_will_not_stay_shared">Value of $x will not stay shared at - line 5</A>
+ <LI><A HREF="#Value_of_x_may_be_unavailable_a">Value of $x may be unavailable at - line 5.</A>
+ <LI><A HREF="#mod_perl_rwrite_returned_1">mod_perl: rwrite returned -1</A>
+ <LI><A HREF="#caught_SIGPIPE_in_process">caught SIGPIPE in process</A>
+ <LI><A HREF="#Client_hit_STOP_or_Netscape_bit_">Client hit STOP or Netscape bit it!</A>
+ <LI><A HREF="#Constant_subroutine_redefine">Constant subroutine ... redefined</A>
+ <LI><A HREF="#Global_symbol_foo_requires_ex">Global symbol "$foo" requires explicit package name</A>
+ <LI><A HREF="#Can_t_undef_active_subroutine">Can't undef active subroutine</A>
+ <LI><A HREF="#Use_of_uninitialized_value_at_e">Use of uninitialized value at (eval 80) line 12.</A>
+ <LI><A HREF="#Undefined_subroutine_Apache_RO">Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function called at</A>
+ <LI><A HREF="#Can_t_load_auto_DBI_DBI_so_">Can't load '.../auto/DBI/DBI.so' for module DBI</A>
+ <LI><A HREF="#Callback_called_exit">Callback called exit</A>
+ <LI><A HREF="#Out_of_memory_">Out of memory!</A>
+ <LI><A HREF="#_warn_child_process_30388_did_n">[warn] child process 30388 did not exit, sending another SIGHUP</A>
+ <LI><A HREF="#RegistryLoader_Cannot_translate">RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl</A>
+ <LI><A HREF="#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>
+ <LI><A HREF="#server_reached_MaxClients_settin">server reached MaxClients setting, consider raising the MaxClients setting</A>
+</UL>
+<!-- INDEX END -->
+
+<HR>
+
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<P>
+<CENTER><H1><A NAME="General_Advice">General Advice</A></H1></CENTER>
+<P>
+Enabling <CODE>use diagnostics;</CODE> generally helps you to determine the source of the problem and how to solve
+it. See <A HREF="././porting.html#diagnostics_pragma">diagnostics pragma</A> for more info.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Incorrect_line_number_reporting_">Incorrect line number reporting in error/warn log messages</A></H1></CENTER>
+<P>
+See <A HREF="././warnings.html#Use_of_uninitialized_value_at_e">Use of uninitialized value at (eval 80) line 12.</A>
+=head1 Incorrect line number reporting in error/warn log messages
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Value_of_x_will_not_stay_shared">Value of $x will not stay shared at - line 5</A></H1></CENTER>
+<P>
+<A HREF="././obvious.html#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Value_of_x_may_be_unavailable_a">Value of $x may be unavailable at - line 5.</A></H1></CENTER>
+<P>
+<A HREF="././obvious.html#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="mod_perl_rwrite_returned_1">mod_perl: rwrite returned -1</A></H1></CENTER>
+<P>
+That message happens when the client breaks the connection while your
+script is trying to write to the client. With Apache 1.3.x, you should only
+see the rwrite messages if LogLevel is set to debug.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="caught_SIGPIPE_in_process">caught SIGPIPE in process</A></H1></CENTER>
+<P>
+<PRE> [modperl] caught SIGPIPE in process 1234
+ [modperl] process 1234 going to Apache::exit with status...
+</PRE>
+<P>
+That's the <STRONG>$SIG{PIPE}</STRONG> handler installed by mod_perl/Apache::SIG, called if a connection timesout
+or Client presses the 'Stop' button. It gives you an opportunity to do
+cleanups if the script was aborted in the middle of its execution. See <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A> for more info.
+
+<P>
+If your mod_perl version < 1.17 you might get the message in the
+following section...
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Client_hit_STOP_or_Netscape_bit_">Client hit STOP or Netscape bit it!</A></H1></CENTER>
+<P>
+<PRE> Client hit STOP or Netscape bit it!
+ Process 2493 going to Apache::exit with status=-2
+</PRE>
+<P>
+You will see this message in mod_perl < 1.17. See <A HREF="././warnings.html#caught_SIGPIPE_in_process">caught SIGPIPE in process</A>.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Constant_subroutine_redefine">Constant subroutine ... redefined</A></H1></CENTER>
+<P>
+That's a mandatory warning inside Perl. It happens only if you modify your
+script and Apache::Registry reloads it. Perl is warning you that the
+<CODE>subroutine(s)</CODE> were redefined. It is mostly harmless. If you
+don't like seeing those, just <CODE>kill -USR2</CODE> (graceful restart) apache when you modify your scripts.
+
+<P>
+<PRE> <META>
+ Someone said:
+ You won't see that warning in this case with 5.004_05 or 5.005+.
+</PRE>
+<P>
+<PRE> I'm running perl5.00502 and I still get these warnings???
+</PRE>
+<P>
+<PRE> Who is right?
+ </META>
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Global_symbol_foo_requires_ex">Global symbol "$foo" requires explicit package name</A></H1></CENTER>
+<P>
+The script below will print a warning like above, moreover it will print
+the whole script as a part of the warning message:
+
+<P>
+<PRE> #!/usr/bin/perl -w
+ use strict;
+ print "Content-type: text/html\n\n";
+ print "Hello $undefined";
+</PRE>
+<P>
+The warning:
+
+<P>
+<PRE> Global symbol "$undefined" requires explicit package name at /usr/apps/foo/cgi/tmp.pl line 4.
+ eval 'package Apache::ROOT::perl::tmp_2epl;use Apache qw(exit);sub handler {
+ #line 1 /usr/apps/foo/cgi/tmp.pl
+ BEGIN {$^W = 1;}#!/usr/bin/perl -w
+ use strict;
+ print "Content-type: text/html\\n\\n";
+ print "Hello $undefined";
+
+
+ }
+ ;' called at /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm line 168
+ Apache::Registry::compile('package
+ Apache::ROOT::perl::tmp_2epl;use Apache qw(exit);sub han...')
+ called at /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm line 121
+ Apache::Registry::handler('Apache=SCALAR(0x205026c0)') called at /usr/apps/foo/cgi/tmp.pl line 4
+ eval {...} called at /usr/apps/foo/cgi/tmp.pl line 4
+ [Sun Nov 15 15:15:30 1998] [error] Undefined subroutine &Apache::ROOT::perl::tmp_2epl::handler called at /
+ usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm line 135.
+
+ [Sun Nov 15 15:15:30 1998] [error] Goto undefined subroutine &Apache::Constants::SERVER_ERROR at /usr/apps
+ /lib/perl5/site_perl/5.005/aix/Apache/Constants.pm line 23.
+</PRE>
+<P>
+The error is simple to fix. When you use the <CODE>use strict;</CODE> pragma (and you should...), all variables should be defined before being
+used.
+
+<P>
+The bad thing is that sometimes the whole script (possibly, thousands of
+lines) is printed to error_log file as a code that the server has tried to <STRONG>eval()</STRONG>uate.
+
+<P>
+As Doug answered to this question:
+
+<P>
+<PRE> Looks like you have a $SIG{__DIE__} handler installed (Carp::confess?).
+ That's what's expected if so
+</PRE>
+<P>
+It wasn't in my case, but may be yours
+
+<P>
+Bryan Miller said:
+
+<P>
+<PRE> You might wish to try something more terse such as
+ "local $SIG{__WARN__} = \&Carp::cluck;" The confess method is _very_
+ verbose and will tell you more than you might wish to know including
+ full source.
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Can_t_undef_active_subroutine">Can't undef active subroutine</A></H1></CENTER>
+<P>
+<PRE> Can't undef active subroutine at /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm line 102.
+ Called from package Apache::Registry, filename /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm, line 102
+</PRE>
+<P>
+This problem is caused when, a client drops the connection while httpd is
+in the middle of a write, httpd timeout happens, sending a SIGPIPE, and
+Perl in that child is stuck in the middle of its eval context. This is
+fixed by the Apache::SIG module which is called by default. This should not
+happen unless you have code that is messing with <STRONG>$SIG{PIPE}</STRONG>. It's also triggered only when you've changed your script on disk and
+mod_perl is trying to reload it.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Use_of_uninitialized_value_at_e">Use of uninitialized value at (eval 80) line 12.</A></H1></CENTER>
+<P>
+Your code includes some undefined variable that you have used as if it was
+already defined and initialized. For example:
+
+<P>
+<PRE> $param = $q->param('test');
+ print $param;
+</PRE>
+<P>
+<PRE> vs.
+</PRE>
+<P>
+<PRE> $param = $q->param('test') || '';
+ print $param;
+</PRE>
+<P>
+In the second case, <CODE>$param</CODE> will always be <CODE>defined</CODE>, either
+<CODE>$q-&gt;param('test')</CODE> returns some value or <CODE>undef</CODE>.
+
+<P>
+Also read about <A HREF="././porting.html#Finding_the_line_number_the_erro">finding the line number the error/warning has been triggered at</A>.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Undefined_subroutine_Apache_RO">Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function called at</A></H1></CENTER>
+<P>
+See <A HREF="././porting.html#Name_collisions_with_Modules_and">Names collisions with Modules and libs</A>.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Can_t_load_auto_DBI_DBI_so_">Can't load '.../auto/DBI/DBI.so' for module DBI</A></H1></CENTER>
+<P>
+Check that all your modules are compiled with the same perl that is being
+compiled into mod_perl. perl 5.005 and 5.004 are not binary compatible by
+default.
+
+<P>
+Other known causes of this problem: OS distributions that ship with a
+(broken) binary Perl installation. The `perl' program and `libperl.a'
+library are somehow built with different binary compatibility flags.
+
+<P>
+The solution to these problems is to rebuild Perl and any extension modules
+from a fresh source tree. Tip for running Perl's Configure script: use the
+`-des' flags to accepts defaults and `-D' flag to override certain
+attributes:
+
+<P>
+<PRE> % ./Configure -des -Dcc=gcc ... && make test && make install
+
+Read Perl's INSTALL doc for more details.
+</PRE>
+<P>
+Solaris OS specific:
+
+<P>
+Can't load DBI or similar Error for the 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'': -Xlinker --export-dynamic
+or
+
+<P>
+<PRE> -Xlinker -E
+</PRE>
+<P>
+This problem is only known to be caused by installing gnu ld under Solaris.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Callback_called_exit">Callback called exit</A></H1></CENTER>
+<P>
+See <A HREF="#Out_of_memory_">Out_of_memory!</A>
+
+
+
+<P>
+I've just discovered that my server is not responding and its error log has
+filled up the remaining space on the file system (about a gig's worth). The
+error_log includes millions of lines:
+
+<P>
+<PRE> Callback called exit at -e line 33, <HTML> chunk 1.
+</PRE>
+<P>
+Why the looping?
+
+<P>
+Perl can get *very* confused inside an endless loop in your code, it
+doesn't mean your code called 'exit', but Perl's malloc went haywire and
+called <CODE>croak(),</CODE> but no memory is left to properly report the
+error, so Perl is stuck in a loop writing that same message to stderr.
+
+<P>
+Perl 5.005+ plus is recommended for its improved malloc.c and features
+mentioned in mod_perl_traps.pod on by default.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Out_of_memory_">Out of memory!</A></H1></CENTER>
+<P>
+If something goes really wrong with your code, Perl may die with an ``Out
+of memory!'' message and/or ``Callback called exit''. Common causes 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:
+
+<P>
+<PRE> =item -DPERL_EMERGENCY_SBRK
+</PRE>
+<P>
+<PRE> If 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.
+</PRE>
+<P>
+If you compile with that option and add '<CODE>use Apache::Debug level =&gt;
+4;</CODE>' to your PerlScript, it will allocate the $^M emergency pool and the
+$SIG{__DIE__} handler will call Carp::confess, giving you a stack trace
+which should reveal where the problem is. See the Apache::Resource module
+for prevention of spinning httpds.
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="_warn_child_process_30388_did_n">[warn] child process 30388 did not exit, sending another SIGHUP</A></H1></CENTER>
<P>
@@ -6699,7 +8652,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="obvious.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="databases.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -6711,8 +8665,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
@@ -6739,11 +8693,14 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: Performance. Benchmarks.</TITLE>
+ <TITLE>mod_perl guide: mod_perl and Relational Databases</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -6751,1606 +8708,2831 @@
<!--
@import url(style.css);
-->
-
- </style>
-<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
-<H1 ALIGN=CENTER>
-<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
-<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Performance. Benchmarks.</H1>
-<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
-<UL>
-
- <LI><A HREF="#Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A>
- <UL>
-
- <LI><A HREF="#Preload_Perl_modules_Real_Numb">Preload Perl modules - Real Numbers</A>
- </UL>
-
- <LI><A HREF="#Preopen_DB_connection_at_server_">Preopen DB connection at server startup</A>
- <LI><A HREF="#Memory_sharing">Memory sharing</A>
- <LI><A HREF="#Preload_Registry_Scripts">Preload Registry Scripts</A>
- <LI><A HREF="#Avoid_Importing_Functions">Avoid Importing Functions</A>
- <LI><A HREF="#Reducing_the_Memory_Usage">Reducing the Memory Usage</A>
- <LI><A HREF="#how_can_I_find_if_my_modperl_scr">how can I find if my modperl scripts have memory leaks (and where)</A>
- <LI><A HREF="#Limiting_the_size_of_the_process">Limiting the size of the processes</A>
- <LI><A HREF="#Limiting_the_resources_used_by_h">Limiting the resources used by httpd children</A>
- <LI><A HREF="#Limiting_the_request_rate_speed_">Limiting the request rate speed (robots blocking)</A>
- <LI><A HREF="#Benchmarks_Impressing_your_Boss">Benchmarks. Impressing your Boss and Colleagues.</A>
- <UL>
-
- <LI><A HREF="#Developers_Talk">Developers Talk</A>
- <LI><A HREF="#Benchmarking_a_Graphic_hits_coun">Benchmarking a Graphic hits counter with Persistent DB Connection</A>
- <LI><A HREF="#Benchmarking_scripts_with_execut">Benchmarking scripts with execution times below 1 second :)</A>
- <LI><A HREF="#PerlHandler_s_Benchmarking">PerlHandler's Benchmarking</A>
- </UL>
-
- <LI><A HREF="#Tuning_the_Apache_s_configuratio">Tuning the Apache's configuration variables for the best performance</A>
- <UL>
-
- <LI><A HREF="#Tuning_with_ab_ApacheBench">Tuning with ab - ApacheBench </A>
- <LI><A HREF="#Tuning_with_crashme_script">Tuning with crashme script</A>
- <LI><A HREF="#Choosing_MaxClients">Choosing MaxClients</A>
- <LI><A HREF="#Choosing_MaxRequestsPerChild">Choosing MaxRequestsPerChild</A>
- <LI><A HREF="#Choosing_MinSpareServers_MaxSpa">Choosing MinSpareServers, MaxSpareServers and StartServers</A>
- <LI><A HREF="#Summary_of_Benchmarking_to_tune_">Summary of Benchmarking to tune all 5 parameters</A>
- </UL>
-
- <LI><A HREF="#Persistent_DB_Connections">Persistent DB Connections</A>
- <LI><A HREF="#Why_you_should_not_use_1_unde">Why you should not use $|=1 under mod_perl</A>
- <LI><A HREF="#Profiling">Profiling</A>
-</UL>
-<!-- INDEX END -->
-
- <P><A HREF="index.html">[Back to the main index]</A></P>
-
- The <a href="http://www.modperl.com/">
- <B>Writing Apache Modules with Perl and C</B></a>
- book can be purchased online from <a
- href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
- and <a
- href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
- Amazon.com</a>.
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<P>
-<CENTER><H1><A NAME="Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A></H1></CENTER>
-<P>
-Use the PerlRequire and PerlModule directives to load commonly used modules
-such as CGI.pm, DBI, etc., when the server is started. On most systems,
-server children will be able to share this space.
-
-<P>
-You can also put the standard <CODE>use Foo;</CODE> into the startup-file.
-
-<P>
-CGI.pm is a special one. Ordinarily CGI.pm autoloads most of its functions
-on an as-needed basis. This speeds up the loading time by deferring the
-compilation phase. However, if you are using mod_perl, FastCGI or another
-system that uses a persistent Perl interpreter, you will want to precompile
-the methods at initialization time. To accomplish this, call the package
-function <CODE>compile()</CODE> like this:
-
-<P>
-<PRE> use CGI ();
- CGI->compile(':all');
-</PRE>
-<P>
-The arguments to <CODE>compile()</CODE> are a list of method names or sets, and are identical to those accepted by
-the use operator.
-
-<P>
-You can also preload the Registry scripts. See <A HREF="#Preload_Registry_Scripts">Preload Registry Scripts</A>.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Preload_Perl_modules_Real_Numb">Preload Perl modules - Real Numbers</A></H2></CENTER>
-<P>
-I have conducted a few tests to benchmark the memory usage when some
-modules are preloaded. First set of tests checks the memory use with
-Library Perl Module preload (only CGI.pm). The second set checks the
-compile method of CGI.pm. The third test checks benefit the the Library
-Perl Module preload but a few of them (too see more memory saved) and also
-the effect of precompiling the Registry modules with
-Apache::RegistryLoader.
-
-<P>
-Summary:
+
+ </style>
+<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+<A NAME="toc"></A>
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+mod_perl and Relational Databases</H1>
+<HR WIDTH="100%">
+ [ <A HREF="warnings.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="dbm.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+<UL>
-<P>
-1. Library Perl Modules Preloading gave a good results everywhere.
+ <LI><A HREF="#Why_Relational_SQL_Databases">Why Relational (SQL) Databases</A>
+ <LI><A HREF="#Apache_DBI_Initiate_a_persist">Apache::DBI - Initiate a persistent database connection</A>
+ <UL>
-<P>
-2. compile method of CGI seems to make things worse (may be the speed is
-better?)
+ <LI><A HREF="#Introduction">Introduction</A>
+ <LI><A HREF="#Configuration">Configuration</A>
+ <LI><A HREF="#Preopening_DBI_connections">Preopening DBI connections</A>
+ <LI><A HREF="#Debugging_Apache_DBI">Debugging Apache::DBI</A>
+ <LI><A HREF="#Problems_and_solutions">Problems and solutions</A>
+ <UL>
-<P>
-3. Apache::RegistryLoader might made the script load faster on the first
-request after the child has just started but the memory usage was worse!!!
-See the numbers by yourself.
+ <LI><A HREF="#The_morning_bug">The morning bug</A>
+ <LI><A HREF="#Cannot_find_the_DBI_handler">Cannot find the DBI handler</A>
+ <LI><A HREF="#Apache_DBI_does_not_work">Apache:DBI does not work</A>
+ </UL>
-<P>
-HW/SW: The server is apache 1.3.2, mod_perl 1.16 running on AIX 4.1.5
+ <LI><A HREF="#Some_useful_code_snippets_to_be_">Some useful code snippets to be used with relational Databases</A>
+ <UL>
-<P>
---------------------------------------------------------------------------------
+ <LI><A HREF="#Turning_the_SQL_queries_writing_">Turning the SQL queries writing into an short and simple task</A>
+ <LI><A HREF="#My_DB_module">My::DB module</A>
+ <LI><A HREF="#My_DB_Module_s_Usage_Examples">My::DB Module's Usage Examples</A>
+ </UL>
-<P>
-1. In the first test was used a script:
+ </UL>
-<P>
-<PRE> use strict;
- use CGI ();
- my $q = new CGI;
- print $q->header;
- print $q->start_html,$q->p("Hello");
-</PRE>
-<P>
-<Server restarted>
+</UL>
+<!-- INDEX END -->
-<P>
-Before the CGI.pm preload: (No other modules preloaded)
+<HR>
-<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 87004 0.0 0.0 1060 1524 - A 16:51:14 0:00 httpd
- httpd 240864 0.0 0.0 1304 1784 - A 16:51:13 0:00 httpd
-</PRE>
-<P>
-After running a script which uses CGI's methods (no imports):
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
-<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 188068 0.0 0.0 1052 1524 - A 17:04:16 0:00 httpd
- httpd 86952 0.0 1.0 2520 3052 - A 17:04:16 0:00 httpd
-</PRE>
-<P>
-Observation: child httpd has grown up by 1268K
+ <HR>
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<Server restarted>
-
+<CENTER><H1><A NAME="Why_Relational_SQL_Databases">Why Relational (SQL) Databases</A></H1></CENTER>
<P>
-After the CGI.pm preload:
+Nowadays millions of users surf the Internet. There are millions of
+Terabytes of data laying around. To manipulate that data new smart
+techniques and technologies were invented. One of the major inventions was
+a relational database, which allows to search and modify huge data storages
+in zero time. It uses <STRONG>SQL</STRONG> (Structured Query Language) to manipulate contents of these databases. Of
+course once we started to use the web, we have found a need to write web
+interfaces to these databases and CGI was and is the mostly used technology
+for building such interfaces. The main limitation for a CGI script driving
+a database versus application, is its statelessness - on every request the
+CGI script has to initiate a connection to the database, when the request
+is completed the connection is lost. <CODE>Apache::DBI</CODE> was written to remove this limitation. When you use it, you have a
+persistent database connection over the process' life. As you understand
+this possible only with CGI running under mod_perl enabled server, since
+the child process does not quit when the request has been served. So when a
+mod_perl script needs to _talk_ to a database, he starts _talking_ right
+away, without initiating a database connection first, <CODE>Apache::DBI</CODE> worries to provide a valid connection immediately. Of course the are more
+nuances, which will be talked about in the following sections.
<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 240796 0.0 0.0 1456 1552 - A 16:55:30 0:00 httpd
- httpd 86944 0.0 0.0 1688 1800 - A 16:55:30 0:00 httpd
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Apache_DBI_Initiate_a_persist">Apache::DBI - Initiate a persistent database connection</A></H1></CENTER>
<P>
-after running a script which uses CGI's methods (no imports):
+This module initiates a persistent database connection. It is possible only
+with mod_perl.
<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 86872 0.0 0.0 1448 1552 - A 17:02:56 0:00 httpd
- httpd 187996 0.0 1.0 2808 2968 - A 17:02:56 0:00 httpd
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Introduction">Introduction</A></H2></CENTER>
<P>
-Observation: child httpd has grown up by 1168K, 100K less then without
-preload - good!
+When loading the DBI module (do not confuse this with the Apache::DBI
+module) it looks if the environment variable GATEWAY_INTERFACE starts with
+'CGI-Perl' and if the module Apache::DBI has been loaded. In this case
+every connect request will be forwarded to the Apache::DBI module. This
+looks if a database handle from a previous connect request is already
+stored and if this handle is still valid using the ping method. If these
+two conditions are fulfilled it just returns the database handle. If there
+is no appropriate database handle or if the ping method fails, a new
+connection is established and the handle is stored for later re-use. In
+other words when the script is run again from a child that has already (and
+is still) connected, the host/username/password is checked against the
+cache of open connections, and if one is available, uses that one. There is
+no need to delete the disconnect statements from your code. They won't do
+anything because the Apache::DBI module overloads the disconnect method
+with a NOP (like an empty call).
<P>
-<Server restarted>
+You want to use this module if you are opening a <STRONG>few</STRONG> DB connections to the server. <CODE>Apache::DBI</CODE> will make them persistent per child, so if you have 10 children and each
+opens 2 different connections you will have in total 20 opened persistent
+connections. Thus after initial connect you will save up the connection
+time for every connect request from your DBI module. Which is a huge
+benefit for the mod_perl apache server with high traffic of users deploying
+the relational DB.
<P>
-After CGI.pm preloaded and compiled with CGI->compile(':all');
+As you understand you must NOT use this module if you are opening a special
+connection for each of your users, since each of them will stay persistent
+and in a short time the number of connections will be so big that your
+machine will scream and die. If you want to use
+<CODE>Apache::DBI</CODE> in both situations, as of this moment the only available solution is to run
+2 mod_perl servers, one using
+<CODE>Apache::DBI</CODE> and one not.
<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 86980 0.0 0.0 2836 1524 - A 17:05:27 0:00 httpd
- httpd 188104 0.0 0.0 3064 1768 - A 17:05:27 0:00 httpd
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Configuration">Configuration</A></H2></CENTER>
<P>
-After running a script which uses CGI's methods (no imports):
+After installing this module, the configuration is simple - add to the
+<CODE>httpd.conf</CODE> the following directive.
<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 86980 0.0 0.0 2828 1524 - A 17:05:27 0:00 httpd
- httpd 188104 0.0 1.0 4188 2940 - A 17:05:27 0:00 httpd
+<PRE> PerlModule Apache::DBI
</PRE>
<P>
-Observation: child httpd has grown up by 1172K No change! So what does
-CGI->compile(':all') helps? I guess it helps if you import the symbols
-(subs) rather you use the methods
+Note that it is important, to load this module before any other ApacheDBI
+module !
<P>
---------------------------------------------------------------------------------
+You can skip preloading <CODE>DBI</CODE>, since <CODE>Apache::DBI</CODE> does that. But there is no harm if you leave it in.
<P>
-2. I have tried the second test to find it. I run the script:
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Preopening_DBI_connections">Preopening DBI connections</A></H2></CENTER>
<P>
-use strict; use CGI <CODE>qw(:all);</CODE> print
-header,start_html,p(``Hello'');
+If you want that when you call the script after server restart, the
+connection will be already preopened, you should use
+<CODE>connect_on_init()</CODE> method in the startup file to preload every connection you are going to
+use. For example:
<P>
-<Server restarted>
-
+<PRE> Apache::DBI->connect_on_init
+ ("DBI:mysql:myDB::myserver",
+ "username",
+ "passwd",
+ {
+ PrintError => 1, # warn() on errors
+ RaiseError => 0, # don't die on error
+ AutoCommit => 1, # commit executes immediately
+ }
+ );
+</PRE>
<P>
-After CGI.pm preloaded and NOT compiled with CGI->compile(':all');
+As noted before, it is wise to you this method only if you only want all of
+apache to be able to connect to the database server as one user (or few
+users).
<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 17268 0.0 0.0 1456 1552 - A 18:02:49 0:00 httpd
- httpd 86904 0.0 0.0 1688 1800 - A 18:02:49 0:00 httpd
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Debugging_Apache_DBI">Debugging Apache::DBI</A></H2></CENTER>
<P>
-After running a script which imports symbols, all of them
+If you are not sure this module is working as advertised, you should enable
+the Debug mode in the startup script by:
<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 17268 0.0 0.0 1448 1552 - A 18:02:49 0:00 httpd
- httpd 86904 0.0 1.0 2952 3112 - A 18:02:49 0:00 httpd
+<PRE> $Apache::DBI::DEBUG = 1;
</PRE>
<P>
-Observation: child httpd has grown up by 1264K
+Since now on you will see in the <CODE>error.log</CODE> file when Apache::DBI initializes a connection and when it just returns it
+from its cache. Use the following command to see it in the real time (your
+<CODE>error.log</CODE> file might be locate at a different path):
<P>
-<Server restarted>
-
+<PRE> tail -f /usr/local/apache/logs/error_log
+</PRE>
<P>
-After CGI.pm preloaded and compiled with CGI->compile(':all');
+I use <CODE>alias</CODE> (in <CODE>tcsh</CODE>) so I will not have to remember the path:
<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 86812 0.0 0.0 2836 1524 - A 17:59:52 0:00 httpd
- httpd 99104 0.0 0.0 3064 1768 - A 17:59:52 0:00 httpd
+<PRE> alias err "tail -f /usr/local/apache/logs/error_log"
</PRE>
<P>
-After running a script which imports symbols, all of them
+Another approach is to add to <CODE>httpd.conf</CODE> (which does the same):
<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 86812 0.0 0.0 2832 1436 - A 17:59:52 0:00 httpd
- httpd 99104 0.0 1.0 4884 3636 - A 17:59:52 0:00 httpd
+<PRE> PerlModule Apache::DebugDBI
</PRE>
<P>
-Observation: child httpd has grown up by 1868K. Why? Isn't
-CGI->compile(':all') supposed to make children to share the compiled
-code with parent?
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Problems_and_solutions">Problems and solutions</A></H2></CENTER>
<P>
---------------------------------------------------------------------------------
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H3><A NAME="The_morning_bug">The morning bug</A></H3></CENTER>
<P>
-3. The third script
+SQL server keeps the connection to the client open for a limited period of
+time. So many developers were bitten by so called <STRONG>Morning
+bug</STRONG> when every morning the first users to use the site were receiving:
+<CODE>No Data Returned</CODE> message, but then everything worked as usual. The error caused by <CODE>Apache::DBI</CODE> returning a handle of the invalid connection (server closed it because of
+timeout), and the script was dying on that error. The infamous and well
+documented in the man page,
+<CODE>ping()</CODE> method was introduced to solve this problem. But seems that people are
+still being beaten by this problem. Another solution was found - to rise
+the timeout parameter at the SQL server startup. Currently I startup <CODE>mySQL</CODE> server with <CODE>safe_mysql</CODE>
+script, so I have updated it to use this option:
<P>
-<PRE> use strict;
- use CGI;
- use Data::Dumper;
- use Storable;
- [and many lines of code, lots of globals - so the code is huge!]
+<PRE> nohup $ledir/mysqld [snipped other options] -O wait_timeout=172800
</PRE>
-<P>
-<Server restarted>
-
<P>
-Nothing preloaded at startup
+Where 172800 secs equal to 48 hours. And it works.
<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 90962 0.0 0.0 1060 1524 - A 17:16:45 0:00 httpd
- httpd 86870 0.0 0.0 1304 1784 - A 17:16:45 0:00 httpd
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H3><A NAME="Cannot_find_the_DBI_handler">Cannot find the DBI handler</A></H3></CENTER>
<P>
-Script using CGI (methods), Storable, Data::Dumper called
+Q: I cannot find the handler name with which to manipulate my connection;
+hence I seem to be unable to do anything to my database.
-<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 90962 0.0 0.0 1064 1436 - A 17:16:45 0:00 httpd
- httpd 86870 0.0 1.0 4024 4548 - A 17:16:45 0:00 httpd
-</PRE>
<P>
-Observation: child httpd has grown up by 2764K
+A: You did not use <CODE>DBI::connect()</CODE> as with usual DBI usage to get your <CODE>$dbh</CODE> database handler.
+Using the <CODE>Apache::DBI</CODE> does not eliminate the need to write a proper <CODE>DBI</CODE> code. As the man page states - you should program as if you did not use <CODE>Apache::DBI</CODE> at all. <CODE>Apache::DBI</CODE> will override and return you a cached connection. And in case of <CODE>disconnect()</CODE> call it will be just ignored.
<P>
-<Server restarted>
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H3><A NAME="Apache_DBI_does_not_work">Apache:DBI does not work</A></H3></CENTER>
<P>
-Preloaded CGI (compiled), Storable, Data::Dumper at startup
+Make sure you have it installed.
<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 26792 0.0 0.0 3120 1528 - A 17:19:21 0:00 httpd
- httpd 91052 0.0 0.0 3340 1764 - A 17:19:21 0:00 httpd
-</PRE>
+Make sure you configured mod_perl with EVERYTHING=1.
+
<P>
-Script using CGI (methods), Storable, Data::Dumper called
+Use the example script eg/startup.pl (remove the comment from the line
<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 26792 0.0 0.0 3124 1440 - A 17:19:21 0:00 httpd
- httpd 91052 0.0 1.0 6568 5040 - A 17:19:21 0:00 httpd
+<PRE> #use Apache::DebugDBI;
</PRE>
<P>
-Observation: child httpd has grown up by 3276K. Great different: 512K
-less!!!
+and adapt the connect string. Do not change anything in your scripts, for
+using Apache::DBI.
<P>
-<Server restarted>
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Some_useful_code_snippets_to_be_">Some useful code snippets to be used with relational Databases</A></H2></CENTER>
<P>
-All the above modules + the above script PreCompiled with
-Apache::RegistryLoader at startup
+In this section you will find scripts, modules and code snippets to help
+get yourself started to use relational Databases with mod_perl scripts.
+Note that I work with <CODE>mysql</CODE> ( <A HREF="http://www.mysql.com">http://www.mysql.com</A> ), so the code
+you will find will work out of box with mysql, if you use some other SQL
+engine, it might work for you as well, or some changes should be applied.
<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 43224 0.0 0.0 3256 1528 - A 17:23:12 0:00 httpd
- httpd 26844 0.0 0.0 3488 1776 - A 17:23:12 0:00 httpd
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H3><A NAME="Turning_the_SQL_queries_writing_">Turning the SQL queries writing into an short and simple task</A></H3></CENTER>
<P>
-Script using CGI (methods), Storable, Data::Dumper called
+Having to write many queries in my CGI scripts, made me to write a stand
+alone module that saves me a lot of time in writing and debugging my code.
+It also makes my scripts are much smaller and easier to read. I will
+present the module here, afterwards examples will follow:
-<P>
-<PRE> USER PID %CPU %MEM SZ RSS TTY STAT STIME TIME COMMAND
- root 43224 0.0 0.0 3252 1440 - A 17:23:12 0:00 httpd
- httpd 26844 0.0 1.0 6748 5092 - A 17:23:12 0:00 httpd
-</PRE>
<P>
-Observation: child httpd has grown even more 3316K ! Does not seem to be
-good!
+Notice the <CODE>DESTROY</CODE> block at the end of the module, which makes various cleanups and allows
+this module to be used under <CODE>mod_cgi</CODE> as well.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Preopen_DB_connection_at_server_">Preopen DB connection at server startup</A></H1></CENTER>
+<CENTER><H3><A NAME="My_DB_module">My::DB module</A></H3></CENTER>
<P>
-If you use DBI for DB connections, you can preopen a connections to DB for
-each child with Apache::DBI.
+(note that you will not find it on CPAN)
<P>
-<PRE> use Apache::DBI ();
- Apache::DBI->connect_on_init("DBI:mysql:test", 'login','passwd',
+<PRE> package My::DB;
+
+ use strict;
+ use 5.004;
+
+ use DBI;
+
+ use vars qw(%c);
+
+ %c =
+ (
+ # DB debug
+ #db_debug => 1,
+ db_debug => 0,
+
+ db => {
+ DB_NAME => 'foo',
+ SERVER => 'localhost',
+ USER => 'put_username_here',
+ USER_PASSWD => 'put_passwd_here',
+ },
+
+ );
+
+ use Carp qw(croak verbose);
+ #local $SIG{__WARN__} = \&Carp::cluck;
+
+ # untaint the path by explicit setting
+ local $ENV{PATH} = '/bin:/usr/bin';
+
+ #######
+ sub new {
+ my $proto = shift;
+ my $class = ref($proto) || $proto;
+ my $self = {};
+
+ # connect to the DB, Apache::DBI worries to cache the connections
+ # save into a dbh - Database handle object
+ $self->{dbh} = DBI->connect("DBI:mysql:$c{db}{DB_NAME}::$c{db}{SERVER}",
+ $c{db}{USER},
+ $c{db}{USER_PASSWD},
{
- RaiseError => 1,
- PrintError => 1,
- AutoCommit => 1,
- };
+ PrintError => 1, # warn() on errors
+ RaiseError => 0, # don't die on error
+ AutoCommit => 1, # commit executes immediately
+ }
+ )
+ or DBI->disconnect("Cannot connect to database: $DBI::errstr\n");
+
+ # we want to die on errors if in debug mode
+ $self->{dbh}->{RaiseError} = 1 if $c{'db_debug'};
+
+ # init the sth - Statement handle object
+ $self->{sth} = '';
+
+ bless ($self, $class);
+
+ $self;
+
+ } # end of sub new
+
+
+
+ ######################################################################
+ ###################################
+ ### ###
+ ### SQL Functions ###
+ ### ###
+ ###################################
+ ######################################################################
+
+ # print debug messages
+ sub d{
+ # we want to print in debug mode the trace
+ print "<DT><B>".join("<BR>", @_)."</B>\n" if $c{'db_debug'};
+
+ } # end of sub d
+
+
+ ######################################################################
+ # return a count of matched rows, by conditions
+ #
+ # $count = sql_count_matched($table_name,\@conditions);
+ #
+ # conditions must be an array so we can path more than one column with
+ # the same name.
+ #
+ # @conditions = ( column => ['comp_sign','value'],
+ # foo => ['>',15],
+ # foo => ['<',30],
+ # );
+ #
+ # The sub knows automatically to detect and quote strings
+ #
+ ##########################
+ sub sql_count_matched{
+ my $self = shift;
+ my $table = shift || '';
+ my $r_conds = shift || [];
+
+ # we want to print in debug mode the trace
+ d( "[".(caller(2))[3]." - ".(caller(1))[3]." - ". (caller(0))[3]."]");
+
+ # build the query
+ my $do_sql = "SELECT COUNT(*) FROM $table ";
+ my @where = ();
+ for(my $i=0;$i<@{$r_conds};$i=$i+2) {
+ push @where, join " ",
+ $$r_conds[$i],
+ $$r_conds[$i+1][0],
+ sql_quote(sql_escape($$r_conds[$i+1][1]));
+ }
+ # Add the where clause if we have one
+ $do_sql .= "WHERE ". join " AND ", @where if @where;
+
+ d("SQL: $do_sql");
+
+ # do query
+ $self->{sth} = $self->{dbh}->prepare($do_sql);
+ $self->{sth}->execute();
+ my ($count) = $self->{sth}->fetchrow_array;
+
+ d("Result: $count");
+
+ $self->{sth}->finish;
+
+ return $count;
+
+ } # end of sub sql_count_matched
+
+
+
+ ######################################################################
+ # return a single (first) matched value or undef, by conditions and
+ # restrictions
+ #
+ # sql_get_matched_value($table_name,$column,\@conditions,\@restrictions);
+ #
+ # column is a name of the column
+ #
+ # conditions must be an array so we can path more than one column with
+ # the same name.
+ # @conditions = ( column => ['comp_sign','value'],
+ # foo => ['>',15],
+ # foo => ['<',30],
+ # );
+ # The sub knows automatically to detect and quote strings
+ #
+ # restrictions is a list of restrictions like ('order by email')
+ #
+ ##########################
+ sub sql_get_matched_value{
+ my $self = shift;
+ my $table = shift || '';
+ my $column = shift || '';
+ my $r_conds = shift || [];
+ my $r_restr = shift || [];
+
+ # we want to print in debug mode the trace
+ d( "[".(caller(2))[3]." - ".(caller(1))[3]." - ". (caller(0))[3]."]");
+
+ # build the query
+ my $do_sql = "SELECT $column FROM $table ";
+
+ my @where = ();
+ for(my $i=0;$i<@{$r_conds};$i=$i+2) {
+ push @where, join " ",
+ $$r_conds[$i],
+ $$r_conds[$i+1][0],
+ sql_quote(sql_escape($$r_conds[$i+1][1]));
+ }
+ # Add the where clause if we have one
+ $do_sql .= " WHERE ". join " AND ", @where if @where;
+
+ # restrictions (DONT put commas!)
+ $do_sql .= " ". join " ", @{$r_restr} if @{$r_restr};
+
+ d("SQL: $do_sql");
+
+ # do query
+ return $self->{dbh}->selectrow_array($do_sql);
+
+ } # end of sub sql_get_matched_value
+
+
+
+
+ ######################################################################
+ # return a single row of first matched rows, by conditions and
+ # restrictions. The row is being inserted into @results_row array
+ # (value1,value2,...) or empty () if non matched
+ #
+ # sql_get_matched_row(\@results_row,$table_name,\@columns,\@conditions,\@restrictions);
+ #
+ # columns is a list of columns to be returned (username, fname,...)
+ #
+ # conditions must be an array so we can path more than one column with
+ # the same name.
+ # @conditions = ( column => ['comp_sign','value'],
+ # foo => ['>',15],
+ # foo => ['<',30],
+ # );
+ # The sub knows automatically to detect and quote strings
+ #
+ # restrictions is a list of restrictions like ('order by email')
+ #
+ ##########################
+ sub sql_get_matched_row{
+ my $self = shift;
+ my $r_row = shift || {};
+ my $table = shift || '';
+ my $r_cols = shift || [];
+ my $r_conds = shift || [];
+ my $r_restr = shift || [];
+
+ # we want to print in debug mode the trace
+ d( "[".(caller(2))[3]." - ".(caller(1))[3]." - ". (caller(0))[3]."]");
+
+ # build the query
+ my $do_sql = "SELECT ";
+ $do_sql .= join ",", @{$r_cols} if @{$r_cols};
+ $do_sql .= " FROM $table ";
+
+ my @where = ();
+ for(my $i=0;$i<@{$r_conds};$i=$i+2) {
+ push @where, join " ",
+ $$r_conds[$i],
+ $$r_conds[$i+1][0],
+ sql_quote(sql_escape($$r_conds[$i+1][1]));
+ }
+ # Add the where clause if we have one
+ $do_sql .= " WHERE ". join " AND ", @where if @where;
+
+ # restrictions (DONT put commas!)
+ $do_sql .= " ". join " ", @{$r_restr} if @{$r_restr};
+
+ d("SQL: $do_sql");
+
+ # do query
+ @{$r_row} = $self->{dbh}->selectrow_array($do_sql);
+
+ } # end of sub sql_get_matched_row
+
+
+
+ ######################################################################
+ # return a ref to hash of single matched row, by conditions
+ # and restrictions. return undef if nothing matched.
+ # (column1 => value1, column2 => value2) or empty () if non matched
+ #
+ # sql_get_hash_ref($table_name,\@columns,\@conditions,\@restrictions);
+ #
+ # columns is a list of columns to be returned (username, fname,...)
+ #
+ # conditions must be an array so we can path more than one column with
+ # the same name.
+ # @conditions = ( column => ['comp_sign','value'],
+ # foo => ['>',15],
+ # foo => ['<',30],
+ # );
+ # The sub knows automatically to detect and quote strings
+ #
+ # restrictions is a list of restrictions like ('order by email')
+ #
+ ##########################
+ sub sql_get_hash_ref{
+ my $self = shift;
+ my $table = shift || '';
+ my $r_cols = shift || [];
+ my $r_conds = shift || [];
+ my $r_restr = shift || [];
+
+ # we want to print in debug mode the trace
+ d( "[".(caller(2))[3]." - ".(caller(1))[3]." - ". (caller(0))[3]."]");
+
+ # build the query
+ my $do_sql = "SELECT ";
+ $do_sql .= join ",", @{$r_cols} if @{$r_cols};
+ $do_sql .= " FROM $table ";
+
+ my @where = ();
+ for(my $i=0;$i<@{$r_conds};$i=$i+2) {
+ push @where, join " ",
+ $$r_conds[$i],
+ $$r_conds[$i+1][0],
+ sql_quote(sql_escape($$r_conds[$i+1][1]));
+ }
+ # Add the where clause if we have one
+ $do_sql .= " WHERE ". join " AND ", @where if @where;
+
+ # restrictions (DONT put commas!)
+ $do_sql .= " ". join " ", @{$r_restr} if @{$r_restr};
+
+ d("SQL: $do_sql");
+
+ # do query
+ $self->{sth} = $self->{dbh}->prepare($do_sql);
+ $self->{sth}->execute();
+
+ return $self->{sth}->fetchrow_hashref;
+
+ } # end of sub sql_get_hash_ref
+
+
+
+
+
+ ######################################################################
+ # returns a reference to an array, matched by conditions and
+ # restrictions, which contains one reference to array per row. If
+ # there are no rows to return, returns a reference to an empty array:
+ # [
+ # [array1],
+ # ......
+ # [arrayN],
+ # ];
+ #
+ # $ref = sql_get_matched_rows_ary_ref($table_name,\@columns,\@conditions,\@restrictions);
+ #
+ # columns is a list of columns to be returned (username, fname,...)
+ #
+ # conditions must be an array so we can path more than one column with
+ # the same name. @conditions are being cancatenated with AND
+ # @conditions = ( column => ['comp_sign','value'],
+ # foo => ['>',15],
+ # foo => ['<',30],
+ # );
+ # results in
+ # WHERE foo > 15 AND foo < 30
+ #
+ # to make an OR logic use (then ANDed )
+ # @conditions = ( column => ['comp_sign',['value1','value2']],
+ # foo => ['=',[15,24] ],
+ # bar => ['=',[16,21] ],
+ # );
+ # results in
+ # WHERE (foo = 15 OR foo = 24) AND (bar = 16 OR bar = 21)
+ #
+ # The sub knows automatically to detect and quote strings
+ #
+ # restrictions is a list of restrictions like ('order by email')
+ #
+ ##########################
+ sub sql_get_matched_rows_ary_ref{
+ my $self = shift;
+ my $table = shift || '';
+ my $r_cols = shift || [];
+ my $r_conds = shift || [];
+ my $r_restr = shift || [];
+
+ # we want to print in debug mode the trace
+ d( "[".(caller(2))[3]." - ".(caller(1))[3]." - ". (caller(0))[3]."]");
+
+ # build the query
+ my $do_sql = "SELECT ";
+ $do_sql .= join ",", @{$r_cols} if @{$r_cols};
+ $do_sql .= " FROM $table ";
+
+ my @where = ();
+ for(my $i=0;$i<@{$r_conds};$i=$i+2) {
+
+ if (ref $$r_conds[$i+1][1] eq 'ARRAY') {
+ # multi condition for the same field/comparator to be ORed
+ push @where, map {"($_)"} join " OR ",
+ map { join " ",
+ $r_conds->[$i],
+ $r_conds->[$i+1][0],
+ sql_quote(sql_escape($_));
+ } @{$r_conds->[$i+1][1]};
+ } else {
+ # single condition for the same field/comparator
+ push @where, join " ",
+ $r_conds->[$i],
+ $r_conds->[$i+1][0],
+ sql_quote(sql_escape($r_conds->[$i+1][1]));
+ }
+ } # end of for(my $i=0;$i<@{$r_conds};$i=$i+2
+
+ # Add the where clause if we have one
+ $do_sql .= " WHERE ". join " AND ", @where if @where;
+
+ # restrictions (DONT put commas!)
+ $do_sql .= " ". join " ", @{$r_restr} if @{$r_restr};
+
+ d("SQL: $do_sql");
+
+ # do query
+ return $self->{dbh}->selectall_arrayref($do_sql);
+
+ } # end of sub sql_get_matched_rows_ary_ref
+
+
+
+
+ ######################################################################
+ # insert a single row into a DB
+ #
+ # sql_insert_row($table_name,\%data,$delayed);
+ #
+ # data is hash of type (column1 => value1 ,column2 => value2 , )
+ #
+ # $delayed: 1 => do delayed insert, 0 or none passed => immediate
+ #
+ # * The sub knows automatically to detect and quote strings
+ #
+ # * The insert id delayed, so the user will not wait untill the insert
+ # will be completed, if many select queries are running
+ #
+ ##########################
+ sub sql_insert_row{
+ my $self = shift;
+ my $table = shift || '';
+ my $r_data = shift || {};
+ my $delayed = (shift) ? 'DELAYED' : '';
+
+ # we want to print in debug mode the trace
+ d( "[".(caller(2))[3]." - ".(caller(1))[3]." - ". (caller(0))[3]."]");
+
+ # build the query
+ my $do_sql = "INSERT $delayed INTO $table ";
+ $do_sql .= "(".join(",",keys %{$r_data}).")";
+ $do_sql .= " VALUES (";
+ $do_sql .= join ",", sql_quote(sql_escape( values %{$r_data} ) );
+ $do_sql .= ")";
+
+ d("SQL: $do_sql");
+
+ # do query
+ $self->{sth} = $self->{dbh}->prepare($do_sql);
+ $self->{sth}->execute();
+
+ } # end of sub sql_insert_row
+
+
+ ######################################################################
+ # update rows in a DB by condition
+ #
+ # sql_update_rows($table_name,\%data,\@conditions,$delayed);
+ #
+ # data is hash of type (column1 => value1 ,column2 => value2 , )
+ #
+ # conditions must be an array so we can path more than one column with
+ # the same name.
+ # @conditions = ( column => ['comp_sign','value'],
+ # foo => ['>',15],
+ # foo => ['<',30],
+ # );
+ #
+ # $delayed: 1 => do delayed insert, 0 or none passed => immediate
+ #
+ # * The sub knows automatically to detect and quote strings
+ #
+ #
+ ##########################
+ sub sql_update_rows{
+ my $self = shift;
+ my $table = shift || '';
+ my $r_data = shift || {};
+ my $r_conds = shift || [];
+ my $delayed = (shift) ? 'LOW_PRIORITY' : '';
+
+ # we want to print in debug mode the trace
+ d( "[".(caller(2))[3]." - ".(caller(1))[3]." - ". (caller(0))[3]."]");
+
+ # build the query
+ my $do_sql = "UPDATE $delayed $table SET ";
+ $do_sql .= join ",",
+ map { "$_=".join "",sql_quote(sql_escape($$r_data{$_})) } keys %{$r_data};
+
+ my @where = ();
+ for(my $i=0;$i<@{$r_conds};$i=$i+2) {
+ push @where, join " ",
+ $$r_conds[$i],
+ $$r_conds[$i+1][0],
+ sql_quote(sql_escape($$r_conds[$i+1][1]));
+ }
+ # Add the where clause if we have one
+ $do_sql .= " WHERE ". join " AND ", @where if @where;
+
+
+ d("SQL: $do_sql");
+
+ # do query
+ $self->{sth} = $self->{dbh}->prepare($do_sql);
+
+ $self->{sth}->execute();
+
+ # my ($count) = $self->{sth}->fetchrow_array;
+ #
+ # d("Result: $count");
+
+ } # end of sub sql_update_rows
+
+
+ ######################################################################
+ # delete rows from DB by condition
+ #
+ # sql_delete_rows($table_name,\@conditions);
+ #
+ # conditions must be an array so we can path more than one column with
+ # the same name.
+ # @conditions = ( column => ['comp_sign','value'],
+ # foo => ['>',15],
+ # foo => ['<',30],
+ # );
+ #
+ # * The sub knows automatically to detect and quote strings
+ #
+ #
+ ##########################
+ sub sql_delete_rows{
+ my $self = shift;
+ my $table = shift || '';
+ my $r_conds = shift || [];
+
+ # we want to print in debug mode the trace
+ d( "[".(caller(2))[3]." - ".(caller(1))[3]." - ". (caller(0))[3]."]");
+
+ # build the query
+ my $do_sql = "DELETE FROM $table ";
+
+ my @where = ();
+ for(my $i=0;$i<@{$r_conds};$i=$i+2) {
+ push @where, join " ",
+ $$r_conds[$i],
+ $$r_conds[$i+1][0],
+ sql_quote(sql_escape($$r_conds[$i+1][1]));
+ }
+
+ # Must be very carefull with deletes, imagine somehow @where is
+ # not getting set, "DELETE FROM NAME" deletes the contents of the table
+ warn("Attempt to delete a whole table $table from DB\n!!!"),return unless @where;
+
+ # Add the where clause if we have one
+ $do_sql .= " WHERE ". join " AND ", @where;
+
+ d("SQL: $do_sql");
+
+ # do query
+ $self->{sth} = $self->{dbh}->prepare($do_sql);
+ $self->{sth}->execute();
+
+ } # end of sub sql_delete_rows
+
+
+ ######################################################################
+ # executes the passed query and returns a reference to an array which
+ # contains one reference per row. If there are no rows to return,
+ # returns a reference to an empty array.
+ #
+ # $r_array = sql_execute_and_get_r_array($query);
+ #
+ #
+ ##########################
+ sub sql_execute_and_get_r_array{
+ my $self = shift;
+ my $do_sql = shift || '';
+
+ # we want to print in debug mode the trace
+ d( "[".(caller(2))[3]." - ".(caller(1))[3]." - ". (caller(0))[3]."]");
+
+ d("SQL: $do_sql");
+
+ $self->{dbh}->selectall_arrayref($do_sql);
+
+ } # end of sub sql_execute_and_get_r_array
+
+
+
+ #
+ #
+ # return current date formatted for a DATE field type
+ # YYYYMMDD
+ #
+ ############
+ sub sql_date{
+ my $self = shift;
+
+ my ($sec,$min,$hour,$mday,$mon,$year) = localtime();
+ $year = ($year>70) ? sprintf "19%0.2d",$year : sprintf "20%0.2d",$year;
+ return sprintf "%0.4d%0.2d%0.2d",$year,++$mon,$mday;
+
+ } # end of sub sql_date
+
+ #
+ #
+ # return current date formatted for a DATE field type
+ # YYYYMMDDHHMMSS
+ #
+ ############
+ sub sql_datetime{
+ my $self = shift;
+
+ my ($sec,$min,$hour,$mday,$mon,$year) = localtime();
+ $year = ($year>70) ? sprintf "19%0.2d",$year : sprintf "20%0.2d",$year;
+ return sprintf "%0.4d%0.2d%0.2d%0.2d%0.2d%0.2d",$year,++$mon,$mday,$hour,$min,$sec;
+
+ } # end of sub sql_datetime
+
+
+ # Quote the list of parameters , alldigits parameters are unquoted (int)
+ # print sql_quote("one",2,"three"); => 'one' 2 'three'
+ #############
+ sub sql_quote{ map{ /^(\d+|NULL)$/ ? $_ : "'$_'" } @_ }
+
+ # Escape the list of parameters (all unsafe chars like ",' are escaped )
+ # must make a copy of @_ since we might try to change the passed
+ # (Modification of a read-only value attempted)
+ ##############
+ sub sql_escape{ my @a = @_; map { s/(['])/\\$1/g;$_} @a }
+
+
+ # DESTROY makes all kinds of cleanups if the fuctions were interuppted
+ # before their completion and haven't had a chance to make a clean up.
+ ###########
+ sub DESTROY{
+ my $self = shift;
+
+ $self->{sth}->finish if defined $self->{sth} and $self->{sth};
+ $self->{dbh}->disconnect if defined $self->{dbh} and $self->{dbh};
+
+ } # end of sub DESTROY
+
+
+
+ # Don't remove
+ 1;
</PRE>
<P>
-See also <A HREF="#Persistent_DB_Connections">Persistent DB Connections</A>
-
-<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Memory_sharing">Memory sharing</A></H1></CENTER>
+<CENTER><H3><A NAME="My_DB_Module_s_Usage_Examples">My::DB Module's Usage Examples</A></H3></CENTER>
<P>
-Another important point is memory sharing. If you OS supports this, and
-most of systems do, you might save more memory by sharing it between child
-processes. This is only possible when you preload code at the server
-startup. However during child process' life its memory pages becomes
-unshared and there is no way we can control perl to make it allocate memory
-so (dynamic) variables land on different memory pages than constants so the
-copy-on-write effect will hit almost at random. If you are pre-loading many
-modules you might be able to balance the memory that stays shared against
-the time for an occasional fork by tuning the <CODE>MaxRequestsperChild</CODE> to a point where you restart before too much becomes unshared. In this case
-the
-<CODE>MaxRequestsPerChild</CODE> is very specific to your scenario. You should do some measurements and you
-might see if this really makes a difference and what a reasonable number
-might be. Each time a child reaches this upper limit and restarts it should
-release the unshared copies and the new child will inherit pages that are
-shared until it scribbles on them.
+In your code that wants to use <CODE>My::DB</CODE>, you have to create a
+<CODE>My::DB</CODE> object first:
<P>
-It is very important to understand that your goal is not to have
-<CODE>MaxRequestsperChild</CODE> to be of 10000. Having a child to serve 300 requests on precompiled code is
-already a huge speedup, so if it is 100 or 10000 it does not really matter
-if it saves you the RAM by sharing. Do not forget that if you preload most
-of your code at the server startup, the fork to spawn a new child will be
-very very fast, cause it inherits most of the preloaded code and the perl
-interpreter from the parent process.
-
+<PRE> use vars qw($db_obj);
+ my $db_obj = new My::DB or croak "Can't initialize My::DB object: $!\n";
+</PRE>
<P>
-The conclusion is that <CODE>MaxRequestsperChild</CODE> should not be too big, otherwise you loose the benefits of the memory
-sharing.
+From this moment, you can use any <CODE>My::DB</CODE>'s methods. I will start from a very simple query - I want to know where
+the users are and produce statistics. <CODE>tracker</CODE> is the name of the table.
+<P>
+<PRE> # fetch the statistics of where users are
+ my $r_ary = $db_obj->sql_get_matched_rows_ary_ref
+ ("tracker",
+ [qw(where_user_are)],
+ );
+
+ my %stats = ();
+ my $total = 0;
+ foreach my $r_row (@$r_ary){
+ $stats{$r_row->[0]}++;
+ $total++;
+ }
+</PRE>
<P>
-See <A HREF="././performance.html#Choosing_MaxRequestsPerChild">Choosing MaxRequestsPerChild</A> for more about tuning the <CODE>MaxRequestsperChild</CODE> parameter.
+Now let's count how many users do we have (in <CODE>users</CODE> table):
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Preload_Registry_Scripts">Preload Registry Scripts</A></H1></CENTER>
+<PRE> my $count = $db_obj->sql_count_matched("users");
+</PRE>
<P>
-Apache::RegistryLoader compiles Apache::Registry scripts at server startup.
-It can be a good idea to preload these as well. So the code will be shared
-among the child servers.
+Check whether user exists:
<P>
-example of use at modperl.com in a PerlRequire'd file:
+<PRE> my $username = 'stas';
+ my $exists = $db_obj->sql_count_matched
+ ("users",
+ [username => ["=",$username]]
+ );
+</PRE>
+<P>
+Check whether user online and get time since when she is online (<CODE>since</CODE> a column in the <CODE>tracker</CODE> table telling since when user is online):
<P>
-<PRE> use File::Find 'finddepth';
- use Apache::RegistryLoader ();
- {
- my $perl_dir = "perl/";
- my $rl = Apache::RegistryLoader->new;
- finddepth(sub {
- return unless /\.pl$/;
- my $url = "/$File::Find::dir/$_";
- print "pre-loading $url\n";
+<PRE> my @row = ();
+ $db_obj->sql_get_matched_row
+ (\@row,
+ "tracker",
+ ['UNIX_TIMESTAMP(since)'],
+ [username => ["=",$username]]
+ );
- my $status = $rl->handler($url);
- unless($status == 200) {
- warn "pre-load of `$url' failed, status=$status\n";
- }
- }, $perl_dir);
+ if (@row) {
+ my $idle = int( (time() - $row[0]) / 60);
+ return "Current status: Is Online and idle for $idle minutes.";
}
</PRE>
<P>
-Note that we don't use here the second argument to the
-<CODE>handler().</CODE> You might need to provide a <CODE>trans()</CODE>
-method, since it's very dependent on your server's configuration. See <CODE>perldoc Apache::RegistryLoader</CODE> for the complete information.
+A complex query. I do join of 2 tables, and want to get a reference to
+array, which will store a slice of the matched query (<CODE>LIMIT
+$offset,$hits</CODE>), sorted by <CODE>username</CODE> and each row in array_ref to include the fields from the <CODE>users</CODE> table, but only those listed in
+<CODE>@verbose_cols</CODE>. Then we print it out.
<P>
-You have to check whether it makes any good for you though, I did some
-testing [ <A HREF="#Preload_Perl_modules_Real_Numb">Preload Perl modules - Real Numbers</A> ], and it seems that it takes more memory than when the scripts is being
-called from the child - This is only a first impression and needs better
-investigation. If you aren't concerned about few scripts invocations which
-will take some time to respond while they load the code, you might not need
-it all!
-
+<PRE> my $r_ary = $db_obj->sql_get_matched_rows_ary_ref
+ (
+ "tracker STRAIGHT_JOIN users",
+ [map {"users.$_"} @verbose_cols],
+ [],
+ ["WHERE tracker.username=users.username",
+ "ORDER BY users.username",
+ "LIMIT $offset,$hits"],
+ );
+
+ foreach my $r_row (@$r_ary){
+ print ...
+ }
+</PRE>
<P>
-See also <A HREF="././porting.html#BEGIN_blocks">BEGIN blocks</A>
+Another complex query. User checks checkboxes to be queried by, selects
+from lists and types in match strings, we process input and build the <CODE>@where</CODE> array. Then we want to get the number of matches and the matched rows as
+well.
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Avoid_Importing_Functions">Avoid Importing Functions</A></H1></CENTER>
+<PRE> my @where = ();
+ # process chekoxes - we turn them into REGEXP
+ foreach (keys %search_keys) {
+ next unless defined $q->param($_) and $q->param($_);
+ my $regexp = "[".join("",$q->param($_))."]";
+ push @where, ($_ => ['REGEXP',$regexp]);
+ }
+
+ # Now add all the single answer , selected => exact macth
+ push @where,(country => ['=',$q->param('country')]) if $q->param('country');
+
+ # Now add all the typed params
+ foreach (qw(city state)) {
+ push @where,($_ => ['LIKE',$q->param($_)]) if $q->param($_);
+ }
+
+ # Do the count all matched query
+ my $total_matched_users = $db_obj->sql_count_matched
+ (
+ "users",
+ \@where,
+ );
+
+ # Now process the orderby
+ my $orderby = $q->param('orderby') || 'username';
+
+ # Do the query and fetch the data
+ my $r_ary = $db_obj->sql_get_matched_rows_ary_ref
+ (
+ "users",
+ \@display_columns,
+ \@where,
+ ["ORDER BY $orderby",
+ "LIMIT $offset,$hits"],
+ );
+</PRE>
<P>
-When possible, avoid importing of a module functions into your name space.
-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.
+<CODE>sql_get_matched_rows_ary_ref</CODE> knows to handle both <CODE>OR</CODE>ed and
+<CODE>AND</CODE>ed params. This example shows how to use <CODE>OR</CODE> on parameters:
<P>
+This snippet is an implementation of the watchdog. Users register usernames
+of the people they want to know when these are going online, so we have to
+make 2 queries - one to get a list of these usernames, second to query
+whether any of these users is online. In the second query we use <CODE>OR</CODE> keyword.
+
+<P>
+<PRE> # check who we are looking for
+ $r_ary = $db_obj->sql_get_matched_rows_ary_ref
+ ("watchdog",
+ [qw(watched)],
+ [username => ['=',$username)],
+ ],
+ );
+
+ # put them into an array
+ my @watched = map {$_->[0]} @{$r_ary};
+
+ my %matched = ();
+ # Do user has some registered usernames?
+ if (@watched) {
+
+ # try to bring all the users who match (exactly) the usernames - put
+ # it into array and compare with a hash!
+ $r_ary = $db_obj->sql_get_matched_rows_ary_ref
+ ("tracker",
+ [qw(username)],
+ [username => ['=',\@watched],
+ ]
+ );
+
+ map {$matched{$_->[0]} = 1} @{$r_ary};
+ }
+
+ # Now %matched includes the usernames of the users who are being
+ # watched by $username and currently are online.
+</PRE>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Reducing_the_Memory_Usage">Reducing the Memory Usage</A></H1></CENTER>
-<P>
-One of the important issues in improving the performance is memory usage
-reduce - the less memory server uses - the more server processes you can
-start - the more performance you have (from the user point of view - the
-respond speed )
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
-<P>
-See <A HREF="././porting.html#Global_Variables">Global Variables</A>
+ <HR>
+ [ <A HREF="warnings.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="dbm.html">Next</A> ]
-<P>
-See <A HREF="././porting.html#Memory_leakages">Memory "leakages"</A>
+<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
+</TR>
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
+ </FONT>
+ </B>
+ </TD>
+
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
+
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
+</TR>
+</TABLE></CENTER>
+
+</BODY>
+</HTML>
+
+
+<HR SIZE=6>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+ <TITLE>mod_perl guide: mod_perl and dbm files</TITLE>
+ <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
+ <META NAME="Author" CONTENT="Bekman Stas">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
+</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
+<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+<A NAME="toc"></A>
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+mod_perl and dbm files</H1>
+<HR WIDTH="100%">
+ [ <A HREF="databases.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="multiuser.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+<UL>
+
+ <LI><A HREF="#Where_and_Why_to_use_dbm_files">Where and Why to use dbm files</A>
+ <LI><A HREF="#mod_perl_and_dbm">mod_perl and dbm</A>
+ <LI><A HREF="#Locking_dbm_handlers">Locking dbm handlers</A>
+ <LI><A HREF="#Tie_DB_Lock">Tie::DB_Lock</A>
+ <LI><A HREF="#Code_snippets">Code snippets</A>
+</UL>
+<!-- INDEX END -->
+
+<HR>
+
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+
+ <HR>
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-Joel Wagner reports that calling an undefined subroutine in a module can
-cause a tight loop that consumes all memory. Here is a way to catch such
-errors. Define an autoload subroutine:
+<CENTER><H1><A NAME="Where_and_Why_to_use_dbm_files">Where and Why to use dbm files</A></H1></CENTER>
+<P>
+dbm files are the first implementations of the databases, which originated
+on Unix systems, and currently being used in many Unix applications where
+simple key-value pairs should be stored and manipulated. As of this writing
+Berkeley DB is the most powerful dbm implementation. If you need a light
+database, with easy API to work with this is a solution that should be
+considered as a first one. Of course only if you are sure the DB you are
+going to use will stay small, I would say under 5000-10000 records, but it
+depends on your hardware, which can rise and lower the numbers above. It is
+a much better solution over the flat file databases which become pretty
+slow on insert, update and delete operations when the number of records
+grows beyond 1000. The situation is even worse when we need to run sort on
+this kind of DB.
+
+<P>
+dbm files are being manipulated much faster than their flat file brothers,
+since almost never the whole DB is being read into a memory and because of
+smart storage technique. You can use a <CODE>HASH</CODE>
+algorithm which allows a <CODE>0(1)</CODE> complexity of search and update, fast insert and delete, but slow sort,
+since you have to do it yourself. <CODE>BTREE</CODE> allows arbitrary key/value pairs to be stored in a sorted, balanced binary
+tree, which allows us to get a sorted sequence of data pairs in <CODE>0(1)</CODE>, but much slower insert, update, delete operations. <CODE>RECNO</CODE> algorithm is more complicated one, and enables for both fixed-length and
+variable-length flat text files to be manipulated using the same key/value
+pair interface as in <CODE>HASH</CODE> and
+<CODE>BTREE</CODE>. In this case the key will consist of a record (line) number. Most chances
+you will want to use the <CODE>HASH</CODE> format, but your choice is very dependent on a kind of your application.
+
+<P>
+<STRONG>dbm</STRONG> databases are not limited for key and value pairs storages, but can store
+more complicated structures with help of <CODE>MLDBM</CODE>
+module. Which can dump and restore the whole symbol table of your script,
+including arrays, hashes and other complicated data <CODE>HASH</CODE>
+structures.
+
+<P>
+Another important thing to say, is that you cannot convert a dbm file from
+one storing algorithm to another, by simply tying it using a wanted format.
+The only way is to dump it into a flat file and then restore it using a new
+format. You can use a script like:
<P>
-<PRE> sub UNIVERSAL::AUTOLOAD {
- my $class = shift;
- warn "$class can't \$UNIVERSAL::AUTOLOAD!\n";
+<PRE> #!/usr/bin/perl -w
+
+ #
+ # This script gets as a parameter a Berkeley DB file(s) which is stored
+ # with DB_BTREE algorithm, and will backup it with .bak and create
+ # instead the db with the same records but stored with DB_HASH
+ # algorithm
+ #
+ # Usage: btree2hash.pl filename(s)
+
+ use strict;
+ use DB_File;
+ use File::Copy;
+
+ # Do checks
+ die "Usage: btree2hash.pl filename(s))\n" unless @ARGV;
+
+ foreach my $filename (@ARGV) {
+
+ die "Can't find $filename: $!\n" unless -e $filename and -r $filename;
+
+ # First backup the filename
+ move("$filename","$filename.btree")
+ or die "can't move $filename $filename.btree:$!\n";
+
+ my %hash;
+ my %btree;
+
+ # tie both dbs (db_hash is a fresh one!)
+ tie %btree , 'DB_File',"$filename.btree", O_RDWR|O_CREAT,
+ 0660, $DB_BTREE or die "Can't tie %btree";
+ tie %hash , 'DB_File',"$filename" , O_RDWR|O_CREAT,
+ 0660, $DB_HASH or die "Can't tie %hash";
+
+ # copy DB
+ %hash = %btree;
+
+ # untie
+ untie %btree ;
+ untie %hash ;
}
</PRE>
<P>
-It will produce a nice error in error_log, giving the line number of the
-call and the name of the undefined subroutine.
+Note that some dbm implementations come with other conversion utilities as
+well.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="how_can_I_find_if_my_modperl_scr">how can I find if my modperl scripts have memory leaks (and where)</A></H1></CENTER>
+<CENTER><H1><A NAME="mod_perl_and_dbm">mod_perl and dbm</A></H1></CENTER>
<P>
-Apache::Leak (derived from Devel::Leak) should help you with this task.
-Example:
+Where mod_perl enters into a picture? If you are using a read only dbm file
+you can have it work faster if you keep it open (tied) all the time, so
+when your CGI script wants to access the database it is already tied and
+ready to be used. It will work as well with your dynamic dbm databases as
+well but you need to use locking to avoid data corruptions. Of course this
+feature can make a huge speedup to your CGIs, but you should be very
+careful. What should be taken into account is a db locking, handling
+possible <CODE>die()</CODE> cases and child quits. A stale lock can deactivate your whole site, if your
+locking mechanism cannot handle dropped locks. You can enter a deadlock
+situations if 2 processes are trying to acquire locks on 2 databases, but
+get stuck because each has got hands on one of the 2 databases, and to
+release it, each process needs the second one, which will never be freed,
+because that is the condition for the first one to be released (possible
+only if processes do not all ask for their DB files in the same order). If
+you modify the DB you should be very careful to flush and synchronize it,
+especially when your CGI unexpectedly dies. In general your application
+should be tested very thoroughly before you put it into production to
+handle important data.
<P>
-<PRE> use Apache::Leak;
-
- my $global = "FooAAA";
-
- leak_test {
- $$global = 1;
- ++$global;
- };
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Locking_dbm_handlers">Locking dbm handlers</A></H1></CENTER>
<P>
-The argument to <CODE>leak_test()</CODE> is an anonymous sub, so you can
-just throw it around any code you suspect might be leaking. beware, it will
-run the code twice, because the first time in, new SVs are created, but
-does not mean you are leaking, the second pass will give better evidence.
-you do not need to be inside mod_perl to use it, from the command line, the
-above script outputs:
+Let's have a lock status as a global variable, so it will persist from
+request to request. If we are requesting a lock - READ (shared) or WRITE
+(exclusive), the current lock status is being obtained first.
<P>
-<PRE> ENTER: 1482 SVs
- new c28b8 : new c2918 :
- LEAVE: 1484 SVs
- ENTER: 1484 SVs
- new db690 : new db6a8 :
- LEAVE: 1486 SVs
- !!! 2 SVs leaked !!!
-</PRE>
+If we get a READ lock request, it is granted as soon as file becomes or is
+locked or already locked for READ. Lock status is READ now.
+
<P>
-Build a debuggable perl to see dumps of the SVs. the simple way to have
-both a normal perl and debuggable perl, is to follow hints in the SUPPORT
-doc for building libperld.a, when that is built copy the `perl' from that
-directory to your perl bin directory, but name it `dperl'.
+If we get a WRITE lock request, it is granted as soon as file becomes or is
+unlocked. Lock status is WRITE now.
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Limiting_the_size_of_the_process">Limiting the size of the processes</A></H1></CENTER>
+What happens to the WRITE lock request, is the most important. If the DB is
+being READ locked, request that request to write will poll until there will
+be no reading or writing process left. Lots of processes can successfully
+read the file, since they do not block each other from doing so. This means
+that a process that wants to write to the file (first obtaining an
+exclusive lock) never gets a chance to squeeze in. The following diagram
+represents a possible scenario where everybody read but no one can write:
+
<P>
-Apache::SizeLimit allows you to kill off Apache httpd processes if they
-grow too large. see perldoc Apache::SizeLimit for more details.
+<PRE> [-p1-] [--p1--]
+ [--p2--]
+ [---------p3---------]
+ [------p4-----]
+ [--p5--] [----p5----]
+</PRE>
+<P>
+So you get a starving process, which most certainly will timeout the
+request, and the DB will be not updated.
<P>
-By using this module, you should be able to discontinue using the Apache
-configuration directive MaxRequestsPerChild, although for some folks, using
-both in combination does the job.
+So you have another reason not to cache the dbm handle with dynamic dbm
+files. But it will work perfect with the static DBM files without a need to
+lock files at all. Ken Williams solved the above problem in his <CODE>Tie::DB_Lock</CODE> module, and I will present it in the next section.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Limiting_the_resources_used_by_h">Limiting the resources used by httpd children</A></H1></CENTER>
+<CENTER><H1><A NAME="Tie_DB_Lock">Tie::DB_Lock</A></H1></CENTER>
<P>
-Apache::Resource uses the BSD::Resource module, which uses the C function
-setrlimit to set limits on system resources such as memory and cpu usage.
+<CODE>Tie::DB_Lock</CODE> - ties hashes to databases using shared and exclusive locks. A module by
+Ken Williams. which solves the problem raised in the previous section.
<P>
-See perldoc Apache::Resource for more info.
+The main difference from what I have described before is that
+<CODE>Tie::DB_Lock</CODE> copies a dbm file on read so that reader processes do not have to keep the
+file locked while they read it, and writers can still access it while
+others are reading. It works best when you have lots of long-duration
+reading, and a few short bursts of writing.
+
+<P>
+The drawback of this module is a heavy IO performed when every reader makes
+a fresh copy of the DB. With big dbm files this can be quite a disadvantage
+and slowdown. An improvement that can cut a number of files that are being
+copied, would be to have only one copy of the dbm image that will be shared
+by all the reader processes. So it would put the responsibility of copying
+the read-only file on the writer, not the reader. It would take some care
+to make sure it does not disturb readers when putting a new read-only copy
+into place.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Limiting_the_request_rate_speed_">Limiting the request rate speed (robots blocking)</A></H1></CENTER>
+<CENTER><H1><A NAME="Code_snippets">Code snippets</A></H1></CENTER>
<P>
-A limitation of using pattern matching to identify robots is that it only
-catches the robots that you know about, and only those that identify
-themselves by name. A few devious robots masquerade as users by using user
-agent strings that identify themselves as conventional browsers. To catch
-such robots, you'll have to be more sophisticated.
+I have discussed what can be achieved with mod_perl and dbm files, the cons
+and pros. Now it is a time to show some code. I wrote a simple wrapper for
+a <CODE>DB_File</CODE> module, and extended it to handle locking, and proper exits. Note that this
+code still demands some testing, so be careful if you use it on your
+production machine as is.
<P>
-Apache::SpeedLimit comes for you to help, see:
+So the <CODE>DB_File::Wrap</CODE> (note that you will not find it on CPAN):
<P>
-<A
-HREF="http://www.modperl.com/chapters/ch6.html#Blocking_Greedy_Clients">http://www.modperl.com/chapters/ch6.html#Blocking_Greedy_Clients</A>
+<PRE> package DB_File::Wrap;
+ require 5.004;
+
+ use strict;
+
+ BEGIN {
+ # RCS/CVS complient: must be all one line, for MakeMaker
+ $DB_File::Wrap::VERSION = do { my @r = (q$Revision: 1.11 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
+
+ }
+
+ use DB_File;
+ use Fcntl qw(:flock O_RDWR O_CREAT);
+ use Carp qw(croak carp verbose);
+ use IO::File;
+
+ use vars qw($debug);
+
+ #$debug = 1;
+ $debug = 0;
+
+ # my $db = DB_File::Wrap \%hash, $filename, [lockmode];
+ # from now one we can work with both %hash (tie API) and $db (direct API)
+ #########
+ sub new{
+ my $class = shift;
+ my $hr_hash = shift;
+ my $file = shift;
+ my $lock_mode = shift || '';
+ my $db_type = shift || 'HASH';
+
+ my $self;
+ $self = bless {
+ db_type => 'DB_File',
+ flags => O_RDWR|O_CREAT,
+ mode => 0660,
+ hash => $hr_hash,
+ how => $DB_HASH,
+ }, $class ;
+
+ # by default we tie with HASH alg and if requested with BTREE
+ $self->{'how'} = ($db_type eq 'BTREE') ? $DB_BTREE : $DB_HASH;
+
+ # tie the object
+ $self->{'db_obj'} = tie %{$hr_hash},
+ $self->{'db_type'},$file, $self->{'flags'},$self->{'mode'}, $self->{'how'}
+ or croak "Can't tie $file:$!\n"; ;
+
+ my $fd = $self->{'db_obj'}->fd;
+ croak "Can't get fd :$!" unless defined $fd and $fd;
+ $self->{'fh'}= new IO::File "+<&=$fd" or croak "[".__PACKAGE__."] Can't dup: $!";
+
+ # set the lock status to unlocked
+ $self->{'lock'} = 0;
+
+ # do the lock here if requested
+ $self->lock($lock_mode) if $lock_mode;
+
+ return $self;
+
+ } # end of sub new
+
+
+ # lock the fd either exclusive or shared lock (write/read)
+ # default is read (shared)
+ ###########
+ sub lock{
+ my $self = shift;
+ my $lock_mode = shift || 'read';
+
+ # lock codes:
+ # 0 == not locked
+ # 1 == read locked
+ # 2 == write locked
+
+ if ($lock_mode eq 'write') {
+ # Get the exclusive write lock
+ unless (flock ($self->{'fh'}, LOCK_EX | LOCK_NB)) {
+ unless (flock ($self->{'fh'}, LOCK_EX)) { croak "exclusive flock: $!" }
+ }
+ # save the status of lock
+ $self->{'lock'} = 2;
+
+ } elsif ($lock_mode eq 'read'){
+ # Get the shared read lock
+ unless (flock ($self->{'fh'}, LOCK_SH | LOCK_NB)) {
+ unless (flock ($self->{'fh'}, LOCK_SH)) { croak "shared flock: $!" }
+ }
+ # save the status of lock
+ $self->{'lock'} = 1;
+ } else {
+ # incorrect mode
+ carp "Can't lock. Unknown mode: $lock_mode\n";
+ }
+
+ } # end of sub lock
+
+ # unlock
+ ###########
+ sub unlock{
+ my $self = shift;
+
+ $self->{'db_obj'}->sync() if defined $self->{'db_obj'}; # flush
+ flock($self->{'fh'}, LOCK_UN);
+ $self->{'lock'} = 0;
+ }
+
+ # untie the hash
+ # and close all the handlers
+ # if wasn't unlocked, end() will unlock as well
+ ###########
+ sub end{
+ my $self = shift;
+
+ # unlock if stilllocked
+ $self->unlock() if $self->{'lock'};
+
+ delete $self->{'db_obj'} if $self->{'db_obj'};
+ untie %{$self->{'hr_hash'}} if $self->{'hr_hash'};
+ $self->{'fh'}->close if $self->{'fh'};
+
+ }
+
+
+ # DESTROY makes all kinds of cleanups if the fuctions were interuppted
+ # before their completion and haven't had a chance to make a clean up.
+ ###########
+ sub DESTROY{
+ my $self = shift;
+
+ # just to be sure that we properly closed everything
+ $self->end();
+
+ print "Destroying ".__PACKAGE__."\n" if $debug;
+ undef $self if $self;
+
+ }
+
+ ####
+ END {
+
+ print "Calling the END from ".__PACKAGE__."\n" if $debug;
+
+ }
+
+ 1;
+</PRE>
+<P>
+And you use it :
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Benchmarks_Impressing_your_Boss">Benchmarks. Impressing your Boss and Colleagues.</A></H1></CENTER>
+<PRE> use DB_File::Wrap ();
+</PRE>
<P>
-How much faster is mod_perl that CGI? There are many ways to benchmark the
-two. See a few examples and numbers below, also checkout the benchmark/
-directory of mod_perl dist for more examples.
+A simple tie, READ lock and untie
<P>
-If you write a benchmarks from your own for heavy scripts use
-<CODE>Benchmark</CODE> and for very fast scripts use <CODE>Time::HiRes</CODE> modules.
-
+<PRE> my %mydb = ();
+ my $db = new DB_File::Wrap \%mydb, $dbfile, 'read';
+ print $mydb{'stas'} if exists $mydb{'stas'};
+ # sync and untie
+ $db->end();
+</PRE>
<P>
-There is no need to write a special benchmark, if you want to impress your
-boss or colleagues, just take the heaviest cgi script you have, open 2
-xterms and call the same script in mod_perl mode in one xterm and in
-mod_cgi mode in the other. You can use lwp-get from LWP package to emulate
-the web agent (browser). (benchmark/ directory of mod_perl dist includes
-such an example)
+You can even skip the <CODE>end()</CODE> call, if leave the scope <CODE>$db</CODE> defined in:
<P>
-See also 2 tools for benchmarking:
-<A HREF="././performance.html#Tuning_with_ab_ApacheBench">ApacheBench</A> and <A HREF="././performance.html#Tuning_with_crashme_script">crashme test</A>
+<PRE> sub user_exists{
+ my $user = shift;
+ my $result = 0;
+
+ my %mydb = ();
+ my $db = new DB_File::Wrap \%mydb, $dbfile, 'read';
+
+ # if we match the username return 1
+ $result = 1 if $mydb{$user};
+
+ $result;
+ } # end of sub user_exists
+</PRE>
+<P>
+Perform both, read and write operations:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Developers_Talk">Developers Talk</A></H2></CENTER>
+<PRE> my %mydb = ();
+ my $db = new DB_File::Wrap \%mydb, $dbfile;
+ print $mydb{'stas'} if exists $mydb{'stas'};
+
+ # lock the db, we gonna change it!
+ $db->lock('write');
+ $mydb{'stas'} = 1;
+ # unlock the db for write
+
+ # sync and untie
+ $db->end();
+</PRE>
<P>
-Perrin Harkins writes on benchmarks or comparisons, official or unofficial:
+If your CGI was interrupted in the middle, <CODE>DESTROY</CODE> block will worry to unlock the dbm file and flush the changes. Note that I
+have got db corruptions even with this code on huge dbm files 10000+
+records, so be careful when you use it. I thought that I have covered all
+the possible failures but seems that not all of them. At the end I have
+moved everything to work with <STRONG>mysql</STRONG>. So if you figure out where the problem is you are very welcome to tell me
+about it.
-<BLOCKQUOTE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
-<P>
-I have used some of the platforms you mentioned and researched others. What
-I can tell you for sure, is that no commercially available system offers
-the depth, power, and ease of use that mod_perl has. Either they don't let
-you access the web server internals, or they make you use less productive
-languages than Perl, sometimes forcing you into restrictive and confusing
-APIs and/or GUI development environments. None of them offer the level of
-support available from simply posting a message to this list, at any price.
+ <HR>
+ [ <A HREF="databases.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="multiuser.html">Next</A> ]
-<P>
-As for performance, beyond doing several important things (code-caching,
-pre-forking/threading, and persistent database connections) there isn't
-much these tools can do, and it's mostly in your hands as the developer to
-see that the things which really take the time (like database queries) are
-optimized.
+<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
+</TR>
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
+ </FONT>
+ </B>
+ </TD>
-<P>
-The downside of all this is that most manager types seem to be unable to
-believe that web development software available for free could be better
-than the stuff that cost $25,000 per CPU. This appears to be the major
-reason most of the web tools companies are still in business. They send a
-bunch of suits to give PowerPoint presentations and hand out glossy
-literature to your boss, and you end up with an expensive disaster and an
-approaching deadline.
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
-<P>
-But I'm not bitter or anything...
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
+</TR>
+</TABLE></CENTER>
-</BLOCKQUOTE>
+</BODY>
+</HTML>
+
+
+<HR SIZE=6>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+ <TITLE>mod_perl guide: mod_perl for ISPs. mod_perl and Virtual Hosts.</TITLE>
+ <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
+ <META NAME="Author" CONTENT="Bekman Stas">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
+</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
+<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+<A NAME="toc"></A>
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+mod_perl for ISPs. mod_perl and Virtual Hosts.</H1>
+<HR WIDTH="100%">
+ [ <A HREF="dbm.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="control.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+<UL>
+
+ <LI><A HREF="#ISPs_providing_mod_perl_services">ISPs providing mod_perl services - a fantasy or reality.</A>
+ <LI><A HREF="#Virtual_Hosts_in_the_guide">Virtual Hosts in the guide</A>
+</UL>
+<!-- INDEX END -->
+
+<HR>
+
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-Jonathan Peterson adds:
+<CENTER><H1><A NAME="ISPs_providing_mod_perl_services">ISPs providing mod_perl services - a fantasy or reality.</A></H1></CENTER>
+<P>
+You have fallen in love with mod_perl from the first sight, since the
+moment you have installed it at your home box. But when you wanted to
+convert your CGI scripts, currently running on your favorite ISPs machine,
+to run under mod_perl - you have discovered, your ISPs either have never
+heard of such a beast, or refuse to install it for you.
-<BLOCKQUOTE>
+<P>
+You are an old sailor in the ISP business, you have seen it all, you know
+how many ISPs are out there and you know that the sales margins are too low
+to keep you happy. You are looking for some new service almost no one
+provides, to attract more clients to become your users and hopefully to
+have a bigger slice than a neighbor ISP.
<P>
-Most of the major solutions have something that they do better than the
-others, and each of them has faults. Microsoft's ASP has a very nice
-objects model, and has IMO the best data access object (better than DBI to
-use - but less portable) It has the worst scripting language. PHP has many
-of the advantages of Perl-based solutions, but is less complicated for
-developers. Netscape's Livewire has a good object model too, and provides
-good server-side Java integration - if you want to leverage Java skills,
-it's good. Also, it has a compiled scripting language - which is great if
-you aren't selling your clients the source code (and a pain otherwise).
+If you are a user asking for a mod_perl service or an ISP considering to
+provide this service, this section should make things clear for both of
+you.
<P>
-mod_perl's advantage is that it is the most powerful. It offers the
-greatest degree of control with one of the more powerful languages. It also
-offers the greatest granularity. You can use an embedding module (eg eperl)
-from one place, a session module (Session) from another, and your data
-access module from yet another.
+an ISP has 3 choices to choose from:
+<OL>
+<P><LI>
<P>
-I think the Apache::ASP module looks very promising. It has very easy to
-use and adequately powerful state maintenance, a good embedding system, and
-a sensible object model (that emulates the Microsoft ASP one). It doesn't
-replicate MS's ADO for data access, but DBI is fine for that.
+ISP cannot afford having a user, running scripts under mod_perl, on the
+main server, since it will die very soon for one of the many reasons:
+either sloppy programming, or user testing just updated script which
+probably has some syntax errors and etc, no need to explain why if you are
+familiar with mod_perl peculiarities. The only scripts that <STRONG>CAN BE ALLOWED</STRONG> to use, are the ones that were written by ISP and are not being modified by
+user (guest books, counters and etc - the same standard scripts ISPs
+providing since they were born). So you have to say <STRONG>NO</STRONG> for this choice.
+<P><LI>
<P>
-I have always found that the developers available make the greatest impact
-on the decision. If you have a team with no Perl experience, and a small or
-medium task, using something like PHP, or Microsoft ASP, makes more sense
-than driving your staff into the vertical learning curve they'll need to
-use mod_perl.
+But, hey why I cannot let my user to run his own server, so I clean my
+hands off and do not care how dirty and sloppy user's code is (assuming
+that user is running the server by his own username).
<P>
-For very large jobs, it may be worth finding the best technical solution,
-and then recruiting the team with the necessary skills.
+This option is fine as long as you are concerned about your new system
+requirements. If you have even some very limited experience with mod_perl,
+you know that mod_perl enabled apache servers while freeing up your CPU and
+lets you run scripts much much faster, has a huge memory demands (5-20
+times the plain apache uses). The size depends on the code length,
+sloppiness of the programmer, possible memory leaks the code might have and
+all that multiplied by the number of children each server spawns. A very
+simple example : a server demanding 10Mb of memory which spawns 10
+children, already rises your memory requirements by 100Mb (the real
+requirement are actually smaller if your OS allows code sharing between
+processes and a programmer exploits these features in her code). Now
+multiply the received number by the number of users you intend to have and
+you will get the memory requirements. Since ISPs never say no, you better
+use an opposite approach - think of a largest memory size you can afford
+then divide it by one user's requirements as I have shown in example, and
+you will know how much mod_perl users you can afford :)
-</BLOCKQUOTE>
+<P>
+But who am I to prognosticate how much memory your user may use. His
+requirement from a single server can be very modest, but do you know how
+many of servers he will run (after all she has all the control over
+httpd.conf - and it has to be that way, since this is very essential for
+the user running mod_perl)?
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Benchmarking_a_Graphic_hits_coun">Benchmarking a Graphic hits counter with Persistent DB Connection</A></H2></CENTER>
+All this rumbling about memory leads to a single question: Can you restrict
+user from using more than X memory? Or another variation of the question:
+Assuming you have as much memory as you want, can you charge user for the
+average memory usage?
+
<P>
-Here are the numbers from Michael Parker's mod_perl presentation at Perl
-Conference (Aug, 98) <A
-HREF="http://www.realtime.net/~parkerm/perl/conf98/index.htm">http://www.realtime.net/~parkerm/perl/conf98/index.htm</A>
-. The script is a standard hits counter, but it logs the counts into the
-mysql relational DataBase:
+If the answer for either of the above question is positive, you are all set
+and your clients will prize your name for letting them run mod_perl! There
+are tools to restrict resources' usage (See for example man pages for <CODE>ulimit(3)</CODE>, <CODE>getrlimit(2)</CODE>, <CODE>setrlimit(2)</CODE>
+and <CODE>sysconf(3)</CODE> ).
<P>
-<PRE> Benchmark: timing 100 iterations of cgi, perl... [rate 1:28]
-
- cgi: 56 secs ( 0.33 usr 0.28 sys = 0.61 cpu)
- perl: 2 secs ( 0.31 usr 0.27 sys = 0.58 cpu)
-
- Benchmark: timing 1000 iterations of cgi,perl... [rate 1:21]
-
- cgi: 567 secs ( 3.27 usr 2.83 sys = 6.10 cpu)
- perl: 26 secs ( 3.11 usr 2.53 sys = 5.64 cpu)
-
- Benchmark: timing 10000 iterations of cgi, perl [rate 1:21]
-
- cgi: 6494 secs (34.87 usr 26.68 sys = 61.55 cpu)
- perl: 299 secs (32.51 usr 23.98 sys = 56.49 cpu)
-</PRE>
+<META> If you have an experience with some restriction techniques
+please share with us. Thank you! </META>
+
<P>
-We don't know what server configurations was used for these testing, but I
-guess the numbers talks for themselves.
+If you have picked this choice, you have to provide your client:
+
+<UL>
+<P><LI>
+<P>
+Shutdown/startup scripts installed together with the rest of your daemon
+startup scripts (e.g <CODE>/etc/rc.d</CODE> directory) scripts, so when you reboot your machine user's server will be
+correctly shutdowned and will be back online the moment your system comes
+back online. Also make sure to start each server under username the server
+belongs to, if you are not looking for a big trouble.
+<P><LI>
<P>
-The source code of the script at <A
-HREF="http://www.realtime.net/~parkerm/perl/conf98/sld006.htm">http://www.realtime.net/~parkerm/perl/conf98/sld006.htm</A>
+Proxy (in a forward or httpd accelerator mode) services for user's virtual
+host. Since user will have to run her server on unprivileged port
+(>1024), you will have to forward all requests from
+<CODE>user.given.virtual.hostname:80</CODE> (which is
+<CODE>user.given.virtual.hostname</CODE> without port - 80 is a default) to
+<CODE>your.machine.ip:port_assigned_to_user</CODE> and user to code his scripts to write self referencing URLs to be of <CODE>user.given.virtual.hostname</CODE>
+base of course.
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Benchmarking_scripts_with_execut">Benchmarking scripts with execution times below 1 second :)</A></H2></CENTER>
+Letting user to run a mod_perl server, immediately adds a requirement for
+user to be able to restart and configure their own server. But only root
+can bind port 80. That is why user has to use ports numbers >1024.
+
+<P><LI>
<P>
-As noted before for very fast scripts you will have to use Time::HiRes
-module, it's usage is similar to the Benchmark's.
+Another problem you will have to solve is how to assign ports between
+users. Since user can pick any port above 1024 to run his server on, you
+will have to make some regulation here. A simple example will stress the
+importance of this problem: I am a malicious user or I just a rival of some
+fellow who runs his own server on your ISP. All I should do is to find out
+what port his server is listening to (e.g. with help of <CODE>netstat(8)</CODE>) and configure my own server to listen on the same port. While I am unable
+to bind to this same port, imagine what will happen when you reboot your
+system and my startup script happen to be run before my rivals! I get the
+port first, now all requests will be redirected to my server and let your
+imagination go wild about what nasty things might happen then. Of course
+the ugly things will be revealed pretty soon, but the damage has been done.
+</UL>
+<P><LI>
<P>
-<PRE> use Time::HiRes qw(gettimeofday tv_interval);
- my $start_time = [ gettimeofday ];
- &sub_that_takes_a_teeny_bit_of_time()
- my $end_time = [ gettimeofday ];
- my $elapsed = tv_interval($start_time,$end_time);
- print "the sub took $elapsed secs."
-</PRE>
+A much better, but costly solution is <STRONG>co-location</STRONG>. Let user to hook her (or ISP's) stand alone machine into your network,
+and forget about this user. Of course either user or you will have to make
+all the system administration chores and it will cost your client more
+money.
+
<P>
-See also <A HREF="././performance.html#Tuning_with_crashme_script">crashme test</A>.
+All in all, who are the people who seek the mod_perl support? The ones who
+run serious projects/businesses, who can afford a stand alone box, thus
+gaining their goal of self autonomy and keeping their ISP happy. So money
+is not an obstacle.
+</OL>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="PerlHandler_s_Benchmarking">PerlHandler's Benchmarking</A></H2></CENTER>
+<CENTER><H1><A NAME="Virtual_Hosts_in_the_guide">Virtual Hosts in the guide</A></H1></CENTER>
<P>
-At <A
-HREF="http://perl.apache.org/dist/contrib/">http://perl.apache.org/dist/contrib/</A>
-you will find Apache::Timeit package which does PerlHandler's Benchmarking.
+If you are about to use <STRONG>Virtual Hosts</STRONG> you might want to read these sections:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Tuning_the_Apache_s_configuratio">Tuning the Apache's configuration variables for the best performance</A></H1></CENTER>
-<P>
-It's very important to make a correct configuration of the
-<CODE>MinSpareServers MaxSpareServers StartServers MaxClients
-MaxRequestsPerChild</CODE> parameters. There are no defaults, the values of these variable are very
-important, as if too ``low'' you will not use the system for its full
-ability, and if too ``high'' chances your server will bring the machine to
-its knees.
+<A HREF="././config.html#Perl_Sections">Perl Sections</A>.
<P>
-All the above parameters should be specified on the basis of the resources
-you have. While with plain apache server, there is no big deal if you run
-too many servers (not too many of course) since the processes are of ~1Mb
-and aren't eating a lot of your RAM. The situation is different with
-mod_perl. I have seen mod_perl processes of 20Mb and more. Now if you have
-MaxClients set to 50: 50x20Mb = 1Gb - do you have 1Gb of RAM? Probably not.
-So how do you tune these numbers? Generally by trying different
-combinations and testing the server.
+<A HREF="././config.html#Configuring_Apache_mod_perl_wi">Easing the chores of configuring the virtual hosts with mod_macro</A>
+
+
<P>
-Before you start this task you should be armed with the proper weapon. You
-need a crashme script, which will load your server with all kinds of
-mod_perl scripts you can think you have in your repository. There are
-commercial solutions for that, when you have free ones that do the same job
-(but for free :). You can use an
-<A HREF="././performance.html#Tuning_with_ab_ApacheBench">ApacheBench</A> <STRONG><CODE>ab</CODE></STRONG> utility that comes with apache distribution or use a <A HREF="././performance.html#Tuning_with_crashme_script">crashme test</A> which uses LWP::Parallel::UserAgent. You need these to have an ability to
-emulate multiuser environment and to generate multiply clients which will
-call the mod_perl scripts at your server simultaneously.
+<A HREF="././config.html#Is_there_a_way_to_provide_a_diff">Is there a way to provide a different startup.pl file for each individual virtual host</A>
+
+
<P>
-See also 2 tools for benchmarking:
-<A HREF="././performance.html#Tuning_with_ab_ApacheBench">ApacheBench</A> and <A HREF="././performance.html#Tuning_with_crashme_script">crashme test</A>
+<A HREF="././config.html#Is_there_a_way_to_modify_INC_on">Is there a way to modify @INC on a per-virtual-host basis</A>
+
+
<P>
+<A HREF="././config.html#Sometimes_the_script_from_one_vi">Sometimes the script from one virtual host calls a script with the same path from the second virtual host</A>
+
+
+
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Tuning_with_ab_ApacheBench">Tuning with ab - ApacheBench</A></H2></CENTER>
-<P>
-<STRONG>ab</STRONG> is a tool for benchmarking your Apache HTTP server. It is designed to give
-you an impression on how much performance your current Apache installation
-can give. Particularly it shows you how much requests per secs your Apache
-server is capable to serve. The
-<STRONG>ab</STRONG> comes bundled with apache source distribution (and it's free :).
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
-<P>
-Lets try it. We will simulate 10 users concurrently requesting the script <CODE>www.you.com:81/test/test.pl</CODE> which a very light one. Each one does it for 10 times.
+ <HR>
+ [ <A HREF="dbm.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="control.html">Next</A> ]
-<P>
-<PRE> % ./ab -n 100 -c 10 www.you.com:81/test/test.pl
-
- Concurrency Level: 10
- Time taken for tests: 0.715 seconds
- Complete requests: 100
- Failed requests: 0
- Non-2xx responses: 100
- Total transferred: 60700 bytes
- HTML transferred: 31900 bytes
- Requests per second: 139.86
- Transfer rate: 84.90 kb/s received
-
- Connection Times (ms)
- min avg max
- Connect: 0 0 3
- Processing: 13 67 71
- Total: 13 67 74
-</PRE>
-<P>
-The only numbers we really care about are:
+<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
+</TR>
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 04/19/1999
+ </FONT>
+ </B>
+ </TD>
+
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
+
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
+</TR>
+</TABLE></CENTER>
+
+</BODY>
+</HTML>
+
+
+<HR SIZE=6>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+ <TITLE>mod_perl guide: Controlling and Monitoring the Server</TITLE>
+ <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
+ <META NAME="Author" CONTENT="Bekman Stas">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
+</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
+<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+<A NAME="toc"></A>
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+Controlling and Monitoring the Server</H1>
+<HR WIDTH="100%">
+ [ <A HREF="multiuser.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="status.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+<UL>
+
+ <LI><A HREF="#Restarting_techniques">Restarting techniques</A>
+ <LI><A HREF="#Implications_of_sending_TERM_HU">Implications of sending TERM, HUP, and USR1 to the server</A>
+ <LI><A HREF="#Using_apachectl_to_control_the_s">Using apachectl to control the server</A>
+ <LI><A HREF="#SUID_start_up_scripts">SUID start-up scripts</A>
+ <LI><A HREF="#Monitoring_the_Server_A_watchdo">Monitoring the Server. A watchdog.</A>
+ <LI><A HREF="#Running_server_in_a_single_mode">Running server in a single mode</A>
+ <LI><A HREF="#Starting_a_personal_server_for_e">Starting a personal server for each developer</A>
+ <LI><A HREF="#Wrapper_to_emulate_the_server_en">Wrapper to emulate the server environment</A>
+ <LI><A HREF="#Log_Rotation">Log Rotation</A>
+ <LI><A HREF="#Preventing_from_modperl_process_">Preventing from modperl process to eat up all the disk's space, when it goes wild.</A>
+</UL>
+<!-- INDEX END -->
+
+<HR>
+
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+
+ <HR>
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<PRE> Complete requests: 100
- Failed requests: 0
- Requests per second: 139.86
-</PRE>
+<CENTER><H1><A NAME="Restarting_techniques">Restarting techniques</A></H1></CENTER>
<P>
-Lets rise the load of requests to 100 x 10 (10 users each 100 requests
+All of these techniques require that you know the server PID (Process ID).
+The easiest way to find the PID is to look it up in the httpd.pid file.
+With my configuration it exists as
+<CODE>/usr/apps/var/httpd_perl/run/httpd.pid</CODE>. It's easy to discover where to look at, by checking out the httpd.conf
+file. Open the file and locate the entry <CODE>PidFile</CODE>:
<P>
-<PRE> % ./ab -n 1000 -c 10 www-pais:81/perl/access/access.cgi
- Concurrency Level: 10
- Complete requests: 1000
- Failed requests: 0
- Requests per second: 139.76
+<PRE> PidFile /usr/apps/var/httpd_perl/run/httpd.pid
</PRE>
<P>
-As expected nothing changes (Since the situation didn't changed, we have
-the same 10 concurrent users). Now lets rise the number of concurrent
-users:
+Another way is to use the <CODE>ps</CODE> and <CODE>grep</CODE> utilities:
<P>
-<PRE> % ./ab -n 1000 -c 50 www-pais:81/perl/access/access.cgi
- Complete requests: 1000
- Failed requests: 0
- Requests per second: 133.01
+<PRE> % ps auxc | grep httpd_perl
</PRE>
-<P>
-We see that the server is capable to serve 50 concurrent users at amazing
-133 req/sec! Lets find the upper bound. Using <CODE>-n 10000 -c
-1000</CODE> failed to get results (Broken Pipe?). Using <CODE>-n 10000 -c
-500</CODE> derived 94.82 req/sec. It went down with the high load.
-
<P>
-This test was performed with the following configuration:
+or maybe:
-<P>
-<PRE> MinSpareServers 8
- MaxSpareServers 6
- StartServers 10
- MaxClients 50
- MaxRequestsPerChild 1500
+<P>
+<PRE> % ps -ef | grep httpd_perl
</PRE>
<P>
-Now let's try this:
+This will produce a list of all httpd_perl (the parent and the children)
+processes. You are looking for the parent process. If you run your server
+as root - you will easily locate it, since it belongs to root. If you run
+the server as user (when you <A HREF="././install.html#Is_it_possible_to_install_and_us">don't have a root access</A>, most likely all the processes will belong to that user (unless defined
+differently in the httpd.conf), but it's still easy to know 'who is the
+parent' -- the one of the smallest size...
<P>
-<PRE> MinSpareServers 8
- MaxSpareServers 6
- StartServers 10
- MaxClients 100
- MaxRequestsPerChild 1
-</PRE>
+You will notice many httpd_perl executables running on your system, but you
+should not send signals to any of them except the parent, whose pid is in
+the <CODE>PidFile</CODE>. That is to say you shouldn't ever need to send signals to any process
+except the parent. There are three signals that you can send the parent:
+TERM, HUP, and USR1.
+
<P>
-<PRE> % ./ab -n 1000 -c 50 www-pais:81/perl/access/access.cgi
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Implications_of_sending_TERM_HU">Implications of sending TERM, HUP, and USR1 to the server</A></H1></CENTER>
<P>
-The benchmark time outed with the above configuration.... I watched the
-output of ps as I run it, the parent process just wasn't capable to respawn
-the killed children in that rate...When I raised the MaxRequestsPerChild to
-10 I've got 8.34 req/sec - very bad (18 times slower!) (You can't benchmark
-the importance of the MinSpareServers, MaxSpareServers and StartServers
-with this kind of test).
+We will concentrate here on the implications of sending these signals to a
+mod_perl-enabled server. For documentation on the implications of sending
+these signals to a plain Apache server see <A
+HREF="http://www.apache.org/docs/stopping.html">http://www.apache.org/docs/stopping.html</A>
+.
+<DL>
+<P><DT><STRONG><A NAME="item_TERM">TERM Signal: stop now</A></STRONG><DD>
<P>
-Now let's try to return MaxRequestsPerChild to 1500, but to lower the
-MaxClients to 10 and run the same test:
+Sending the TERM signal to the parent causes it to immediately attempt to
+kill off all of its children. This process may take several seconds to
+complete, following which the parent itself exits. Any requests in progress
+are terminated, and no further requests are served.
<P>
-<PRE> MinSpareServers 8
- MaxSpareServers 6
- StartServers 10
- MaxClients 10
- MaxRequestsPerChild 1500
-</PRE>
+That's the moment that the accumulated END{} blocks will be executed! Note
+that if you use <STRONG>Apache::Registry</STRONG> or <STRONG>Apache::PerlRun</STRONG>, then END {} blocks are being executed upon each request (at the end).
+
+<P><DT><STRONG><A NAME="item_HUP">HUP Signal: restart now</A></STRONG><DD>
<P>
-I have got 27.12 req/sec, which is better but still 4-5 times slower (133
-with MaxClients of 50)
+Sending the HUP signal to the parent causes it to kill off its children
+like in TERM (Any requests in progress are terminated) but the parent
+doesn't exit. It re-reads its configuration files, and re-opens any log
+files. Then it spawns a new set of children and continues serving hits.
<P>
-<STRONG>Summary:</STRONG> I have tested a few combinations of server configuration variables
-(MinSpareServers MaxSpareServers StartServers MaxClients
-MaxRequestsPerChild). And the results we have received are as follows:
+The server will reread its configuration files, flush all the compiled and
+preloaded modules, and rerun any startup files. It's equivalent to
+stopping, then restarting a server.
<P>
-MinSpareServers, MaxSpareServers and StartServers are only important for
-user respond times (sometimes user will have to wait a bit).
+Note: If your configuration file has errors in it when you issue a restart
+then your parent will not restart but exit with an error. See below for a
+method of avoiding this.
+<P><DT><STRONG><A NAME="item_USR1">USR1 Signal: graceful restart</A></STRONG><DD>
<P>
-The important parameters are MaxClients and MaxRequestsPerChild. MaxClients
-should be not to big so it will not abuse your machine's memory resources
-and not too small, when users will be forced to wait for the children to
-become free to come serve them. MaxRequestsPerChild should be as big as
-possible, to take the full benefit of the mod_perl, but watch your server
-at the beginning to make sure your scripts are not leaking memory causing
-your server (and your service) to die very fast.
+The USR1 signal causes the parent process to advise the children to exit
+after their current request (or to exit immediately if they're not serving
+anything). The parent re-reads its configuration files and re-opens its log
+files. As each child dies off the parent replaces it with a child from the
+new generation of the configuration, which begins serving new requests
+immediately.
<P>
-Also it is important to understand that we didn't test the respond times in
-the tests above, but the ability of the server to respond. If the script
-that was used to test was heavier, the numbers would be different but the
-conclusions are very similar.
+The only difference between USR1 and HUP is that USR1 allows children to
+complete any in-progress request prior to killing them off.
<P>
-The benchmarks were run at:
+By default, if a server is restarted (ala <CODE>kill -USR1 `cat
+logs/httpd.pid`</CODE> or with HUP signal), Perl scripts and modules are not reloaded. To reload <STRONG>PerlRequire</STRONG>'s, <STRONG>PerlModule</STRONG>'s, other <CODE>use()'d</CODE> modules and flush the Apache::Registry
+cache, enable with this command:
<P>
-<PRE> HW: RS6000, 1Gb RAM
- SW: AIX 4.1.5 . mod_perl 1.16, apache 1.3.3
- Machine running only mysql service, httpd docs and mod_perl servers.
- Machine was completely unloaded during the benchmarking.
+<PRE> PerlFreshRestart On (in httpd.conf)
</PRE>
-<P>
-After each server restart when I did changes to server's configurations, I
-made sure the scripts were preloaded by fetching a script at least one time
-by each child.
-
<P>
-It is important to notice that None of requests time outed even if was kept
-in server's queue form more than 1 minute! (That is the way <STRONG>ab</STRONG>
-works, which is OK for the test but will not for the real world - user will
-not wait for more than 5-10 secs for a request to complete, and the browser
-will timeout in a 30 secs or so)
+Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
+</DL>
<P>
-Now let me take a real code whose execution time is bigger than a few
-msecs. Will will do real testing and collect the data in tables for easier
-view.
+It's worth mentioning that restart or termination can sometimes take quite
+a lot of time. Check out the PERL_DESTRUCT_LEVEL=-1 option during the
+mod_perl ./Configure stage, which speeds this up and leads to more robust
+operation in the face of problems, like running out of memory. It is only
+usable if no significant cleanup has to be done by perl END{} blocks and
+DESTROY methods when the child terminates, of course. What constitutes
+significant cleanup? Any change of state outside of the current process
+that would not be handled by the operating system itself. So committing
+database transactions is significant but closing an ordinary file isn't.
<P>
-I will use the following abbreviations
+Some folks prefer to specify signals using numerical values, rather than
+symbolics. If you are looking for these, check out your
+<CODE>kill(3)</CODE> man page. My page points to
+<CODE>/usr/include/sys/signal.h</CODE>, the relevant entries are:
<P>
-<PRE> NR = Number of Request Total
- NC = Number of multiple requests to make
- MC = MaxClients
- MRPC = MaxRequestsPerChild
- RPS = Requests per second
+<PRE> #define SIGHUP 1 /* hangup, generated when terminal disconnects */
+ #define SIGTERM 15 /* software termination signal */
+ #define SIGUSR1 30 /* user defined signal 1 */
</PRE>
<P>
-Running a mod_perl script with lots of mysql queries (script mysqld
-bounded) (http://www:81/perl/access/access.cgi?do_sub=query_form)
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Using_apachectl_to_control_the_s">Using apachectl to control the server</A></H1></CENTER>
+<P>
+Apache's distribution provides a nice script to control the server. It's
+called <STRONG>apachectl</STRONG> and it's installed into the same location with httpd. In our scenario -
+it's /usr/apps/sbin/httpd_perl/apachectl
<P>
-<PRE> MinSpareServers 8
- MaxSpareServers 16
- StartServers 10
- MaxClients 50
- MaxRequestsPerChild 5000
-</PRE>
+Start httpd
+
<P>
-<PRE> NR NC RPS comment
- ------------------------------------------------
- 10 10 3.33 # not a reliable stats
- 100 10 3.94
- 1000 10 4.62
- 1000 50 4.09
+<PRE> % /usr/apps/sbin/httpd_perl/apachectl start
</PRE>
<P>
-Conclusions: Here I wanted to show that when the application is slow not
-because of perl loading, script compiling and execution, but bounded to
-some external operation like mysqld querying which made the bottleneck - it
-almost does not matter what is the load we make - the RPS (Requests per
-second) is almost the same (taken that all the requested has been served,
-you have an ability to queue the clients, but be aware that something that
-goes to queue means a waiting client and browser can get time outed!)
+Stop httpd
<P>
-Now we will benchmark the same script without using the mysql (perl only
-bounded) (http://www.you.com:81/perl/access/access.cgi)
+<PRE> % /usr/apps/sbin/httpd_perl/apachectl stop
+</PRE>
+<P>
+Restart httpd if running by sending a SIGHUP or start if not running
<P>
-<PRE> MinSpareServers 8
- MaxSpareServers 16
- StartServers 10
- MaxClients 50
- MaxRequestsPerChild 5000
+<PRE> % /usr/apps/sbin/httpd_perl/apachectl restart
</PRE>
<P>
-<PRE> NR NC RPS comment
- ------------------------------------------------
- 10 10 26.95 # not a reliable stats
- 100 10 30.88
- 1000 10 29.31
- 1000 50 28.01
- 1000 100 29.74
- 10000 200 24.92
- 100000 400 24.95
+Do a graceful restart by sending a SIGUSR1 or start if not running
+
+<P>
+<PRE> % /usr/apps/sbin/httpd_perl/apachectl graceful
</PRE>
<P>
-Conclusions: This time the script we executed was a pure perl (not bounded
-to I/O or mysql), so we see that the server serves the requests much
-faster. You can see the RequestPerSecond (RPS) is almost the same for any
-load, but goes lower when the number of concurrent clients goes beyond the
-MaxClients. With 25 RPS, the client in load of 400 concurrent clients will
-be served in 16 secs. But to get more realistic and assume the max
-concurrency of 100, with 30 RPS, the client will be served in 3.5 secs,
-which is pretty good for a highly loaded server.
+Do a configuration syntax test:
<P>
-Now we will use the server for its full capacity, by keeping all MaxClients
-alive all the time and having a big MaxRequestsPerChild, so no server will
-be killed during the benchmarking.
+<PRE> % /usr/apps/sbin/httpd_perl/apachectl configtest
+</PRE>
+<P>
+See the next section for the implication of the above calls.
<P>
-<PRE> MinSpareServers 50
- MaxSpareServers 50
- StartServers 50
- MaxClients 50
- MaxRequestsPerChild 5000
-
- NR NC RPS comment
- ------------------------------------------------
- 100 10 32.05
- 1000 10 33.14
- 1000 50 33.17
- 1000 100 31.72
- 10000 200 31.60
-</PRE>
+Replace 'httpd_perl' with 'httpd_docs' in the above calls to control the
+httpd_docs server.
+
<P>
-Conclusion: In this scenario there is no overhead for parent server to load
-new children, all the servers are available, and the only bottleneck is a
-rival over the CPU
+There are other options for <STRONG>apachectl</STRONG>, use 'help' option to see them all.
<P>
-Now we will try to change the MaxClients and to watch the results: Let's
-reduce MC to 10.
+It's important to understand that this script is based on the PID file
+which is PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid. If you delete the
+file by hand - <STRONG>apachectl</STRONG> will fail to run.
<P>
-<PRE> MinSpareServers 8
- MaxSpareServers 10
- StartServers 10
- MaxClients 10
- MaxRequestsPerChild 5000
-
- NR NC RPS comment
- ------------------------------------------------
- 10 10 23.87 # not a reliable stats
- 100 10 32.64
- 1000 10 32.82
- 1000 50 30.43
- 1000 100 25.68
- 1000 500 26.95
- 2000 500 32.53
-</PRE>
+Also, note that <STRONG>apachectl</STRONG> is suitable to use from within your Unix system's startup files so that
+your web server is automatically restarted upon system reboot. Either copy
+the <STRONG>apachectl</STRONG> file to the appropriate location (<CODE>/etc/rc.d/rc3.d/S99apache</CODE> works on my RedHat Linux system) or create a symlink with that name
+pointing to the the canonical location. (If you do this, make certain that
+the script is writable only by root -- the startup scripts have root
+privileges during init processing, and you don't want to be opening any
+security holes.)
+
<P>
-Conclusions: Very little difference! Almost no change! 10 servers were able
-to serve almost with the same throughput as 50 servers. Why? My guess it's
-because of CPU , Seems that 10 servers were serving 5 times faster the
-requests then when in the test above we worked with 50 servers. In the case
-above each child received its CPU time slice 5 times less frequently. So
-having a big value for MaxClients, doesn't mean that the performance will
-be better. You have just saw the numbers!
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="SUID_start_up_scripts">SUID start-up scripts</A></H1></CENTER>
+<P>
+For those who wants to use SUID startup script, here is an example for you.
+This script is SUID to <STRONG>root</STRONG>, and should be executable only by members of some special group at your
+site. Note the 10th line, which ``fixes an obscure error when starting
+apache/mod_perl'' by setting the real to the effective UID. As others have
+pointed out, it is the mismatch between the real and the effective UIDs
+that causes Perl to croak on the -e switch.
<P>
-Now we will start to reduce drastically the MaxRequestsPerClient
+Note that you must be using a version of Perl that recognizes and emulates
+the suid bits in order for this to work. The script will do different
+things depending on whether it is named ``start_http'', ``stop_http'' or
+``restart_http''. You can use symbolic links for this purpose.
<P>
-<PRE> MinSpareServers 8
- MaxSpareServers 16
- StartServers 10
- MaxClients 50
-
- NR NC MRPC RPS comment
- ------------------------------------------------
- 100 10 10 5.77
- 100 10 5 3.32
- 1000 50 20 8.92
- 1000 50 10 5.47
- 1000 50 5 2.83
- 1000 100 10 6.51
+<PRE> #!/usr/bin/perl
+
+ # These constants will need to be adjusted.
+ $PID_FILE = '/home/www/logs/httpd.pid';
+ $HTTPD = '/home/www/httpd -d /home/www';
+
+ # These prevent taint warnings while running suid
+ $ENV{PATH}='/bin:/usr/bin';
+ $ENV{IFS}='';
+
+ # This sets the real to the effective ID, and prevents
+ # an obscure error when starting apache/mod_perl
+ $< = $>;
+ $( = $) = 0; # set the group to root too
+
+ # Do different things depending on our name
+ ($name) = $0 =~ m|([^/]+)$|;
+
+ if ($name eq 'start_http') {
+ system $HTTPD and die "Unable to start HTTP";
+ print "HTTP started.\n";
+ exit 0;
+ }
+
+ # extract the process id and confirm that it is numeric
+ $pid = `cat $PID_FILE`;
+ $pid =~ /(\d+)/ or die "PID $pid not numeric";
+ $pid = $1;
+
+ if ($name eq 'stop_http') {
+ kill 'TERM',$pid or die "Unable to signal HTTP";
+ print "HTTP stopped.\n";
+ exit 0;
+ }
+
+ if ($name eq 'restart_http') {
+ kill 'HUP',$pid or die "Unable to signal HTTP";
+ print "HTTP restarted.\n";
+ exit 0;
+ }
+
+ die "Script must be named start_http, stop_http, or restart_http.\n";
</PRE>
<P>
-Conclusions: When we reduce drastically the MaxRequestsPerClient, the
-performance starts to become closer to the plain mod_cgi. Just for compare
-with mod_cgi, here are the numbers of run with mod_cgi:
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Monitoring_the_Server_A_watchdo">Monitoring the Server. A watchdog.</A></H1></CENTER>
+<P>
+With mod_perl many things can happen to your server. The worst one is the
+possibility that the server will die when you will be not around. As with
+any other critical service you need to run some kind of watchdog.
<P>
-<PRE> MinSpareServers 8
- MaxSpareServers 16
- StartServers 10
- MaxClients 50
-
- NR NC RPS comment
- ------------------------------------------------
- 100 10 1.12
- 1000 50 1.14
- 1000 100 1.13
-</PRE>
+One simple solution is to use a slightly modified <STRONG>apachectl</STRONG> script which I called apache.watchdog and to put it into the crontab to be
+called every 30 minutes or even every minute - if it's so critical to make
+sure the server will be up all the time.
+
<P>
-Conclusion: mod_cgi is much slower :) in test NReq/NClients 100/10 the RPS
-in mod_cgi 1.12 and in mod_perl 32 => 30 times faster !!! In the first
-test each child waited about 100 secs to be served. In the second and third
-1000 secs!
+Crontab entry:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Tuning_with_crashme_script">Tuning with crashme script</A></H2></CENTER>
+<PRE> 0,30 * * * * /path/to/the/apache.watchdog >/dev/null 2>&1
+</PRE>
<P>
-This is another crashme suite originally written by Michael Schilli and
-located at <A
-HREF="http://www.linux-magazin.de/ausgabe.1998.08/Pounder/pounder.html">http://www.linux-magazin.de/ausgabe.1998.08/Pounder/pounder.html</A>
-. I did a few modifications (mostly adding <CODE>my()</CODE> ops :). I also
-allowed it to accept more then one url, since sometimes you want to test
-overall and not just one script.
+The script:
<P>
-The tool provides the same results as <STRONG>ab</STRONG> above but it also allows you to set the timeout value, so requests will
-fail if not served before time outed. You also get Latency (secs/Request)
-and Throughput (Requests/sec) numbers. It can give you a better picture and
-make a complete simulation of your favorite Netscape browser :)
+<PRE> #!/bin/sh
+
+ # this script is a watchdog to see whether the server is online
+ # It tries to restart the server if it's
+ # down and sends an email alert to admin
+
+ # admin's email
+ EMAIL=webmaster@somewhere.far
+ #EMAIL=root@localhost
+
+ # the path to your PID file
+ PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid
+
+ # the path to your httpd binary, including options if necessary
+ HTTPD=/usr/apps/sbin/httpd_perl/httpd_perl
+
+ # check for pidfile
+ if [ -f $PIDFILE ] ; then
+ PID=`cat $PIDFILE`
+
+ if kill -0 $PID; then
+ STATUS="httpd (pid $PID) running"
+ RUNNING=1
+ else
+ STATUS="httpd (pid $PID?) not running"
+ RUNNING=0
+ fi
+ else
+ STATUS="httpd (no pid file) not running"
+ RUNNING=0
+ fi
+
+ if [ $RUNNING -eq 0 ]; then
+ echo "$0 $ARG: httpd not running, trying to start"
+ if $HTTPD ; then
+ echo "$0 $ARG: httpd started"
+ mail $EMAIL -s "$0 $ARG: httpd started" </dev/null >& /dev/null
+ else
+ echo "$0 $ARG: httpd could not be started"
+ mail $EMAIL -s "$0 $ARG: httpd could not be started" </dev/null >& /dev/null
+ fi
+ fi
+</PRE>
+<P>
+Another approach, probably even more practical, is to use the Cool LWP perl
+package , to test the server by trying to fetch some document (script)
+served by the server. Why is it more practical? While server can be up as a
+process, it can be stuck and not working (SYN_RECV state - anyone??? Am I
+getting a SYNC flood attack), So failing to get the document will trigger
+restart, and ``probably'' the problem will go away. (Just replace <CODE>start</CODE> with <CODE>restart</CODE> in the
+<CODE>$restart_command</CODE> below.
<P>
-I have noticed while running these 2 benchmarking suites - <STRONG>ab</STRONG> gave me results 2.5-3.0 times better. Both suites run on the same machine
-with the same load with the same parameters. Weird ha? Any ideas why? Again
-C vs Perl question :(
+Again we put this script into a crontab to call it every 30 minutes.
+Personally I call it every minute, to fetch some very light script. Why so
+often? If your server starts to spin and trash your disk's space with
+multiply error messages. In a 5 minutes you might run out of free space,
+which might bring your system to its knees. And most chances that no other
+child will be able to serve requests, since the system will be too busy,
+writing to an <CODE>error_log</CODE> file. Think big - if you running a heavy service, which is very fast, since
+you are running under mod_perl, adding one more request every minute, will
+be not felt by the server at all.
<P>
-Sample output:
+So we end up with crontab entry:
<P>
-<PRE> URL(s): <A HREF="http://www.you.com:81/perl/access/access.cgi">http://www.you.com:81/perl/access/access.cgi</A>
- Total Requests: 100
- Parallel Agents: 10
- Succeeded: 100 (100.00%)
- Errors: NONE
- Total Time: 9.39 secs
- Throughput: 10.65 Requests/sec
- Latency: 0.85 secs/Request
+<PRE> * * * * * /path/to/the/watchdog.pl >/dev/null 2>&1
</PRE>
<P>
-And the code:
+And the watchdog itself:
<P>
-<PRE> #!/usr/apps/bin/perl -w
+<PRE> #!/usr/local/bin/perl -w
- use LWP::Parallel::UserAgent;
- use Time::HiRes qw(gettimeofday tv_interval);
use strict;
-
- ###
- # Configuration
- ###
-
- my $nof_parallel_connections = 10;
- my $nof_requests_total = 100;
- my $timeout = 10;
- my @urls = (
- '<A HREF="http://www.you.com:81/perl/faq_manager/faq_manager.pl">http://www.you.com:81/perl/faq_manager/faq_manager.pl</A>',
- '<A HREF="http://www.you.com:81/perl/access/access.cgi">http://www.you.com:81/perl/access/access.cgi</A>',
- );
-
-
- ##################################################
- # Derived Class for latency timing
- ##################################################
+ use diagnostics;
+ use URI::URL;
+ use LWP::MediaTypes qw(media_suffix);
- package MyParallelAgent;
- @MyParallelAgent::ISA = qw(LWP::Parallel::UserAgent);
- use strict;
+ my $VERSION = '0.01';
+ use vars qw($ua $proxy);
- ###
- # Is called when connection is opened
- ###
- sub on_connect {
- my ($self, $request, $response, $entry) = @_;
- $self->{__start_times}->{$entry} = [Time::HiRes::gettimeofday];
- }
+ require LWP::UserAgent;
+ use HTTP::Status;
- ###
- # Are called when connection is closed
- ###
- sub on_return {
- my ($self, $request, $response, $entry) = @_;
- my $start = $self->{__start_times}->{$entry};
- $self->{__latency_total} += Time::HiRes::tv_interval($start);
- }
+ ###### Config ########
+ my $test_script_url = '<A HREF="http://www.stas.com:81/perl/test.pl">http://www.stas.com:81/perl/test.pl</A>';
+ my $monitor_email = 'root@localhost';
+ my $restart_command = '/usr/apps/sbin/httpd_perl/apachectl start';
+ my $mail_program = '/usr/lib/sendmail -t -n';
+ ######################
- sub on_failure {
- on_return(@_); # Same procedure
- }
+ $ua = new LWP::UserAgent;
+ $ua->agent("$0/Stas " . $ua->agent);
+ # Uncomment the proxy if you don't use it!
+ # $proxy="<A HREF="http://www-proxy.com"">http://www-proxy.com"</A>;;
+ $ua->proxy('http', $proxy) if $proxy;
- ###
- # Access function for new instance var
- ###
- sub get_latency_total {
- return shift->{__latency_total};
- }
+ # If returns '1' it's we are alive
+ exit 1 if checkurl($test_script_url);
- ##################################################
- package main;
- ##################################################
- ###
- # Init parallel user agent
- ###
- my $ua = MyParallelAgent->new();
- $ua->agent("pounder/1.0");
- $ua->max_req($nof_parallel_connections);
- $ua->redirect(0); # No redirects
+ # We have got the problem - the server seems to be down. Try to
+ # restart it.
+ my $status = system $restart_command;
+ # print "Status $status\n";
- ###
- # Register all requests
- ###
- foreach (1..$nof_requests_total) {
- foreach my $url (@urls) {
- my $request = HTTP::Request->new('GET', $url);
- $ua->register($request);
- }
- }
+ my $message = ($status == 0)
+ ? "Server was down and successfully restarted!"
+ : "Server is down. Can't restart.";
+
+ my $subject = ($status == 0)
+ ? "Attention! Webserver restarted"
+ : "Attention! Webserver is down. can't restart";
- ###
- # Launch processes and check time
- ###
- my $start_time = [gettimeofday];
- my $results = $ua->wait($timeout);
- my $total_time = tv_interval($start_time);
+ # email the monitoring person
+ my $to = $monitor_email;
+ my $from = $monitor_email;
+ send_mail($from,$to,$subject,$message);
- ###
- # Requests all done, check results
- ###
+ # input: URL to check
+ # output: 1 if success, o for fail
+ #######################
+ sub checkurl{
+ my ($url) = @_;
- my $succeeded = 0;
- my %errors = ();
+ # Fetch document
+ my $res = $ua->request(HTTP::Request->new(GET => $url));
- foreach my $entry (values %$results) {
- my $response = $entry->response();
- if($response->is_success()) {
- $succeeded++; # Another satisfied customer
- } else {
- # Error, save the message
- $response->message("TIMEOUT") unless $response->code();
- $errors{$response->message}++;
- }
- }
+ # Check the result status
+ return 1 if is_success($res->code);
- ###
- # Format errors if any from %errors
- ###
- my $errors = join(',', map "$_ ($errors{$_})", keys %errors);
- $errors = "NONE" unless $errors;
+ # failed
+ return 0;
+ } # end of sub checkurl
- ###
- # Format results
- ###
+ # sends email about the problem
+ #######################
+ sub send_mail{
+ my($from,$to,$subject,$messagebody) = @_;
- #@urls = map {($_,".")} @urls;
- my @P = (
- "URL(s)" => join("\n\t\t ", @urls),
- "Total Requests" => "$nof_requests_total",
- "Parallel Agents" => $nof_parallel_connections,
- "Succeeded" => sprintf("$succeeded (%.2f%%)\n",
- $succeeded * 100 / $nof_requests_total),
- "Errors" => $errors,
- "Total Time" => sprintf("%.2f secs\n", $total_time),
- "Throughput" => sprintf("%.2f Requests/sec\n",
- $nof_requests_total / $total_time),
- "Latency" => sprintf("%.2f secs/Request",
- $ua->get_latency_total() /
- $nof_requests_total),
- );
+ open MAIL, "|$mail_program"
+ or die "Can't open a pipe to a $mail_program :$!\n";
+
+ print MAIL <<__END_OF_MAIL__;
+ To: $to
+ From: $from
+ Subject: $subject
+ $messagebody
- my ($left, $right);
- ###
- # Print out statistics
- ###
- format STDOUT =
- @<<<<<<<<<<<<<<< @*
- "$left:", $right
- .
+ __END_OF_MAIL__
- while(($left, $right) = splice(@P, 0, 2)) {
- write;
- }
+ close MAIL;
+ }
</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Choosing_MaxClients">Choosing MaxClients</A></H2></CENTER>
+<CENTER><H1><A NAME="Running_server_in_a_single_mode">Running server in a single mode</A></H1></CENTER>
<P>
-The <CODE>MaxClients</CODE> directive sets the limit on the number of simultaneous requests that can be
-supported; not more than this number of child server processes will be
-created. To configure more than 256 clients, you must edit the
-HARD_SERVER_LIMIT entry in httpd.h and recompile. In our case we want to
-set this variable to as little as possible number, this way we can
-virtually bound the resources used by the server children. If we know that
-we have X Mb of RAM, each child consumes a maximum of Y Mb of RAM (we can
-restrict each child See
-<A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>) and we have the all these X Mb dedicated for the webserver. Then
-calculation of
-<CODE>MaxClients</CODE> is pretty straightforward :
+Often while developing new code, you will want to run the server in single
+process mode. See <A HREF="././porting.html#Sometimes_it_Works_Sometimes_Not">Sometimes it works Sometimes Not</A> and <A HREF="././porting.html#Name_collisions_with_Modules_and">Names collisions with Modules and libs</A>
+Running in single process mode inhibits the server from ``daemonizing'',
+allowing you to run it more easily under debugger control.
<P>
-<PRE> MaxClients = Total Available to the webserver RAM / MAX child's size
+<PRE> % /usr/apps/sbin/httpd_perl/httpd_perl -X
</PRE>
<P>
-So If I have 400Mb left for the the webserver to run . I can set the
-<CODE>MaxClients</CODE> to be of 40 if I know that each child is bounded to the 10Mb of memory
-(with Apache::SizeLimit, See the reference above)
+When you execute the above the server will run in the fg (foreground) of
+the shell you have called it from. So to kill you just kill it with Ctrl-C.
<P>
-Certainly you will wander what happens to your server if there are more
-than <CODE>MaxClients</CODE> concurrent users at some moment. This situation is accompanied by the
-following warning message into the <CODE>error.log</CODE>
-file:
+Note that in -X mode the server will run very slowly while fetching images.
+If you use Netscape while your server is running in single-process mode,
+HTTP's ``KeepAlive'' feature gets in the way. Netscape tries to open
+multiple connections and keep them open. Because there is only one server
+process listening, each connection has to time-out before the next
+succeeds. Turn off KeepAlive in httpd.conf to avoid this effect while
+developing or you can press <STRONG>STOP</STRONG> after a few seconds (assuming you use the image size params, so the
+Netscape will be able to render the rest of the page).
-<P>
-<PRE> [Sun Jan 24 12:05:32 1999] [error] server reached MaxClients setting,
- consider raising the MaxClients setting
-</PRE>
<P>
-No problem - any connection attempts over the <CODE>MaxClients</CODE> limit will normally be queued, up to a number based on the ListenBacklog
-directive. Once a child process is freed at the end of a different request,
-the connection will then be serviced.
+In addition you should know that when running with -X you will not see any
+control messages that the parent server normally writes to the error_log.
+(Like ``server started, server stopped and etc''.) Since
+<CODE>httpd -X</CODE> causes the server to handle all requests itself, without forking any
+children, there is no controlling parent to write status messages.
<P>
-It <STRONG>is</STRONG> an error because clients are being put in the queue rather than getting
-serviced at once, but they do not get an error response. The error can be
-allowed to persist to balance available system resources and response time,
-but sooner or later you will need to get more RAM so you can start more
-children. The best thing is not to have this condition reached at all.
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Starting_a_personal_server_for_e">Starting a personal server for each developer</A></H1></CENTER>
<P>
-It's important to understand what is child's memory size? If your children
-can share some memory (when OS supports that and you worry to let the
-sharing happen - See <A HREF="././performance.html#Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A>). If this is the case chances that your <CODE>MaxClients</CODE> can be even higher. But seems that it's not so simple to calculate the
-absolute number. (If you come up with solution please let me know)
+If you are the only developer working on the specific server:port - you
+have no problems, since you have a complete control over the server.
+However, many times you have a group of developers who need to concurrently
+develop their own mod_perl scripts. This means that each one will want to
+have control over the server - to kill it, to run it in single server mode,
+to restart it again, etc., as well to have control over the location of the
+log files and other configuration settings like <STRONG>MaxClients</STRONG>, etc. You can work around this problem by preparing a few httpd.conf file
+and forcing each developer to use:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Choosing_MaxRequestsPerChild">Choosing MaxRequestsPerChild</A></H2></CENTER>
+<PRE> httpd_perl -f /path/to/httpd.conf
+</PRE>
<P>
-The <CODE>MaxRequestsPerChild</CODE> directive sets the limit on the number of requests that an individual child
-server process will handle. After
-<CODE>MaxRequestsPerChild</CODE> requests, the child process will die. If
-<CODE>MaxRequestsPerChild</CODE> is 0, then the process will never expire.
+I have approached it in other way. I have used the -Dparameter startup
+option of the server. I call my version of the server
<P>
-Setting <CODE>MaxRequestsPerChild</CODE> to a non-zero limit has two beneficial effects: solves memory leakages and
-helps reduce the number of processes when the server load reduces.
-
+<PRE> % http_perl -Dsbekman
+</PRE>
<P>
-The first reason is the most crucial for mod_perl, since dirty programming
-will cause a child process to consume more memory after each request. If
-left unbounded after a certain number of requests children will it up all
-the available memory and leave the server to die in memory starvation :).
-Note, that sometimes some standard modules leaks memory, on OSes where
-memory managements is bad (Solaris 2.5 on x86 ?)
+In <CODE>httpd.conf</CODE> I wrote:
<P>
-If this is your case you can set <CODE>MaxRequestsPerChild</CODE> to a small number, which will allow the parent to kill the memory greedy
-son after <CODE>MaxRequestsPerChild</CODE> requests. But then you loose all the speed bonuses you receive with
-mod_perl, and you better fall back to run in plain mod_cgi, since the
-overhead of reloading the script and the perl on each request will be too
-high. Consider using Apache::PerlRun if this is your case. Also setting
-MaxSpareServers to number close to
-<CODE>MaxClients</CODE>, will make the respond time faster (but your parent process will be busy
-to respawn new children all the time!)
-
+<PRE> # Personal development Server for sbekman
+ # sbekman use the server running on port 8000
+ <IfDefine sbekman>
+ Port 8000
+ PidFile /usr/apps/var/httpd_perl/run/httpd.pid.sbekman
+ ErrorLog /usr/apps/var/httpd_perl/logs/error_log.sbekman
+ Timeout 300
+ KeepAlive On
+ MinSpareServers 2
+ MaxSpareServers 2
+ StartServers 1
+ MaxClients 3
+ MaxRequestsPerChild 15
+ </IfDefine>
+
+ # Personal development Server for userfoo
+ # userfoo use the server running on port 8001
+ <IfDefine userfoo>
+ Port 8001
+ PidFile /usr/apps/var/httpd_perl/run/httpd.pid.userfoo
+ ErrorLog /usr/apps/var/httpd_perl/logs/error_log.userfoo
+ Timeout 300
+ KeepAlive Off
+ MinSpareServers 1
+ MaxSpareServers 2
+ StartServers 1
+ MaxClients 5
+ MaxRequestsPerChild 0
+ </IfDefine>
+</PRE>
<P>
-Another approach is to use Apache::SizeLimit (See <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>). By using this module, you should be able to discontinue using the
-<CODE>MaxRequestsPerChild</CODE>, although for some folks, using both in combination does the job.
+What we have achieved with this technique: Full control over start/stop,
+number of children, separate error log file, and port selection. This saves
+me from getting called every few minutes - ``Stas, I'm going to restart the
+server''.
<P>
-See also <A HREF="././performance.html#Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A> and
-<A HREF="././performance.html#Memory_sharing">Memory sharing</A>.
+To make things even easier. (In the above technique, you have to discover
+the PID of your parent httpd_perl process - written in
+/usr/apps/var/httpd_perl/run/httpd.pid.userfoo) . We change the
+<STRONG>apachectl</STRONG> script to do the work for us. We make a copy for each developer called <STRONG>apachectl.username</STRONG> and we change 2 lines in script:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Choosing_MinSpareServers_MaxSpa">Choosing MinSpareServers, MaxSpareServers and StartServers</A></H2></CENTER>
+<PRE> PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid.sbekman
+ HTTPD='/usr/apps/sbin/httpd_perl/httpd_perl -Dsbekman'
+</PRE>
<P>
-With mod_perl it might take up to a 30-50 secs before the new server is
-ready to serve the requests. It depends on OS, number of preloaded modules
-and the load of the machine. So you better set <CODE>StartServers</CODE>
-and <CODE>MinSpareServers</CODE> to a big numbers so if you get a high load after the server has been just
-restarted, the fresh servers will be ready to serve on the first demand.
-It's good for mod_perl to raise all 3 variables up, Since with mod_perl you
-don't want to kill the servers when not in use, on opposite you want them
-to stay up. (For the same reason of the heavy and slow load). I think an
-ideal configuration is with <CODE>MinSpareServers</CODE> and <CODE>MaxSpareServers</CODE> of similar values, even the same. Having the <CODE>MaxSpareServers</CODE> close to
-<CODE>MaxClients</CODE> will use completely all of your resources (if <CODE>MaxClients</CODE>
-has been chosen to take the full advantage of the resources), but it'll
-make sure that in any given moment your system will be capable of
-responding to request with the maximum speed (taken that number of
-concurrent requests is not higher then <CODE>MaxClients</CODE>)
+Of course you think you can use only one control file and know who is
+calling by using uid, but since you have to be root to start the server -
+it is not so simple.
<P>
-Let me try some numbers. For the heavily loaded web site and the dedicated
-machine I would think of (note 400Mb is just for the show case):
+The last thing was to let developers an option to run in single process
+mode by:
<P>
-<PRE> Available to webserver RAM: 400Mb
- Child's memory size bounded: 10Mb
- MaxClients: 400/10 = 40
- StartServers: 20
- MinSpareServers: 20
- MaxSpareServers: 35
+<PRE> /usr/apps/sbin/httpd_perl/httpd_perl -Dsbekman -X
</PRE>
<P>
-However if I want to use the server for many other tasks but make it
-capable of the high load, I'd think of:
+In addition to making life easier, we decided to use relative links
+everywhere in the static docs (including the calls to CGIs). You may ask
+how using the relative link you will get to the right server? Very simple -
+we have utilized the mod_rewrite to solve our problems:
<P>
-<PRE> Available to webserver RAM: 400Mb
- Child's memory size bounded: 10Mb
- MaxClients: 400/10 = 40
- StartServers: 5
- MinSpareServers: 5
- MaxSpareServers: 10
+In access.conf of the httpd_docs server we have the following code: (you
+have to configure your httpd_docs server with
+<CODE>--enable-module=rewrite</CODE> )
+
+<P>
+<PRE> # sbekman' server
+ # port = 8000
+ RewriteCond %{REQUEST_URI} ^/(perl|cgi-perl)
+ RewriteCond %{REMOTE_ADDR} 123.34.45.56
+ RewriteRule ^(.*) <A HREF="http://ourserver.com:8000/">http://ourserver.com:8000/</A>$1 [R,L]
+
+ # userfoo's server
+ # port = 8001
+ RewriteCond %{REQUEST_URI} ^/(perl|cgi-perl)
+ RewriteCond %{REMOTE_ADDR} 123.34.45.57
+ RewriteRule ^(.*) <A HREF="http://ourserver.com:8001/">http://ourserver.com:8001/</A>$1 [R,L]
+
+ # all the rest
+ RewriteCond %{REQUEST_URI} ^/(perl|cgi-perl)
+ RewriteRule ^(.*) <A HREF="http://ourserver.com:81/">http://ourserver.com:81/</A>$1 [R]
+
</PRE>
<P>
-(These numbers are taken from the head and it shouldn't be used as rule,
-but to show you some possible scenarios. Use this information wisely!)
+where IP numbers are the IPs of the developers' client machines (where they
+are running their web browser.) (I have tried to use REMOTE_USER since we
+have all the users authenticated but it did not work for me)
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Summary_of_Benchmarking_to_tune_">Summary of Benchmarking to tune all 5 parameters</A></H2></CENTER>
<P>
-OK, we run various benchmarks and what are the conclusions:
+So if I have a relative URL like <CODE>/perl/test.pl</CODE> written in some html or even <A
+HREF="http://ourserver.com/perl/test.pl">http://ourserver.com/perl/test.pl</A>
+in my case (user at machine of sbekman) it will be redirected by httpd_docs
+to <A
+HREF="http://ourserver.com:8000/perl/test.pl">http://ourserver.com:8000/perl/test.pl</A>
-<UL>
-<P><LI><STRONG><A NAME="item_MaxRequestsPerChild">MaxRequestsPerChild</A></STRONG>
-<P>
-If your scripts are clean and don't leak the memory set this variable to a
-number as big as possible (10000?). If you use Apache::SizeLimit, you can
-set this parameter to 0 (equal to infinity).
-<P><LI><STRONG><A NAME="item_StartServers">StartServers</A></STRONG>
<P>
-If you keep a little number of servers most of the time, keep this number
-low. Especially if MaxSpareServers is low and it'll kill the just loaded
-servers before they were utilized at all (if there is no load). If your
-service is heavily loaded make this number close to
-<CODE>MaxClients</CODE> (and keep MaxSpareServers equal to <CODE>MaxClients</CODE> as well)
+Of course you have another problem: The cgi generates some html, which
+should be called again. If it generates a URL with hard coded PORT the
+above scheme will not work. There 2 solutions:
-<P><LI><STRONG><A NAME="item_MinSpareServers">MinSpareServers</A></STRONG>
<P>
-If your server performs other work except web serving, make it low so the
-memory will be freed when there is no big load. If you server's load is
-like a wave (you get a load in bursts) and you want a fast respond for all
-clients at any time you will want to make it high, so new children will be
-respawned in advance.
+First, generate relative URL so it will reuse the technique above, with
+redirect (which is transparent for user) but it will not work if you have
+something to POST (redirect looses all the data!).
-<P><LI><STRONG><A NAME="item_MaxSpareServers">MaxSpareServers</A></STRONG>
<P>
-The logic the same as of MinSpareServers - low if need the machine for
-other tasks, high if it's web dedicated and you want the minimal delay on
-responses.
+Second, use a general configuration module which generates a correct full
+URL according to REMOTE_USER, so if <CODE>$ENV{REMOTE_USER} eq
+'sbekman'</CODE>, I return <A
+HREF="http://ourserver.com:8000/perl/">http://ourserver.com:8000/perl/</A>
+as
+<CODE>cgi_base_url</CODE>. Again this will work if the user is authenticated.
-<P><LI><STRONG><A NAME="item_MaxClients">MaxClients</A></STRONG>
<P>
-Not too low, so you don't get a situation where clients are waiting for
-server to start serving them. (they might wait, but not too long). Don't
-make it high, since if you get a high load and all requests will be
-immediately granted your CPU will have a hard times and if child's size *
-number of running children is bigger than the total available RAM, your
-server will start swapping (which will slow down everything, which in turn
-will make things even more slower, until eventually your machine will die).
-It's important that you make sure that no swap will be normally used. Swap
-is an emergency pool, not a resource to be used on the constant basis. If
-you low on memory and you badly need it - buy it, the memory is amazingly
-cheap these days. But based on the test I conducted above, even if you have
-a plenty of memory like I have (1Gb), pulling <CODE>MaxClients</CODE> sometimes will give you no speedup. The more clients are running the more
-CPU will be utilized, the less CPU time slices each process will receive,
-the latency (the to process the request) will grow, so you didn't get an
-improve. The best approach is to find the minimum requirement for your kind
-of service and the maximum capability of your machine, then start at the
-minimum and start testing like I did, by raising this parameter, until you
-find the point where the curve on the latency or throughput graph stops to
-raise or the ramp becomes smaller. Stop there and use it. Of course when
-you use these parameters in production server, you will have the ability to
-tune them more precisely. Also don't forget that if you add more scripts,
-most probably that the parameters need to be recalculated, since the
-processes will grow in size as you compile in more code.
+All this is good for development. It is better to use the full URLs in
+production, since if you have a static form and the <CODE>Action</CODE> is relative but the static document located on another server, pressing the
+form's submit will cause a redirect to mod_perl server, but all the form's
+data will be lost during the redirect.
-</UL>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Persistent_DB_Connections">Persistent DB Connections</A></H1></CENTER>
+<CENTER><H1><A NAME="Wrapper_to_emulate_the_server_en">Wrapper to emulate the server environment</A></H1></CENTER>
<P>
-Another popular use of mod_perl is to take advantage of it's persistence to
-maintain open database connections. The basic idea goes like so:
+Many times you start off debugging your script by running it from your
+favorite shell. Sometimes you encounter a very weird situation when script
+runs from the shell but dies when called as a CGI. The real problem lies in
+the difference between the environment that is being used by your server
+and your shell. An example can be a different perl path or having PERL5LIB
+env variable which includes paths that are not in the <CODE>@INC</CODE> of
+the perl compiled with mod_perl server and configured during the startup.
<P>
-<PRE> #Apache::Registry script
+The best debugging approach is to write a wrapper that emulates the exact
+environment of the server, by first deleting the environment variables like
+PERL5LIB and calling the same perl binary that it is being used by the
+server. Next, set the environment identical to the server's by copying the
+perl run directives from server startup and configuration files. It will
+also allow you to remove completely the first line of the script - since
+mod_perl skips it and the wrapper knows how to call the script.
+
+<P>
+Below is the example of such a script. Note that we force the -Tw when we
+call the real script. (I have also added the ability to pass params, which
+will not happen when you call the cgi from the web)
+
+<P>
+<PRE> #!/usr/apps/bin/perl -w
+
+ # This is a wrapper example
+
+ # It simulates the web server environment by setting the @INC and other
+ # stuff, so what will run under this wrapper will run under web and
+ # vice versa.
+
+ #
+ # Usage: wrap.pl some_cgi.pl
+ #
+
+ BEGIN{
+ use vars qw($basedir);
+ $basedir = "/usr/apps";
+
+ # we want to make a complete emulation, so we must remove the
+ # user's environment
+ @INC = ();
+
+ # local perl libs
+ push @INC, ("$basedir/lib/perl5/5.00502/aix",
+ "$basedir/lib/perl5/5.00502",
+ "$basedir/lib/perl5/site_perl/5.005/aix",
+ "$basedir/lib/perl5/site_perl/5.005",
+ );
+ }
+
use strict;
- use vars qw($dbh);
+ use File::Basename;
- $dbh ||= SomeDbPackage->connect(...);
+ # process the passed params
+ my $cgi = shift || '';
+ my $params = (@ARGV) ? join(" ", @ARGV) : '';
+
+ die "Usage:\n\t$0 some_cgi.pl\n" unless $cgi;
+
+ # Set the environment
+ my $PERL5LIB = join ":", @INC;
+
+ # if the path includes the directory we extract it and chdir there
+ if ($cgi =~ m|/|) {
+ my $dirname = dirname($cgi);
+ chdir $dirname or die "Can't chdir to $dirname: $! \n";
+ $cgi =~ m|$dirname/(.*)|;
+ $cgi = $1;
+ }
+
+ # run the cgi from the script's directory
+ # Note that we invoke warnings and Taintness ON!!!
+ system qq{$basedir/bin/perl -I$PERL5LIB -Tw $cgi $params};
</PRE>
<P>
-Since <CODE>$dbh</CODE> is a global variable for the child, once the child
-has opened the connection it will use it over and over again, unless you
-perform <CODE>disconnect().</CODE>
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Log_Rotation">Log Rotation</A></H1></CENTER>
<P>
-Be careful to use different names for handlers if you open connection to
-different Databases!
+A little bit off topic but good to know and use with mod_perl where your
+error_log can grow at a 10-100Mb per day rate if your scripts spit out lots
+of warnings...
<P>
-Apache::DBI - allows to make a persistent database connection. With this
-module enabled every connect request to plain DBI module will be forwarded
-to the Apache::DBI module. This looks if a database handle from a previous
-connect request is already stored and if this handle is still valid using
-the ping method. If these two conditions are fulfilled it just returns the
-database handle. If there is no appropriate database handle or if the ping
-method fails, a new connection is established and the handle is stored for
-later re-use. <STRONG>There is no need to delete the disconnect statements from
-your code</STRONG>. They would not do anything because the Apache::DBI module overloads the
-disconnect method with a NOP. On child exit there is no explicit
-disconnect, the child dies and so does the database connection.
+To rotate the logs do:
<P>
-The usage is simple:
+<PRE> mv access_log access_log.renamed
+ kill -HUP `cat httpd.pid`
+ sleep 10; # allow some children to complete requests and logging
+ # now it's safe to use access_log.renamed
+ .....
+</PRE>
+<P>
+The effect of SIGUSR1 and SIGHUP is detailed in: <A
+HREF="http://www.apache.org/docs/stopping.html">http://www.apache.org/docs/stopping.html</A>
+
<P>
-<PRE> httpd.conf
- ----------
- PerlModule Apache::DBI
-</PRE>
+<META>I tried to kill -USR1 and it did not reset the logs!!! kill
+-HUP did work</META>
+
<P>
-It is important, to load this module before any other ApacheDBI module !
+I use this script:
<P>
-<PRE> a script.perl
- ------------
- use DBI;
+<PRE> #!/usr/apps/bin/perl -Tw
+
+ # this script does a log rotation. Called from crontab.
+
use strict;
+ $ENV{PATH}='/bin:/usr/bin';
- my $dbh = DBI->connect( 'DBI:mysql:database', 'user', 'password',
- { autocommit => 0 }
- ) || die $DBI::errstr;
+ ### configuration
+ my @logfiles = qw(access_log error_log);
+ umask 0;
+ my $server = "httpd_perl";
+ my $logs_dir = "/usr/apps/var/$server/logs";
+ my $restart_command = "/usr/apps/sbin/$server/apachectl restart";
+ my $gzip_exec = "/usr/intel/bin/gzip";
- ...rest of program
+ my ($sec,$min,$hour,$mday,$mon,$year) = localtime(time);
+ my $time = sprintf "%0.2d.%0.2d.%0.2d-%0.2d.%0.2d.%0.2d", $year,++$mon,$mday,$hour,$min,$sec;
+ $^I = ".".$time;
+
+ # rename log files
+ chdir $logs_dir;
+ @ARGV = @logfiles;
+ while (<>) {
+ close ARGV;
+ }
+
+ # now restart the server so the logs will be restarted
+ system $restart_command;
+
+ # compress log files
+ foreach (@logfiles) {
+ system "$gzip_exec $_.$time";
+ }
+</PRE>
+<P>
+Randal L. Schwartz contributed this:
+
+<BLOCKQUOTE>
+
+<P>
+Cron fires off setuid script called log-roller that looks like this:
+
+<P>
+<PRE> #!/usr/bin/perl -Tw
+ use strict;
+ use File::Basename;
+
+ $ENV{PATH} = "/usr/ucb:/bin:/usr/bin";
+
+ my $ROOT = "/WWW/apache"; # names are relative to this
+ my $CONF = "$ROOT/conf/httpd.conf"; # master conf
+ my $MIDNIGHT = "MIDNIGHT"; # name of program in each logdir
+
+ my ($user_id, $group_id, $pidfile); # will be set during parse of conf
+ die "not running as root" if $>;
+
+ chdir $ROOT or die "Cannot chdir $ROOT: $!";
+
+ my %midnights;
+ open CONF, "<$CONF" or die "Cannot open $CONF: $!";
+ while (<CONF>) {
+ if (/^User (\w+)/i) {
+ $user_id = getpwnam($1);
+ next;
+ }
+ if (/^Group (\w+)/i) {
+ $group_id = getgrnam($1);
+ next;
+ }
+ if (/^PidFile (.*)/i) {
+ $pidfile = $1;
+ next;
+ }
+ next unless /^ErrorLog (.*)/i;
+ my $midnight = (dirname $1)."/$MIDNIGHT";
+ next unless -x $midnight;
+ $midnights{$midnight}++;
+ }
+ close CONF;
+
+ die "missing User definition" unless defined $user_id;
+ die "missing Group definition" unless defined $group_id;
+ die "missing PidFile definition" unless defined $pidfile;
+
+ open PID, $pidfile or die "Cannot open $pidfile: $!";
+ <PID> =~ /(\d+)/;
+ my $httpd_pid = $1;
+ close PID;
+ die "missing pid definition" unless defined $httpd_pid and $httpd_pid;
+ kill 0, $httpd_pid or die "cannot find pid $httpd_pid: $!";
+
+
+ for (sort keys %midnights) {
+ defined(my $pid = fork) or die "cannot fork: $!";
+ if ($pid) {
+ ## parent:
+ waitpid $pid, 0;
+ } else {
+ my $dir = dirname $_;
+ ($(,$)) = ($group_id,$group_id);
+ ($<,$>) = ($user_id,$user_id);
+ chdir $dir or die "cannot chdir $dir: $!";
+ exec "./$MIDNIGHT";
+ die "cannot exec $MIDNIGHT: $!";
+ }
+ }
+
+ kill 1, $httpd_pid or die "Cannot sighup $httpd_pid: $!";
</PRE>
<P>
-The module provides the additional method:
+And then individual MIDNIGHT scripts can look like this:
<P>
-<PRE> Apache::DBI->connect_on_init($data_source, $username, $auth, \%attr)
+<PRE> #!/usr/bin/perl -Tw
+ use strict;
+
+ die "bad guy" unless getpwuid($<) =~ /^(root|nobody)$/;
+ my @LOGFILES = qw(access_log error_log);
+ umask 0;
+ $^I = ".".time;
+ @ARGV = @LOGFILES;
+ while (<>) {
+ close ARGV;
+ }
</PRE>
-<P>
-This can be used as a simple way to have apache children establish
-connections on server startup. This call should be in a startup file
-(PerlModule, <Perl> or PerlRequire). It will establish a connection
-when a child is started in that child process. See the Apache::DBI manpage
-to see the requirements for this method.
-
-<P>
-However be warned that some old DBD drivers are not supporting this feature
-(ping method), so check the documentation of the driver you use.
-
<P>
-Another problem are timeouts: some databases disconnect the client after a
-certain time of inactivity. ping method ensures that this will not happen.
-Some DBD drivers don't have this method, check the Apache::DBI manpage to
-see how to write a ping method.
+Can you spot the security holes? Our trusted user base can't or won't. :)
+But these shouldn't be used in hostile situations.
-<P>
-Also some folks at list suggested to change the timeout of the server (they
-talked specifically about mysql). So starting from 3.22.x you can set a
-wait_timeout option at mysqld server startup to change the default value,
-setting it to 24 hours probably will fix the timeout problem.
+</BLOCKQUOTE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Why_you_should_not_use_1_unde">Why you should not use $|=1 under mod_perl</A></H1></CENTER>
-<P>
-As you know <CODE>$1=1</CODE> disables the buffering of the current selected file handle (default is
-STDOUT). If you enable it <CODE>ap_rflush()</CODE> is called after each
-<CODE>print(),</CODE> unbuffering Apache's IO.
-
+<CENTER><H1><A NAME="Preventing_from_modperl_process_">Preventing from modperl process to eat up all the disk's space, when it goes wild.</A></H1></CENTER>
<P>
-If you are using the _bad_ style of generating the output, by multiply
-<CODE>print()</CODE> calls or you just have too many of them, you will experience a degradation
-in performance. The severity depends on the number of the calls.
+Sometimes an error happens and causes the server to write millions of lines
+into your error_log file and in a few minutes to put your server down on
+its knees. For example I get an error <CODE>Callback called exit</CODE>
+show up in my error_log file many times. The error_log files grows to 300
+Mbytes in size in a few minutes. You should run a cron job to make sure
+this does not happen and if it does to take care of it. Andreas J. Koenig
+is running this shell script every minute:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Profiling">Profiling</A></H1></CENTER>
+<PRE> S=`ls -s /usr/local/apache/logs/error_log | awk '{print $1}'`
+ if [ "$S" -gt 100000 ] ; then
+ /etc/rc.d/init.d/httpd restart
+ date | /bin/mail -s "error_log $S kB on inx" myemail@domain.com
+ fi
+</PRE>
<P>
-Profiling will help you to determine which subroutines are using the most
-time and which subroutines are being called most often, then you will
-probably will want to optimize those, if your code is a way heavy.
+It seems that his script will trigger restart every minute, since once the
+logfile grows to be of 100000 lines, it will stay of this size, unless you
+remove or rename it, before you do restart. On my server I run a watchdog
+every five minutes which restarts the server if it is getting stuck (it
+always works since when some modperl child process goes wild, the I/O it
+causes is so heavy that other brother processes cannot normally to serve
+the requests.) See <A HREF="././control.html#Monitoring_the_Server_A_watchdo">Monitoring the Server</A> for more hints.
<P>
-It is possible to profile code run under mod_perl with the Devel::DProf
-module available on CPAN. However, you must have apache version 1.3b3 or
-higher and the PerlChildExitHandler enabled. When the server is started,
-Devel::DProf installs an END block to write the tmon.out file, which will
-be run when the server is shutdown. Here's how to start and stop a server
-with the profiler enabled:
+Also check out the daemontools from <A
+HREF="ftp://koobera.math.uic.edu/www/daemontools.html">ftp://koobera.math.uic.edu/www/daemontools.html</A>
+
<P>
-<PRE> % setenv PERL5OPT -d:DProf
- % httpd -X -d `pwd` &
- ... make some requests to the server here ...
- % kill `cat logs/httpd.pid`
- % unsetenv PERL5OPT
- % dprofpp
+<PRE> ,-----
+ | cyclog writes a log to disk. It automatically synchronizes the log
+ | every 100KB (by default) to guarantee data integrity after a crash. It
+ | automatically rotates the log to keep it below 1MB (by default). If
+ | the disk fills up, cyclog pauses and then tries again, without losing
+ | any data.
+ `-----
</PRE>
-<P>
-The Devel::DProf package is a Perl code profiler. This will collect
-information on the execution time of a Perl script and of the subs in that
-script. This information can be used to determine which subroutines are
-using the most time and which subroutines are being called most often.
-
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -8360,7 +11542,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="multiuser.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="status.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -8372,8 +11555,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
@@ -8403,8 +11586,11 @@
<TITLE>mod_perl guide: mod_perl Status. Peeking into the Server's Perl Innards</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -8415,14 +11601,14 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
mod_perl Status. Peeking into the Server's Perl Innards</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="control.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="debug.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Watching_the_server">Watching the server</A>
@@ -8436,7 +11622,7 @@
</UL>
<!-- INDEX END -->
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -8446,7 +11632,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Watching_the_server">Watching the server</A></H1></CENTER>
<P>
@@ -8493,6 +11681,7 @@
Assuming that your mod_perl server listens to port 81, fetch <A
HREF="http://www.myserver.com:81/perl-status">http://www.myserver.com:81/perl-status</A>
+
<P>
<PRE> Embedded Perl version 5.00502 for Apache/1.3.2 (Unix) mod_perl/1.16
process 187138, running since Thu Nov 19 09:50:33 1998
@@ -8545,7 +11734,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="control.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="debug.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -8557,8 +11747,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 04/19/1999
</FONT>
</B>
</TD>
@@ -8588,8 +11778,11 @@
<TITLE>mod_perl guide: Debugging mod_perl</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -8600,14 +11793,14 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Debugging mod_perl</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="status.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="browserbugs.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Sometimes_script_works_Sometime">Sometimes script works, Sometimes Not</A>
@@ -8618,7 +11811,7 @@
</UL>
<!-- INDEX END -->
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -8628,12 +11821,16 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Sometimes_script_works_Sometime">Sometimes script works, Sometimes Not</A></H1></CENTER>
<P>
-See <A HREF="././porting.html#Sometimes_it_works_Sometimes_Not">Sometimes it works Sometimes Not</A>
+See <A HREF="././porting.html#Sometimes_it_Works_Sometimes_Not">Sometimes it works Sometimes Not</A>
+
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Apache_DB_Run_the_interactive">Apache::DB - Run the interactive Perl debugger under mod_perl</A></H1></CENTER>
@@ -8748,7 +11945,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="status.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="browserbugs.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -8760,8 +11958,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
@@ -8788,11 +11986,14 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: Perl Reference</TITLE>
+ <TITLE>mod_perl guide: Workarounds for some known bugs in browsers.</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -8803,30 +12004,22 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Perl Reference</H1>
+Workarounds for some known bugs in browsers.</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="debug.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="modules.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
-
- <LI><A HREF="#Coverage">Coverage</A>
- <LI><A HREF="#Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A>
- <UL>
-
- <LI><A HREF="#Making_the_variables_global">Making the variables global</A>
- <LI><A HREF="#Making_the_variables_global_with">Making the variables global with strict pragma On</A>
- <LI><A HREF="#Using_Exporter_pm_to_share_globa">Using Exporter.pm to share global variables</A>
- <LI><A HREF="#Using_aliasing_perl_feature_to_s">Using aliasing perl feature to share global variables</A>
- </UL>
+ <LI><A HREF="#Preventing_QUERY_STRING_to_get_c">Preventing QUERY_STRING to get corrupted with &entity key names.</A>
+ <LI><A HREF="#IE_4_x_does_not_re_post_data_to_">IE 4.x does not re-post data to a non-port-80 URL</A>
</UL>
<!-- INDEX END -->
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -8836,247 +12029,265 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
+<CENTER><H1><A NAME="Preventing_QUERY_STRING_to_get_c">Preventing QUERY_STRING to get corrupted with &entity key names.</A></H1></CENTER>
<P>
-This new document was born because some users reluctant to learn perl prior
-to jumping into a mod_perl. I will try to cover some of the most frequent
-pure perl questions being asked at the list.
+In URL <CODE>http://my.site.com/foo.pl?foo=bar&reg=foobar</CODE> , some browsers will interpret <CODE>&reg</CODE> as a magic entity, and encode it as it was
+<CODE>&reg;</CODE>, which will result in a corrupted <CODE>QUERY_STRING</CODE>. If you encounter this problem you should either avoid using such a keys
+or separate parameter pairs with <CODE>;</CODE> instead of <CODE>&</CODE>. Both <CODE>CGI.pm</CODE> and
+<CODE>Apache::Request</CODE> support a semicolon instead of an ampersand as a separator. So your URI
+should look like:
+<CODE>http://my.site.com/foo.pl?foo=bar;reg=foobar</CODE>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A></H1></CENTER>
+<CENTER><H1><A NAME="IE_4_x_does_not_re_post_data_to_">IE 4.x does not re-post data to a non-port-80 URL</A></H1></CENTER>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Making_the_variables_global">Making the variables global</A></H2></CENTER>
+One problem with publishing 8080 port numbers is that I was told that IE
+4.x has a bug when re-posting data to a non-port-80 url. It drops the port
+designator, and uses port 80 anyway.
+
<P>
-When you first wrote <CODE>$x</CODE> in your code you created a global
-variable. It is visible everywhere in the file you have use it. or if
-defined it inside a package - it is visible inside this package. But it
-will work only if you do not use <CODE>strict</CODE> pragma and you <STRONG>HAVE</STRONG> to use this pragma if you want to run your scripts under mod_perl. Read <A HREF="././porting.html#strict_pragma">Strict pragma</A> to find out why.
+See <A HREF="././config.html#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>
+
+
+
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+
+ <HR>
+ [ <A HREF="debug.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="modules.html">Next</A> ]
+
+<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
+</TR>
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
+ </FONT>
+ </B>
+ </TD>
+
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
+
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
+</TR>
+</TABLE></CENTER>
+
+</BODY>
+</HTML>
+
+
+<HR SIZE=6>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+ <TITLE>mod_perl guide: Apache::* modules</TITLE>
+ <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
+ <META NAME="Author" CONTENT="Bekman Stas">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
+</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
+<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+<A NAME="toc"></A>
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+Apache::* modules</H1>
+<HR WIDTH="100%">
+ [ <A HREF="browserbugs.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="perl.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+<UL>
+
+ <LI><A HREF="#Apache_Session_Maintain_sessi">Apache::Session - Maintain session state across HTTP requests</A>
+ <LI><A HREF="#Apache_DBI_Initiate_a_persist">Apache::DBI - Initiate a persistent database connection</A>
+ <LI><A HREF="#Apache_Request_libapreq_Gen">Apache::Request (libapreq) - Generic Apache Request Library</A>
+ <LI><A HREF="#Apache_PerlRun_Run_unaltered_">Apache::PerlRun - Run unaltered CGI scripts under mod_perl</A>
+</UL>
+<!-- INDEX END -->
+
+<HR>
+
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+
+ <HR>
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Making_the_variables_global_with">Making the variables global with strict pragma On</A></H2></CENTER>
+<CENTER><H1><A NAME="Apache_Session_Maintain_sessi">Apache::Session - Maintain session state across HTTP requests</A></H1></CENTER>
<P>
-First you use :
+This module provides the Apache/mod_perl user a mechanism for storing
+persistent user data in a global hash, which is independent of its real
+storage mechanism. Currently you can choose from these storage mechanisms <CODE>Apache::Session::DBI</CODE>, <CODE>Apache::Session::Win32</CODE>,
+<CODE>Apache::Session::File</CODE>, <CODE>Apache::Session::IPC</CODE>. Read the man page of the mechanism you want to use for a complete
+reference.
-<P>
-<PRE> use strict;
-</PRE>
<P>
-Then you use:
+What Apache::Session does is provide persistence to a data structure. The
+data structure has an ID number, and you can retrieve it by using the ID
+number. In the case of Apache, you would store the ID number in a cookie or
+the URL to associate it with one browser, but the method of dealing with
+the ID is completely up to you. The flow of things is generally:
<P>
-<PRE> use vars qw($scalar %hash @array);
+<PRE> Tie a session to Apache::Session.
+ Get the ID number.
+ Store the ID number in a cookie.
+ End of Request 1.
</PRE>
-<P>
-Starting from this moment the variables are global in the package you
-defined them, if you want to share global variables between packages, here
-what you can do.
-
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Using_Exporter_pm_to_share_globa">Using Exporter.pm to share global variables</A></H2></CENTER>
-<P>
-Assume that you want to share the <CODE>CGI.pm</CODE>'s object (I will use <CODE>$q</CODE>) between your modules. For example you create it in the <CODE>script.pl</CODE>, but want it to be visible in <CODE>My::HTML</CODE>. First - you make <CODE>$q</CODE> global.
-
+<PRE> (time passes)
+</PRE>
<P>
-<PRE> script.pl:
- ----------------
- use vars qw($q);
- use CGI;
- use My::HTML qw($q);
- $q = new CGI;
-
- My::HTML::printmyheader();
- ----------------
+<PRE> Get the cookie.
+ Restore your hash using the ID number in the cookie.
+ Use whatever data you put in the hash.
+ End of Request 2.
</PRE>
<P>
-Note that we have imported <CODE>$q</CODE> from <CODE>My::HTML</CODE>. And the <CODE>My::HTML</CODE>
-which does the export of <CODE>$q</CODE>:
+Using Apache::Session is easy: simply tie a hash to the session object,
+stick any data structure into the hash, and the data you put in
+automatically persists until the next invocation. Here is a quick example
+which uses cookies to track the user's session.
<P>
-<PRE> My/HTML.pm
- ----------------
- package My::HTML;
- use strict;
-
- BEGIN {
- use Exporter ();
+<PRE> # Pull in the require packages
+ use Apache::Session::DBI;
+ use Apache;
- @My::HTML::ISA = qw(Exporter);
- @My::HTML::EXPORT = qw();
- @My::HTML::EXPORT_OK = qw($q);
+ use strict;
- }
+ # Read in the cookie if this is an old session
+ my $r = Apache->request;
+ my $cookie = $r->header_in('Cookie');
+ $cookie =~ s/SESSION_ID=(\w*)/$1/;
- use vars qw($q);
+ # Create a session object based on the cookie we got from the
+ # browser, or a new session if we got no cookie
+ my %session;
+ tie %session, 'Apache::Session::DBI', $cookie,
+ {DataSource => 'dbi:mysql:sessions',
+ UserName => $db_user,
+ Password => $db_pass
+ };
- sub printmyheader{
- # Whatever you want to do with $q... e.g.
- print $q->header();
- }
- -------------------
+ # Might be a new session, so lets give them their cookie back
+ my $session_cookie = "SESSION_ID=$session{_session_id};";
+ $r->header_out("Set-Cookie" => $session_cookie);
</PRE>
-<P>
-So the <CODE>$q</CODE> is being shared between the <CODE>My::HTML</CODE> package and the
-<CODE>script.pl</CODE>. It will work vice versa as well, if you create the object in the <CODE>My::HTML</CODE> but use it in the <CODE>script.pl</CODE>. You have a true sharing, since if you change <CODE>$q</CODE> in <CODE>script.pl</CODE>, it will be changed in <CODE>My::HTML</CODE> as well.
-
<P>
-What if you need to share <CODE>$q</CODE> between more than 2 packages? For example you want My::Doc to share <CODE>$q</CODE> as well.
+After setting this up, you can stick anything you want into
+<CODE>%session</CODE> (except file handles), and it will still be there
+when the user invokes the next page.
<P>
-You leave the <CODE>My::HTML</CODE> untouched, modify the script.pl to include:
+It is possible to write an Apache authen handler using Apache::Session. You
+can put your authentication token into the session. When a user invokes a
+page, you open their session, check to see if they have a valid token, and
+approve or deny their authorization based on that.
-<P>
-<PRE> use My::Doc qw($q);
-</PRE>
<P>
-And write the <CODE>My::Doc</CODE> exactly like <CODE>My::HTML</CODE> - of course that the content is different :).
+As for IIS, let's compare. IIS's sessions are only valid on the same web
+server as the one that issued the session. Apache::Session's session
+objects can be shared amongst a farm of many machines running different
+operating systems, including even Win32. IIS stores session information in
+RAM. Apache::Session stores sessions in databases, file systems, or RAM.
+IIS's sessions are only good for storing scalars or arrays.
+Apache::Session's sessions allow you to store arbitrarily complex objects.
+IIS sets up the session and automatically tracks it for you. With
+Apache::Session, you setup and track the session yourself. IIS is
+proprietary. Apache::Session is open-source. Apache::Session::DBI can issue
+400+ session requests per second on light Celeron 300A running Linux. IIS?
<P>
-One possible pitfall is when you want to use the <CODE>My::Doc</CODE> in both
-<CODE>My::HTML</CODE> and <CODE>script.pl</CODE>. Only if you add:
+An alternative to Apache::Session is Apache::ASP, which has session
+tracking abilities. HTML::Embperl hooks into Apache::Session for you.
<P>
-<PRE> use My::Doc qw($q);
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Apache_DBI_Initiate_a_persist">Apache::DBI - Initiate a persistent database connection</A></H1></CENTER>
<P>
-Into a <CODE>My::HTML</CODE>, the <CODE>$q</CODE> will be shared. Otherwise <CODE>My::Doc</CODE> will not share the <CODE>$q</CODE> anymore. To make things clear here is the code:
+See <A HREF="././databases.html#Apache_DBI_Initiate_a_persist">mod_perl and relational Databases</A>
-<P>
-<PRE> script.pl:
- ----------------
- use vars qw($q);
- use CGI;
- use My::HTML qw($q);
- use My::Doc qw($q);
- $q = new CGI;
-
- My::HTML::printmyheader();
- ----------------
-</PRE>
-<P>
-<PRE> My/HTML.pm
- ----------------
- package My::HTML;
- use strict;
-
- BEGIN {
- use Exporter ();
-
- @My::HTML::ISA = qw(Exporter);
- @My::HTML::EXPORT = qw();
- @My::HTML::EXPORT_OK = qw($q);
-
- }
-
- use vars qw($q);
- use My::Doc qw($q);
-
- sub printmyheader{
- # Whatever you want to do with $q... e.g.
- print $q->header();
-
- My::Doc::printtitle('Guide');
- }
- -------------------
-</PRE>
-<P>
-<PRE> My/Doc.pm
- ----------------
- package My::Doc;
- use strict;
-
- BEGIN {
- use Exporter ();
-
- @My::Doc::ISA = qw(Exporter);
- @My::Doc::EXPORT = qw();
- @My::Doc::EXPORT_OK = qw($q);
-
- }
-
- use vars qw($q);
-
- sub printtitle{
- my $title = shift || 'None';
-
- print $q->h1($title);
- }
- -------------------
-</PRE>
+
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Using_aliasing_perl_feature_to_s">Using aliasing perl feature to share global variables</A></H2></CENTER>
+<CENTER><H1><A NAME="Apache_Request_libapreq_Gen">Apache::Request (libapreq) - Generic Apache Request Library</A></H1></CENTER>
<P>
-As the title says you can import a variable into a script/module without
-using an Exporter.pm. I have found it useful to keep all the configuration
-variables in one module <CODE>My::Config</CODE>. But then I have to export all the variables in order to use them in other
-modules, which is bad for two reasons: polluting other packages' name
-spaces with extra tags which rise up the memory requirements, adding an
-overhead of keeping track of what variables should be exported from the
-configuration module and what imported for some particular package. I solve
-this problem by keeping all the variables in one hash <CODE>%c</CODE> and exporting only it. Here is an example of <CODE>My::Config</CODE>:
+This package contains modules for manipulating client request data via the
+Apache API with Perl and C. Functionality includes:
-<P>
-<PRE> package My::Config;
- use strict;
- use vars qw(%c);
- %c = (
- # All the configs go here
- scalar_var => 5,
-
- array_var => [
- foo,
- bar,
- ],
-
- hash_var => {
- foo => 'Foo',
- bar => 'BARRR',
- },
- );
-</PRE>
<P>
-Now in packages that want to use the configuration variables I have either
-to use the fully qualified names like <CODE>$My::Config::test</CODE>, which I dislike or import them as described in the previous section. But
-hey, since we have only one variable to handle, we can make things even
-simpler and save the loading of the <CODE>Exporter.pm</CODE> package. We will use aliasing perl feature for exporting and saving the
-keystrokes:
+- parsing of application/x-www-form-urlencoded data
<P>
-<PRE> package My::HTML;
- use strict;
- # Global Configuration now aliased to global %c
- use My::Config ();
- use vars qw(%c);
- *c = \%My::Config::c;
-
- # Now you can access the variables from the My::Config
- print $c{scalar_val};
- print $c{array_val}[0];
- print $c{hash_val}{foo};
-</PRE>
+- parsing of multipart/form-data
+
<P>
-Of course <CODE>$c</CODE> is global everywhere you use it as described
-above, and if you change it somewhere it will affect any other packages you
-have aliased <CODE>$My::Config::c</CODE> to.
+- parsing of HTTP Cookies
<P>
-Note that aliases work either with global or <CODE>local()</CODE> vars - you cannot write:
+The Perl modules are simply a thin xs layer on top of libapreq, making them
+a lighter and faster alternative to CGI.pm and CGI::Cookie. See the
+Apache::Request and Apache::Cookie documentation for more details and
+eg/perl/ for examples.
<P>
-<PRE> my *c = \%My::Config::c;
-</PRE>
+Apache::Request and the libapreq are tied tight to the Apache API, which
+there is no access to in a process running under mod_cgi.
+
<P>
-Which is an error. But you can:
+Get it from CPAN at $CPAN/authors/id/DOUGM/libapreq-x.xx.tar.gz or from <A
+HREF="http://perl.apache.org/dist/libapreq-x.xx.tar.gz">http://perl.apache.org/dist/libapreq-x.xx.tar.gz</A>
+. (replace x.xx with the current version)
<P>
-<PRE> local *c = \%My::Config::c;
-</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Apache_PerlRun_Run_unaltered_">Apache::PerlRun - Run unaltered CGI scripts under mod_perl</A></H1></CENTER>
+<P>
+See <A HREF="././porting.html#Apache_PerlRun_a_closer_look">Apache::PerlRun - a closer look</A>.
+
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -9086,7 +12297,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="browserbugs.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="perl.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -9098,8 +12310,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
@@ -9126,11 +12338,14 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: mod_perl for ISPs. mod_perl and Virtual Hosts.</TITLE>
+ <TITLE>mod_perl guide: Perl Reference</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -9141,22 +12356,30 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-mod_perl for ISPs. mod_perl and Virtual Hosts.</H1>
+Perl Reference</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="modules.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="snippets.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
- <LI><A HREF="#ISPs_providing_mod_perl_services">ISPs providing mod_perl services - a fantasy or reality.</A>
- <LI><A HREF="#Virtual_Hosts_in_the_guide">Virtual Hosts in the guide</A>
+ <LI><A HREF="#Coverage">Coverage</A>
+ <LI><A HREF="#Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A>
+ <UL>
+
+ <LI><A HREF="#Making_the_variables_global">Making the variables global</A>
+ <LI><A HREF="#Making_the_variables_global_with">Making the variables global with strict pragma On</A>
+ <LI><A HREF="#Using_Exporter_pm_to_share_globa">Using Exporter.pm to share global variables</A>
+ <LI><A HREF="#Using_aliasing_perl_feature_to_s">Using aliasing perl feature to share global variables</A>
+ </UL>
+
</UL>
<!-- INDEX END -->
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -9166,166 +12389,249 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<CENTER><H1><A NAME="ISPs_providing_mod_perl_services">ISPs providing mod_perl services - a fantasy or reality.</A></H1></CENTER>
+<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
<P>
-You have fallen in love with mod_perl from the first sight, since the
-moment you have installed it at your home box. But when you wanted to
-convert your CGI scripts, currently running on your favorite ISPs machine,
-to run under mod_perl - you have discovered, your ISPs either have never
-heard of such a beast, or refuse to install it for you.
+This new document was born because some users reluctant to learn perl prior
+to jumping into a mod_perl. I will try to cover some of the most frequent
+pure perl questions being asked at the list.
<P>
-You are an old sailor in the ISP business, you have seen it all, you know
-how many ISPs are out there and you know that the sales margins are too low
-to keep you happy. You are looking for some new service almost no one
-provides, to attract more clients to become your users and hopefully to
-have a bigger slice than a neighbor ISP.
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A></H1></CENTER>
<P>
-If you are a user asking for a mod_perl service or an ISP considering to
-provide this service, this section should make things clear for both of
-you.
-
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Making_the_variables_global">Making the variables global</A></H2></CENTER>
<P>
-an ISP has 3 choices to choose from:
+When you first wrote <CODE>$x</CODE> in your code you created a global
+variable. It is visible everywhere in the file you have use it. or if
+defined it inside a package - it is visible inside this package. But it
+will work only if you do not use <CODE>strict</CODE> pragma and you <STRONG>HAVE</STRONG> to use this pragma if you want to run your scripts under mod_perl. Read <A HREF="././porting.html#strict_pragma">Strict pragma</A> to find out why.
-<OL>
-<P><LI>
<P>
-ISP cannot afford having a user, running scripts under mod_perl, on the
-main server, since it will die very soon for one of the many reasons:
-either sloppy programming, or user testing just updated script which
-probably has some syntax errors and etc, no need to explain why if you are
-familiar with mod_perl peculiarities. The only scripts that <STRONG>CAN BE ALLOWED</STRONG> to use, are the ones that were written by ISP and are not being modified by
-user (guest books, counters and etc - the same standard scripts ISPs
-providing since they were born). So you have to say <STRONG>NO</STRONG> for this choice.
-
-<P><LI>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Making_the_variables_global_with">Making the variables global with strict pragma On</A></H2></CENTER>
<P>
-But, hey why I cannot let my user to run his own server, so I clean my
-hands off and do not care how dirty and sloppy user's code is (assuming
-that user is running the server by his own username).
+First you use :
<P>
-This option is fine as long as you are concerned about your new system
-requirements. If you have even some very limited experience with mod_perl,
-you know that mod_perl enabled apache servers while freeing up your CPU and
-lets you run scripts much much faster, has a huge memory demands (5-20
-times the plain apache uses). The size depends on the code length,
-sloppiness of the programmer, possible memory leaks the code might have and
-all that multiplied by the number of children each server spawns. A very
-simple example : a server demanding 10Mb of memory which spawns 10
-children, already rises your memory requirements by 100Mb (the real
-requirement are actually smaller if your OS allows code sharing between
-processes and a programmer exploits these features in her code). Now
-multiply the received number by the number of users you intend to have and
-you will get the memory requirements. Since ISPs never say no, you better
-use an opposite approach - think of a largest memory size you can afford
-then divide it by one user's requirements as I have shown in example, and
-you will know how much mod_perl users you can afford :)
-
+<PRE> use strict;
+</PRE>
<P>
-But who am I to prognosticate how much memory your user may use. His
-requirement from a single server can be very modest, but do you know how
-many of servers he will run (after all she has all the control over
-httpd.conf - and it has to be that way, since this is very essential for
-the user running mod_perl)?
+Then you use:
<P>
-All this rumbling about memory leads to a single question: Can you restrict
-user from using more than X memory? Or another variation of the question:
-Assuming you have as much memory as you want, can you charge user for the
-average memory usage?
-
+<PRE> use vars qw($scalar %hash @array);
+</PRE>
<P>
-If the answer for either of the above question is positive, you are all set
-and your clients will prize your name for letting them run mod_perl! There
-are tools to restrict resources' usage (See for example man pages for <CODE>ulimit(3)</CODE>, <CODE>getrlimit(2)</CODE>, <CODE>setrlimit(2)</CODE>
-and <CODE>sysconf(3)</CODE> ).
+Starting from this moment the variables are global in the package you
+defined them, if you want to share global variables between packages, here
+what you can do.
<P>
-<META> If you have an experience with some restriction techniques
-please share with us. Thank you! </META>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Using_Exporter_pm_to_share_globa">Using Exporter.pm to share global variables</A></H2></CENTER>
+<P>
+Assume that you want to share the <CODE>CGI.pm</CODE>'s object (I will use <CODE>$q</CODE>) between your modules. For example you create it in the <CODE>script.pl</CODE>, but want it to be visible in <CODE>My::HTML</CODE>. First - you make <CODE>$q</CODE> global.
<P>
-If you have picked this choice, you have to provide your client:
+<PRE> script.pl:
+ ----------------
+ use vars qw($q);
+ use CGI;
+ use My::HTML qw($q);
+ $q = new CGI;
+
+ My::HTML::printmyheader();
+ ----------------
+</PRE>
+<P>
+Note that we have imported <CODE>$q</CODE> from <CODE>My::HTML</CODE>. And the <CODE>My::HTML</CODE>
+which does the export of <CODE>$q</CODE>:
-<UL>
-<P><LI>
<P>
-Shutdown/startup scripts installed together with the rest of your daemon
-startup scripts (e.g <CODE>/etc/rc.d</CODE> directory) scripts, so when you reboot your machine user's server will be
-correctly shutdowned and will be back online the moment your system comes
-back online. Also make sure to start each server under username the server
-belongs to, if you are not looking for a big trouble.
+<PRE> My/HTML.pm
+ ----------------
+ package My::HTML;
+ use strict;
+
+ BEGIN {
+ use Exporter ();
+
+ @My::HTML::ISA = qw(Exporter);
+ @My::HTML::EXPORT = qw();
+ @My::HTML::EXPORT_OK = qw($q);
+
+ }
+
+ use vars qw($q);
+
+ sub printmyheader{
+ # Whatever you want to do with $q... e.g.
+ print $q->header();
+ }
+ -------------------
+</PRE>
+<P>
+So the <CODE>$q</CODE> is being shared between the <CODE>My::HTML</CODE> package and the
+<CODE>script.pl</CODE>. It will work vice versa as well, if you create the object in the <CODE>My::HTML</CODE> but use it in the <CODE>script.pl</CODE>. You have a true sharing, since if you change <CODE>$q</CODE> in <CODE>script.pl</CODE>, it will be changed in <CODE>My::HTML</CODE> as well.
-<P><LI>
<P>
-Proxy (in a forward or httpd accelerator mode) services for user's virtual
-host. Since user will have to run her server on unprivileged port
-(>1024), you will have to forward all requests from
-<CODE>user.given.virtual.hostname:80</CODE> (which is
-<CODE>user.given.virtual.hostname</CODE> without port - 80 is a default) to
-<CODE>your.machine.ip:port_assigned_to_user</CODE> and user to code his scripts to write self referencing URLs to be of <CODE>user.given.virtual.hostname</CODE>
-base of course.
+What if you need to share <CODE>$q</CODE> between more than 2 packages? For example you want My::Doc to share <CODE>$q</CODE> as well.
<P>
-Letting user to run a mod_perl server, immediately adds a requirement for
-user to be able to restart and configure their own server. But only root
-can bind port 80. That is why user has to use ports numbers >1024.
+You leave the <CODE>My::HTML</CODE> untouched, modify the script.pl to include:
-<P><LI>
<P>
-Another problem you will have to solve is how to assign ports between
-users. Since user can pick any port above 1024 to run his server on, you
-will have to make some regulation here. A simple example will stress the
-importance of this problem: I am a malicious user or I just a rival of some
-fellow who runs his own server on your ISP. All I should do is to find out
-what port his server is listening to (e.g. with help of <CODE>netstat(8)</CODE>) and configure my own server to listen on the same port. While I am unable
-to bind to this same port, imagine what will happen when you reboot your
-system and my startup script happen to be run before my rivals! I get the
-port first, now all requests will be redirected to my server and let your
-imagination go wild about what nasty things might happen then. Of course
-the ugly things will be revealed pretty soon, but the damage has been done.
+<PRE> use My::Doc qw($q);
+</PRE>
+<P>
+And write the <CODE>My::Doc</CODE> exactly like <CODE>My::HTML</CODE> - of course that the content is different :).
-</UL>
-<P><LI>
<P>
-A much better, but costly solution is <STRONG>co-location</STRONG>. Let user to hook her (or ISP's) stand alone machine into your network,
-and forget about this user. Of course either user or you will have to make
-all the system administration chores and it will cost your client more
-money.
+One possible pitfall is when you want to use the <CODE>My::Doc</CODE> in both
+<CODE>My::HTML</CODE> and <CODE>script.pl</CODE>. Only if you add:
<P>
-All in all, who are the people who seek the mod_perl support? The ones who
-run serious projects/businesses, who can afford a stand alone box, thus
-gaining their goal of self autonomy and keeping their ISP happy. So money
-is not an obstacle.
+<PRE> use My::Doc qw($q);
+</PRE>
+<P>
+Into a <CODE>My::HTML</CODE>, the <CODE>$q</CODE> will be shared. Otherwise <CODE>My::Doc</CODE> will not share the <CODE>$q</CODE> anymore. To make things clear here is the code:
-</OL>
+<P>
+<PRE> script.pl:
+ ----------------
+ use vars qw($q);
+ use CGI;
+ use My::HTML qw($q);
+ use My::Doc qw($q);
+ $q = new CGI;
+
+ My::HTML::printmyheader();
+ ----------------
+</PRE>
+<P>
+<PRE> My/HTML.pm
+ ----------------
+ package My::HTML;
+ use strict;
+
+ BEGIN {
+ use Exporter ();
+
+ @My::HTML::ISA = qw(Exporter);
+ @My::HTML::EXPORT = qw();
+ @My::HTML::EXPORT_OK = qw($q);
+
+ }
+
+ use vars qw($q);
+ use My::Doc qw($q);
+
+ sub printmyheader{
+ # Whatever you want to do with $q... e.g.
+ print $q->header();
+
+ My::Doc::printtitle('Guide');
+ }
+ -------------------
+</PRE>
+<P>
+<PRE> My/Doc.pm
+ ----------------
+ package My::Doc;
+ use strict;
+
+ BEGIN {
+ use Exporter ();
+
+ @My::Doc::ISA = qw(Exporter);
+ @My::Doc::EXPORT = qw();
+ @My::Doc::EXPORT_OK = qw($q);
+
+ }
+
+ use vars qw($q);
+
+ sub printtitle{
+ my $title = shift || 'None';
+
+ print $q->h1($title);
+ }
+ -------------------
+</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Virtual_Hosts_in_the_guide">Virtual Hosts in the guide</A></H1></CENTER>
+<CENTER><H2><A NAME="Using_aliasing_perl_feature_to_s">Using aliasing perl feature to share global variables</A></H2></CENTER>
<P>
-If you are about to use <STRONG>Virtual Hosts</STRONG> you might want to read these sections:
+As the title says you can import a variable into a script/module without
+using an Exporter.pm. I have found it useful to keep all the configuration
+variables in one module <CODE>My::Config</CODE>. But then I have to export all the variables in order to use them in other
+modules, which is bad for two reasons: polluting other packages' name
+spaces with extra tags which rise up the memory requirements, adding an
+overhead of keeping track of what variables should be exported from the
+configuration module and what imported for some particular package. I solve
+this problem by keeping all the variables in one hash <CODE>%c</CODE> and exporting only it. Here is an example of <CODE>My::Config</CODE>:
<P>
-<A HREF="././config.html#Perl_Sections">Perl Sections</A>.
-
+<PRE> package My::Config;
+ use strict;
+ use vars qw(%c);
+ %c = (
+ # All the configs go here
+ scalar_var => 5,
+
+ array_var => [
+ foo,
+ bar,
+ ],
+
+ hash_var => {
+ foo => 'Foo',
+ bar => 'BARRR',
+ },
+ );
+</PRE>
<P>
-<A HREF="././config.html#Configuring_Apache_mod_perl_wi">Easing the chores of configuring the virtual hosts with mod_macro</A>
+Now in packages that want to use the configuration variables I have either
+to use the fully qualified names like <CODE>$My::Config::test</CODE>, which I dislike or import them as described in the previous section. But
+hey, since we have only one variable to handle, we can make things even
+simpler and save the loading of the <CODE>Exporter.pm</CODE> package. We will use aliasing perl feature for exporting and saving the
+keystrokes:
<P>
-<A HREF="././config.html#Is_there_a_way_to_provide_a_diff">Is there a way to provide a different startup.pl file for each individual virtual host</A>
+<PRE> package My::HTML;
+ use strict;
+ # Global Configuration now aliased to global %c
+ use My::Config ();
+ use vars qw(%c);
+ *c = \%My::Config::c;
+
+ # Now you can access the variables from the My::Config
+ print $c{scalar_val};
+ print $c{array_val}[0];
+ print $c{hash_val}{foo};
+</PRE>
+<P>
+Of course <CODE>$c</CODE> is global everywhere you use it as described
+above, and if you change it somewhere it will affect any other packages you
+have aliased <CODE>$My::Config::c</CODE> to.
<P>
-<A HREF="././config.html#Is_there_a_way_to_modify_INC_on">Is there a way to modify @INC on a per-virtual-host basis</A>
+Note that aliases work either with global or <CODE>local()</CODE> vars - you cannot write:
<P>
-<A HREF="././config.html#Sometimes_the_script_from_one_vi">Sometimes the script from one virtual host calls a script with the same path from the second virtual host</A>
+<PRE> my *c = \%My::Config::c;
+</PRE>
+<P>
+Which is an error. But you can:
+<P>
+<PRE> local *c = \%My::Config::c;
+</PRE>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -9335,7 +12641,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="modules.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="snippets.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -9347,8 +12654,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 04/19/1999
</FONT>
</B>
</TD>
@@ -9378,8 +12685,11 @@
<TITLE>mod_perl guide: Code Snippets</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -9390,14 +12700,14 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Code Snippets</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="perl.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="help.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Sending_MIME_headers">Sending MIME headers</A>
@@ -9409,7 +12719,7 @@
</UL>
<!-- INDEX END -->
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -9419,7 +12729,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Sending_MIME_headers">Sending MIME headers</A></H1></CENTER>
<P>
@@ -9578,46 +12890,388 @@
}
</PRE>
<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Accessing_variables_from_the_cal">Accessing variables from the caller's package</A></H1></CENTER>
+<P>
+Sometimes you want to access some variables from the caller's package. One
+way is to do:
+
+<P>
+<PRE> my $caller = caller;
+ print qq[$caller --- ${"${caller}::var"}];
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Handling_cookies">Handling cookies</A></H1></CENTER>
+<P>
+Unless you use some well known modules like CGI.pm you can handle the
+cookies yourself.
+
+<P>
+Cookies come in the $ENV{HTTP_COOKIE} variable. You can print the raw
+cookie string as $ENV{HTTP_COOKIE}.
+
+<P>
+This is a fairly well-known bit of code to take cookie values and put them
+into a hash.
+
+<P>
+<PRE> sub getCookies {
+ # cookies are seperated by a semicolon and a space, this will
+ # split them and return a hash of cookies
+ local(@rawCookies) = split (/; /,$ENV{'HTTP_COOKIE'});
+ local(%cookies);
+
+ foreach(@rawCookies){
+ ($key, $val) = split (/=/,$_);
+ $cookies{$key} = $val;
+ }
+
+ return %cookies;
+ }
+</PRE>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+
+ <HR>
+ [ <A HREF="perl.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="help.html">Next</A> ]
+
+<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
+</TR>
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 04/19/1999
+ </FONT>
+ </B>
+ </TD>
+
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
+
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
+</TR>
+</TABLE></CENTER>
+
+</BODY>
+</HTML>
+
+
+<HR SIZE=6>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+ <TITLE>mod_perl guide: Getting Helped and Further Learning</TITLE>
+ <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
+ <META NAME="Author" CONTENT="Bekman Stas">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
+</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
+<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+<A NAME="toc"></A>
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+Getting Helped and Further Learning</H1>
+<HR WIDTH="100%">
+ [ <A HREF="snippets.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="download.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+<UL>
+
+ <LI><A HREF="#READ_ME_FIRST">READ ME FIRST</A>
+ <LI><A HREF="#This_document_s_Author">This document's Author</A>
+ <LI><A HREF="#Get_helped_with_mod_perl">Get helped with mod_perl</A>
+ <LI><A HREF="#Get_helped_with_Perl">Get helped with Perl</A>
+ <LI><A HREF="#Get_helped_with_Perl_CGI">Get helped with Perl/CGI</A>
+ <LI><A HREF="#Get_helped_with_Apache">Get helped with Apache </A>
+ <LI><A HREF="#Get_helped_with_DBI">Get helped with DBI</A>
+</UL>
+<!-- INDEX END -->
+
+<HR>
+
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<P>
+<CENTER><H1><A NAME="READ_ME_FIRST">READ ME FIRST</A></H1></CENTER>
+<P>
+If after reading this guide and other documents listed in this section, you
+feel that your question is not yet answered, please ask the apache/mod_perl
+mailing list to help you. But first try to browse the mailing list archive.
+Most of the time you will find the answer for your question by searching
+the mailing archive, since there is a big chance someone else already have
+encountered the problem and found a solution for it. If you ignore this
+advice, do not be surprised if your question will be left unanswered - it
+bores people to answer the same question more than once. It does not mean
+that you should avoid asking questions. Just do not abuse the available
+help and <STRONG>RTFM</STRONG>
+before you call for <STRONG>HELP</STRONG>. (You have certainly heard the infamous fable of the shepherd boy and the
+wolves)
+
+<P>
+For more information See <A HREF="#Get_helped_with_mod_perl">Get helped with mod_perl</A>.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="This_document_s_Author">This document's Author</A></H1></CENTER>
+<P>
+Hi, I wrote this document to help you with mod_perl. It does not mean that
+if you have any question regarding mod_perl, perl or whatever you think I
+might know, you should directly send it to me. Please see the
+<A HREF="#Get_helped_with_mod_perl">Get helped with mod_perl</A> section and follow the guidelines as prescribed there.
+
+<P>
+However, you are welcome to submit corrections and suggestions directly to
+me at <A
+HREF="mailto:sbekman@iname.com?subject=mod_perl%20guide%20corrections.">sbekman@iname.com?subject=mod_perl%20guide%20corrections.</A>
+ <STRONG>But PLEASE
+NO QUESTIONS, they will be immediately deleted.</STRONG>
+
+
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Get_helped_with_mod_perl">Get helped with mod_perl</A></H1></CENTER>
+<DL>
+<P><DT><STRONG><A NAME="item_mod_perl">mod_perl home</A></STRONG><DD>
+<P>
+<A HREF="http://perl.apache.org">http://perl.apache.org</A>
+
+<P><DT><STRONG><A NAME="item_Apache">Apache Modules Book</A></STRONG><DD>
+<P>
+<A HREF="http://www.modperl.com">http://www.modperl.com</A> is the home
+site of The Apache Modules Book, a book about creating Web server modules
+using the Apache API, written by Lincoln Stein and Doug MacEachern.
+
+<P>
+Now you can purchase the book at your local bookstore or from the online
+dealer. O'Reilly lists this book as:
+
+<P>
+<PRE> Writing Apache Modules with Perl and C
+ By Lincoln Stein & Doug MacEachern
+ 1st Edition March 1999
+ 1-56592-567-X, Order Number: 567X
+ 746 pages, $34.95
+</PRE>
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl FAQ</A></STRONG>
+<P>
+by Frank Cringle at <A
+HREF="http://perl.apache.org/faq/">http://perl.apache.org/faq/</A> .
+
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl performance tuning guide</A></STRONG>
+<P>
+by Vivek Khera at <A
+HREF="http://perl.apache.org/tuning/">http://perl.apache.org/tuning/</A> .
+
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl plugin reference guide</A></STRONG>
+<P>
+by Doug MacEachern at <A
+HREF="http://perl.apache.org/src/mod_perl.html">http://perl.apache.org/src/mod_perl.html</A>
+.
+
+<P><LI><STRONG><A NAME="item_Quick">Quick guide for moving from CGI to mod_perl</A></STRONG>
+<P>
+at <A
+HREF="http://perl.apache.org/dist/cgi_to_mod_perl.html">http://perl.apache.org/dist/cgi_to_mod_perl.html</A>
+.
+
+<P><LI><STRONG><A NAME="item_mod_perl_traps">mod_perl_traps, common traps and solutions for mod_perl users</A></STRONG>
+<P>
+at <A
+HREF="http://perl.apache.org/dist/mod_perl_traps.html">http://perl.apache.org/dist/mod_perl_traps.html</A>
+.
+
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl Quick Reference Card</A></STRONG>
+<P>
+<A HREF="http://www.refcards.com">http://www.refcards.com</A> (Apache and
+other refcards are available from this link)
+
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl mailing list</A></STRONG>
+<P>
+The Apache/Perl mailing list (<A
+HREF="mailto:modperl@apache.org">modperl@apache.org</A>) <STRONG>is available for
+mod_perl users and developers to share ideas, solve problems and
+discuss things related to mod_perl and the Apache::* modules.</STRONG> To subscribe to this list, send mail to <A
+HREF="mailto:majordomo@apache.org">majordomo@apache.org</A> with empty <CODE>Subject</CODE> and with <CODE>Body</CODE>:
+
+<P>
+<PRE> subscribe modperl
+</PRE>
+<P>
+A <STRONG>searchable</STRONG> mod_perl mailing list archive available at <A
+HREF="http://forum.swarthmore.edu/epigone/modperl.">http://forum.swarthmore.edu/epigone/modperl.</A>
+We owe it to Ken Williams.
+
+<P>
+Another arhive: <A
+HREF="http://www.geocrawler.com/lists/3/web/182/0/">http://www.geocrawler.com/lists/3/web/182/0/</A>
+
+
+</DL>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Get_helped_with_Perl">Get helped with Perl</A></H1></CENTER>
+<UL>
+<P><LI><STRONG><A NAME="item_The">The Perl FAQ</A></STRONG>
+<P>
+<A
+HREF="http://www.perl.com/CPAN/doc/FAQs/FAQ/PerlFAQ.html">http://www.perl.com/CPAN/doc/FAQs/FAQ/PerlFAQ.html</A>
+
+
+<P><LI><STRONG><A NAME="item_perl">perl home</A></STRONG>
+<P>
+<A HREF="http://www.perl.com/">http://www.perl.com/</A>
+
+<P><LI><STRONG><A NAME="item_The">The Perl Journal</A></STRONG>
+<P>
+<A HREF="http://www.tpj.com/">http://www.tpj.com/</A>
+
+<P><LI><STRONG><A NAME="item_Perl">Perl Module Mechanics</A></STRONG>
+<P>
+<A
+HREF="http://world.std.com/~swmcd/steven/perl/module_mechanics.html">http://world.std.com/~swmcd/steven/perl/module_mechanics.html</A>
+- This page describes the mechanics of creating, compiling, releasing and
+maintaining Perl modules.
+
+</UL>
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Accessing_variables_from_the_cal">Accessing variables from the caller's package</A></H1></CENTER>
+<CENTER><H1><A NAME="Get_helped_with_Perl_CGI">Get helped with Perl/CGI</A></H1></CENTER>
+<UL>
+<P><LI><STRONG><A NAME="item_Perl">Perl/CGI FAQ</A></STRONG>
<P>
-Sometimes you want to access some variables from the caller's package. One
-way is to do:
+at <A
+HREF="http://www.perl.com/CPAN/doc/FAQs/cgi/perl-cgi-faq.html">http://www.perl.com/CPAN/doc/FAQs/cgi/perl-cgi-faq.html</A>
+
+<P><LI><STRONG><A NAME="item_Answers">Answers to some bothering Perl and Perl/CGI questions</A></STRONG>
<P>
-<PRE> my $caller = caller;
- print qq[$caller --- ${"${caller}::var"}];
-</PRE>
+<A
+HREF="http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html">http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html</A>
+
+
+<P><LI><STRONG><A NAME="item_Idiot">Idiot's Guide to CGI programming</A></STRONG>
+<P>
+<A
+HREF="http://www.perl.com/CPAN/doc/FAQs/cgi/idiots-guide.html">http://www.perl.com/CPAN/doc/FAQs/cgi/idiots-guide.html</A>
+
+
+<P><LI><STRONG><A NAME="item_WWW">WWW Security FAQ</A></STRONG>
+<P>
+<A
+HREF="http://www.w3.org/Security/Faq/www-security-faq.html">http://www.w3.org/Security/Faq/www-security-faq.html</A>
+
+
+<P><LI><STRONG><A NAME="item_CGI">CGI/Perl Taint Mode FAQ</A></STRONG>
+<P>
+<A
+HREF="http://www.gunther.web66.com/FAQS/taintmode.html">http://www.gunther.web66.com/FAQS/taintmode.html</A>
+(by Gunther Birznieks)
+
+</UL>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Handling_cookies">Handling cookies</A></H1></CENTER>
+<CENTER><H1><A NAME="Get_helped_with_Apache">Get helped with Apache</A></H1></CENTER>
+<UL>
+<P><LI><STRONG><A NAME="item_Apache">Apache Project's Home</A></STRONG>
<P>
-Unless you use some well known modules like CGI.pm you can handle the
-cookies yourself.
+<A HREF="http://www.apache.org">http://www.apache.org</A>
+<P><LI><STRONG><A NAME="item_Apache">Apache Quick Reference Card</A></STRONG>
<P>
-Cookies come in the $ENV{HTTP_COOKIE} variable. You can print the raw
-cookie string as $ENV{HTTP_COOKIE}.
+<A HREF="http://www.refcards.com">http://www.refcards.com</A> (Apache and
+other refcards are available from this link)
+<P><LI><STRONG><A NAME="item_The">The Apache FAQ</A></STRONG>
<P>
-This is a fairly well-known bit of code to take cookie values and put them
-into a hash.
+<A
+HREF="http://www.apache.org/docs/misc/FAQ.html">http://www.apache.org/docs/misc/FAQ.html</A>
+
+<P><LI><STRONG><A NAME="item_Apache">Apache Server Documentation</A></STRONG>
<P>
-<PRE> sub getCookies {
- # cookies are seperated by a semicolon and a space, this will
- # split them and return a hash of cookies
- local(@rawCookies) = split (/; /,$ENV{'HTTP_COOKIE'});
- local(%cookies);
-
- foreach(@rawCookies){
- ($key, $val) = split (/=/,$_);
- $cookies{$key} = $val;
- }
-
- return %cookies;
- }
-</PRE>
+<A HREF="http://www.apache.org/docs/">http://www.apache.org/docs/</A>
+
+<P><LI><STRONG><A NAME="item_Apache">Apache Handlers</A></STRONG>
+<P>
+<A
+HREF="http://www.apache.org/docs/handler.html">http://www.apache.org/docs/handler.html</A>
+
+
+</UL>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Get_helped_with_DBI">Get helped with DBI</A></H1></CENTER>
+<UL>
+<P><LI><STRONG><A NAME="item_Perl">Perl DBI examples</A></STRONG>
+<P>
+<A
+HREF="http://eskimo.tamu.edu/~jbaker/dbi-examples.html">http://eskimo.tamu.edu/~jbaker/dbi-examples.html</A>
+(by Jeffrey William Baker).
+
+<P><LI><STRONG><A NAME="item_DBI">DBI at Hermetica</A></STRONG>
+<P>
+<A
+HREF="http://www.hermetica.com/technologia/DBI/">http://www.hermetica.com/technologia/DBI/</A>
+
+
+<P><LI><STRONG><A NAME="item_DBI">DBI mailing list information</A></STRONG>
+<P>
+<A HREF="http://www.fugue.com/dbi/">http://www.fugue.com/dbi/</A>
+
+<P><LI><STRONG><A NAME="item_DBI">DBI mailing list archives</A></STRONG>
+<P>
+<A
+HREF="http://outside.organic.com/mail-archives/dbi-users/">http://outside.organic.com/mail-archives/dbi-users/</A>
+
+
+<P><LI><STRONG><A NAME="item_Persistent">Persistent connections with mod_perl</A></STRONG>
+<P>
+<A
+HREF="http://perl.apache.org/src/mod_perl.html#PERSISTENT_DATABASE_CONNECTIONS">http://perl.apache.org/src/mod_perl.html#PERSISTENT_DATABASE_CONNECTIONS</A>
+
+
+</UL>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -9627,7 +13281,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="snippets.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="download.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -9639,8 +13294,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 04/30/1999
</FONT>
</B>
</TD>
@@ -9667,235 +13322,160 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: </TITLE>
+ <TITLE>mod_perl guide: Appendix A: Downloading software and documentation</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
-<H1 ALIGN=CENTER><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Help. Further Learning</H1>
-
-<P>
-<HR WIDTH="100%"></P>
-
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
-
+<A NAME="toc"></A>
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+Appendix A: Downloading software and documentation</H1>
+<HR WIDTH="100%">
+ [ <A HREF="help.html">Prev</A> | <A HREF="index.html">Main Page</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
-<LI><A HREF="#1">READ ME FIRST</A></LI>
-
-<LI><A HREF="#author">This document's Author</A></LI>
-
-<LI><A HREF="#2">Get helped with mod_perl</A></LI>
-
-<LI><A HREF="#3">Get helped with perl </A></LI>
-
-<LI><A HREF="#4">Get helped with perl/CGI</A></LI>
-<LI><A HREF="#5">Get helped with apache </A></LI>
-
-<LI><A HREF="#6">Get helped with DBI </A></LI>
+ <LI><A HREF="#Coverage">Coverage</A>
+ <LI><A HREF="#perl">perl</A>
+ <LI><A HREF="#apache">apache</A>
+ <LI><A HREF="#mod_perl">mod_perl</A>
+ <LI><A HREF="#Squid">Squid</A>
+ <LI><A HREF="#thttpd">thttpd</A>
+ <LI><A HREF="#mod_proxy_add_forward">mod_proxy_add_forward</A>
</UL>
-
-<P>
-<HR WIDTH="100%"></P>
-
-<H3><A NAME="1"></A>READ ME FIRST</H3>
-
-<P>If after reading this guide and other documents listed in this section,
-you feel that your question is yet not answered, please ask the apache/mod_perl
-mailing list to help you. But first try to browse the mailing list archive.
-Most of the time you will find the answer for your question by searching
-the mailing archive, since there is a big chance someone else already have
-encountered the problem and found a solution for it. If you ignore this
-advice, don't be surprised if your question will be left unanswered - it
-bores people to answer the same question more than once. It doesn't mean
-that you should avoid asking questions. Just don't abuse the available
-help and <B>RTFM </B>before you call for <B>HELP</B>. (You have certainly
-heard the infamous fable of the shepherd boy and the wolves)</P>
-
-<P>For more information See <A HREF="#2">Get helped with mod_perl</A>.
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
-
-<H3><A NAME="author"></A>This document's Author</H3>
-
-<P>Hi, I wrote this document to help you with mod_perl.
-It doesn't mean that if you have any question regarding
-mod_perl, perl or whatever you think I might know,
-you should directly send it to me. Please see the
-<A HREF="help.html#2">Get helped with mod_perl</A> section and
-follow the guidelines as prescribed there.</P>
-
-<P>However, You are welcome to submit any corrections
-<A href="mailto:sbekman@iname.com?subject=mod_perl%20guide%20corrections">
-directly to me</A>. <B>But please no questions, they will
-be immediately deleted.</B></P>
+<!-- INDEX END -->
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
+<HR>
-<H3><A NAME="2"></A>Get helped with mod_perl</H3>
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
-<UL>
-<LI><A HREF="HTTP://perl.apache.org">perl.apache.org </A>- mod_perl home </LI>
+ <HR>
-<LI><A HREF="HTTP://www.modperl.com">www.modperl.com</A> - This is the home site
-of The Apache Modules Book, a book about creating Web server modules using
-the Apache API, written by Lincoln Stein and Doug MacEachern.
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-Now you can purchase the book at your local bookstore or from the online dealer.
-O'Reilly lists this book as:
-<PRE>
- Writing Apache Modules with Perl and C
- By Lincoln Stein & Doug MacEachern
- 1st Edition March 1999
- 1-56592-567-X, Order Number: 567X
- 746 pages, $34.95
-</PRE>
-
-</LI>
-
-<LI><A HREF="http://perl.apache.org/dist/cgi_to_mod_perl.html">Quick guide
-</A>for moving from CGI to mod_perl. </LI>
-
-<LI>Frank Cringle's <A HREF="http://perl.apache.org/faq/">mod_perl FAQ</A></LI>
-
-<LI>Vivek Khera's <A HREF="http://perl.apache.org/tuning/">mod_perl performance
-tuning guide</A></LI>
-
-<LI>Doug MacEachern's <A HREF="http://perl.apache.org/src/mod_perl.html">mod_perl
-plugin reference guide</A>. </LI>
-
-<LI><A HREF="http://perl.apache.org/dist/mod_perl_traps.html">mod_perl_traps,</A>
-common traps and solutions for mod_perl users. </LI>
-
-<LI><A HREF="http://www.refcards.com">mod_perl Quick Reference
- Card</A>
-(Apache and other refcards are available from this link</LI>
-
-<LI>mod_perl mailing list</LI>
-
-<P>The Apache/Perl mailing list (modperl@apache.org) <B>is available
-for mod_perl users and developers to share ideas, solve problems and
-discuss things related to mod_perl and the Apache::* modules.</B> To
-subscribe to this list, send mail to <a
-href="mailto:majordomo@apache.org">majordomo@apache.org</a> with the
-string "subscribe modperl" in the body. </P>
-
-<P><B>Searchable </B>mod_perl mailing list <A
-HREF="http://forum.swarthmore.edu/epigone/modperl"><B>archive</B></A> by Ken Williams. </P> </UL>
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
-
-<H3><A NAME="3"></A>Get helped with Perl </H3>
-
-<UL>
-<LI><A HREF="http://www.perl.com/CPAN/doc/FAQs/FAQ/PerlFAQ.html">The Perl
-FAQ </A></LI>
-
-<LI><A HREF="http://www.perl.com/">www.perl.com</A></LI>
-
-<LI><A HREF="http://www.tpj.com/">The Perl Journal </A></LI>
-
-<LI><A HREF="http://world.std.com/~swmcd/steven/perl/module_mechanics.html">Perl
-Module Mechanics </A>- This page describes the mechanics of creating, compiling,
-releasing and maintaining Perl modules. </LI>
-</UL>
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
-
-<H3><A NAME="4"></A>Get helped with Perl/CGI</H3>
-
-<UL>
-<LI><A HREF="http://www.perl.com/CPAN/doc/FAQs/cgi/perl-cgi-faq.html">Perl/CGI
-FAQ </A></LI>
-
-<LI><A
-HREF="http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html">Answers
-to some bothering Perl and Perl/CGI questions</A></LI>
-
-<LI><A HREF="http://www.perl.com/CPAN/doc/FAQs/cgi/idiots-guide.html">Idiot's
-Guide to CGI programming </A></LI>
-
-<LI><A HREF="http://www.w3.org/Security/Faq/www-security-faq.html">WWW
-Security FAQ </A></LI>
-
-<LI><A HREF="http://www.gunther.web66.com/FAQS/taintmode.html">CGI/Perl
-Taint Mode FAQ</A> (by Gunther Birznieks)</LI>
-</UL>
-
-<H3><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></H3>
-
-<H3><A NAME="5"></A>Get helped with Apache </H3>
-
-<UL>
-<LI><A HREF="http://www.apache.org">Apache Project's Home</A></LI>
-
-<LI><A HREF="http://www.ford-mason.co.uk/resources/refcards/apache.html">Apache
-Quick Reference Card</A></LI>
-
-<LI><A HREF="http://www.apache.org/docs/misc/FAQ.html">The Apache FAQ</A></LI>
-
-<LI><A HREF="http://www.apache.org/docs/">Apache Server Documentation</A></LI>
-
-<LI><A HREF="http://www.apache.org/docs/handler.html">Apache Handlers</A></LI>
-
-</UL>
+<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
+<P>
+Here you will find the instructions for downloading the software and the
+related documentation.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="perl">perl</A></H1></CENTER>
+<P>
+Perl is most likely already installed on your machine, but you should at
+least check the version you using. It is highly recommended that you have
+at least perl version 5.004 or higher. You can get the latest perl version
+from <A HREF="http://www.perl.com/">http://www.perl.com/</A> . Try the
+direct download link <A
+HREF="http://www.perl.com/pace/pub/perldocs/latest.html">http://www.perl.com/pace/pub/perldocs/latest.html</A>
+. You can get a perl documentation from the same location.
-<H3><A NAME="6"></A>Get helped with DBI </H3>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="apache">apache</A></H1></CENTER>
+<P>
+Get the latest apache webserver and documentation from <A
+HREF="http://www.apache.org">http://www.apache.org</A> . Try the direct
+download link <A
+HREF="http://www.apache.org/dist/">http://www.apache.org/dist/</A> .
-<UL>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="mod_perl">mod_perl</A></H1></CENTER>
+<P>
+Get the latest mod_perl sources and documentation from <A
+HREF="http://perl.apache.org">http://perl.apache.org</A> . Try the direct
+download link <A
+HREF="http://perl.apache.org/dist/">http://perl.apache.org/dist/</A> .
-<LI><A HREF="http://eskimo.tamu.edu/~jbaker/dbi-examples.html">Perl DBI examples</A>
-by Jeffrey William Baker.</LI>
-
-<LI><a href="http://www.hermetica.com/technologia/DBI/">DBI at Hermetica</a>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Squid">Squid</A></H1></CENTER>
+<P>
+<META>
-<LI><a href="http://www.fugue.com/dbi/">DBI mailing list information</a>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="thttpd">thttpd</A></H1></CENTER>
+<P>
+<META>
-<LI><a href="http://outside.organic.com/mail-archives/dbi-users/">DBI mailing list archives</a>
-
-<LI><a href="http://perl.apache.org/src/mod_perl.html#PERSISTENT_DATABASE_CONNECTIONS">Persistent connections with mod_perl</a>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="mod_proxy_add_forward">mod_proxy_add_forward</A></H1></CENTER>
+<P>
+Ask Bjoern Hansen has written a <CODE>mod_proxy_add_forward.c</CODE> module for Apache, that sets the <CODE>X-Forwarded-For</CODE> field when doing a ProxyPass, similar to what Squid can do. His patch is
+at: <A
+HREF="http://modules.apache.org/search?id=124">http://modules.apache.org/search?id=124</A>
+or at <A
+HREF="ftp://ftp.netcetera.dk/pub/apache/">ftp://ftp.netcetera.dk/pub/apache/</A>
-</UL>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main page]</A></P>
+ <HR>
+ [ <A HREF="help.html">Prev</A> | <A HREF="index.html">Main Page</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
-<TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
-<HR></TD>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
</TR>
-
<TR ALIGN=CENTER VALIGN=TOP>
-<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A HREF="help.html#author">Stas
-Bekman</A>.<BR>
-Last Modified at 04/17/1998 </FONT></B></TD>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
+ </FONT>
+ </B>
+ </TD>
-<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" BORDER=0 ALT="Mod Perl Icon" HEIGHT=59 WIDTH=150></A>
-</TD>
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
-<TD><FONT SIZE=-2>Use of the Camel for Perl is <BR>
-a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
-and is used by permission. </FONT> </TD>
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
</TR>
</TABLE></CENTER>
</BODY>
</HTML>
-
+
<HR SIZE=6>
1.12 +111 -81 modperl-site/guide/config.html
Index: config.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/config.html,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- config.html 1999/04/19 19:53:29 1.11
+++ config.html 1999/05/08 17:46:29 1.12
@@ -4,8 +4,11 @@
<TITLE>mod_perl guide: Server Configuration</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,30 +19,36 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Server Configuration</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="install.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="frequent.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
- <LI><A HREF="#Configuration">Configuration</A>
+ <LI><A HREF="#mod_perl_Specific_Configuration">mod_perl Specific Configuration</A>
<UL>
<LI><A HREF="#Alias_Configurations">Alias Configurations</A>
+ <LI><A HREF="#Location_Configuration">Location Configuration</A>
+ <LI><A HREF="#PerlFreshRestart">PerlFreshRestart</A>
+ <LI><A HREF="#_perl_status_location">/perl-status location</A>
+ <LI><A HREF="#perl_startup_file">perl-startup file</A>
+ <UL>
+
+ <LI><A HREF="#Sample_perl_startup_file">Sample perl-startup file</A>
+ <LI><A HREF="#What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A>
+ <LI><A HREF="#Is_it_possible_to_preopen_a_DB_c">Is it possible to preopen a DB connection at the server startup?</A>
+ </UL>
+
</UL>
- <LI><A HREF="#Location_Configuration">Location Configuration</A>
- <LI><A HREF="#_perl_status_location">/perl-status location </A>
- <LI><A HREF="#perl_startup_file">perl-startup file</A>
- <LI><A HREF="#PerlFreshRestart">PerlFreshRestart</A>
- <LI><A HREF="#What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A>
- <LI><A HREF="#Is_it_possible_to_preopen_a_DB_c">Is it possible to preopen a DB connection at the server startup?</A>
<LI><A HREF="#Perl_behavior_controls">Perl behavior controls</A>
- <LI><A HREF="#Tuning_MinSpareServers_MaxSpareS">Tuning MinSpareServers MaxSpareServers StartServers MaxClients MaxRequestsPerChild </A>
+ <LI><A HREF="#Tuning_MinSpareServers_MaxSpareS">Tuning MinSpareServers MaxSpareServers StartServers MaxClients</A>
+ <LI><A HREF="#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>
<LI><A HREF="#Perl_Sections">Perl Sections</A>
<LI><A HREF="#Configuring_Apache_mod_perl_wi">Configuring Apache + mod_perl with mod_macro</A>
<LI><A HREF="#General_pitfalls">General pitfalls</A>
@@ -55,11 +64,9 @@
</UL>
<!-- INDEX END -->
-
+<HR>
- <P><A HREF="index.html">[Back to the main index]</A></P>
-
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -68,9 +75,11 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<CENTER><H1><A NAME="Configuration">Configuration</A></H1></CENTER>
+<CENTER><H1><A NAME="mod_perl_Specific_Configuration">mod_perl Specific Configuration</A></H1></CENTER>
<P>
The next step after building and installing your new mod_perl-enabled
Apache server, is to configure the server's configuration files. To learn
@@ -85,7 +94,8 @@
<P>
[ Note that prior to version 1.3.4, the default Apache install used three
-configuration files -- <STRONG>httpd.conf</STRONG>, <STRONG>srm.conf</STRONG>, and <STRONG>access.conf</STRONG>. The 1.3.4 version began distributing the configuration directives in a
+configuration files -- <STRONG>httpd.conf</STRONG>, <STRONG>srm.conf</STRONG>, and
+<STRONG>access.conf</STRONG>. The 1.3.4 version began distributing the configuration directives in a
single file -- <STRONG>httpd.conf</STRONG>. The remainder of this chapter refers to the location of the configuration
directives using their historical location. ]
@@ -97,29 +107,30 @@
located.
<P>
-Add the following configuration directives to srm.conf:
+Add the following configuration directives:
<P>
-<PRE> # plain cgi-bin:
- ScriptAlias /cgi-bin/ /usr/apps/myproject/cgi/
+<PRE> # for plain cgi-bin:
+ ScriptAlias /cgi-bin/ /usr/local/myproject/cgi/
- # Apache::Registry mode
- Alias /perl/ /usr/apps/myproject/cgi/
+ # for Apache::Registry mode
+ Alias /perl/ /usr/local/myproject/cgi/
# Apache::PerlRun mode
- Alias /cgi-perl/ /usr/apps/myproject/cgi/
+ Alias /cgi-perl/ /usr/local/myproject/cgi/
</PRE>
<P>
-Alias provides a mapping of URL to file system object.
+<CODE>Alias</CODE> provides a mapping of URL to file system object under
+<CODE>mod_perl</CODE>. <CODE>ScriptAlias</CODE> is being used for <CODE>mod_cgi</CODE>.
<P>
Alias defines the start of the URL path to the script you are referencing.
For example, using the above configuration, fetching
-<STRONG>http://www.you.com/perl/test.pl</STRONG>, will cause the server to look for the file <STRONG>test.pl</STRONG> at <STRONG>/usr/apps/myproject/cgi</STRONG>, and execute it as an <STRONG>Apache::Registry</STRONG> script. The URL
+<STRONG>http://www.you.com/perl/test.pl</STRONG>, will cause the server to look for the file <STRONG>test.pl</STRONG> at <STRONG>/usr/local/myproject/cgi</STRONG>, and execute it as an <STRONG>Apache::Registry</STRONG> script if we define Apache::Register to be the handler of <CODE>/perl</CODE> location (see below). The URL
<STRONG>http://www.you.com/perl/test.pl</STRONG> will be mapped to
-<STRONG>/usr/apps/myproject/cgi/test.pl</STRONG>. This means you can have all your CGIs located at the same place at file
+<STRONG>/usr/local/myproject/cgi/test.pl</STRONG>. This means you can have all your CGIs located at the same place at file
system, and call the script in any of three modes simply by changing the
-directory name component of the URL (cgi-bin|perl|cgi-perl) - is not that
+directory name component of the URL (cgi-bin|perl|cgi-perl) - is not this
cool? (That is the configuration you see above - all three Aliases point to
the same directory within your file system, but of course they can be
different). If your script does not seem to be working while running under
@@ -128,27 +139,24 @@
you invoke it by.
<P>
-FYI: for modperl ScriptAlias is the same thing as an Alias command +
-'sethandler cgi-handler'. The latter will be overwritten if you enable
-Apache::Registry. In other words, ``ScriptAlias does not work for
-mod_perl'', it only appears to work when the additional configuration is in
-there. If the Apache::Registry configuration came before the ScriptAlias,
-scripts would be run under mod_cgi. While handy, ScriptAlias is a known
-kludge, always better to use 'Alias' and 'SetHandler'.
+FYI: for modperl <CODE>ScriptAlias</CODE> is the same thing as an <CODE>Alias</CODE>
+directive + <CODE>sethandler cgi-handler</CODE>. The latter will be overwritten if you enable <CODE>Apache::Registry</CODE>. In other words, <CODE>ScriptAlias</CODE> does not work for mod_perl, it only appears to work when the additional
+configuration is in there. If the <CODE>Apache::Registry</CODE> configuration came before the <CODE>ScriptAlias</CODE>, scripts would be run under mod_cgi. While handy, <CODE>ScriptAlias</CODE> is a known kludge, always better to use
+<CODE>Alias</CODE> and <CODE>SetHandler</CODE>.
<P>
Of course you can choose any other alias (you will use it later in
http.conf), you can choose to use all three modes or only one of these (It
is undesirable to run plain cgi-bin scripts from a mod_perl-enabled server
- the price is too high, it is better to run these on plain Apache server.
-See <A HREF="././scenario.html#Making_a_strategic_decision">Real World scenario</A> for details.)
+(META: add link to strategies)
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Location_Configuration">Location Configuration</A></H1></CENTER>
+<CENTER><H2><A NAME="Location_Configuration">Location Configuration</A></H2></CENTER>
<P>
-Now we will work with the httpd.conf file. I add all the mod_perl stuff at
-the end of the file, after the native Apache configurations.
+Now we will work with the <CODE>httpd.conf</CODE> file. I add all the mod_perl stuff at the end of the file, after the native
+Apache configurations.
<P>
First we add:
@@ -179,7 +187,7 @@
will fail to locate the script in the file system. (We are talking about
script execution here -- there are cases where Location is something that
is being executed by the server itself, without having the corresponding
-file, like <A HREF="#perl_status">perl-status</A>.)
+file, like <A HREF="#_perl_status_location">perl-status location</A>.)
<P>
Note that sometimes you will have to add : PerlModule Apache::Registry
@@ -209,27 +217,45 @@
</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="_perl_status_location">/perl-status location</A></H1></CENTER>
+<CENTER><H2><A NAME="PerlFreshRestart">PerlFreshRestart</A></H2></CENTER>
<P>
-Adding a directive to enable a <STRONG>/perl-status</STRONG> location allows you to see many things about your server. See /<A HREF="././status.html#Configuration">perl-status</A>
+To reload <STRONG>PerlRequire</STRONG>, <STRONG>PerlModule</STRONG>, other <CODE>use()'d</CODE> modules and flush the Apache::Registry cache
+on server restart, add:
+<P>
+<PRE> PerlFreshRestart On
+</PRE>
+<P>
+Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="_perl_status_location">/perl-status location</A></H2></CENTER>
+<P>
+Adding a directive to enable a <STRONG>/perl-status</STRONG> location allows you to see many things about your server. See
+<A HREF="././status.html#Configuration">perl-status</A>
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="perl_startup_file">perl-startup file</A></H1></CENTER>
+<CENTER><H2><A NAME="perl_startup_file">perl-startup file</A></H2></CENTER>
<P>
Since many times you have to add many perl directives to the configuration
file, it can be a good idea to put all of these into one file, so the
-configuration file will be cleaner, also you can call <STRONG>perl -c perl-startup</STRONG>
-to test the file's syntax. What does this take? Add this line to
+configuration file will be cleaner, also you can call
+<STRONG>perl -c perl-startup</STRONG> to test the file's syntax. What does this take? Add this line to
httpd.conf:
<P>
-<PRE> # startup.perl loads all functions that we want to use within mod_perl
- Perlrequire /path/to/startup.pl
+<PRE> # startup.perl loads all functions that we want to use within
+ # mod_perl
+ Perlrequire /path/to/startup.pl
</PRE>
<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H3><A NAME="Sample_perl_startup_file">Sample perl-startup file</A></H3></CENTER>
+<P>
An example of perl-startup file:
<P>
@@ -239,7 +265,8 @@
use lib qw(/some/other/dir /some/bar/dir);
# make sure we are in a sane environment.
- $ENV{GATEWAY_INTERFACE} =~ /^CGI-Perl/ or die "GATEWAY_INTERFACE not Perl!";
+ $ENV{GATEWAY_INTERFACE} =~ /^CGI-Perl/
+ or die "GATEWAY_INTERFACE not Perl!";
# for things in the "/perl" URL
use Apache::Registry;
@@ -275,21 +302,8 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="PerlFreshRestart">PerlFreshRestart</A></H1></CENTER>
+<CENTER><H3><A NAME="What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A></H3></CENTER>
<P>
-To reload <STRONG>PerlRequire</STRONG>, <STRONG>PerlModule</STRONG>, other <CODE>use()'d</CODE> modules and flush the Apache::Registry cache
-on server restart, add:
-
-<P>
-<PRE> PerlFreshRestart On
-</PRE>
-<P>
-Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A></H1></CENTER>
-<P>
Modules that are being loaded at the server startup will be shared among
server children, so only one copy of each module will be loaded, thus
saving a lot of RAM for you.
@@ -301,7 +315,7 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Is_it_possible_to_preopen_a_DB_c">Is it possible to preopen a DB connection at the server startup?</A></H1></CENTER>
+<CENTER><H3><A NAME="Is_it_possible_to_preopen_a_DB_c">Is it possible to preopen a DB connection at the server startup?</A></H3></CENTER>
<P>
Yes! See <A HREF="././performance.html#Persistent_DB_Connections">Persistent DB Connections</A>
@@ -317,7 +331,8 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Tuning_MinSpareServers_MaxSpareS">Tuning MinSpareServers MaxSpareServers StartServers MaxClients MaxRequestsPerChild</A></H1></CENTER>
+<CENTER><H1><A NAME="Tuning_MinSpareServers_MaxSpareS">Tuning MinSpareServers MaxSpareServers StartServers MaxClients
+MaxRequestsPerChild</A></H1></CENTER>
<P>
See <A HREF="././performance.html#Tuning_the_Apache_s_configuratio">Tuning the Apache's configuration variables for the best performance</A>
@@ -325,6 +340,21 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Publishing_port_numbers_differen">Publishing port numbers different from 80</A></H1></CENTER>
+<P>
+It is advised not to publish the 8080 (or alike) port number in URLs, but
+rather using a proxying rewrite rule in the thin (httpd_docs) server:
+
+<P>
+<PRE> RewriteRule .*/perl/(.*) <A HREF="http://my.url:8080/perl/">http://my.url:8080/perl/</A>$1 [P]
+</PRE>
+<P>
+One problem with publishing 8080 port numbers is that I was told that IE
+4.x has a bug when re-posting data to a non-port-80 url. It drops the port
+designator, and uses port 80 anyway.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Perl_Sections">Perl Sections</A></H1></CENTER>
<P>
With <STRONG><Perl></Perl></STRONG> sections, it is possible to configure your server entirely in Perl.
@@ -352,7 +382,7 @@
</PRE>
<P>
Block sections such as <Location></Location> are represented in
-a %Hash, e.g.:
+a %Hash, e.g.:
<P>
<PRE> $Location{"/~dougm/"} = {
@@ -368,8 +398,7 @@
</PRE>
<P>
If a Directive can take two *or* three arguments you may push strings and
-the lowest number of arguments will be shifted off the
-<CODE>@List</CODE> or use array reference to handle any number greater than the minimum for
+the lowest number of arguments will be shifted off the <CODE>@List</CODE> or use array reference to handle any number greater than the minimum for
that directive:
<P>
@@ -380,8 +409,8 @@
push @Redirect, [qw(temp "/here" "<A HREF="http://www.there.com"">http://www.there.com"</A>;)];
</PRE>
<P>
-Other section counterparts include <STRONG>%VirtualHost</STRONG>,
-<STRONG>%Directory</STRONG> and <STRONG>%Files</STRONG>.
+Other section counterparts include <STRONG>%VirtualHost</STRONG>, <STRONG>%Directory</STRONG> and
+<STRONG>%Files</STRONG>.
<P>
To pass all environment variables to the children with a single
@@ -399,15 +428,15 @@
</PRE>
<P>
These are somewhat simple 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 in mod_perl distribution for some examples.
+idea. You can mix in any Perl code your heart desires. See
+<CODE>eg/httpd.conf.pl</CODE> and <CODE>eg/perl_sections.txt</CODE> in mod_perl distribution for some examples.
<P>
-A tip for syntax checking outside of httpd:
+A tip for syntax checking outside of httpd:
<P>
<PRE> <Perl>
- #!perl
+ # !perl
#... code here ...
@@ -418,7 +447,7 @@
Now you may run <STRONG>perl -cx httpd.conf</STRONG>.
<P>
-To configure this feature build with <STRONG>perl Makefile.PL
+To configure this feature build with <STRONG>perl Makefile.PL
PERL_SECTIONS=1</STRONG>
@@ -437,8 +466,8 @@
<P>
First download the latest version of mod_macro from <A
-HREF="http://www.cri.ensmp.fr/~coelho/mod_macro/,">http://www.cri.ensmp.fr/~coelho/mod_macro/,</A>
-and configure your Apache server to use this module.
+HREF="http://www.cri.ensmp.fr/~coelho/mod_macro/">http://www.cri.ensmp.fr/~coelho/mod_macro/</A>
+, and configure your Apache server to use this module.
<P>
Here are some useful macros for mod_perl users:
@@ -626,7 +655,7 @@
script running for more than one Virtual host on the same machine, this can
be a waste, right? Set it to 0 in a startup script if you want to turn it
off and have this bug as a feature. (Only makes sense if you are sure that
-there will be no <STRONG>other</STRONG> scripts named by the same path/name)
+there will be no <STRONG>other</STRONG>scripts named by the same path/name)
<P>
<PRE> $Apache::Registry::NameWithVirtualHost = 0;
@@ -649,7 +678,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="install.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="frequent.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -661,8 +691,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
1.13 +141 -69 modperl-site/guide/control.html
Index: control.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/control.html,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- control.html 1999/04/19 19:53:30 1.12
+++ control.html 1999/05/08 17:46:29 1.13
@@ -4,8 +4,11 @@
<TITLE>mod_perl guide: Controlling and Monitoring the Server</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,31 +19,30 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Controlling and Monitoring the Server</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="multiuser.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="status.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Restarting_techniques">Restarting techniques</A>
<LI><A HREF="#Implications_of_sending_TERM_HU">Implications of sending TERM, HUP, and USR1 to the server</A>
<LI><A HREF="#Using_apachectl_to_control_the_s">Using apachectl to control the server</A>
+ <LI><A HREF="#SUID_start_up_scripts">SUID start-up scripts</A>
<LI><A HREF="#Monitoring_the_Server_A_watchdo">Monitoring the Server. A watchdog.</A>
- <LI><A HREF="#Running_in_Single_Mode">Running in Single Mode</A>
+ <LI><A HREF="#Running_server_in_a_single_mode">Running server in a single mode</A>
<LI><A HREF="#Starting_a_personal_server_for_e">Starting a personal server for each developer</A>
<LI><A HREF="#Wrapper_to_emulate_the_server_en">Wrapper to emulate the server environment</A>
<LI><A HREF="#Log_Rotation">Log Rotation</A>
<LI><A HREF="#Preventing_from_modperl_process_">Preventing from modperl process to eat up all the disk's space, when it goes wild.</A>
</UL>
<!-- INDEX END -->
-
-
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -50,7 +52,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Restarting_techniques">Restarting techniques</A></H1></CENTER>
<P>
@@ -79,7 +83,7 @@
This will produce a list of all httpd_perl (the parent and the children)
processes. You are looking for the parent process. If you run your server
as root - you will easily locate it, since it belongs to root. If you run
-the server as user (when you <A HREF="././scenario.html#Is_it_possible_to_install_mod_pe">don't have a root access</A>, most likely all the processes will belong to that user (unless defined
+the server as user (when you <A HREF="././install.html#Is_it_possible_to_install_and_us">don't have a root access</A>, most likely all the processes will belong to that user (unless defined
differently in the httpd.conf), but it's still easy to know 'who is the
parent' -- the one of the smallest size...
@@ -240,6 +244,67 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="SUID_start_up_scripts">SUID start-up scripts</A></H1></CENTER>
+<P>
+For those who wants to use SUID startup script, here is an example for you.
+This script is SUID to <STRONG>root</STRONG>, and should be executable only by members of some special group at your
+site. Note the 10th line, which ``fixes an obscure error when starting
+apache/mod_perl'' by setting the real to the effective UID. As others have
+pointed out, it is the mismatch between the real and the effective UIDs
+that causes Perl to croak on the -e switch.
+
+<P>
+Note that you must be using a version of Perl that recognizes and emulates
+the suid bits in order for this to work. The script will do different
+things depending on whether it is named ``start_http'', ``stop_http'' or
+``restart_http''. You can use symbolic links for this purpose.
+
+<P>
+<PRE> #!/usr/bin/perl
+
+ # These constants will need to be adjusted.
+ $PID_FILE = '/home/www/logs/httpd.pid';
+ $HTTPD = '/home/www/httpd -d /home/www';
+
+ # These prevent taint warnings while running suid
+ $ENV{PATH}='/bin:/usr/bin';
+ $ENV{IFS}='';
+
+ # This sets the real to the effective ID, and prevents
+ # an obscure error when starting apache/mod_perl
+ $< = $>;
+ $( = $) = 0; # set the group to root too
+
+ # Do different things depending on our name
+ ($name) = $0 =~ m|([^/]+)$|;
+
+ if ($name eq 'start_http') {
+ system $HTTPD and die "Unable to start HTTP";
+ print "HTTP started.\n";
+ exit 0;
+ }
+
+ # extract the process id and confirm that it is numeric
+ $pid = `cat $PID_FILE`;
+ $pid =~ /(\d+)/ or die "PID $pid not numeric";
+ $pid = $1;
+
+ if ($name eq 'stop_http') {
+ kill 'TERM',$pid or die "Unable to signal HTTP";
+ print "HTTP stopped.\n";
+ exit 0;
+ }
+
+ if ($name eq 'restart_http') {
+ kill 'HUP',$pid or die "Unable to signal HTTP";
+ print "HTTP restarted.\n";
+ exit 0;
+ }
+
+ die "Script must be named start_http, stop_http, or restart_http.\n";
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Monitoring_the_Server_A_watchdo">Monitoring the Server. A watchdog.</A></H1></CENTER>
<P>
With mod_perl many things can happen to your server. The worst one is the
@@ -310,13 +375,30 @@
served by the server. Why is it more practical? While server can be up as a
process, it can be stuck and not working (SYN_RECV state - anyone??? Am I
getting a SYNC flood attack), So failing to get the document will trigger
-restart, and ``probably'' the problem will go away. (Just replace
-<CODE>start</CODE> with <CODE>restart</CODE> in the <CODE>$restart_command</CODE> below.
+restart, and ``probably'' the problem will go away. (Just replace <CODE>start</CODE> with <CODE>restart</CODE> in the
+<CODE>$restart_command</CODE> below.
+
+<P>
+Again we put this script into a crontab to call it every 30 minutes.
+Personally I call it every minute, to fetch some very light script. Why so
+often? If your server starts to spin and trash your disk's space with
+multiply error messages. In a 5 minutes you might run out of free space,
+which might bring your system to its knees. And most chances that no other
+child will be able to serve requests, since the system will be too busy,
+writing to an <CODE>error_log</CODE> file. Think big - if you running a heavy service, which is very fast, since
+you are running under mod_perl, adding one more request every minute, will
+be not felt by the server at all.
<P>
-Again we put this script into a crontab to call it every 30 minutes.
+So we end up with crontab entry:
<P>
+<PRE> * * * * * /path/to/the/watchdog.pl >/dev/null 2>&1
+</PRE>
+<P>
+And the watchdog itself:
+
+<P>
<PRE> #!/usr/local/bin/perl -w
use strict;
@@ -399,24 +481,13 @@
close MAIL;
}
-
-</PRE>
-<P>
-<PRE> <META>
- Is it possible to make the server do something when it dies? e.g
- restart itself :) NO, really when it dies , (killed in improper way?)
- is it possible to trigger some action?
-</PRE>
-<P>
-<PRE> Ideas?
- </META>
</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Running_in_Single_Mode">Running in Single Mode</A></H1></CENTER>
+<CENTER><H1><A NAME="Running_server_in_a_single_mode">Running server in a single mode</A></H1></CENTER>
<P>
Often while developing new code, you will want to run the server in single
-process mode. See <A HREF="././porting.html#Sometimes_it_works_Sometimes_Not">Sometimes it works Sometimes Not</A> and <A HREF="././porting.html#Names_collisions_with_Modules_an">Names collisions with Modules and libs</A>
+process mode. See <A HREF="././porting.html#Sometimes_it_Works_Sometimes_Not">Sometimes it works Sometimes Not</A> and <A HREF="././porting.html#Name_collisions_with_Modules_and">Names collisions with Modules and libs</A>
Running in single process mode inhibits the server from ``daemonizing'',
allowing you to run it more easily under debugger control.
@@ -425,7 +496,7 @@
</PRE>
<P>
When you execute the above the server will run in the fg (foreground) of
-the shell you have called it from. So to kill you just kill it with Ctrl-C.
+the shell you have called it from. So to kill you just kill it with Ctrl-C.
<P>
Note that in -X mode the server will run very slowly while fetching images.
@@ -435,12 +506,13 @@
process listening, each connection has to time-out before the next
succeeds. Turn off KeepAlive in httpd.conf to avoid this effect while
developing or you can press <STRONG>STOP</STRONG> after a few seconds (assuming you use the image size params, so the
-Netscape will be able to render the rest of the page).
+Netscape will be able to render the rest of the page).
<P>
In addition you should know that when running with -X you will not see any
control messages that the parent server normally writes to the error_log.
-(Like ``server started, server stopped and etc''.) Since <CODE>httpd -X</CODE> causes the server to handle all requests itself, without forking any
+(Like ``server started, server stopped and etc''.) Since
+<CODE>httpd -X</CODE> causes the server to handle all requests itself, without forking any
children, there is no controlling parent to write status messages.
<P>
@@ -454,20 +526,20 @@
have control over the server - to kill it, to run it in single server mode,
to restart it again, etc., as well to have control over the location of the
log files and other configuration settings like <STRONG>MaxClients</STRONG>, etc. You can work around this problem by preparing a few httpd.conf file
-and forcing each developer to use:
+and forcing each developer to use:
<P>
<PRE> httpd_perl -f /path/to/httpd.conf
</PRE>
<P>
-I've approached it in other way. I have used the -Dparameter startup option
-of the server. I call my version of the server
+I have approached it in other way. I have used the -Dparameter startup
+option of the server. I call my version of the server
<P>
<PRE> % http_perl -Dsbekman
</PRE>
<P>
-At the end of the httpd.conf I wrote:
+In <CODE>httpd.conf</CODE> I wrote:
<P>
<PRE> # Personal development Server for sbekman
@@ -519,7 +591,7 @@
<P>
Of course you think you can use only one control file and know who is
calling by using uid, but since you have to be root to start the server -
-it's not so simple.
+it is not so simple.
<P>
The last thing was to let developers an option to run in single process
@@ -536,7 +608,8 @@
<P>
In access.conf of the httpd_docs server we have the following code: (you
-have to configure your httpd_docs server with --enable-module=rewrite )
+have to configure your httpd_docs server with
+<CODE>--enable-module=rewrite</CODE> )
<P>
<PRE> # sbekman' server
@@ -557,18 +630,17 @@
</PRE>
<P>
-where IP numbers are the IPs of the developers' client machine (where they
+where IP numbers are the IPs of the developers' client machines (where they
are running their web browser.) (I have tried to use REMOTE_USER since we
-have all the users authenticated but it didn't work for me)
+have all the users authenticated but it did not work for me)
<P>
-So if I have a relative URL like /perl/test.pl written in some html or even
-<A
+So if I have a relative URL like <CODE>/perl/test.pl</CODE> written in some html or even <A
HREF="http://ourserver.com/perl/test.pl">http://ourserver.com/perl/test.pl</A>
in my case (user at machine of sbekman) it will be redirected by httpd_docs
to <A
HREF="http://ourserver.com:8000/perl/test.pl">http://ourserver.com:8000/perl/test.pl</A>
-
+
<P>
Of course you have another problem: The cgi generates some html, which
@@ -582,17 +654,17 @@
<P>
Second, use a general configuration module which generates a correct full
-URL according to REMOTE_USER, so if $ENV{REMOTE_USER} eq 'sbekman', I
-return <A
+URL according to REMOTE_USER, so if <CODE>$ENV{REMOTE_USER} eq
+'sbekman'</CODE>, I return <A
HREF="http://ourserver.com:8000/perl/">http://ourserver.com:8000/perl/</A>
-as cgi_base_url. Again this will work if the user is authenticated.
+as
+<CODE>cgi_base_url</CODE>. Again this will work if the user is authenticated.
<P>
-All this is good for development. It's better to use the full URLs in
-production, since if you have a static form and the Action is relative but
-the static document sits on another server, pressing the form's submit will
-cause a redirect to mod_perl server, but all the form's data will be lost
-during the redirect.
+All this is good for development. It is better to use the full URLs in
+production, since if you have a static form and the <CODE>Action</CODE> is relative but the static document located on another server, pressing the
+form's submit will cause a redirect to mod_perl server, but all the form's
+data will be lost during the redirect.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -601,18 +673,18 @@
Many times you start off debugging your script by running it from your
favorite shell. Sometimes you encounter a very weird situation when script
runs from the shell but dies when called as a CGI. The real problem lies in
-the difference between the environment that's being used by your server and
-your shell. An example can be a different perl path or having PERL5LIB env
-variable which includes paths that aren't in the <CODE>@INC</CODE> of the
-perl compiled with mod_perl server and configured during the startup.
+the difference between the environment that is being used by your server
+and your shell. An example can be a different perl path or having PERL5LIB
+env variable which includes paths that are not in the <CODE>@INC</CODE> of
+the perl compiled with mod_perl server and configured during the startup.
<P>
The best debugging approach is to write a wrapper that emulates the exact
environment of the server, by first deleting the environment variables like
-PERL5LIB and calling the same perl binary that it's being used by the
+PERL5LIB and calling the same perl binary that it is being used by the
server. Next, set the environment identical to the server's by copying the
-perl run directives from server startup and configuration files. It'll also
-allow you to remove completely the first line of the script - since
+perl run directives from server startup and configuration files. It will
+also allow you to remove completely the first line of the script - since
mod_perl skips it and the wrapper knows how to call the script.
<P>
@@ -697,8 +769,8 @@
<P>
-<META>I tried to kill -USR1 and it didn't reset the logs!!! kill -HUP
-did work</META>
+<META>I tried to kill -USR1 and it did not reset the logs!!! kill
+-HUP did work</META>
<P>
I use this script:
@@ -844,8 +916,8 @@
its knees. For example I get an error <CODE>Callback called exit</CODE>
show up in my error_log file many times. The error_log files grows to 300
Mbytes in size in a few minutes. You should run a cron job to make sure
-this doesn't happen and if it does to take care of it. Andreas J. Koenig is
-running this shell script every minute:
+this does not happen and if it does to take care of it. Andreas J. Koenig
+is running this shell script every minute:
<P>
<PRE> S=`ls -s /usr/local/apache/logs/error_log | awk '{print $1}'`
@@ -856,16 +928,15 @@
</PRE>
<P>
It seems that his script will trigger restart every minute, since once the
-logfile grows to be of 100000 lines, it'll stay of this size, unless you
+logfile grows to be of 100000 lines, it will stay of this size, unless you
remove or rename it, before you do restart. On my server I run a watchdog
-every five minutes which restarts the server if it's getting stuck (it
+every five minutes which restarts the server if it is getting stuck (it
always works since when some modperl child process goes wild, the I/O it
-causes is so heavy that other brother processes can't normally to serve the
-requests.) See <A HREF="././control.html#Monitoring_the_Server_A_watchdo">Monitoring the Server</A> for more hints.
+causes is so heavy that other brother processes cannot normally to serve
+the requests.) See <A HREF="././control.html#Monitoring_the_Server_A_watchdo">Monitoring the Server</A> for more hints.
<P>
-Ulrich Pfeifer told us this: You may also look at the daemontools from D.
-J. Bernstein - <A
+Also check out the daemontools from <A
HREF="ftp://koobera.math.uic.edu/www/daemontools.html">ftp://koobera.math.uic.edu/www/daemontools.html</A>
@@ -887,7 +958,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="multiuser.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="status.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -899,8 +971,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
1.11 +17 -13 modperl-site/guide/debug.html
Index: debug.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/debug.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- debug.html 1999/04/19 19:53:31 1.10
+++ debug.html 1999/05/08 17:46:29 1.11
@@ -4,8 +4,11 @@
<TITLE>mod_perl guide: Debugging mod_perl</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,14 +19,14 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Debugging mod_perl</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="status.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="browserbugs.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Sometimes_script_works_Sometime">Sometimes script works, Sometimes Not</A>
@@ -33,11 +36,9 @@
<LI><A HREF="#gdb_says_there_are_no_debugging_">gdb says there are no debugging symbols</A>
</UL>
<!-- INDEX END -->
-
+<HR>
- <P><A HREF="index.html">[Back to the main index]</A></P>
-
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -46,11 +47,13 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Sometimes_script_works_Sometime">Sometimes script works, Sometimes Not</A></H1></CENTER>
<P>
-See <A HREF="././porting.html#Sometimes_it_works_Sometimes_Not">Sometimes it works Sometimes Not</A>
+See <A HREF="././porting.html#Sometimes_it_Works_Sometimes_Not">Sometimes it works Sometimes Not</A>
@@ -168,7 +171,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="status.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="browserbugs.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -180,8 +184,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
1.4 +18 -16 modperl-site/guide/frequent.html
Index: frequent.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/frequent.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- frequent.html 1999/04/19 19:53:31 1.3
+++ frequent.html 1999/05/08 17:46:30 1.4
@@ -4,8 +4,11 @@
<TITLE>mod_perl guide: Frequent mod_perl problems</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,14 +19,14 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Frequent mod_perl problems</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="config.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="porting.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Coverage">Coverage</A>
@@ -31,10 +34,8 @@
<LI><A HREF="#Segfaults_caused_by_PerlFreshRes">Segfaults caused by PerlFreshRestart</A>
</UL>
<!-- INDEX END -->
-
-
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -44,7 +45,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
<P>
@@ -59,15 +62,13 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A></H1></CENTER>
<P>
-<A HREF="././obvious.html#my_scoped_variable_in_nested_s">More info</A>
-
+See <A HREF="././obvious.html#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>.
-
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Segfaults_caused_by_PerlFreshRes">Segfaults caused by PerlFreshRestart</A></H1></CENTER>
<P>
-<A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>
+See <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>
@@ -80,7 +81,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="config.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="porting.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -92,8 +94,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/02/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
1.4 +558 -532 modperl-site/guide/guide-src.tar.gz
<<Binary file>>
1.5 +1071 -834 modperl-site/guide/guide.tar.gz
<<Binary file>>
1.11 +253 -212 modperl-site/guide/help.html
Index: help.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/help.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- help.html 1999/04/19 19:53:36 1.10
+++ help.html 1999/05/08 17:46:31 1.11
@@ -1,299 +1,340 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: </TITLE>
+ <TITLE>mod_perl guide: Getting Helped and Further Learning</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
-
-<H1 ALIGN=CENTER><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Help. Further Learning</H1>
-
-
-<P>
-<HR WIDTH="100%"></P>
-
-
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
-
-
+<A NAME="toc"></A>
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+Getting Helped and Further Learning</H1>
+<HR WIDTH="100%">
+ [ <A HREF="snippets.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="download.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
-<LI><A HREF="#1">READ ME FIRST</A></LI>
-
-
-<LI><A HREF="#author">This document's Author</A></LI>
-
-
-<LI><A HREF="#2">Get helped with mod_perl</A></LI>
-
-
-<LI><A HREF="#3">Get helped with perl </A></LI>
-
-
-<LI><A HREF="#4">Get helped with perl/CGI</A></LI>
-
-<LI><A HREF="#5">Get helped with apache </A></LI>
-
-
-<LI><A HREF="#6">Get helped with DBI </A></LI>
+ <LI><A HREF="#READ_ME_FIRST">READ ME FIRST</A>
+ <LI><A HREF="#This_document_s_Author">This document's Author</A>
+ <LI><A HREF="#Get_helped_with_mod_perl">Get helped with mod_perl</A>
+ <LI><A HREF="#Get_helped_with_Perl">Get helped with Perl</A>
+ <LI><A HREF="#Get_helped_with_Perl_CGI">Get helped with Perl/CGI</A>
+ <LI><A HREF="#Get_helped_with_Apache">Get helped with Apache </A>
+ <LI><A HREF="#Get_helped_with_DBI">Get helped with DBI</A>
</UL>
-
+<!-- INDEX END -->
-<P>
-<HR WIDTH="100%"></P>
-
+<HR>
-<H3><A NAME="1"></A>READ ME FIRST</H3>
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+ <HR>
-<P>If after reading this guide and other documents listed in this section,
-you feel that your question is yet not answered, please ask the apache/mod_perl
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<P>
+<CENTER><H1><A NAME="READ_ME_FIRST">READ ME FIRST</A></H1></CENTER>
+<P>
+If after reading this guide and other documents listed in this section, you
+feel that your question is not yet answered, please ask the apache/mod_perl
mailing list to help you. But first try to browse the mailing list archive.
Most of the time you will find the answer for your question by searching
the mailing archive, since there is a big chance someone else already have
encountered the problem and found a solution for it. If you ignore this
-advice, don't be surprised if your question will be left unanswered - it
-bores people to answer the same question more than once. It doesn't mean
-that you should avoid asking questions. Just don't abuse the available
-help and <B>RTFM </B>before you call for <B>HELP</B>. (You have certainly
-heard the infamous fable of the shepherd boy and the wolves)</P>
-
-
-<P>For more information See <A HREF="#2">Get helped with mod_perl</A>.
-
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
-
-
-<H3><A NAME="author"></A>This document's Author</H3>
-
-
-<P>Hi, I wrote this document to help you with mod_perl.
-It doesn't mean that if you have any question regarding
-mod_perl, perl or whatever you think I might know,
-you should directly send it to me. Please see the
-<A HREF="help.html#2">Get helped with mod_perl</A> section and
-follow the guidelines as prescribed there.</P>
+advice, do not be surprised if your question will be left unanswered - it
+bores people to answer the same question more than once. It does not mean
+that you should avoid asking questions. Just do not abuse the available
+help and <STRONG>RTFM</STRONG>
+before you call for <STRONG>HELP</STRONG>. (You have certainly heard the infamous fable of the shepherd boy and the
+wolves)
-
-<P>However, You are welcome to submit any corrections
-<A href="mailto:sbekman@iname.com?subject=mod_perl%20guide%20corrections">
-directly to me</A>. <B>But please no questions, they will
-be immediately deleted.</B></P>
+<P>
+For more information See <A HREF="#Get_helped_with_mod_perl">Get helped with mod_perl</A>.
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="This_document_s_Author">This document's Author</A></H1></CENTER>
+<P>
+Hi, I wrote this document to help you with mod_perl. It does not mean that
+if you have any question regarding mod_perl, perl or whatever you think I
+might know, you should directly send it to me. Please see the
+<A HREF="#Get_helped_with_mod_perl">Get helped with mod_perl</A> section and follow the guidelines as prescribed there.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
+<P>
+However, you are welcome to submit corrections and suggestions directly to
+me at <A
+HREF="mailto:sbekman@iname.com?subject=mod_perl%20guide%20corrections.">sbekman@iname.com?subject=mod_perl%20guide%20corrections.</A>
+ <STRONG>But PLEASE
+NO QUESTIONS, they will be immediately deleted.</STRONG>
-<H3><A NAME="2"></A>Get helped with mod_perl</H3>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Get_helped_with_mod_perl">Get helped with mod_perl</A></H1></CENTER>
+<DL>
+<P><DT><STRONG><A NAME="item_mod_perl">mod_perl home</A></STRONG><DD>
+<P>
+<A HREF="http://perl.apache.org">http://perl.apache.org</A>
-<UL>
-<LI><A HREF="HTTP://perl.apache.org">perl.apache.org </A>- mod_perl home </LI>
+<P><DT><STRONG><A NAME="item_Apache">Apache Modules Book</A></STRONG><DD>
+<P>
+<A HREF="http://www.modperl.com">http://www.modperl.com</A> is the home
+site of The Apache Modules Book, a book about creating Web server modules
+using the Apache API, written by Lincoln Stein and Doug MacEachern.
+<P>
+Now you can purchase the book at your local bookstore or from the online
+dealer. O'Reilly lists this book as:
-<LI><A HREF="HTTP://www.modperl.com">www.modperl.com</A> - This is the home site
-of The Apache Modules Book, a book about creating Web server modules using
-the Apache API, written by Lincoln Stein and Doug MacEachern.
-<P>
-Now you can purchase the book at your local bookstore or from the online dealer.
-O'Reilly lists this book as:
-<PRE>
- Writing Apache Modules with Perl and C
- By Lincoln Stein & Doug MacEachern
+<P>
+<PRE> Writing Apache Modules with Perl and C
+ By Lincoln Stein & Doug MacEachern
1st Edition March 1999
1-56592-567-X, Order Number: 567X
746 pages, $34.95
</PRE>
-
-
-</LI>
-
-
-<LI><A HREF="http://perl.apache.org/dist/cgi_to_mod_perl.html">Quick guide
-</A>for moving from CGI to mod_perl. </LI>
-
-
-<LI>Frank Cringle's <A HREF="http://perl.apache.org/faq/">mod_perl FAQ</A></LI>
-
-
-<LI>Vivek Khera's <A HREF="http://perl.apache.org/tuning/">mod_perl performance
-tuning guide</A></LI>
-
-
-<LI>Doug MacEachern's <A HREF="http://perl.apache.org/src/mod_perl.html">mod_perl
-plugin reference guide</A>. </LI>
-
-
-<LI><A HREF="http://perl.apache.org/dist/mod_perl_traps.html">mod_perl_traps,</A>
-common traps and solutions for mod_perl users. </LI>
-
-
-<LI><A HREF="http://www.refcards.com">mod_perl Quick Reference
- Card</A>
-(Apache and other refcards are available from this link</LI>
-
-
-<LI>mod_perl mailing list</LI>
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl FAQ</A></STRONG>
+<P>
+by Frank Cringle at <A
+HREF="http://perl.apache.org/faq/">http://perl.apache.org/faq/</A> .
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl performance tuning guide</A></STRONG>
+<P>
+by Vivek Khera at <A
+HREF="http://perl.apache.org/tuning/">http://perl.apache.org/tuning/</A> .
-<P>The Apache/Perl mailing list (modperl@apache.org) <B>is available
-for mod_perl users and developers to share ideas, solve problems and
-discuss things related to mod_perl and the Apache::* modules.</B> To
-subscribe to this list, send mail to <a
-href="mailto:majordomo@apache.org">majordomo@apache.org</a> with the
-string "subscribe modperl" in the body. </P>
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl plugin reference guide</A></STRONG>
+<P>
+by Doug MacEachern at <A
+HREF="http://perl.apache.org/src/mod_perl.html">http://perl.apache.org/src/mod_perl.html</A>
+.
+<P><LI><STRONG><A NAME="item_Quick">Quick guide for moving from CGI to mod_perl</A></STRONG>
+<P>
+at <A
+HREF="http://perl.apache.org/dist/cgi_to_mod_perl.html">http://perl.apache.org/dist/cgi_to_mod_perl.html</A>
+.
-<P><B>Searchable </B>mod_perl mailing list <A
-HREF="http://forum.swarthmore.edu/epigone/modperl"><B>archive</B></A> by Ken Williams. </P> </UL>
+<P><LI><STRONG><A NAME="item_mod_perl_traps">mod_perl_traps, common traps and solutions for mod_perl users</A></STRONG>
+<P>
+at <A
+HREF="http://perl.apache.org/dist/mod_perl_traps.html">http://perl.apache.org/dist/mod_perl_traps.html</A>
+.
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl Quick Reference Card</A></STRONG>
+<P>
+<A HREF="http://www.refcards.com">http://www.refcards.com</A> (Apache and
+other refcards are available from this link)
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl mailing list</A></STRONG>
+<P>
+The Apache/Perl mailing list (<A
+HREF="mailto:modperl@apache.org">modperl@apache.org</A>) <STRONG>is available for
+mod_perl users and developers to share ideas, solve problems and
+discuss things related to mod_perl and the Apache::* modules.</STRONG> To subscribe to this list, send mail to <A
+HREF="mailto:majordomo@apache.org">majordomo@apache.org</A> with empty <CODE>Subject</CODE> and with <CODE>Body</CODE>:
+<P>
+<PRE> subscribe modperl
+</PRE>
+<P>
+A <STRONG>searchable</STRONG> mod_perl mailing list archive available at <A
+HREF="http://forum.swarthmore.edu/epigone/modperl.">http://forum.swarthmore.edu/epigone/modperl.</A>
+We owe it to Ken Williams.
-<H3><A NAME="3"></A>Get helped with Perl </H3>
+<P>
+Another arhive: <A
+HREF="http://www.geocrawler.com/lists/3/web/182/0/">http://www.geocrawler.com/lists/3/web/182/0/</A>
+</DL>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Get_helped_with_Perl">Get helped with Perl</A></H1></CENTER>
<UL>
-<LI><A HREF="http://www.perl.com/CPAN/doc/FAQs/FAQ/PerlFAQ.html">The Perl
-FAQ </A></LI>
-
+<P><LI><STRONG><A NAME="item_The">The Perl FAQ</A></STRONG>
+<P>
+<A
+HREF="http://www.perl.com/CPAN/doc/FAQs/FAQ/PerlFAQ.html">http://www.perl.com/CPAN/doc/FAQs/FAQ/PerlFAQ.html</A>
-<LI><A HREF="http://www.perl.com/">www.perl.com</A></LI>
+<P><LI><STRONG><A NAME="item_perl">perl home</A></STRONG>
+<P>
+<A HREF="http://www.perl.com/">http://www.perl.com/</A>
-<LI><A HREF="http://www.tpj.com/">The Perl Journal </A></LI>
+<P><LI><STRONG><A NAME="item_The">The Perl Journal</A></STRONG>
+<P>
+<A HREF="http://www.tpj.com/">http://www.tpj.com/</A>
+<P><LI><STRONG><A NAME="item_Perl">Perl Module Mechanics</A></STRONG>
+<P>
+<A
+HREF="http://world.std.com/~swmcd/steven/perl/module_mechanics.html">http://world.std.com/~swmcd/steven/perl/module_mechanics.html</A>
+- This page describes the mechanics of creating, compiling, releasing and
+maintaining Perl modules.
-<LI><A HREF="http://world.std.com/~swmcd/steven/perl/module_mechanics.html">Perl
-Module Mechanics </A>- This page describes the mechanics of creating, compiling,
-releasing and maintaining Perl modules. </LI>
</UL>
-
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
-
-
-<H3><A NAME="4"></A>Get helped with Perl/CGI</H3>
-
-
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Get_helped_with_Perl_CGI">Get helped with Perl/CGI</A></H1></CENTER>
<UL>
-<LI><A HREF="http://www.perl.com/CPAN/doc/FAQs/cgi/perl-cgi-faq.html">Perl/CGI
-FAQ </A></LI>
-
-
-<LI><A
-HREF="http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html">Answers
-to some bothering Perl and Perl/CGI questions</A></LI>
-
-
-<LI><A HREF="http://www.perl.com/CPAN/doc/FAQs/cgi/idiots-guide.html">Idiot's
-Guide to CGI programming </A></LI>
-
+<P><LI><STRONG><A NAME="item_Perl">Perl/CGI FAQ</A></STRONG>
+<P>
+at <A
+HREF="http://www.perl.com/CPAN/doc/FAQs/cgi/perl-cgi-faq.html">http://www.perl.com/CPAN/doc/FAQs/cgi/perl-cgi-faq.html</A>
-<LI><A HREF="http://www.w3.org/Security/Faq/www-security-faq.html">WWW
-Security FAQ </A></LI>
+<P><LI><STRONG><A NAME="item_Answers">Answers to some bothering Perl and Perl/CGI questions</A></STRONG>
+<P>
+<A
+HREF="http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html">http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html</A>
-<LI><A HREF="http://www.gunther.web66.com/FAQS/taintmode.html">CGI/Perl
-Taint Mode FAQ</A> (by Gunther Birznieks)</LI>
-</UL>
+<P><LI><STRONG><A NAME="item_Idiot">Idiot's Guide to CGI programming</A></STRONG>
+<P>
+<A
+HREF="http://www.perl.com/CPAN/doc/FAQs/cgi/idiots-guide.html">http://www.perl.com/CPAN/doc/FAQs/cgi/idiots-guide.html</A>
-<H3><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></H3>
+<P><LI><STRONG><A NAME="item_WWW">WWW Security FAQ</A></STRONG>
+<P>
+<A
+HREF="http://www.w3.org/Security/Faq/www-security-faq.html">http://www.w3.org/Security/Faq/www-security-faq.html</A>
-<H3><A NAME="5"></A>Get helped with Apache </H3>
+<P><LI><STRONG><A NAME="item_CGI">CGI/Perl Taint Mode FAQ</A></STRONG>
+<P>
+<A
+HREF="http://www.gunther.web66.com/FAQS/taintmode.html">http://www.gunther.web66.com/FAQS/taintmode.html</A>
+(by Gunther Birznieks)
+</UL>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Get_helped_with_Apache">Get helped with Apache</A></H1></CENTER>
<UL>
-<LI><A HREF="http://www.apache.org">Apache Project's Home</A></LI>
-
-
-<LI><A HREF="http://www.ford-mason.co.uk/resources/refcards/apache.html">Apache
-Quick Reference Card</A></LI>
-
+<P><LI><STRONG><A NAME="item_Apache">Apache Project's Home</A></STRONG>
+<P>
+<A HREF="http://www.apache.org">http://www.apache.org</A>
-<LI><A HREF="http://www.apache.org/docs/misc/FAQ.html">The Apache FAQ</A></LI>
+<P><LI><STRONG><A NAME="item_Apache">Apache Quick Reference Card</A></STRONG>
+<P>
+<A HREF="http://www.refcards.com">http://www.refcards.com</A> (Apache and
+other refcards are available from this link)
+<P><LI><STRONG><A NAME="item_The">The Apache FAQ</A></STRONG>
+<P>
+<A
+HREF="http://www.apache.org/docs/misc/FAQ.html">http://www.apache.org/docs/misc/FAQ.html</A>
-<LI><A HREF="http://www.apache.org/docs/">Apache Server Documentation</A></LI>
+<P><LI><STRONG><A NAME="item_Apache">Apache Server Documentation</A></STRONG>
+<P>
+<A HREF="http://www.apache.org/docs/">http://www.apache.org/docs/</A>
-<LI><A HREF="http://www.apache.org/docs/handler.html">Apache Handlers</A></LI>
+<P><LI><STRONG><A NAME="item_Apache">Apache Handlers</A></STRONG>
+<P>
+<A
+HREF="http://www.apache.org/docs/handler.html">http://www.apache.org/docs/handler.html</A>
</UL>
-
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
-
-
-<H3><A NAME="6"></A>Get helped with DBI </H3>
-
-
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Get_helped_with_DBI">Get helped with DBI</A></H1></CENTER>
<UL>
-
-
-<LI><A HREF="http://eskimo.tamu.edu/~jbaker/dbi-examples.html">Perl DBI examples</A>
-by Jeffrey William Baker.</LI>
-
-<LI><a href="http://www.hermetica.com/technologia/DBI/">DBI at Hermetica</a>
-
-
-<LI><a href="http://www.fugue.com/dbi/">DBI mailing list information</a>
+<P><LI><STRONG><A NAME="item_Perl">Perl DBI examples</A></STRONG>
+<P>
+<A
+HREF="http://eskimo.tamu.edu/~jbaker/dbi-examples.html">http://eskimo.tamu.edu/~jbaker/dbi-examples.html</A>
+(by Jeffrey William Baker).
+<P><LI><STRONG><A NAME="item_DBI">DBI at Hermetica</A></STRONG>
+<P>
+<A
+HREF="http://www.hermetica.com/technologia/DBI/">http://www.hermetica.com/technologia/DBI/</A>
-<LI><a href="http://outside.organic.com/mail-archives/dbi-users/">DBI mailing list archives</a>
-
-<LI><a href="http://perl.apache.org/src/mod_perl.html#PERSISTENT_DATABASE_CONNECTIONS">Persistent connections with mod_perl</a>
+<P><LI><STRONG><A NAME="item_DBI">DBI mailing list information</A></STRONG>
+<P>
+<A HREF="http://www.fugue.com/dbi/">http://www.fugue.com/dbi/</A>
-</UL>
+<P><LI><STRONG><A NAME="item_DBI">DBI mailing list archives</A></STRONG>
+<P>
+<A
+HREF="http://outside.organic.com/mail-archives/dbi-users/">http://outside.organic.com/mail-archives/dbi-users/</A>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
+<P><LI><STRONG><A NAME="item_Persistent">Persistent connections with mod_perl</A></STRONG>
+<P>
+<A
+HREF="http://perl.apache.org/src/mod_perl.html#PERSISTENT_DATABASE_CONNECTIONS">http://perl.apache.org/src/mod_perl.html#PERSISTENT_DATABASE_CONNECTIONS</A>
-<P><A HREF="index.html">[Back to the main page]</A></P>
+</UL>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+ <HR>
+ [ <A HREF="snippets.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="download.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
-<TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
-<HR></TD>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
</TR>
-
-
<TR ALIGN=CENTER VALIGN=TOP>
-<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A HREF="help.html#author">Stas
-Bekman</A>.<BR>
-Last Modified at 04/17/1998 </FONT></B></TD>
-
-
-<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" BORDER=0 ALT="Mod Perl Icon" HEIGHT=59 WIDTH=150></A>
-</TD>
-
-
-<TD><FONT SIZE=-2>Use of the Camel for Perl is <BR>
-a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
-and is used by permission. </FONT> </TD>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 04/30/1999
+ </FONT>
+ </B>
+ </TD>
+
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
+
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
</TR>
</TABLE></CENTER>
-
</BODY>
</HTML>
+
\ No newline at end of file
1.14 +405 -46 modperl-site/guide/index.html
Index: index.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/index.html,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- index.html 1999/04/19 19:53:37 1.13
+++ index.html 1999/05/08 17:46:31 1.14
@@ -1,106 +1,471 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>Mod Perl Developer's Guide</TITLE>
- <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
- <META NAME="Author" CONTENT="Bekman Stas">
+ <TITLE>mod_perl Guide</TITLE>
+ <META NAME="Author" CONTENT="Stas Bekman">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl cgi apache webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
+ <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
+ <META NAME="Classification" CONTENT="information">
</HEAD>
-<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
-<H1 ALIGN=CENTER>Mod Perl Developer's Guide</H1>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
+<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
+<H1 ALIGN=CENTER>mod_perl Guide</H1>
<CENTER><P><B>Deploying mod_perl technology to give a rocket speed
-to your perl cgi-bin scripts.</B></P></CENTER>
-
+to your CGI/perl scripts.</B></P></CENTER>
-<CENTER><P><B>Version 1.09 (+1/2) Apr, 19 1999</B></P></CENTER>
+<CENTER><P><B>Version 1.10
+ May, 8 1999</B></P></CENTER>
<P>
<HR WIDTH="100%"></P>
+<H3>Table of Contents:</H3>
-<H3><FONT SIZE=-1>Table of Contents:</FONT></H3>
-
+<UL>
+<LI><A HREF="intro.html"><B><FONT SIZE=+1>Introduction. Incentives. Credits.</FONT></B></A></LI><P>
<UL>
-<LI><A HREF="intro.html">Introduction. Incentives. Credits.</A></LI>
+ <LI><A HREF="intro.html#What_is_mod_perl">What is mod_perl</A>
+ <LI><A HREF="intro.html#What_is_covered_in_this_document">What is covered in this document</A>
+ <LI><A HREF="intro.html#References_and_Acknowledgments">References and Acknowledgments</A>
+</UL>
+<P><LI><A HREF="start.html"><B><FONT SIZE=+1>Guide's Overview</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="start.html">Getting Started with mod_perl. Overview.</A></LI>
+ <LI><A HREF="start.html#What_s_inside_">What's inside?</A>
+</UL>
+<P><LI><A HREF="strategy.html"><B><FONT SIZE=+1>Picking the Right Strategy</FONT></B></A></LI><P>
+<UL>
+ <LI><A HREF="strategy.html#Do_it_like_me_">Do it like me?!</A>
+ <LI><A HREF="strategy.html#mod_perl_Deploying_Schemas_Overv">mod_perl Deploying Schemas Overview</A>
+ <LI><A HREF="strategy.html#Stand_alone_mod_perl_Enabled_Apa">Stand alone mod_perl Enabled Apache Server</A>
+ <LI><A HREF="strategy.html#One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl enabled Apache Servers</A>
+ <LI><A HREF="strategy.html#One_light_non_Apache_and_One_mod">One light non-Apache and One mod_perl enabled Apache Servers</A>
+ <LI><A HREF="strategy.html#Adding_a_Proxy_Server_in_http_Ac">Adding a Proxy Server in http Accelerator Mode</A>
+ <LI><A HREF="strategy.html#squid_server">squid server</A>
+ <LI><A HREF="strategy.html#apache_s_mod_proxy">apache's mod_proxy</A>
+</UL>
+<P><LI><A HREF="scenario.html"><B><FONT SIZE=+1>Real World Scenarios of Implementing Various Strategies</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="scenario.html">Server Installation. Real World scenarios</A></LI>
+ <LI><A HREF="scenario.html#Before_you_dive_into_the_gory_de">Before you dive into the gory details</A>
+ <LI><A HREF="scenario.html#One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl enabled Apache Servers</A>
+ <UL>
+
+ <LI><A HREF="scenario.html#Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A>
+ <UL>
+
+ <LI><A HREF="scenario.html#Building_the_httpd_docs_Server">Building the httpd_docs Server</A>
+ <LI><A HREF="scenario.html#Building_the_httpd_perl_Server_">Building the httpd_perl Server (mod_perl):</A>
+ </UL>
+
+ <LI><A HREF="scenario.html#Configuration_of_the_servers">Configuration of the servers</A>
+ <UL>
+
+ <LI><A HREF="scenario.html#Basic_httpd_docs_Server_s_Config">Basic httpd_docs Server's Configuration</A>
+ <LI><A HREF="scenario.html#Basic_httpd_perl_Server_s_Config">Basic httpd_perl Server's Configuration</A>
+ </UL>
+
+ </UL>
+
+ <LI><A HREF="scenario.html#Running_2_webservers_and_squid_i">Running 2 webservers and squid in httpd accelerator mode</A>
+ <LI><A HREF="scenario.html#Running_1_webserver_and_squid_in">Running 1 webserver and squid in httpd accelerator mode</A>
+ <LI><A HREF="scenario.html#Using_mod_proxy">Using mod_proxy</A>
+ <LI><A HREF="scenario.html#mod_perl_server_as_DSO">mod_perl server as DSO</A>
+</UL>
+<P><LI><A HREF="install.html"><B><FONT SIZE=+1>Installation Notes</FONT></B></A></LI><P>
+<UL>
+ <LI><A HREF="install.html#Configuration_and_Installation">Configuration and Installation</A>
+ <UL>
-<LI><A HREF="config.html">Server Configuration</A>.</LI>
+ <LI><A HREF="install.html#Perl">Perl</A>
+ <LI><A HREF="install.html#Apache">Apache</A>
+ <LI><A HREF="install.html#Mod_Perl">Mod_Perl</A>
+ </UL>
+
+ <LI><A HREF="install.html#How_can_I_tell_whether_mod_perl_">How can I tell whether mod_perl is really installed</A>
+ <UL>
+
+ <LI><A HREF="install.html#Testing_by_checking_the_error_lo">Testing by checking the error_log file</A>
+ <LI><A HREF="install.html#Testing_by_viewing_perl_status">Testing by viewing /perl-status</A>
+ <LI><A HREF="install.html#Testing_via_telnet">Testing via telnet</A>
+ <LI><A HREF="install.html#Testing_via_a_CGI_script">Testing via a CGI script</A>
+ <LI><A HREF="install.html#Testing_via_lwp_request">Testing via lwp-request</A>
+ </UL>
+
+ <LI><A HREF="install.html#Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A>
+ <LI><A HREF="install.html#Is_it_possible_to_determine_whic">Is it possible to determine which options were given to modperl's Makefile.PL</A>
+ <LI><A HREF="install.html#Server_Installation">Server Installation</A>
+ <UL>
+ <LI><A HREF="install.html#make_test_fails">make test fails</A>
+ </UL>
-<LI><A HREF="control.html">Server Controlling and Monitoring</A></LI>
+</UL>
+<P><LI><A HREF="config.html"><B><FONT SIZE=+1>Server Configuration</FONT></B></A></LI><P>
+<UL>
+ <LI><A HREF="config.html#mod_perl_Specific_Configuration">mod_perl Specific Configuration</A>
+ <UL>
-<LI><A HREF="frequent.html">Frequent mod_perl problems</A></LI>
+ <LI><A HREF="config.html#Alias_Configurations">Alias Configurations</A>
+ <LI><A HREF="config.html#Location_Configuration">Location Configuration</A>
+ <LI><A HREF="config.html#PerlFreshRestart">PerlFreshRestart</A>
+ <LI><A HREF="config.html#_perl_status_location">/perl-status location</A>
+ <LI><A HREF="config.html#perl_startup_file">perl-startup file</A>
+ <UL>
+
+ <LI><A HREF="config.html#Sample_perl_startup_file">Sample perl-startup file</A>
+ <LI><A HREF="config.html#What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A>
+ <LI><A HREF="config.html#Is_it_possible_to_preopen_a_DB_c">Is it possible to preopen a DB connection at the server startup?</A>
+ </UL>
+
+ </UL>
+
+ <LI><A HREF="config.html#Perl_behavior_controls">Perl behavior controls</A>
+ <LI><A HREF="config.html#Tuning_MinSpareServers_MaxSpareS">Tuning MinSpareServers MaxSpareServers StartServers MaxClients</A>
+ <LI><A HREF="config.html#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>
+ <LI><A HREF="config.html#Perl_Sections">Perl Sections</A>
+ <LI><A HREF="config.html#Configuring_Apache_mod_perl_wi">Configuring Apache + mod_perl with mod_macro</A>
+ <LI><A HREF="config.html#General_pitfalls">General pitfalls</A>
+ <UL>
+
+ <LI><A HREF="config.html#My_cgi_perl_code_is_being_return">My cgi/perl code is being returned as a plain text instead of being executed by the webserver?</A>
+ <LI><A HREF="config.html#My_script_works_under_cgi_bin_b">My script works under cgi-bin, but when called via mod_perl I see A 'Save-As' prompt</A>
+ <LI><A HREF="config.html#Is_there_a_way_to_provide_a_diff">Is there a way to provide a different startup.pl file for each individual virtual host</A>
+ <LI><A HREF="config.html#Is_there_a_way_to_modify_INC_on">Is there a way to modify @INC on a per-virtual-host basis. </A>
+ <LI><A HREF="config.html#Sometimes_the_script_from_one_vi">Sometimes the script from one virtual host calls a script with</A>
+ <LI><A HREF="config.html#the_server_no_longer_retrieves_t">the server no longer retrieves the DirectoryIndex files for a directory</A>
+ </UL>
+</UL>
+<P><LI><A HREF="frequent.html"><B><FONT SIZE=+1>Frequent mod_perl problems</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="porting.html">CGI to mod_perl Porting. mod_perl Coding guidelines.</A></LI>
+ <LI><A HREF="frequent.html#Coverage">Coverage</A>
+ <LI><A HREF="frequent.html#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>
+ <LI><A HREF="frequent.html#Segfaults_caused_by_PerlFreshRes">Segfaults caused by PerlFreshRestart</A>
+</UL>
+<P><LI><A HREF="porting.html"><B><FONT SIZE=+1>CGI to mod_perl Porting. mod_perl Coding guidelines.</FONT></B></A></LI><P>
+<UL>
+ <LI><A HREF="porting.html#Document_Coverage">Document Coverage</A>
+ <LI><A HREF="porting.html#Before_you_start_to_code">Before you start to code</A>
+ <LI><A HREF="porting.html#Coding_with_mod_perl">Coding with mod_perl</A>
+ <UL>
+
+ <LI><A HREF="porting.html#What_s_different_about_modperl">What's different about modperl</A>
+ <UL>
+
+ <LI><A HREF="porting.html#Script_s_name_space">Script's name space</A>
+ <LI><A HREF="porting.html#Name_collisions_with_Modules_and">Name collisions with Modules and libs</A>
+ <LI><A HREF="porting.html#_END_or_DATA_tokens">__END__ or __DATA__ tokens</A>
+ <LI><A HREF="porting.html#Output_from_system_calls">Output from system calls</A>
+ <LI><A HREF="porting.html#Using_format_">Using format()</A>
+ <LI><A HREF="porting.html#Using_exit_">Using exit()</A>
+ <LI><A HREF="porting.html#Running_from_shell">Running from shell</A>
+ <LI><A HREF="porting.html#I_O_is_different">I/O is different</A>
+ <LI><A HREF="porting.html#HTTP_MIME_Headers_PerlSendHea">HTTP + MIME Headers (PerlSendHeader)</A>
+ <LI><A HREF="porting.html#NPH_Non_Parsed_Headers_scripts">NPH (Non Parsed Headers) scripts</A>
+ <LI><A HREF="porting.html#BEGIN_blocks">BEGIN blocks </A>
+ <LI><A HREF="porting.html#END_blocks">END blocks </A>
+ <LI><A HREF="porting.html#Switches_w_T">Switches -w, -T</A>
+ </UL>
+
+ <LI><A HREF="porting.html#strict_pragma">strict pragma</A>
+ <LI><A HREF="porting.html#Turning_warnings_ON">Turning warnings ON</A>
+ <LI><A HREF="porting.html#diagnostics_pragma">diagnostics pragma</A>
+ <LI><A HREF="porting.html#Global_Variables">Global Variables</A>
+ <LI><A HREF="porting.html#Code_has_been_changed_but_it_se">Code has been changed, but it seems the script is running the old code</A>
+ <LI><A HREF="porting.html#Memory_leakage">Memory leakage</A>
+ </UL>
+
+ <LI><A HREF="porting.html#Filehandlers_and_locks_leakages">Filehandlers and locks leakages</A>
+ <UL>
+
+ <LI><A HREF="porting.html#Sometimes_it_Works_Sometimes_Not">Sometimes it Works Sometimes Not (Very important!)</A>
+ <LI><A HREF="porting.html#The_Script_is_too_dirty_It_does">The Script is too dirty, It does the job and I can't afford rewriting it.</A>
+ <LI><A HREF="porting.html#Apache_PerlRun_a_closer_look">Apache::PerlRun - a closer look</A>
+ </UL>
+
+ <LI><A HREF="porting.html#Redirecting_Errors_to_Client_ins">Redirecting Errors to Client instead of error_log</A>
+ <LI><A HREF="porting.html#Finding_the_line_number_the_erro">Finding the line number the error/warning has been triggered at</A>
+ <LI><A HREF="porting.html#Forking_subprocesses_from_mod_pe">Forking subprocesses from mod_perl</A>
+</UL>
+<P><LI><A HREF="performance.html"><B><FONT SIZE=+1>Performance. Benchmarks.</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="obvious.html">What is obvious for others but not for you</A>.</LI>
+ <LI><A HREF="performance.html#Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A>
+ <UL>
+ <LI><A HREF="performance.html#Preload_Perl_modules_Real_Numb">Preload Perl modules - Real Numbers</A>
+ </UL>
-<LI><A HREF="warnings.html">Warnings and Errors: Where and Why.</A>? </LI>
+ <LI><A HREF="performance.html#Preopen_DB_connection_at_server_">Preopen DB connection at server startup</A>
+ <LI><A HREF="performance.html#Memory_sharing">Memory sharing</A>
+ <LI><A HREF="performance.html#Preload_Registry_Scripts">Preload Registry Scripts</A>
+ <LI><A HREF="performance.html#Avoid_Importing_Functions">Avoid Importing Functions</A>
+ <LI><A HREF="performance.html#Reducing_the_Memory_Usage">Reducing the Memory Usage</A>
+ <LI><A HREF="performance.html#how_can_I_find_if_my_modperl_scr">how can I find if my modperl scripts have memory leaks (and where)</A>
+ <LI><A HREF="performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>
+ <LI><A HREF="performance.html#Limiting_the_resources_used_by_h">Limiting the resources used by httpd children</A>
+ <LI><A HREF="performance.html#Limiting_the_request_rate_speed_">Limiting the request rate speed (robots blocking)</A>
+ <LI><A HREF="performance.html#Benchmarks_Impressing_your_Boss">Benchmarks. Impressing your Boss and Colleagues.</A>
+ <UL>
+
+ <LI><A HREF="performance.html#Developers_Talk">Developers Talk</A>
+ <LI><A HREF="performance.html#Benchmarking_a_Graphic_hits_coun">Benchmarking a Graphic hits counter with Persistent DB Connection</A>
+ <LI><A HREF="performance.html#Benchmarking_scripts_with_execut">Benchmarking scripts with execution times below 1 second :)</A>
+ <LI><A HREF="performance.html#PerlHandler_s_Benchmarking">PerlHandler's Benchmarking</A>
+ </UL>
+
+ <LI><A HREF="performance.html#Tuning_the_Apache_s_configuratio">Tuning the Apache's configuration variables for the best performance</A>
+ <UL>
+
+ <LI><A HREF="performance.html#Tuning_with_ab_ApacheBench">Tuning with ab - ApacheBench </A>
+ <LI><A HREF="performance.html#Tuning_with_crashme_script">Tuning with crashme script</A>
+ <LI><A HREF="performance.html#Choosing_MaxClients">Choosing MaxClients</A>
+ <LI><A HREF="performance.html#Choosing_MaxRequestsPerChild">Choosing MaxRequestsPerChild</A>
+ <LI><A HREF="performance.html#Choosing_MinSpareServers_MaxSpa">Choosing MinSpareServers, MaxSpareServers and StartServers</A>
+ <LI><A HREF="performance.html#Summary_of_Benchmarking_to_tune_">Summary of Benchmarking to tune all 5 parameters</A>
+ </UL>
+
+ <LI><A HREF="performance.html#Persistent_DB_Connections">Persistent DB Connections</A>
+ <LI><A HREF="performance.html#Using_1_under_mod_perl_and_be">Using $|=1 under mod_perl and better print() techniques.</A>
+ <LI><A HREF="performance.html#Profiling">Profiling</A>
+ <LI><A HREF="performance.html#CGI_pm_s_object_methods_calls_vs">CGI.pm's object methods calls vs. function calls</A>
+</UL>
+<P><LI><A HREF="obvious.html"><B><FONT SIZE=+1>Things obvious to others, but not to you</FONT></B></A></LI><P>
+<UL>
+ <LI><A HREF="obvious.html#Coverage">Coverage</A>
+ <LI><A HREF="obvious.html#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>
+ <UL>
+
+ <LI><A HREF="obvious.html#The_poison">The poison</A>
+ <LI><A HREF="obvious.html#The_diagnosis">The diagnosis</A>
+ <LI><A HREF="obvious.html#The_remedy">The remedy</A>
+ </UL>
+
+ <LI><A HREF="obvious.html#Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A>
+ <UL>
+
+ <LI><A HREF="obvious.html#Restarting_the_server">Restarting the server</A>
+ <LI><A HREF="obvious.html#Using_Apache_StatINC">Using Apache::StatINC</A>
+ <LI><A HREF="obvious.html#Reloading_only_specific_files">Reloading only specific files</A>
+ </UL>
+
+ <LI><A HREF="obvious.html#Compiled_Regular_Expressions">Compiled Regular Expressions </A>
+ <LI><A HREF="obvious.html#Debugging_your_code_in_Single_Se">Debugging your code in Single Server Mode</A>
+ <LI><A HREF="obvious.html#_M_and_other_time_file_tests_u">-M and other time() file tests under mod_perl</A>
+ <LI><A HREF="obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>
+ <LI><A HREF="obvious.html#Handling_the_server_timeout_case">Handling the server timeout cases</A>
+ <LI><A HREF="obvious.html#Where_do_the_warnings_errors_go_">Where do the warnings/errors go?</A>
+ <LI><A HREF="obvious.html#Setting_environment_variables_fo">Setting environment variables for scripts called from CGI.</A>
+</UL>
+<P><LI><A HREF="warnings.html"><B><FONT SIZE=+1>Warnings and Errors: Where and Why.</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="performance.html">Performance. Benchmarks.</A> </LI>
+ <LI><A HREF="warnings.html#General_Advice">General Advice </A>
+ <LI><A HREF="warnings.html#Incorrect_line_number_reporting_">Incorrect line number reporting in error/warn log messages</A>
+ <LI><A HREF="warnings.html#Value_of_x_will_not_stay_shared">Value of $x will not stay shared at - line 5</A>
+ <LI><A HREF="warnings.html#Value_of_x_may_be_unavailable_a">Value of $x may be unavailable at - line 5.</A>
+ <LI><A HREF="warnings.html#mod_perl_rwrite_returned_1">mod_perl: rwrite returned -1</A>
+ <LI><A HREF="warnings.html#caught_SIGPIPE_in_process">caught SIGPIPE in process</A>
+ <LI><A HREF="warnings.html#Client_hit_STOP_or_Netscape_bit_">Client hit STOP or Netscape bit it!</A>
+ <LI><A HREF="warnings.html#Constant_subroutine_redefine">Constant subroutine ... redefined</A>
+ <LI><A HREF="warnings.html#Global_symbol_foo_requires_ex">Global symbol "$foo" requires explicit package name</A>
+ <LI><A HREF="warnings.html#Can_t_undef_active_subroutine">Can't undef active subroutine</A>
+ <LI><A HREF="warnings.html#Use_of_uninitialized_value_at_e">Use of uninitialized value at (eval 80) line 12.</A>
+ <LI><A HREF="warnings.html#Undefined_subroutine_Apache_RO">Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function called at</A>
+ <LI><A HREF="warnings.html#Can_t_load_auto_DBI_DBI_so_">Can't load '.../auto/DBI/DBI.so' for module DBI</A>
+ <LI><A HREF="warnings.html#Callback_called_exit">Callback called exit</A>
+ <LI><A HREF="warnings.html#Out_of_memory_">Out of memory!</A>
+ <LI><A HREF="warnings.html#_warn_child_process_30388_did_n">[warn] child process 30388 did not exit, sending another SIGHUP</A>
+ <LI><A HREF="warnings.html#RegistryLoader_Cannot_translate">RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl</A>
+ <LI><A HREF="warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>
+ <LI><A HREF="warnings.html#server_reached_MaxClients_settin">server reached MaxClients setting, consider raising the MaxClients setting</A>
+</UL>
+<P><LI><A HREF="databases.html"><B><FONT SIZE=+1>mod_perl and Relational Databases</FONT></B></A></LI><P>
+<UL>
+ <LI><A HREF="databases.html#Why_Relational_SQL_Databases">Why Relational (SQL) Databases</A>
+ <LI><A HREF="databases.html#Apache_DBI_Initiate_a_persist">Apache::DBI - Initiate a persistent database connection</A>
+ <UL>
+
+ <LI><A HREF="databases.html#Introduction">Introduction</A>
+ <LI><A HREF="databases.html#Configuration">Configuration</A>
+ <LI><A HREF="databases.html#Preopening_DBI_connections">Preopening DBI connections</A>
+ <LI><A HREF="databases.html#Debugging_Apache_DBI">Debugging Apache::DBI</A>
+ <LI><A HREF="databases.html#Problems_and_solutions">Problems and solutions</A>
+ <UL>
+
+ <LI><A HREF="databases.html#The_morning_bug">The morning bug</A>
+ <LI><A HREF="databases.html#Cannot_find_the_DBI_handler">Cannot find the DBI handler</A>
+ <LI><A HREF="databases.html#Apache_DBI_does_not_work">Apache:DBI does not work</A>
+ </UL>
+
+ <LI><A HREF="databases.html#Some_useful_code_snippets_to_be_">Some useful code snippets to be used with relational Databases</A>
+ <UL>
+
+ <LI><A HREF="databases.html#Turning_the_SQL_queries_writing_">Turning the SQL queries writing into an short and simple task</A>
+ <LI><A HREF="databases.html#My_DB_module">My::DB module</A>
+ <LI><A HREF="databases.html#My_DB_Module_s_Usage_Examples">My::DB Module's Usage Examples</A>
+ </UL>
-<LI><A HREF="status.html">mod_perl Status. Peeking into the Server's Perl Innards</A></LI>
+ </UL>
+</UL>
+<P><LI><A HREF="dbm.html"><B><FONT SIZE=+1>mod_perl and dbm files</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="debug.html">Debugging mod_perl</A></LI>
+ <LI><A HREF="dbm.html#Where_and_Why_to_use_dbm_files">Where and Why to use dbm files</A>
+ <LI><A HREF="dbm.html#mod_perl_and_dbm">mod_perl and dbm</A>
+ <LI><A HREF="dbm.html#Locking_dbm_handlers">Locking dbm handlers</A>
+ <LI><A HREF="dbm.html#Tie_DB_Lock">Tie::DB_Lock</A>
+ <LI><A HREF="dbm.html#Code_snippets">Code snippets</A>
+</UL>
+<P><LI><A HREF="multiuser.html"><B><FONT SIZE=+1>mod_perl for ISPs. mod_perl and Virtual Hosts.</FONT></B></A></LI><P>
+<UL>
+ <LI><A HREF="multiuser.html#ISPs_providing_mod_perl_services">ISPs providing mod_perl services - a fantasy or reality.</A>
+ <LI><A HREF="multiuser.html#Virtual_Hosts_in_the_guide">Virtual Hosts in the guide</A>
+</UL>
+<P><LI><A HREF="control.html"><B><FONT SIZE=+1>Controlling and Monitoring the Server</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="modules.html">Apache::* modules</A></LI>
+ <LI><A HREF="control.html#Restarting_techniques">Restarting techniques</A>
+ <LI><A HREF="control.html#Implications_of_sending_TERM_HU">Implications of sending TERM, HUP, and USR1 to the server</A>
+ <LI><A HREF="control.html#Using_apachectl_to_control_the_s">Using apachectl to control the server</A>
+ <LI><A HREF="control.html#SUID_start_up_scripts">SUID start-up scripts</A>
+ <LI><A HREF="control.html#Monitoring_the_Server_A_watchdo">Monitoring the Server. A watchdog.</A>
+ <LI><A HREF="control.html#Running_server_in_a_single_mode">Running server in a single mode</A>
+ <LI><A HREF="control.html#Starting_a_personal_server_for_e">Starting a personal server for each developer</A>
+ <LI><A HREF="control.html#Wrapper_to_emulate_the_server_en">Wrapper to emulate the server environment</A>
+ <LI><A HREF="control.html#Log_Rotation">Log Rotation</A>
+ <LI><A HREF="control.html#Preventing_from_modperl_process_">Preventing from modperl process to eat up all the disk's space, when it goes wild.</A>
+</UL>
+<P><LI><A HREF="status.html"><B><FONT SIZE=+1>mod_perl Status. Peeking into the Server's Perl Innards</FONT></B></A></LI><P>
+<UL>
+ <LI><A HREF="status.html#Watching_the_server">Watching the server</A>
+ <UL>
-<LI><A HREF="multiuser.html">mod_perl for ISPs. mod_perl and Virtual
-Hosts.</A></LI>
+ <LI><A HREF="status.html#Configuration">Configuration</A>
+ <LI><A HREF="status.html#Usage">Usage</A>
+ <LI><A HREF="status.html#Compiled_Registry_Scripts_sectio">Compiled Registry Scripts section seems to be empty.</A>
+ </UL>
+</UL>
+<P><LI><A HREF="debug.html"><B><FONT SIZE=+1>Debugging mod_perl</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="perl.html">Perl Reference</A></LI>
+ <LI><A HREF="debug.html#Sometimes_script_works_Sometime">Sometimes script works, Sometimes Not</A>
+ <LI><A HREF="debug.html#Apache_DB_Run_the_interactive">Apache::DB - Run the interactive Perl debugger under mod_perl</A>
+ <LI><A HREF="debug.html#Debug_Tracing">Debug Tracing</A>
+ <LI><A HREF="debug.html#Getting_some_decent_debug_info_w">Getting some decent debug info when running under mod_perl</A>
+ <LI><A HREF="debug.html#gdb_says_there_are_no_debugging_">gdb says there are no debugging symbols</A>
+</UL>
+<P><LI><A HREF="browserbugs.html"><B><FONT SIZE=+1>Workarounds for some known bugs in browsers.</FONT></B></A></LI><P>
+<UL>
+ <LI><A HREF="browserbugs.html#Preventing_QUERY_STRING_to_get_c">Preventing QUERY_STRING to get corrupted with &entity key names.</A>
+ <LI><A HREF="browserbugs.html#IE_4_x_does_not_re_post_data_to_">IE 4.x does not re-post data to a non-port-80 URL</A>
+</UL>
+<P><LI><A HREF="modules.html"><B><FONT SIZE=+1>Apache::* modules</FONT></B></A></LI><P>
+<UL>
-<LI><A HREF="snippets.html">Code Snippets</A></LI>
+ <LI><A HREF="modules.html#Apache_Session_Maintain_sessi">Apache::Session - Maintain session state across HTTP requests</A>
+ <LI><A HREF="modules.html#Apache_DBI_Initiate_a_persist">Apache::DBI - Initiate a persistent database connection</A>
+ <LI><A HREF="modules.html#Apache_Request_libapreq_Gen">Apache::Request (libapreq) - Generic Apache Request Library</A>
+ <LI><A HREF="modules.html#Apache_PerlRun_Run_unaltered_">Apache::PerlRun - Run unaltered CGI scripts under mod_perl</A>
+</UL>
+<P><LI><A HREF="perl.html"><B><FONT SIZE=+1>Perl Reference</FONT></B></A></LI><P>
+<UL>
+ <LI><A HREF="perl.html#Coverage">Coverage</A>
+ <LI><A HREF="perl.html#Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A>
+ <UL>
+
+ <LI><A HREF="perl.html#Making_the_variables_global">Making the variables global</A>
+ <LI><A HREF="perl.html#Making_the_variables_global_with">Making the variables global with strict pragma On</A>
+ <LI><A HREF="perl.html#Using_Exporter_pm_to_share_globa">Using Exporter.pm to share global variables</A>
+ <LI><A HREF="perl.html#Using_aliasing_perl_feature_to_s">Using aliasing perl feature to share global variables</A>
+ </UL>
-<LI><A HREF="help.html">Help. Further Learning.</A></LI>
+</UL>
+<P><LI><A HREF="snippets.html"><B><FONT SIZE=+1>Code Snippets</FONT></B></A></LI><P>
+<UL>
+ <LI><A HREF="snippets.html#Sending_MIME_headers">Sending MIME headers</A>
+ <LI><A HREF="snippets.html#How_to_avoid_printing_the_header">How to avoid printing the header more than once.</A>
+ <LI><A HREF="snippets.html#More_on_relative_paths">More on relative paths</A>
+ <LI><A HREF="snippets.html#Watching_the_error_log_file_with">Watching the error_log file without telneting to the server.</A>
+ <LI><A HREF="snippets.html#Accessing_variables_from_the_cal">Accessing variables from the caller's package</A>
+ <LI><A HREF="snippets.html#Handling_cookies">Handling cookies</A>
+</UL>
+<P><LI><A HREF="help.html"><B><FONT SIZE=+1>Getting Helped and Further Learning</FONT></B></A></LI><P>
+<UL>
-<LI> <HR WIDTH=200 SIZE=5 ALIGN="left">
+ <LI><A HREF="help.html#READ_ME_FIRST">READ ME FIRST</A>
+ <LI><A HREF="help.html#This_document_s_Author">This document's Author</A>
+ <LI><A HREF="help.html#Get_helped_with_mod_perl">Get helped with mod_perl</A>
+ <LI><A HREF="help.html#Get_helped_with_Perl">Get helped with Perl</A>
+ <LI><A HREF="help.html#Get_helped_with_Perl_CGI">Get helped with Perl/CGI</A>
+ <LI><A HREF="help.html#Get_helped_with_Apache">Get helped with Apache </A>
+ <LI><A HREF="help.html#Get_helped_with_DBI">Get helped with DBI</A>
+</UL>
+<P><LI><A HREF="download.html"><B><FONT SIZE=+1>Appendix A: Downloading software and documentation</FONT></B></A></LI><P>
+<UL>
+ <LI><A HREF="download.html#Coverage">Coverage</A>
+ <LI><A HREF="download.html#perl">perl</A>
+ <LI><A HREF="download.html#apache">apache</A>
+ <LI><A HREF="download.html#mod_perl">mod_perl</A>
+ <LI><A HREF="download.html#Squid">Squid</A>
+ <LI><A HREF="download.html#thttpd">thttpd</A>
+ <LI><A HREF="download.html#mod_proxy_add_forward">mod_proxy_add_forward</A>
+</UL>
+<P>
-<LI><A HREF="all.html">Guide All in One. Ready for Printing</A></LI>
+</UL>
+<HR>
-<LI><A HREF="CHANGES">CHANGES</A></LI>
+<UL>
+<LI><A HREF="all.html"><B>Guide All in One. Ready for Printing</B></A></LI>
-<LI><A HREF="#search">Search perl.apache.org along with this guide</A></LI>
+<LI><A HREF="CHANGES"><B>CHANGES</B></A></LI>
+<LI><A HREF="#search"><B>Search perl.apache.org along with this guide</B></A></LI>
-<LI>Download all files <A HREF="guide.tar.gz">guide.tar.gz</A>
+<LI><B>Download all files <A HREF="guide.tar.gz">guide.tar.gz</A>
or sources and build scripts
-<A HREF="guide-src.tar.gz">guide-src.tar.gz</A></LI>
-
+<A HREF="guide-src.tar.gz">guide-src.tar.gz</A></B></LI>
</UL>
-
<HR>
<P>
-
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -126,32 +491,26 @@
</TABLE>
</CENTER>
-
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
<TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
<HR></TD>
</TR>
-
<TR ALIGN=CENTER VALIGN=TOP>
-
<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A
-HREF="help.html#author">Stas Bekman</A>.<BR> Last Modified at
-04/17/1999 </FONT></B></TD>
-
+HREF="help.html#This_document_s_Author">Stas Bekman</A>.<BR> Last Modified at 05/08/1999
+</FONT></B></TD>
<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" BORDER=0 ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
</TD>
-
<TD><FONT SIZE=-2>Use of the Camel for Perl is <BR>
a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
and is used by permission. </FONT> </TD>
</TR>
</TABLE></CENTER>
-
</BODY>
</HTML>
1.9 +259 -235 modperl-site/guide/intro.html
Index: intro.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/intro.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- intro.html 1999/04/17 21:44:43 1.8
+++ intro.html 1999/05/08 17:46:32 1.9
@@ -1,289 +1,313 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl mini-guide: Introduction. Incentives. Credits. </TITLE>
+ <TITLE>mod_perl guide: Introduction. Incentives. Credits.</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
+ <LINK REL=STYLESHEET TYPE="text/css"
+ HREF="style.css" TITLE="refstyle">
+ <style type="text/css">
+ <!--
+ @import url(style.css);
+ -->
+
+ </style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
-
-<H1 ALIGN=CENTER><A HREF="http://perl.apache.org">
-<IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30
- WIDTH=90 ALIGN=LEFT></A>
-<A HREF="http://perl.apache.org">
-<IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30
- WIDTH=90 ALIGN=RIGHT></A>Introduction. Incentives. Credits.</H1>
-
-
-<P>
-<HR WIDTH="100%"></P>
-
-
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
-
-
+<A NAME="toc"></A>
+<H1 ALIGN=CENTER>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
+<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
+Introduction. Incentives. Credits.</H1>
+<HR WIDTH="100%">
+ [ <A HREF="index.html">Main Page</A> | <A HREF="start.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
-<LI><A HREF="#1">What is mod_perl</A></LI>
-
-
-<LI><A HREF="#2">What is covered in this document</A></LI>
-
-<LI><A HREF="#3">Sources and Acknowledgments</LI>
+ <LI><A HREF="#What_is_mod_perl">What is mod_perl</A>
+ <LI><A HREF="#What_is_covered_in_this_document">What is covered in this document</A>
+ <LI><A HREF="#References_and_Acknowledgments">References and Acknowledgments</A>
</UL>
-
-
-<P>
-<HR WIDTH="100%"></P>
-
+<!-- INDEX END -->
-<H3 ALIGN=CENTER><A NAME="1"></A>What is mod_perl</H3>
+<HR>
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
-<P>The Apache/Perl integration project brings together the full power of
-the Perl programming language and the Apache HTTP server. With mod_perl
-it is possible to write Apache modules entirely in Perl. In addition,
-the persistent interpreter embedded in the server avoids the overhead of
-starting an external interpreter, the penalty of Perl start-up time and
-loading and compiling the modules and the scripts. </P>
+ <HR>
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<P>
+<CENTER><H1><A NAME="What_is_mod_perl">What is mod_perl</A></H1></CENTER>
+<P>
+The Apache/Perl integration project brings together the full power of the
+Perl programming language and the Apache HTTP server. With mod_perl it is
+possible to write Apache modules entirely in Perl, this lets you easily do
+things that are more difficult or impossible in regular CGI programs, such
+as running sub requests for example. In addition, the persistent
+interpreter embedded in the server saves the overhead of starting an
+external perl interpreter, the penalty of Perl start-up time. A not least
+important feature is code caching, the modules and scripts are being loaded
+and compiled only once, then for the rest of the server's life the scripts
+are being served from the cache, thus server spends its time only to run
+the already loaded and compiled code, which is very fast.
-<P>The primary advantages of mod_perl are power and speed. You have full
+<P>
+The primary advantages of mod_perl are power and speed. You have full
access to the inner-workings of the web server and can intervene at any
-stage of request-processing. This allows for customized processing of
-(to name just a few of the phases) URI->filename translation,
+stage of request-processing. This allows for customized processing of (to
+name just a few of the phases) URI-&gt;filename translation,
authentication, response generation and logging. There is very little
-run-time overhead. In particular, it is not necessary to start a
-separate process, as is often done with web-server extensions. The most
-wide-spread such extension mechanism, the Common Gateway Interface
-(CGI), can be replaced entirely with perl-code that handles the response
-generation phase of request processing. Mod_perl includes 2 general
-purpose modules for this purpose: Apache::Registry, which can
-transparently run existing perl CGI scripts and Apache::PerlRun, which
-does a similar job but allows you to run "dirtier" (to some extent)
-scripts.</P>
-
-
-<P>Many people wonder and ask "How much of a performance
-improvement does mod_perl give?". Well, it all depends on what
-you're doing with mod_perl and possibly who you ask. People report speed
-boosts from 200% to 2000%. The best way to measure is to try it and
-see for yourself! (see <A
-HREF="http://perl.apache.org/tidbits.html">Tidbit </A>and <A
-HREF="http://perl.apache.org/stories/">Stories </A>pages for the
-facts)</P>
-
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
-
-
-<H3 ALIGN=CENTER><A NAME="2"></A>What is covered in this document</H3>
-
-
-<P>This document was written in an effort to help one to start using
-Apache's mod_perl extension as quickly and easily as possible. It
-includes information about installation and configuration of perl and
-the Apache web server and delves deeply into issues of writing and
-porting existing perl scripts to run under mod_perl. Note that it
-doesn't attempt to enter the big world of using the Perl API or C API.
-You will find the Pointers covering these topics at <A
-HREF="help.html">Help Seek and Learning more</A> section of this
-document.<B> This guide tries to cover the most of the Apache::Registry
-and Apache::PerlRun modules.</B></P>
-
+run-time overhead. In particular, it is not necessary to start a separate
+process, as is often done with web-server extensions. The most wide-spread
+such extension mechanism, the Common Gateway Interface (CGI), can be
+replaced entirely with perl-code that handles the response generation phase
+of request processing. Mod_perl includes 2 general purpose modules for this
+purpose: <CODE>Apache::Registry</CODE>, which can transparently run existing perl CGI scripts and
+<CODE>Apache::PerlRun</CODE>, which does a similar job but allows you to run ``dirtier'' (to some
+extent) scripts.
-<P>It is assumed that you know the basics of building and installing
-perl and Apache (If you don't, just read the INSTALL docs coming with
-distribution of each package). However you will find in the document
-specific perl and Apache related installation and configuration notes,
-which will help you to successfully complete the mod_perl
-installation.</P>
-
-
-<P>If after reading this guide and other documents listed at <A
-HREF="help.html">Help section</A>, you feel that your question is yet
-not answered, please ask the apache/mod_perl mailing list to help you.
-But first try to browse the mailing list archive (located at <A
-HREF="http://forum.swarthmore.edu/epigone/modperl">
-http://forum.swarthmore.edu/epigone/modperl</A>). Often you will find
-the answer to your question by searching the mailing archive, since
-there is a good chance someone else has already encountered the problem
-and found a solution for it. If you ignore this advice, don't be
-surprised if your question goes unanswered - it bores people to answer
-the same question more than once (twice?). This doesn't mean that you
-should avoid asking questions, just don't abuse the available help and
-<B>RTFM</B>before you call for <B>HELP</B>. (You have certainly heard
-the infamous fable of the shepherd boy and the wolves...)</P>
-
-
-<P>If you find incorrect details, my grammar mistakes or you want to
-contribute to this document please feel free to send me an <A
-HREF="mailto:sbekman@iname.com">email</A> at
-<B>sbekman@iname.com</B>.</P>
-
+<P>
+You can configure your httpd server and handlers in Perl (using
+<CODE>PerlSetVar</CODE>, and <CODE>lt</CODE>Perl<CODE>gt</CODE> sections). You can even define your own configuration directives.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
+<P>
+Many people wonder and ask ``How much of a performance improvement does
+mod_perl give?''. Well, it all depends on what you are doing with mod_perl
+and possibly who you ask. Developers report speed boosts from 200% to
+2000%. The best way to measure is to try it and see for yourself! (see <A
+HREF="http://perl.apache.org/tidbits.html">http://perl.apache.org/tidbits.html</A>
+and <A
+HREF="http://perl.apache.org/stories/">http://perl.apache.org/stories/</A>
+for the facts)
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="What_is_covered_in_this_document">What is covered in this document</A></H1></CENTER>
+<P>
+This document was written in an effort to help one to start using Apache's
+mod_perl extension as quickly and easily as possible. It includes
+information about installation and configuration of perl and the Apache web
+server and delves deeply into issues of writing and porting existing perl
+scripts to run under mod_perl. Note that it does not attempt to enter the
+big world of using the Perl API or C API. You will find the pointers
+covering these topics at <A HREF="././help.html#">Getting Helped and Further Learning</A> section of this document. This guide tries to cover the most of the <CODE>Apache::Registry</CODE> and <CODE>Apache::PerlRun</CODE>
+modules. Along with mod_perl related topics, there are many more issues
+related to administrating apache servers, debugging scripts, using
+databases, perl reference, code snippets and more. <A HREF="././start.html#">Guide's Overview</A> will help you to find your way through the guide.
-<H3 ALIGN=CENTER><A NAME="3"></A>Sources and Acknowledgments</H3>
+<P>
+It is assumed that you know at least the basics of building and installing
+perl and Apache (If you do not, just read the INSTALL docs coming with
+distribution of each package). However you will find in the document
+specific perl and Apache related installation and configuration notes,
+which will help you to successfully complete the mod_perl installation and
+get the running server in a short time.
+<P>
+If after reading this guide and other documents listed at <A HREF="././help.html#">Help section</A>, you feel that your question is yet not answered, please ask the
+apache/mod_perl mailing list to help you. But first try to browse the
+mailing list archive (located at <A
+HREF="http://forum.swarthmore.edu/epigone/modperl">http://forum.swarthmore.edu/epigone/modperl</A>
+). Often you will find the answer to your question by searching the mailing
+archive, since there is a good chance someone else has already encountered
+the problem and found a solution for it. If you ignore this advice, do not
+be surprised if your question goes unanswered - it bores people to answer
+the same question more than once (twice?). This does not mean that you
+should avoid asking questions, just do not abuse the available help and <STRONG>RTFM</STRONG>before you call for <STRONG>HELP</STRONG>. (You have certainly heard the infamous fable of the shepherd boy and the
+wolves...)
-<P>This document is based on:</P>
+<P>
+If you find incorrect details, my grammar mistakes or you want to
+contribute to this document please feel free to send me an email at <A
+HREF="mailto:sbekman@iname.com">sbekman@iname.com</A> .
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="References_and_Acknowledgments">References and Acknowledgments</A></H1></CENTER>
+<P>
+I have used the following references while writing this guide:
<UL>
-<LI>Frank Cringle's <A HREF="http://perl.apache.org/faq/">mod_perl FAQ</A></LI>
-
-
-<LI>Vivek Khera's <A HREF="http://perl.apache.org/tuning/">mod_perl performance
-tuning guide</A></LI>
-
-
-<LI>Doug MacEachern's <A HREF="http://perl.apache.org/src/mod_perl.html">mod_perl
-plugin reference guide</A>. </LI>
-
-
-<LI><A HREF="http://perl.apache.org/dist/cgi_to_mod_perl.html">Quick guide
-</A>for moving from CGI to mod_perl. </LI>
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl FAQ</A></STRONG>
+<P>
+by Frank Cringle at <A
+HREF="http://perl.apache.org/faq/">http://perl.apache.org/faq/</A> .
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl performance tuning guide</A></STRONG>
+<P>
+by Vivek Khera at <A
+HREF="http://perl.apache.org/tuning/">http://perl.apache.org/tuning/</A> .
-<LI><A HREF="http://perl.apache.org/dist/mod_perl_traps.html">mod_perl_traps,</A>
-common traps and solutions for mod_perl users. </LI>
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl plugin reference guide</A></STRONG>
+<P>
+by Doug MacEachern at <A
+HREF="http://perl.apache.org/src/mod_perl.html">http://perl.apache.org/src/mod_perl.html</A>
+.
+<P><LI><STRONG><A NAME="item_Quick">Quick guide for moving from CGI to mod_perl</A></STRONG>
+<P>
+at <A
+HREF="http://perl.apache.org/dist/cgi_to_mod_perl.html">http://perl.apache.org/dist/cgi_to_mod_perl.html</A>
+.
-<LI>Answers to some of the questions posted to <A
-HREF="mailto:modperl@apache.org">Apache/Perl mailing
-list</A>. (Subscription information is in the <a
-href="http://perl.apache.org/src/mod_perl-1.16/SUPPORT">SUPPORT</a>
-file in the distribution)</LI>
+<P><LI><STRONG><A NAME="item_mod_perl_traps">mod_perl_traps, common traps and solutions for mod_perl users</A></STRONG>
+<P>
+at <A
+HREF="http://perl.apache.org/dist/mod_perl_traps.html">http://perl.apache.org/dist/mod_perl_traps.html</A>
+.
+<P><LI><STRONG><A NAME="item_mod_perl">mod_perl mailing list emails</A></STRONG>
+<P>
+Answers to some of the questions posted to <A
+HREF="mailto:modperl@apache.org">modperl@apache.org</A> Apache/Perl mailing
+list.
-<LI>My personal experience with mod_perl</LI>
+<P><LI><STRONG><A NAME="item_My">My personal experience with mod_perl.</A></STRONG>
</UL>
-
-
-<P>As I said, I've quoted many information snippets from FAQs and emails,
- and I didn't credit people after each quote in the guide.
- I didn't mean to
- take the credits for myself, it's just that I've tried to keep
- track of names, and became lost, so I preferred not to credit at
- all in the guide, but to centralize it here. If you think that
- you want your name to show up under your original quote that I
- have used, please tell me and I'll add it for you.<P>
-
-
-<P>Major contributors:
+<P>
+As I said, I have quoted many information snippets from FAQs and emails,
+and I did not credit people after each quote in the guide. I did not mean
+to take the credits for myself, it's just that I have tried to keep track
+of names, and became lost, so I preferred not to credit at all in the
+guide, but to centralize it here. If you think that you want your name to
+show up under your original quote that I have used, please tell me and I'll
+add it for you.
+<P>
+Major contributors:
<UL>
- <LI><B>Doug MacEachern</B> - a big part of this guide is build upon his
- email replies to the users' questions
-
-
- <LI><B>Frank Cringle</B> - whose mod_perl FAQ lays in the basis of the guide.
-
-
- <LI><B>Vivek Khera</B> - for his mod_perl performance tuning guide.
-
-
- <LI><B>Steve Reppucci</B> - who made a thorough review of the stuff I
- wrote. Fixed lots of spelling and grammar errors, and made
- the guide readable to English speakers :)
+<P><LI><STRONG><A NAME="item_Doug">Doug MacEachern</A></STRONG>
+<P>
+a big part of this guide is build upon his email replies to the users'
+questions
+<P><LI><STRONG><A NAME="item_Frank">Frank Cringle</A></STRONG>
+<P>
+parts of his mod_perl FAQ has been used in the guide.
- <LI><B>Eric Cholet</B> - who wrote complete sections for the guide, and
- pointed out the errors the guide carried away.
+<P><LI><STRONG><A NAME="item_Vivek">Vivek Khera</A></STRONG>
+<P>
+for his mod_perl performance tuning guide.
+<P><LI><STRONG><A NAME="item_Steve">Steve Reppucci</A></STRONG>
+<P>
+who made a thorough review of the stuff I wrote. Fixed lots of spelling and
+grammar errors, and made the guide readable to English speakers :)
- <LI><B>Ken Williams</B> - who reviewed a lot of stuff in the guide, and
- many snippets from his emails are included in the guide.
+<P><LI><STRONG><A NAME="item_Eric">Eric Cholet</A></STRONG>
+<P>
+who wrote complete sections for the guide, and pointed out the errors the
+guide carried away.
+<P><LI><STRONG><A NAME="item_Ken">Ken Williams</A></STRONG>
+<P>
+who reviewed a lot of stuff in the guide, and many snippets from his emails
+are included in the guide.
</UL>
-
-
-<P> Credits go of course to ( alphabetically sorted ):
- <UL>
- <LI><B>Andreas J. Koenig</B>
- <LI><B>Ask Bjoern Hansen</B>
- <LI><B>Brian Moseley </B>
- <LI><B>Chad K. Lewis</B>
- <LI><B>David Landgren</B>
- <LI><B>Doug Bagley</B>
- <LI><B>Ed Park</B>
- <LI><B>Edmund Mergl</B>
- <LI><B>Evan A. Zacks</B>
- <LI><B>G.Richter</B>
- <LI><B>Garr Updegraff</B>
- <LI><B>Gunther Birznieks</B>
- <LI><B>Henrique Pantarotto</B>
- <LI><B>Howard Jones</B>
- <LI><B>Jeff Baker</B>
- <LI><B>Jeff Rowe</B>
- <LI><B>Jon Orwant</B>
- <LI><B>Jonathan Peterson</B>
- <LI><B>Leslie Mikesell</B>
- <LI><B>Lincoln Stein</B>
- <LI><B>Mark Mills</B>
- <LI><B>Marshall Dudley</B>
- <LI><B>Mike Fletcher</B>
- <LI><B>Nancy Lin</B>
- <LI><B>Nathan Torkington</B>
- <LI><B>Nathan Vonnahme</B>
- <LI><B>Perrin Harkins</B>
- <LI><B>Peter Skov</B>
- <LI><B>Radu Greab</B>
- <LI><B>Ralf Engelschall</B>
- <LI><B>Randal Schwartz</B>
- <LI><B>Richard Dice</B>
- <LI><B>Tzvetan Stoyanov</B>
- <LI><B>Ulrich Pfeifer</B>
- <LI>
- <LI>Did I miss you? Tell me!
- </UL>
-</P>
-
-
-<P>I want to thank all the people who donated their time and efforts
-to make this amazing idea of mod_perl a reality. This includes Doug
-MacEachern, the author of mod_perl and all the developers who
-contributed bug patches, modules and help. And of course the numerous
-unseen users who helped to find the bugs and advocate mod_perl around
-the world.</P>
-
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B>
-<HR WIDTH="100%"></P>
-
+<P>
+Credits of course go to ( alphabetically sorted ):
-<P><A HREF="index.html">[Back to the main page]</A></P>
+<UL>
+<P><LI><STRONG><A NAME="item_Andreas">Andreas J. Koenig</A></STRONG>
+<P><LI><STRONG><A NAME="item_Ask">Ask Bjoern Hansen</A></STRONG>
+<P><LI><STRONG><A NAME="item_Brian">Brian Moseley</A></STRONG>
+<P><LI><STRONG><A NAME="item_Chad">Chad K. Lewis</A></STRONG>
+<P><LI><STRONG><A NAME="item_David">David Landgren</A></STRONG>
+<P><LI><STRONG><A NAME="item_Doug">Doug Bagley</A></STRONG>
+<P><LI><STRONG><A NAME="item_Ed">Ed Park</A></STRONG>
+<P><LI><STRONG><A NAME="item_Edmund">Edmund Mergl</A></STRONG>
+<P><LI><STRONG><A NAME="item_Evan">Evan A. Zacks</A></STRONG>
+<P><LI><STRONG><A NAME="item_G">G.Richter</A></STRONG>
+<P><LI><STRONG><A NAME="item_Garr">Garr Updegraff</A></STRONG>
+<P><LI><STRONG><A NAME="item_Gunther">Gunther Birznieks</A></STRONG>
+<P><LI><STRONG><A NAME="item_Henrique">Henrique Pantarotto</A></STRONG>
+<P><LI><STRONG><A NAME="item_Howard">Howard Jones</A></STRONG>
+<P><LI><STRONG><A NAME="item_Jeff">Jeff Baker</A></STRONG>
+<P><LI><STRONG><A NAME="item_Jeff">Jeff Rowe</A></STRONG>
+<P><LI><STRONG><A NAME="item_Jon">Jon Orwant</A></STRONG>
+<P><LI><STRONG><A NAME="item_Jonathan">Jonathan Peterson</A></STRONG>
+<P><LI><STRONG><A NAME="item_Leslie">Leslie Mikesell</A></STRONG>
+<P><LI><STRONG><A NAME="item_Lincoln">Lincoln Stein</A></STRONG>
+<P><LI><STRONG><A NAME="item_Mark">Mark Mills</A></STRONG>
+<P><LI><STRONG><A NAME="item_Marshall">Marshall Dudley</A></STRONG>
+<P><LI><STRONG><A NAME="item_Mike">Mike Fletcher</A></STRONG>
+<P><LI><STRONG><A NAME="item_Nancy">Nancy Lin</A></STRONG>
+<P><LI><STRONG><A NAME="item_Nathan">Nathan Torkington</A></STRONG>
+<P><LI><STRONG><A NAME="item_Nathan">Nathan Vonnahme</A></STRONG>
+<P><LI><STRONG><A NAME="item_Perrin">Perrin Harkins</A></STRONG>
+<P><LI><STRONG><A NAME="item_Peter">Peter Skov</A></STRONG>
+<P><LI><STRONG><A NAME="item_Radu">Radu Greab</A></STRONG>
+<P><LI><STRONG><A NAME="item_Ralf">Ralf Engelschall</A></STRONG>
+<P><LI><STRONG><A NAME="item_Randal">Randal Schwartz</A></STRONG>
+<P><LI><STRONG><A NAME="item_Richard">Richard Dice</A></STRONG>
+<P><LI><STRONG><A NAME="item_Tzvetan">Tzvetan Stoyanov</A></STRONG>
+<P><LI><STRONG><A NAME="item_Ulrich">Ulrich Pfeifer</A></STRONG>
+<P><LI>
+<P><LI><STRONG><A NAME="item_Did">Did I miss you? Tell me!</A></STRONG>
+</UL>
+<P>
+I want to thank all the people who donated their time and efforts to make
+this amazing idea of mod_perl a reality. This includes Doug MacEachern, the
+author of mod_perl and all the developers who contributed bug patches,
+modules and help. And of course the numerous unseen users who helped to
+find the bugs and advocate mod_perl around the world.
+
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ The <a href="http://www.modperl.com/">
+ <B>Writing Apache Modules with Perl and C</B></a>
+ book can be purchased online from <a
+ href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
+ and <a
+ href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
+ Amazon.com</a>.
+ <HR>
+ [ <A HREF="index.html">Main Page</A> | <A HREF="start.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
-<TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
-<HR></TD>
+ <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
+ <HR>
+ </TD>
</TR>
-
-
-<TR ALIGN=CENTER VALIGN=TOP> <TD ALIGN=CENTER VALIGN=CENTER><B><FONT
-SIZE=-1>Written by <A HREF="help.html#author">Stas Bekman</A>.<BR> Last
-Modified at 04/17/1999 </FONT></B></TD>
-
-
-<TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg"
-BORDER=0 ALT="Mod Perl Icon" HEIGHT=59 WIDTH=150></A> </TD>
-
-
-<TD><FONT SIZE=-2>Use of the Camel for Perl is <BR>
-a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
-and is used by permission. </FONT> </TD>
+<TR ALIGN=CENTER VALIGN=TOP>
+ <TD ALIGN=CENTER VALIGN=CENTER>
+ <B>
+ <FONT SIZE=-1>
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
+ </FONT>
+ </B>
+ </TD>
+
+ <TD>
+ <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
+ </TD>
+
+ <TD>
+ <FONT SIZE=-2>
+ Use of the Camel for Perl is <BR>
+ a trademark of <A HREF="http://www.ora.com">O'Reilly & Associates</A>,<BR>
+ and is used by permission.
+ </FONT>
+ </TD>
</TR>
</TABLE></CENTER>
-
</BODY>
</HTML>
+
\ No newline at end of file
1.3 +46 -190 modperl-site/guide/modules.html
Index: modules.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/modules.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- modules.html 1999/04/19 19:53:38 1.2
+++ modules.html 1999/05/08 17:46:32 1.3
@@ -4,8 +4,11 @@
<TITLE>mod_perl guide: Apache::* modules</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,41 +19,24 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Apache::* modules</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="browserbugs.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="perl.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Apache_Session_Maintain_sessi">Apache::Session - Maintain session state across HTTP requests</A>
<LI><A HREF="#Apache_DBI_Initiate_a_persist">Apache::DBI - Initiate a persistent database connection</A>
- <UL>
-
- <LI><A HREF="#Introduction">Introduction</A>
- <LI><A HREF="#Configuration">Configuration </A>
- <LI><A HREF="#Preopening_DBI_connections">Preopening DBI connections</A>
- <LI><A HREF="#Debugging_Apache_DBI">Debugging Apache::DBI</A>
- <LI><A HREF="#Problems_and_solutions">Problems and solutions</A>
- <UL>
-
- <LI><A HREF="#The_morning_bug">The morning bug</A>
- <LI><A HREF="#Cannot_find_the_DBI_handler">Cannot find the DBI handler</A>
- <LI><A HREF="#Apache_DBI_does_not_work">Apache:DBI does not work</A>
- </UL>
-
- </UL>
-
<LI><A HREF="#Apache_Request_libapreq_Gen">Apache::Request (libapreq) - Generic Apache Request Library</A>
+ <LI><A HREF="#Apache_PerlRun_Run_unaltered_">Apache::PerlRun - Run unaltered CGI scripts under mod_perl</A>
</UL>
<!-- INDEX END -->
-
-
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -60,7 +46,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Apache_Session_Maintain_sessi">Apache::Session - Maintain session state across HTTP requests</A></H1></CENTER>
<P>
@@ -71,6 +59,28 @@
reference.
<P>
+What Apache::Session does is provide persistence to a data structure. The
+data structure has an ID number, and you can retrieve it by using the ID
+number. In the case of Apache, you would store the ID number in a cookie or
+the URL to associate it with one browser, but the method of dealing with
+the ID is completely up to you. The flow of things is generally:
+
+<P>
+<PRE> Tie a session to Apache::Session.
+ Get the ID number.
+ Store the ID number in a cookie.
+ End of Request 1.
+</PRE>
+<P>
+<PRE> (time passes)
+</PRE>
+<P>
+<PRE> Get the cookie.
+ Restore your hash using the ID number in the cookie.
+ Use whatever data you put in the hash.
+ End of Request 2.
+</PRE>
+<P>
Using Apache::Session is easy: simply tie a hash to the session object,
stick any data structure into the hash, and the data you put in
automatically persists until the next invocation. Here is a quick example
@@ -132,174 +142,13 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Apache_DBI_Initiate_a_persist">Apache::DBI - Initiate a persistent database connection</A></H1></CENTER>
-<P>
-This module initiates a persistent database connection. It is possible only
-with mod_perl.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Introduction">Introduction</A></H2></CENTER>
-<P>
-When loading the DBI module (do not confuse this with the Apache::DBI
-module) it looks if the environment variable GATEWAY_INTERFACE starts with
-'CGI-Perl' and if the module Apache::DBI has been loaded. In this case
-every connect request will be forwarded to the Apache::DBI module. This
-looks if a database handle from a previous connect request is already
-stored and if this handle is still valid using the ping method. If these
-two conditions are fulfilled it just returns the database handle. If there
-is no appropriate database handle or if the ping method fails, a new
-connection is established and the handle is stored for later re-use. In
-other words when the script is run again from a child that has already (and
-is still) connected, the host/username/password is checked against the
-cache of open connections, and if one is available, uses that one. There is
-no need to delete the disconnect statements from your code. They won't do
-anything because the Apache::DBI module overloads the disconnect method
-with a NOP.
-
-<P>
-You want to use this module if you are opening a <STRONG>few</STRONG> DB connections to the server. <CODE>Apache::DBI</CODE> will make them persistent per child, so if you have 10 children and each
-opens 2 different connections you will have in total 20 opened persistent
-connections. Thus after initial connect you will save up the connection
-time for every connect request from your DBI module. Which is a huge
-benefit for the mod_perl apache server with high traffic of users deploying
-the relational DB.
-
-<P>
-As you understand you must NOT use this module if you are opening a special
-connection for each of your users, since each of them will stay persistent
-and in a short time the number of connections will be so big that your
-machine will scream and die. If you want to use
-<CODE>Apache::DBI</CODE> in both situations, as of this moment the only available solution is to run
-2 mod_perl servers, one using
-<CODE>Apache::DBI</CODE> and one not.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Configuration">Configuration</A></H2></CENTER>
-<P>
-After installing this module, the configuration is simple - add to the
-<CODE>httpd.conf</CODE> the following directive.
-
-<P>
-<PRE> PerlModule Apache::DBI
-</PRE>
-<P>
-Note that it is important, to load this module before any other ApacheDBI
-module !
-
-<P>
-You can skip preloading <CODE>DBI</CODE>, since <CODE>Apache::DBI</CODE> does that. But there is no harm if you leave it in.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Preopening_DBI_connections">Preopening DBI connections</A></H2></CENTER>
-<P>
-If you want that when you call the script after server restart, the
-connection will be already preopened, you should use
-<CODE>connect_on_init()</CODE> method in the startup file to preload every connection you are going to
-use. For example:
-
-<P>
-<PRE> Apache::DBI->connect_on_init
- ("DBI:mysql:myDB::myserver",
- "username",
- "passwd",
- {
- PrintError => 1, # warn() on errors
- RaiseError => 0, # don't die on error
- AutoCommit => 1, # commit executes immediately
- }
- );
-</PRE>
-<P>
-As noted before, it is wise to you this method only if you only want all of
-apache to be able to connect to the database server as one user (or few
-users).
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Debugging_Apache_DBI">Debugging Apache::DBI</A></H2></CENTER>
-<P>
-If you are not sure this module is working as advertised, you should enable
-the Debug mode in the startup script by:
-
<P>
-<PRE> $Apache::DBI::DEBUG = 1;
-</PRE>
-<P>
-Since now on you will see in the <CODE>error.log</CODE> file when Apache::DBI initializes a connection and when it just returns it
-from its cache. Use the following command to see it in the real time (your
-<CODE>error.log</CODE> file might be locate at a different path):
-
-<P>
-<PRE> tail -f /usr/local/apache/logs/error_log
-</PRE>
-<P>
-I use <CODE>alias</CODE> so I will not have to remember the path:
+See <A HREF="././databases.html#Apache_DBI_Initiate_a_persist">mod_perl and relational Databases</A>
-<P>
-<PRE> alias err "tail -f /usr/local/apache/logs/error_log"
-</PRE>
-<P>
-Another approach is to add to <CODE>httpd.conf</CODE> (which does the same):
-
-<P>
-<PRE> PerlModule Apache::DebugDBI
-</PRE>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Problems_and_solutions">Problems and solutions</A></H2></CENTER>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="The_morning_bug">The morning bug</A></H3></CENTER>
-<P>
-SQL server keeps the connection to the client open for a limited period of
-time. So many developers were bitten by so called <STRONG>Morning
-bug</STRONG> when every morning the first users to use the site were receiving: <CODE>No Data Returned</CODE> message, but then everything worked as usual. The error caused by <CODE>Apache::DBI</CODE> returning a handle of the invalid connection (server closed it because of
-timeout), and the script was dying on that error. The infamous and well
-documented in the man page, <CODE>ping()</CODE> method was introduced to solve this problem. But seems that people are
-still being beaten by this problem. Another solution was found - to rise
-the timeout parameter at the SQL server startup. Currently I startup <CODE>mySQL</CODE> server with
-<CODE>safe_mysql</CODE> script, so I have updated it to use this option:
-<P>
-<PRE> nohup $ledir/mysqld [snipped other options] -O wait_timeout=172800
-</PRE>
-<P>
-Where 172800 secs equal to 48 hours. And it works.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="Cannot_find_the_DBI_handler">Cannot find the DBI handler</A></H3></CENTER>
-<P>
-Q: I cannot find the handler name with which to manipulate my connection;
-hence I seem to be unable to do anything to my database.
-
-<P>
-A: You did not use <CODE>DBI::connect()</CODE> as with usual DBI usage to get your <CODE>$dbh</CODE> database handler.
-Using the <CODE>Apache::DBI</CODE> does not eliminate the need to write a proper <CODE>DBI</CODE> code. As the man page states - you should program as if you did not use <CODE>Apache::DBI</CODE> at all. <CODE>Apache::DBI</CODE> will override and return you a cached connection. And in case of <CODE>disconnect()</CODE> call it will be just ignored.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="Apache_DBI_does_not_work">Apache:DBI does not work</A></H3></CENTER>
-<P>
-Make sure you have it installed.
-
-<P>
-Make sure you configured mod_perl with EVERYTHING=1.
-
-<P>
-Use the example script eg/startup.pl (remove the comment from the line
-
-<P>
-<PRE> #use Apache::DebugDBI;
-</PRE>
-<P>
-and adapt the connect string. Do not change anything in your scripts, for
-using Apache::DBI.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Apache_Request_libapreq_Gen">Apache::Request (libapreq) - Generic Apache Request Library</A></H1></CENTER>
<P>
This package contains modules for manipulating client request data via the
@@ -329,7 +178,13 @@
HREF="http://perl.apache.org/dist/libapreq-x.xx.tar.gz">http://perl.apache.org/dist/libapreq-x.xx.tar.gz</A>
. (replace x.xx with the current version)
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Apache_PerlRun_Run_unaltered_">Apache::PerlRun - Run unaltered CGI scripts under mod_perl</A></H1></CENTER>
+<P>
+See <A HREF="././porting.html#Apache_PerlRun_a_closer_look">Apache::PerlRun - a closer look</A>.
+
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -338,7 +193,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="browserbugs.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="perl.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -350,8 +206,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
1.3 +16 -12 modperl-site/guide/multiuser.html
Index: multiuser.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/multiuser.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- multiuser.html 1999/04/19 19:53:38 1.2
+++ multiuser.html 1999/05/08 17:46:32 1.3
@@ -4,8 +4,11 @@
<TITLE>mod_perl guide: mod_perl for ISPs. mod_perl and Virtual Hosts.</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,25 +19,23 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
mod_perl for ISPs. mod_perl and Virtual Hosts.</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="dbm.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="control.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#ISPs_providing_mod_perl_services">ISPs providing mod_perl services - a fantasy or reality.</A>
<LI><A HREF="#Virtual_Hosts_in_the_guide">Virtual Hosts in the guide</A>
</UL>
<!-- INDEX END -->
-
+<HR>
- <P><A HREF="index.html">[Back to the main index]</A></P>
-
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -43,7 +44,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="ISPs_providing_mod_perl_services">ISPs providing mod_perl services - a fantasy or reality.</A></H1></CENTER>
<P>
@@ -220,7 +223,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="dbm.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="control.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -232,8 +236,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 04/19/1999
</FONT>
</B>
</TD>
1.11 +58 -19 modperl-site/guide/obvious.html
Index: obvious.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/obvious.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- obvious.html 1999/04/19 19:53:39 1.10
+++ obvious.html 1999/05/08 17:46:32 1.11
@@ -4,8 +4,11 @@
<TITLE>mod_perl guide: Things obvious to others, but not to you</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,14 +19,14 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Things obvious to others, but not to you</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="performance.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="warnings.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Coverage">Coverage</A>
@@ -49,13 +52,12 @@
<LI><A HREF="#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>
<LI><A HREF="#Handling_the_server_timeout_case">Handling the server timeout cases</A>
<LI><A HREF="#Where_do_the_warnings_errors_go_">Where do the warnings/errors go?</A>
+ <LI><A HREF="#Setting_environment_variables_fo">Setting environment variables for scripts called from CGI.</A>
</UL>
<!-- INDEX END -->
-
+<HR>
- <P><A HREF="index.html">[Back to the main index]</A></P>
-
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -64,7 +66,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
<P>
@@ -181,9 +185,8 @@
making an entry in the symbol table, and you are telling the
compiler that you are going to be referencing that entry without an
explicit package name.
-</PRE>
-<P>
-<PRE> With my(), NO ENTRY IS PUT IN THE SYMBOL TABLE. The compiler
+
+ With my(), NO ENTRY IS PUT IN THE SYMBOL TABLE. The compiler
figures out _at_ _compile_time_ which my() variables (i.e. lexical
variables) are the same as each other, and once you hit execute time
you can not go looking those variables up in the symbol table.
@@ -197,9 +200,8 @@
the previous value (if any) is restored. References to such a
variable are *also* global... only the value changes. (Aside: that
is what causes variable suicide. :)
-</PRE>
-<P>
-<PRE> my() creates a lexically-limited non-package-based scalar, array, or
+
+ my() creates a lexically-limited non-package-based scalar, array, or
hash -- when the scope of definition is exited at compile-time, the
variable ceases to be accessible. Any references to such a variable
at runtime turn into unique anonymous variables on each scope exit.
@@ -592,7 +594,7 @@
<P>
Here is the working example. Run the server with -X, Press 'Stop' before
-the countup to 10 has been finished. Then rerun the script, it'll hang in
+the count-up to 10 has been finished. Then rerun the script, it'll hang in
<CODE>while(1)!</CODE> The resource is not available anymore.
<P>
@@ -753,7 +755,43 @@
<P>
</META>
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Setting_environment_variables_fo">Setting environment variables for scripts called from CGI.</A></H1></CENTER>
+<P>
+Perl uses <CODE>sh()</CODE> for its iteractions for <CODE>system()</CODE> and <CODE>open()</CODE>
+calls. So when you want to set a temporary variable when you call a script
+from your CGI you do:
+
+<P>
+<PRE> open UTIL, "USER=stas ; script.pl | " or die "...: $!\n";
+</PRE>
+<P>
+or
+
+<P>
+<PRE> system "USER=stas ; script.pl";
+</PRE>
+<P>
+This is useful for example if you need to invoke a script that uses CGI.pm
+from within a mod_perl script. We are tricking the perl script to think
+it's a simple CGI, which is not running under mod_perl.
+
+<P>
+<PRE> open(PUBLISH, "GATEWAY_INTERFACE=CGI/1.1 ; script.cgi
+ \"param1=value1&param2=value2\" |") or die "...: $!\n";
+</PRE>
+<P>
+Make sure, that the parameters you pass are shell safe (All ``unsafe''
+characters like single-tick should be properly escaped).
+
+<P>
+However you are fork-ing to run a Perl script, so you have thrown the so
+hardly gained performance out the window. Whatever script.cgi is now, it
+should be moved to a module with a subroutine you can call directly from
+your script, to avoid the fork.
+
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -762,7 +800,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="performance.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="warnings.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -774,8 +813,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
1.13 +122 -25 modperl-site/guide/performance.html
Index: performance.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/performance.html,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- performance.html 1999/04/19 19:53:40 1.12
+++ performance.html 1999/05/08 17:46:32 1.13
@@ -4,8 +4,11 @@
<TITLE>mod_perl guide: Performance. Benchmarks.</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,14 +19,14 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Performance. Benchmarks.</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="porting.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="obvious.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A>
@@ -62,14 +65,13 @@
</UL>
<LI><A HREF="#Persistent_DB_Connections">Persistent DB Connections</A>
- <LI><A HREF="#Why_you_should_not_use_1_unde">Why you should not use $|=1 under mod_perl</A>
+ <LI><A HREF="#Using_1_under_mod_perl_and_be">Using $|=1 under mod_perl and better print() techniques.</A>
<LI><A HREF="#Profiling">Profiling</A>
+ <LI><A HREF="#CGI_pm_s_object_methods_calls_vs">CGI.pm's object methods calls vs. function calls</A>
</UL>
<!-- INDEX END -->
-
-
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -79,7 +81,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Preload_Perl_modules_at_server_s">Preload Perl modules at server startup</A></H1></CENTER>
<P>
@@ -489,7 +493,7 @@
<P>
-See <A HREF="././porting.html#Memory_leakages">Memory "leakages"</A>
+See <A HREF="././porting.html#Memory_leakage">Memory "leakages"</A>
@@ -825,7 +829,7 @@
Total: 13 67 74
</PRE>
<P>
-The only numbers we really care about are:
+The only numbers we are really care about are:
<P>
<PRE> Complete requests: 100
@@ -1470,7 +1474,7 @@
<P><LI><STRONG><A NAME="item_MaxSpareServers">MaxSpareServers</A></STRONG>
<P>
-The logic the same as of MinSpareServers - low if need the machine for
+The logic is the same as of MinSpareServers - low if need the machine for
other tasks, high if it's web dedicated and you want the minimal delay on
responses.
@@ -1591,18 +1595,82 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Why_you_should_not_use_1_unde">Why you should not use $|=1 under mod_perl</A></H1></CENTER>
+<CENTER><H1><A NAME="Using_1_under_mod_perl_and_be">Using $|=1 under mod_perl and better print() techniques.</A></H1></CENTER>
<P>
-As you know <CODE>$1=1</CODE> disables the buffering of the current selected file handle (default is
-STDOUT). If you enable it <CODE>ap_rflush()</CODE> is called after each
-<CODE>print(),</CODE> unbuffering Apache's IO.
+As you know <CODE>$|=1;</CODE> disables the buffering of the currently selected file handle (default is
+STDOUT). If you enable it, <CODE>ap_rflush()</CODE> is being called after
+each <CODE>print()</CODE>, unbuffering Apache's IO.
<P>
-If you are using the _bad_ style of generating the output, by multiply
-<CODE>print()</CODE> calls or you just have too many of them, you will experience a degradation
+If you are using a _bad_ style of output generating, which consist of
+multiply <CODE>print()</CODE> calls or you just have too many of them, you will experience a degradation
in performance. The severity depends on the number of the calls.
<P>
+Many old CGIs were written in style of:
+
+<P>
+<PRE> print "<BODY BGCOLOR=\"black\" TEXT=\"white\">";
+ print "<H1>";
+ print "Hello";
+ print "</H1>";
+ print "<A HREF=\"foo.html\"> foo </A>";
+ print "</BODY>";
+</PRE>
+<P>
+which reveals the following drawbacks: multiply <CODE>print()</CODE> calls - performance degradation with $|=1, backslashism which makes the
+code unreadable and difficulty to format the HTML to be easily readable as
+CGI's output. The code below solves them all:
+
+<P>
+<PRE> print qq{
+ <BODY BGCOLOR="black" TEXT="white">
+ <H1>
+ Hello
+ </H1>
+ <A HREF="foo.html"> foo </A>
+ </BODY>
+ };
+</PRE>
+<P>
+I guess you see the difference. Be careful though, when printing the
+<CODE>&lt;HTML&gt;</CODE> tag. The correct way is:
+
+<P>
+<PRE> print qq{<HTML>
+ <HEAD></HEAD>
+ <BODY>
+ }
+</PRE>
+<P>
+If you use the approach bellow:
+
+<P>
+<PRE> print qq{
+ <HTML>
+ <HEAD></HEAD>
+ <BODY>
+ }
+</PRE>
+<P>
+Some older browsers might not accept the output as HTML, and print it as a
+plain text, since they expect the first characters after the headers and
+empty line to be <CODE>&lt;HTML&gt;</CODE> and not spaces and/or additional newline and then <CODE>&lt;HTML&gt;</CODE>. Even if it works in your browser it might not work in other.
+
+<P>
+Now let's go back to the <CODE>$|=1</CODE> topic. I still disable the buffering, for 2 reasons: I use few <CODE>print()</CODE> calls and I want my users to get the output immediately. So if I am about
+to produce the results of the DB query, which might take some time to
+complete, I want user to get some headers which improves the usability of
+my site. Recall yourself - what do you like better: getting the output
+``slowly'' but steadily or having to watch the ``falling stars'' for awhile
+and then getting the whole output at once (if browser did not timeout till
+then).
+
+<P>
+Conclusion: Do not follow blind suggestions but think what is best for you
+in every given case.
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Profiling">Profiling</A></H1></CENTER>
<P>
@@ -1615,8 +1683,8 @@
module available on CPAN. However, you must have apache version 1.3b3 or
higher and the PerlChildExitHandler enabled. When the server is started,
Devel::DProf installs an END block to write the tmon.out file, which will
-be run when the server is shutdown. Here's how to start and stop a server
-with the profiler enabled:
+be run when the server is shutdown. Here is how to start and stop a server
+with the profiler enabled:
<P>
<PRE> % setenv PERL5OPT -d:DProf
@@ -1630,8 +1698,36 @@
The Devel::DProf package is a Perl code profiler. This will collect
information on the execution time of a Perl script and of the subs in that
script. This information can be used to determine which subroutines are
-using the most time and which subroutines are being called most often.
+using the most time and which subroutines are being called most often.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="CGI_pm_s_object_methods_calls_vs">CGI.pm's object methods calls vs. function calls</A></H1></CENTER>
+<P>
+What approach is better?
+
+<P>
+<PRE> use CGI;
+ my $q = new CGI;
+ print $q->param('x');
+</PRE>
+<P>
+versus
+<P>
+<PRE> use CGI (:standard);
+ print param('x');
+</PRE>
+<P>
+There is not any performance benefit of using the object calls rather than
+the function calls, but there is a real memory hit when you import all of
+CGI.pm's function calls into the process memory. This can be significant,
+particularly when there are many child daemons.
+
+<P>
+I strongly endorse <A HREF="././modules.html#Apache_Request_libapreq_Gen">Apache::Request (libapreq) - Generic Apache Request Library</A>. Its guts are all written in C, giving it a significant memory and
+performance benefit.
+
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -1641,7 +1737,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="porting.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="obvious.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -1653,8 +1750,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
1.4 +16 -12 modperl-site/guide/perl.html
Index: perl.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/perl.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- perl.html 1999/04/19 19:53:41 1.3
+++ perl.html 1999/05/08 17:46:33 1.4
@@ -4,8 +4,11 @@
<TITLE>mod_perl guide: Perl Reference</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,14 +19,14 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Perl Reference</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="modules.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="snippets.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Coverage">Coverage</A>
@@ -38,11 +41,9 @@
</UL>
<!-- INDEX END -->
-
+<HR>
- <P><A HREF="index.html">[Back to the main index]</A></P>
-
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -51,7 +52,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
<P>
@@ -301,7 +304,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="modules.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="snippets.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -313,8 +317,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 04/19/1999
</FONT>
</B>
</TD>
1.14 +155 -38 modperl-site/guide/porting.html
Index: porting.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/porting.html,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- porting.html 1999/04/19 19:53:41 1.13
+++ porting.html 1999/05/08 17:46:33 1.14
@@ -4,8 +4,11 @@
<TITLE>mod_perl guide: CGI to mod_perl Porting. mod_perl Coding guidelines.</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,14 +19,14 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
CGI to mod_perl Porting. mod_perl Coding guidelines.</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="frequent.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="performance.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Document_Coverage">Document Coverage</A>
@@ -42,8 +45,8 @@
<LI><A HREF="#Using_exit_">Using exit()</A>
<LI><A HREF="#Running_from_shell">Running from shell</A>
<LI><A HREF="#I_O_is_different">I/O is different</A>
- <LI><A HREF="#HTTP_MIME_Headers">HTTP (MIME) Headers</A>
- <LI><A HREF="#NPH_Non_Parsed_Headers_scripts">NPH (Non Parsed Headers) scripts </A>
+ <LI><A HREF="#HTTP_MIME_Headers_PerlSendHea">HTTP + MIME Headers (PerlSendHeader)</A>
+ <LI><A HREF="#NPH_Non_Parsed_Headers_scripts">NPH (Non Parsed Headers) scripts</A>
<LI><A HREF="#BEGIN_blocks">BEGIN blocks </A>
<LI><A HREF="#END_blocks">END blocks </A>
<LI><A HREF="#Switches_w_T">Switches -w, -T</A>
@@ -66,13 +69,13 @@
</UL>
<LI><A HREF="#Redirecting_Errors_to_Client_ins">Redirecting Errors to Client instead of error_log</A>
+ <LI><A HREF="#Finding_the_line_number_the_erro">Finding the line number the error/warning has been triggered at</A>
+ <LI><A HREF="#Forking_subprocesses_from_mod_pe">Forking subprocesses from mod_perl</A>
</UL>
<!-- INDEX END -->
-
+<HR>
- <P><A HREF="index.html">[Back to the main index]</A></P>
-
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -81,7 +84,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Document_Coverage">Document Coverage</A></H1></CENTER>
<P>
@@ -208,7 +213,7 @@
<P>
And both scripts do: <CODE>use Foo;</CODE> only the first one called will know about Foo, when you will call the
second script it will not know about Foo at all - it's like you've
-forgotten to write <CODE>use Foo;</CODE>. Run the server in <A HREF="././control.html#Single_Mode_Running">single server mode</A> to solve that kind of bug immediately.
+forgotten to write <CODE>use Foo;</CODE>. Run the server in <A HREF="././control.html#Running_server_in_a_single_mode">single server mode</A> to solve that kind of bug immediately.
<P>
You will see the following in the error_log file:
@@ -447,7 +452,7 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="HTTP_MIME_Headers">HTTP (MIME) Headers</A></H3></CENTER>
+<CENTER><H3><A NAME="HTTP_MIME_Headers_PerlSendHea">HTTP + MIME Headers (PerlSendHeader)</A></H3></CENTER>
<P>
By default, mod_perl does not send any headers by itself, however, you may
wish to change this (in httpd.conf):
@@ -464,7 +469,7 @@
<PRE> print "Content-type: text/html\r\n\r\n";
</PRE>
<P>
-If you're using CGI.pm or CGI::Switch and <STRONG>print $q->header</STRONG> you do _not_ need PerlSendHeader On.
+If you are using CGI.pm or CGI::Switch and <STRONG>print $q->header</STRONG> you do _not_ need PerlSendHeader On.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -501,50 +506,50 @@
Modules and files pulled in via require/use which contain BEGIN blocks will
be executed:
-<DL>
-<P><DT><STRONG><A NAME="item__">-</A></STRONG><DD>
+<UL>
+<P><LI>
<P>
only once, if pulled in by the parent process.
-<P><DT><STRONG>-</STRONG><DD>
+<P><LI>
<P>
once per-child process if not pulled in by the parent process.
-<P><DT><STRONG>-</STRONG><DD>
+<P><LI>
<P>
an additional time, once per-child process if the module is pulled in off
of disk again via Apache::StatINC.
-<P><DT><STRONG>-</STRONG><DD>
+<P><LI>
<P>
an additional time, in the parent process on each restart if
PerlFreshRestart is On.
-<P><DT><STRONG>-</STRONG><DD>
+<P><LI>
<P>
unpredictable if you fiddle with <CODE>%INC</CODE> yourself.
-</DL>
+</UL>
<P>
Apache::Registry scripts which contain BEGIN blocks will be executed:
-<DL>
-<P><DT><STRONG>-</STRONG><DD>
+<UL>
+<P><LI>
<P>
only once, if pulled in by the parent process via Apache::RegistryLoader -
once per-child process if not pulled in by the parent process.
-<P><DT><STRONG>-</STRONG><DD>
+<P><LI>
<P>
an additional time, once per-child process if the script file has changed
on disk.
-<P><DT><STRONG>-</STRONG><DD>
+<P><LI>
<P>
an additional time, in the parent process on each restart if pulled in by
the parent process via Apache::RegistryLoader and PerlFreshRestart is On.
-</DL>
+</UL>
<P>
Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
@@ -577,9 +582,7 @@
desirable.
<P>
-The last paragraph is very important for the <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>
-
-
+The last paragraph is very important for the <A HREF="././obvious.html#Handling_the_User_pressed_Stop_">Handling the 'User pressed Stop button' case</A>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -622,14 +625,15 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="strict_pragma">strict pragma</A></H2></CENTER>
<P>
-It's absolutely mandatory to start all your scripts with:
+It's _absolutely_ mandatory (at least for development) to start all your
+scripts with:
<P>
-<PRE> use strict; (at least for development)
+<PRE> use strict;
</PRE>
<P>
-If needed, you can always turn off the 'strict' pragma inside the block,
-e.g:
+If needed, you can always turn off the 'strict' pragma or a part of it
+inside the block, e.g:
<P>
<PRE> {
@@ -1052,7 +1056,7 @@
the more it runs without a restart, the more it screws up. Many times you
can resolve this problem very easily. You have to test your script under
with Server running as a
-<A HREF="././control.html#Single_Mode_Running">single process</A>.
+<A HREF="././control.html#Running_server_in_a_single_mode">single process</A>.
<P>
Generally the problem you have is using global variables. Since global
@@ -1125,7 +1129,7 @@
<P>
To make sure you don't miss these bugs always test your CGI in
-<A HREF="././control.html#Single_Mode_Running">single process</A>. To solve this particular <STRONG>/o</STRONG> problem refer to <A HREF="././obvious.html#Compiled_Regular_Expressions">Compiled Regular Expressions</A>.
+<A HREF="././control.html#Running_server_in_a_single_mode">single process</A>. To solve this particular <STRONG>/o</STRONG> problem refer to <A HREF="././obvious.html#Compiled_Regular_Expressions">Compiled Regular Expressions</A>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -1372,7 +1376,119 @@
method to print the errors and wouldn't <CODE>die()</CODE> unless you want
it.
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Finding_the_line_number_the_erro">Finding the line number the error/warning has been triggered at</A></H1></CENTER>
+<P>
+If you compile with the experimental <STRONG>PERL_MARK_WHERE=1</STRONG>, it shows you ``exactly'' where this is happening. many times compiler
+makes a shift for ``unknown'' reasons in its line counter. You can always
+stuff your code with special compiler directives, to reset its counter to
+the value you will tell. At the beginning of the line you should write (the
+'#' in column 1):
+
+<P>
+<PRE> #line 298 myscript.pl
+ or
+ #line 890 some_label_to_be_used_in_the_error_message
+</PRE>
+<P>
+The label is optional - the filename of the script will be used by default.
+This specifies the line number of the <STRONG>following</STRONG> line, not the line the directive is on. You can use a little script to
+stuff every N lines of your code with these directives, but then you will
+have to rerun this script every time you add or remove code lines. The
+script:
+
+<P>
+<PRE> <META>
+ This example was double incrementing $counter.
+ I took the second increment out -- sgr.
+ </META>
+</PRE>
+<P>
+<PRE> #!/usr/bin/perl
+ # Puts Perl line markers in a Perl program for debugging purposes.
+ # Also takes out old line markers.
+ die "No filename to process.\n" unless @ARGV;
+ my $filename = $ARGV[0];
+ my $lines = 100;
+ open IN, $filename or die "Cannot open file: $filename: $!\n";
+ open OUT, ">$filename.marked"
+ or die "Cannot open file: $filename.marked: $!\n";
+ my $counter = 1;
+ while (<IN>) {
+ print OUT "#line $counter\n" unless $counter++ % $lines;
+ next if $_ =~ /^#line /;
+ print OUT $_;
+ }
+ close OUT;
+ close IN;
+ chmod 0755, "$filename.marked";
+</PRE>
+<P>
+To have a complete trace of calls add:
+
+<P>
+<PRE> use Carp ();
+ local $SIG{__WARN__} = \&Carp::cluck;
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Forking_subprocesses_from_mod_pe">Forking subprocesses from mod_perl</A></H1></CENTER>
+<P>
+Generally you should not fork from your mod_perl scripts, since when you do
+you are forking the entire apache web server, lock, stock and barrel. Not
+only is your perl code being duplicated, but so is mod_ssl, mod_rewrite,
+mod_log, mod_proxy, mod_speling or whatever modules you have used in your
+server, all the core routines and so on. A much wiser approche would be to
+spawn a sub-process, hand it the information it needs to do the task, and
+have it detach (close x3 + <CODE>setsid()).</CODE> This is wise only if the
+parent who spawns this process, immediately continue, you do not wait for
+the sub process to complete. This approach is suitable for a situation when
+you want to trigger a long time taking process through the web interface,
+like processing some data, sending email to thousands of subscribed users
+and etc. Otherwise, you should convert the code into a module, and use its
+function or methods to call from CGI script. Just making a
+<CODE>system()</CODE> call defeats the whole idea behind mod_perl, perl interpreter and modules
+should be loaded again for this extenal program to run.
+
+<P>
+Basically, you would do:
+
+<P>
+<PRE> $params=FreezeThaw::freeze(
+ [all data to pass to the other process]
+ );
+ system("program.pl $params");
+</PRE>
+<P>
+and in <CODE>program.pl</CODE> :
+
+<P>
+<PRE> @params=FreezeThaw::thaw(shift @ARGV);
+ # check that @params is ok
+ close STDIN;
+ close STDOUT;
+ open STDERR, ">/dev/null";
+ setsid(); # to detach
+</PRE>
+<P>
+At this point, <CODE>program.pl</CODE> is running in the ``background'' while the <CODE>system()</CODE> returns
+and permits apache to get on with life.
+
+<P>
+This has obvious problems. Not the least of which is that
+<CODE>$params</CODE> must not be bigger then whatever your architecture's
+limit is (could depend on your shell).
+
+<P>
+Also, the communication is only one way.
+
+<P>
+However, you might want be trying to do the ``wrong thing''. If what you
+want is to send information to the browser and then do some
+post-processing, look into <CODE>PerlCleanupHandler</CODE>.
+
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -1381,7 +1497,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="frequent.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="performance.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -1393,8 +1510,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
1.12 +343 -458 modperl-site/guide/scenario.html
Index: scenario.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/scenario.html,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- scenario.html 1999/04/19 19:53:42 1.11
+++ scenario.html 1999/05/08 17:46:33 1.12
@@ -1,11 +1,14 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: Server Installation. Real World scenarios</TITLE>
+ <TITLE>mod_perl guide: Real World Scenarios of Implementing Various Strategies</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,55 +19,44 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Server Installation. Real World scenarios</H1>
+Real World Scenarios of Implementing Various Strategies</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="strategy.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="install.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
- <LI><A HREF="#Making_a_Strategic_Decision">Making a Strategic Decision</A>
- <LI><A HREF="#Deciding_on_a_Directory_Layout">Deciding on a Directory Layout</A>
- <LI><A HREF="#Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A>
+ <LI><A HREF="#Before_you_dive_into_the_gory_de">Before you dive into the gory details</A>
+ <LI><A HREF="#One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl enabled Apache Servers</A>
<UL>
-
- <LI><A HREF="#httpd_docs_Server">httpd_docs Server</A>
- <LI><A HREF="#httpd_perl_Server_mod_perl_">httpd_perl Server (mod_perl):</A>
- <LI><A HREF="#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>
- </UL>
- <LI><A HREF="#More_mod_perl_deploying_schemas">More mod_perl deploying schemas</A>
- <LI><A HREF="#mod_perl_and_proxy_server">mod_perl and proxy server</A>
- <UL>
-
- <LI><A HREF="#Incentives">Incentives</A>
- <LI><A HREF="#Squid_proxy_server_in_httpd_acce">Squid proxy server in httpd accelerator mode</A>
+ <LI><A HREF="#Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A>
<UL>
- <LI><A HREF="#Running_a_squid_and_2_webservers">Running a squid and 2 webservers scenario</A>
- <LI><A HREF="#Running_a_squid_and_1_mod_perl_a">Running a squid and 1 mod_perl apache server scenario</A>
+ <LI><A HREF="#Building_the_httpd_docs_Server">Building the httpd_docs Server</A>
+ <LI><A HREF="#Building_the_httpd_perl_Server_">Building the httpd_perl Server (mod_perl):</A>
</UL>
- </UL>
+ <LI><A HREF="#Configuration_of_the_servers">Configuration of the servers</A>
+ <UL>
- <LI><A HREF="#Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A>
- <LI><A HREF="#Is_it_possible_to_determine_whic">Is it possible to determine which options were given to modperl's Makefile.PL</A>
- <LI><A HREF="#mod_perl_as_DSO">mod_perl as DSO</A>
- <LI><A HREF="#Installation_problems">Installation problems</A>
- <UL>
+ <LI><A HREF="#Basic_httpd_docs_Server_s_Config">Basic httpd_docs Server's Configuration</A>
+ <LI><A HREF="#Basic_httpd_perl_Server_s_Config">Basic httpd_perl Server's Configuration</A>
+ </UL>
- <LI><A HREF="#make_test_fails">make test fails</A>
</UL>
+ <LI><A HREF="#Running_2_webservers_and_squid_i">Running 2 webservers and squid in httpd accelerator mode</A>
+ <LI><A HREF="#Running_1_webserver_and_squid_in">Running 1 webserver and squid in httpd accelerator mode</A>
+ <LI><A HREF="#Using_mod_proxy">Using mod_proxy</A>
+ <LI><A HREF="#mod_perl_server_as_DSO">mod_perl server as DSO</A>
</UL>
<!-- INDEX END -->
-
-
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -74,25 +66,33 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-<CENTER><H1><A NAME="Making_a_Strategic_Decision">Making a Strategic Decision</A></H1></CENTER>
+<CENTER><H1><A NAME="Before_you_dive_into_the_gory_de">Before you dive into the gory details</A></H1></CENTER>
<P>
-When running your scripts under mod_perl, you will notice that the httpd
-processes consume a huge amount of memory, from 5M to 25M and more. That is
-the price you pay for the great speed improvements under mod_perl -- the
-function of Perl embedded in the Apache server binary.
+There are many implementation schemes, each one has its benefits and
+drawbacks. Please take your time to read the <A HREF="././strategy.html#">Picking the Right Strategy</A> chapter before you proceed. This section
+<EM>merely</EM> details the implementation, installation and configuration. It hardly
+mentions the pros and cons of each scheme detailed here.
<P>
-It is overkill to serve the static objects like images and html docs with
-these larger processes. The best approach is to run two servers: a light
-Apache server with no mod_perl compiled in serving the static pages, and a
-heavy Apache/mod_perl server serving the CGIs in mod_perl mode only. This
-section describes a real world example ready for copy and paste to start
-with. You will probably will want to change the base directories, but
+This section describes a real world scenarios ready for almost blindly copy
+and paste, you may think of it as a kick start. You will probably will want
+to change the directories and some parameters like your hostname, but
basically you can use it as it is.
<P>
+<STRONG>Important:</STRONG> Since both apache and mod_perl tend to release new versions so often (which
+is good :), I will be not able to update the version numbers I present
+here. So make sure to work with the latest version, even if you see me
+using some older one. I prefer to use the real version number instead of <CODE>x.xx.xx</CODE>.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl enabled Apache Servers</A></H1></CENTER>
+<P>
Since we run two apache servers we will need two different configuration
files, log files and etc. We need a special directory layout. While some of
the directories can be shared between the two servers (assuming that both
@@ -101,185 +101,195 @@
(Apache/mod_perl).
<P>
-Of course there are more ways to use mod_perl. Please read <A HREF="././scenario.html#More_mod_perl_deploying_schemas">More mod_perl deploying schemas</A>.
+For this illustration, we will use <CODE>/usr/local</CODE> as our <EM>root</EM>
+directory. The Apache installation directories will be stored under this
+root (<CODE>/usr/local/bin</CODE>, <CODE>/usr/local/etc</CODE> and etc...)
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Deciding_on_a_Directory_Layout">Deciding on a Directory Layout</A></H1></CENTER>
-<P>
-For this illustration, we will use <CODE>/usr/apps</CODE> as our <STRONG>root</STRONG> directory. The Apache installation directories will be stored under this
-root (<CODE>/usr/apps/bin</CODE>, <CODE>/usr/apps/etc</CODE> and etc...)
+First let's prepare the sources. We will assume that all the sources go
+into <CODE>/usr/src</CODE> dir. It is better when you use two separate copies of apache sources. Since
+you probably will want to tune each apache version at separate and to do
+some modifications and recompilations as the time goes. Having two
+independent source trees will prove helpful, unless you use <CODE>DSO</CODE>, which is covered in this section.
<P>
-First let's prepare the sources. We will assume that all the sources go to
-/usr/apps/usr/src dir. First let's make two subdirectories:
+Make two subdirectories:
<P>
-<PRE> % mkdir /usr/apps/usr/src/httpd_docs
- % mkdir /usr/apps/usr/src/httpd_perl
+<PRE> % mkdir /usr/src/httpd_docs
+ % mkdir /usr/src/httpd_perl
</PRE>
<P>
-Now we will put the Apache source into <CODE>/usr/apps/usr/src/httpd_docs</CODE>:
+Now we will put the Apache source into <CODE>/usr/src/httpd_docs</CODE>:
<P>
-<PRE> % cd /usr/apps/usr/src/httpd_docs
- % gzip -dc /path/to/tarfile/apache.tar.gz | tar xvf -
+<PRE> % cd /usr/src/httpd_docs
+ % gzip -dc /path/to/tarfile/apache.tar.gz | tar xvf -
</PRE>
<P>
-(Replace '<CODE>/path/to/tarfile</CODE>' with the location where you've downloaded the file in all examples.)
-Let's check:
+If you have a gnu tar:
<P>
-<PRE> % ls -l
- drwxr-xr-x 8 stas stas 2048 Oct 29 17:38 apache_1.3.2/
+<PRE> % tar xvzf /path/to/apache.tar.gz
</PRE>
<P>
-Now we will prepare the httpd_perl server sources:
+Replace everywhere <CODE>/path/to/tarfile</CODE> with a path to a downloaded file.
<P>
-<PRE> % cd /usr/apps/usr/src/httpd_perl
- % gzip -dc /path/to/tarfile/apache.tar.gz | tar xvf -
- % gzip -dc /path/to/tarfile/modperl.tar.gz | tar xvf -
+<PRE> % cd /usr/src/httpd_docs
+ % ls -l
+ drwxr-xr-x 8 stas stas 2048 Apr 29 17:38 apache_1.3.6/
</PRE>
<P>
-Let's check:
+Now we will prepare the <CODE>httpd_perl</CODE> server sources:
<P>
-<PRE> % ls -l
- drwxr-xr-x 8 stas stas 2048 Oct 29 17:38 apache_1.3.2/
- drwxr-xr-x 8 stas stas 2048 Oct 29 17:38 modperl-1.16/
+<PRE> % cd /usr/src/httpd_perl
+ % gzip -dc /path/to/apache.tar.gz | tar xvf -
+ % gzip -dc /path/to/modperl.tar.gz | tar xvf -
+ % ls -l
+ drwxr-xr-x 8 stas stas 2048 Apr 29 17:38 apache_1.3.6/
+ drwxr-xr-x 8 stas stas 2048 Apr 29 17:38 modperl-1.19/
</PRE>
<P>
Time to decide on the desired directory structure layout (where the apache
files go):
<P>
-<PRE> ROOT = /usr/apps
+<PRE> ROOT = /usr/local
</PRE>
<P>
The two servers can share the following directories (so we will not
duplicate data):
<P>
-<PRE> /usr/apps/bin/
- /usr/apps/lib
- /usr/apps/include/
- /usr/apps/man/
- /usr/apps/share/
+<PRE> /usr/local/bin/
+ /usr/local/lib
+ /usr/local/include/
+ /usr/local/man/
+ /usr/local/share/
</PRE>
<P>
<STRONG>Important:</STRONG> we assume that both servers are built from the same Apache source version.
<P>
-Servers store their specific files either in httpd_docs or httpd_perl:
+Servers store their specific files either in <CODE>httpd_docs</CODE> or
+<CODE>httpd_perl</CODE> sub-directories:
<P>
-<PRE> /usr/apps/etc/httpd_docs/
- httpd_perl/
-
- /usr/apps/sbin/httpd_docs/
- httpd_perl/
+<PRE> /usr/local/etc/httpd_docs/
+ httpd_perl/
- /usr/apps/var/httpd_docs/logs/
- proxy/
- run/
- httpd_perl/logs/
- proxy/
- run/
+ /usr/local/sbin/httpd_docs/
+ httpd_perl/
+
+ /usr/local/var/httpd_docs/logs/
+ proxy/
+ run/
+ httpd_perl/logs/
+ proxy/
+ run/
</PRE>
<P>
After you will complete the compilation and installation of the both
servers, you will have to configure them. To make things clear before we
proceed into details, you should configure the
-<CODE>/usr/apps/etc/httpd_docs/httpd.conf</CODE> as a plain apache (something that is not covered here, but which is very
-simple) and <CODE>Port</CODE>
+<CODE>/usr/local/etc/httpd_docs/httpd.conf</CODE> as a plain apache and <CODE>Port</CODE>
directive to be 80 for example. And
-<CODE>/usr/apps/etc/httpd_perl/httpd.conf</CODE> to configure for mod_perl server (which is covered in <A HREF="././config.html#">Server Configuration</A> section) and of course whose <CODE>Port</CODE> should be different then the one
-<CODE>httpd_docs</CODE> server listens to (e.g. 8080). I will discuss the port numbers issue later.
+<CODE>/usr/local/etc/httpd_perl/httpd.conf</CODE> to configure for mod_perl server and of course whose <CODE>Port</CODE> should be different then the one
+<CODE>httpd_docs</CODE> server listens to (e.g. 8080). The port numbers issue will be discussed
+later.
<P>
The next step is to configure and compile the sources: Below are the
-procedures to compile both servers taking into account the above directory
-layout:
+procedures to compile both servers taking into account the directory layout
+we have just decided to use.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A></H1></CENTER>
+<CENTER><H2><A NAME="Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A></H2></CENTER>
<P>
Important note: In the installation scenario I have used apache and
mod_perl release numbers. As you understand I would not change these
numbers every time a new version of either apache or mod_perl will be
-released. So please if you see <CODE>apache_1.3.2</CODE> it does not mean
-<CODE>1.3.2</CODE> is the latest apache version. Thank you!
+released. So please if you see <CODE>apache_1.3.6</CODE> it does not mean
+<CODE>1.3.6</CODE> is the latest apache version.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="httpd_docs_Server">httpd_docs Server</A></H2></CENTER>
+<CENTER><H3><A NAME="Building_the_httpd_docs_Server">Building the httpd_docs Server</A></H3></CENTER>
<DL>
-<P><DT><STRONG><A NAME="item_Configuration">Configuration</A></STRONG><DD>
+<P><DT><STRONG><A NAME="item_Sources">Sources Configuration</A></STRONG><DD>
<P>
-<PRE> % cd /usr/apps/usr/src/httpd_docs/apache_1.3.2
-
- % make clean
-
- # gcc - compiles httpd by 100K+ smaller then cc on AIX!
-
- % env CC=gcc \
- ./configure --prefix=/usr/apps \
- --sbindir=/usr/apps/sbin/httpd_docs \
- --sysconfdir=/usr/apps/etc/httpd_docs \
- --localstatedir=/usr/apps/var/httpd_docs \
- --runtimedir=/usr/apps/var/httpd_docs/run \
- --logfiledir=/usr/apps/var/httpd_docs/logs \
- --proxycachedir=/usr/apps/var/httpd_docs/proxy \
- --enable-module=include --enable-module=rewrite
+<PRE> % cd /usr/src/httpd_docs/apache_1.3.6
+ % make clean
+ % env CC=gcc \
+ ./configure --prefix=/usr/local \
+ --sbindir=/usr/local/sbin/httpd_docs \
+ --sysconfdir=/usr/local/etc/httpd_docs \
+ --localstatedir=/usr/local/var/httpd_docs \
+ --runtimedir=/usr/local/var/httpd_docs/run \
+ --logfiledir=/usr/local/var/httpd_docs/logs \
+ --proxycachedir=/usr/local/var/httpd_docs/proxy
</PRE>
<P>
-Note: add --layout to see the resulting directories' layout without
-actually making the configuration.
+If you need some other modules, like mod_rewrite and mod_include (SSI), add
+them here as well:
-<P><DT><STRONG><A NAME="item_Compilation">Compilation:</A></STRONG><DD>
<P>
-<PRE> % make
-
- % make install
+<PRE> --enable-module=include --enable-module=rewrite
+</PRE>
+<P>
+Note: gcc - compiles httpd by 100K+ smaller then cc on AIX, remove the
+<CODE>env CC=gcc</CODE> if you want to use the default compiler.
+
+<P>
+Note: add <CODE>--layout</CODE> to see the resulting directories' layout without actually making the
+configuration.
+
+<P><DT><STRONG>Sources Compilation:</STRONG><DD>
+<P>
+<PRE> % make
+ % make install
</PRE>
<P>
-Rename 'httpd' to 'http_docs'
+Rename <CODE>httpd</CODE> to <CODE>http_docs</CODE>
+
+
<P>
-<PRE> % mv /usr/apps/sbin/httpd_docs/httpd /usr/apps/sbin/httpd_docs/httpd_docs
+<PRE> % mv /usr/local/sbin/httpd_docs/httpd \
+ /usr/local/sbin/httpd_docs/httpd_docs
</PRE>
<P>
-Now update the apachectl utility to point to the new httpd name (via your
-favorite text editor or by using perl)
+Now update an <STRONG>apachectl</STRONG> utility to point to the renamed httpd via your favorite text editor or by
+using perl:
<P>
-<PRE> % perl -p -i -e 's|httpd_docs/httpd|httpd_docs/httpd_docs|' \
- /usr/apps/sbin/httpd_docs/apachectl
+<PRE> % perl -p -i -e 's|httpd_docs/httpd|httpd_docs/httpd_docs|' \
+ /usr/local/sbin/httpd_docs/apachectl
</PRE>
</DL>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="httpd_perl_Server_mod_perl_">httpd_perl Server (mod_perl):</A></H2></CENTER>
+<CENTER><H3><A NAME="Building_the_httpd_perl_Server_">Building the httpd_perl Server (mod_perl):</A></H3></CENTER>
<P>
Before you start to configure the mod_perl sources, you should be aware
that there are a few Perl modules that have to be installed before building
mod_perl. You will be alerted if any required modules are missing when you
-run the <CODE>perl Makefile.PL</CODE> command line below. If you discover that you do not have these, go to your
-nearest CPAN repository (if you do not know what is it, go to <A
-HREF="http://www.perl.com/CPAN">http://www.perl.com/CPAN</A> ) or run the
-CPAN interactive shell via the command line <CODE>perl -MCPAN -e
-shell</CODE> .
+run the <CODE>perl Makefile.PL</CODE> command line below. If you discover that some are missing, pick them from
+your nearest CPAN repository (if you do not know what is it, make a visit
+to <A HREF="http://www.perl.com/CPAN">http://www.perl.com/CPAN</A> ) or run
+the <CODE>CPAN</CODE> interactive shell via the command line <CODE>perl -MCPAN -e shell</CODE>.
<P>
-Now back to installation.
+Make sure the sources are clean:
<P>
-<PRE> % cd /usr/apps/usr/src/httpd_perl/apache_1.3.2
- % make clean
- % cd /usr/apps/usr/src/httpd_perl/mod_perl-1.16
- % make clean
+<PRE> % cd /usr/src/httpd_perl/apache_1.3.6
+ % make clean
+ % cd /usr/src/httpd_perl/mod_perl-1.19
+ % make clean
</PRE>
<P>
It is important to <STRONG>make clean</STRONG> since some of the versions are not binary compatible (e.g apache 1.3.3 vs
@@ -287,44 +297,54 @@
1.3.4 header files.
<P>
-Here I did not find a way to compile with gcc (but perl was compiled with
-cc so we have to compile with the same compiler!!!
+Here I did not find a way to compile with gcc (my perl was compiled with cc
+so we have to compile with the same compiler!!!
<P>
-Notice that <STRONG>ALL</STRONG> <CODE>APACI_ARGS</CODE> (below) must be passed as one long line!!!
+Notice that <STRONG>ALL</STRONG> <CODE>APACI_ARGS</CODE> (below) must be passed as one long line!!! I have wrapped them to allow
+easier reading.
+<P>
+<PRE> % cd /usr/src/httpd_perl/mod_perl-1.19
+</PRE>
<P>
-<PRE> % cd /usr/apps/usr/src/httpd_perl/mod_perl-1.16
+<PRE> % /usr/local/bin/perl Makefile.PL \
+ APACHE_PREFIX=/usr/local/ \
+ APACHE_SRC=../apache_1.3.6/src \
+ DO_HTTPD=1 \
+ USE_APACI=1 \
+ PERL_MARK_WHERE=1 \
+ PERL_STACKED_HANDLERS=1 \
+ ALL_HOOKS=1 \
+ APACI_ARGS=--sbindir=/usr/local/sbin/httpd_perl,
+ --sysconfdir=/usr/local/etc/httpd_perl,
+ --localstatedir=/usr/local/var/httpd_perl,
+ --runtimedir=/usr/local/var/httpd_perl/run,
+ --logfiledir=/usr/local/var/httpd_perl/logs,
+ --proxycachedir=/usr/local/var/httpd_perl/proxy
</PRE>
+<P>
+As with <CODE>httpd_docs</CODE> you might need other modules like
+<CODE>mod_rewrite</CODE>, so add them here:
+
<P>
-<PRE> % /usr/apps/bin/perl Makefile.PL \
- APACHE_PREFIX=/usr/apps/ \
- APACHE_SRC=../apache_1.3.2/src \
- DO_HTTPD=1 \
- USE_APACI=1 \
- PERL_MARK_WHERE=1 \
- PERL_STACKED_HANDLERS=1 \
- ALL_HOOKS=1 \
- APACI_ARGS=--sbindir=/usr/apps/sbin/httpd_perl,
- --sysconfdir=/usr/apps/etc/httpd_perl,
- --localstatedir=/usr/apps/var/httpd_perl,
- --runtimedir=/usr/apps/var/httpd_perl/run,
- --logfiledir=/usr/apps/var/httpd_perl/logs,
- --proxycachedir=/usr/apps/var/httpd_perl/proxy,
- --enable-module=rewrite
+<PRE> --enable-module=rewrite
</PRE>
<P>
-Notes: <CODE>-DPERL_STACKED_HANDLERS</CODE> needed for <CODE>Apache::DBI</CODE>
+Note: <CODE>PERL_STACKED_HANDLERS=1</CODE> is needed for <CODE>Apache::DBI</CODE>
<P>
-<PRE> % make && make test && make install
+Now, build, test and install the <CODE>httpd_perl</CODE>.
+
+<P>
+<PRE> % make && make test && make install
</PRE>
<P>
-Note: Apache puts a stripped version of httpd at
-/usr/apps/sbin/httpd_perl/httpd the original version sits at
-/usr/apps/usr/src/httpd_perl/apache_1.3.2/src/httpd
+Note: Apache puts a stripped version of <CODE>httpd</CODE> at
+<CODE>/usr/local/sbin/httpd_perl/httpd</CODE>. The original version including debugging symbols (if you need to run a
+debugger on this executable) is located at <CODE>/usr/src/httpd_perl/apache_1.3.6/src/httpd</CODE>.
<P>
Note: You may have noted that we did not go to the apache's source dir and
@@ -335,249 +355,151 @@
the configuration, log and document trees.
<P>
-If make test fails, look into t/logs and see what is in there. Also see <A HREF="././scenario.html#make_test_fails">make test fails</A>.
+If <CODE>make test</CODE> fails, look into <CODE>t/logs</CODE> and see what is in there. Also see <A HREF="././install.html#make_test_fails">make test fails</A>.
<P>
While doing <CODE>perl Makefile.PL ...</CODE> mod_perl might complain by warning you about missing <CODE>libgdbm</CODE>. Users reported that it is actually crucial, and you must have it in order
-to successfully complete the mod_perl build process.
+to successfully complete the mod_perl building process.
<P>
-Rename the 'httpd' to 'httpd_perl'
+Now rename the <CODE>httpd</CODE> to <CODE>httpd_perl</CODE>:
<P>
-<PRE> % mv /usr/apps/sbin/httpd_perl/httpd \
- /usr/apps/sbin/httpd_perl/httpd_perl
+<PRE> % mv /usr/local/sbin/httpd_perl/httpd \
+ /usr/local/sbin/httpd_perl/httpd_perl
</PRE>
<P>
-Now update the apachectl utility to point to a new httpd name (by hand or
-by using perl)
+Update the apachectl utility to point to renamed httpd name:
<P>
-<PRE> % perl -p -i -e 's|httpd_perl/httpd|httpd_perl/httpd_perl|' \
- /usr/apps/sbin/httpd_perl/apachectl
+<PRE> % perl -p -i -e 's|httpd_perl/httpd|httpd_perl/httpd_perl|' \
+ /usr/local/sbin/httpd_perl/apachectl
</PRE>
<P>
-Now proceed to the <A HREF="././config.html#">Server Configuration</A> section.
-
-<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Publishing_port_numbers_differen">Publishing port numbers different from 80</A></H2></CENTER>
+<CENTER><H2><A NAME="Configuration_of_the_servers">Configuration of the servers</A></H2></CENTER>
<P>
-It is advised not to publish the 8080 (or alike) port number in URLs, but
-rather using a proxying rewrite rule in the thin (httpd_docs) server:
+Now when we have completed the building process, the last stage before
+running the servers, is to configure them.
<P>
-<PRE> RewriteRule .*/perl/(.*) <A HREF="http://my.url:8080/perl/">http://my.url:8080/perl/</A>$1 [P]
-</PRE>
-<P>
-One problem with publishing 8080 port numbers is that I was told that IE
-4.x has a bug when re-posting data to a non-port-80 url. It drops the port
-designator, and uses port 80 anyway.
-
-<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="More_mod_perl_deploying_schemas">More mod_perl deploying schemas</A></H1></CENTER>
-<P>
-There are several different ways to build, configure and deploy your
-mod_perl enabled site. Some of the ways are:
-
-<OL>
-<P><LI>
-<P>
-1 binary and 1 config file (suffer a big binary for all kind of objects)
-
-<P><LI>
-<P>
-2 binaries and 2 config files (one big binary for mod_perl and one small
-for static object like images)
-
-<P><LI>
-<P>
-1 DSO style compile and 2 configs (Dynamic linking lets you compile once
-and have a big and a small binary in memory BUT you have to deal with a
-freshly made solution that has week documentation and is still subject to
-change and is rather more complex)
-
-<P><LI>
-<P>
-Any of the 3 approaches above plus proxy server in the http accelerator
-mode (squid was reported to be the best as of this writing).
-
-</OL>
-<P>
-If you are a newbie, I would recommend you to start with the first option
-and work on getting your feet wet with apache and mod_perl, then decide
-whether to move to a second one for production work or move up to the more
-state-of-the-art-yet-suspiciously-new DSO system (third) )or/and proven to
-be good forth option from above.
-
-<P>
-Option 1 will kill you in production if you load out a lot of static data
-with a 2-12 MB webserver process. On the other hand while testing you will
-have no other server interaction to mask or add to your errors.
-
-<P>
-Option 2 means keeping two compiles but lets you seriously tune the two
-binaries to their exact purpose. On the other hand you have to deal with
-proxying or fancy site design to keep the two servers in step. Choose
-serving on multiple ports, multiple IPs, etc...
-
+<CENTER><H3><A NAME="Basic_httpd_docs_Server_s_Config">Basic httpd_docs Server's Configuration</A></H3></CENTER>
<P>
-Option 3 (DSO) -- as mentioned above -- means playing with the bleeding
-edge. Also the <CODE>mod_so</CODE> adds size and complexity to your binaries. The benefit being that modules
-can be added and removed with out recompiling and even shared amongst
-multiple servers. Again, it is bleeding edge and still sort of platform
-wonky so YMMV. See
-<A HREF="././scenario.html#mod_perl_as_DSO">mod_perl as DSO</A>
+Configuring of <CODE>httpd_docs</CODE> server is a very easy task. Open
+<CODE>/usr/local/etc/httpd_docs/httpd.conf</CODE> into your favorite editor (starting from version 1.3.4 of Apache - there is
+only one file to edit). And configure it as you always do. Make sure you
+configure the log files and other pathes according to the directory layout
+we decided to use.
-
-
<P>
-Option 4 (proxy in http accelerator mode) - should make you lots of good
-things, once correctly configured and tuned. Stay tuned for more
-information.
+Start the server with:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="mod_perl_and_proxy_server">mod_perl and proxy server</A></H1></CENTER>
+<PRE> /usr/local/sbin/httpd_docs/apachectl start
+</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Incentives">Incentives</A></H2></CENTER>
+<CENTER><H3><A NAME="Basic_httpd_perl_Server_s_Config">Basic httpd_perl Server's Configuration</A></H3></CENTER>
<P>
-At the beginning there were 2 apache servers: one - plain apache server,
-which was _very_ light, and configured to serve static objects, the other -
-mod_perl enabled, which was _very_ heavy and aimed to serve mod_perl
-scripts. We named them: httpd_docs and httpd_perl appropriately. The two
-servers coexisted at the same <CODE>IP(DNS)</CODE> by listening to
-different ports: 80 - for httpd_docs (e.g. <A
-HREF="http://www.nowhere.com/images/test.gif">http://www.nowhere.com/images/test.gif</A>
-) and 8080 for httpd_perl (e.g. <A
-HREF="http://www.nowhere.com:8080/perl/test.pl">http://www.nowhere.com:8080/perl/test.pl</A>
-). Note that I did not write <A
-HREF="http://www.nowhere.com:80">http://www.nowhere.com:80</A> for the
-first example, since port 80 is a default http port. (Note that later on, I
-will be moving the httpd_docs server to port 81.)
+Here we will make a basic configuration of the <CODE>httpd_perl</CODE> server. We edit the <CODE>/usr/local/etc/httpd_perl/httpd.conf</CODE> file. As with
+<CODE>httpd_docs</CODE> server configuration, make sure that log and other files directives are set
+to point to the right places, according to the chosen directory layout.
<P>
-Now I am going to convince you that you _want_ to use a proxy server (in
-the http accelerator mode). The reasons are:
+One first thing to do is to set a <CODE>Port</CODE> directive - it should be different from <CODE>80</CODE> since we cannot bind 2 servers to use the same port number on the same
+machine. Here we will use <8080>. Some developers use port <CODE>81</CODE>, but you can bind to it, only if you have root permissions. If you are
+running on multiuser machine, there is a chance someone already uses that
+port, or will start using it in the future - which as you understand might
+cause a collision. If you are the only user on your machine, basically you
+can pick any not used port number. Port number choosing is a controversial
+topic, for many organizations use firewalls, which may block some of the
+ports, or enable only a known ones. From my experience the most used port
+numbers are: <CODE>80</CODE>, <CODE>81</CODE>, <CODE>8000</CODE> and <CODE>8080</CODE>. Personally, I prefer the port <CODE>8080</CODE>. Of course with 2 server scenario you can hide the nonstandard port number
+from users, by either using the mod_proxy's
+<CODE>ProxyPass</CODE> or proxy server like squid.
-<UL>
-<P><LI>
<P>
-Allow serving of static objects from the proxy's cache (objects that
-previously were entirely served by the httpd_docs server).
+For more details see <A HREF="././config.html#Publishing_port_numbers_differen">Publishing port numbers different from 80 </A>, <A HREF="././scenario.html#Running_1_webserver_and_squid_in">Running 1 webserver and squid in httpd accelerator mode</A>,
+<A HREF="././scenario.html#Running_2_webservers_and_squid_i">Running 2 webservers and squid in httpd accelerator mode</A>
+and <A HREF="././scenario.html#Using_mod_proxy">Using mod_proxy</A>.
<P>
-You get less I/O activity to read the object from the disk (proxy serves
-the most ``popular'' objects from the RAM memory - of course you benefit
-more if you allow the proxy server to consume more RAM). Since you do not
-wait for the I/O to be completed you serve the static objects faster. (I/O
-+1 points, faster static object serving +1 point)
+Now we proceed to mod_perl specific directives. A good idea will be to add
+them all at the end of the <CODE>httpd.conf</CODE>, since you are going to fiddle a lot of them.
-<P><LI>
<P>
-The proxy server acts as a sort of output buffer for the dynamic content.
-The mod_perl server sends the entire response to the proxy and is then free
-to deal with other requests. The proxy server is responsible for getting
-the response to the browser. So if the transfer is over a slow link, the
-mod_perl server is not waiting around for the data to move.
+First, you need to specify the location where all mod_perl scripts will be
+located.
<P>
-Using numbers is always more convincing :) Let's take a user connected to
-your site with 28.8 kbps (bps == bits/sec) modem. It means that a speed of
-user's link is 28.8/8 = 3.6 kbytes/sec. I assume an average generated HTML
-page to be of 10kb (kb == kilobytes) and pretty average script that
-generates this output in 0.5 secs. How much time the server will wait
-before user will get the whole output down his way? A simple calculation
-reveals pretty scaring numbers - it will have to wait for another 6 secs
-(20kb/3.6kb), when it could serve another 12 (6/0.5) requests at the time
-it was stalled. This very simple example shows us that we need 12 times
-less children running, which means you will need 12 fold times less memory
-(which is not quite true because some parts of the code are being shared).
-But you know that nowadays scripts return pages which sometimes are being
-blown up with javascript code and similar, which makes them of 100kb size
-and download time to be of... (This calculation was left to the reader as
-an exercise :)
+Add the following configuration directive:
<P>
-To make your numbers of download time even worse let me remind you that
-many users like to open many browser windows and do many things at once
-(download files and visit _heavy_ sites). So the speed of 3.6kb/sec I was
-talking about before, many times 5-10 times smaller.
-
+<PRE> # mod_perl scripts will be called from
+ Alias /perl/ /usr/local/myproject/perl/
+</PRE>
<P>
-(+3 point for memory cut up, I give it 3 times more points for the savings
-we get with this most important functionality)
+From now on, all requests starting with <CODE>/perl</CODE> will be executed under <CODE>mod_perl</CODE> and will be mapped to the files in
+<CODE>/usr/local/myproject/perl/</CODE>.
-<P><LI>
<P>
-Also we are going to hide the details of the server's implementation. Users
-will never see ports in the URLs (more on that topic later). And you can
-have a few boxes serving the requests, and only one serves as a front end,
-which spreads the jobs between the servers in a way you configured it too.
-So you can actually put down one server down for upgrade, but end user will
-never notice that because the front end server will dispatch the jobs to
-other servers. (of course this is pretty big topic, and it would not be
-included in the scope of this document)
+Now we should configure the <CODE>/perl</CODE> location.
<P>
-(+1 point for flexibility to change things at the background and making
-user to bookmark only one URL)
-
-<P><LI>
+<PRE> PerlModule Apache::Registry
+</PRE>
+<P>
+<PRE> <Location /perl>
+ #AllowOverride None
+ SetHandler perl-script
+ PerlHandler Apache::Registry
+ Options ExecCGI
+ allow from all
+ PerlSendHeader On
+ </Location>
+</PRE>
<P>
-Of course there are drawbacks. Luckily, these are not functionality
-drawbacks, but more of administration hassle. Yes, you add another program
-to worry about, while proxies are generally stable you have to make sure to
-prepare proper startup and shutdown scripts, which are being run at the
-boot and reboot appropriately. May be a watchdog script running at the
-crontab.
+This configuration causes all scripts that are called with a <STRONG>/perl</STRONG>
+path prefix to be executed under the <STRONG>Apache::Registry</STRONG> module and as a CGI (so the <STRONG>ExecCGI</STRONG>, if you omit this option the script will be printed to the caller's
+browser as a plain text or will possibly will trigger a 'Save-As' window). <STRONG>Apache::Registry</STRONG> module lets you run almost unaltered CGI/perl scripts under <CODE>mod_perl</CODE>. <CODE>PerlModule</CODE>
+directive is an equivalent of perl's <CODE>require()</CODE>. We load the
+<STRONG>Apache::Registry</STRONG> module before we use it in the <CODE>PerlHandler</CODE> in the <CODE>Location</CODE> configuration.
<P>
-Proxy servers can be configured to be light or heavy, admin must decide
-what gives the highest performance for his application. Proxy server like
-squid is light in the concept of having only one process serving all
-requests. But it can appear pretty heavy when it loads objects into memory
-for faster serving.
+<STRONG>PerlSendHeader On</STRONG> tells the server to send an HTTP header to the browser on every script
+invocation. You will want to turn this off for nph (non-parsed-headers)
+scripts.
<P>
-(-1 point for administration overhead, very small but overhead. -1 point
-for memory consuming)
+This is only a very basic configuration. <A HREF="././config.html#">Server Configuration</A> section covers the rest of the details.
-</UL>
<P>
-So let's sum up the points. We have 4 (6-2) points for the proxy server and
-I believe I have succeeded to convince you, that you want it :)
+Start the server with:
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Squid_proxy_server_in_httpd_acce">Squid proxy server in httpd accelerator mode</A></H2></CENTER>
+<PRE> /usr/local/sbin/httpd_perl/apachectl start
+</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="Running_a_squid_and_2_webservers">Running a squid and 2 webservers scenario</A></H3></CENTER>
+<CENTER><H1><A NAME="Running_2_webservers_and_squid_i">Running 2 webservers and squid in httpd accelerator mode</A></H1></CENTER>
<P>
-OK, Now when you are convinced that you must have a proxy server, let's
-proceed. As many people suggested using the squid server as the best, we
-will go for it. While I have detailed the mod_perl server installation, you
-are on your own with installing the squid server. I run linux, so I have
-got the rpm package, installed it, configured the
-<CODE>/etc/squid/squid.conf</CODE>, fired off the server and was all set. Basically once you have the squid
-installed, you just need to modify the default <CODE>squid.conf</CODE> the way I will explain below and you are done.
+While I have detailed the mod_perl server installation, you are on your own
+with installing the squid server (See <A HREF="././help.html#">Getting Helped</A> for more details). I run linux, so I have got the rpm package, installed
+it, configured the <CODE>/etc/squid/squid.conf</CODE>, fired off the server and was all set. Basically once you have the squid
+installed, you just need to modify the default <CODE>squid.conf</CODE> the way I will explain below, then you are ready to run the server.
<P>
First, lets understand what do we have in hands and what do we want from
-squid. We have an httpd_docs and httpd_perl servers listening on ports 81
-and 8080 accordingly (we have to move the httpd_docs server to port 81,
-since port 80 will be taken over by squid). Both reside on the same machine
-as squid. We want squid to listen on port 80, forward a single static
-object request to the port httpd_docs server listens to, and dynamic
-request to httpd_perl's port. Both servers return the data to the proxy
-server (unless it is already cached in the squid), so user never sees the
-ports and never knows that there might be more then one server running.
-Proxy server makes all the magic behind it transparent to user. Do not
-confuse it with
-<STRONG>mod_rewrite</STRONG>, where a server redirects the request somewhere according to the rules and
+squid. We have an <CODE>httpd_docs</CODE> and <CODE>httpd_perl</CODE> servers listening on ports 81 and 8080 accordingly (we have to move the
+httpd_docs server to port 81, since port 80 will be taken over by squid).
+Both reside on the same machine as squid. We want squid to listen on port
+80, forward a single static object request to the port httpd_docs server
+listens to, and dynamic request to httpd_perl's port. Both servers return
+the data to the proxy server (unless it is already cached in the squid), so
+user never sees the ports and never knows that there might be more then one
+server running. Proxy server makes all the magic behind it transparent to
+user. Do not confuse it with <STRONG>mod_rewrite</STRONG>, where a server redirects the request somewhere according to the rules and
forgets about it. The described functionality is being known as <CODE>httpd accelerator mode</CODE> in proxy dialect.
<P>
@@ -669,9 +591,9 @@
<P>
Even if you insert user-ID and date in your page, caching can save
-resources when you set the expiration time to 1 second. A user might
-doubleclick where a single click would do, thus sending two requests in
-parallel, squid could serve the second.
+resources when you set the expiration time to 1 second. A user might double
+click where a single click would do, thus sending two requests in parallel,
+squid could serve the second.
<P>
But if you are lazy, or just have too many things to deal with, you can
@@ -770,11 +692,11 @@
$|=1;
while (<>) {
- # redirect to mod_perl server
+ # redirect to mod_perl server
print($_), next if
- s|<A HREF="http://127">http://127</A>\.0\.0\.1:81/perl|<A HREF="http://www.nowhere.com:8080/perl">http://www.nowhere.com:8080/perl</A>|o;
+ s|<A HREF="http://127">http://127</A>\.0\.0\.1:81/perl|<A HREF="http://www.nowhere.com:8080/perl">http://www.nowhere.com:8080/perl</A>|o;
- # default - static server
+ # default - static server
print;
}
</PRE>
@@ -844,7 +766,7 @@
I think that you must also have in the /etc/hosts an entry:
<P>
-<PRE> 127.0.0.1 localhost.localdomain localhost
+<PRE> 127.0.0.1 localhost.localdomain localhost
</PRE>
<P>
But generally it is always there in first place.
@@ -863,18 +785,22 @@
you have one, or to leave a note on your pages asking users to update their
bookmarks. You could avoid this problem if you did not publish this non-80
port. See
-<A HREF="#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>.
+<A HREF="././config.html#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>.
<P>
<META> Need to write up a section about server logging with squid.
-X-Forward-Host header. One thing I sure would like to know is how requests
-are logged with this setup. I have, as most everyone I imagine, log
-rotation, analysis, archiving scripts and they all assume a single log.
-Does one have different logs that have to be merged (up to 3 for each
-server + squid) ? Even when squid responds to a request out of its cache
-I'd still want the thing to be logged. </META>
+One thing I sure would like to know is how requests are logged with this
+setup. I have, as most everyone I imagine, log rotation, analysis,
+archiving scripts and they all assume a single log. Does one have different
+logs that have to be merged (up to 3 for each server + squid) ? Even when
+squid responds to a request out of its cache I'd still want the thing to be
+logged. </META>
<P>
+See <A HREF="././scenario.html#Using_mod_proxy">Using mod_proxy</A> for information about
+<CODE>X-Forwarded-For</CODE>.
+
+<P>
To save you keystrokes, here is the whole modified <CODE>squid.conf</CODE>:
<P>
@@ -927,7 +853,7 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H3><A NAME="Running_a_squid_and_1_mod_perl_a">Running a squid and 1 mod_perl apache server scenario</A></H3></CENTER>
+<CENTER><H1><A NAME="Running_1_webserver_and_squid_in">Running 1 webserver and squid in httpd accelerator mode</A></H1></CENTER>
<P>
When I was first told about the squid, I thought: ``Hey I can drop now the <CODE>httpd_docs</CODE> server and to have only squid and <CODE>httpd_perl</CODE>
servers``. Since all my static objects will be cached by squid, I do not
@@ -948,10 +874,10 @@
So I have decided to have even more administration overhead and to stick to
the squid, httpd_docs and httpd_perl scenario, where I can optimize and
fine tune everything. Of course this can be not your case. If you are
-feeling like that the scenario from the previous section is too complicated
-for you make it simpler. Have only one server with mod_perl built in and
-let the squid to do most of the job that plain light apache used to do. As
-I have explained in the last paragraph, you should pick this lighter setup
+feeling that the scenario from the previous section is too complicated for
+you, make it simpler. Have only one server with mod_perl built in and let
+the squid to do most of the job that plain light apache used to do. As I
+have explained in the last paragraph, you should pick this lighter setup
only if you can make squid cache most of your static objects. If it cannot,
your mod_perl server will do the work we do not want it to.
@@ -960,7 +886,7 @@
squid. Then use a similar configuration from the previous section, but now
httpd_docs is not there anymore. Also we do not need the redirector anymore
and we specify <CODE>httpd_accel_host</CODE> as a name of the server and not <CODE>virtual</CODE>. We also do not need to bind two servers on the same port anymore because
-we do not redirect anymore (do there is no need for <CODE>Bind</CODE> and <CODE>Listen</CODE> directives in the httpd.conf).
+we do not redirect anymore (There is no more need for <CODE>Bind</CODE> and <CODE>Listen</CODE> directives in the httpd.conf).
<P>
The modified configuration (see the explanations in the previous section):
@@ -1009,84 +935,75 @@
</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A></H1></CENTER>
+<CENTER><H1><A NAME="Using_mod_proxy">Using mod_proxy</A></H1></CENTER>
<P>
-Yes, no problem with that. Follow the instructions above and when you
-encounter APACI_ARGS use your home directory (or some other directory which
-you have write access to as a prefix, for example,
-<CODE>/home/stas/www</CODE>) and everything will be installed there. There is a chance that some perl
-libs will be not installed on your server by root and you will have to
-install these locally too. See the <A
-HREF="http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html#7">http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html#7</A>
-for more information on local perl installations.
+The server on port 80 answers html requests directly and proxies the
+modperl enabled directory like this:
<P>
-You will not be able to have the server listen to a port lower then 1024 if
-you are not starting it as <CODE>root</CODE>, so choose a port number above 1024. (I use 8080 in most cases). Note that
-you will have to use a URL like <CODE>http://www.you.com:8080</CODE> in that case, but that is not a problem since generally users do not
-directly access URLs to CGI scripts, but rather are directed to them from a
-link on a web page or as the '<CODE>ACTION</CODE>' of an HTML form, so they should not know at all that the port is
-different from the default port 80.
-
+<PRE> ProxyPass /modperl/ <A HREF="http://localhost:81/modperl/">http://localhost:81/modperl/</A>
+ ProxyPassReverse /modperl/ <A HREF="http://localhost:81/modperl/">http://localhost:81/modperl/</A>
+</PRE>
<P>
-If you want your Apache server to start automatically on system reboot, you
-will need to invoke the server startup script from somewhere within the
-init scripts on your host. (This is often somewhere under <CODE>/etc/rc.d</CODE>, but this path can vary depending upon the flavor of Unix you are using.)
+<CODE>PPR</CODE> is the saving grace here, that makes Apache a win for me over Squid. That
+cleans up redirects and stuff to remove the :81 from the URIs. Very nice.
<P>
-One more important thing to keep in mind is system resources. Mod_perl is
-memory hungry -- if you run a lot of mod_perl processes on that machine
-(and it's not your own host...), most likely the system administrator of
-the host will ask you to shutdown your mod_perl server, or to find another
-home for it. You have a few solutions:
+Ask Bjoern Hansen has written a <CODE>mod_proxy_add_forward.c</CODE> module for Apache, that sets the <CODE>X-Forwarded-For</CODE> field when doing a <CODE>ProxyPass</CODE>, similar to what Squid can do. His patch is at: <A
+HREF="http://modules.apache.org/search?id=124">http://modules.apache.org/search?id=124</A>
+or at <A
+HREF="ftp://ftp.netcetera.dk/pub/apache/">ftp://ftp.netcetera.dk/pub/apache/</A>
+. Basically, that module adds an extra HTTP header to proxying requests.
+You can access that header in the mod_perl-enabled server, and set the IP
+of the remote server. You won't need to compile anything into the back-end
+server, just put something like the following into your mod_perl handler:
<P>
-<STRONG>a</STRONG>. Reduce resource usage - see <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>
-
-
-
+<PRE> my $real_client;
+ if (defined($real_client = $::r->header_in('X-Forwarded-For'))) {
+ $::r->connection->remote_ip($real_client);
+ }
+</PRE>
<P>
-<STRONG>b</STRONG>. Ask your ISP if you can put a dedicated machine into their computer room
-and be root there.
+See how it works? From that point on, the remote IP address is correct.You
+should be able to access REMOTE_ADDR as usual.
<P>
-<STRONG>c</STRONG>. Look for another ISP with lots of resources or one that supports mod_perl
-(not likely)
+IF you are using Apache::{Registry,PerlRun} - do it like this:
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Is_it_possible_to_determine_whic">Is it possible to determine which options were given to modperl's Makefile.PL</A></H1></CENTER>
<P>
-It is possible to determine which options were given to modperl's
-<CODE>Makefile.PL</CODE> during the configuration stage, so to be used later in recreating the same
-build tree when rebuilding the server. This is relevant only if did not use
-the default config parameters and altered some of them during the
-configuration stage.
+in startup.pl:
<P>
-I was into this problem many times. I am going to build something by
-passing some non default parameters to the config script and then later
-when I need to rebuild the tool either to upgrade it or to make an
-identical copy at some other machine, I have found that I do not remember
-what parameters did I altered.
-
+<PRE> sub My::ProxyRemoteAddr ($) {
+ my $r = shift;
+
+ # we'll only look at the X-Forwarded-For header if the requests
+ # comes from our proxy at localhost
+ return OK unless ($r->connection->remote_ip eq "127.0.0.1");
+
+ my @ip = split(/,\s*/, $r->header_in('X-Forwarded-For'));
+ if (my $ip = pop(@ip)) {
+ $r->connection->remote_ip($ip);
+ }
+
+ return OK;
+ }
+</PRE>
<P>
-The best solution for this problem is to prepare the run file with all the
-parameters that are about to be used and then run it instead of typing it
-all by hand. So later I will have the script handy to be reused.
+And in <CODE>httpd.conf</CODE>:
<P>
-mod_perl suggests using the <CODE>makepl_args.mod_perl</CODE> file which comes with mod_perl distribution. This is the file you specify
-all the parameters you are going to use.
-
+<PRE> PerlPostReadRequestHandler My::ProxyRemoteAddr
+</PRE>
<P>
-But if you have found yourself with a compiled tool and no traces of the
-specified parameters left, you can still find them out if the sources were
-not <CODE>make clean</CODE>'d. So you will find the apache specific parameters in <CODE>apache_x.x.x/config.status</CODE> and modperl's at in <CODE>mod_perl_x.xx/apaci/mod_perl.config</CODE>.
+You could do the same thing with other environment variables (though I
+think several of them are preserved, you will want to run some tests to see
+which ones).
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="mod_perl_as_DSO">mod_perl as DSO</A></H1></CENTER>
+<CENTER><H1><A NAME="mod_perl_server_as_DSO">mod_perl server as DSO</A></H1></CENTER>
<P>
To build the mod_perl as DSO add <CODE>USE_DSO=1</CODE> to the rest of configuration parameters, like:
@@ -1102,40 +1019,7 @@
<P>
<META> Incomplete </META>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Installation_problems">Installation problems</A></H1></CENTER>
-<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="make_test_fails">make test fails</A></H2></CENTER>
-<P>
-There are two configuration parameters <CODE>PREP_HTTPD</CODE> and <CODE>DO_HTTPD</CODE>
-you can use in <CODE>perl Makefile.PL [options]</CODE>.
-
-<P>
-<CODE>DO_HTTPD=1</CODE> means default to 'y' for the two prompts (which source tree to configure
-against and to build the httpd in that tree).
-<CODE>PREP_HTTPD=1</CODE> just means default 'n' to the second prompt, meaning, do not build httpd
-(make) in the Apache source tree.
-
-<P>
-In other words if you use <CODE>PREP_HTTPD=1</CODE> the httpd will be not build. It will be build only if you use <CODE>DO_HTTPD=1</CODE> option and not use
-<CODE>PREP_HTTPD=1</CODE>.
-
-<P>
-If you did not build the httpd, chdir to the apache source, and execute:
-
-<P>
-<PRE> make
-</PRE>
-<P>
-Then return to the mod_perl source and run:
-
-<P>
-<PRE> make test
- make install
-</PRE>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -1144,7 +1028,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="strategy.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="install.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -1156,8 +1041,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
1.11 +16 -12 modperl-site/guide/snippets.html
Index: snippets.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/snippets.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- snippets.html 1999/04/19 19:53:43 1.10
+++ snippets.html 1999/05/08 17:46:33 1.11
@@ -4,8 +4,11 @@
<TITLE>mod_perl guide: Code Snippets</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,14 +19,14 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Code Snippets</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="perl.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="help.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Sending_MIME_headers">Sending MIME headers</A>
@@ -34,11 +37,9 @@
<LI><A HREF="#Handling_cookies">Handling cookies</A>
</UL>
<!-- INDEX END -->
-
+<HR>
- <P><A HREF="index.html">[Back to the main index]</A></P>
-
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -47,7 +48,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Sending_MIME_headers">Sending MIME headers</A></H1></CENTER>
<P>
@@ -255,7 +258,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="perl.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="help.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -267,8 +271,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 04/19/1999
</FONT>
</B>
</TD>
1.12 +89 -313 modperl-site/guide/start.html
Index: start.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/start.html,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- start.html 1999/04/19 19:53:45 1.11
+++ start.html 1999/05/08 17:46:33 1.12
@@ -1,11 +1,14 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
- <TITLE>mod_perl guide: Getting Started with mod_perl. Overview.</TITLE>
+ <TITLE>mod_perl guide: Guide's Overview</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,51 +19,22 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
-Getting Started with mod_perl. Overview.</H1>
+Guide's Overview</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="intro.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="strategy.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
-
- <LI><A HREF="#Coverage">Coverage</A>
- <LI><A HREF="#Downloading_the_needed_component">Downloading the needed components.</A>
- <UL>
-
- <LI><A HREF="#Perl_Download">Perl Download</A>
- <LI><A HREF="#Apache_Download">Apache Download</A>
- <LI><A HREF="#Mod_Perl_Download">Mod_Perl Download</A>
- </UL>
-
- <LI><A HREF="#Configuration_and_Installation">Configuration and Installation</A>
- <UL>
-
- <LI><A HREF="#Perl">Perl</A>
- <LI><A HREF="#Apache">Apache</A>
- <LI><A HREF="#Mod_Perl">Mod_Perl</A>
- </UL>
-
- <LI><A HREF="#How_can_I_tell_whether_mod_perl_">How can I tell whether mod_perl is really installed</A>
- <UL>
-
- <LI><A HREF="#Testing_by_checking_the_error_lo">Testing by checking the error_log file</A>
- <LI><A HREF="#Testing_by_viewing_perl_status">Testing by viewing /perl-status</A>
- <LI><A HREF="#Testing_via_telnet">Testing via telnet</A>
- <LI><A HREF="#Testing_via_a_CGI_script">Testing via a CGI script</A>
- <LI><A HREF="#Testing_via_lwp_request">Testing via lwp-request</A>
- </UL>
- <LI><A HREF="#Starting_to_use_the_server">Starting to use the server</A>
+ <LI><A HREF="#What_s_inside_">What's inside?</A>
</UL>
<!-- INDEX END -->
-
+<HR>
- <P><A HREF="index.html">[Back to the main index]</A></P>
-
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -68,323 +42,124 @@
and <a
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<P>
-<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
-<P>
-These sections give a quick review of configuration and installation of the
-required tools. For a quick-start tutorial, which will allow you make to
-make a copy-and-paste slick installation, see
-<A HREF="././scenario.html#">Real World Scenario</A>
-
-
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Downloading_the_needed_component">Downloading the needed components.</A></H1></CENTER>
-<P>
-In order to start using mod_perl you will first need to get Perl, the
-Apache webserver, and mod_perl itself. Below you will find the needed
-information.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Perl_Download">Perl Download</A></H2></CENTER>
-<P>
-Perl is most likely already installed on your machine, but you should at
-least check the version you using. It is highly recommended that you have
-at least perl version 5.004 or higher. You can get the latest perl version
-from <A HREF="http://www.perl.com/">http://www.perl.com/</A> . Try the
-direct download link <A
-HREF="http://www.perl.com/pace/pub/perldocs/latest.html">http://www.perl.com/pace/pub/perldocs/latest.html</A>
-.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Apache_Download">Apache Download</A></H2></CENTER>
-<P>
-Get the latest apache webserver from <A
-HREF="http://www.apache.org">http://www.apache.org</A> . Try the direct
-download link <A
-HREF="http://www.apache.org/dist/">http://www.apache.org/dist/</A> .
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Mod_Perl_Download">Mod_Perl Download</A></H2></CENTER>
-<P>
-Get the latest mod_perl from <A
-HREF="http://perl.apache.org">http://perl.apache.org</A> . Try the direct
-download link <A
-HREF="http://perl.apache.org/dist/">http://perl.apache.org/dist/</A> .
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Configuration_and_Installation">Configuration and Installation</A></H1></CENTER>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Perl">Perl</A></H2></CENTER>
-<P>
-First install perl. Follow the instructions in the distribution's INSTALL
-file. During the configuration stage (while running
-<CODE>./Configure</CODE>), make sure you answer <CODE>YES</CODE> to:
-
-<P>
-<PRE> Do you wish to use dynamic loading? [y]
-</PRE>
-<P>
-You will want this feature on to dynamically load the Perl
-Modules/extensions.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Apache">Apache</A></H2></CENTER>
-<P>
-It is a good idea to try to install the Apache webserver without mod_perl
-first. This way, if something going wrong, you will know that it's not the
-Apache server's problem. But you can skip this stage if you already have a
-working (non-mod_perl) Apache server, or if you're just the daring type. In
-any case you should unpack the Apache source distribution, preferably at
-the same level as the mod_perl distribution.
-<P>
-<PRE> % ls -l /usr/src
- drwxr-xr-x 8 stas bar 2048 Oct 6 09:46 apache_1.3.2/
- drwxr-xr-x 19 stas bar 4096 Oct 2 14:33 mod_perl-1.16/
-</PRE>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Mod_Perl">Mod_Perl</A></H2></CENTER>
-<P>
-Now we come to the main point of this document.
+ <HR>
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
-Here I'll give only a short example of mod_perl installation. You should
-read the real world scenarios for a more complete description.
-
+<CENTER><H1><A NAME="What_s_inside_">What's inside?</A></H1></CENTER>
<P>
-As with any perl package, the installation of mod_perl is very easy and
-standard. <CODE>perldoc INSTALL</CODE> will guide you thru the configuration and installation process.
+Before you begin to install the mod_perl, you should have an overall
+picture. There are more then one way you set your mod_perl enabled
+webserver. You have to decide what mod_perl schema you want to use. <A HREF="././strategy.html#">Picking the Right Strategy</A> chapter presents various approaches, discusses the pros and cons of each
+one.
<P>
-The fastest way to install would be:
+Once you know what fits your requirements the best, you should proceed to <A HREF="././scenario.html#">Real World Scenarios of Implementing Various Strategies</A>. This chapter provides a very detailed scenarios of the schemas discussed
+in the <A HREF="././strategy.html#">Picking the Right Strategy</A> chapter.
-<P>
-<PRE> % perl Makefile.PL APACHE_SRC=../apache_1.3.2/src \
- DO_HTTPD=1 USE_APACI=1 PERL_MARK_WHERE=1 EVERYTHING=1
- % make && make test && make install
-</PRE>
<P>
-(Note: if you use an apache version different then apache_1.3.2, change the
-version number in the example above and in all later examples
-appropriately)
+<A HREF="././install.html#">Server Installation</A> chapter completes the <A HREF="././scenario.html#">Real World Scenarios of Implementing Various Strategies</A> by providing more installation details.
<P>
-To change the installation target (either if you aren't <CODE>root</CODE> or you need to install a second copy for testing purposes), assuming you
-use /foo/server as a base directory root, you have to run this:
+<A HREF="././config.html#">Server Configuration</A> extends the basic configurations presented in the <A HREF="././scenario.html#">Real World Scenarios of Implementing Various Strategies</A> with extended configurations and solutions to various configuration
+pitfalls.
<P>
-<PRE> % perl Makefile.PL APACHE_SRC=../apache_1.3.2/src \
- DO_HTTPD=1 PERL_MARK_WHERE=1 EVERYTHING=1 \
- APACHE_PREFIX=/foo/server PREFIX=/foo/server
-</PRE>
-<P>
-Where <CODE>PREFIX</CODE> specifies where to install the perl modules,
-<CODE>APACHE_PREFIX</CODE> - the same for the apache files.
+<A HREF="././frequent.html#">Frequent mod_perl problems</A> chapter just collects links to other chapters. It is an attempt to stress
+some of the most frequently mod_perl problems. So this is the first place
+you should check if you have got a problem.
<P>
-The next step is to configure the mod_perl sections of the apache conf
-files. See <A HREF="././config.html#">ModPerlConfiguration</A>
-
+Probably the most important chapter is <A HREF="././porting.html#">CGI to mod_perl Porting. mod_perl Coding guidelines</A>. It explains what are the differences between scripts running under
+mod_cgi and mod_perl. What should be done in order to make the existent
+scripts work under mod_perl. The proper mod_perl coding guidelines.
-
-<P>
-Fire up the server with <CODE>/foo/server/sbin/apachectl start</CODE>, Watch the error log file if server doesn't start up (No error message
-will be printed to the console!)
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="How_can_I_tell_whether_mod_perl_">How can I tell whether mod_perl is really installed</A></H1></CENTER>
<P>
-There a few ways. In older versions of apache ( < 1.3.2 ?) you could check that by running <CODE>httpd -v</CODE>, it no longer works. Now you should use <CODE>httpd -l</CODE>. Please notice that it is not enough to have it installed - you should of
-course configure it and restart the server.
+<A HREF="././performance.html#">Performance. Benchmarks</A> is the biggest and very important chapter. It explains the details of
+tuning the mod_perl and the scripts running under mod_perl, so you can
+squeeze every ounce of the power from your server. A big part of it are the
+benchmarks. The numbers that IT managers love to see. But those are
+different - these benchmarks are comparing mod_perl with other technologies
+but compare different configurations of mod_perl servers, to guide you in
+the tuning process. I have to admit - performance tuning is a very hard
+task, and demands a lot of understanding and experience, but once you get
+this knowledge - you can make magic with your server.
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Testing_by_checking_the_error_lo">Testing by checking the error_log file</A></H2></CENTER>
-<P>
-<PRE> [Thu Dec 3 17:27:52 1998] [notice] Apache/1.3.1 (Unix) mod_perl/1.15 configured -- resuming normal operations
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-</PRE>
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Testing_by_viewing_perl_status">Testing by viewing /perl-status</A></H2></CENTER>
<P>
-Assuming that you have configured the <CODE><Location /perl-status</CODE>> Section in the server configuration file (refer to
-<A HREF="././config.html#">ModPerlConfiguration</A>), fetch: <A
-HREF="http://www.yourserver.com/perl-status">http://www.yourserver.com/perl-status</A>
-using your favorite Netscape browser :-)
+<A HREF="././obvious.html#">Things obvious to others, but not to you</A> is exactly what it claims to be. Some people are too long into this
+business, and many things have become obvious to them. This is not true for
+a newbie, this chapter tries to talk about such things.
<P>
-You should see something like this:
+While developing your mod_perl applications, you are beginning to
+understand that an <CODE>error_log</CODE> file is your best friend. It tells you all the intimate details of what is
+happening to your scripts, but the problem that it talks in a secret
+language. To learn the alphabet and the grammar of this language, refer to
+a <A HREF="././warnings.html#">Warnings and Errors: Where and Why</A>.
-<P>
-<PRE> Embedded Perl version 5.00502 for Apache/1.3.1 (Unix) mod_perl/1.16
- process 50880, running since Tue Oct 6 14:31:45 1998
-</PRE>
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Testing_via_telnet">Testing via telnet</A></H2></CENTER>
-<P>
-Knowing the port you've configured Apache to listen on, you can use <CODE>telnet</CODE> to talk directly to the web server.
+If you are into driving relational databases with your cgi scripts, the <A HREF="././databases.html#">mod_perl and Relational Databases</A> chapter will tell you all about what database related goodies mod_perl
+prepared for you.
<P>
-Assume that you set <CODE>Port 8080</CODE> in the httpd.conf for your mod_perl enabled server. Telnet to your server
-at port 8080, and type <CODE>HEAD / HTTP/1.0</CODE> then press the <ENTER> key TWICE!
+If you are using the good old dbm files for your databases, <A HREF="././dbm.html#">mod_perl and dbm files</A> explains how to utilize them better under mod_perl.
-<P>
-<PRE> % telnet yourserver.com 8080<ENTER>
- HEAD / HTTP/1.0<ENTER><ENTER>
-</PRE>
<P>
-You should see a response like this:
+More and more ISPs are evaluating a possibility to give the mod_perl
+services to their users. Is it possible? Is it secure? Will it work? How
+much resources? <A HREF="././multiuser.html#">mod_perl for ISPs. mod_perl and Virtual Hosts</A> chapter answers all these questions. If you want to run a mod_perl enabled
+server, but do not have a root access read it as well, either to learn how
+do it by yourself, or maybe to persuade your ISP to provide you this
+service.
<P>
-<PRE> HTTP/1.1 200 OK
- Date: Tue, 01 Dec 1998 12:27:52 GMT
- Server: Apache/1.3.2 (Unix) mod_perl/1.16_01
- Connection: close
- Content-Type: text/html
-
- Connection closed.
-</PRE>
-<P>
-So you see <CODE>Server: Apache/1.3.2 (Unix) mod_perl/1.16_01</CODE> - which says that you <STRONG>do</STRONG> have mod_perl installed and it is version 1.16_01. Of course in your case
-it would be the version you have installed.
+If you have to administrate your apache mod_perl server - the
+<A HREF="././control.html#">Controlling and Monitoring the Server</A> chapter is for you. It includes the restarting and monitoring techniques.
+And very important - how to prevent from server to finish up your disk
+space in a matter of minutes.
<P>
-However, just because you've got mod_perl linked in there, that doesn't
-meant that you have your server configured to use mod_perl to handle Perl
-scripts. You will find the configuration assistance at
-<A HREF="././config.html#">ModPerlConfiguration</A>
-
-
+<A HREF="././status.html#">mod_perl Status. Peeking into the Server's Perl Innards</A>
+chapter shows you the ways you can peek into what is going on in the server
+while it is running. Like looking what are the value of some global
+variable. What database connections are open, and much more.
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Testing_via_a_CGI_script">Testing via a CGI script</A></H2></CENTER>
<P>
-Another method is to invoke a CGI script which dumps the server's
-environment.
+Every programmer need to know how to debug the program. It is _easy_ with
+perl, you invoke the script with <CODE>-d</CODE> flag and you start debugging it. Is it possible to do under mod_perl, after
+all you cannot debug every script by running it from the command line?
+<A HREF="././debug.html#">Debugging mod_perl</A> chapter tells exactly how to do it.
<P>
-Copy and paste the script below (no need for perl line!). Let's say you
-called it test.pl, you saved it into the root of the cgi scripts, and cgi
-root is mapped directly to /perl of your server.
-
-<P>
-<PRE> print "Content-type: text/html\n\n";
- print "Server's environment<P>\n";
- print "<TABLE>";
- foreach ( keys %ENV ) {
- print "<TR><TD>$_ </TD><TD>$ENV{$_}</TR></TD>";
- }
- print "</TABLE>";
-</PRE>
-<P>
-Make it executable:
-
-<P>
-<PRE> % chmod a+x test.pl
-</PRE>
-<P>
-Now fetch the URL <A
-HREF="http://www.you.com:8080/perl/test.pl">http://www.you.com:8080/perl/test.pl</A>
-. You should see something like this (part of the output was snipped).
-
-<P>
-<PRE> SERVER_SOFTWARE Apache/1.3.2 (Unix) mod_perl/1.16_01
- GATEWAY_INTERFACE CGI-Perl/1.1
- REQUEST_METHOD GET
- HTTP_ACCEPT image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
- MOD_PERL 1.16_01
- REQUEST_URI /perl/test.pl
- SCRIPT_NAME /perl/test.pl
- [...snipped]
-</PRE>
-<P>
-Now if I run the same script in mod_cgi mode (configured with /cgi-bin)
-(you'll need to add the perl line #!/bin/perl for the above script) and
-fetch <A
-HREF="http://www.you.com/cgi-bin/test.pl">http://www.you.com/cgi-bin/test.pl</A>
-.
-
-<P>
-<PRE> SERVER_SOFTWARE Apache/1.3.2 (Unix)
- GATEWAY_INTERFACE CGI/1.1
- [...snipped]
-</PRE>
-<P>
-You will see that two variables, <CODE>SERVER_SOFTWARE</CODE> and
-<CODE>GATEWAY_INTERFACE</CODE>, are different from the case above. This gives you a hint of how to tell
-in what mode you are running in your cgi scripts. I start all my cgi
-scripts that are mod_perl aware with:
-
-<P>
-<PRE> BEGIN {
- # Auto-detect if we are running under mod_perl or CGI.
- $USE_MOD_PERL = ((exists $ENV{'GATEWAY_INTERFACE'}
- and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
- or exists $ENV{'MOD_PERL'} );
- # perl5.004 is a must under mod_perl
- require 5.004 if $USE_MOD_PERL;
- }
-</PRE>
-<P>
-You might wonder why in the world you would need to know in what mode you
-are running. For example you will want to use <CODE>Apache::exit()</CODE>
-and not <CODE>CORE::exit()</CODE> in your scripts, but if you think that your script might be used in both
-environments (mod_cgi vs mod_perl), you will have to override the <CODE>exit()</CODE> subroutine and to make the runtime decision of what method you will use.
-For reasons and implementations see: <A HREF="././porting.html#using_exit_">Using exit()</A> and the whole
-<A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs to it</A> page.
+Sometimes browsers that interact with our servers have bugs, creating real
+problems to the CGI developers. How to prevent this bugs from happening
+discussed in <A HREF="././browserbugs.html#">Workarounds for some known bugs in browsers</A> chapter.
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Testing_via_lwp_request">Testing via lwp-request</A></H2></CENTER>
-<P>
-Yet another one. Why do I show all these approaches? While here they are
-serving a very simple purpose, they can be helpful in other situations.
+There many modules were written to extend the mod_perl's core
+functionality. Some of the important modules are being covered in <A HREF="././modules.html#">Apache::* modules</A>.
<P>
-Assuming you have the libwww-perl (LWP) package installed (you will need it
-installed in order to pass mod_perl's <CODE>make test</CODE> anyway):
+Some folks decides to go mod_perl, but they miss the basic understanding of
+the perl, which is not tolerant by mod_perl. if you are such a person,
+there is nothing to be ashamed of, we all went thru this. Get a good perl
+book and start reading. <A HREF="././perl.html#">Perl Reference</A> - gives some basic perl lessons, providing the information you cannot start
+to program mod_perl scripts without.
-<P>
-<PRE> % lwp-request -e -d www.site.com
-</PRE>
<P>
-Will show you all the headers. (The <CODE>-d</CODE> option disables printing the response content.)
+<A HREF="././snippets.html#">Code Snippets</A> chapter is just a collection of code snippets I have found useful while
+writing the scripts.
<P>
-<PRE> % lwp-request -e -d www.site.com | egrep '^Server:'
-</PRE>
-<P>
-To see the server's version only.
+<A HREF="././help.html#">Getting Helped and Further Learning</A> points you to other information sources, like perl programming, security,
+databases and more.
<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Starting_to_use_the_server">Starting to use the server</A></H1></CENTER>
-<P>
-Now you are ready to start writing CGIs. Note here -- you better start
-writing your scripts with an eye towards making them clean (i.e., <CODE>use strict;</CODE>), and with understanding of the new running environment. You have to learn
-how to write correctly for mod_perl. There is nothing new, the major item
-to remember is that your script would not die after it finishes serving the
-request, but will stay in memory and might affect all other scripts running
-under the same server process (child). You will read more about it in the
-following sections: <A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs</A>
-
+<A HREF="././download.html#">Appendix A: Downloading software and documentation</A>
+includes pointers to the software that was explained and/or mentioned in
+this guide.
-
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -394,7 +169,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="intro.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="strategy.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -406,8 +182,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/17/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>
1.12 +16 -12 modperl-site/guide/status.html
Index: status.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/status.html,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- status.html 1999/04/19 19:53:46 1.11
+++ status.html 1999/05/08 17:46:33 1.12
@@ -4,8 +4,11 @@
<TITLE>mod_perl guide: mod_perl Status. Peeking into the Server's Perl Innards</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,14 +19,14 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
mod_perl Status. Peeking into the Server's Perl Innards</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="control.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="debug.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#Watching_the_server">Watching the server</A>
@@ -36,11 +39,9 @@
</UL>
<!-- INDEX END -->
-
+<HR>
- <P><A HREF="index.html">[Back to the main index]</A></P>
-
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
book can be purchased online from <a
@@ -49,7 +50,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="Watching_the_server">Watching the server</A></H1></CENTER>
<P>
@@ -149,7 +152,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="control.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="debug.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -161,8 +165,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 04/19/1999
</FONT>
</B>
</TD>
1.3 +3 -21 modperl-site/guide/style.css
Index: style.css
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/style.css,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- style.css 1999/04/04 10:56:00 1.2
+++ style.css 1999/05/08 17:46:34 1.3
@@ -1,33 +1,15 @@
A {
text-decoration: none;
}
-BODY, P, UL, OL, LI, DL, DD {
- font-family: palatino, georgia, times, serif;
-}
-H1, H2, H3, H4, H5, TH {
- font-family: verdana, helvetica, arial, sans-serif;
-}
-CAPTION, DT {
- font-family: verdana, helvetica, arial, sans-serif;
- font-weight: bold;
- font-size: medium;
-}
PRE {
white-space: pre;
- font-family: profont, monaco, ocr-a, monospace;
+ font-family: profont, monaco, ocr-a, monospace, fixed;
+ font-size: medium;
line-height: normal;
color: black;
background-color: #ccccff;
padding: .25em;
margin: .25em;
border: thin dashed black;
-}
-CODE, SAMP {
- font-family: profont, monaco, ocr-a, monospace;
- line-height: normal;
- color: #990000;
-}
-TT {
- font-family: profont, monaco, ocr-a, monospace;
- line-height: normal;
}
+
1.12 +36 -66 modperl-site/guide/warnings.html
Index: warnings.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/warnings.html,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- warnings.html 1999/04/19 19:53:49 1.11
+++ warnings.html 1999/05/08 17:46:34 1.12
@@ -4,8 +4,11 @@
<TITLE>mod_perl guide: Warnings and Errors: Where and Why.</TITLE>
<META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
<META NAME="Author" CONTENT="Bekman Stas">
- <META NAME="Description" CONTENT="mod_perl,perl,apache">
- <META NAME="Keywords" CONTENT="mod_perl,perl,apache,webserver,cgi">
+ <META NAME="Description" CONTENT="All Apache/Perl related information: Hints,
+Guidelines, Scenarios and Troubleshottings">
+ <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed
+fast guide mod_perl apache guide help info faq mod_perl installation cgi
+troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
</HEAD>
<LINK REL=STYLESHEET TYPE="text/css"
HREF="style.css" TITLE="refstyle">
@@ -16,14 +19,14 @@
</style>
<BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
-
+<A NAME="toc"></A>
<H1 ALIGN=CENTER>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
<A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
Warnings and Errors: Where and Why.</H1>
<HR WIDTH="100%">
- <!-- INDEX BEGIN -->
-<P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
+ [ <A HREF="obvious.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="databases.html">Next</A> ]<HR><!-- INDEX BEGIN -->
+<P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
<UL>
<LI><A HREF="#General_Advice">General Advice </A>
@@ -47,10 +50,8 @@
<LI><A HREF="#server_reached_MaxClients_settin">server reached MaxClients setting, consider raising the MaxClients setting</A>
</UL>
<!-- INDEX END -->
-
-
- <P><A HREF="index.html">[Back to the main index]</A></P>
+<HR>
The <a href="http://www.modperl.com/">
<B>Writing Apache Modules with Perl and C</B></a>
@@ -60,7 +61,9 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+ <HR>
+
+ <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<P>
<CENTER><H1><A NAME="General_Advice">General Advice</A></H1></CENTER>
<P>
@@ -78,18 +81,14 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Value_of_x_will_not_stay_shared">Value of $x will not stay shared at - line 5</A></H1></CENTER>
<P>
-See <A HREF="././obvious.html#my_scoped_variable_in_the_nest">my() scoped variable in the nested subroutine</A>
+<A HREF="././obvious.html#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>.
-
-
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Value_of_x_may_be_unavailable_a">Value of $x may be unavailable at - line 5.</A></H1></CENTER>
<P>
-See <A HREF="././obvious.html#my_scoped_variable_in_the_nest">my() scoped variable in the nested subroutine</A>
-
+<A HREF="././obvious.html#my_scoped_variable_in_nested_s">my() scoped variable in nested subroutines</A>.
-
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="mod_perl_rwrite_returned_1">mod_perl: rwrite returned -1</A></H1></CENTER>
@@ -230,63 +229,33 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Use_of_uninitialized_value_at_e">Use of uninitialized value at (eval 80) line 12.</A></H1></CENTER>
<P>
-If you compile with the experimental <STRONG>PERL_MARK_WHERE=1</STRONG>, it shows you ``exactly'' where this is happening. many times compiler
-makes a shift for ``unknown'' reasons in its line counter. You can always
-stuff your code with special compiler directives, to reset its counter to
-the value you will tell. At the beginning of the line you should write (the
-'#' in column 1):
-
-<P>
-<PRE> #line 298 myscript.pl
-</PRE>
-<P>
-(myscript.pl is optional.) This specifies the line number of the
-<STRONG>following</STRONG> line, not the line the directive is on. You can use a little script to
-stuff every N lines of your code with these directives, but then you will
-have to rerun this script every time you add or remove code lines. The
-script:
-
-<P>
-<PRE> <META>
- This example was double incrementing $counter.
- I took the second increment out -- sgr.
- </META>
-</PRE>
-<P>
-<PRE> #!/usr/bin/perl
- # Puts Perl line markers in a Perl program for debugging purposes.
- # Also takes out old line markers.
- die "No filename to process.\n" unless @ARGV;
- my $filename = $ARGV[0];
- my $lines = 100;
- open IN, $filename or die "Cannot open file: $filename: $!\n";
- open OUT, ">$filename.marked"
- or die "Cannot open file: $filename.marked: $!\n";
- my $counter = 1;
- while (<IN>) {
- print OUT "# line $counter\n" unless $counter++ % $gap;
- next if $_ =~ /^# line /;
- print OUT $_;
- }
- close OUT;
- close IN;
- chmod 0755, "$filename.marked";
+Your code includes some undefined variable that you have used as if it was
+already defined and initialized. For example:
+
+<P>
+<PRE> $param = $q->param('test');
+ print $param;
</PRE>
<P>
-You can also add:
-
+<PRE> vs.
+</PRE>
<P>
-<PRE> use Carp ();
- local $SIG{__WARN__} = \&Carp::cluck;
+<PRE> $param = $q->param('test') || '';
+ print $param;
</PRE>
<P>
+In the second case, <CODE>$param</CODE> will always be <CODE>defined</CODE>, either
+<CODE>$q-&gt;param('test')</CODE> returns some value or <CODE>undef</CODE>.
+
+<P>
+Also read about <A HREF="././porting.html#Finding_the_line_number_the_erro">finding the line number the error/warning has been triggered at</A>.
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Undefined_subroutine_Apache_RO">Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function called at</A></H1></CENTER>
<P>
-See <A HREF="././porting.html#Names_collisions_with_Modules_an">Names collisions with Modules and libs</A>
-
+See <A HREF="././porting.html#Name_collisions_with_Modules_and">Names collisions with Modules and libs</A>.
-
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Can_t_load_auto_DBI_DBI_so_">Can't load '.../auto/DBI/DBI.so' for module DBI</A></H1></CENTER>
@@ -447,7 +416,8 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
-<P><A HREF="index.html">[Back to the main index]</A></P>
+ <HR>
+ [ <A HREF="obvious.html">Prev</A> | <A HREF="index.html">Main Page</A> | <A HREF="databases.html">Next</A> ]
<CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
<TR ALIGN=CENTER VALIGN=TOP>
@@ -459,8 +429,8 @@
<TD ALIGN=CENTER VALIGN=CENTER>
<B>
<FONT SIZE=-1>
- Written by <A HREF="help.html#author">Stas Bekman</A>.
- <BR>Last Modified at 04/19/99
+ Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
+ <BR>Last Modified at 05/08/1999
</FONT>
</B>
</TD>