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/08/17 21:03:57 UTC
cvs commit: modperl-site/guide CHANGES advocacy.html all.html browserbugs.html config.html control.html databases.html dbm.html debug.html download.html frequent.html guide-src.tar.gz guide.tar.gz hardware.html help.html index.html install.html intro.html mod_perl_guide.ps.gz modules.html multiuser.html obvious.html performance.html perl.html porting.html scenario.html security.html snippets.html start.html status.html strategy.html warnings.html
sbekman 99/08/17 12:03:56
Modified: guide CHANGES advocacy.html all.html browserbugs.html
config.html control.html databases.html dbm.html
debug.html download.html frequent.html
guide-src.tar.gz guide.tar.gz hardware.html
help.html index.html install.html intro.html
mod_perl_guide.ps.gz modules.html multiuser.html
obvious.html performance.html perl.html
porting.html scenario.html security.html
snippets.html start.html status.html strategy.html
warnings.html
Log:
* Richard A. Wells has kindly reviewed and corrected the following
pods: advocacy.pod download.pod snippets.pod status.pod
browserbugs.pod intro.pod start.pod
* security.pod : added "Forcing reauthenticating" section
* index.pod : Added a link to http://www.perlreference.com/mod_perl/
* help.pod : Added links to modperl.sourcegarden.org and
http://www.perlreference.com/mod_perl/
* performance.pod: a little fix to the crashme script (Jay J)
* Updated the porting.pod sections: "Sometimes it wors, sometimes
doesn't", "Script's name space" and other as well
* config.pod: updated <Perl> sections (how to dump the sections (Eric
Cholet) and how to use the /perl-status for doing that.
* hardware.pod: David Landgren did a great job of reviewing,
suggesting and correcting the OS/Hardare chapter!
* Andreas J. Koenig pointed out that it's unfair to mention eddieware
without the others.. I agree Andreas! hardware.pod and download.pod
were updated to point to "High-Availability Linux Project"
site... Eddieware was removed :)
* download.pod: now guide hints on where to find Apache::Request
(libapreq-x.xx.tar.gz) - on Philip Jacob request
* config.pod: a few small typos (John Milton)
* databases.pod: Matt Arnold pointed out a problem with
connect_on_init if the database server is down. I've added a
warning.
* porting.pod: Cleared out the confusion with StatINC and @INC issue
* perl.pod: Added a section that reveals the useful perldoc options
* performance.pod: Added the explanation of the Apache::Leak example
(Cliff Rayman)
* databases.pod: Added the explanation of the "skipping connection
cache during server startup", when the connection is attempted to be
opened in the parent process. (Edmund Mergl)
* debug.pod: started the "Debugging Core Dumps" item (Doug)
* performance.pod: added the reference to Apache::RegistryBB, for
those who want to save the little overhead of the stat() call that
is being executed under Apache::Registry. (Doug)
* modules.pod: added Apache::RegistryBB (Doug)
* porting.pod: covered the issue of Apache/Work/Foo/Bar.pm collision
with Apache/Work/Foo.pm if the former is being loaded first (Doug)
* Apache::Leak considered to be non-friendly, added a reference to
B::LexInfo (Doug)
* porting.pod: "Passing ENV variables to CGI" added clarifications for
%ENV setting/passing mechanism in mod_perl (Doug)
* performance.pod: started a new subsection - shared memory (what, how
much, where)
* modules.pod and porting.pod: added an Apache::LogSTDERR module to
solve the syslog problem(Doug)
* porting.pod: Reloading handlers trick (Doug)
Revision Changes Path
1.15 +74 -22 modperl-site/guide/CHANGES
Index: CHANGES
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/CHANGES,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- CHANGES 1999/07/02 13:42:09 1.14
+++ CHANGES 1999/08/17 19:03:28 1.15
@@ -1,5 +1,79 @@
This is a CHANGES file for mod_perl guide
+08.17.99 ver 1.15
+
+* Richard A. Wells has kindly reviewed and corrected the following
+ pods: advocacy.pod download.pod snippets.pod status.pod
+ browserbugs.pod intro.pod start.pod
+
+* security.pod : added "Forcing reauthenticating" section
+
+* index.pod : Added a link to http://www.perlreference.com/mod_perl/
+
+* help.pod : Added links to modperl.sourcegarden.org and
+ http://www.perlreference.com/mod_perl/
+
+* performance.pod: a little fix to the crashme script (Jay J)
+
+* Updated the porting.pod sections: "Sometimes it wors, sometimes
+ doesn't", "Script's name space" and other as well
+
+* config.pod: updated <Perl> sections (how to dump the sections (Eric
+ Cholet) and how to use the /perl-status for doing that.
+
+* hardware.pod: David Landgren did a great job of reviewing,
+ suggesting and correcting the OS/Hardare chapter!
+
+* Andreas J. Koenig pointed out that it's unfair to mention eddieware
+ without the others.. I agree Andreas! hardware.pod and download.pod
+ were updated to point to "High-Availability Linux Project"
+ site... Eddieware was removed :)
+
+* download.pod: now guide hints on where to find Apache::Request
+ (libapreq-x.xx.tar.gz) - on Philip Jacob request
+
+* config.pod: a few small typos (John Milton)
+
+* databases.pod: Matt Arnold pointed out a problem with
+ connect_on_init if the database server is down. I've added a
+ warning.
+
+* porting.pod: Cleared out the confusion with StatINC and @INC issue
+
+* perl.pod: Added a section that reveals the useful perldoc options
+
+* performance.pod: Added the explanation of the Apache::Leak example
+ (Cliff Rayman)
+
+* databases.pod: Added the explanation of the "skipping connection
+ cache during server startup", when the connection is attempted to be
+ opened in the parent process. (Edmund Mergl)
+
+* debug.pod: started the "Debugging Core Dumps" item (Doug)
+
+* performance.pod: added the reference to Apache::RegistryBB, for
+ those who want to save the little overhead of the stat() call that
+ is being executed under Apache::Registry. (Doug)
+
+* modules.pod: added Apache::RegistryBB (Doug)
+
+* porting.pod: covered the issue of Apache/Work/Foo/Bar.pm collision
+ with Apache/Work/Foo.pm if the former is being loaded first (Doug)
+
+* Apache::Leak considered to be non-friendly, added a reference to
+ B::LexInfo (Doug)
+
+* porting.pod: "Passing ENV variables to CGI" added clarifications for
+ %ENV setting/passing mechanism in mod_perl (Doug)
+
+* performance.pod: started a new subsection - shared memory (what, how
+ much, where)
+
+* modules.pod and porting.pod: added an Apache::LogSTDERR module to
+ solve the syslog problem(Doug)
+
+* porting.pod: Reloading handlers trick (Doug)
+
07.3.99 ver 1.14
* porting.pod: added "Exposing Apache::Registry secrets, closures,
@@ -20,28 +94,6 @@
databases.pod
multiuser.pod
help.pod
-
-*
-
-*
-
-*
-
-*
-
-*
-
-*
-
-*
-
-*
-
-*
-
-*
-
-*
06.19.99 ver 1.13
1.3 +20 -20 modperl-site/guide/advocacy.html
Index: advocacy.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/advocacy.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- advocacy.html 1999/06/19 21:14:58 1.2
+++ advocacy.html 1999/08/17 19:03:31 1.3
@@ -48,19 +48,19 @@
<CENTER><H1><A NAME="Thoughts_about_scalability_and_f">Thoughts about scalability and flexibility</A></H1></CENTER>
<P>
Your need for scalability and flexibility depends on your needs from the
-web. If you want only a simple guest book or Database gateway with no
+web. If you want only a simple guest book or database gateway with no
feature headroom, you can get away with any EASY_AND_FAST_TO_DEVELOP_TOOL
(Exchange, MS IIS, Lotus Notes, etc).
<P>
-Experience shows that you will soon want more functionality, that you'll
-start spending time learning the limitations of these ``easy'' tools.
-Gradually, your boss will ask for increasing functionality and at some
-point you'll realize that the tool lacks flexibility and/or scalability.
-Then your boss will either buy another EASY_AND_FAST_TO_DEVELOP_TOOL and
-repeat the process (with different unforseen problems), or you'll start
-investing time learning how to use a powerful, flexible tool to make the
-long-term development cycle easier.
+Experience shows that you will soon want more functionality, that's the
+point you'll discover the limitations of these ``easy'' tools. Gradually,
+your boss will ask for increasing functionality and at some point you'll
+realize that the tool lacks flexibility and/or scalability. Then your boss
+will either buy another EASY_AND_FAST_TO_DEVELOP_TOOL and repeat the
+process (with different unforseen problems), or you'll start investing time
+learning how to use a powerful, flexible tool to make the long-term
+development cycle easier.
<P>
If you and your company are serious about delivering flexible Internet
@@ -82,19 +82,19 @@
<P>
Personally, when I discovered mod_perl I did a lot of testing and coding at
home and at work. Once I had a working heavy application, I came to my boss
-with 2 URLs - one for the plain CGI server and the other for mod_perl
-enabled server. It took about 30 secs for my boss to say: `Go with it''. Of
-course the moment I did it, I have had to provide all the support for other
-developers, that is why I took my time to learn it in first place (that is
-how this guide was born!).
+with 2 URLs - one for the plain CGI server and the other for the
+mod_perl-enabled server. It took about 30 secs for my boss to say: `Go with
+it''. Of course the moment I did it, I have had to provide all the support
+for other developers, that is why I took time to learn it in first place
+(that is how this guide was born!).
<P>
Chances are that if you've done your homework, you've learned the tools and
-you can deliver results, you'll have a successful project. If you convince
-your boss to try a tool that you don't know very well, your results may
-suffer. If your boss follows your development process closely and sees much
-worse than expected progress, he might say ``forget it'' and wish never to
-give mod_perl a second chance.
+can deliver results, you'll have a successful project. If you convince your
+boss to try a tool that you don't know very well, your results may suffer.
+If your boss follows your development process closely and sees much worse
+than expected progress, he might say ``forget it'' and wish never to give
+mod_perl a second chance.
<P>
Advocacy is a great thing for the open-source software movement, but it's
@@ -132,7 +132,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/19/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
1.16 +1235 -760 modperl-site/guide/all.html
Index: all.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/all.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- all.html 1999/07/02 13:42:11 1.15
+++ all.html 1999/08/17 19:03:32 1.16
@@ -30,8 +30,8 @@
<CENTER><P><B>Deploying mod_perl technology to give a rocket speed
to your CGI/perl scripts.</B></P></CENTER>
-<CENTER><P><B>Version 1.14
- Jul, 2 1999</B></P></CENTER>
+<CENTER><P><B>Version 1.15
+ Aug, 17 1999</B></P></CENTER>
<P>
<HR WIDTH="100%"></P>
@@ -69,6 +69,7 @@
<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#More_package_name_related_issues">More package name related issues</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>
@@ -86,6 +87,7 @@
<LI><A HREF="porting.html#Passing_ENV_variables_to_CGI">Passing ENV variables to CGI</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#Apache_and_syslog">Apache and syslog</A>
<LI><A HREF="porting.html#Memory_leakage">Memory leakage</A>
</UL>
@@ -95,6 +97,7 @@
<LI><A HREF="porting.html#Restarting_the_server">Restarting the server</A>
<LI><A HREF="porting.html#Using_Apache_StatINC">Using Apache::StatINC</A>
<LI><A HREF="porting.html#Reloading_only_specific_files">Reloading only specific files</A>
+ <LI><A HREF="porting.html#Reloading_handlers">Reloading handlers</A>
</UL>
<LI><A HREF="porting.html#Filehandlers_and_locks_leakages">Filehandlers and locks leakages</A>
@@ -118,7 +121,9 @@
<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#How_can_I_find_if_my_mod_perl_sc">How can I find if my mod_perl scripts have memory leaks (and where)</A>
+ <LI><A HREF="performance.html#Shared_Memory">Shared Memory</A>
+ <LI><A HREF="performance.html#Checking_script_modification_tim">Checking script modification times</A>
+ <LI><A HREF="performance.html#How_can_I_find_if_my_mod_perl_sc">How can I find if my mod_perl scripts have memory leaks</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>
@@ -193,7 +198,7 @@
<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#Building_and_Using_mod_proxy">Building and Using mod_proxy</A>
<LI><A HREF="scenario.html#mod_perl_server_as_DSO">mod_perl server as DSO</A>
<LI><A HREF="scenario.html#HTTP_Authentication_with_2_serve">HTTP Authentication with 2 servers + proxy</A>
</UL>
@@ -354,6 +359,12 @@
<LI><A HREF="security.html#Non_authenticated_access_for_int">Non authenticated access for internal IPs, but authenticated by external IPs</A>
</UL>
+ <LI><A HREF="security.html#Authentication_code_snippets">Authentication code snippets</A>
+ <UL>
+
+ <LI><A HREF="security.html#Forcing_reauthenticating">Forcing reauthenticating</A>
+ </UL>
+
</UL>
<P><LI><A HREF="databases.html"><B><FONT SIZE=+1>mod_perl and Relational Databases</FONT></B></A></LI><P>
<UL>
@@ -373,6 +384,7 @@
<LI><A HREF="databases.html#Opening_a_connection_with_differ">Opening a connection with different parameters</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>
+ <LI><A HREF="databases.html#skipping_connection_cache_during">skipping connection cache during server startup</A>
</UL>
</UL>
@@ -420,6 +432,7 @@
<LI><A HREF="debug.html#Sometimes_script_works_sometime">Sometimes script works, sometimes does not</A>
<LI><A HREF="debug.html#Non_interactive_debugging_when_r">Non-interactive debugging when running under mod_perl</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#Debugging_Core_Dumps">Debugging Core Dumps</A>
<LI><A HREF="debug.html#Debug_Tracing">Debug Tracing</A>
<LI><A HREF="debug.html#gdb_says_there_are_no_debugging_">gdb says there are no debugging symbols</A>
<LI><A HREF="debug.html#Monitoring_error_log_file">Monitoring error_log file</A>
@@ -442,11 +455,14 @@
<LI><A HREF="modules.html#Apache_PerlRun_Run_unaltered_">Apache::PerlRun - Run unaltered CGI scripts under mod_perl</A>
<LI><A HREF="modules.html#Apache_GzipChain_compress_HTM">Apache::GzipChain - compress HTML (or anything) in the OutputChain</A>
<LI><A HREF="modules.html#Apache_PerlVINC_set_a_differe">Apache::PerlVINC - set a different @INC perl-location </A>
+ <LI><A HREF="modules.html#Apache_RegistryBB_Apache_Re">Apache::RegistryBB -- Apache::Registry Bare-Bones</A>
+ <LI><A HREF="modules.html#Apache_LogSTDERR">Apache::LogSTDERR</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#perldoc_s_little_known_but_very_">perldoc's little known but very useful options</A>
<LI><A HREF="perl.html#Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A>
<UL>
@@ -461,9 +477,9 @@
<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#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#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>
@@ -486,10 +502,11 @@
<LI><A HREF="hardware.html#Choosing_Hardware">Choosing Hardware</A>
<UL>
- <LI><A HREF="hardware.html#Site_traffic">Site traffic</A>
+ <LI><A HREF="hardware.html#Expected_site_traffic">Expected site traffic</A>
<LI><A HREF="hardware.html#Cash">Cash</A>
- <LI><A HREF="hardware.html#Memory">Memory</A>
<LI><A HREF="hardware.html#Internet_Connection">Internet Connection</A>
+ <LI><A HREF="hardware.html#I_O_performance">I/O performance</A>
+ <LI><A HREF="hardware.html#Memory">Memory</A>
<LI><A HREF="hardware.html#Bottlenecks">Bottlenecks</A>
<LI><A HREF="hardware.html#Conclusion">Conclusion</A>
</UL>
@@ -517,15 +534,16 @@
<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#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_Internet_Object_Cache">Squid - Internet Object Cache</A>
<LI><A HREF="download.html#thttpd_tiny_turbo_throttling_H">thttpd - tiny/turbo/throttling HTTP server</A>
<LI><A HREF="download.html#mod_proxy_add_forward">mod_proxy_add_forward</A>
<LI><A HREF="download.html#httperf_webserver_Benchmarking">httperf - webserver Benchmarking tool</A>
<LI><A HREF="download.html#ab_ApacheBench">ab - ApacheBench</A>
- <LI><A HREF="download.html#Eddieware">Eddieware</A>
+ <LI><A HREF="download.html#High_Availability_Linux_Project">High-Availability Linux Project</A>
+ <LI><A HREF="download.html#Apache_Request">Apache::Request</A>
</UL>
<P>
@@ -565,6 +583,12 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
<HR>
+<P>
+
+Now you can search the indexed version of the guide at <A
+HREF="http://www.perlreference.com/mod_perl/guide">perlreference.com</A>.
+
+<HR>
<CENTER>
<TABLE BORDER=10 CELLSPACING=2 CELLPADDING=8 >
<TR BGCOLOR="gray" ALIGN=CENTER VALIGN=TOP>
@@ -600,7 +624,7 @@
<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 07/02/1999
+HREF="help.html#This_document_s_Author">Stas Bekman</A>.<BR> Last Modified at 08/17/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>
@@ -670,27 +694,27 @@
<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
+possible to write Apache modules entirely in Perl, letting 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.
+as running sub requests. In addition, the persistent Perl interpreter
+embedded in the server saves the overhead of starting an external
+interpreter, i.e. the penalty of Perl start-up time. And not the least
+important feature is code caching, where modules and scripts are loaded and
+compiled only once, then for the rest of the server's life they are served
+from the cache, thus the server spends its time only on running already
+loaded and compiled code, which is very fast.
<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
+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
+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
+such extension, 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.
@@ -703,34 +727,34 @@
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
+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)
+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_will_you_learn">What will you learn</A></H1></CENTER>
<P>
-This document was written in an effort to help one to start using Apache's
+This document was written in an effort to help you 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
+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>
+big world of using the Perl API or C API. You will find pointers covering
+these topics in the <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.
+databases, Perl reference, code snippets and more. The <A HREF="././start.html#">Guide's Overview</A> will help you to find your way through the guide.
<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.
+Perl and Apache. (If you do not, just read the INSTALL docs coming with
+distribution of each package.) However, in this guide you will find
+specific Perl and Apache installation and configuration notes, which will
+help you successfully complete the mod_perl installation and get the server
+running 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
@@ -738,15 +762,15 @@
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
+list archive, since there is a good chance someone else has already
+encountered the problem and found a solution. 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>
-If you find incorrect details, my grammar mistakes or you want to
+If you find incorrect details or 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> .
@@ -799,11 +823,10 @@
<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.
+to take the credit for myself, it's just that I tried to keep track of
+names, and became lost, so I preferred not to put credit throughout the
+guide, but rather to centralize it here. If you want your name to show up
+under your original quote, please tell me and I'll add it for you.
<P>
Major contributors:
@@ -811,7 +834,7 @@
<UL>
<P><LI>
<P>
-<STRONG>Doug MacEachern</STRONG>. A big part of this guide is build upon his email replies to users'
+<STRONG>Doug MacEachern</STRONG>. A big part of this guide is built upon his email replies to users'
questions.
<P><LI>
@@ -829,13 +852,13 @@
<P><LI>
<P>
-<STRONG>Eric Cholet</STRONG>, who wrote complete sections for the guide, and pointed out the errors the
-guide carried away.
+<STRONG>Eric Cholet</STRONG>, who wrote complete sections for the guide, and pointed out the errors in
+the guide.
<P><LI>
<P>
-<STRONG>Ken Williams</STRONG>, who reviewed a lot of stuff in the guide, and many snippets from his
-emails are included in the guide.
+<STRONG>Ken Williams</STRONG>, who reviewed a lot of stuff in the guide. Many snippets from his emails
+are included in the guide.
</UL>
<P>
@@ -884,7 +907,7 @@
<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,
+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 bugs and advocate the mod_perl around the world.
@@ -911,7 +934,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
@@ -983,120 +1006,118 @@
<P>
<CENTER><H1><A NAME="What_s_inside_">What's inside?</A></H1></CENTER>
<P>
-Before you start with mod_perl installation, you should see an overall
-picture of this wonderful technology. There is more then one way to use
-mod_perl enabled webserver. You have to decide what mod_perl schema you
+Before you start installing mod_perl, you should have an overall picture of
+this wonderful technology. There is more then one way to use a
+mod_perl-enabled webserver. You have to decide what mod_perl scheme you
want to use. <A HREF="././strategy.html#">Picking the Right Strategy</A>
-chapter presents various approaches and discusses the pros and cons of
-them.
+chapter presents various approaches and discusses their pros and cons.
<P>
-Once you know what fits your requirements the best, you should proceed to <A HREF="././scenario.html#">Real World Scenarios Implementaion</A>. This chapter provides a very detailed scenarios of the schemas discussed
-in the
+Once you know what fits your requirements the best, you should proceed to <A HREF="././scenario.html#">Real World Scenarios Implementaion</A>. This chapter provides very detailed scenarios of the schemes discussed in
+the
<A HREF="././strategy.html#">Picking the Right Strategy</A> chapter.
<P>
-<A HREF="././install.html#">Server Installation</A> chapter completes the <A HREF="././scenario.html#">Real World Scenarios Implementaion</A> by providing more indepth installation details.
+The <A HREF="././install.html#">Server Installation</A> chapter follows on to the <A HREF="././scenario.html#">Real World Scenarios Implementaion</A> chapter by providing more in-depth installation details.
<P>
-<A HREF="././config.html#">Server Configuration</A> adds to the basic configurations presented in the <A HREF="././scenario.html#">Real World Scenarios Implementaion</A>
-extended configurations and various configuration examples.
+The <A HREF="././config.html#">Server Configuration</A> chapter adds to the basic configurations presented in the <A HREF="././scenario.html#">Real World Scenarios Implementaion</A> chapter with extended configurations and various configuration examples.
<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.
+The <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 encountered mod_perl problems. So this is the
+first place you should check if you have got a problem.
<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 run under mod_perl. Along with the porting notes it provides
-guidelines for a proper mod_perl programming.
+Probably the most important chapter is <A HREF="././porting.html#">CGI to mod_perl Porting. mod_perl Coding guidelines</A>. It explains the differences between scripts running under mod_cgi and
+mod_perl, and what should be done in order to make existing scripts run
+under mod_perl. Along with the porting notes it provides guidelines for
+proper mod_perl programming.
<P>
<A HREF="././performance.html#">Performance. Benchmarks</A> is the biggest and a very important chapter. It explains the details of
-tuning the mod_perl and the scripts running under it, so you can squeeze
-every ounce of the power from your server. A big part of the chapter are
+tuning mod_perl and the scripts running under it, so you can squeeze every
+ounce of the power from your server. A big part of the chapter are
benchmarks, the numbers that IT managers love to read. But these are
-different benchmarks - they are not comparing mod_perl with other alike
-technologies but different configurations of mod_perl servers, to guide you
-through 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
-acquire this knowledge - you can make a magic with your server.
+different benchmarks: they are not comparing mod_perl with similar
+technologies, rather with different configurations of mod_perl servers, to
+guide you through 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 acquire this knowledge you can make magic with your server.
<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 too obvious to them. This is not true
-for a newbie, this chapter tries to talk about such things.
+The <A HREF="././obvious.html#">Things obvious to others, but not to you</A> chapter is exactly what it claims to be. Some people have been in this
+business too long, and many things have become too obvious to them. This is
+not true for a newbie, so this chapter talks about such things.
<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 speaks a secret
+While developing your mod_perl applications, you will begin 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 is that it speaks 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>.
+the chapter <A HREF="././warnings.html#">Warnings and Errors: Where and Why</A>.
<P>
-If you are into a driving of relational databases with your cgi scripts, <A HREF="././databases.html#">mod_perl and Relational Databases</A> chapter will tell you all about database related goodies mod_perl has
+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 the database-related goodies mod_perl has
prepared for you.
<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.
+If you are using good old dbm files for your databases, the <A HREF="././dbm.html#">mod_perl and dbm files</A> chapter explains how to utilize them better under mod_perl.
<P>
-More and more Internet Service Providers (ISPs) are evaluating a
-possibility to provide the mod_perl services to their users. Is it
-possible? Is it secure? Will it work? How much resources does it takes? <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
+More and more Internet Service Providers (ISPs) are evaluating the
+possibility of providing mod_perl services to their users. Is this
+possible? Is it secure? Will it work? What resources does it take? The <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 root access, read this chapter as well, either to
+learn how do it yourself, or maybe to persuade your ISP to provide this
service.
<P>
-If you have to administrate your apache mod_perl server -
-<A HREF="././control.html#">Controlling and Monitoring the Server</A> chapter is for you. Among the topics there are server restarting and
-monitoring techniques, preventing from server to eat up all your disk space
-in a matter of minutes and more.
-
-<P>
-<A HREF="././status.html#">mod_perl Status. Peeking into the Server's Perl Innards</A>
-chapter shows you the ways you can peek at what is going on in the mod_perl
-enabled server while it is running. Like looking what is the value of some
-global variable, what database connections are open, looking up what
-modules were loaded and their pathes, what is the value of
-<CODE>@INC</CODE> and much more.
+If you have to administer your Apache mod_perl server the
+<A HREF="././control.html#">Controlling and Monitoring the Server</A> chapter is for you. Among the topics are: server restarting and monitoring
+techniques, preventing the server from eating up all your disk space in a
+matter of minutes, and more.
<P>
-Every programmer needs to know how to debug the program she writes. It is
-an _easy_ task with plain perl. Just invoke the program with <CODE>-d</CODE>
+The <A HREF="././status.html#">mod_perl Status. Peeking into the Server's Perl Innards</A>
+chapter shows you the ways you can peek at what is going on in a
+mod_perl-enabled server while it is running. Like looking at the value of
+some global variable, what database connections are open, looking up what
+modules were loaded and their paths, what is the value of <CODE>@INC</CODE>, and much more.
+
+<P>
+Every programmer needs to know how to debug her program. It is an _easy_
+task with plain Perl. Just invoke the program with the <CODE>-d</CODE>
flag and debug it. Is it possible to do the same under mod_perl? After all
-you cannot debug every CGI script by executing it from the command line,
-some scripts will not run from the command line. <A HREF="././debug.html#">Debugging mod_perl</A> chapter proves it possible and real.
+you cannot debug every CGI script by executing it from the command line:
+some scripts will not run from the command line. The <A HREF="././debug.html#">Debugging mod_perl</A> chapter proves debugging under mod_perl is possible and real.
<P>
-Sometimes browsers that interact with our servers have bugs, which cause a
-strong headache to CGI developers. Preventing these bugs from happening is
-being discussed in <A HREF="././browserbugs.html#">Workarounds for some known bugs in browsers</A> chapter.
+Sometimes browsers that interact with our servers have bugs, which cause
+big headaches for CGI developers. Preventing these bugs from happening is
+discussed in the <A HREF="././browserbugs.html#">Workarounds for some known bugs in browsers</A> chapter.
<P>
Many modules were written to extend the mod_perl's core functionality. Some
-of important modules are being covered in
+important modules are covered in the
<A HREF="././modules.html#">Apache::* modules</A> chapter.
<P>
-Some folks decide to go mod_perl, but they miss the basic understanding of
-the perl, which is absolutely not tolerant by mod_perl. If you are such a
-person, there is nothing to be ashamed of, we all went through this. Get a
-good perl book and start reading. <A HREF="././perl.html#">Perl Reference</A> gives some basic perl lessons, delivering the knowledge you cannot start to
-program mod_perl scripts without.
+Some folks decide to go with mod_perl, but they are missing a basic
+understanding of Perl, which is absolutely not tolerated by mod_perl. If
+you are such a person, there is nothing to be ashamed of; we all went
+through this. Get a good Perl book and start reading. The <A HREF="././perl.html#">Perl Reference</A> chapter gives some basic perl lessons, delivering the knowledge without
+which you cannot start to program mod_perl scripts.
<P>
-<A HREF="././snippets.html#">Code Snippets</A> chapter is just a collection of code snippets I have found useful while
+The <A HREF="././snippets.html#">Code Snippets</A> chapter is just a collection of code snippets I have found useful while
writing the scripts.
<P>
-<A HREF="././help.html#">Getting Helped and Further Learning</A> refers you to other related information resources, like learning perl
-programming and SQL, understanding security, building databases and more.
+The <A HREF="././help.html#">Getting Helped and Further Learning</A> chapter refers you to other related information resources, like learning
+Perl programming and SQL, understanding security, building databases, and
+more.
<P>
<A HREF="././download.html#">Appendix A: Downloading software and documentation</A>
@@ -1126,7 +1147,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
@@ -1187,6 +1208,7 @@
<LI><A HREF="#Script_s_name_space">Script's name space</A>
<LI><A HREF="#Name_collisions_with_Modules_and">Name collisions with Modules and libs</A>
+ <LI><A HREF="#More_package_name_related_issues">More package name related issues</A>
<LI><A HREF="#_END_or_DATA_tokens">__END__ or __DATA__ tokens</A>
<LI><A HREF="#Output_from_system_calls">Output from system calls</A>
<LI><A HREF="#Using_format_">Using format()</A>
@@ -1204,6 +1226,7 @@
<LI><A HREF="#Passing_ENV_variables_to_CGI">Passing ENV variables to CGI</A>
<LI><A HREF="#Global_Variables">Global Variables</A>
<LI><A HREF="#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="#Apache_and_syslog">Apache and syslog</A>
<LI><A HREF="#Memory_leakage">Memory leakage</A>
</UL>
@@ -1213,6 +1236,7 @@
<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="#Reloading_handlers">Reloading handlers</A>
</UL>
<LI><A HREF="#Filehandlers_and_locks_leakages">Filehandlers and locks leakages</A>
@@ -1432,7 +1456,7 @@
use strict;
- print "Content-type: text/html\\r\\n\\r\\n";
+ print "Content-type: text/html\r\n\r\n";
my $counter = 0;
@@ -1442,7 +1466,7 @@
sub increment_counter{
$counter++;
- print "Counter is equal to $counter !<BR>\\n";
+ print "Counter is equal to $counter !<BR>\n";
}
}
@@ -1590,17 +1614,16 @@
site you have your account on (Free Email Account?). Now you want to see
what other users read.
+<P>
+You type in a username you want to peek at and a dummy password and try to
+enter the account. On some services it does works!!!
+
<P>
-You type in your name and passwd, and you expect to enter to your account,
-but instead you enter the account of someone else. This is cool isn't it?
-Is it a bug or feature. (For some of us it's a feature, while for others
-it's a bug.) You say, why in the world does this happen? The answer is
-simple: Global Variables. You have entered the account of someone who
-happened to be served by the same server child as you. Because of sloppy
-programming, a global variable was not reset at the beginning of the
-program and voila, you can easily peek into other people's emails! You
-would think that it can't happen, since you have entered the login and
-passwd. I tell you, it happens! See for yourself:
+You say, why in the world does this happen? The answer is simple:
+<STRONG>Global Variables</STRONG>. You have entered the account of someone who happened to be served by the
+same server child as you. Because of sloppy programming, a global variable
+was not reset at the beginning of the program and voila, you can easily
+peek into other people's emails! Here is an example of sloppy written code:
<P>
<PRE> use vars ($authenticated);
@@ -1650,7 +1673,7 @@
child that already cached the regexp and wouldn't recompile because of <STRONG>/o</STRONG>.) The example of such a case would be:
<P>
-<PRE> my $pat = '^foo$'; # likely to be input from an HTML form field
+<PRE> my $pat = $q->param("keyword");
foreach( @list ) {
print if /$pat/o;
}
@@ -1680,51 +1703,100 @@
<P>
To make things clear before we go into details: each child process has its
own <CODE>%INC</CODE> hash which is used to store information about its compiled modules. The
-keys of the hash are the names of the modules or parameters passed to <CODE>require()</CODE>. The values are the real paths to these modules. So if you do:
+keys of the hash are the names of the modules or parameters passed to <CODE>require()</CODE> (<CODE>use()</CODE>). The values are the full or relative paths to these modules/files. Let's
+say we have
+<CODE>my-lib.pl</CODE> and <CODE>MyModule.pm</CODE> both located at <CODE>/home/httpd/perl/my/</CODE>.
+
+<P>
+* <CODE>/home/httpd/perl/my/</CODE> is in the <CODE>@INC</CODE> path at the server startup.
+
+<P>
+<PRE> require "my-lib.pl";
+ use MyModule.pm;
+ print $INC{"my-lib.pl"},"\n";
+ print $INC{"MyModule.pm"},"\n";
+</PRE>
+<P>
+prints:
<P>
+<PRE> /home/httpd/perl/my/my-lib.pl
+ /home/httpd/perl/my/MyModule.pm
+</PRE>
+<P>
+Adding <CODE>use lib</CODE>:
+
+<P>
<PRE> use lib qw(.);
- require "./my/lib.pl";
+ require "my-lib.pl";
+ use MyModule.pm;
+ print $INC{"my-lib.pl"},"\n";
+ print $INC{"MyModule.pm"},"\n";
</PRE>
<P>
-where <CODE>./my/lib.pl</CODE> is actually a <CODE>/home/httpd/perl/my/lib.pl</CODE>. The following entry will show up in the <CODE>%INC</CODE>:
+prints:
<P>
-<PRE> print $INC{"./my/lib.pl"};
-
- printed result:
- ---------------
- /home/httpd/perl/my/lib.pl
+<PRE> my-lib.pl
+ MyModule.pm
+</PRE>
+<P>
+* <CODE>/home/httpd/perl/my/</CODE> isn't in the <CODE>@INC</CODE> path at the server startup.
+
+<P>
+<PRE> require "my-lib.pl";
+ use MyModule.pm;
+ print $INC{"my-lib.pl"},"\n";
+ print $INC{"MyModule.pm"},"\n";
+</PRE>
+<P>
+Wouldn't work, since perl cannot find the modules.
+
+<P>
+Adding <CODE>use lib</CODE>:
+
+<P>
+<PRE> use lib qw(.);
+ require "my-lib.pl";
+ use MyModule.pm;
+ print $INC{"my-lib.pl"},"\n";
+ print $INC{"MyModule.pm"},"\n";
+</PRE>
+<P>
+prints:
+
+<P>
+<PRE> my-lib.pl
+ MyModule.pm
</PRE>
<P>
I'm talking about single server child below!
<P>
-Let's look at 3 faulty scenarios:
+Let's look at 3 faulty script's name space related scenarios:
<DL>
<P><DT><STRONG><A NAME="item_Scenario">Scenario 1</A></STRONG><DD>
<P>
First, You can't have 2 identical module names running under the same
-server! Only the first one <CODE>use()'d</CODE> or <CODE>require()'d</CODE>
-will be compiled into the package, the request to the other identical
+server! Only the first one <CODE>use()</CODE>'d or <CODE>require()</CODE>'d will be compiled into the package, the request to the other identical
module will be skipped since server will think that it's already compiled.
It's already in the child's <CODE>%INC</CODE>. (See <A HREF="././status.html#Watching_the_server">Watching the server</A> section to find out how you can know what is loaded and where)
<P>
-So if you have two different <CODE>Foo</CODE> modules in two different directories and two scripts <CODE>script1.pl</CODE> and <CODE>script2.pl</CODE>, locate like:
+So if you have two different <CODE>Foo</CODE> modules in two different directories and two scripts <CODE>script1.pl</CODE> and <CODE>script2.pl</CODE>, placed like:
<P>
-<PRE> ./cgi/tool1/Foo.pm
- ./cgi/tool1/tool1.pl
- ./cgi/tool2/Foo.pm
- ./cgi/tool2/tool2.pl
+<PRE> ./perl/tool1/Foo.pm
+ ./perl/tool1/tool1.pl
+ ./perl/tool2/Foo.pm
+ ./perl/tool2/tool2.pl
</PRE>
<P>
Where a sample code could be:
<P>
-<PRE> ./cgi/tool1/tool1.pl
+<PRE> ./perl/tool1/tool1.pl
--------------------
use Foo;
print "Content-type: text/html\n\n";
@@ -1733,7 +1805,7 @@
--------------------
</PRE>
<P>
-<PRE> ./cgi/tool1/Foo.pm
+<PRE> ./perl/tool1/Foo.pm
--------------------
sub foo{
print "<B>I'm Tool Number One!</B><BR>\n";
@@ -1742,7 +1814,7 @@
--------------------
</PRE>
<P>
-<PRE> ./cgi/tool2/tool2.pl
+<PRE> ./perl/tool2/tool2.pl
--------------------
use Foo;
print "Content-type: text/html\n\n";
@@ -1751,7 +1823,7 @@
--------------------
</PRE>
<P>
-<PRE> ./cgi/tool2/Foo.pm
+<PRE> ./perl/tool2/Foo.pm
--------------------
sub foo{
print "<B>I'm Tool Number Two!</B><BR>\n";
@@ -1760,17 +1832,16 @@
--------------------
</PRE>
<P>
-And both scripts call: <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#Running_server_in_a_single_mode">single server mode</A> to detect that kind of bug immediately.
+And both scripts call: <CODE>use Foo;</CODE> -- only the first one called will know about <CODE>Foo</CODE>, when you will call the second script it will not know about <CODE>Foo</CODE> at all - it's like you've 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 detect this kind of bug immediately.
<P>
You will see the following in the error_log file:
<P>
<PRE> Undefined subroutine
- &Apache::ROOT::perl::tool2_2epl::some_function called at
- /home/httpd/perl/tool2.pl line 4.
+ &Apache::ROOT::perl::tool2::tool2_2epl::foo called at
+ /home/httpd/perl/tool2/tool2.pl line 4.
</PRE>
<P><DT><STRONG>Scenario 2</STRONG><DD>
<P>
@@ -1778,10 +1849,10 @@
have:
<P>
-<PRE> ./cgi/tool1/config.pl
- ./cgi/tool1/tool1.pl
- ./cgi/tool2/config.pl
- ./cgi/tool2/tool2.pl
+<PRE> ./perl/tool1/config.pl
+ ./perl/tool1/tool1.pl
+ ./perl/tool2/config.pl
+ ./perl/tool2/tool2.pl
</PRE>
<P>
And both scripts do:
@@ -1802,9 +1873,9 @@
What's interesting that the following scenario wouldn't work too!
<P>
-<PRE> ./cgi/tool/config.pl
- ./cgi/tool/tool1.pl
- ./cgi/tool/tool2.pl
+<PRE> ./perl/tool/config.pl
+ ./perl/tool/tool1.pl
+ ./perl/tool/tool2.pl
</PRE>
<P>
where <CODE>tool1.pl</CODE> and <CODE>tool2.pl</CODE> both <CODE>require()</CODE> the <STRONG>same</STRONG>
@@ -1823,13 +1894,13 @@
prefixes. The file system layout will be something like:
<P>
-<PRE> ./cgi/tool1/Tool1/Foo.pm
- ./cgi/tool1/tool1.pl
- ./cgi/tool2/Tool2/Foo.pm
- ./cgi/tool2/tool2.pl
+<PRE> ./perl/tool1/Tool1/Foo.pm
+ ./perl/tool1/tool1.pl
+ ./perl/tool2/Tool2/Foo.pm
+ ./perl/tool2/tool2.pl
</PRE>
<P>
-And change the scripts:
+And modify the scripts:
<P>
<PRE> use Tool1::Foo;
@@ -1839,10 +1910,10 @@
For <CODE>require()</CODE> (scenario number 2) use the following:
<P>
-<PRE> ./cgi/tool1/tool1-lib/config.pl
- ./cgi/tool1/tool1.pl
- ./cgi/tool2/tool2-lib/config.pl
- ./cgi/tool2/tool2.pl
+<PRE> ./perl/tool1/tool1-lib/config.pl
+ ./perl/tool1/tool1.pl
+ ./perl/tool2/tool2-lib/config.pl
+ ./perl/tool2/tool2.pl
</PRE>
<P>
And each script does respectively:
@@ -1854,12 +1925,13 @@
<P>
<PRE> use lib qw(.);
require "tool2-lib/config.pl";
-
-But this solution is very bad, since while it might work for you now,
-if you add another script that wants to use the same module or
-C<config.pl> file, it still wouldn't work as we saw in the third
-scenario. So let see better solutions.
</PRE>
+<P>
+But this solution isn't good, since while it might work for you now, if you
+add another script that wants to use the same module or
+<CODE>config.pl</CODE> file, it still wouldn't work as we saw in the third scenario. So let's see
+better solutions.
+
<P><DT><STRONG>Solution 2</STRONG><DD>
<P>
Another option is to use a full path to the script, so it'll be compiled
@@ -1881,13 +1953,16 @@
Declare a package in the required files! (Of course it should be unique to
the rest of the package names you use!) The <CODE>%INC</CODE> will use the package name for the key! It's a good idea to build at least 2
level package names for your private modules. (e.g. <CODE>MyProject::Carp</CODE>
-and not <CODE>Carp</CODE> for it will collide with existent standard package - even if as of the time
-of your coding it doesn't exist yet - it might enter the next perl
+and not <CODE>Carp</CODE>, since it will collide with existent standard package.) Even if as of the
+time of your coding it doesn't exist yet - it might enter the next perl
distribution as a standard module and your code will become broken. Foresee
-problems like this and save you a future trouble.)
+problems like this and save you a future trouble.
+
+<P>
+What are the implications of package declaration?
<P>
-When you <CODE>use()d</CODE> or <CODE>require()d</CODE> files without package declarations, it was very convenient since all the
+When you <CODE>use()'d</CODE> or <CODE>require()'d</CODE> files without package declarations, it was very convenient since all the
variables and subroutines were part of the <CODE>main::</CODE> package, so any of them could be used as if they were part of the main
script. With package declarations things get more complicated. To be
correct -- not complicated, but awkward, since you will have to use
@@ -1897,16 +1972,15 @@
defined variables inside <CODE>Package</CODE> (declared with <CODE>my()</CODE>).
<P>
-You can make things simpler by exporting the symbols from the
-<CODE>use()'d</CODE> package, like:
+ou still can leave your scripts unchanged if you import the names of the
+global variables and subs into a <STRONG>main::</STRONG> package's namespace, like:
<P>
-<PRE> use Package qw(:mysubs sub_b $var1 :myvars);
+<PRE> use Module qw(:mysubs sub_b $var1 :myvars);
</PRE>
<P>
-You can export both -- subroutines and global variables. This is a bad
-approach since it'll consume more memory for the current process. (See
-<CODE>perldoc Exporter</CODE> for information about exporting variables)
+You can export both -- subroutines and global variables. This isn't a good
+approach since it'll consume more memory for the current process. (See <CODE>perldoc Exporter</CODE> for information about exporting variables and other symbols)
<P>
This solution completely covers the third scenario. By using different
@@ -1915,14 +1989,32 @@
</DL>
<P>
-Read also perlmodlib and perlmod manpages.
+See also <CODE>perlmodlib</CODE> and <CODE>perlmod</CODE> manpages.
<P>
From the above discussion it should be clear that you cannot run a
-development and a production versions of the tools on the same server! You
-have to run a separate server for each (it still can be the same machine,
-but the server will use a different port).
+development and a production versions of the tools using the same apache
+server!
+
+<P>
+You have to run a separate server for each (it still can be the same
+machine, but the server will use a different port).
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="More_package_name_related_issues">More package name related issues</A></H2></CENTER>
+<P>
+If you have the following:
+
+<P>
+<PRE> PerlHandler Apache::Work::Foo
+ PerlHandler Apache::Work::Foo::Bar
+</PRE>
+<P>
+If you make a request that pulls in <CODE>Apache/Work/Foo/Bar.pm</CODE> first, then the <CODE>Apache::Work::Foo</CODE> package gets defined, so mod_perl does not try to pull in <CODE>Apache/Work/Foo.pm</CODE>
+
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="_END_or_DATA_tokens">__END__ or __DATA__ tokens</A></H2></CENTER>
@@ -1973,7 +2065,8 @@
}
</PRE>
<P>
-Now each time the select code is called, the correct <CODE>exit()</CODE> will be chosen, whether you run the script as a CGI or from the shell.
+Now the correct <CODE>exit()</CODE> will be always chosen, whether you run the script as a CGI or from the
+shell.
<P>
<STRONG>Note</STRONG> that if you run the script under <CODE>Apache::Registry</CODE>, <STRONG>The
@@ -2004,38 +2097,38 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Running_from_shell">Running from shell</A></H2></CENTER>
<P>
-Your scripts <STRONG>will not</STRONG> run from the command line (yet) unless you use CGI::Switch or CGI.pm and
-5.004+ and do not make any direct calls to Apache->methods.
+Your scripts <STRONG>will not</STRONG> run from the command line (yet) unless you use <CODE>CGI::Switch</CODE> or <CODE>CGI.pm</CODE> and perl 5.004+ and do not make any direct calls to <CODE>Apache-&gt;methods</CODE>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="I_O_is_different">I/O is different</A></H2></CENTER>
<P>
If you are using Perl 5.004 or better, most CGI scripts can run under
-mod_perl untouched. If you're using 5.003, Perl's built-in
-<CODE>read()</CODE> and <CODE>print()</CODE> functions do not work as they
-do under CGI. If you're using CGI.pm, use $query->print instead of plain 'ol <CODE>print().</CODE>
+mod_perl untouched. If you're using 5.003, Perl's built-in <CODE>read()</CODE>
+and <CODE>print()</CODE> functions do not work as they do under CGI. If you're using <CODE>CGI.pm</CODE>, use <CODE>$query-&gt;print</CODE> instead of plain 'ol
+<CODE>print()</CODE>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="HTTP_MIME_Headers_PerlSendHea">HTTP + MIME Headers (PerlSendHeader)</A></H2></CENTER>
<P>
By default, mod_perl does not send any headers by itself, however, you may
-wish to change this (in httpd.conf):
+wish to change this (in <CODE>httpd.conf</CODE>):
<P>
<PRE> PerlSendHeader On
</PRE>
<P>
Now the response line and common headers will be sent as they are by
-mod_cgi. And, just as with mod_cgi, <CODE>PerlSendHeader</CODE> will not send a terminating newline, your script must send that itself,
-e.g.:
+mod_cgi. And, just as with mod_cgi, <CODE>PerlSendHeader</CODE> will not send the MIME type and a terminating newline. Your script must
+send that itself, e.g.:
<P>
<PRE> print "Content-type: text/html\r\n\r\n";
</PRE>
<P>
-If you are using CGI.pm or CGI::Switch and <STRONG>print $q->header</STRONG> you do _not_ need <CODE>PerlSendHeader</CODE> On.
+If you are using <CODE>CGI.pm</CODE> or <CODE>CGI::Switch</CODE> and <STRONG>print
+$q->header</STRONG> you do _not_ need <CODE>PerlSendHeader</CODE> On.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -2067,7 +2160,7 @@
happens to be one that is compiling the code.
<P>
-<CODE>BEGIN</CODE> blocks in modules and files pulled in via <CODE>require()</CODE> and/or
+<CODE>BEGIN</CODE> blocks in modules and files pulled in via <CODE>require()</CODE> or
<CODE>use()</CODE> will be executed:
<UL>
@@ -2095,7 +2188,7 @@
</UL>
<P>
-<CODE>BEGIN</CODE> blocks in <CODE>Apache::Registry</CODE> scripts will be executed:
+<CODE>BEGIN</CODE> blocks in <CODE>Apache::Registry</CODE> scripts will be executed, as above plus:
<UL>
<P><LI>
@@ -2124,7 +2217,7 @@
<P>
As perlmod explains, an <CODE>END</CODE> subroutine is executed as late as possible, that is, when the interpreter
exits. In the mod_perl environment, the interpreter does not exit until the
-server is shutdown. However, mod_perl does make a special case for
+server shutdown. However, mod_perl does make a special case for
<CODE>Apache::Registry</CODE> scripts.
<P>
@@ -2132,16 +2225,18 @@
function, which is called once each time the Perl program is executed, e.g.
once per (mod_cgi) CGI scripts. However, mod_perl only calls
<STRONG>perl_run()</STRONG> once, during server startup. Any <CODE>END</CODE> blocks encountered during main server startup, i.e. those pulled in by the
-<CODE>PerlRequire</CODE> or by any <CODE>PerlModule</CODE>, are suspended and run at server shutdown, aka child_exit (requires apache
-1.3b3+).
+<CODE>PerlRequire</CODE> or by any <CODE>PerlModule</CODE>, are suspended and run at server shutdown, aka <CODE>child_exit()</CODE> (requires apache 1.3b3+).
<P>
Any <CODE>END</CODE> blocks that are encountered during compilation of
<CODE>Apache::Registry</CODE> scripts <STRONG>are called after the script has
completed</STRONG> (not during the cleanup phase though) including subsequent invocations when
-the script is cached in memory. All other <CODE>END</CODE>
-blocks encountered during other <CODE>Perl*Handler</CODE> call-backs, e.g.
-<CODE>PerlChildInitHandler</CODE>, will be suspended while the process is running and called during <CODE>child_exit()</CODE> when the process is shutting down. Module authors might wish to use $r->register_cleanup as an alternative to <CODE>END</CODE> blocks if this behavior is not desirable.
+the script is cached in memory.
+
+<P>
+All other <CODE>END</CODE> blocks encountered during other <CODE>Perl*Handler</CODE>
+call-backs, e.g. <CODE>PerlChildInitHandler</CODE>, will be suspended while the process is running and called during <CODE>child_exit()</CODE> when the process is shutting down. Module authors might wish to use
+<CODE>$r-&gt;register_cleanup</CODE> as an alternative to <CODE>END</CODE> blocks if this behavior is not 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>.
@@ -2247,8 +2342,8 @@
<P>
<CODE>diagnostics</CODE> pragma can shed more light on the errors and warnings you see, but again,
it's better not to use it in production, since otherwise you incur a huge
-overhead of the diagnostics pragma examining your every bit of code
-mod_perl executes. (You can run your script with <CODE>-dDprof</CODE> to check the overhead. See <CODE>Devel::Dprof</CODE> for more info).
+overhead of the diagnostics pragma examining every bit of the code mod_perl
+executes. (You can run your script with <CODE>-dDprof</CODE> to check the overhead. See <CODE>Devel::Dprof</CODE> for more info).
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -2293,11 +2388,23 @@
will set <CODE>$ENV{PERLDB_OPTS}</CODE>, and it'll be accessible in every child.
<P>
+<CODE>%ENV</CODE> is only setup for CGI emulation. If you are using the API, you should use <CODE>$r-&gt;subprocess_env</CODE>, <CODE>$r-&gt;notes</CODE> or
+<CODE>$r-&gt;pnotes</CODE> for passing data around between handlers. <CODE>%ENV</CODE> is slow because it must update the underlying C environment table, which
+also exposes that data to systems who can view with <CODE>ps</CODE>.
+
+<P>
+In any case, <CODE>%ENV</CODE> and the tables used by those methods are all cleared after the request is
+served. so, no, <CODE>$ENV{SESSION_ID}</CODE> will not be swaped or reused by different http requests.
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Global_Variables">Global Variables</A></H2></CENTER>
<P>
It's always a good idea to stay away from global variables when possible.
-Some variables must be global so Perl can see them, such as a module's <CODE>@ISA</CODE> or <CODE>$VERSION</CODE> variables. In common practice, a combination of <CODE>strict</CODE> and <CODE>vars</CODE> pragmas keeps modules clean and reduces a bit of noise. However, <CODE>vars</CODE> pragma also creates aliases as the <CODE>Exporter</CODE> does, which eat up more space. When possible, try to use fully qualified
+Some variables must be global so Perl can see them, such as a module's <CODE>@ISA</CODE> or <CODE>$VERSION</CODE> variables (or fully qualified
+<STRONG>@MyModule::ISA</STRONG>). In common practice, a combination of <CODE>strict</CODE> and
+<CODE>vars</CODE> pragmas keeps modules clean and reduces a bit of noise. However, <CODE>vars</CODE> pragma also creates aliases as the <CODE>Exporter</CODE>
+does, which eat up more memory. When possible, try to use fully qualified
names instead of use vars. Example:
<P>
@@ -2329,6 +2436,17 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Apache_and_syslog">Apache and syslog</A></H2></CENTER>
+<P>
+When native syslog support is enabled, the stderr stream will be redirected
+to <CODE>/dev/null</CODE>!
+
+<P>
+It has nothing to do with mod_perl (plain Apache does the same). Doug wrote
+a <A HREF="././modules.html#Apache_LogSTDERR">Apache::LogSTDERR</A> module to work around this
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Memory_leakage">Memory leakage</A></H2></CENTER>
<P>
Scripts under mod_perl can very easily leak memory! Global variables stay
@@ -2340,7 +2458,7 @@
it though!
<P>
-<STRONG>First example</STRONG> demonstrates reading a file:
+<STRONG>First example</STRONG> demonstrates reading in a whole file:
<P>
<PRE> open IN, $file or die $!;
@@ -2360,8 +2478,10 @@
<P>
<STRONG>Second example</STRONG> demonstrates copying variables between functions (passing variables by
value). Let's use the example above, assuming we have no choice but to read
-the whole file before any data processing. Now you have some imagine <CODE>process()</CODE> subroutine that processes the data and returns it back. What happens if you
-pass the <CODE>$content</CODE> by value? You have just copied another 5M and the child has grown by
+the whole file before any data processing takes place. Now you have some
+imagine <CODE>process()</CODE> subroutine that processes the data and returns it back. What happens if you
+pass the
+<CODE>$content</CODE> by value? You have just copied another 5M and the child has grown by
another 5M in size (watch your swap space!) now multiply it again by factor
of 20 you have 200M of wasted RAM, which will be apparently reused but it's
a waste! Whenever you think the variable can grow bigger than few Kb, pass
@@ -2422,12 +2542,12 @@
by reference or return the processed variable (e.g. <CODE>$content=process($content);</CODE>).
<P>
-<STRONG>Third example</STRONG> demonstrates work with DataBases. If you do some DB processing, many times
-you encounter the need to read lots of records into your program, and then
-print them to the browser after they are formatted. (I don't even mention
-the horrible case where programmers read in the whole DB and then use perl
-to process it!!! Use a relational DB and let the SQL do the job, so you get
-only the records you need!!!).
+<STRONG>Third example</STRONG> demonstrates a work with DataBases. If you do some DB processing, many
+times you encounter the need to read lots of records into your program, and
+then print them to the browser after they are formatted. (I don't even
+mention the horrible case where programmers read in the whole DB and then
+use perl to process it!!! Use a relational DB and let the SQL do the job,
+so you get only the records you need!!!).
<P>
We will use <CODE>DBI</CODE> for this (assume that we are already connected to the DB) (refer to <CODE>perldoc DBI</CODE> for a complete manual of the <CODE>DBI</CODE>
@@ -2475,7 +2595,8 @@
Note: the above method doesn't allow you to know how many records have been
matched. The workaround is to run an identical query before the code above
where you use <CODE>SELECT count(*) ...</CODE> instead of <CODE>'SELECT *
-...</CODE> to get the number of matched records.
+...</CODE> to get the number of matched records. It should be much faster, since you
+can remove any <STRONG>SORTBY</STRONG> and alike attributes.
<P>
For those who think that <STRONG>$sth->rows</STRONG> will do the job, here is the quote from the <CODE>DBI</CODE> manpage:
@@ -2650,7 +2771,7 @@
<CODE>Apache::StatINC</CODE> module.
<P>
-<CODE>Apache::StatINC</CODE> - Reload <CODE>%INC</CODE> files when updated on disk. When Perl pulls a file via require, it stores
+<CODE>Apache::StatINC</CODE> reloads <CODE>%INC</CODE> files when updated on disk. When Perl pulls a file via require, it stores
the filename in the global hash <CODE>%INC</CODE>. The next time Perl tries to require the same file, it sees the file in <CODE>%INC</CODE> and does not reload from disk. This module's handler iterates over <CODE>%INC</CODE> and reloads the file if it has changed on disk.
<P>
@@ -2676,20 +2797,38 @@
</Location>
</PRE>
<P>
-Beware that only the modules located in <CODE>@INC</CODE> are being reloaded on change, and you can change the <CODE>@INC</CODE> 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
-<CODE>@INC</CODE>. When you do <STRONG>use lib qw(foo/bar);</STRONG>, the <CODE>@INC</CODE> is being changed only for the time the code is being parsed and compiled.
+Beware that only the modules located in <CODE>@INC</CODE> are being reloaded on change, and you can change the <CODE>@INC</CODE> only before the server has been started (in startup file).
+
+<P>
+Whatever you do in your scripts and modules which are being <CODE>required()</CODE> after the server startup will not have any effect on <CODE>@INC</CODE>. When you do:
+
+<P>
+<PRE> use lib qw(foo/bar);
+</PRE>
+<P>
+the <CODE>@INC</CODE> is being changed only for the time the code is being parsed and compiled.
When it's over the <CODE>@INC</CODE> is being reset to its original value. To make sure that you have set a
correct <CODE>@INC</CODE> fetch <A
HREF="http://www.nowhere.com/perl-status?inc">http://www.nowhere.com/perl-status?inc</A>
-and watch the bottom of the page. (I assume you have configured the <Location /perl-status> section in <CODE>httpd.conf</CODE> as the mod_perl docs show.)
+and look at the bottom of the page. (I assume you have configured the <A HREF="././config.html#_perl_status_location">/perl-status location</A>.)
+
+<P>
+Also, notice the following caveat: While ``<CODE>.</CODE>'' is in the <CODE>@INC</CODE> -- perl knows to <CODE>require()</CODE> files relative to the script directory. Once the script was parsed - the
+server doesn't remember the path any more! So you end up with broken entry
+in <CODE>%INC</CODE> like:
<P>
+<PRE> $INC{bar.pl} eq "bar.pl"
+</PRE>
+<P>
+If you want Apache::StatINC to reload your script - modify the <CODE>@INC</CODE>
+at the server startup file! or use a full path in <CODE>require()</CODE> call.
+
+<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> every time can add a large overhead to server response times, and you
+Checking all the modules in <STRONG>%INC</STRONG> every time can add a large overhead to server response times, and you
certainly would not want
<CODE>Apache::StatINC</CODE> module to be enabled in your production site's configuration. But sometimes
you want to have some Configuration module to be reloaded without
@@ -2751,11 +2890,24 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Reloading_handlers">Reloading handlers</A></H2></CENTER>
+<P>
+If you want to reload perlhandler on each invocation, the following trick
+will do it:
+
+<P>
+<PRE> PerlHandler "sub { do 'MyTest.pm'; MyTest::handler(shift) }"
+</PRE>
+<P>
+<CODE>do()</CODE> will reload <CODE>MyTest.pm</CODE> every request.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Filehandlers_and_locks_leakages">Filehandlers and locks leakages</A></H1></CENTER>
<P>
-When you wrote a script running under mod_cgi, you could get away with
-sloppy programming, by opening a file and letting the interpreter to close
-it for you when the script had finished his run, like:
+When you write a script running under mod_cgi, you can get away with sloppy
+programming, like opening a file and letting the interpreter to close it
+for you when the script had finished his run:
<P>
<PRE> open IN, "in.txt" or die "Cannot open in.txt for reading : $!\n";
@@ -2903,8 +3055,7 @@
Done with script
</PRE>
<P>
-Then, uncomment the line where <CODE>$self</CODE> makes a circular
-reference, and you'll see:
+Then, uncomment the line where <CODE>$self</CODE> makes a circular reference, and you'll see:
<P>
<PRE> Done with script
@@ -3108,6 +3259,11 @@
chmod 0755, "$filename.marked";
</PRE>
<P>
+Also notice, that another solution is to move most of the code into a
+separare modules, which ensures that the line number will be reported
+correctly.
+
+<P>
To have a complete trace of calls add:
<P>
@@ -3124,14 +3280,14 @@
mod_rewrite, mod_log, mod_proxy, mod_spelling or whatever modules you have
used in your server, all the core routines and so on. A much wiser approach
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
+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 functions 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 external program to run.
@@ -3156,13 +3312,13 @@
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.
+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).
+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.
@@ -3245,7 +3401,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
@@ -3307,7 +3463,9 @@
<LI><A HREF="#Preload_Registry_Scripts">Preload Registry Scripts</A>
<LI><A HREF="#Avoid_Importing_Functions">Avoid Importing Functions</A>
- <LI><A HREF="#How_can_I_find_if_my_mod_perl_sc">How can I find if my mod_perl scripts have memory leaks (and where)</A>
+ <LI><A HREF="#Shared_Memory">Shared Memory</A>
+ <LI><A HREF="#Checking_script_modification_tim">Checking script modification times</A>
+ <LI><A HREF="#How_can_I_find_if_my_mod_perl_sc">How can I find if my mod_perl scripts have memory leaks</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>
@@ -3377,15 +3535,18 @@
there is nothing you can do if user has a slow connection on its behalf.
<P>
-From the other side, you might tune your scripts and webserver to process
-incoming requests ultra fast, so you will need a little number of working
-servers, but you might find out that server processes are busy waiting for
-slow clients to complete the download. You will see more examples in this
-chapter. My point is that a web service is like car, if one of the details
-or mechanisms is broken the car will not drive smoothly and it can even
-stop dead if pushed further without first fixing it.
+Moreover, you might tune your scripts and webserver to process incoming
+requests ultra fast, so you will need a little number of working servers,
+but you might find out that server processes are busy waiting for slow
+clients to complete the download. You will see more examples in this
+chapter.
<P>
+My point is that a web service is like car, if one of the details or
+mechanisms is broken the car will not drive smoothly and it can even stop
+dead if pushed further without first fixing it.
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Sharing_Memory">Sharing Memory</A></H1></CENTER>
<P>
@@ -3412,10 +3573,10 @@
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, because it inherits most of the preloaded code and the perl
-interpreter from the parent process. But then during the work of the child,
-its memory pages (which aren't really its yet, it uses the parent's pages)
-are getting dirty (originally inherited and shared variables are getting
-updated/modified) and the <STRONG>copy-on-write</STRONG>
+interpreter from the parent process. But than, during the work of the
+child, its memory pages (which aren't really its yet, it uses the parent's
+pages) are getting dirty (originally inherited and shared variables are
+getting updated/modified) and the <STRONG>copy-on-write</STRONG>
happens, which reduces the number of shared memory pages - thus enlarging
the memory demands. Killing the child and respawning a new one, allows to
get the pristine shared memory from the parent process again.
@@ -3799,8 +3960,44 @@
<CODE>Package::function</CODE> or <CODE>$Package::variable</CODE> like names instead.
<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Shared_Memory">Shared Memory</A></H1></CENTER>
+<P>
+You've probably noticed that the word shared is being repeated many times
+in many things related to mod_perl. Indeed, shared memory might save you a
+lot of money, since with sharing in place you can run many more servers
+than without it. See <A HREF="././performance.html#Choosing_MaxClients">the Formula and the numbers</A>.
+
+<P>
+How much shared memory do you have? You can see it by either using the
+memory utils that comes with your system or you can deploy <CODE>GTop</CODE>
+module:
+
+<P>
+<PRE> print "Shared memory of the current process: ",
+ GTop->new->proc_mem($$)->share,"\n";
+</PRE>
+<P>
+<PRE> print "Total shared memory: ",
+ GTop->new->mem->share,"\n";
+</PRE>
+<P>
+When you watch the output of the <CODE>top</CODE> utility, don't confuse <STRONG>RSS</STRONG>
+(or <STRONG>RES</STRONG>) column with <STRONG>SHARE</STRONG> column -- <STRONG>RES</STRONG> is a RESident memory, which is a size of pages currently swapped in.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Checking_script_modification_tim">Checking script modification times</A></H1></CENTER>
+<P>
+Under <CODE>Apache::Registry</CODE> the requested CGI script is always being
+<CODE>stat()</CODE>'ed to check whether it was modified. It adds a very little overhead, but
+if you are into squeezing all the jouces from the server, you might want to
+save this call. If you do -- take a look at
+<A HREF="././modules.html#">Apache::RegistryBB</A> module.
+
+<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_mod_perl_sc">How can I find if my mod_perl scripts have memory leaks (and where)</A></H1></CENTER>
+<CENTER><H1><A NAME="How_can_I_find_if_my_mod_perl_sc">How can I find if my mod_perl scripts have memory leaks</A></H1></CENTER>
<P>
<CODE>Apache::Leak</CODE> (derived from <CODE>Devel::Leak</CODE>) should help you with this task. Example:
@@ -3816,9 +4013,9 @@
</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
+might be leaking. Beware, it will run the code twice, because the first
time in, new <CODE>SV</CODE>s 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
+better evidence. You do not need to be inside mod_perl to use it, from the
command line, the above script outputs:
<P>
@@ -3831,13 +4028,39 @@
!!! 2 SVs leaked !!!
</PRE>
<P>
-Build a debuggable perl to see dumps of the <CODE>SV</CODE>s. the simple way to have both a normal perl and debuggable perl, is to
+Build a debuggable perl to see dumps of the <CODE>SV</CODE>s. The simple way to have both a normal perl and debuggable perl, is to
follow hints in the
<CODE>SUPPORT</CODE> doc for building <CODE>libperld.a</CODE>, when that is built copy the
<CODE>perl</CODE> from that directory to your perl bin directory, but name it
<CODE>dperl</CODE>.
<P>
+Leak explanation: <CODE>$$global = 1;</CODE> : new global variable created
+<CODE>FooAAA</CODE> with value of <CODE>1</CODE>, will not be destructed until this module is destroyed.
+
+<P>
+<CODE>Apache::Leak</CODE> is not very user-friendly, have a look at
+<CODE>B::LexInfo</CODE>. You'll see that what might appear to be a leak, is actually just a Perl
+optimization. e.g. consider this code:
+
+<P>
+<PRE> sub foo {
+ my $string = shift;
+ }
+</PRE>
+<P>
+<PRE> foo("a string");
+</PRE>
+<P>
+<CODE>B::LexInfo</CODE> will show you that Perl does not release the value from $string, unless you
+undef it. this is because Perl anticipates the memory will be needed for
+another string, the next time the subroutine is entered. you'll see similar
+for <CODE>@array</CODE> length, <CODE>%hash</CODE> keys, and scratch areas of the padlist for ops such as <CODE>join()</CODE>, `<CODE>.</CODE>', etc.
+
+<P>
+<CODE>Apache::Status</CODE> now includes a new StatusLexInfo option.
+
+<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>
<P>
@@ -4339,14 +4562,13 @@
1000 50 4.09
</PRE>
<P>
-Conclusions: Here I wanted to show that when the application is slow -- not
-due to perl loading, code compilation and execution, but bounded to some
-external operation like mysqld querying which made the bottleneck -- it
-almost does not matter what load we place on the server. The RPS (Requests
-per second) is almost the same (given that all the requests have been
-served, you have an ability to queue the clients, but be aware that
-something that goes to queue means a waiting client and a client (browser)
-that might time out!)
+<STRONG>Conclusions:</STRONG> Here I wanted to show that when the application is slow -- not due to perl
+loading, code compilation and execution, but bounded to some external
+operation like mysqld querying which made the bottleneck -- it almost does
+not matter what load we place on the server. The RPS (Requests per second)
+is almost the same (given that all the requests have been served, you have
+an ability to queue the clients, but be aware that something that goes to
+queue means a waiting client and a client (browser) that might time out!)
<P>
Now we will benchmark the same script without using the mysql (perl only
@@ -4372,9 +4594,9 @@
100000 400 24.95
</PRE>
<P>
-Conclusions: This time the script we executed was pure perl (not bounded to
-I/O or mysql), so we see that the server serves the requests much faster.
-You can see the <CODE>RequestPerSecond</CODE> (RPS) is almost the same for any load, but goes lower when the number of
+<STRONG>Conclusions:</STRONG> This time the script we executed was pure perl (not bounded to I/O or
+mysql), so we see that the server serves the requests much faster. You can
+see the <CODE>RequestPerSecond</CODE> (RPS) is almost the same for any load, but goes lower when the number of
concurrent clients goes beyond the <CODE>MaxClients</CODE>. With 25 RPS, the client supplying a 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,
@@ -4426,12 +4648,12 @@
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 throttling. It seems that 10 servers were serving requests 5
-times faster than 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
+<STRONG>Conclusions:</STRONG> A 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 throttling. It seems that 10 servers were serving requests 5 times
+faster than 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
<CODE>MaxClients</CODE>, doesn't mean that the performance will be better. You have just seen the
numbers!
@@ -4454,7 +4676,7 @@
1000 100 10 6.51
</PRE>
<P>
-Conclusions: When we drastically reduce the <CODE>MaxRequestsPerChild</CODE>, the performance starts to become closer to the plain mod_cgi. Just for
+<STRONG>Conclusions:</STRONG> When we drastically reduce the <CODE>MaxRequestsPerChild</CODE>, the performance starts to become closer to the plain mod_cgi. Just for
comparison with mod_cgi, here are the numbers of this run with mod_cgi:
<P>
@@ -4470,10 +4692,10 @@
1000 100 1.13
</PRE>
<P>
-Conclusion: mod_cgi is much slower :) in test NReq/NClients 100/10 the RPS
-in mod_cgi was of 1.12 and in mod_perl of 32, which is 30 times faster!!!
-In the first test each child waited about 100 secs to be served. In the
-second and third 1000 secs!
+<STRONG>Conclusion</STRONG>: mod_cgi is much slower :) in test NReq/NClients 100/10 the RPS in mod_cgi
+was of 1.12 and in mod_perl of 32, which is 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>
@@ -4488,10 +4710,9 @@
<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 within the time out period. 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 :).
+fail if not served within the time out period. You also get <STRONG>Latency</STRONG> (secs/Request) and
+<STRONG>Throughput</STRONG> (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
@@ -4638,7 +4859,7 @@
"Throughput" => sprintf("%.2f Requests/sec\n",
$nof_requests_total / $total_time),
"Latency" => sprintf("%.2f secs/Request",
- $ua->get_latency_total() /
+ ($ua->get_latency_total() || 0) /
$nof_requests_total),
);
@@ -4661,7 +4882,7 @@
<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
+supported; no more than this number of child server processes will be
created. To configure more than 256 clients, you must edit the <CODE>HARD_SERVER_LIMIT</CODE> entry in <CODE>httpd.h</CODE>
and recompile. In our case we want this variable to be as small as
possible, this way we can virtually bound the resources used by the server
@@ -4669,7 +4890,9 @@
<A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>) -- the calculation of <CODE>MaxClients</CODE> is pretty straightforward :
<P>
-<PRE> MaxClients = Total RAM Dedicated to the Webserver / MAX child's process size
+<PRE> Total RAM Dedicated to the Webserver
+ MaxClients = ------------------------------------
+ MAX child's process size
</PRE>
<P>
So if I have 400Mb left for the webserver to run with, I can set the
@@ -4699,7 +4922,7 @@
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 approach is to try not to have this condition
-reached at all, and if reached you should start to worry about it.
+reached at all, and if reach it often you should start to worry about it.
<P>
It's important to understand how much real memory a child occupies. Your
@@ -4711,15 +4934,57 @@
derive a much better formula:
<P>
-<PRE> MaxClients=(Total_RAM+Shared_RAM_per_Child*MaxClients)/Max_Process_Size-1
+<PRE> Total_RAM + Shared_RAM_per_Child * MaxClients
+ MaxClients = ---------------------------------------------
+ Max_Process_Size - 1
</PRE>
<P>
which is:
+<P>
+<PRE> Total_RAM - Max_Process_Size
+ MaxClients = ---------------------------------------
+ Max_Process_Size - Shared_RAM_per_Child
+</PRE>
+<P>
+Let's roll some calculations:
+
+<P>
+<PRE> Total_RAM = 500Mb
+ Max_Process_Size = 10Mb
+ Shared_RAM_per_Child = 4Mb
+</PRE>
+<P>
+<PRE> 500 - 10
+ MaxClients = --------- = 81
+ 10 - 4
+</PRE>
+<P>
+With no sharing in place
+
+<P>
+<PRE> 500
+ MaxClients = --------- = 50
+ 10
+</PRE>
+<P>
+With sharing in place you can have 60% more servers without purchasing more
+RAM, if you improve and keep the sharing level, let's say:
+
<P>
-<PRE> MaxClients=(Total_RAM-Max_Process_Size)/(Max_Process_Size-Shared_RAM_per_Child)
+<PRE> Total_RAM = 500Mb
+ Max_Process_Size = 10Mb
+ Shared_RAM_per_Child = 8Mb
</PRE>
<P>
+<PRE> 500 - 10
+ MaxClients = --------- = 245
+ 10 - 8
+</PRE>
+<P>
+390% more servers!!! You've got the point :)
+
+<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>
@@ -4740,8 +5005,8 @@
starvation. Note, that sometimes standard system libraries leak memory too,
especially on OSes with bad memory management (e.g. Solaris 2.5 on x86
arch). If this is your case you can set <CODE>MaxRequestsPerChild</CODE> to a small number, which will allow the system to reclaim the memory,
-greedy child process consumed, when it exits after <CODE>MaxRequestsPerChild</CODE> requests. But beware -- if you set this number too low, you will loose the
-speed bonus you receive with mod_perl. Consider using <CODE>Apache::PerlRun</CODE> if this is the case. Also setting <CODE>MaxSpareServers</CODE> to a number close to
+greedy child process consumed, when it exits after <CODE>MaxRequestsPerChild</CODE> requests. But beware -- if you set this number too low, you will loose a
+fracture of the speed bonus you receive with mod_perl. Consider using <CODE>Apache::PerlRun</CODE> if this is the case. Also setting <CODE>MaxSpareServers</CODE> to a number close to
<CODE>MaxClients</CODE>, will improve the response time (but your parent process will be busy
respawning new children all the time!)
@@ -4772,7 +5037,7 @@
<CODE>MaxClients</CODE> has been chosen to take the full advantage of the resources), but it'll
make sure that at any given moment your system will be capable of
responding to requests with the maximum speed (given that number of
-concurrent requests is not higher then
+concurrent requests is not higher than
<CODE>MaxClients</CODE>.)
<P>
@@ -5036,14 +5301,13 @@
produce the results of the DB query, which might take some time to
complete, I want users to get some titles ahead. This improves the
usability of my site. Recall yourself: What do you like better: getting the
-output a bit slower, but steadily from the moment you've pressed the Submit
-button or having to watch the ``falling stars'' for awhile and then to
+output a bit slower, but steadily from the moment you've pressed the <STRONG>Submit</STRONG> button or having to watch the ``falling stars'' for awhile and then to
receive the whole output at once, even a few millisecs faster (if the
client (browser) did not time out till then).
<P>
-Conclusion: Do not blindly follow suggestions, but think what is best for
-you in every given case.
+<STRONG>Conclusion</STRONG>: Do not blindly follow 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>
@@ -5170,7 +5434,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 08/16/1999
</FONT>
</B>
</TD>
@@ -5302,7 +5566,7 @@
and work on getting your feet wet with apache and mod_perl. Later, you can
decide whether to move to the second one which allows better tuning at the
expense of more complicated administration, or to the third option -- the
-more state-of-the-art-yet-suspiciously-new DSO system, or to the forth
+more state-of-the-art-yet-suspiciously-new DSO system, or to the fourth
option which gives you even more power.
<OL>
@@ -5440,9 +5704,10 @@
<CENTER><H1><A NAME="One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl-enabled Apache Servers</A></H1></CENTER>
<P>
As I have mentioned before, when running scripts under mod_perl, you will
-notice that the httpd processes consume a huge amount of memory, from 5M to
-25M, or even more. That is the price you pay for the enormous speed
-improvements under mod_perl. (Again -- shared memory keeps them smaller :)
+notice that the httpd processes consume a huge amount of virtual memory,
+from 5Mb to 15Mb and even more. That is the price you pay for the enormous
+speed improvements under mod_perl. (Again -- shared memory keeps the real
+memory that is being used much smaller :)
<P>
Using these large processes to serve static objects like images and html
@@ -5596,14 +5861,17 @@
At the beginning there were 2 servers: one - plain apache server, which was <STRONG>very light</STRONG>, and configured to serve static objects, the other -- mod_perl enabled,
which was <STRONG>very heavy</STRONG> 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
+by listening to different ports: 80 -- for <CODE>httpd_docs</CODE>
+(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
+) and 8080 -- for
+<CODE>httpd_perl</CODE> (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. (Later on, I will be
-moving the httpd_docs server to port 81.)
+moving the
+<CODE>httpd_docs</CODE> server to port 81.)
<P>
Now I am going to convince you that you <STRONG>want</STRONG> to use a proxy server (in the http accelerator mode). The advantages are:
@@ -5612,7 +5880,7 @@
<P><LI>
<P>
Allow serving of static objects from the proxy's cache (objects that
-previously were entirely served by the httpd_docs server).
+previously were entirely served by the <CODE>httpd_docs</CODE> server).
<P><LI>
<P>
@@ -5648,9 +5916,9 @@
to you as an exercise :)
<P>
-To make your download time numbers even worse, let me remind you that many
-users like to open many browser windows and do many things at once
-(download files and browse <STRONG>heavy</STRONG> sites). So the speed of 3.6kb/sec we were assuming before, may many times
+To make your estimation of download time numbers even worse, let me remind
+you that many users like to open many browser windows and do many things at
+once (download files and browse <STRONG>heavy</STRONG> sites). So the speed of 3.6kb/sec we were assuming before, may many times
be 5-10 times slower.
<P><LI>
@@ -5759,14 +6027,14 @@
<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.
+HTTP protocol level. Squid is pretty much a <CODE>HTTP/1.0</CODE> server, which seriously limits the deployment of <CODE>HTTP/1.1</CODE> features.
<P><LI>
<P>
-HTTP headers / dates, freshness. The squid server might give out ``old''
+HTTP headers, dates and freshness. The squid server might give out ``old''
pages, confusing downstream/client caches. Also chances are that you will
-be giving out stale pages.
+be giving out stale pages. (You update the some documents on the site, but
+squid will still serve the old ones.)
<P><LI>
<P>
@@ -5790,9 +6058,9 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="An_Apache_s_mod_proxy">An 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
+I do not think the difference in speed between apache's <STRONG>mod_proxy</STRONG>
+and <STRONG>squid</STRONG> 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
@@ -5827,7 +6095,7 @@
</PRE>
<P><LI>
<P>
-It does mod_perl output buffering like squid does. See the <A HREF="././scenario.html#Using_mod_proxy">Using mod_proxy</A> notes for more details.
+It does mod_perl output buffering like squid does. See the <A HREF="././scenario.html#Building_and_Using_mod_proxy">Using mod_proxy</A> notes for more details.
<P><LI>
<P>
@@ -5863,7 +6131,7 @@
</UL>
<P>
-For implementation see <A HREF="././scenario.html#Using_mod_proxy">Using mod_proxy</A>.
+For implementation see <A HREF="././scenario.html#Building_and_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/">
@@ -5888,7 +6156,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 07/02/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
@@ -5969,7 +6237,7 @@
<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="#Building_and_Using_mod_proxy">Building and Using mod_proxy</A>
<LI><A HREF="#mod_perl_server_as_DSO">mod_perl server as DSO</A>
<LI><A HREF="#HTTP_Authentication_with_2_serve">HTTP Authentication with 2 servers + proxy</A>
</UL>
@@ -6068,8 +6336,8 @@
<PRE> % make && make test && make install
</PRE>
<P>
-Note that if <CODE>make</CODE> fails, neither <CODE>make test</CODE> nor <CODE>make
-install</CODE> will be executed. If <CODE>make test</CODE> fails, <CODE>make install</CODE>
+Note that if <STRONG>make</STRONG> fails, neither <STRONG>make test</STRONG> nor <STRONG>make
+install</STRONG> will be not executed. If <STRONG>make test</STRONG> fails, <STRONG>make install</STRONG>
will be not executed.
<P>
@@ -6085,7 +6353,7 @@
you how to start a freshly built webserver (the path of the
<CODE>apachectl</CODE>, more about it later) and where the configuration files are. Remember (or
even better write down) both, since you will need this information very
-soon. On my machine they two important paths are:
+soon. On my machine the two important paths are:
<P>
<PRE> /usr/local/apache/bin/apachectl
@@ -6333,7 +6601,7 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A></H2></CENTER>
<P>
-Let's proceed with instalation. I will use x.x.x instead of real version
+Let's proceed with installation. I will use x.x.x instead of real version
numbers so this document will never become obsolete :).
<P>
@@ -6530,7 +6798,7 @@
<P>
The 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
+machine. Here we will use <CODE>8080</CODE>. 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
@@ -6543,7 +6811,7 @@
<P>
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>.
+and <A HREF="././scenario.html#Building_and_Using_mod_proxy">Using mod_proxy</A>.
<P>
Now we proceed to mod_perl specific directives. A good idea will be to add
@@ -6610,7 +6878,7 @@
installed, you just need to modify the default <CODE>squid.conf</CODE> the way I will explain below, then you are ready to run it.
<P>
-First, lets understand what do we have in hands and what do we want from
+First, let's understand what do we have in hands and what do we want from
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
@@ -6696,8 +6964,11 @@
want your scripts to be more complying with the HTTP standards, the headers
of your scripts should carry the <CODE>Caching Directives</CODE>
according to the HTTP specs. You will find a complete tutorial about this
-topic in <CODE>Tutorial on HTTP Headers for mod_perl users</CODE> by Andreas J. Koenig. If you set the headers correctly there is no need to
-tell squid accelerator to <STRONG>NOT</STRONG> try to cache something. The headers I am talking about are <CODE>Last-Modified</CODE> and <CODE>Expires</CODE>. What are they good for? Squid would not bother your mod_perl server a
+topic in <CODE>Tutorial on HTTP Headers for mod_perl users</CODE> by Andreas J. Koenig (at <A
+HREF="http://perl.apache.org">http://perl.apache.org</A> ). If you set the
+headers correctly there is no need to tell squid accelerator to <STRONG>NOT</STRONG>
+try to cache something. The headers I am talking about are
+<CODE>Last-Modified</CODE> and <CODE>Expires</CODE>. What are they good for? Squid would not bother your mod_perl server a
second time if a request is (a) cachable and (b) still in the cache. Many
mod_perl applications will produce identical results on identical requests
at least if not much time goes by between the requests. So your squid might
@@ -6853,13 +7124,14 @@
<P>
Almost... When you try the new setup, you will be surprised and upset to
-discover the port 81 showing up in the URLs of the static objects (like
+discover a port 81 showing up in the URLs of the static objects (like
htmls). Hey, we did not want the user to see the port 81 and use it instead
-of 80, since than it will bypass the squid server and the hard work we went
-through was just a waste of time? The solution is to run both squid and
-httpd_docs on the same port. This can be accomplished by binding each one
-to a specific interface. Modify the
-<CODE>httpd.conf</CODE> in the <CODE>httpd_docs</CODE> configuration directory:
+of 80, since then it will bypass the squid server and the hard work we went
+through was just a waste of time?
+
+<P>
+The solution is to run both squid and httpd_docs at the same port. This can
+be accomplished by binding each one to a specific interface. Modify the <CODE>httpd.conf</CODE> in the <CODE>httpd_docs</CODE> configuration directory:
<P>
<PRE> Port 80
@@ -6891,16 +7163,19 @@
references, using the 8080 or other port -- you should fix them to generate
links to point to port 80 (which means not using the port at all). If you
do not, users will bypass squid, like if it was not there at all, by making
-direct requests to the mod_perl server's port. The only question left is
-what to do with users who bookmarked your services and they still have the
-port 8080 inside the URL. Do not worry about it. The most important thing
-is for your scripts to return a full URLs, so if the user comes from the
-link with 8080 port inside, let it be. Just make sure that all the
-consecutive calls to your server will be rewritten correctly. During a
-period of time users will change their bookmarks. What can be done is to
-send them an email if 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 in first place. See <A HREF="././config.html#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>.
+direct requests to the mod_perl server's port.
+
+<P>
+The only question left is what to do with users who bookmarked your
+services and they still have the port 8080 inside the URL. Do not worry
+about it. The most important thing is for your scripts to return a full
+URLs, so if the user comes from the link with 8080 port inside, let it be.
+Just make sure that all the consecutive calls to your server will be
+rewritten correctly. During a period of time users will change their
+bookmarks. What can be done is to send them an email if 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 in first
+place. See <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.
@@ -6912,8 +7187,7 @@
logged. </META>
<P>
-See <A HREF="././scenario.html#Using_mod_proxy">Using mod_proxy</A> for information about
-<CODE>X-Forwarded-For</CODE>.
+See <A HREF="././scenario.html#Building_and_Using_mod_proxy">Using mod_proxy</A> for information about <CODE>X-Forwarded-For</CODE>.
<P>
To save you some keystrokes, here is the whole modified <CODE>squid.conf</CODE>:
@@ -7051,8 +7325,11 @@
</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Using_mod_proxy">Using mod_proxy</A></H1></CENTER>
+<CENTER><H1><A NAME="Building_and_Using_mod_proxy">Building and Using mod_proxy</A></H1></CENTER>
<P>
+To build it into apache just add <STRONG>--enable-module=proxy</STRONG> during the apache <STRONG>configure</STRONG> stage.
+
+<P>
Now we will talk about apache's mod_proxy and understand how it works.
<P>
@@ -7060,7 +7337,7 @@
mod_perl enabled server in the following way:
<P>
-<PRE> ProxyPass /modperl/ <A HREF="http://localhost:81/modperl/">http://localhost:81/modperl/</A>
+<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>
@@ -7209,7 +7486,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 07/02/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
@@ -7739,7 +8016,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 07/02/1999
+ <BR>Last Modified at 07/09/1999
</FONT>
</B>
</TD>
@@ -7902,7 +8179,7 @@
For example, using the above configuration, fetching
<CODE>http://www.nowhere.com/perl/test.pl</CODE>, will cause the server to look for the file <CODE>test.pl</CODE> at <CODE>/usr/local/myproject/cgi</CODE>, and execute it as an <CODE>Apache::Registry</CODE> script if we define <CODE>Apache::Registry</CODE> to be the handler of <CODE>/perl</CODE> location (see below). The URL
<CODE>http://www.nowhere.com/perl/test.pl</CODE> will be mapped to
-<CODE>/usr/local/myproject/cgi/test.pl</CODE>. This means that you can have all your CGIs located at the same place at
+<CODE>/usr/local/myproject/cgi/test.pl</CODE>. This means that you can have all your CGIs located at the same place in
the file-system, and call the script in any of three modes simply by
changing the directory name component of the URL (<CODE>cgi-bin|perl|cgi-perl</CODE>) - is not this neat? (That is the configuration you see above - all three
Aliases point to the same directory within your file system, but of course
@@ -7926,9 +8203,9 @@
<P>
Of course you can choose any other Alias (you will use it later in
-<CODE>httpd.conf</CODE>), 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.
+<CODE>httpd.conf</CODE>), you can choose to use all three modes or only one of these. It is
+undesirable to run scripts in plain mod_cgi from a mod_perl-enabled server
+- the price is too high, it is better to run these on plain apache server.
(See <A HREF="././strategy.html#Standalone_mod_perl_Enabled_Apac">Standalone mod_perl Enabled Apache Server</A>)
<P>
@@ -8033,7 +8310,7 @@
</Location>
</PRE>
<P>
-If you are going to use <CODE>Apache::Status</CODE>. It's important to put it as a first module in the start-up file, or in
+If you are going to use <CODE>Apache::Status</CODE>, it's important to put it as a first module in the start-up file, or in
the <CODE>httpd.conf</CODE> (after
<CODE>Apache::Registry</CODE>):
@@ -8453,6 +8730,14 @@
Makefile.PL PERL_SECTIONS=1</STRONG>.
<P>
+You can watch how have you configured the <CODE><Perl</CODE>> sections through the <A HREF="././config.html#_perl_status_location">/perl-status</A> location, by choosing the <STRONG>Perl Sections</STRONG> from the menu.
+
+<P>
+<A
+HREF="http://www.modperl.com/book/chapters/ch8.html#Debugging_B_E_lt_PerlE_gt_Sect">http://www.modperl.com/book/chapters/ch8.html#Debugging_B_E_lt_PerlE_gt_Sect</A>
+shows how can you dump the contents of your <CODE><Perl</CODE>> sections to the error_log.
+
+<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>
<P>
@@ -8752,7 +9037,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 07/02/1999
+ <BR>Last Modified at 08/15/1999
</FONT>
</B>
</TD>
@@ -8870,7 +9155,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 05/08/1999
+ <BR>Last Modified at 07/09/1999
</FONT>
</B>
</TD>
@@ -8952,13 +9237,12 @@
<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
+The easiest way to find the PID is to look it up in the <CODE>httpd.pid</CODE> file. With my configuration it exists as
+<CODE>/usr/local/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> PidFile /usr/local/var/httpd_perl/run/httpd.pid
</PRE>
<P>
Another way is to use the <CODE>ps</CODE> and <CODE>grep</CODE> utilities:
@@ -8973,18 +9257,16 @@
<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="././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
+This will produce a list of all <CODE>httpd_perl</CODE> (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
<CODE>httpd.conf</CODE>), but it's still easy to know 'who is the parent' -- the one of the
smallest size...
<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
+You will notice many <CODE>httpd_perl</CODE> 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: <STRONG>TERM</STRONG>, <STRONG>HUP</STRONG>, and <STRONG>USR1</STRONG>.
<P>
@@ -9052,9 +9334,10 @@
</DL>
<P>
It's worth mentioning that restart or termination can sometimes take quite
-a lot of time. Check out the <CODE>PERL_DESTRUCT_LEVEL=-1</CODE> option during the mod_perl <CODE>./Configure</CODE> stage, which speeds this up and leads to more robust operation in the face
+a lot of time. Check out the <CODE>PERL_DESTRUCT_LEVEL=-1</CODE> option during the mod_perl <CODE>perl Makefile.PL</CODE> 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 <CODE>END</CODE> blocks and <CODE>DESTROY</CODE> methods when the child terminates, of course. What constitutes significant
+significant cleanup has to be done by perl <CODE>END</CODE>
+blocks and <CODE>DESTROY</CODE> 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.
@@ -9076,42 +9359,39 @@
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
-<CODE>/usr/apps/sbin/httpd_perl/apachectl</CODE>.
+<CODE>/usr/local/sbin/httpd_perl/apachectl</CODE>.
<P>
Start httpd:
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl start
+<PRE> % /usr/local/sbin/httpd_perl/apachectl start
</PRE>
<P>
Stop httpd:
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl stop
+<PRE> % /usr/local/sbin/httpd_perl/apachectl stop
</PRE>
<P>
Restart httpd if running by sending a <STRONG>SIGHUP</STRONG> or start if not running:
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl restart
+<PRE> % /usr/local/sbin/httpd_perl/apachectl restart
</PRE>
<P>
Do a graceful restart by sending a <STRONG>SIGUSR1</STRONG> or start if not running:
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl graceful
+<PRE> % /usr/local/sbin/httpd_perl/apachectl graceful
</PRE>
<P>
Do a configuration syntax test:
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl configtest
+<PRE> % /usr/local/sbin/httpd_perl/apachectl configtest
</PRE>
<P>
-See the next section for the implication of the above calls.
-
-<P>
Replace <CODE>httpd_perl</CODE> with <CODE>httpd_docs</CODE> in the above calls to control the <STRONG>httpd_docs</STRONG> server.
<P>
@@ -9119,7 +9399,7 @@
<P>
It's important to understand that this script is based on the PID file
-which is <CODE>PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid</CODE>. If you delete the file by hand - <STRONG>apachectl</STRONG> will fail to run.
+which is <CODE>PIDFILE=/usr/local/var/httpd_perl/run/httpd.pid</CODE>. If you delete the file by hand - <STRONG>apachectl</STRONG> will fail to run.
<P>
Also, notice that <STRONG>apachectl</STRONG> is suitable to use from within your Unix system's startup files so that
@@ -9224,10 +9504,10 @@
#EMAIL=root@localhost
# the path to your PID file
- PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid
+ PIDFILE=/usr/local/var/httpd_perl/run/httpd.pid
# the path to your httpd binary, including options if necessary
- HTTPD=/usr/apps/sbin/httpd_perl/httpd_perl
+ HTTPD=/usr/local/sbin/httpd_perl/httpd_perl
# check for pidfile
if [ -f $PIDFILE ] ; then
@@ -9257,23 +9537,24 @@
fi
</PRE>
<P>
-Another approach, probably even more practical, is to use the cool
-<CODE>LWP</CODE> 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, 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.
+Another approach, probably even more practical, is to use the cool <CODE>LWP</CODE>
+perl package , to test the server by trying to fetch some document (script)
+served by the server. Why is it more practical? Because, while server can
+be up as a process, it can be stuck and not working, 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>
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,
+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.
+writing to an <CODE>error_log</CODE> file. Think big -- if you are 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>
So we end up with crontab entry:
@@ -9294,14 +9575,16 @@
my $VERSION = '0.01';
use vars qw($ua $proxy);
-
- require LWP::UserAgent;
+ $proxy = '';
+</PRE>
+<P>
+<PRE> require LWP::UserAgent;
use HTTP::Status;
###### 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 $restart_command = '/usr/local/sbin/httpd_perl/apachectl restart';
my $mail_program = '/usr/lib/sendmail -t -n';
######################
@@ -9378,7 +9661,7 @@
allowing you to run it more easily under debugger control.
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/httpd_perl -X
+<PRE> % /usr/local/sbin/httpd_perl/httpd_perl -X
</PRE>
<P>
When you execute the above the server will run in the fg (foreground) of
@@ -9431,8 +9714,8 @@
# 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
+ PidFile /usr/local/var/httpd_perl/run/httpd.pid.sbekman
+ ErrorLog /usr/local/var/httpd_perl/logs/error_log.sbekman
Timeout 300
KeepAlive On
MinSpareServers 2
@@ -9446,8 +9729,8 @@
# 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
+ PidFile /usr/local/var/httpd_perl/run/httpd.pid.userfoo
+ ErrorLog /usr/local/var/httpd_perl/logs/error_log.userfoo
Timeout 300
KeepAlive Off
MinSpareServers 1
@@ -9465,13 +9748,13 @@
<P>
To make things even easier. (In the above technique, you have to discover
-the PID of your parent httpd_perl process - written in
-<CODE>/usr/apps/var/httpd_perl/run/httpd.pid.userfoo</CODE>) . We change the
+the PID of your parent <CODE>httpd_perl</CODE> process - written in
+<CODE>/usr/local/var/httpd_perl/run/httpd.pid.userfoo</CODE>) . 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>
-<PRE> PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid.sbekman
- HTTPD='/usr/apps/sbin/httpd_perl/httpd_perl -Dsbekman'
+<PRE> PIDFILE=/usr/local/var/httpd_perl/run/httpd.pid.sbekman
+ HTTPD='/usr/local/sbin/httpd_perl/httpd_perl -Dsbekman'
</PRE>
<P>
Of course you think you can use only one control file and know who is
@@ -9483,7 +9766,7 @@
mode by:
<P>
-<PRE> /usr/apps/sbin/httpd_perl/httpd_perl -Dsbekman -X
+<PRE> /usr/local/sbin/httpd_perl/httpd_perl -Dsbekman -X
</PRE>
<P>
In addition to making life easier, we decided to use relative links
@@ -9492,8 +9775,7 @@
we have utilized the mod_rewrite to solve our problems:
<P>
-In access.conf of the httpd_docs server we have the following code: (you
-have to configure your httpd_docs server with
+In <CODE>access.conf</CODE> of the <CODE>httpd_docs</CODE> server we have the following code: (you have to configure your <CODE>httpd_docs</CODE> server with
<CODE>--enable-module=rewrite</CODE> )
<P>
@@ -9501,17 +9783,17 @@
# 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]
+ RewriteRule ^(.*) <A HREF="http://nowhere.com:8000/">http://nowhere.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]
+ RewriteRule ^(.*) <A HREF="http://nowhere.com:8001/">http://nowhere.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]
+ RewriteRule ^(.*) <A HREF="http://nowhere.com:81/">http://nowhere.com:81/</A>$1 [R]
</PRE>
<P>
@@ -9520,7 +9802,7 @@
<CODE>REMOTE_USER</CODE> since we have all the users authenticated but it did not work for me)
<P>
-So if I have a relative URL like <CODE>/perl/test.pl</CODE> written in some html or even <CODE>http://www.nowhere.com/perl/test.pl</CODE> in my case (user at machine of <CODE>sbekman</CODE>) it will be redirected by httpd_docs to
+So if I have a relative URL like <CODE>/perl/test.pl</CODE> written in some html or even <CODE>http://www.nowhere.com/perl/test.pl</CODE> in my case (user at machine of <CODE>sbekman</CODE>) it will be redirected by <CODE>httpd_docs</CODE> to
<CODE>http://www.nowhere.com:8000/perl/test.pl</CODE>.
<P>
@@ -9570,7 +9852,7 @@
params, which will not happen when you call the cgi from the web)
<P>
-<PRE> #!/usr/apps/bin/perl -w
+<PRE> #!/usr/local/bin/perl -w
# This is a wrapper example
@@ -9584,18 +9866,19 @@
BEGIN{
use vars qw($basedir);
- $basedir = "/usr/apps";
+ $basedir = "/usr/local";
- # we want to make a complete emulation, so we must remove the
- # user's environment
+ # 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",
- );
+ push @INC,
+ qw($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;
@@ -9610,7 +9893,8 @@
# Set the environment
my $PERL5LIB = join ":", @INC;
- # if the path includes the directory we extract it and chdir there
+ # 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";
@@ -9619,7 +9903,7 @@
}
# run the cgi from the script's directory
- # Note that we invoke warnings and Taintness ON!!!
+ # Note that we invoke warnings and Taint mode ON!!!
system qq{$basedir/bin/perl -I$PERL5LIB -Tw $cgi $params};
</PRE>
<P>
@@ -9649,7 +9933,7 @@
I use this script:
<P>
-<PRE> #!/usr/apps/bin/perl -Tw
+<PRE> #!/usr/local/bin/perl -Tw
# this script does a log rotation. Called from crontab.
@@ -9660,9 +9944,9 @@
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 $logs_dir = "/usr/local/var/$server/logs";
+ my $restart_command = "/usr/local/sbin/$server/apachectl restart";
+ my $gzip_exec = "/usr/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;
@@ -9790,8 +10074,8 @@
<P>
<PRE> sub UNIVERSAL::AUTOLOAD {
- my $class = shift;
- warn "$class can't \$UNIVERSAL::AUTOLOAD!\n";
+ my $class = shift;
+ warn "$class can't \$UNIVERSAL::AUTOLOAD!\n";
}
</PRE>
<P>
@@ -9809,6 +10093,7 @@
<P>
<PRE> S=`ls -s /usr/local/apache/logs/error_log | awk '{print $1}'`
if [ "$S" -gt 100000 ] ; then
+ mv /usr/local/apache/logs/error_log /usr/local/apache/logs/error_log.old
/etc/rc.d/init.d/httpd restart
date | /bin/mail -s "error_log $S kB on inx" myemail@domain.com
fi
@@ -9859,7 +10144,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/27/1999
+ <BR>Last Modified at 08/05/1999
</FONT>
</B>
</TD>
@@ -10187,7 +10472,7 @@
<PRE> "\377" =~ /$pat|^[\377]$/; # guaranteed if meta-characters present
</PRE>
<P>
-Phil. Chu contributed this:
+Another approach:
<P>
It depends on the complexity of the regexp you apply this technique to. One
@@ -10197,7 +10482,7 @@
<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:
+Regex''.
<P>
<PRE> #####################################################
@@ -10381,7 +10666,7 @@
<P>
Here is the working example. Run the server with <CODE>-X</CODE>, Press <STRONG>STOP</STRONG>
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.
+hang in <CODE>while(1)</CODE>! The resource is not available anymore to this child.
<P>
<PRE> use vars qw(%CACHE);
@@ -10436,8 +10721,8 @@
<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.
+If you are into Apache API
+<CODE>Apache-&gt;request-&gt;connection-&gt;aborted()</CODE> construct can be used to test for the aborted connection.
<P>
I hope you noticed, that this example is very misleading, since there is a
@@ -10590,7 +10875,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/27/1999
+ <BR>Last Modified at 08/07/1999
</FONT>
</B>
</TD>
@@ -11047,7 +11332,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/19/1999
+ <BR>Last Modified at 07/09/1999
</FONT>
</B>
</TD>
@@ -11106,6 +11391,12 @@
<LI><A HREF="#Non_authenticated_access_for_int">Non authenticated access for internal IPs, but authenticated by external IPs</A>
</UL>
+ <LI><A HREF="#Authentication_code_snippets">Authentication code snippets</A>
+ <UL>
+
+ <LI><A HREF="#Forcing_reauthenticating">Forcing reauthenticating</A>
+ </UL>
+
</UL>
<!-- INDEX END -->
@@ -11290,6 +11581,27 @@
<CODE>userB</CODE> according on the IP, if non matched <CODE>PerlAuthenHandler</CODE> will be not set to OK, and the next Authentication stage will ask the user
for a login and password.
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Authentication_code_snippets">Authentication code snippets</A></H1></CENTER>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Forcing_reauthenticating">Forcing reauthenticating</A></H2></CENTER>
+<P>
+To force authenticated user to reauthenticate just send the following
+header to the browser:
+
+<P>
+<PRE> HTTP/1.0 401 Unauthorized
+</PRE>
+<P>
+This will pop-up (on Netscape at least) a window saying that the
+<STRONG>Authorization Failed. Retry?</STRONG> And an <STRONG>OK</STRONG> and a <STRONG>Cancel</STRONG> buttons. When that window pops up you know that the password has been
+cleared. If the user hits the <STRONG>Cancel</STRONG> button the username will also be cleared, and you can have a page that will
+be output written after the header if this is a CGI (or PHP, or anything
+else like that). If the user hits the <STRONG>OK</STRONG> button, the authentication window will be brought up again with their
+previous username already in the username field.
+
<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>
@@ -11313,7 +11625,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
@@ -11380,6 +11692,7 @@
<LI><A HREF="#Opening_a_connection_with_differ">Opening a connection with different parameters</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>
+ <LI><A HREF="#skipping_connection_cache_during">skipping connection cache during server startup</A>
</UL>
</UL>
@@ -11518,6 +11831,12 @@
users).
<P>
+Be warned though, that if your database is down, apache children will get
+delayed trying to <CODE>connect_on_init()</CODE>. They won't begin serving requests until they get logged in, or the login
+attempt fails (which can take several minutes (depending on your DBD
+driver).
+
+<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>
@@ -11622,6 +11941,32 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H3><A NAME="skipping_connection_cache_during">skipping connection cache during server startup</A></H3></CENTER>
+<P>
+Does your error_log looks like this:
+
+<P>
+<PRE> 10169 Apache::DBI PerlChildInitHandler
+ 10169 Apache::DBI skipping connection cache during server startup
+ Database handle destroyed without explicit disconnect at
+ /usr/lib/perl5/site_perl/5.005/Apache/DBI.pm line 29.
+</PRE>
+<P>
+then you are trying to open a database connection in the parent httpd
+process. If you do, children will get a copy of this handle, causing
+clashes when the handle is used by two processes at the same time. Each
+child must have its own unique connection handle.
+
+<P>
+To avoid this problem, <CODE>Apache::DBI</CODE> checks whether it is called during server startup. In this case the module
+skips the connection cache and returns immediately without a database
+handle.
+
+<P>
+You have to use the method <CODE>Apache::DBI-&gt;connect_on_init()</CODE> in the startup file.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="mysql_use_result_vs_mysql_store">mysql_use_result vs. mysql_store_result.</A></H1></CENTER>
<P>
Since many mod_perl developers uses mysql as their preferable engine, these
@@ -12500,7 +12845,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 08/16/1999
</FONT>
</B>
</TD>
@@ -12770,7 +13115,7 @@
BEGIN {
# RCS/CVS complient: must be all one line, for MakeMaker
- $DB_File::Wrap::VERSION = do { my @r = (q$Revision: 1.15 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
+ $DB_File::Wrap::VERSION = do { my @r = (q$Revision: 1.16 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
}
@@ -12990,7 +13335,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/09/1999
</FONT>
</B>
</TD>
@@ -13250,7 +13595,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/09/1999
</FONT>
</B>
</TD>
@@ -13329,9 +13674,9 @@
<P>
<CENTER><H1><A NAME="Watching_the_server">Watching the server</A></H1></CENTER>
<P>
-Very useful feature. You can watch what happens to the perl parts of the
-server. Below you will find the instructions of configuration and usage of
-this feature
+This is a very useful feature. You can watch what happens to the Perl parts
+of the server. Here are the instructions for configuring and using this
+feature:
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -13349,8 +13694,8 @@
</Location>
</PRE>
<P>
-If you are going to use Apache::Status. It's important to put it as a first
-module in the start-up file, or in the httpd.conf.
+If you are going to use <CODE>Apache::Status</CODE> it's important to put it as the first module in the start-up file, or in
+the httpd.conf:
<P>
<PRE> # startup.pl
@@ -13359,17 +13704,16 @@
use Apache::DBI ();
</PRE>
<P>
-If you don't put Apache::Status before Apache::DBI then you don't get
-Apache::DBI's menu entry in status.
+If you don't put <CODE>Apache::Status</CODE> before <CODE>Apache::DBI</CODE>, you wouldn't get <CODE>Apache::DBI</CODE>'s menu entry in status.
<P>
-For more about Apache::DBI see <A HREF="././performance.html#Persistent_DB_Connections">Persistent DB Connections</A>.
+For more about <CODE>Apache::DBI</CODE> 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><H2><A NAME="Usage">Usage</A></H2></CENTER>
<P>
-Assuming that your mod_perl server listens to port 81, fetch <A
+Assuming that your mod_perl server listens on port 81, fetch <A
HREF="http://www.myserver.com:81/perl-status">http://www.myserver.com:81/perl-status</A>
@@ -13394,27 +13738,25 @@
Symbol Table Dump
</PRE>
<P>
-Let's follow for example : PerlRequire'd Files => we see:
+Let's follow, for example, <CODE>PerlRequire</CODE>'d Files. We see:
<P>
-<PRE> PerlRequire Location
- /usr/apps/pais/lib/apache-startup.pl /usr/apps/pais/lib/apache-startup.pl
+<PRE> PerlRequire Location
+ /home/perl/apache-startup.pl /home/perl/apache-startup.pl
</PRE>
<P>
-From some menus you can continue dipper to peek into internals of the
+From some menus you can continue deeper to peek into the internals of the
server, to see the values of the global variables in the packages, to the
-the cached scripts and modules and much more. Just click around...
+cached scripts and modules, and much more. Just click around...
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Compiled_Registry_Scripts_sectio">Compiled Registry Scripts section seems to be empty.</A></H2></CENTER>
<P>
-Sometimes when you fetch /perl-status you and follow the <STRONG>Compiled
-Registry Scripts</STRONG> -- you see no listing of scripts at all. This is absolutely correct --
-Apache::Status shows the registry scripts compiled in the httpd child which
-is serving your request for /perl-status. If a child has not compiled yet
-the script you are asking for, /perl-status will just show you the main
-menu.
+Sometimes when you fetch <CODE>/perl-status</CODE> and follow the <STRONG>Compiled
+Registry Scripts</STRONG> you see no listing of scripts at all. This is absolutely correct: <CODE>Apache::Status</CODE> shows the registry scripts compiled in the httpd child which is serving
+your request for /perl-status. If a child has not compiled yet the script
+you are asking for, /perl-status will just show you the main menu.
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
@@ -13439,7 +13781,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
@@ -13494,6 +13836,7 @@
<LI><A HREF="#Sometimes_script_works_sometime">Sometimes script works, sometimes does not</A>
<LI><A HREF="#Non_interactive_debugging_when_r">Non-interactive debugging when running under mod_perl</A>
<LI><A HREF="#Apache_DB_Run_the_interactive">Apache::DB - Run the interactive Perl debugger under mod_perl</A>
+ <LI><A HREF="#Debugging_Core_Dumps">Debugging Core Dumps</A>
<LI><A HREF="#Debug_Tracing">Debug Tracing</A>
<LI><A HREF="#gdb_says_there_are_no_debugging_">gdb says there are no debugging symbols</A>
<LI><A HREF="#Monitoring_error_log_file">Monitoring error_log file</A>
@@ -13581,6 +13924,27 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Debugging_Core_Dumps">Debugging Core Dumps</A></H1></CENTER>
+<P>
+See the SUPPORT doc for hints on getting a stacktrace. To do this with
+<STRONG>make test</STRONG>, build mod_perl giving <CODE>Makefile.PL</CODE> the <CODE>PERL_DEBUG=1</CODE>
+flag. Now execute
+
+<P>
+<PRE> gdb ../apache_x.x.x/src/httpd
+ (gdb) thttpd
+</PRE>
+<P>
+(thttpd is defined in .gdbinit)
+
+<P>
+then, in another term run <STRONG>make run_tests</STRONG>, and at the gdb prompt:
+
+<P>
+<PRE> (gdb) bt
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Debug_Tracing">Debug Tracing</A></H1></CENTER>
<P>
To enable mod_perl debug tracing configure mod_perl with the PERL_TRACE
@@ -13651,9 +14015,7 @@
with some ISPs who provides user CGI support but no telnet access), you
might want to use a CGI script I wrote to fetch the latest lines from the
file (with a bonus of colored output for an easier reading). You might need
-to ask your ISP to install this script for a general usage. See <A HREF="././snippets.html#Watching_the_error_log_file_with">Watching the error_log file without telneting to the server.</A>
-
-
+to ask your ISP to install this script for a general usage. See <A HREF="././snippets.html#Watching_the_error_log_file_with">Watching the error_log file without telneting to the server</A>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -13825,7 +14187,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
@@ -13898,25 +14260,25 @@
<P>
<CENTER><H1><A NAME="Preventing_QUERY_STRING_from_get">Preventing QUERY_STRING from getting corrupted because of &entity key names.</A></H1></CENTER>
<P>
-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
+In a URL such as <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
+<CODE>&reg;</CODE>, which will result in a corrupted <CODE>QUERY_STRING</CODE>. If you encounter this problem you should either avoid using such 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>
Note that this is only an issue when you are building your own URLs with
-query strings, it is not a problem when the URL is the result of submitting
+query strings. It is not a problem when the URL is the result of submitting
a form because the browsers _have_ to get that right.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<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>
-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.
+One problem with publishing 8080 port numbers is that (so I was told) 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>
See <A HREF="././config.html#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>
@@ -13946,7 +14308,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 05/15/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
@@ -14004,6 +14366,8 @@
<LI><A HREF="#Apache_PerlRun_Run_unaltered_">Apache::PerlRun - Run unaltered CGI scripts under mod_perl</A>
<LI><A HREF="#Apache_GzipChain_compress_HTM">Apache::GzipChain - compress HTML (or anything) in the OutputChain</A>
<LI><A HREF="#Apache_PerlVINC_set_a_differe">Apache::PerlVINC - set a different @INC perl-location </A>
+ <LI><A HREF="#Apache_RegistryBB_Apache_Re">Apache::RegistryBB - Apache::Registry Bare-Bones</A>
+ <LI><A HREF="#Apache_LogSTDERR">Apache::LogSTDERR</A>
</UL>
<!-- INDEX END -->
@@ -14143,9 +14507,7 @@
to in a process running under mod_cgi.
<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)
+(<A HREF="././download.html#Apache_Request">Apache::Request</A>)
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -14246,6 +14608,34 @@
HREF="http://perl.apache.org/~dougm/Apache-PerlVINC-0.01.tar.gz">http://perl.apache.org/~dougm/Apache-PerlVINC-0.01.tar.gz</A>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Apache_RegistryBB_Apache_Re">Apache::RegistryBB -- Apache::Registry Bare-Bones</A></H1></CENTER>
+<P>
+It works just like <CODE>Apache::Registry</CODE>, but does not test the x bit, only compiles the file once, and does not <CODE>chdir()</CODE> into the script parent directory.
+
+<P>
+Configuration:
+
+<P>
+<PRE> PerlModule Apache::RegistryBB
+ <Location /perl>
+ SetHandler perl-script
+ PerlHandler ApacheRegistryBB->handler
+ </Location>
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Apache_LogSTDERR">Apache::LogSTDERR</A></H1></CENTER>
+<P>
+When Apache's builtin syslog support is used, the stderr stream is
+redirected to <CODE>/dev/null</CODE>. This means Perl warnings, any messages from <CODE>die()</CODE>, <CODE>croak()</CODE>, etc., will also end up in the black hole. The <EM>HookStderr</EM> directive will hook the stderr stream to a file of your choice, the default
+is shown in this example:
+
+<P>
+<PRE> PerlModule Apache::LogSTDERR
+ HookStderr logs/stderr_log
+</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>
@@ -14269,7 +14659,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
@@ -14322,6 +14712,7 @@
<UL>
<LI><A HREF="#Coverage">Coverage</A>
+ <LI><A HREF="#perldoc_s_little_known_but_very_">perldoc's little known but very useful options</A>
<LI><A HREF="#Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A>
<UL>
@@ -14356,6 +14747,36 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="perldoc_s_little_known_but_very_">perldoc's little known but very useful options</A></H1></CENTER>
+<P>
+To find what functions perl has, you would execute:
+
+<P>
+<PRE> perldoc perlfunc
+</PRE>
+<P>
+To learn the syntax and to find an example of specific known function, you
+would execute (e.g. for <CODE>open()</CODE>):
+
+<P>
+<PRE> perldoc -f open
+</PRE>
+<P>
+There is a bug in this option, for it wouldn't call pod2man and display the
+section in POD. But it's still readable and very useful.
+
+<P>
+To search the Perl FAQ (<CODE>perlfaq</CODE>) sections you would do (e.g for an
+<STRONG>open</STRONG> keyword):
+
+<P>
+<PRE> perldoc -q open
+</PRE>
+<P>
+will return you all the matching Q&A sections, still in POD.
+
+<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>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -14617,7 +15038,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/05/1999
+ <BR>Last Modified at 08/16/1999
</FONT>
</B>
</TD>
@@ -14670,9 +15091,9 @@
<UL>
<LI><A HREF="#Sending_MIME_headers">Sending MIME headers</A>
- <LI><A HREF="#How_to_avoid_printing_the_header">How to avoid printing the header more than once.</A>
+ <LI><A HREF="#How_to_avoid_printing_the_header">How to avoid printing the header more than once</A>
<LI><A HREF="#More_on_relative_paths">More on relative paths</A>
- <LI><A HREF="#Watching_the_error_log_file_with">Watching the error_log file without telneting to the server.</A>
+ <LI><A HREF="#Watching_the_error_log_file_with">Watching the error_log file without telneting to the server</A>
<LI><A HREF="#Accessing_variables_from_the_cal">Accessing variables from the caller's package</A>
<LI><A HREF="#Handling_cookies">Handling cookies</A>
</UL>
@@ -14695,31 +15116,32 @@
<CENTER><H1><A NAME="Sending_MIME_headers">Sending MIME headers</A></H1></CENTER>
<P>
By default, mod_perl does not send any headers by itself, however, you may
-wish to change this behavior by setting in config file:
+wish to change this behavior by setting in the config file:
<P>
<PRE> PerlSendHeader On
</PRE>
<P>
-The safest bet is to use CGI.pm's <CODE>print header();</CODE> method (If you use this, you don't need the above setting)
+The safest bet is to use CGI.pm's <CODE>header()</CODE> method. (If you do <CODE>print header();</CODE>, you don't need the above setting.)
<P>
-Also there is $ENV{PERL_SEND_HEADER} to see if PerlSendHeader is On or Off.
+Also there is <CODE>$ENV{PERL_SEND_HEADER}</CODE> to see if <CODE>PerlSendHeader</CODE> is <CODE>On</CODE> or
+<CODE>Off</CODE>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="How_to_avoid_printing_the_header">How to avoid printing the header more than once.</A></H1></CENTER>
+<CENTER><H1><A NAME="How_to_avoid_printing_the_header">How to avoid printing the header more than once</A></H1></CENTER>
<P>
-I'm sure you have been in the situations, where you wish you knew whether
-the MIME header has been already printed. Since if it was printing it again
-will cause an ugly ``Content-type: ...'' string show up at the web page. So
-how do we solve it? With help of closure.
+I'm sure you have been in situations where you wish you knew whether the
+MIME header has already been printed. Since if it is printed again it will
+cause an ugly ``Content-type: ...'' string to show up in the browser. So
+how do we solve it? With the help of a closure.
<P>
-Just copy the code below as it is, including the block's curly parentheses.
-And everywhere in your code use the <CODE>print_header()</CODE> sub to
-print the header. <CODE>$need_header</CODE> is the same beast as static variable in C, so it remembers its value from
-call to call.
+Just copy the code below, including the block's curly parentheses. And
+everywhere in your code you print the header use the <CODE>print_header()</CODE> sub.
+<CODE>$need_header</CODE> is the same kind of beast as a static variable in C, so it remembers its
+value from call to call.
<P>
<PRE> {
@@ -14732,39 +15154,67 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="More_on_relative_paths">More on relative paths</A></H1></CENTER>
+<P>
+Many people use relative paths for <CODE>require</CODE>, <CODE>use</CODE>, etc., or open files in the current directory or relative to the current
+directory. But this will fail if you don't <CODE>chdir()</CODE> into the correct directory first (e.g when you call the script by its full
+path). This code would work:
+
+<P>
+<PRE> /home/httpd/perl/test.pl:
+ -------------------------
+ #!/usr/bin/perl
+ open IN, "./foo.txt";
+ -------------------------
+</PRE>
+<P>
+if we call the script by:
+
+<P>
+<PRE> % chdir /home/httpd/perl
+ % ./test.pl
+</PRE>
+<P>
+since <CODE>foo.txt</CODE> is located at the same directory the script is being called from. if we
+call the script by:
+
+<P>
+<PRE> % /home/httpd/perl/test.pl
+</PRE>
<P>
-Many use a relative require call, or write to the file in the current or
-relative to the current directory. But this will fail if you wouldn't
-<CODE>chdir()</CODE> into the directory first. So you have to either do
-this in the code or to use a nice <CODE>FindBin.pm</CODE> package.
+when we aren't chdir to the <CODE>/home/httpd/perl</CODE>, the script will fail to find <CODE>foo.txt</CODE>. If you don't want to use hardcoded directories in your scripts, <CODE>FindBin.pm</CODE> package will come to rescue.
<P>
<PRE> use FindBin qw($Bin);
use lib $Bin;
- # or
+ open IN, "./foo.txt";
+</PRE>
+<P>
+or
+
+<P>
+<PRE> use FindBin qw($Bin);
open IN, "$Bin/foo.txt";
</PRE>
<P>
-Now <CODE>$Bin</CODE> includes the path of the directory the script resides on, so you can move
-the script from one directory to the other and call it from anywhere else,
-the paths will be always correct.
+Now <CODE>$Bin</CODE> includes the path of the directory the script resides in, so you can move
+the script from one directory to the other and call it from anywhere else.
+The paths will be always correct.
<P>
-It's different from using the ``./foo'', for you have to chdir to the
-directory the script located at first. (Think about crontabs!!!)
+It's different from using <CODE>"./foo"</CODE>, for you first have to <CODE>chdir</CODE> to the directory in which the script is located. (Think about <CODE>crontab</CODE>s!!!)
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Watching_the_error_log_file_with">Watching the error_log file without telneting to the server.</A></H1></CENTER>
+<CENTER><H1><A NAME="Watching_the_error_log_file_with">Watching the error_log file without telneting to the server</A></H1></CENTER>
<P>
-I wrote this script long time ago, when I have had to debug my cgi scripts
-but I didn't have the access to the error_log file. I have asked the admin
-to install this script and happily used it since then.
+I wrote this script a long time ago, when I had to debug my CGI scripts but
+didn't have the access to the <CODE>error_log</CODE> file. I asked the admin to install this script and have used it happily
+since then.
<P>
-If your scripts are running on these 'Get-free-site' servers, and your
+If your scripts are running on these 'Get-free-site' servers, and you
cannot debug your script because you can't telnet to the server or can't
-see the error_log, you can ask your sysadmin to install this script.
+see the <CODE>error_log</CODE>, you can ask your sysadmin to install this script.
<P>
Ok, here is the code:
@@ -14852,8 +15302,8 @@
<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:
+Sometimes you want to access variables from the caller's package. One way
+is to do:
<P>
<PRE> my $caller = caller;
@@ -14863,16 +15313,15 @@
<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
+Unless you use some well known module 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}.
+Cookies come in the <CODE>$ENV{HTTP_COOKIE}</CODE> variable. You can print the raw cookie string as <CODE>$ENV{HTTP_COOKIE}</CODE>.
<P>
-This is a fairly well-known bit of code to take cookie values and put them
-into a hash.
+Here is a fairly well-known bit of code to take cookie values and put them
+into a hash:
<P>
<PRE> sub getCookies {
@@ -14912,7 +15361,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 05/17/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
@@ -14980,10 +15429,11 @@
<LI><A HREF="#Choosing_Hardware">Choosing Hardware</A>
<UL>
- <LI><A HREF="#Site_traffic">Site traffic</A>
+ <LI><A HREF="#Expected_site_traffic">Expected site traffic</A>
<LI><A HREF="#Cash">Cash</A>
- <LI><A HREF="#Memory">Memory</A>
<LI><A HREF="#Internet_Connection">Internet Connection</A>
+ <LI><A HREF="#I_O_performance">I/O performance</A>
+ <LI><A HREF="#Memory">Memory</A>
<LI><A HREF="#Bottlenecks">Bottlenecks</A>
<LI><A HREF="#Conclusion">Conclusion</A>
</UL>
@@ -15007,41 +15457,42 @@
<P>
<CENTER><H1><A NAME="Is_it_important_">Is it important?</A></H1></CENTER>
<P>
-You can invest a lot of time and money in server tuning and code rewriting
-according the guidelines you have just learned, but your performance will
-be really bad if you did not take into account the hardware demands, and
-did not wisely chose the operating system suited for your needs. While the
-tips below apply to any webserver, they are written for a mod_perl enabled
-webservers' administrators.
+You can invest a lot of time and money into server tuning and code
+rewriting according the guidelines you have just learned, but your
+performance will be really bad if you do not take into account the hardware
+demands, and do not wisely choose the operating system suited for your
+needs. While the tips below apply to any webserver, they are written for an
+administrator of a mod_perl-enabled webserver
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Choosing_an_Operating_System">Choosing an Operating System</A></H1></CENTER>
<P>
-First lets talk about Operating Systems (OS). While personally I am a Linux
-devotee, I do not want to start yet another OS war. Assuming this, I will
-try to define what you should be looking for, then when you know what do
-you want from your OS, go find it. Visit the Web sites of operating systems
-you are interested in. You can gauge user's opinions by searching relevant
-discussions in newsgroup and mailing list archives such as Deja - <A
-HREF="http://deja.com">http://deja.com</A> and eGroups - <A
+First let's talk about Operating Systems (OS). While I am personally a
+Linux devotee, I do not want to start yet another OS war. Assuming this, I
+will try to define what you should be looking for, then when you know what
+do you want from your OS, go find it. Visit the Web sites of operating
+systems you are interested in. You can gauge user's opinions by searching
+relevant discussions in newsgroup and mailing list archives such as Deja -
+<A HREF="http://deja.com">http://deja.com</A> and eGroups - <A
HREF="http://egroups.com">http://egroups.com</A> . I will leave this fan
-research up to you. But I would use linux :o) Just kidding...
+research up to you. But I would use Linux or something from the
+<CODE>*BSD</CODE> family.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Stability_and_Robustness">Stability and Robustness</A></H2></CENTER>
<P>
Probably the most desired features in an OS are stability and robustness.
-We are involved in an Internet business, which does not have normal working
-hours, like many conventional businesses we know about (9pm to 5pm). We are
-open 24 hours a day. We can not afford off line periods, for our customers
-will go shop for another service like ours, unless you have a monopoly :) .
-If the OS of your choice crashes every day or so, I would throw it away,
-after doing a little investigation, for there are might be a reason for a
-system crash. Like a runaway server that eats up all the memory and disk,
-so we cannot blame the OS for that. Generally people who use the OS for
-some time can tell you a lot about its stability.
+You are in an Internet business, which does not have normal working hours,
+like many conventional businesses you know about (9am to 5pm). You are open
+24 hours a day. You cannot afford to be off-line, for your customers will
+go shop at another service like yours, unless you have a monopoly :) . If
+the OS of your choice crashes every day or so, I would throw it away, after
+doing a little investigation, for there might be a reason for a system
+crash. Like a runaway server that eats up all the memory and disk, so you
+cannot blame the OS for that. Generally, people who use the OS for some
+time can tell you a lot about its stability.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -15056,55 +15507,54 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Memory_Leakages">Memory Leakages</A></H2></CENTER>
<P>
-Some OSes and/or the libraries (like C libraries) suffer from memory
-leakage. You cannot afford such a system, for you are already know that a
-single mod_perl process sometimes serves thousands of requests before it
-terminates. So if a leak occurs on every request, your memory demands will
-be huge. Of course your code can be the cause of the memory leakages as
-well (check out the <CODE>Apache::Leak</CODE>
-module). Certainly you can lower the number of requests to be served over
-the process' life, but performance degrades with this.
+Some OSes and/or the libraries (like C runtime libraries) suffer from
+memory leaks. You cannot afford such a system, for you are already know
+that a single mod_perl process sometimes serves thousands of requests
+before itimer terminates. So if a leak occurs on every request, your memory
+demands will be huge. Of course your code can be the cause of the memory
+leaks as well (check out the <CODE>Apache::Leak</CODE>
+module). Certainly, you can lower the number of requests to be served over
+the process' life, but that can degrade performance.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Sharing_Memory">Sharing Memory</A></H2></CENTER>
<P>
You want an OS with good memory sharing capabilities. As you have learned,
-if you preload the modules and scripts at server startup, they are being
-shared between the spawned children, at least for a part of a process' life
-span, since memory pages are getting ``dirty'' and ceasing to be shared.
-This feature can save you up a lot of memory!!!
+if you preload the modules and scripts at server startup, they are shared
+between the spawned children, at least for a part of a process' life span,
+since memory pages become ``dirty'' and cease to be shared. This feature
+can save you up a lot of memory!
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Cost_and_Support">Cost and Support</A></H2></CENTER>
<P>
-If you are into a big business you are probably do not care to pay another
+If you are in a big business you are probably do not mind paying another
<CODE>$1000</CODE> for some fancy OS and to get the bundled support for it.
-But if your resources are low, you will look for cheaper and free OSes.
-Free does not mean bad, it can be quite opposite as we all either know from
-our own experience or read about in news. Free OSes could have and do have
-the best support you can find. It is very easy to understand - most of the
+But if your resources are low, you will look for cheaper and free OS. Free
+does not mean bad, it can be quite opposite as we all either know from our
+own experience or read about in news. Free OSes could have and do have the
+best support you can find. It is very easy to understand - most of the
people are not rich and will try to use a cheaper or free OS first if it
does the work for them. Since it really fits their needs, many people keep
using it and eventually know it well enough to be able to provide support
-for others in trouble. Why would they do this for free? For a real spirit
-of the first days of the Internet, when there was no commercial Internet
-and people helped each other, because someone helped them in first place. I
-was there, I was touched by that spirit and I will do anything to keep this
+for others in trouble. Why would they do this for free? For the spirit of
+the first days of the Internet, when there was no commercial Internet and
+people helped each other, because someone helped them in first place. I was
+there, I was touched by that spirit and I will do anything to keep that
spirit alive.
<P>
But, let's get back to our world. We are living in material world, and our
bosses pay us to keep the systems running. So if you feel that you cannot
provide the support yourself and you do not trust the available free
-resources, you must get an OS that has a company behind it to pay to blame
-for any problems you encounter in hopes that your cries for help will be
-heard and answered. Your boss wants to be able to sue someone if the
-project has a problem caused by the external product that is being used in
-the project. If you buy a product and the company selling it, claims
-support, you have someone to sue. You do not have someone to sue other than
-getting yourself fired if you go with Open Source and it fails.
+resources, you must pay for an OS backed by a company, and blame them for
+any problem. Your boss wants to be able to sue someone if the project has a
+problem caused by the external product that is being used in the project.
+If you buy a product and the company selling it, claims support, you have
+someone to sue. You do not have someone to sue other than getting yourself
+fired if you go with Open Source and it fails.
<P>
Also remember that if you spend less or zero money on OS and Software, you
@@ -15114,30 +15564,30 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Discontinued_products">Discontinued products</A></H2></CENTER>
<P>
-You have invested a lot into a developing of some proprietary software,
-that is bundled with the OS you were developing on and for. Like you write
-some mod_perl handler that takes an advantage of some proprietary features
-of the OS and it will not run on any other OS. Things are under control,
-the performance is great and you sing from happiness. But... one day the
-company who wrote your beloved OS went bankrupt, which is not unlikely to
-happen nowadays. You have got stuck with their last masterpiece and no
-support! What you are going to do then? Invest more into porting the
-software for another OS...
+You have invested a lot of time and money into developing some proprietary
+software that is bundled with the OS you were developing on. Like writing a
+mod_perl handler that takes advantage of some proprietary features of the
+OS and it will not run on any other OS. Things are under control, the
+performance is great and you sing from happiness. But... one day the
+company who wrote your beloved OS goes bankrupt, which is not unlikely to
+happen nowadays. You are stuck with their last masterpiece and no support!
+What you are going to do then? Invest more into porting the software to
+another OS...
<P>
-Everyone can be hit by this mini disaster, so it is better to watch the
+Everyone can be hit by this mini-disaster, so it is better to check the
background of the company when making your choice, but still you never know
-what will happen in a next minute. The OSes in this hazard group are
-completely developed by a single companies. Free OSes are probably less
-susceptible to this, for development is distributed between many companies
-and developers, so if a person who developed a really important part of the
-kernel lost interest to continue, someone else will pick the falling flag
-and continue from the same place. Of course if tomorrow some better project
-shows up, developers might migrate there and finally drop the development,
-but we are here not to let this happen.
+what will happen tomorrow. The OSes in this hazard group are completely
+developed by a single companies. Free OSes are probably less susceptible to
+this, for development is distributed between many companies and developers,
+so if a person who developed a really important part of the kernel lost
+interest in continuing, someone else will pick the falling flag and carry
+on. Of course if tomorrow some better project showed up, developers might
+migrate there and finally drop the development, but we are here not to let
+this happen.
<P>
-But you are the one to make the right decision...
+In the final analysis, the decision is yours.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -15145,29 +15595,28 @@
<P>
Actively developed OSes generally try to keep the pace with the latest
technology developments, and continually optimize the kernel and other
-parts of OS to become better and faster. Nowadays, Internet and Networking
-in general are the hottest targets for system developers. Sometimes a
-simple OS upgrade to a latest stable version, can save you an expensive
-hardware upgrade. Also, remember that when you buy a new hardware, chances
-are that the latest software will make the most out of it. Since while the
-existing software (drivers) might support the new brand product because of
-its back compatibility with previous products of the same family, it might
-not take advantage of new features. It means that you could spend much less
-money for almost the same functionality if you were to buy a previous model
-of the same product.
+parts of the OS to become better and faster. Nowadays, Internet and
+networking in general are the hottest targets for system developers.
+Sometimes a simple OS upgrade to a latest stable version, can save you an
+expensive hardware upgrade. Also, remember that when you buy new hardware,
+chances are that the latest software will make the most of it. Since the
+existing software (drivers) might support the brand new product because of
+its backwards compatibility with previous products of the same family, it
+might not reap all the benefits of the new features. It means that you
+could spend much less money for almost the same functionality if you were
+to buy a previous model of the same product.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Choosing_Hardware">Choosing Hardware</A></H1></CENTER>
<P>
While I am not fond of the idea of updating this section every day a new
-processor or memory type comes out, exactly like with OS choosing
-guidelines, I will only hint what should you look after and persuade you
-that sometimes the most expensive machine is not the one which provides the
-best performance.
+processor or memory type comes out, I will only hint what should you look
+for and suggest that sometimes the most expensive machine is not the one
+which provides the best performance.
<P>
-Your demands are bound to many aspects and components. Let's discuss some
+Your demands are based on many aspects and components. Let's discuss some
of them.
<P>
@@ -15191,7 +15640,7 @@
users. One of the advantages is that you can take one of the machines down
for a repair or upgrade, and your service will still work - the main server
will not dispatch the requests to the machine that was taken down. I will
-just say that there are many load balancing techniques. (e.g. <A HREF="././download.html#">Eddieware</A>)
+just say that there are many load balancing techniques. (See <A HREF="././download.html#High_Availability_Linux_Project">High-Availability Linux Project</A> for more info.)
<P><LI>
<P>
@@ -15208,9 +15657,9 @@
</UL>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Site_traffic">Site traffic</A></H2></CENTER>
+<CENTER><H2><A NAME="Expected_site_traffic">Expected site traffic</A></H2></CENTER>
<P>
-If you are building a fans' site, but want to amaze your friends with
+If you are building a fan site, but want to amaze your friends with a
mod_perl guest book, an old 486 machine will do it. If you are into a
serious business, it is very important to build a scalable server, so if
your service is successful and becomes popular, you get your server's
@@ -15238,11 +15687,11 @@
<CENTER><H2><A NAME="Cash">Cash</A></H2></CENTER>
<P>
Everybody knows that Internet is a cash hole, what you throw in, hardly
-comes back. This is not always correct, but there is a lot of wisdom in
-these words. While you have to invest money to build a decent service, it
-can be cheaper! You can spend as much as 10 times more money on a strong
-new machine, but get only a 10% improve in performance. Remember that
-processor that was born 4 years ago is still very mighty.
+comes back. This is not always true, but there is a lot of wisdom in these
+words. While you have to invest money to build a decent service, it can be
+cheaper! You can spend as much as 10 times more money on a strong new
+machine, but get only a 10% improvement in performance. Remember that a
+four year old processor is still very powerful.
<P>
If you really need a lot of power do not think about a single strong
@@ -15251,92 +15700,30 @@
machines and have a 8 times more power, then purchasing only one single new
machine. Why is that? Because as I mentioned before generally the
performance improvement is marginal while the price is much bigger. Because
-10 machines will do a faster Hard Disk IO (Input/Output), then one single
-machine even if the disk is much faster. Yes, you have more administration
-overhead, but there is a chance you will have it anyway, for in a short
-time the machine you have just invested into will not stand the load and
-you will have to purchase more and think how to implement the load
-balancing and file system distribution.
+10 machines will do faster disk I/O, than one single machine, even if the
+disk is much faster. Yes, you have more administration overhead, but there
+is a chance you will have it anyway, for in a short time the machine you
+have just invested in will not stand the load anyway and you will have to
+purchase more and think how to implement load balancing and file system
+distribution.
<P>
Why I am so convinced? Facts! Look at the most used services on the
-Internet: search engines, email servers and alike - most of them are using
-clustering approach. While you will not always notice that, they do it by
-hiding the real implementation behind the proxy servers.
-
-<P>
-<PRE> =head2 IO performance
-</PRE>
-<P>
-If your service is IO bound (does a lot of read/write operations to your
-disk, remember that relational DataBases are sitting on disk as well) you
-need a very fast disk. So you should not spend money on a Video card and
-monitor (monochrome card and 14`` B&W will do for server
-configuration), but rather look for the best price/performance in disks (of
-course asking around for a solid firm, whose HDs are not getting corrupted
-at all.) With money in hand you should think about getting a RAID system.
-RAID is generally a box with many HDs. It is capable of reading/writing
-data much faster, and is protected against disk corruptions. It does this
-by duplicating the same data over a number of disks, so if one gets
-corrupted the RAID detects it and the data is still correct on the
-duplicated disks. You must think about RAID or similar systems if you have
-an enormous data set to serve. (What is an enormous data set nowadays?).
-
-<P>
-Ok, we have a fast disk, what's next? You need a fast disk controller. So
-either you should use the one embedded on your motherboard or you should
-plug a controller card if the one you have onboard is not good enough.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Memory">Memory</A></H2></CENTER>
-<P>
-How much RAM (Randomly Accessed Memory) do you need? Nowadays, chances are
-you will hear: ``Memory is cheap, the more you buy the better''. But how
-much is enough? The answer pretty straightforward: ``You do not want your
-machine to swap''. When the CPU needs to write something into memory, but
-notices that it is already full, it takes the least frequently used memory
-pages (4k/page on average OS) and swaps them out. Swapping out means
-copying to the disk into a special partition or file called swap and
-deleting from the real memory. When another process asks the CPU to access
-another page, but CPU cannot find the memory page in RAM (it was just
-swapped out), it goes and brings it from the swap (swapping in). If memory
-is small, swapping (in/out) happens too frequently, the CPU becomes too
-busy swapping pages in and out, the HD is working hard to read/write the
-swapped out pages, and the whole performance of the system is going down.
-Sometimes your swap partition can become full as well and your system might
-die.
-
-<P>
-How do you make a decision? You know what is the highest page request rate
-your service has and how much time an average request takes. Now you can
-calculate how many servers do you need. Knowing the maximum size any of
-your servers can get, you know how much memory do you need. You probably
-need less memory that you have calculated if your OS supports memory
-sharing and you know how to deploy this feature (preloading the modules and
-scripts at server's startup). Do not forget that other essential system
-processes need memory as well, so you should not plan for the webserver
-only, but to take into an account all processes to be run on your system.
-Remember that requests can be queued, so you can afford your client to wait
-a few moments, while some server comes to service it, your numbers will be
-more correct, since you generally do not have the highest load, but you
-should be ready to bear the picks. So you need to reserve at least 20% of
-free memory for peak situations. Many sites were reported to crash a few
-moments after some scooping news about them were posted, and unexpected
-number of requests suddenly came in. If you are about to announce something
-cool, be aware of possible consequences.
+Internet: search engines, email servers and the like -- most of them are
+using a clustering approach. While you may not always notice that, they do
+it by hiding the real implementation behind the proxy servers.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Internet_Connection">Internet Connection</A></H2></CENTER>
<P>
-You have the best hardware you could get, but the service is still
-crawling. Make sure you have a fast Internet connection. Not _fast_ as your
-ISP claims it to be, but fast as it should be. The ISP might have a very
-good connection to the Internet, but put many clients on the same line. If
-these are heavy clients your traffic will have to share the same line, thus
-your speed is effectively limited. Think about a dedicated connection and
-make sure it is truly dedicated, trust the ISP but check it!
+You have the best hardware you can get, but the service is still crawling.
+Make sure you have a fast Internet connection. Not as fast as your ISP
+claims it to be, but fast as it should be. The ISP might have a very good
+connection to the Internet, but puts many clients on the same line. If
+these are heavy clients, your traffic will have to share the same line and
+the throughput will decline. Think about a dedicated connection and make
+sure it is truly dedicated. Trust the ISP but check it!
<P>
The idea of having a connection to <STRONG>The Internet</STRONG> is a little misleading. Many Web hosting and co-location companies have
@@ -15355,34 +15742,100 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Bottlenecks">Bottlenecks</A></H2></CENTER>
+<CENTER><H2><A NAME="I_O_performance">I/O performance</A></H2></CENTER>
<P>
-The most important thing to understand is that you might use the most
-expensive components, but still get a bad performance. Why? Let me
-introduce you to this annoying word: A bottleneck.
+If your service is I/O bound (does a lot of read/write operations to disk,
+remember that relational databases are sitting on disk as well) you need a
+very fast disk. So you should not spend money on Video card and monitor
+(monochrome card and 14`` B&W are perfectly adequate for a server --
+you will probably be telnetted or ssh-ed in most of the time), but rather
+look for disks with the best price/performance ratio. Of course, ask around
+and avoid disks that have a reputation for headcrashes and other disasters.
+
+<P>
+With money in hand you should think about getting a RAID system. RAID is
+generally a box with many HDs. It is capable of reading and writing data
+much faster, and is protected against disk failures. It does this by
+duplicating the same data over a number of disks, so if one fails, the RAID
+controller detects it and the data is still correct on the duplicated
+disks. You must think about RAID or similar systems if you have an enormous
+data set to serve. (What is an enormous data set nowadays? Gigabytes,
+terabytes?).
+
+<P>
+Ok, we have a fast disk, what's next? You need a fast disk controller. So
+either you should use the one embedded on your motherboard or you should
+plug a controller card if the one you have onboard is not good enough.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Memory">Memory</A></H2></CENTER>
+<P>
+How much RAM (Randomly Accessed Memory) do you need? Nowadays, chances are
+you will hear: ``Memory is cheap, the more you buy the better''. But how
+much is enough? The answer pretty straightforward: ``You do not want your
+machine to swap''. When the CPU needs to write something into memory, but
+notices that it is already full, it takes the least frequently used memory
+pages and swaps them out. Swapping out means writing the data to disk.
+Another process then references some of its own data, which happens to be
+on one of the pages that were just swapped out. The CPU, ever obliging,
+swaps it back in again, probably swapping out some other data that will be
+needed very shortly by another process. Carried to the extreme, the CPU and
+disk start to thrash hopelessly in circles, without getting any real work
+done. The less RAM there is, the more often this scenario arises. Worse,
+you can exhaust swap space as well, and then the troubles really set in...
+
+<P>
+How do you make a decision? You know the highest rate your server expects
+to serve pages and how long it takes to do so. Now you can calculate how
+many server processes you need. Knowing the maximum size any of your
+servers can get, you know how much memory you need. You probably need less
+memory than you have calculated if your OS supports memory sharing and you
+know how to make best use of this feature (preloading the modules and
+scripts at server startup). Do not forget that other essential system
+processes need memory as well, so you should plan not only for the web
+server, but also take into account the other players. Remember that
+requests can be queued, so you can afford to let your client wait for a few
+moments until a server is available to serve it, your numbers will be more
+correct, since you generally do not have the highest load, but you should
+be ready to bear the peaks. So you need to reserve at least 20% of free
+memory for peak situations. Many sites have crashed a few moments after a
+big scoop about them was posted and unexpected number of requests suddenly
+came in. (This is called a Slashdot effect, which was born at <A
+HREF="http://slashdot.org">http://slashdot.org</A> ) If you are about to
+announce something cool, be aware of the possible consequences.
<P>
-A machine is an aggregate of many small and big components. Each one of
-them can become a bottleneck. If you have a fast processor but a small
-amount of RAM (memory), the processor will be under utilized waiting for
-the kernel to swap memory pages in and out, because memory is too small to
-fit at least the most used ones. If you have a lot of memory and a fast
-processor and a fast disk, but a slow controller - the performance will be
-bad, and you have wasted the money.
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Bottlenecks">Bottlenecks</A></H2></CENTER>
+<P>
+The most important thing to understand is that you might use the most
+expensive components, but still get bad performance. Why? Let me introduce
+an annoying word: A bottleneck.
<P>
-Of course use a NIC (Network Interface Card) that does not create a
-bottleneck. If it is slow, the whole service is slow.
+A machine is an aggregate of many big and small components. Each one of
+them may be a bottleneck. If you have a fast processor but a small amount
+of RAM (memory), the processor will be under-utilized waiting for the
+kernel to swap the memory pages in and out, because memory is too small to
+hold the most used ones. If you have a lot of memory and a fast processor
+and a fast disk, but a slow controller - the performance will be bad, and
+you have wasted money.
+
+<P>
+Use a fast NIC (Network Interface Card) that does not create a bottleneck.
+If it is slow, the whole service is slow. This is the most important
+component, since webservers are much more network-bound than disk-bound!
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Conclusion">Conclusion</A></H2></CENTER>
<P>
-To optimally use your money, you have to either understand the hardware
-very well, so you will know what to pick, or you should hire a
-knowledgeable hardware consultants and employ them on a constant basis,
-since your demands will probably change as time goes on, and your HW should
-be adapted with each change you make.
+To use your money optimally you have to understand the hardware very well,
+so you will know what to pick. Otherwise, you should hire a knowledgeable
+hardware consultants and employ him/her on a regular basis, since your
+demands will probably change as time goes by and your hardware will
+likewise be forced to adapt as well.
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
@@ -15407,7 +15860,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
@@ -15481,19 +15934,19 @@
<CENTER><H1><A NAME="Thoughts_about_scalability_and_f">Thoughts about scalability and flexibility</A></H1></CENTER>
<P>
Your need for scalability and flexibility depends on your needs from the
-web. If you want only a simple guest book or Database gateway with no
+web. If you want only a simple guest book or database gateway with no
feature headroom, you can get away with any EASY_AND_FAST_TO_DEVELOP_TOOL
(Exchange, MS IIS, Lotus Notes, etc).
<P>
-Experience shows that you will soon want more functionality, that you'll
-start spending time learning the limitations of these ``easy'' tools.
-Gradually, your boss will ask for increasing functionality and at some
-point you'll realize that the tool lacks flexibility and/or scalability.
-Then your boss will either buy another EASY_AND_FAST_TO_DEVELOP_TOOL and
-repeat the process (with different unforseen problems), or you'll start
-investing time learning how to use a powerful, flexible tool to make the
-long-term development cycle easier.
+Experience shows that you will soon want more functionality, that's the
+point you'll discover the limitations of these ``easy'' tools. Gradually,
+your boss will ask for increasing functionality and at some point you'll
+realize that the tool lacks flexibility and/or scalability. Then your boss
+will either buy another EASY_AND_FAST_TO_DEVELOP_TOOL and repeat the
+process (with different unforseen problems), or you'll start investing time
+learning how to use a powerful, flexible tool to make the long-term
+development cycle easier.
<P>
If you and your company are serious about delivering flexible Internet
@@ -15515,19 +15968,19 @@
<P>
Personally, when I discovered mod_perl I did a lot of testing and coding at
home and at work. Once I had a working heavy application, I came to my boss
-with 2 URLs - one for the plain CGI server and the other for mod_perl
-enabled server. It took about 30 secs for my boss to say: `Go with it''. Of
-course the moment I did it, I have had to provide all the support for other
-developers, that is why I took my time to learn it in first place (that is
-how this guide was born!).
+with 2 URLs - one for the plain CGI server and the other for the
+mod_perl-enabled server. It took about 30 secs for my boss to say: `Go with
+it''. Of course the moment I did it, I have had to provide all the support
+for other developers, that is why I took time to learn it in first place
+(that is how this guide was born!).
<P>
Chances are that if you've done your homework, you've learned the tools and
-you can deliver results, you'll have a successful project. If you convince
-your boss to try a tool that you don't know very well, your results may
-suffer. If your boss follows your development process closely and sees much
-worse than expected progress, he might say ``forget it'' and wish never to
-give mod_perl a second chance.
+can deliver results, you'll have a successful project. If you convince your
+boss to try a tool that you don't know very well, your results may suffer.
+If your boss follows your development process closely and sees much worse
+than expected progress, he might say ``forget it'' and wish never to give
+mod_perl a second chance.
<P>
Advocacy is a great thing for the open-source software movement, but it's
@@ -15565,7 +16018,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/19/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
@@ -15685,6 +16138,11 @@
<P>
<A HREF="http://perl.apache.org">http://perl.apache.org</A>
+<P><DT><STRONG>mod_perl Garden project</STRONG><DD>
+<P>
+<A
+HREF="http://modperl.sourcegarden.org">http://modperl.sourcegarden.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
@@ -15735,6 +16193,12 @@
<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 Resources Page</A></STRONG>
+<P>
+<A
+HREF="http://www.perlreference.com/mod_perl/">http://www.perlreference.com/mod_perl/</A>
+
+
<P><LI><STRONG><A NAME="item_mod_perl">mod_perl mailing list</A></STRONG>
<P>
The Apache/Perl mailing list (<A
@@ -15931,7 +16395,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
@@ -15984,15 +16448,16 @@
<UL>
<LI><A HREF="#Coverage">Coverage</A>
- <LI><A HREF="#perl">perl</A>
- <LI><A HREF="#apache">apache</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_Internet_Object_Cache">Squid - Internet Object Cache</A>
<LI><A HREF="#thttpd_tiny_turbo_throttling_H">thttpd - tiny/turbo/throttling HTTP server</A>
<LI><A HREF="#mod_proxy_add_forward">mod_proxy_add_forward</A>
<LI><A HREF="#httperf_webserver_Benchmarking">httperf - webserver Benchmarking tool</A>
<LI><A HREF="#ab_ApacheBench">ab - ApacheBench</A>
- <LI><A HREF="#Eddieware">Eddieware</A>
+ <LI><A HREF="#High_Availability_Linux_Project">High-Availability Linux Project</A>
+ <LI><A HREF="#Apache_Request">Apache::Request</A>
</UL>
<!-- INDEX END -->
@@ -16012,26 +16477,26 @@
<P>
<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
<P>
-Here you will find the instructions for downloading the software and the
+Here you will find instructions for downloading the software and the
related documentation.
<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>
+<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
+least check the version you are using. It is highly recommended that you
+have at least Perl version 5.004. 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.
+. You can get Perl documentation from the same location.
<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>
+<CENTER><H1><A NAME="Apache">Apache</A></H1></CENTER>
<P>
-Get the latest apache webserver and documentation from <A
+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> .
@@ -16068,7 +16533,7 @@
<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
+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
@@ -16086,14 +16551,24 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="ab_ApacheBench">ab - ApacheBench</A></H1></CENTER>
+<P>
+Comes with the Apache distribution.
+
<P>
-Comes within apache distribution.
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="High_Availability_Linux_Project">High-Availability Linux Project</A></H1></CENTER>
+<P>
+You will find the definite guide to load balancing techniques at the
+High-Availability Linux Project site -- <A
+HREF="http://www.henge.com/~alanr/ha/">http://www.henge.com/~alanr/ha/</A>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Eddieware">Eddieware</A></H1></CENTER>
+<CENTER><H1><A NAME="Apache_Request">Apache::Request</A></H1></CENTER>
<P>
-<A HREF="http://www.eddieware.org">http://www.eddieware.org</A>
+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><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
@@ -16118,7 +16593,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/19/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
1.4 +8 -8 modperl-site/guide/browserbugs.html
Index: browserbugs.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/browserbugs.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- browserbugs.html 1999/06/19 21:15:02 1.3
+++ browserbugs.html 1999/08/17 19:03:34 1.4
@@ -47,25 +47,25 @@
<P>
<CENTER><H1><A NAME="Preventing_QUERY_STRING_from_get">Preventing QUERY_STRING from getting corrupted because of &entity key names.</A></H1></CENTER>
<P>
-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
+In a URL such as <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
+<CODE>&reg;</CODE>, which will result in a corrupted <CODE>QUERY_STRING</CODE>. If you encounter this problem you should either avoid using such 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>
Note that this is only an issue when you are building your own URLs with
-query strings, it is not a problem when the URL is the result of submitting
+query strings. It is not a problem when the URL is the result of submitting
a form because the browsers _have_ to get that right.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<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>
-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.
+One problem with publishing 8080 port numbers is that (so I was told) 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>
See <A HREF="././config.html#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>
@@ -95,7 +95,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 05/15/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
1.17 +14 -6 modperl-site/guide/config.html
Index: config.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/config.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- config.html 1999/07/02 13:42:17 1.16
+++ config.html 1999/08/17 19:03:34 1.17
@@ -137,7 +137,7 @@
For example, using the above configuration, fetching
<CODE>http://www.nowhere.com/perl/test.pl</CODE>, will cause the server to look for the file <CODE>test.pl</CODE> at <CODE>/usr/local/myproject/cgi</CODE>, and execute it as an <CODE>Apache::Registry</CODE> script if we define <CODE>Apache::Registry</CODE> to be the handler of <CODE>/perl</CODE> location (see below). The URL
<CODE>http://www.nowhere.com/perl/test.pl</CODE> will be mapped to
-<CODE>/usr/local/myproject/cgi/test.pl</CODE>. This means that you can have all your CGIs located at the same place at
+<CODE>/usr/local/myproject/cgi/test.pl</CODE>. This means that you can have all your CGIs located at the same place in
the file-system, and call the script in any of three modes simply by
changing the directory name component of the URL (<CODE>cgi-bin|perl|cgi-perl</CODE>) - is not this neat? (That is the configuration you see above - all three
Aliases point to the same directory within your file system, but of course
@@ -161,9 +161,9 @@
<P>
Of course you can choose any other Alias (you will use it later in
-<CODE>httpd.conf</CODE>), 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.
+<CODE>httpd.conf</CODE>), you can choose to use all three modes or only one of these. It is
+undesirable to run scripts in plain mod_cgi from a mod_perl-enabled server
+- the price is too high, it is better to run these on plain apache server.
(See <A HREF="././strategy.html#Standalone_mod_perl_Enabled_Apac">Standalone mod_perl Enabled Apache Server</A>)
<P>
@@ -268,7 +268,7 @@
</Location>
</PRE>
<P>
-If you are going to use <CODE>Apache::Status</CODE>. It's important to put it as a first module in the start-up file, or in
+If you are going to use <CODE>Apache::Status</CODE>, it's important to put it as a first module in the start-up file, or in
the <CODE>httpd.conf</CODE> (after
<CODE>Apache::Registry</CODE>):
@@ -688,6 +688,14 @@
Makefile.PL PERL_SECTIONS=1</STRONG>.
<P>
+You can watch how have you configured the <CODE><Perl</CODE>> sections through the <A HREF="././config.html#_perl_status_location">/perl-status</A> location, by choosing the <STRONG>Perl Sections</STRONG> from the menu.
+
+<P>
+<A
+HREF="http://www.modperl.com/book/chapters/ch8.html#Debugging_B_E_lt_PerlE_gt_Sect">http://www.modperl.com/book/chapters/ch8.html#Debugging_B_E_lt_PerlE_gt_Sect</A>
+shows how can you dump the contents of your <CODE><Perl</CODE>> sections to the error_log.
+
+<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>
<P>
@@ -987,7 +995,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 07/02/1999
+ <BR>Last Modified at 08/15/1999
</FONT>
</B>
</TD>
1.17 +72 -72 modperl-site/guide/control.html
Index: control.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/control.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- control.html 1999/07/02 13:42:19 1.16
+++ control.html 1999/08/17 19:03:34 1.17
@@ -56,13 +56,12 @@
<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
+The easiest way to find the PID is to look it up in the <CODE>httpd.pid</CODE> file. With my configuration it exists as
+<CODE>/usr/local/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> PidFile /usr/local/var/httpd_perl/run/httpd.pid
</PRE>
<P>
Another way is to use the <CODE>ps</CODE> and <CODE>grep</CODE> utilities:
@@ -77,18 +76,16 @@
<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="././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
+This will produce a list of all <CODE>httpd_perl</CODE> (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
<CODE>httpd.conf</CODE>), but it's still easy to know 'who is the parent' -- the one of the
smallest size...
<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
+You will notice many <CODE>httpd_perl</CODE> 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: <STRONG>TERM</STRONG>, <STRONG>HUP</STRONG>, and <STRONG>USR1</STRONG>.
<P>
@@ -156,9 +153,10 @@
</DL>
<P>
It's worth mentioning that restart or termination can sometimes take quite
-a lot of time. Check out the <CODE>PERL_DESTRUCT_LEVEL=-1</CODE> option during the mod_perl <CODE>./Configure</CODE> stage, which speeds this up and leads to more robust operation in the face
+a lot of time. Check out the <CODE>PERL_DESTRUCT_LEVEL=-1</CODE> option during the mod_perl <CODE>perl Makefile.PL</CODE> 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 <CODE>END</CODE> blocks and <CODE>DESTROY</CODE> methods when the child terminates, of course. What constitutes significant
+significant cleanup has to be done by perl <CODE>END</CODE>
+blocks and <CODE>DESTROY</CODE> 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.
@@ -180,42 +178,39 @@
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
-<CODE>/usr/apps/sbin/httpd_perl/apachectl</CODE>.
+<CODE>/usr/local/sbin/httpd_perl/apachectl</CODE>.
<P>
Start httpd:
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl start
+<PRE> % /usr/local/sbin/httpd_perl/apachectl start
</PRE>
<P>
Stop httpd:
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl stop
+<PRE> % /usr/local/sbin/httpd_perl/apachectl stop
</PRE>
<P>
Restart httpd if running by sending a <STRONG>SIGHUP</STRONG> or start if not running:
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl restart
+<PRE> % /usr/local/sbin/httpd_perl/apachectl restart
</PRE>
<P>
Do a graceful restart by sending a <STRONG>SIGUSR1</STRONG> or start if not running:
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl graceful
+<PRE> % /usr/local/sbin/httpd_perl/apachectl graceful
</PRE>
<P>
Do a configuration syntax test:
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/apachectl configtest
+<PRE> % /usr/local/sbin/httpd_perl/apachectl configtest
</PRE>
<P>
-See the next section for the implication of the above calls.
-
-<P>
Replace <CODE>httpd_perl</CODE> with <CODE>httpd_docs</CODE> in the above calls to control the <STRONG>httpd_docs</STRONG> server.
<P>
@@ -223,7 +218,7 @@
<P>
It's important to understand that this script is based on the PID file
-which is <CODE>PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid</CODE>. If you delete the file by hand - <STRONG>apachectl</STRONG> will fail to run.
+which is <CODE>PIDFILE=/usr/local/var/httpd_perl/run/httpd.pid</CODE>. If you delete the file by hand - <STRONG>apachectl</STRONG> will fail to run.
<P>
Also, notice that <STRONG>apachectl</STRONG> is suitable to use from within your Unix system's startup files so that
@@ -328,10 +323,10 @@
#EMAIL=root@localhost
# the path to your PID file
- PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid
+ PIDFILE=/usr/local/var/httpd_perl/run/httpd.pid
# the path to your httpd binary, including options if necessary
- HTTPD=/usr/apps/sbin/httpd_perl/httpd_perl
+ HTTPD=/usr/local/sbin/httpd_perl/httpd_perl
# check for pidfile
if [ -f $PIDFILE ] ; then
@@ -361,23 +356,24 @@
fi
</PRE>
<P>
-Another approach, probably even more practical, is to use the cool
-<CODE>LWP</CODE> 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, 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.
+Another approach, probably even more practical, is to use the cool <CODE>LWP</CODE>
+perl package , to test the server by trying to fetch some document (script)
+served by the server. Why is it more practical? Because, while server can
+be up as a process, it can be stuck and not working, 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>
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,
+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.
+writing to an <CODE>error_log</CODE> file. Think big -- if you are 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>
So we end up with crontab entry:
@@ -398,14 +394,16 @@
my $VERSION = '0.01';
use vars qw($ua $proxy);
-
- require LWP::UserAgent;
+ $proxy = '';
+</PRE>
+<P>
+<PRE> require LWP::UserAgent;
use HTTP::Status;
###### 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 $restart_command = '/usr/local/sbin/httpd_perl/apachectl restart';
my $mail_program = '/usr/lib/sendmail -t -n';
######################
@@ -482,7 +480,7 @@
allowing you to run it more easily under debugger control.
<P>
-<PRE> % /usr/apps/sbin/httpd_perl/httpd_perl -X
+<PRE> % /usr/local/sbin/httpd_perl/httpd_perl -X
</PRE>
<P>
When you execute the above the server will run in the fg (foreground) of
@@ -535,8 +533,8 @@
# 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
+ PidFile /usr/local/var/httpd_perl/run/httpd.pid.sbekman
+ ErrorLog /usr/local/var/httpd_perl/logs/error_log.sbekman
Timeout 300
KeepAlive On
MinSpareServers 2
@@ -550,8 +548,8 @@
# 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
+ PidFile /usr/local/var/httpd_perl/run/httpd.pid.userfoo
+ ErrorLog /usr/local/var/httpd_perl/logs/error_log.userfoo
Timeout 300
KeepAlive Off
MinSpareServers 1
@@ -569,13 +567,13 @@
<P>
To make things even easier. (In the above technique, you have to discover
-the PID of your parent httpd_perl process - written in
-<CODE>/usr/apps/var/httpd_perl/run/httpd.pid.userfoo</CODE>) . We change the
+the PID of your parent <CODE>httpd_perl</CODE> process - written in
+<CODE>/usr/local/var/httpd_perl/run/httpd.pid.userfoo</CODE>) . 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>
-<PRE> PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid.sbekman
- HTTPD='/usr/apps/sbin/httpd_perl/httpd_perl -Dsbekman'
+<PRE> PIDFILE=/usr/local/var/httpd_perl/run/httpd.pid.sbekman
+ HTTPD='/usr/local/sbin/httpd_perl/httpd_perl -Dsbekman'
</PRE>
<P>
Of course you think you can use only one control file and know who is
@@ -587,7 +585,7 @@
mode by:
<P>
-<PRE> /usr/apps/sbin/httpd_perl/httpd_perl -Dsbekman -X
+<PRE> /usr/local/sbin/httpd_perl/httpd_perl -Dsbekman -X
</PRE>
<P>
In addition to making life easier, we decided to use relative links
@@ -596,8 +594,7 @@
we have utilized the mod_rewrite to solve our problems:
<P>
-In access.conf of the httpd_docs server we have the following code: (you
-have to configure your httpd_docs server with
+In <CODE>access.conf</CODE> of the <CODE>httpd_docs</CODE> server we have the following code: (you have to configure your <CODE>httpd_docs</CODE> server with
<CODE>--enable-module=rewrite</CODE> )
<P>
@@ -605,17 +602,17 @@
# 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]
+ RewriteRule ^(.*) <A HREF="http://nowhere.com:8000/">http://nowhere.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]
+ RewriteRule ^(.*) <A HREF="http://nowhere.com:8001/">http://nowhere.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]
+ RewriteRule ^(.*) <A HREF="http://nowhere.com:81/">http://nowhere.com:81/</A>$1 [R]
</PRE>
<P>
@@ -624,7 +621,7 @@
<CODE>REMOTE_USER</CODE> since we have all the users authenticated but it did not work for me)
<P>
-So if I have a relative URL like <CODE>/perl/test.pl</CODE> written in some html or even <CODE>http://www.nowhere.com/perl/test.pl</CODE> in my case (user at machine of <CODE>sbekman</CODE>) it will be redirected by httpd_docs to
+So if I have a relative URL like <CODE>/perl/test.pl</CODE> written in some html or even <CODE>http://www.nowhere.com/perl/test.pl</CODE> in my case (user at machine of <CODE>sbekman</CODE>) it will be redirected by <CODE>httpd_docs</CODE> to
<CODE>http://www.nowhere.com:8000/perl/test.pl</CODE>.
<P>
@@ -674,7 +671,7 @@
params, which will not happen when you call the cgi from the web)
<P>
-<PRE> #!/usr/apps/bin/perl -w
+<PRE> #!/usr/local/bin/perl -w
# This is a wrapper example
@@ -688,18 +685,19 @@
BEGIN{
use vars qw($basedir);
- $basedir = "/usr/apps";
+ $basedir = "/usr/local";
- # we want to make a complete emulation, so we must remove the
- # user's environment
+ # 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",
- );
+ push @INC,
+ qw($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;
@@ -714,7 +712,8 @@
# Set the environment
my $PERL5LIB = join ":", @INC;
- # if the path includes the directory we extract it and chdir there
+ # 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";
@@ -723,7 +722,7 @@
}
# run the cgi from the script's directory
- # Note that we invoke warnings and Taintness ON!!!
+ # Note that we invoke warnings and Taint mode ON!!!
system qq{$basedir/bin/perl -I$PERL5LIB -Tw $cgi $params};
</PRE>
<P>
@@ -753,7 +752,7 @@
I use this script:
<P>
-<PRE> #!/usr/apps/bin/perl -Tw
+<PRE> #!/usr/local/bin/perl -Tw
# this script does a log rotation. Called from crontab.
@@ -764,9 +763,9 @@
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 $logs_dir = "/usr/local/var/$server/logs";
+ my $restart_command = "/usr/local/sbin/$server/apachectl restart";
+ my $gzip_exec = "/usr/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;
@@ -894,8 +893,8 @@
<P>
<PRE> sub UNIVERSAL::AUTOLOAD {
- my $class = shift;
- warn "$class can't \$UNIVERSAL::AUTOLOAD!\n";
+ my $class = shift;
+ warn "$class can't \$UNIVERSAL::AUTOLOAD!\n";
}
</PRE>
<P>
@@ -913,6 +912,7 @@
<P>
<PRE> S=`ls -s /usr/local/apache/logs/error_log | awk '{print $1}'`
if [ "$S" -gt 100000 ] ; then
+ mv /usr/local/apache/logs/error_log /usr/local/apache/logs/error_log.old
/etc/rc.d/init.d/httpd restart
date | /bin/mail -s "error_log $S kB on inx" myemail@domain.com
fi
@@ -963,7 +963,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/27/1999
+ <BR>Last Modified at 08/05/1999
</FONT>
</B>
</TD>
1.6 +34 -1 modperl-site/guide/databases.html
Index: databases.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/databases.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- databases.html 1999/07/02 13:42:20 1.5
+++ databases.html 1999/08/17 19:03:35 1.6
@@ -41,6 +41,7 @@
<LI><A HREF="#Opening_a_connection_with_differ">Opening a connection with different parameters</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>
+ <LI><A HREF="#skipping_connection_cache_during">skipping connection cache during server startup</A>
</UL>
</UL>
@@ -179,6 +180,12 @@
users).
<P>
+Be warned though, that if your database is down, apache children will get
+delayed trying to <CODE>connect_on_init()</CODE>. They won't begin serving requests until they get logged in, or the login
+attempt fails (which can take several minutes (depending on your DBD
+driver).
+
+<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>
@@ -283,6 +290,32 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H3><A NAME="skipping_connection_cache_during">skipping connection cache during server startup</A></H3></CENTER>
+<P>
+Does your error_log looks like this:
+
+<P>
+<PRE> 10169 Apache::DBI PerlChildInitHandler
+ 10169 Apache::DBI skipping connection cache during server startup
+ Database handle destroyed without explicit disconnect at
+ /usr/lib/perl5/site_perl/5.005/Apache/DBI.pm line 29.
+</PRE>
+<P>
+then you are trying to open a database connection in the parent httpd
+process. If you do, children will get a copy of this handle, causing
+clashes when the handle is used by two processes at the same time. Each
+child must have its own unique connection handle.
+
+<P>
+To avoid this problem, <CODE>Apache::DBI</CODE> checks whether it is called during server startup. In this case the module
+skips the connection cache and returns immediately without a database
+handle.
+
+<P>
+You have to use the method <CODE>Apache::DBI-&gt;connect_on_init()</CODE> in the startup file.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="mysql_use_result_vs_mysql_store">mysql_use_result vs. mysql_store_result.</A></H1></CENTER>
<P>
Since many mod_perl developers uses mysql as their preferable engine, these
@@ -1161,7 +1194,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 08/16/1999
</FONT>
</B>
</TD>
1.6 +2 -2 modperl-site/guide/dbm.html
Index: dbm.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/dbm.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- dbm.html 1999/07/02 13:42:21 1.5
+++ dbm.html 1999/08/17 19:03:35 1.6
@@ -244,7 +244,7 @@
BEGIN {
# RCS/CVS complient: must be all one line, for MakeMaker
- $DB_File::Wrap::VERSION = do { my @r = (q$Revision: 1.5 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
+ $DB_File::Wrap::VERSION = do { my @r = (q$Revision: 1.6 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r };
}
@@ -464,7 +464,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/09/1999
</FONT>
</B>
</TD>
1.15 +24 -4 modperl-site/guide/debug.html
Index: debug.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/debug.html,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- debug.html 1999/07/02 13:42:22 1.14
+++ debug.html 1999/08/17 19:03:35 1.15
@@ -29,6 +29,7 @@
<LI><A HREF="#Sometimes_script_works_sometime">Sometimes script works, sometimes does not</A>
<LI><A HREF="#Non_interactive_debugging_when_r">Non-interactive debugging when running under mod_perl</A>
<LI><A HREF="#Apache_DB_Run_the_interactive">Apache::DB - Run the interactive Perl debugger under mod_perl</A>
+ <LI><A HREF="#Debugging_Core_Dumps">Debugging Core Dumps</A>
<LI><A HREF="#Debug_Tracing">Debug Tracing</A>
<LI><A HREF="#gdb_says_there_are_no_debugging_">gdb says there are no debugging symbols</A>
<LI><A HREF="#Monitoring_error_log_file">Monitoring error_log file</A>
@@ -116,6 +117,27 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Debugging_Core_Dumps">Debugging Core Dumps</A></H1></CENTER>
+<P>
+See the SUPPORT doc for hints on getting a stacktrace. To do this with
+<STRONG>make test</STRONG>, build mod_perl giving <CODE>Makefile.PL</CODE> the <CODE>PERL_DEBUG=1</CODE>
+flag. Now execute
+
+<P>
+<PRE> gdb ../apache_x.x.x/src/httpd
+ (gdb) thttpd
+</PRE>
+<P>
+(thttpd is defined in .gdbinit)
+
+<P>
+then, in another term run <STRONG>make run_tests</STRONG>, and at the gdb prompt:
+
+<P>
+<PRE> (gdb) bt
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Debug_Tracing">Debug Tracing</A></H1></CENTER>
<P>
To enable mod_perl debug tracing configure mod_perl with the PERL_TRACE
@@ -186,9 +208,7 @@
with some ISPs who provides user CGI support but no telnet access), you
might want to use a CGI script I wrote to fetch the latest lines from the
file (with a bonus of colored output for an easier reading). You might need
-to ask your ISP to install this script for a general usage. See <A HREF="././snippets.html#Watching_the_error_log_file_with">Watching the error_log file without telneting to the server.</A>
-
-
+to ask your ISP to install this script for a general usage. See <A HREF="././snippets.html#Watching_the_error_log_file_with">Watching the error_log file without telneting to the server</A>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -360,7 +380,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
1.4 +28 -17 modperl-site/guide/download.html
Index: download.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/download.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- download.html 1999/06/19 21:15:03 1.3
+++ download.html 1999/08/17 19:03:36 1.4
@@ -27,15 +27,16 @@
<UL>
<LI><A HREF="#Coverage">Coverage</A>
- <LI><A HREF="#perl">perl</A>
- <LI><A HREF="#apache">apache</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_Internet_Object_Cache">Squid - Internet Object Cache</A>
<LI><A HREF="#thttpd_tiny_turbo_throttling_H">thttpd - tiny/turbo/throttling HTTP server</A>
<LI><A HREF="#mod_proxy_add_forward">mod_proxy_add_forward</A>
<LI><A HREF="#httperf_webserver_Benchmarking">httperf - webserver Benchmarking tool</A>
<LI><A HREF="#ab_ApacheBench">ab - ApacheBench</A>
- <LI><A HREF="#Eddieware">Eddieware</A>
+ <LI><A HREF="#High_Availability_Linux_Project">High-Availability Linux Project</A>
+ <LI><A HREF="#Apache_Request">Apache::Request</A>
</UL>
<!-- INDEX END -->
@@ -55,26 +56,26 @@
<P>
<CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
<P>
-Here you will find the instructions for downloading the software and the
+Here you will find instructions for downloading the software and the
related documentation.
<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>
+<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
+least check the version you are using. It is highly recommended that you
+have at least Perl version 5.004. 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.
+. You can get Perl documentation from the same location.
<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>
+<CENTER><H1><A NAME="Apache">Apache</A></H1></CENTER>
<P>
-Get the latest apache webserver and documentation from <A
+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> .
@@ -111,7 +112,7 @@
<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
+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
@@ -129,14 +130,24 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="ab_ApacheBench">ab - ApacheBench</A></H1></CENTER>
+<P>
+Comes with the Apache distribution.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="High_Availability_Linux_Project">High-Availability Linux Project</A></H1></CENTER>
<P>
-Comes within apache distribution.
+You will find the definite guide to load balancing techniques at the
+High-Availability Linux Project site -- <A
+HREF="http://www.henge.com/~alanr/ha/">http://www.henge.com/~alanr/ha/</A>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Eddieware">Eddieware</A></H1></CENTER>
+<CENTER><H1><A NAME="Apache_Request">Apache::Request</A></H1></CENTER>
<P>
-<A HREF="http://www.eddieware.org">http://www.eddieware.org</A>
+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><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
@@ -161,7 +172,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/19/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
1.7 +1 -1 modperl-site/guide/frequent.html
Index: frequent.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/frequent.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- frequent.html 1999/07/02 13:42:22 1.6
+++ frequent.html 1999/08/17 19:03:36 1.7
@@ -92,7 +92,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 05/08/1999
+ <BR>Last Modified at 07/09/1999
</FONT>
</B>
</TD>
1.9 +792 -820 modperl-site/guide/guide-src.tar.gz
<<Binary file>>
1.10 +1419 -1398modperl-site/guide/guide.tar.gz
<<Binary file>>
1.5 +196 -192 modperl-site/guide/hardware.html
Index: hardware.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/hardware.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- hardware.html 1999/07/02 13:42:27 1.4
+++ hardware.html 1999/08/17 19:03:41 1.5
@@ -42,10 +42,11 @@
<LI><A HREF="#Choosing_Hardware">Choosing Hardware</A>
<UL>
- <LI><A HREF="#Site_traffic">Site traffic</A>
+ <LI><A HREF="#Expected_site_traffic">Expected site traffic</A>
<LI><A HREF="#Cash">Cash</A>
- <LI><A HREF="#Memory">Memory</A>
<LI><A HREF="#Internet_Connection">Internet Connection</A>
+ <LI><A HREF="#I_O_performance">I/O performance</A>
+ <LI><A HREF="#Memory">Memory</A>
<LI><A HREF="#Bottlenecks">Bottlenecks</A>
<LI><A HREF="#Conclusion">Conclusion</A>
</UL>
@@ -69,41 +70,42 @@
<P>
<CENTER><H1><A NAME="Is_it_important_">Is it important?</A></H1></CENTER>
<P>
-You can invest a lot of time and money in server tuning and code rewriting
-according the guidelines you have just learned, but your performance will
-be really bad if you did not take into account the hardware demands, and
-did not wisely chose the operating system suited for your needs. While the
-tips below apply to any webserver, they are written for a mod_perl enabled
-webservers' administrators.
+You can invest a lot of time and money into server tuning and code
+rewriting according the guidelines you have just learned, but your
+performance will be really bad if you do not take into account the hardware
+demands, and do not wisely choose the operating system suited for your
+needs. While the tips below apply to any webserver, they are written for an
+administrator of a mod_perl-enabled webserver
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Choosing_an_Operating_System">Choosing an Operating System</A></H1></CENTER>
<P>
-First lets talk about Operating Systems (OS). While personally I am a Linux
-devotee, I do not want to start yet another OS war. Assuming this, I will
-try to define what you should be looking for, then when you know what do
-you want from your OS, go find it. Visit the Web sites of operating systems
-you are interested in. You can gauge user's opinions by searching relevant
-discussions in newsgroup and mailing list archives such as Deja - <A
-HREF="http://deja.com">http://deja.com</A> and eGroups - <A
+First let's talk about Operating Systems (OS). While I am personally a
+Linux devotee, I do not want to start yet another OS war. Assuming this, I
+will try to define what you should be looking for, then when you know what
+do you want from your OS, go find it. Visit the Web sites of operating
+systems you are interested in. You can gauge user's opinions by searching
+relevant discussions in newsgroup and mailing list archives such as Deja -
+<A HREF="http://deja.com">http://deja.com</A> and eGroups - <A
HREF="http://egroups.com">http://egroups.com</A> . I will leave this fan
-research up to you. But I would use linux :o) Just kidding...
+research up to you. But I would use Linux or something from the
+<CODE>*BSD</CODE> family.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Stability_and_Robustness">Stability and Robustness</A></H2></CENTER>
<P>
Probably the most desired features in an OS are stability and robustness.
-We are involved in an Internet business, which does not have normal working
-hours, like many conventional businesses we know about (9pm to 5pm). We are
-open 24 hours a day. We can not afford off line periods, for our customers
-will go shop for another service like ours, unless you have a monopoly :) .
-If the OS of your choice crashes every day or so, I would throw it away,
-after doing a little investigation, for there are might be a reason for a
-system crash. Like a runaway server that eats up all the memory and disk,
-so we cannot blame the OS for that. Generally people who use the OS for
-some time can tell you a lot about its stability.
+You are in an Internet business, which does not have normal working hours,
+like many conventional businesses you know about (9am to 5pm). You are open
+24 hours a day. You cannot afford to be off-line, for your customers will
+go shop at another service like yours, unless you have a monopoly :) . If
+the OS of your choice crashes every day or so, I would throw it away, after
+doing a little investigation, for there might be a reason for a system
+crash. Like a runaway server that eats up all the memory and disk, so you
+cannot blame the OS for that. Generally, people who use the OS for some
+time can tell you a lot about its stability.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -118,55 +120,54 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Memory_Leakages">Memory Leakages</A></H2></CENTER>
<P>
-Some OSes and/or the libraries (like C libraries) suffer from memory
-leakage. You cannot afford such a system, for you are already know that a
-single mod_perl process sometimes serves thousands of requests before it
-terminates. So if a leak occurs on every request, your memory demands will
-be huge. Of course your code can be the cause of the memory leakages as
-well (check out the <CODE>Apache::Leak</CODE>
-module). Certainly you can lower the number of requests to be served over
-the process' life, but performance degrades with this.
+Some OSes and/or the libraries (like C runtime libraries) suffer from
+memory leaks. You cannot afford such a system, for you are already know
+that a single mod_perl process sometimes serves thousands of requests
+before itimer terminates. So if a leak occurs on every request, your memory
+demands will be huge. Of course your code can be the cause of the memory
+leaks as well (check out the <CODE>Apache::Leak</CODE>
+module). Certainly, you can lower the number of requests to be served over
+the process' life, but that can degrade performance.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Sharing_Memory">Sharing Memory</A></H2></CENTER>
<P>
You want an OS with good memory sharing capabilities. As you have learned,
-if you preload the modules and scripts at server startup, they are being
-shared between the spawned children, at least for a part of a process' life
-span, since memory pages are getting ``dirty'' and ceasing to be shared.
-This feature can save you up a lot of memory!!!
+if you preload the modules and scripts at server startup, they are shared
+between the spawned children, at least for a part of a process' life span,
+since memory pages become ``dirty'' and cease to be shared. This feature
+can save you up a lot of memory!
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Cost_and_Support">Cost and Support</A></H2></CENTER>
<P>
-If you are into a big business you are probably do not care to pay another
+If you are in a big business you are probably do not mind paying another
<CODE>$1000</CODE> for some fancy OS and to get the bundled support for it.
-But if your resources are low, you will look for cheaper and free OSes.
-Free does not mean bad, it can be quite opposite as we all either know from
-our own experience or read about in news. Free OSes could have and do have
-the best support you can find. It is very easy to understand - most of the
+But if your resources are low, you will look for cheaper and free OS. Free
+does not mean bad, it can be quite opposite as we all either know from our
+own experience or read about in news. Free OSes could have and do have the
+best support you can find. It is very easy to understand - most of the
people are not rich and will try to use a cheaper or free OS first if it
does the work for them. Since it really fits their needs, many people keep
using it and eventually know it well enough to be able to provide support
-for others in trouble. Why would they do this for free? For a real spirit
-of the first days of the Internet, when there was no commercial Internet
-and people helped each other, because someone helped them in first place. I
-was there, I was touched by that spirit and I will do anything to keep this
+for others in trouble. Why would they do this for free? For the spirit of
+the first days of the Internet, when there was no commercial Internet and
+people helped each other, because someone helped them in first place. I was
+there, I was touched by that spirit and I will do anything to keep that
spirit alive.
<P>
But, let's get back to our world. We are living in material world, and our
bosses pay us to keep the systems running. So if you feel that you cannot
provide the support yourself and you do not trust the available free
-resources, you must get an OS that has a company behind it to pay to blame
-for any problems you encounter in hopes that your cries for help will be
-heard and answered. Your boss wants to be able to sue someone if the
-project has a problem caused by the external product that is being used in
-the project. If you buy a product and the company selling it, claims
-support, you have someone to sue. You do not have someone to sue other than
-getting yourself fired if you go with Open Source and it fails.
+resources, you must pay for an OS backed by a company, and blame them for
+any problem. Your boss wants to be able to sue someone if the project has a
+problem caused by the external product that is being used in the project.
+If you buy a product and the company selling it, claims support, you have
+someone to sue. You do not have someone to sue other than getting yourself
+fired if you go with Open Source and it fails.
<P>
Also remember that if you spend less or zero money on OS and Software, you
@@ -176,30 +177,30 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Discontinued_products">Discontinued products</A></H2></CENTER>
<P>
-You have invested a lot into a developing of some proprietary software,
-that is bundled with the OS you were developing on and for. Like you write
-some mod_perl handler that takes an advantage of some proprietary features
-of the OS and it will not run on any other OS. Things are under control,
-the performance is great and you sing from happiness. But... one day the
-company who wrote your beloved OS went bankrupt, which is not unlikely to
-happen nowadays. You have got stuck with their last masterpiece and no
-support! What you are going to do then? Invest more into porting the
-software for another OS...
+You have invested a lot of time and money into developing some proprietary
+software that is bundled with the OS you were developing on. Like writing a
+mod_perl handler that takes advantage of some proprietary features of the
+OS and it will not run on any other OS. Things are under control, the
+performance is great and you sing from happiness. But... one day the
+company who wrote your beloved OS goes bankrupt, which is not unlikely to
+happen nowadays. You are stuck with their last masterpiece and no support!
+What you are going to do then? Invest more into porting the software to
+another OS...
<P>
-Everyone can be hit by this mini disaster, so it is better to watch the
+Everyone can be hit by this mini-disaster, so it is better to check the
background of the company when making your choice, but still you never know
-what will happen in a next minute. The OSes in this hazard group are
-completely developed by a single companies. Free OSes are probably less
-susceptible to this, for development is distributed between many companies
-and developers, so if a person who developed a really important part of the
-kernel lost interest to continue, someone else will pick the falling flag
-and continue from the same place. Of course if tomorrow some better project
-shows up, developers might migrate there and finally drop the development,
-but we are here not to let this happen.
+what will happen tomorrow. The OSes in this hazard group are completely
+developed by a single companies. Free OSes are probably less susceptible to
+this, for development is distributed between many companies and developers,
+so if a person who developed a really important part of the kernel lost
+interest in continuing, someone else will pick the falling flag and carry
+on. Of course if tomorrow some better project showed up, developers might
+migrate there and finally drop the development, but we are here not to let
+this happen.
<P>
-But you are the one to make the right decision...
+In the final analysis, the decision is yours.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -207,29 +208,28 @@
<P>
Actively developed OSes generally try to keep the pace with the latest
technology developments, and continually optimize the kernel and other
-parts of OS to become better and faster. Nowadays, Internet and Networking
-in general are the hottest targets for system developers. Sometimes a
-simple OS upgrade to a latest stable version, can save you an expensive
-hardware upgrade. Also, remember that when you buy a new hardware, chances
-are that the latest software will make the most out of it. Since while the
-existing software (drivers) might support the new brand product because of
-its back compatibility with previous products of the same family, it might
-not take advantage of new features. It means that you could spend much less
-money for almost the same functionality if you were to buy a previous model
-of the same product.
+parts of the OS to become better and faster. Nowadays, Internet and
+networking in general are the hottest targets for system developers.
+Sometimes a simple OS upgrade to a latest stable version, can save you an
+expensive hardware upgrade. Also, remember that when you buy new hardware,
+chances are that the latest software will make the most of it. Since the
+existing software (drivers) might support the brand new product because of
+its backwards compatibility with previous products of the same family, it
+might not reap all the benefits of the new features. It means that you
+could spend much less money for almost the same functionality if you were
+to buy a previous model of the same product.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Choosing_Hardware">Choosing Hardware</A></H1></CENTER>
<P>
While I am not fond of the idea of updating this section every day a new
-processor or memory type comes out, exactly like with OS choosing
-guidelines, I will only hint what should you look after and persuade you
-that sometimes the most expensive machine is not the one which provides the
-best performance.
+processor or memory type comes out, I will only hint what should you look
+for and suggest that sometimes the most expensive machine is not the one
+which provides the best performance.
<P>
-Your demands are bound to many aspects and components. Let's discuss some
+Your demands are based on many aspects and components. Let's discuss some
of them.
<P>
@@ -253,7 +253,7 @@
users. One of the advantages is that you can take one of the machines down
for a repair or upgrade, and your service will still work - the main server
will not dispatch the requests to the machine that was taken down. I will
-just say that there are many load balancing techniques. (e.g. <A HREF="././download.html#">Eddieware</A>)
+just say that there are many load balancing techniques. (See <A HREF="././download.html#High_Availability_Linux_Project">High-Availability Linux Project</A> for more info.)
<P><LI>
<P>
@@ -270,9 +270,9 @@
</UL>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Site_traffic">Site traffic</A></H2></CENTER>
+<CENTER><H2><A NAME="Expected_site_traffic">Expected site traffic</A></H2></CENTER>
<P>
-If you are building a fans' site, but want to amaze your friends with
+If you are building a fan site, but want to amaze your friends with a
mod_perl guest book, an old 486 machine will do it. If you are into a
serious business, it is very important to build a scalable server, so if
your service is successful and becomes popular, you get your server's
@@ -300,11 +300,11 @@
<CENTER><H2><A NAME="Cash">Cash</A></H2></CENTER>
<P>
Everybody knows that Internet is a cash hole, what you throw in, hardly
-comes back. This is not always correct, but there is a lot of wisdom in
-these words. While you have to invest money to build a decent service, it
-can be cheaper! You can spend as much as 10 times more money on a strong
-new machine, but get only a 10% improve in performance. Remember that
-processor that was born 4 years ago is still very mighty.
+comes back. This is not always true, but there is a lot of wisdom in these
+words. While you have to invest money to build a decent service, it can be
+cheaper! You can spend as much as 10 times more money on a strong new
+machine, but get only a 10% improvement in performance. Remember that a
+four year old processor is still very powerful.
<P>
If you really need a lot of power do not think about a single strong
@@ -313,92 +313,30 @@
machines and have a 8 times more power, then purchasing only one single new
machine. Why is that? Because as I mentioned before generally the
performance improvement is marginal while the price is much bigger. Because
-10 machines will do a faster Hard Disk IO (Input/Output), then one single
-machine even if the disk is much faster. Yes, you have more administration
-overhead, but there is a chance you will have it anyway, for in a short
-time the machine you have just invested into will not stand the load and
-you will have to purchase more and think how to implement the load
-balancing and file system distribution.
+10 machines will do faster disk I/O, than one single machine, even if the
+disk is much faster. Yes, you have more administration overhead, but there
+is a chance you will have it anyway, for in a short time the machine you
+have just invested in will not stand the load anyway and you will have to
+purchase more and think how to implement load balancing and file system
+distribution.
<P>
Why I am so convinced? Facts! Look at the most used services on the
-Internet: search engines, email servers and alike - most of them are using
-clustering approach. While you will not always notice that, they do it by
-hiding the real implementation behind the proxy servers.
-
-<P>
-<PRE> =head2 IO performance
-</PRE>
-<P>
-If your service is IO bound (does a lot of read/write operations to your
-disk, remember that relational DataBases are sitting on disk as well) you
-need a very fast disk. So you should not spend money on a Video card and
-monitor (monochrome card and 14`` B&W will do for server
-configuration), but rather look for the best price/performance in disks (of
-course asking around for a solid firm, whose HDs are not getting corrupted
-at all.) With money in hand you should think about getting a RAID system.
-RAID is generally a box with many HDs. It is capable of reading/writing
-data much faster, and is protected against disk corruptions. It does this
-by duplicating the same data over a number of disks, so if one gets
-corrupted the RAID detects it and the data is still correct on the
-duplicated disks. You must think about RAID or similar systems if you have
-an enormous data set to serve. (What is an enormous data set nowadays?).
-
-<P>
-Ok, we have a fast disk, what's next? You need a fast disk controller. So
-either you should use the one embedded on your motherboard or you should
-plug a controller card if the one you have onboard is not good enough.
+Internet: search engines, email servers and the like -- most of them are
+using a clustering approach. While you may not always notice that, they do
+it by hiding the real implementation behind the proxy servers.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Memory">Memory</A></H2></CENTER>
-<P>
-How much RAM (Randomly Accessed Memory) do you need? Nowadays, chances are
-you will hear: ``Memory is cheap, the more you buy the better''. But how
-much is enough? The answer pretty straightforward: ``You do not want your
-machine to swap''. When the CPU needs to write something into memory, but
-notices that it is already full, it takes the least frequently used memory
-pages (4k/page on average OS) and swaps them out. Swapping out means
-copying to the disk into a special partition or file called swap and
-deleting from the real memory. When another process asks the CPU to access
-another page, but CPU cannot find the memory page in RAM (it was just
-swapped out), it goes and brings it from the swap (swapping in). If memory
-is small, swapping (in/out) happens too frequently, the CPU becomes too
-busy swapping pages in and out, the HD is working hard to read/write the
-swapped out pages, and the whole performance of the system is going down.
-Sometimes your swap partition can become full as well and your system might
-die.
-
-<P>
-How do you make a decision? You know what is the highest page request rate
-your service has and how much time an average request takes. Now you can
-calculate how many servers do you need. Knowing the maximum size any of
-your servers can get, you know how much memory do you need. You probably
-need less memory that you have calculated if your OS supports memory
-sharing and you know how to deploy this feature (preloading the modules and
-scripts at server's startup). Do not forget that other essential system
-processes need memory as well, so you should not plan for the webserver
-only, but to take into an account all processes to be run on your system.
-Remember that requests can be queued, so you can afford your client to wait
-a few moments, while some server comes to service it, your numbers will be
-more correct, since you generally do not have the highest load, but you
-should be ready to bear the picks. So you need to reserve at least 20% of
-free memory for peak situations. Many sites were reported to crash a few
-moments after some scooping news about them were posted, and unexpected
-number of requests suddenly came in. If you are about to announce something
-cool, be aware of possible consequences.
-
-<P>
-<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Internet_Connection">Internet Connection</A></H2></CENTER>
<P>
-You have the best hardware you could get, but the service is still
-crawling. Make sure you have a fast Internet connection. Not _fast_ as your
-ISP claims it to be, but fast as it should be. The ISP might have a very
-good connection to the Internet, but put many clients on the same line. If
-these are heavy clients your traffic will have to share the same line, thus
-your speed is effectively limited. Think about a dedicated connection and
-make sure it is truly dedicated, trust the ISP but check it!
+You have the best hardware you can get, but the service is still crawling.
+Make sure you have a fast Internet connection. Not as fast as your ISP
+claims it to be, but fast as it should be. The ISP might have a very good
+connection to the Internet, but puts many clients on the same line. If
+these are heavy clients, your traffic will have to share the same line and
+the throughput will decline. Think about a dedicated connection and make
+sure it is truly dedicated. Trust the ISP but check it!
<P>
The idea of having a connection to <STRONG>The Internet</STRONG> is a little misleading. Many Web hosting and co-location companies have
@@ -417,34 +355,100 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H2><A NAME="Bottlenecks">Bottlenecks</A></H2></CENTER>
+<CENTER><H2><A NAME="I_O_performance">I/O performance</A></H2></CENTER>
<P>
-The most important thing to understand is that you might use the most
-expensive components, but still get a bad performance. Why? Let me
-introduce you to this annoying word: A bottleneck.
+If your service is I/O bound (does a lot of read/write operations to disk,
+remember that relational databases are sitting on disk as well) you need a
+very fast disk. So you should not spend money on Video card and monitor
+(monochrome card and 14`` B&W are perfectly adequate for a server --
+you will probably be telnetted or ssh-ed in most of the time), but rather
+look for disks with the best price/performance ratio. Of course, ask around
+and avoid disks that have a reputation for headcrashes and other disasters.
+
+<P>
+With money in hand you should think about getting a RAID system. RAID is
+generally a box with many HDs. It is capable of reading and writing data
+much faster, and is protected against disk failures. It does this by
+duplicating the same data over a number of disks, so if one fails, the RAID
+controller detects it and the data is still correct on the duplicated
+disks. You must think about RAID or similar systems if you have an enormous
+data set to serve. (What is an enormous data set nowadays? Gigabytes,
+terabytes?).
<P>
-A machine is an aggregate of many small and big components. Each one of
-them can become a bottleneck. If you have a fast processor but a small
-amount of RAM (memory), the processor will be under utilized waiting for
-the kernel to swap memory pages in and out, because memory is too small to
-fit at least the most used ones. If you have a lot of memory and a fast
-processor and a fast disk, but a slow controller - the performance will be
-bad, and you have wasted the money.
+Ok, we have a fast disk, what's next? You need a fast disk controller. So
+either you should use the one embedded on your motherboard or you should
+plug a controller card if the one you have onboard is not good enough.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Memory">Memory</A></H2></CENTER>
+<P>
+How much RAM (Randomly Accessed Memory) do you need? Nowadays, chances are
+you will hear: ``Memory is cheap, the more you buy the better''. But how
+much is enough? The answer pretty straightforward: ``You do not want your
+machine to swap''. When the CPU needs to write something into memory, but
+notices that it is already full, it takes the least frequently used memory
+pages and swaps them out. Swapping out means writing the data to disk.
+Another process then references some of its own data, which happens to be
+on one of the pages that were just swapped out. The CPU, ever obliging,
+swaps it back in again, probably swapping out some other data that will be
+needed very shortly by another process. Carried to the extreme, the CPU and
+disk start to thrash hopelessly in circles, without getting any real work
+done. The less RAM there is, the more often this scenario arises. Worse,
+you can exhaust swap space as well, and then the troubles really set in...
+
+<P>
+How do you make a decision? You know the highest rate your server expects
+to serve pages and how long it takes to do so. Now you can calculate how
+many server processes you need. Knowing the maximum size any of your
+servers can get, you know how much memory you need. You probably need less
+memory than you have calculated if your OS supports memory sharing and you
+know how to make best use of this feature (preloading the modules and
+scripts at server startup). Do not forget that other essential system
+processes need memory as well, so you should plan not only for the web
+server, but also take into account the other players. Remember that
+requests can be queued, so you can afford to let your client wait for a few
+moments until a server is available to serve it, your numbers will be more
+correct, since you generally do not have the highest load, but you should
+be ready to bear the peaks. So you need to reserve at least 20% of free
+memory for peak situations. Many sites have crashed a few moments after a
+big scoop about them was posted and unexpected number of requests suddenly
+came in. (This is called a Slashdot effect, which was born at <A
+HREF="http://slashdot.org">http://slashdot.org</A> ) If you are about to
+announce something cool, be aware of the possible consequences.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Bottlenecks">Bottlenecks</A></H2></CENTER>
+<P>
+The most important thing to understand is that you might use the most
+expensive components, but still get bad performance. Why? Let me introduce
+an annoying word: A bottleneck.
<P>
-Of course use a NIC (Network Interface Card) that does not create a
-bottleneck. If it is slow, the whole service is slow.
+A machine is an aggregate of many big and small components. Each one of
+them may be a bottleneck. If you have a fast processor but a small amount
+of RAM (memory), the processor will be under-utilized waiting for the
+kernel to swap the memory pages in and out, because memory is too small to
+hold the most used ones. If you have a lot of memory and a fast processor
+and a fast disk, but a slow controller - the performance will be bad, and
+you have wasted money.
+
+<P>
+Use a fast NIC (Network Interface Card) that does not create a bottleneck.
+If it is slow, the whole service is slow. This is the most important
+component, since webservers are much more network-bound than disk-bound!
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Conclusion">Conclusion</A></H2></CENTER>
<P>
-To optimally use your money, you have to either understand the hardware
-very well, so you will know what to pick, or you should hire a
-knowledgeable hardware consultants and employ them on a constant basis,
-since your demands will probably change as time goes on, and your HW should
-be adapted with each change you make.
+To use your money optimally you have to understand the hardware very well,
+so you will know what to pick. Otherwise, you should hire a knowledgeable
+hardware consultants and employ him/her on a regular basis, since your
+demands will probably change as time goes by and your hardware will
+likewise be forced to adapt as well.
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
@@ -469,7 +473,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
1.16 +12 -1 modperl-site/guide/help.html
Index: help.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/help.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- help.html 1999/07/02 13:42:27 1.15
+++ help.html 1999/08/17 19:03:41 1.16
@@ -94,6 +94,11 @@
<P>
<A HREF="http://perl.apache.org">http://perl.apache.org</A>
+<P><DT><STRONG>mod_perl Garden project</STRONG><DD>
+<P>
+<A
+HREF="http://modperl.sourcegarden.org">http://modperl.sourcegarden.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
@@ -144,6 +149,12 @@
<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 Resources Page</A></STRONG>
+<P>
+<A
+HREF="http://www.perlreference.com/mod_perl/">http://www.perlreference.com/mod_perl/</A>
+
+
<P><LI><STRONG><A NAME="item_mod_perl">mod_perl mailing list</A></STRONG>
<P>
The Apache/Perl mailing list (<A
@@ -340,7 +351,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
1.19 +36 -12 modperl-site/guide/index.html
Index: index.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/index.html,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- index.html 1999/07/02 13:42:28 1.18
+++ index.html 1999/08/17 19:03:41 1.19
@@ -27,8 +27,8 @@
<CENTER><P><B>Deploying mod_perl technology to give a rocket speed
to your CGI/perl scripts.</B></P></CENTER>
-<CENTER><P><B>Version 1.14
- Jul, 2 1999</B></P></CENTER>
+<CENTER><P><B>Version 1.15
+ Aug, 17 1999</B></P></CENTER>
<P>
<HR WIDTH="100%"></P>
@@ -66,6 +66,7 @@
<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#More_package_name_related_issues">More package name related issues</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>
@@ -83,6 +84,7 @@
<LI><A HREF="porting.html#Passing_ENV_variables_to_CGI">Passing ENV variables to CGI</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#Apache_and_syslog">Apache and syslog</A>
<LI><A HREF="porting.html#Memory_leakage">Memory leakage</A>
</UL>
@@ -92,6 +94,7 @@
<LI><A HREF="porting.html#Restarting_the_server">Restarting the server</A>
<LI><A HREF="porting.html#Using_Apache_StatINC">Using Apache::StatINC</A>
<LI><A HREF="porting.html#Reloading_only_specific_files">Reloading only specific files</A>
+ <LI><A HREF="porting.html#Reloading_handlers">Reloading handlers</A>
</UL>
<LI><A HREF="porting.html#Filehandlers_and_locks_leakages">Filehandlers and locks leakages</A>
@@ -115,7 +118,9 @@
<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#How_can_I_find_if_my_mod_perl_sc">How can I find if my mod_perl scripts have memory leaks (and where)</A>
+ <LI><A HREF="performance.html#Shared_Memory">Shared Memory</A>
+ <LI><A HREF="performance.html#Checking_script_modification_tim">Checking script modification times</A>
+ <LI><A HREF="performance.html#How_can_I_find_if_my_mod_perl_sc">How can I find if my mod_perl scripts have memory leaks</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>
@@ -190,7 +195,7 @@
<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#Building_and_Using_mod_proxy">Building and Using mod_proxy</A>
<LI><A HREF="scenario.html#mod_perl_server_as_DSO">mod_perl server as DSO</A>
<LI><A HREF="scenario.html#HTTP_Authentication_with_2_serve">HTTP Authentication with 2 servers + proxy</A>
</UL>
@@ -351,6 +356,12 @@
<LI><A HREF="security.html#Non_authenticated_access_for_int">Non authenticated access for internal IPs, but authenticated by external IPs</A>
</UL>
+ <LI><A HREF="security.html#Authentication_code_snippets">Authentication code snippets</A>
+ <UL>
+
+ <LI><A HREF="security.html#Forcing_reauthenticating">Forcing reauthenticating</A>
+ </UL>
+
</UL>
<P><LI><A HREF="databases.html"><B><FONT SIZE=+1>mod_perl and Relational Databases</FONT></B></A></LI><P>
<UL>
@@ -370,6 +381,7 @@
<LI><A HREF="databases.html#Opening_a_connection_with_differ">Opening a connection with different parameters</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>
+ <LI><A HREF="databases.html#skipping_connection_cache_during">skipping connection cache during server startup</A>
</UL>
</UL>
@@ -417,6 +429,7 @@
<LI><A HREF="debug.html#Sometimes_script_works_sometime">Sometimes script works, sometimes does not</A>
<LI><A HREF="debug.html#Non_interactive_debugging_when_r">Non-interactive debugging when running under mod_perl</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#Debugging_Core_Dumps">Debugging Core Dumps</A>
<LI><A HREF="debug.html#Debug_Tracing">Debug Tracing</A>
<LI><A HREF="debug.html#gdb_says_there_are_no_debugging_">gdb says there are no debugging symbols</A>
<LI><A HREF="debug.html#Monitoring_error_log_file">Monitoring error_log file</A>
@@ -439,11 +452,14 @@
<LI><A HREF="modules.html#Apache_PerlRun_Run_unaltered_">Apache::PerlRun - Run unaltered CGI scripts under mod_perl</A>
<LI><A HREF="modules.html#Apache_GzipChain_compress_HTM">Apache::GzipChain - compress HTML (or anything) in the OutputChain</A>
<LI><A HREF="modules.html#Apache_PerlVINC_set_a_differe">Apache::PerlVINC - set a different @INC perl-location </A>
+ <LI><A HREF="modules.html#Apache_RegistryBB_Apache_Re">Apache::RegistryBB -- Apache::Registry Bare-Bones</A>
+ <LI><A HREF="modules.html#Apache_LogSTDERR">Apache::LogSTDERR</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#perldoc_s_little_known_but_very_">perldoc's little known but very useful options</A>
<LI><A HREF="perl.html#Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A>
<UL>
@@ -458,9 +474,9 @@
<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#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#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>
@@ -483,10 +499,11 @@
<LI><A HREF="hardware.html#Choosing_Hardware">Choosing Hardware</A>
<UL>
- <LI><A HREF="hardware.html#Site_traffic">Site traffic</A>
+ <LI><A HREF="hardware.html#Expected_site_traffic">Expected site traffic</A>
<LI><A HREF="hardware.html#Cash">Cash</A>
- <LI><A HREF="hardware.html#Memory">Memory</A>
<LI><A HREF="hardware.html#Internet_Connection">Internet Connection</A>
+ <LI><A HREF="hardware.html#I_O_performance">I/O performance</A>
+ <LI><A HREF="hardware.html#Memory">Memory</A>
<LI><A HREF="hardware.html#Bottlenecks">Bottlenecks</A>
<LI><A HREF="hardware.html#Conclusion">Conclusion</A>
</UL>
@@ -514,15 +531,16 @@
<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#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_Internet_Object_Cache">Squid - Internet Object Cache</A>
<LI><A HREF="download.html#thttpd_tiny_turbo_throttling_H">thttpd - tiny/turbo/throttling HTTP server</A>
<LI><A HREF="download.html#mod_proxy_add_forward">mod_proxy_add_forward</A>
<LI><A HREF="download.html#httperf_webserver_Benchmarking">httperf - webserver Benchmarking tool</A>
<LI><A HREF="download.html#ab_ApacheBench">ab - ApacheBench</A>
- <LI><A HREF="download.html#Eddieware">Eddieware</A>
+ <LI><A HREF="download.html#High_Availability_Linux_Project">High-Availability Linux Project</A>
+ <LI><A HREF="download.html#Apache_Request">Apache::Request</A>
</UL>
<P>
@@ -562,6 +580,12 @@
href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
Amazon.com</a>.
<HR>
+<P>
+
+Now you can search the indexed version of the guide at <A
+HREF="http://www.perlreference.com/mod_perl/guide">perlreference.com</A>.
+
+<HR>
<CENTER>
<TABLE BORDER=10 CELLSPACING=2 CELLPADDING=8 >
<TR BGCOLOR="gray" ALIGN=CENTER VALIGN=TOP>
@@ -597,7 +621,7 @@
<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 07/02/1999
+HREF="help.html#This_document_s_Author">Stas Bekman</A>.<BR> Last Modified at 08/17/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>
1.6 +1 -1 modperl-site/guide/install.html
Index: install.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/install.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- install.html 1999/07/02 13:42:28 1.5
+++ install.html 1999/08/17 19:03:42 1.6
@@ -504,7 +504,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 07/02/1999
+ <BR>Last Modified at 07/09/1999
</FONT>
</B>
</TD>
1.13 +43 -44 modperl-site/guide/intro.html
Index: intro.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/intro.html,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- intro.html 1999/07/02 13:42:28 1.12
+++ intro.html 1999/08/17 19:03:42 1.13
@@ -50,27 +50,27 @@
<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
+possible to write Apache modules entirely in Perl, letting 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.
+as running sub requests. In addition, the persistent Perl interpreter
+embedded in the server saves the overhead of starting an external
+interpreter, i.e. the penalty of Perl start-up time. And not the least
+important feature is code caching, where modules and scripts are loaded and
+compiled only once, then for the rest of the server's life they are served
+from the cache, thus the server spends its time only on running already
+loaded and compiled code, which is very fast.
<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
+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
+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
+such extension, 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.
@@ -83,34 +83,34 @@
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
+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)
+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_will_you_learn">What will you learn</A></H1></CENTER>
<P>
-This document was written in an effort to help one to start using Apache's
+This document was written in an effort to help you 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
+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>
+big world of using the Perl API or C API. You will find pointers covering
+these topics in the <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.
+databases, Perl reference, code snippets and more. The <A HREF="././start.html#">Guide's Overview</A> will help you to find your way through the guide.
<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.
+Perl and Apache. (If you do not, just read the INSTALL docs coming with
+distribution of each package.) However, in this guide you will find
+specific Perl and Apache installation and configuration notes, which will
+help you successfully complete the mod_perl installation and get the server
+running 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
@@ -118,15 +118,15 @@
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
+list archive, since there is a good chance someone else has already
+encountered the problem and found a solution. 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>
-If you find incorrect details, my grammar mistakes or you want to
+If you find incorrect details or 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> .
@@ -179,11 +179,10 @@
<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.
+to take the credit for myself, it's just that I tried to keep track of
+names, and became lost, so I preferred not to put credit throughout the
+guide, but rather to centralize it here. If you want your name to show up
+under your original quote, please tell me and I'll add it for you.
<P>
Major contributors:
@@ -191,7 +190,7 @@
<UL>
<P><LI>
<P>
-<STRONG>Doug MacEachern</STRONG>. A big part of this guide is build upon his email replies to users'
+<STRONG>Doug MacEachern</STRONG>. A big part of this guide is built upon his email replies to users'
questions.
<P><LI>
@@ -209,13 +208,13 @@
<P><LI>
<P>
-<STRONG>Eric Cholet</STRONG>, who wrote complete sections for the guide, and pointed out the errors the
-guide carried away.
+<STRONG>Eric Cholet</STRONG>, who wrote complete sections for the guide, and pointed out the errors in
+the guide.
<P><LI>
<P>
-<STRONG>Ken Williams</STRONG>, who reviewed a lot of stuff in the guide, and many snippets from his
-emails are included in the guide.
+<STRONG>Ken Williams</STRONG>, who reviewed a lot of stuff in the guide. Many snippets from his emails
+are included in the guide.
</UL>
<P>
@@ -264,7 +263,7 @@
<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,
+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 bugs and advocate the mod_perl around the world.
@@ -291,7 +290,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
1.3 +711 -771 modperl-site/guide/mod_perl_guide.ps.gz
<<Binary file>>
1.7 +32 -4 modperl-site/guide/modules.html
Index: modules.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/modules.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- modules.html 1999/07/02 13:42:29 1.6
+++ modules.html 1999/08/17 19:03:43 1.7
@@ -32,6 +32,8 @@
<LI><A HREF="#Apache_PerlRun_Run_unaltered_">Apache::PerlRun - Run unaltered CGI scripts under mod_perl</A>
<LI><A HREF="#Apache_GzipChain_compress_HTM">Apache::GzipChain - compress HTML (or anything) in the OutputChain</A>
<LI><A HREF="#Apache_PerlVINC_set_a_differe">Apache::PerlVINC - set a different @INC perl-location </A>
+ <LI><A HREF="#Apache_RegistryBB_Apache_Re">Apache::RegistryBB - Apache::Registry Bare-Bones</A>
+ <LI><A HREF="#Apache_LogSTDERR">Apache::LogSTDERR</A>
</UL>
<!-- INDEX END -->
@@ -171,9 +173,7 @@
to in a process running under mod_cgi.
<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)
+(<A HREF="././download.html#Apache_Request">Apache::Request</A>)
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -274,6 +274,34 @@
HREF="http://perl.apache.org/~dougm/Apache-PerlVINC-0.01.tar.gz">http://perl.apache.org/~dougm/Apache-PerlVINC-0.01.tar.gz</A>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Apache_RegistryBB_Apache_Re">Apache::RegistryBB -- Apache::Registry Bare-Bones</A></H1></CENTER>
+<P>
+It works just like <CODE>Apache::Registry</CODE>, but does not test the x bit, only compiles the file once, and does not <CODE>chdir()</CODE> into the script parent directory.
+
+<P>
+Configuration:
+
+<P>
+<PRE> PerlModule Apache::RegistryBB
+ <Location /perl>
+ SetHandler perl-script
+ PerlHandler ApacheRegistryBB->handler
+ </Location>
+</PRE>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Apache_LogSTDERR">Apache::LogSTDERR</A></H1></CENTER>
+<P>
+When Apache's builtin syslog support is used, the stderr stream is
+redirected to <CODE>/dev/null</CODE>. This means Perl warnings, any messages from <CODE>die()</CODE>, <CODE>croak()</CODE>, etc., will also end up in the black hole. The <EM>HookStderr</EM> directive will hook the stderr stream to a file of your choice, the default
+is shown in this example:
+
+<P>
+<PRE> PerlModule Apache::LogSTDERR
+ HookStderr logs/stderr_log
+</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>
@@ -297,7 +325,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
1.7 +1 -1 modperl-site/guide/multiuser.html
Index: multiuser.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/multiuser.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- multiuser.html 1999/07/02 13:42:29 1.6
+++ multiuser.html 1999/08/17 19:03:43 1.7
@@ -234,7 +234,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/09/1999
</FONT>
</B>
</TD>
1.16 +6 -6 modperl-site/guide/obvious.html
Index: obvious.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/obvious.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- obvious.html 1999/07/02 13:42:29 1.15
+++ obvious.html 1999/08/17 19:03:44 1.16
@@ -302,7 +302,7 @@
<PRE> "\377" =~ /$pat|^[\377]$/; # guaranteed if meta-characters present
</PRE>
<P>
-Phil. Chu contributed this:
+Another approach:
<P>
It depends on the complexity of the regexp you apply this technique to. One
@@ -312,7 +312,7 @@
<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:
+Regex''.
<P>
<PRE> #####################################################
@@ -496,7 +496,7 @@
<P>
Here is the working example. Run the server with <CODE>-X</CODE>, Press <STRONG>STOP</STRONG>
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.
+hang in <CODE>while(1)</CODE>! The resource is not available anymore to this child.
<P>
<PRE> use vars qw(%CACHE);
@@ -551,8 +551,8 @@
<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.
+If you are into Apache API
+<CODE>Apache-&gt;request-&gt;connection-&gt;aborted()</CODE> construct can be used to test for the aborted connection.
<P>
I hope you noticed, that this example is very misleading, since there is a
@@ -705,7 +705,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/27/1999
+ <BR>Last Modified at 08/07/1999
</FONT>
</B>
</TD>
1.18 +164 -56 modperl-site/guide/performance.html
Index: performance.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/performance.html,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- performance.html 1999/07/02 13:42:30 1.17
+++ performance.html 1999/08/17 19:03:44 1.18
@@ -36,7 +36,9 @@
<LI><A HREF="#Preload_Registry_Scripts">Preload Registry Scripts</A>
<LI><A HREF="#Avoid_Importing_Functions">Avoid Importing Functions</A>
- <LI><A HREF="#How_can_I_find_if_my_mod_perl_sc">How can I find if my mod_perl scripts have memory leaks (and where)</A>
+ <LI><A HREF="#Shared_Memory">Shared Memory</A>
+ <LI><A HREF="#Checking_script_modification_tim">Checking script modification times</A>
+ <LI><A HREF="#How_can_I_find_if_my_mod_perl_sc">How can I find if my mod_perl scripts have memory leaks</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>
@@ -106,15 +108,18 @@
there is nothing you can do if user has a slow connection on its behalf.
<P>
-From the other side, you might tune your scripts and webserver to process
-incoming requests ultra fast, so you will need a little number of working
-servers, but you might find out that server processes are busy waiting for
-slow clients to complete the download. You will see more examples in this
-chapter. My point is that a web service is like car, if one of the details
-or mechanisms is broken the car will not drive smoothly and it can even
-stop dead if pushed further without first fixing it.
+Moreover, you might tune your scripts and webserver to process incoming
+requests ultra fast, so you will need a little number of working servers,
+but you might find out that server processes are busy waiting for slow
+clients to complete the download. You will see more examples in this
+chapter.
<P>
+My point is that a web service is like car, if one of the details or
+mechanisms is broken the car will not drive smoothly and it can even stop
+dead if pushed further without first fixing it.
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Sharing_Memory">Sharing Memory</A></H1></CENTER>
<P>
@@ -141,10 +146,10 @@
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, because it inherits most of the preloaded code and the perl
-interpreter from the parent process. But then during the work of the child,
-its memory pages (which aren't really its yet, it uses the parent's pages)
-are getting dirty (originally inherited and shared variables are getting
-updated/modified) and the <STRONG>copy-on-write</STRONG>
+interpreter from the parent process. But than, during the work of the
+child, its memory pages (which aren't really its yet, it uses the parent's
+pages) are getting dirty (originally inherited and shared variables are
+getting updated/modified) and the <STRONG>copy-on-write</STRONG>
happens, which reduces the number of shared memory pages - thus enlarging
the memory demands. Killing the child and respawning a new one, allows to
get the pristine shared memory from the parent process again.
@@ -529,8 +534,44 @@
<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_mod_perl_sc">How can I find if my mod_perl scripts have memory leaks (and where)</A></H1></CENTER>
+<CENTER><H1><A NAME="Shared_Memory">Shared Memory</A></H1></CENTER>
+<P>
+You've probably noticed that the word shared is being repeated many times
+in many things related to mod_perl. Indeed, shared memory might save you a
+lot of money, since with sharing in place you can run many more servers
+than without it. See <A HREF="././performance.html#Choosing_MaxClients">the Formula and the numbers</A>.
+
<P>
+How much shared memory do you have? You can see it by either using the
+memory utils that comes with your system or you can deploy <CODE>GTop</CODE>
+module:
+
+<P>
+<PRE> print "Shared memory of the current process: ",
+ GTop->new->proc_mem($$)->share,"\n";
+</PRE>
+<P>
+<PRE> print "Total shared memory: ",
+ GTop->new->mem->share,"\n";
+</PRE>
+<P>
+When you watch the output of the <CODE>top</CODE> utility, don't confuse <STRONG>RSS</STRONG>
+(or <STRONG>RES</STRONG>) column with <STRONG>SHARE</STRONG> column -- <STRONG>RES</STRONG> is a RESident memory, which is a size of pages currently swapped in.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Checking_script_modification_tim">Checking script modification times</A></H1></CENTER>
+<P>
+Under <CODE>Apache::Registry</CODE> the requested CGI script is always being
+<CODE>stat()</CODE>'ed to check whether it was modified. It adds a very little overhead, but
+if you are into squeezing all the jouces from the server, you might want to
+save this call. If you do -- take a look at
+<A HREF="././modules.html#">Apache::RegistryBB</A> module.
+
+<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_mod_perl_sc">How can I find if my mod_perl scripts have memory leaks</A></H1></CENTER>
+<P>
<CODE>Apache::Leak</CODE> (derived from <CODE>Devel::Leak</CODE>) should help you with this task. Example:
<P>
@@ -545,9 +586,9 @@
</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
+might be leaking. Beware, it will run the code twice, because the first
time in, new <CODE>SV</CODE>s 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
+better evidence. You do not need to be inside mod_perl to use it, from the
command line, the above script outputs:
<P>
@@ -560,13 +601,39 @@
!!! 2 SVs leaked !!!
</PRE>
<P>
-Build a debuggable perl to see dumps of the <CODE>SV</CODE>s. the simple way to have both a normal perl and debuggable perl, is to
+Build a debuggable perl to see dumps of the <CODE>SV</CODE>s. The simple way to have both a normal perl and debuggable perl, is to
follow hints in the
<CODE>SUPPORT</CODE> doc for building <CODE>libperld.a</CODE>, when that is built copy the
<CODE>perl</CODE> from that directory to your perl bin directory, but name it
<CODE>dperl</CODE>.
<P>
+Leak explanation: <CODE>$$global = 1;</CODE> : new global variable created
+<CODE>FooAAA</CODE> with value of <CODE>1</CODE>, will not be destructed until this module is destroyed.
+
+<P>
+<CODE>Apache::Leak</CODE> is not very user-friendly, have a look at
+<CODE>B::LexInfo</CODE>. You'll see that what might appear to be a leak, is actually just a Perl
+optimization. e.g. consider this code:
+
+<P>
+<PRE> sub foo {
+ my $string = shift;
+ }
+</PRE>
+<P>
+<PRE> foo("a string");
+</PRE>
+<P>
+<CODE>B::LexInfo</CODE> will show you that Perl does not release the value from $string, unless you
+undef it. this is because Perl anticipates the memory will be needed for
+another string, the next time the subroutine is entered. you'll see similar
+for <CODE>@array</CODE> length, <CODE>%hash</CODE> keys, and scratch areas of the padlist for ops such as <CODE>join()</CODE>, `<CODE>.</CODE>', etc.
+
+<P>
+<CODE>Apache::Status</CODE> now includes a new StatusLexInfo option.
+
+<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>
<P>
@@ -1068,14 +1135,13 @@
1000 50 4.09
</PRE>
<P>
-Conclusions: Here I wanted to show that when the application is slow -- not
-due to perl loading, code compilation and execution, but bounded to some
-external operation like mysqld querying which made the bottleneck -- it
-almost does not matter what load we place on the server. The RPS (Requests
-per second) is almost the same (given that all the requests have been
-served, you have an ability to queue the clients, but be aware that
-something that goes to queue means a waiting client and a client (browser)
-that might time out!)
+<STRONG>Conclusions:</STRONG> Here I wanted to show that when the application is slow -- not due to perl
+loading, code compilation and execution, but bounded to some external
+operation like mysqld querying which made the bottleneck -- it almost does
+not matter what load we place on the server. The RPS (Requests per second)
+is almost the same (given that all the requests have been served, you have
+an ability to queue the clients, but be aware that something that goes to
+queue means a waiting client and a client (browser) that might time out!)
<P>
Now we will benchmark the same script without using the mysql (perl only
@@ -1101,9 +1167,9 @@
100000 400 24.95
</PRE>
<P>
-Conclusions: This time the script we executed was pure perl (not bounded to
-I/O or mysql), so we see that the server serves the requests much faster.
-You can see the <CODE>RequestPerSecond</CODE> (RPS) is almost the same for any load, but goes lower when the number of
+<STRONG>Conclusions:</STRONG> This time the script we executed was pure perl (not bounded to I/O or
+mysql), so we see that the server serves the requests much faster. You can
+see the <CODE>RequestPerSecond</CODE> (RPS) is almost the same for any load, but goes lower when the number of
concurrent clients goes beyond the <CODE>MaxClients</CODE>. With 25 RPS, the client supplying a 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,
@@ -1155,12 +1221,12 @@
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 throttling. It seems that 10 servers were serving requests 5
-times faster than 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
+<STRONG>Conclusions:</STRONG> A 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 throttling. It seems that 10 servers were serving requests 5 times
+faster than 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
<CODE>MaxClients</CODE>, doesn't mean that the performance will be better. You have just seen the
numbers!
@@ -1183,7 +1249,7 @@
1000 100 10 6.51
</PRE>
<P>
-Conclusions: When we drastically reduce the <CODE>MaxRequestsPerChild</CODE>, the performance starts to become closer to the plain mod_cgi. Just for
+<STRONG>Conclusions:</STRONG> When we drastically reduce the <CODE>MaxRequestsPerChild</CODE>, the performance starts to become closer to the plain mod_cgi. Just for
comparison with mod_cgi, here are the numbers of this run with mod_cgi:
<P>
@@ -1199,10 +1265,10 @@
1000 100 1.13
</PRE>
<P>
-Conclusion: mod_cgi is much slower :) in test NReq/NClients 100/10 the RPS
-in mod_cgi was of 1.12 and in mod_perl of 32, which is 30 times faster!!!
-In the first test each child waited about 100 secs to be served. In the
-second and third 1000 secs!
+<STRONG>Conclusion</STRONG>: mod_cgi is much slower :) in test NReq/NClients 100/10 the RPS in mod_cgi
+was of 1.12 and in mod_perl of 32, which is 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>
@@ -1217,10 +1283,9 @@
<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 within the time out period. 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 :).
+fail if not served within the time out period. You also get <STRONG>Latency</STRONG> (secs/Request) and
+<STRONG>Throughput</STRONG> (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
@@ -1367,7 +1432,7 @@
"Throughput" => sprintf("%.2f Requests/sec\n",
$nof_requests_total / $total_time),
"Latency" => sprintf("%.2f secs/Request",
- $ua->get_latency_total() /
+ ($ua->get_latency_total() || 0) /
$nof_requests_total),
);
@@ -1390,7 +1455,7 @@
<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
+supported; no more than this number of child server processes will be
created. To configure more than 256 clients, you must edit the <CODE>HARD_SERVER_LIMIT</CODE> entry in <CODE>httpd.h</CODE>
and recompile. In our case we want this variable to be as small as
possible, this way we can virtually bound the resources used by the server
@@ -1398,7 +1463,9 @@
<A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>) -- the calculation of <CODE>MaxClients</CODE> is pretty straightforward :
<P>
-<PRE> MaxClients = Total RAM Dedicated to the Webserver / MAX child's process size
+<PRE> Total RAM Dedicated to the Webserver
+ MaxClients = ------------------------------------
+ MAX child's process size
</PRE>
<P>
So if I have 400Mb left for the webserver to run with, I can set the
@@ -1428,7 +1495,7 @@
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 approach is to try not to have this condition
-reached at all, and if reached you should start to worry about it.
+reached at all, and if reach it often you should start to worry about it.
<P>
It's important to understand how much real memory a child occupies. Your
@@ -1440,15 +1507,57 @@
derive a much better formula:
<P>
-<PRE> MaxClients=(Total_RAM+Shared_RAM_per_Child*MaxClients)/Max_Process_Size-1
+<PRE> Total_RAM + Shared_RAM_per_Child * MaxClients
+ MaxClients = ---------------------------------------------
+ Max_Process_Size - 1
</PRE>
<P>
which is:
+<P>
+<PRE> Total_RAM - Max_Process_Size
+ MaxClients = ---------------------------------------
+ Max_Process_Size - Shared_RAM_per_Child
+</PRE>
+<P>
+Let's roll some calculations:
+
+<P>
+<PRE> Total_RAM = 500Mb
+ Max_Process_Size = 10Mb
+ Shared_RAM_per_Child = 4Mb
+</PRE>
+<P>
+<PRE> 500 - 10
+ MaxClients = --------- = 81
+ 10 - 4
+</PRE>
+<P>
+With no sharing in place
+
+<P>
+<PRE> 500
+ MaxClients = --------- = 50
+ 10
+</PRE>
+<P>
+With sharing in place you can have 60% more servers without purchasing more
+RAM, if you improve and keep the sharing level, let's say:
+
+<P>
+<PRE> Total_RAM = 500Mb
+ Max_Process_Size = 10Mb
+ Shared_RAM_per_Child = 8Mb
+</PRE>
<P>
-<PRE> MaxClients=(Total_RAM-Max_Process_Size)/(Max_Process_Size-Shared_RAM_per_Child)
+<PRE> 500 - 10
+ MaxClients = --------- = 245
+ 10 - 8
</PRE>
<P>
+390% more servers!!! You've got the point :)
+
+<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>
@@ -1469,8 +1578,8 @@
starvation. Note, that sometimes standard system libraries leak memory too,
especially on OSes with bad memory management (e.g. Solaris 2.5 on x86
arch). If this is your case you can set <CODE>MaxRequestsPerChild</CODE> to a small number, which will allow the system to reclaim the memory,
-greedy child process consumed, when it exits after <CODE>MaxRequestsPerChild</CODE> requests. But beware -- if you set this number too low, you will loose the
-speed bonus you receive with mod_perl. Consider using <CODE>Apache::PerlRun</CODE> if this is the case. Also setting <CODE>MaxSpareServers</CODE> to a number close to
+greedy child process consumed, when it exits after <CODE>MaxRequestsPerChild</CODE> requests. But beware -- if you set this number too low, you will loose a
+fracture of the speed bonus you receive with mod_perl. Consider using <CODE>Apache::PerlRun</CODE> if this is the case. Also setting <CODE>MaxSpareServers</CODE> to a number close to
<CODE>MaxClients</CODE>, will improve the response time (but your parent process will be busy
respawning new children all the time!)
@@ -1501,7 +1610,7 @@
<CODE>MaxClients</CODE> has been chosen to take the full advantage of the resources), but it'll
make sure that at any given moment your system will be capable of
responding to requests with the maximum speed (given that number of
-concurrent requests is not higher then
+concurrent requests is not higher than
<CODE>MaxClients</CODE>.)
<P>
@@ -1765,14 +1874,13 @@
produce the results of the DB query, which might take some time to
complete, I want users to get some titles ahead. This improves the
usability of my site. Recall yourself: What do you like better: getting the
-output a bit slower, but steadily from the moment you've pressed the Submit
-button or having to watch the ``falling stars'' for awhile and then to
+output a bit slower, but steadily from the moment you've pressed the <STRONG>Submit</STRONG> button or having to watch the ``falling stars'' for awhile and then to
receive the whole output at once, even a few millisecs faster (if the
client (browser) did not time out till then).
<P>
-Conclusion: Do not blindly follow suggestions, but think what is best for
-you in every given case.
+<STRONG>Conclusion</STRONG>: Do not blindly follow 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>
@@ -1899,7 +2007,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 08/16/1999
</FONT>
</B>
</TD>
1.7 +32 -1 modperl-site/guide/perl.html
Index: perl.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/perl.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- perl.html 1999/06/19 21:15:12 1.6
+++ perl.html 1999/08/17 19:03:44 1.7
@@ -27,6 +27,7 @@
<UL>
<LI><A HREF="#Coverage">Coverage</A>
+ <LI><A HREF="#perldoc_s_little_known_but_very_">perldoc's little known but very useful options</A>
<LI><A HREF="#Using_global_variables_and_shari">Using global variables and sharing them between modules/packages</A>
<UL>
@@ -61,6 +62,36 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="perldoc_s_little_known_but_very_">perldoc's little known but very useful options</A></H1></CENTER>
+<P>
+To find what functions perl has, you would execute:
+
+<P>
+<PRE> perldoc perlfunc
+</PRE>
+<P>
+To learn the syntax and to find an example of specific known function, you
+would execute (e.g. for <CODE>open()</CODE>):
+
+<P>
+<PRE> perldoc -f open
+</PRE>
+<P>
+There is a bug in this option, for it wouldn't call pod2man and display the
+section in POD. But it's still readable and very useful.
+
+<P>
+To search the Perl FAQ (<CODE>perlfaq</CODE>) sections you would do (e.g for an
+<STRONG>open</STRONG> keyword):
+
+<P>
+<PRE> perldoc -q open
+</PRE>
+<P>
+will return you all the matching Q&A sections, still in POD.
+
+<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>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -322,7 +353,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/05/1999
+ <BR>Last Modified at 08/16/1999
</FONT>
</B>
</TD>
1.19 +265 -130 modperl-site/guide/porting.html
Index: porting.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/porting.html,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- porting.html 1999/07/02 13:42:30 1.18
+++ porting.html 1999/08/17 19:03:44 1.19
@@ -35,6 +35,7 @@
<LI><A HREF="#Script_s_name_space">Script's name space</A>
<LI><A HREF="#Name_collisions_with_Modules_and">Name collisions with Modules and libs</A>
+ <LI><A HREF="#More_package_name_related_issues">More package name related issues</A>
<LI><A HREF="#_END_or_DATA_tokens">__END__ or __DATA__ tokens</A>
<LI><A HREF="#Output_from_system_calls">Output from system calls</A>
<LI><A HREF="#Using_format_">Using format()</A>
@@ -52,6 +53,7 @@
<LI><A HREF="#Passing_ENV_variables_to_CGI">Passing ENV variables to CGI</A>
<LI><A HREF="#Global_Variables">Global Variables</A>
<LI><A HREF="#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="#Apache_and_syslog">Apache and syslog</A>
<LI><A HREF="#Memory_leakage">Memory leakage</A>
</UL>
@@ -61,6 +63,7 @@
<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="#Reloading_handlers">Reloading handlers</A>
</UL>
<LI><A HREF="#Filehandlers_and_locks_leakages">Filehandlers and locks leakages</A>
@@ -280,7 +283,7 @@
use strict;
- print "Content-type: text/html\\r\\n\\r\\n";
+ print "Content-type: text/html\r\n\r\n";
my $counter = 0;
@@ -290,7 +293,7 @@
sub increment_counter{
$counter++;
- print "Counter is equal to $counter !<BR>\\n";
+ print "Counter is equal to $counter !<BR>\n";
}
}
@@ -439,18 +442,17 @@
what other users read.
<P>
-You type in your name and passwd, and you expect to enter to your account,
-but instead you enter the account of someone else. This is cool isn't it?
-Is it a bug or feature. (For some of us it's a feature, while for others
-it's a bug.) You say, why in the world does this happen? The answer is
-simple: Global Variables. You have entered the account of someone who
-happened to be served by the same server child as you. Because of sloppy
-programming, a global variable was not reset at the beginning of the
-program and voila, you can easily peek into other people's emails! You
-would think that it can't happen, since you have entered the login and
-passwd. I tell you, it happens! See for yourself:
+You type in a username you want to peek at and a dummy password and try to
+enter the account. On some services it does works!!!
<P>
+You say, why in the world does this happen? The answer is simple:
+<STRONG>Global Variables</STRONG>. You have entered the account of someone who happened to be served by the
+same server child as you. Because of sloppy programming, a global variable
+was not reset at the beginning of the program and voila, you can easily
+peek into other people's emails! Here is an example of sloppy written code:
+
+<P>
<PRE> use vars ($authenticated);
my $q = new CGI;
my $username = $q->param('username');
@@ -498,7 +500,7 @@
child that already cached the regexp and wouldn't recompile because of <STRONG>/o</STRONG>.) The example of such a case would be:
<P>
-<PRE> my $pat = '^foo$'; # likely to be input from an HTML form field
+<PRE> my $pat = $q->param("keyword");
foreach( @list ) {
print if /$pat/o;
}
@@ -528,51 +530,100 @@
<P>
To make things clear before we go into details: each child process has its
own <CODE>%INC</CODE> hash which is used to store information about its compiled modules. The
-keys of the hash are the names of the modules or parameters passed to <CODE>require()</CODE>. The values are the real paths to these modules. So if you do:
+keys of the hash are the names of the modules or parameters passed to <CODE>require()</CODE> (<CODE>use()</CODE>). The values are the full or relative paths to these modules/files. Let's
+say we have
+<CODE>my-lib.pl</CODE> and <CODE>MyModule.pm</CODE> both located at <CODE>/home/httpd/perl/my/</CODE>.
+
+<P>
+* <CODE>/home/httpd/perl/my/</CODE> is in the <CODE>@INC</CODE> path at the server startup.
+
+<P>
+<PRE> require "my-lib.pl";
+ use MyModule.pm;
+ print $INC{"my-lib.pl"},"\n";
+ print $INC{"MyModule.pm"},"\n";
+</PRE>
+<P>
+prints:
+
+<P>
+<PRE> /home/httpd/perl/my/my-lib.pl
+ /home/httpd/perl/my/MyModule.pm
+</PRE>
+<P>
+Adding <CODE>use lib</CODE>:
<P>
<PRE> use lib qw(.);
- require "./my/lib.pl";
+ require "my-lib.pl";
+ use MyModule.pm;
+ print $INC{"my-lib.pl"},"\n";
+ print $INC{"MyModule.pm"},"\n";
+</PRE>
+<P>
+prints:
+
+<P>
+<PRE> my-lib.pl
+ MyModule.pm
</PRE>
<P>
-where <CODE>./my/lib.pl</CODE> is actually a <CODE>/home/httpd/perl/my/lib.pl</CODE>. The following entry will show up in the <CODE>%INC</CODE>:
+* <CODE>/home/httpd/perl/my/</CODE> isn't in the <CODE>@INC</CODE> path at the server startup.
<P>
-<PRE> print $INC{"./my/lib.pl"};
-
- printed result:
- ---------------
- /home/httpd/perl/my/lib.pl
+<PRE> require "my-lib.pl";
+ use MyModule.pm;
+ print $INC{"my-lib.pl"},"\n";
+ print $INC{"MyModule.pm"},"\n";
</PRE>
<P>
+Wouldn't work, since perl cannot find the modules.
+
+<P>
+Adding <CODE>use lib</CODE>:
+
+<P>
+<PRE> use lib qw(.);
+ require "my-lib.pl";
+ use MyModule.pm;
+ print $INC{"my-lib.pl"},"\n";
+ print $INC{"MyModule.pm"},"\n";
+</PRE>
+<P>
+prints:
+
+<P>
+<PRE> my-lib.pl
+ MyModule.pm
+</PRE>
+<P>
I'm talking about single server child below!
<P>
-Let's look at 3 faulty scenarios:
+Let's look at 3 faulty script's name space related scenarios:
<DL>
<P><DT><STRONG><A NAME="item_Scenario">Scenario 1</A></STRONG><DD>
<P>
First, You can't have 2 identical module names running under the same
-server! Only the first one <CODE>use()'d</CODE> or <CODE>require()'d</CODE>
-will be compiled into the package, the request to the other identical
+server! Only the first one <CODE>use()</CODE>'d or <CODE>require()</CODE>'d will be compiled into the package, the request to the other identical
module will be skipped since server will think that it's already compiled.
It's already in the child's <CODE>%INC</CODE>. (See <A HREF="././status.html#Watching_the_server">Watching the server</A> section to find out how you can know what is loaded and where)
<P>
-So if you have two different <CODE>Foo</CODE> modules in two different directories and two scripts <CODE>script1.pl</CODE> and <CODE>script2.pl</CODE>, locate like:
+So if you have two different <CODE>Foo</CODE> modules in two different directories and two scripts <CODE>script1.pl</CODE> and <CODE>script2.pl</CODE>, placed like:
<P>
-<PRE> ./cgi/tool1/Foo.pm
- ./cgi/tool1/tool1.pl
- ./cgi/tool2/Foo.pm
- ./cgi/tool2/tool2.pl
+<PRE> ./perl/tool1/Foo.pm
+ ./perl/tool1/tool1.pl
+ ./perl/tool2/Foo.pm
+ ./perl/tool2/tool2.pl
</PRE>
<P>
Where a sample code could be:
<P>
-<PRE> ./cgi/tool1/tool1.pl
+<PRE> ./perl/tool1/tool1.pl
--------------------
use Foo;
print "Content-type: text/html\n\n";
@@ -581,7 +632,7 @@
--------------------
</PRE>
<P>
-<PRE> ./cgi/tool1/Foo.pm
+<PRE> ./perl/tool1/Foo.pm
--------------------
sub foo{
print "<B>I'm Tool Number One!</B><BR>\n";
@@ -590,7 +641,7 @@
--------------------
</PRE>
<P>
-<PRE> ./cgi/tool2/tool2.pl
+<PRE> ./perl/tool2/tool2.pl
--------------------
use Foo;
print "Content-type: text/html\n\n";
@@ -599,7 +650,7 @@
--------------------
</PRE>
<P>
-<PRE> ./cgi/tool2/Foo.pm
+<PRE> ./perl/tool2/Foo.pm
--------------------
sub foo{
print "<B>I'm Tool Number Two!</B><BR>\n";
@@ -608,17 +659,16 @@
--------------------
</PRE>
<P>
-And both scripts call: <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#Running_server_in_a_single_mode">single server mode</A> to detect that kind of bug immediately.
+And both scripts call: <CODE>use Foo;</CODE> -- only the first one called will know about <CODE>Foo</CODE>, when you will call the second script it will not know about <CODE>Foo</CODE> at all - it's like you've 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 detect this kind of bug immediately.
<P>
You will see the following in the error_log file:
<P>
<PRE> Undefined subroutine
- &Apache::ROOT::perl::tool2_2epl::some_function called at
- /home/httpd/perl/tool2.pl line 4.
+ &Apache::ROOT::perl::tool2::tool2_2epl::foo called at
+ /home/httpd/perl/tool2/tool2.pl line 4.
</PRE>
<P><DT><STRONG>Scenario 2</STRONG><DD>
<P>
@@ -626,10 +676,10 @@
have:
<P>
-<PRE> ./cgi/tool1/config.pl
- ./cgi/tool1/tool1.pl
- ./cgi/tool2/config.pl
- ./cgi/tool2/tool2.pl
+<PRE> ./perl/tool1/config.pl
+ ./perl/tool1/tool1.pl
+ ./perl/tool2/config.pl
+ ./perl/tool2/tool2.pl
</PRE>
<P>
And both scripts do:
@@ -650,9 +700,9 @@
What's interesting that the following scenario wouldn't work too!
<P>
-<PRE> ./cgi/tool/config.pl
- ./cgi/tool/tool1.pl
- ./cgi/tool/tool2.pl
+<PRE> ./perl/tool/config.pl
+ ./perl/tool/tool1.pl
+ ./perl/tool/tool2.pl
</PRE>
<P>
where <CODE>tool1.pl</CODE> and <CODE>tool2.pl</CODE> both <CODE>require()</CODE> the <STRONG>same</STRONG>
@@ -671,13 +721,13 @@
prefixes. The file system layout will be something like:
<P>
-<PRE> ./cgi/tool1/Tool1/Foo.pm
- ./cgi/tool1/tool1.pl
- ./cgi/tool2/Tool2/Foo.pm
- ./cgi/tool2/tool2.pl
+<PRE> ./perl/tool1/Tool1/Foo.pm
+ ./perl/tool1/tool1.pl
+ ./perl/tool2/Tool2/Foo.pm
+ ./perl/tool2/tool2.pl
</PRE>
<P>
-And change the scripts:
+And modify the scripts:
<P>
<PRE> use Tool1::Foo;
@@ -687,10 +737,10 @@
For <CODE>require()</CODE> (scenario number 2) use the following:
<P>
-<PRE> ./cgi/tool1/tool1-lib/config.pl
- ./cgi/tool1/tool1.pl
- ./cgi/tool2/tool2-lib/config.pl
- ./cgi/tool2/tool2.pl
+<PRE> ./perl/tool1/tool1-lib/config.pl
+ ./perl/tool1/tool1.pl
+ ./perl/tool2/tool2-lib/config.pl
+ ./perl/tool2/tool2.pl
</PRE>
<P>
And each script does respectively:
@@ -702,12 +752,13 @@
<P>
<PRE> use lib qw(.);
require "tool2-lib/config.pl";
-
-But this solution is very bad, since while it might work for you now,
-if you add another script that wants to use the same module or
-C<config.pl> file, it still wouldn't work as we saw in the third
-scenario. So let see better solutions.
</PRE>
+<P>
+But this solution isn't good, since while it might work for you now, if you
+add another script that wants to use the same module or
+<CODE>config.pl</CODE> file, it still wouldn't work as we saw in the third scenario. So let's see
+better solutions.
+
<P><DT><STRONG>Solution 2</STRONG><DD>
<P>
Another option is to use a full path to the script, so it'll be compiled
@@ -729,13 +780,16 @@
Declare a package in the required files! (Of course it should be unique to
the rest of the package names you use!) The <CODE>%INC</CODE> will use the package name for the key! It's a good idea to build at least 2
level package names for your private modules. (e.g. <CODE>MyProject::Carp</CODE>
-and not <CODE>Carp</CODE> for it will collide with existent standard package - even if as of the time
-of your coding it doesn't exist yet - it might enter the next perl
+and not <CODE>Carp</CODE>, since it will collide with existent standard package.) Even if as of the
+time of your coding it doesn't exist yet - it might enter the next perl
distribution as a standard module and your code will become broken. Foresee
-problems like this and save you a future trouble.)
+problems like this and save you a future trouble.
<P>
-When you <CODE>use()d</CODE> or <CODE>require()d</CODE> files without package declarations, it was very convenient since all the
+What are the implications of package declaration?
+
+<P>
+When you <CODE>use()'d</CODE> or <CODE>require()'d</CODE> files without package declarations, it was very convenient since all the
variables and subroutines were part of the <CODE>main::</CODE> package, so any of them could be used as if they were part of the main
script. With package declarations things get more complicated. To be
correct -- not complicated, but awkward, since you will have to use
@@ -745,16 +799,15 @@
defined variables inside <CODE>Package</CODE> (declared with <CODE>my()</CODE>).
<P>
-You can make things simpler by exporting the symbols from the
-<CODE>use()'d</CODE> package, like:
+ou still can leave your scripts unchanged if you import the names of the
+global variables and subs into a <STRONG>main::</STRONG> package's namespace, like:
<P>
-<PRE> use Package qw(:mysubs sub_b $var1 :myvars);
+<PRE> use Module qw(:mysubs sub_b $var1 :myvars);
</PRE>
<P>
-You can export both -- subroutines and global variables. This is a bad
-approach since it'll consume more memory for the current process. (See
-<CODE>perldoc Exporter</CODE> for information about exporting variables)
+You can export both -- subroutines and global variables. This isn't a good
+approach since it'll consume more memory for the current process. (See <CODE>perldoc Exporter</CODE> for information about exporting variables and other symbols)
<P>
This solution completely covers the third scenario. By using different
@@ -763,14 +816,32 @@
</DL>
<P>
-Read also perlmodlib and perlmod manpages.
+See also <CODE>perlmodlib</CODE> and <CODE>perlmod</CODE> manpages.
<P>
From the above discussion it should be clear that you cannot run a
-development and a production versions of the tools on the same server! You
-have to run a separate server for each (it still can be the same machine,
-but the server will use a different port).
+development and a production versions of the tools using the same apache
+server!
+
+<P>
+You have to run a separate server for each (it still can be the same
+machine, but the server will use a different port).
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="More_package_name_related_issues">More package name related issues</A></H2></CENTER>
+<P>
+If you have the following:
+
+<P>
+<PRE> PerlHandler Apache::Work::Foo
+ PerlHandler Apache::Work::Foo::Bar
+</PRE>
+<P>
+If you make a request that pulls in <CODE>Apache/Work/Foo/Bar.pm</CODE> first, then the <CODE>Apache::Work::Foo</CODE> package gets defined, so mod_perl does not try to pull in <CODE>Apache/Work/Foo.pm</CODE>
+
+
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="_END_or_DATA_tokens">__END__ or __DATA__ tokens</A></H2></CENTER>
@@ -821,7 +892,8 @@
}
</PRE>
<P>
-Now each time the select code is called, the correct <CODE>exit()</CODE> will be chosen, whether you run the script as a CGI or from the shell.
+Now the correct <CODE>exit()</CODE> will be always chosen, whether you run the script as a CGI or from the
+shell.
<P>
<STRONG>Note</STRONG> that if you run the script under <CODE>Apache::Registry</CODE>, <STRONG>The
@@ -852,38 +924,38 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Running_from_shell">Running from shell</A></H2></CENTER>
<P>
-Your scripts <STRONG>will not</STRONG> run from the command line (yet) unless you use CGI::Switch or CGI.pm and
-5.004+ and do not make any direct calls to Apache->methods.
+Your scripts <STRONG>will not</STRONG> run from the command line (yet) unless you use <CODE>CGI::Switch</CODE> or <CODE>CGI.pm</CODE> and perl 5.004+ and do not make any direct calls to <CODE>Apache-&gt;methods</CODE>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="I_O_is_different">I/O is different</A></H2></CENTER>
<P>
If you are using Perl 5.004 or better, most CGI scripts can run under
-mod_perl untouched. If you're using 5.003, Perl's built-in
-<CODE>read()</CODE> and <CODE>print()</CODE> functions do not work as they
-do under CGI. If you're using CGI.pm, use $query->print instead of plain 'ol <CODE>print().</CODE>
+mod_perl untouched. If you're using 5.003, Perl's built-in <CODE>read()</CODE>
+and <CODE>print()</CODE> functions do not work as they do under CGI. If you're using <CODE>CGI.pm</CODE>, use <CODE>$query-&gt;print</CODE> instead of plain 'ol
+<CODE>print()</CODE>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="HTTP_MIME_Headers_PerlSendHea">HTTP + MIME Headers (PerlSendHeader)</A></H2></CENTER>
<P>
By default, mod_perl does not send any headers by itself, however, you may
-wish to change this (in httpd.conf):
+wish to change this (in <CODE>httpd.conf</CODE>):
<P>
<PRE> PerlSendHeader On
</PRE>
<P>
Now the response line and common headers will be sent as they are by
-mod_cgi. And, just as with mod_cgi, <CODE>PerlSendHeader</CODE> will not send a terminating newline, your script must send that itself,
-e.g.:
+mod_cgi. And, just as with mod_cgi, <CODE>PerlSendHeader</CODE> will not send the MIME type and a terminating newline. Your script must
+send that itself, e.g.:
<P>
<PRE> print "Content-type: text/html\r\n\r\n";
</PRE>
<P>
-If you are using CGI.pm or CGI::Switch and <STRONG>print $q->header</STRONG> you do _not_ need <CODE>PerlSendHeader</CODE> On.
+If you are using <CODE>CGI.pm</CODE> or <CODE>CGI::Switch</CODE> and <STRONG>print
+$q->header</STRONG> you do _not_ need <CODE>PerlSendHeader</CODE> On.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -915,7 +987,7 @@
happens to be one that is compiling the code.
<P>
-<CODE>BEGIN</CODE> blocks in modules and files pulled in via <CODE>require()</CODE> and/or
+<CODE>BEGIN</CODE> blocks in modules and files pulled in via <CODE>require()</CODE> or
<CODE>use()</CODE> will be executed:
<UL>
@@ -943,7 +1015,7 @@
</UL>
<P>
-<CODE>BEGIN</CODE> blocks in <CODE>Apache::Registry</CODE> scripts will be executed:
+<CODE>BEGIN</CODE> blocks in <CODE>Apache::Registry</CODE> scripts will be executed, as above plus:
<UL>
<P><LI>
@@ -972,7 +1044,7 @@
<P>
As perlmod explains, an <CODE>END</CODE> subroutine is executed as late as possible, that is, when the interpreter
exits. In the mod_perl environment, the interpreter does not exit until the
-server is shutdown. However, mod_perl does make a special case for
+server shutdown. However, mod_perl does make a special case for
<CODE>Apache::Registry</CODE> scripts.
<P>
@@ -980,18 +1052,20 @@
function, which is called once each time the Perl program is executed, e.g.
once per (mod_cgi) CGI scripts. However, mod_perl only calls
<STRONG>perl_run()</STRONG> once, during server startup. Any <CODE>END</CODE> blocks encountered during main server startup, i.e. those pulled in by the
-<CODE>PerlRequire</CODE> or by any <CODE>PerlModule</CODE>, are suspended and run at server shutdown, aka child_exit (requires apache
-1.3b3+).
+<CODE>PerlRequire</CODE> or by any <CODE>PerlModule</CODE>, are suspended and run at server shutdown, aka <CODE>child_exit()</CODE> (requires apache 1.3b3+).
<P>
Any <CODE>END</CODE> blocks that are encountered during compilation of
<CODE>Apache::Registry</CODE> scripts <STRONG>are called after the script has
completed</STRONG> (not during the cleanup phase though) including subsequent invocations when
-the script is cached in memory. All other <CODE>END</CODE>
-blocks encountered during other <CODE>Perl*Handler</CODE> call-backs, e.g.
-<CODE>PerlChildInitHandler</CODE>, will be suspended while the process is running and called during <CODE>child_exit()</CODE> when the process is shutting down. Module authors might wish to use $r->register_cleanup as an alternative to <CODE>END</CODE> blocks if this behavior is not desirable.
+the script is cached in memory.
<P>
+All other <CODE>END</CODE> blocks encountered during other <CODE>Perl*Handler</CODE>
+call-backs, e.g. <CODE>PerlChildInitHandler</CODE>, will be suspended while the process is running and called during <CODE>child_exit()</CODE> when the process is shutting down. Module authors might wish to use
+<CODE>$r-&gt;register_cleanup</CODE> as an alternative to <CODE>END</CODE> blocks if this behavior is not 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>.
<P>
@@ -1095,8 +1169,8 @@
<P>
<CODE>diagnostics</CODE> pragma can shed more light on the errors and warnings you see, but again,
it's better not to use it in production, since otherwise you incur a huge
-overhead of the diagnostics pragma examining your every bit of code
-mod_perl executes. (You can run your script with <CODE>-dDprof</CODE> to check the overhead. See <CODE>Devel::Dprof</CODE> for more info).
+overhead of the diagnostics pragma examining every bit of the code mod_perl
+executes. (You can run your script with <CODE>-dDprof</CODE> to check the overhead. See <CODE>Devel::Dprof</CODE> for more info).
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -1141,11 +1215,23 @@
will set <CODE>$ENV{PERLDB_OPTS}</CODE>, and it'll be accessible in every child.
<P>
+<CODE>%ENV</CODE> is only setup for CGI emulation. If you are using the API, you should use <CODE>$r-&gt;subprocess_env</CODE>, <CODE>$r-&gt;notes</CODE> or
+<CODE>$r-&gt;pnotes</CODE> for passing data around between handlers. <CODE>%ENV</CODE> is slow because it must update the underlying C environment table, which
+also exposes that data to systems who can view with <CODE>ps</CODE>.
+
+<P>
+In any case, <CODE>%ENV</CODE> and the tables used by those methods are all cleared after the request is
+served. so, no, <CODE>$ENV{SESSION_ID}</CODE> will not be swaped or reused by different http requests.
+
+<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Global_Variables">Global Variables</A></H2></CENTER>
<P>
It's always a good idea to stay away from global variables when possible.
-Some variables must be global so Perl can see them, such as a module's <CODE>@ISA</CODE> or <CODE>$VERSION</CODE> variables. In common practice, a combination of <CODE>strict</CODE> and <CODE>vars</CODE> pragmas keeps modules clean and reduces a bit of noise. However, <CODE>vars</CODE> pragma also creates aliases as the <CODE>Exporter</CODE> does, which eat up more space. When possible, try to use fully qualified
+Some variables must be global so Perl can see them, such as a module's <CODE>@ISA</CODE> or <CODE>$VERSION</CODE> variables (or fully qualified
+<STRONG>@MyModule::ISA</STRONG>). In common practice, a combination of <CODE>strict</CODE> and
+<CODE>vars</CODE> pragmas keeps modules clean and reduces a bit of noise. However, <CODE>vars</CODE> pragma also creates aliases as the <CODE>Exporter</CODE>
+does, which eat up more memory. When possible, try to use fully qualified
names instead of use vars. Example:
<P>
@@ -1177,6 +1263,17 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Apache_and_syslog">Apache and syslog</A></H2></CENTER>
+<P>
+When native syslog support is enabled, the stderr stream will be redirected
+to <CODE>/dev/null</CODE>!
+
+<P>
+It has nothing to do with mod_perl (plain Apache does the same). Doug wrote
+a <A HREF="././modules.html#Apache_LogSTDERR">Apache::LogSTDERR</A> module to work around this
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Memory_leakage">Memory leakage</A></H2></CENTER>
<P>
Scripts under mod_perl can very easily leak memory! Global variables stay
@@ -1188,7 +1285,7 @@
it though!
<P>
-<STRONG>First example</STRONG> demonstrates reading a file:
+<STRONG>First example</STRONG> demonstrates reading in a whole file:
<P>
<PRE> open IN, $file or die $!;
@@ -1208,8 +1305,10 @@
<P>
<STRONG>Second example</STRONG> demonstrates copying variables between functions (passing variables by
value). Let's use the example above, assuming we have no choice but to read
-the whole file before any data processing. Now you have some imagine <CODE>process()</CODE> subroutine that processes the data and returns it back. What happens if you
-pass the <CODE>$content</CODE> by value? You have just copied another 5M and the child has grown by
+the whole file before any data processing takes place. Now you have some
+imagine <CODE>process()</CODE> subroutine that processes the data and returns it back. What happens if you
+pass the
+<CODE>$content</CODE> by value? You have just copied another 5M and the child has grown by
another 5M in size (watch your swap space!) now multiply it again by factor
of 20 you have 200M of wasted RAM, which will be apparently reused but it's
a waste! Whenever you think the variable can grow bigger than few Kb, pass
@@ -1270,12 +1369,12 @@
by reference or return the processed variable (e.g. <CODE>$content=process($content);</CODE>).
<P>
-<STRONG>Third example</STRONG> demonstrates work with DataBases. If you do some DB processing, many times
-you encounter the need to read lots of records into your program, and then
-print them to the browser after they are formatted. (I don't even mention
-the horrible case where programmers read in the whole DB and then use perl
-to process it!!! Use a relational DB and let the SQL do the job, so you get
-only the records you need!!!).
+<STRONG>Third example</STRONG> demonstrates a work with DataBases. If you do some DB processing, many
+times you encounter the need to read lots of records into your program, and
+then print them to the browser after they are formatted. (I don't even
+mention the horrible case where programmers read in the whole DB and then
+use perl to process it!!! Use a relational DB and let the SQL do the job,
+so you get only the records you need!!!).
<P>
We will use <CODE>DBI</CODE> for this (assume that we are already connected to the DB) (refer to <CODE>perldoc DBI</CODE> for a complete manual of the <CODE>DBI</CODE>
@@ -1323,7 +1422,8 @@
Note: the above method doesn't allow you to know how many records have been
matched. The workaround is to run an identical query before the code above
where you use <CODE>SELECT count(*) ...</CODE> instead of <CODE>'SELECT *
-...</CODE> to get the number of matched records.
+...</CODE> to get the number of matched records. It should be much faster, since you
+can remove any <STRONG>SORTBY</STRONG> and alike attributes.
<P>
For those who think that <STRONG>$sth->rows</STRONG> will do the job, here is the quote from the <CODE>DBI</CODE> manpage:
@@ -1498,7 +1598,7 @@
<CODE>Apache::StatINC</CODE> module.
<P>
-<CODE>Apache::StatINC</CODE> - Reload <CODE>%INC</CODE> files when updated on disk. When Perl pulls a file via require, it stores
+<CODE>Apache::StatINC</CODE> reloads <CODE>%INC</CODE> files when updated on disk. When Perl pulls a file via require, it stores
the filename in the global hash <CODE>%INC</CODE>. The next time Perl tries to require the same file, it sees the file in <CODE>%INC</CODE> and does not reload from disk. This module's handler iterates over <CODE>%INC</CODE> and reloads the file if it has changed on disk.
<P>
@@ -1524,20 +1624,38 @@
</Location>
</PRE>
<P>
-Beware that only the modules located in <CODE>@INC</CODE> are being reloaded on change, and you can change the <CODE>@INC</CODE> 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
-<CODE>@INC</CODE>. When you do <STRONG>use lib qw(foo/bar);</STRONG>, the <CODE>@INC</CODE> is being changed only for the time the code is being parsed and compiled.
+Beware that only the modules located in <CODE>@INC</CODE> are being reloaded on change, and you can change the <CODE>@INC</CODE> only before the server has been started (in startup file).
+
+<P>
+Whatever you do in your scripts and modules which are being <CODE>required()</CODE> after the server startup will not have any effect on <CODE>@INC</CODE>. When you do:
+
+<P>
+<PRE> use lib qw(foo/bar);
+</PRE>
+<P>
+the <CODE>@INC</CODE> is being changed only for the time the code is being parsed and compiled.
When it's over the <CODE>@INC</CODE> is being reset to its original value. To make sure that you have set a
correct <CODE>@INC</CODE> fetch <A
HREF="http://www.nowhere.com/perl-status?inc">http://www.nowhere.com/perl-status?inc</A>
-and watch the bottom of the page. (I assume you have configured the <Location /perl-status> section in <CODE>httpd.conf</CODE> as the mod_perl docs show.)
+and look at the bottom of the page. (I assume you have configured the <A HREF="././config.html#_perl_status_location">/perl-status location</A>.)
+
+<P>
+Also, notice the following caveat: While ``<CODE>.</CODE>'' is in the <CODE>@INC</CODE> -- perl knows to <CODE>require()</CODE> files relative to the script directory. Once the script was parsed - the
+server doesn't remember the path any more! So you end up with broken entry
+in <CODE>%INC</CODE> like:
<P>
+<PRE> $INC{bar.pl} eq "bar.pl"
+</PRE>
+<P>
+If you want Apache::StatINC to reload your script - modify the <CODE>@INC</CODE>
+at the server startup file! or use a full path in <CODE>require()</CODE> call.
+
+<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> every time can add a large overhead to server response times, and you
+Checking all the modules in <STRONG>%INC</STRONG> every time can add a large overhead to server response times, and you
certainly would not want
<CODE>Apache::StatINC</CODE> module to be enabled in your production site's configuration. But sometimes
you want to have some Configuration module to be reloaded without
@@ -1599,11 +1717,24 @@
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Reloading_handlers">Reloading handlers</A></H2></CENTER>
+<P>
+If you want to reload perlhandler on each invocation, the following trick
+will do it:
+
+<P>
+<PRE> PerlHandler "sub { do 'MyTest.pm'; MyTest::handler(shift) }"
+</PRE>
+<P>
+<CODE>do()</CODE> will reload <CODE>MyTest.pm</CODE> every request.
+
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="Filehandlers_and_locks_leakages">Filehandlers and locks leakages</A></H1></CENTER>
<P>
-When you wrote a script running under mod_cgi, you could get away with
-sloppy programming, by opening a file and letting the interpreter to close
-it for you when the script had finished his run, like:
+When you write a script running under mod_cgi, you can get away with sloppy
+programming, like opening a file and letting the interpreter to close it
+for you when the script had finished his run:
<P>
<PRE> open IN, "in.txt" or die "Cannot open in.txt for reading : $!\n";
@@ -1751,8 +1882,7 @@
Done with script
</PRE>
<P>
-Then, uncomment the line where <CODE>$self</CODE> makes a circular
-reference, and you'll see:
+Then, uncomment the line where <CODE>$self</CODE> makes a circular reference, and you'll see:
<P>
<PRE> Done with script
@@ -1956,6 +2086,11 @@
chmod 0755, "$filename.marked";
</PRE>
<P>
+Also notice, that another solution is to move most of the code into a
+separare modules, which ensures that the line number will be reported
+correctly.
+
+<P>
To have a complete trace of calls add:
<P>
@@ -1972,14 +2107,14 @@
mod_rewrite, mod_log, mod_proxy, mod_spelling or whatever modules you have
used in your server, all the core routines and so on. A much wiser approach
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
+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 functions 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 external program to run.
@@ -2004,13 +2139,13 @@
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.
+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).
+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.
@@ -2093,7 +2228,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
1.17 +40 -31 modperl-site/guide/scenario.html
Index: scenario.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/scenario.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- scenario.html 1999/07/02 13:42:30 1.16
+++ scenario.html 1999/08/17 19:03:45 1.17
@@ -55,7 +55,7 @@
<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="#Building_and_Using_mod_proxy">Building and Using mod_proxy</A>
<LI><A HREF="#mod_perl_server_as_DSO">mod_perl server as DSO</A>
<LI><A HREF="#HTTP_Authentication_with_2_serve">HTTP Authentication with 2 servers + proxy</A>
</UL>
@@ -154,8 +154,8 @@
<PRE> % make && make test && make install
</PRE>
<P>
-Note that if <CODE>make</CODE> fails, neither <CODE>make test</CODE> nor <CODE>make
-install</CODE> will be executed. If <CODE>make test</CODE> fails, <CODE>make install</CODE>
+Note that if <STRONG>make</STRONG> fails, neither <STRONG>make test</STRONG> nor <STRONG>make
+install</STRONG> will be not executed. If <STRONG>make test</STRONG> fails, <STRONG>make install</STRONG>
will be not executed.
<P>
@@ -171,7 +171,7 @@
you how to start a freshly built webserver (the path of the
<CODE>apachectl</CODE>, more about it later) and where the configuration files are. Remember (or
even better write down) both, since you will need this information very
-soon. On my machine they two important paths are:
+soon. On my machine the two important paths are:
<P>
<PRE> /usr/local/apache/bin/apachectl
@@ -419,7 +419,7 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A></H2></CENTER>
<P>
-Let's proceed with instalation. I will use x.x.x instead of real version
+Let's proceed with installation. I will use x.x.x instead of real version
numbers so this document will never become obsolete :).
<P>
@@ -616,7 +616,7 @@
<P>
The 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
+machine. Here we will use <CODE>8080</CODE>. 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
@@ -629,7 +629,7 @@
<P>
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>.
+and <A HREF="././scenario.html#Building_and_Using_mod_proxy">Using mod_proxy</A>.
<P>
Now we proceed to mod_perl specific directives. A good idea will be to add
@@ -696,7 +696,7 @@
installed, you just need to modify the default <CODE>squid.conf</CODE> the way I will explain below, then you are ready to run it.
<P>
-First, lets understand what do we have in hands and what do we want from
+First, let's understand what do we have in hands and what do we want from
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
@@ -782,8 +782,11 @@
want your scripts to be more complying with the HTTP standards, the headers
of your scripts should carry the <CODE>Caching Directives</CODE>
according to the HTTP specs. You will find a complete tutorial about this
-topic in <CODE>Tutorial on HTTP Headers for mod_perl users</CODE> by Andreas J. Koenig. If you set the headers correctly there is no need to
-tell squid accelerator to <STRONG>NOT</STRONG> try to cache something. The headers I am talking about are <CODE>Last-Modified</CODE> and <CODE>Expires</CODE>. What are they good for? Squid would not bother your mod_perl server a
+topic in <CODE>Tutorial on HTTP Headers for mod_perl users</CODE> by Andreas J. Koenig (at <A
+HREF="http://perl.apache.org">http://perl.apache.org</A> ). If you set the
+headers correctly there is no need to tell squid accelerator to <STRONG>NOT</STRONG>
+try to cache something. The headers I am talking about are
+<CODE>Last-Modified</CODE> and <CODE>Expires</CODE>. What are they good for? Squid would not bother your mod_perl server a
second time if a request is (a) cachable and (b) still in the cache. Many
mod_perl applications will produce identical results on identical requests
at least if not much time goes by between the requests. So your squid might
@@ -939,15 +942,16 @@
<P>
Almost... When you try the new setup, you will be surprised and upset to
-discover the port 81 showing up in the URLs of the static objects (like
+discover a port 81 showing up in the URLs of the static objects (like
htmls). Hey, we did not want the user to see the port 81 and use it instead
-of 80, since than it will bypass the squid server and the hard work we went
-through was just a waste of time? The solution is to run both squid and
-httpd_docs on the same port. This can be accomplished by binding each one
-to a specific interface. Modify the
-<CODE>httpd.conf</CODE> in the <CODE>httpd_docs</CODE> configuration directory:
+of 80, since then it will bypass the squid server and the hard work we went
+through was just a waste of time?
<P>
+The solution is to run both squid and httpd_docs at the same port. This can
+be accomplished by binding each one to a specific interface. Modify the <CODE>httpd.conf</CODE> in the <CODE>httpd_docs</CODE> configuration directory:
+
+<P>
<PRE> Port 80
BindAddress 127.0.0.1
Listen 127.0.0.1:80
@@ -977,16 +981,19 @@
references, using the 8080 or other port -- you should fix them to generate
links to point to port 80 (which means not using the port at all). If you
do not, users will bypass squid, like if it was not there at all, by making
-direct requests to the mod_perl server's port. The only question left is
-what to do with users who bookmarked your services and they still have the
-port 8080 inside the URL. Do not worry about it. The most important thing
-is for your scripts to return a full URLs, so if the user comes from the
-link with 8080 port inside, let it be. Just make sure that all the
-consecutive calls to your server will be rewritten correctly. During a
-period of time users will change their bookmarks. What can be done is to
-send them an email if 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 in first place. See <A HREF="././config.html#Publishing_port_numbers_differen">Publishing port numbers different from 80</A>.
+direct requests to the mod_perl server's port.
+
+<P>
+The only question left is what to do with users who bookmarked your
+services and they still have the port 8080 inside the URL. Do not worry
+about it. The most important thing is for your scripts to return a full
+URLs, so if the user comes from the link with 8080 port inside, let it be.
+Just make sure that all the consecutive calls to your server will be
+rewritten correctly. During a period of time users will change their
+bookmarks. What can be done is to send them an email if 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 in first
+place. See <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.
@@ -998,8 +1005,7 @@
logged. </META>
<P>
-See <A HREF="././scenario.html#Using_mod_proxy">Using mod_proxy</A> for information about
-<CODE>X-Forwarded-For</CODE>.
+See <A HREF="././scenario.html#Building_and_Using_mod_proxy">Using mod_proxy</A> for information about <CODE>X-Forwarded-For</CODE>.
<P>
To save you some keystrokes, here is the whole modified <CODE>squid.conf</CODE>:
@@ -1137,7 +1143,10 @@
</PRE>
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Using_mod_proxy">Using mod_proxy</A></H1></CENTER>
+<CENTER><H1><A NAME="Building_and_Using_mod_proxy">Building and Using mod_proxy</A></H1></CENTER>
+<P>
+To build it into apache just add <STRONG>--enable-module=proxy</STRONG> during the apache <STRONG>configure</STRONG> stage.
+
<P>
Now we will talk about apache's mod_proxy and understand how it works.
@@ -1146,7 +1155,7 @@
mod_perl enabled server in the following way:
<P>
-<PRE> ProxyPass /modperl/ <A HREF="http://localhost:81/modperl/">http://localhost:81/modperl/</A>
+<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>
@@ -1295,7 +1304,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 07/02/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
1.5 +28 -1 modperl-site/guide/security.html
Index: security.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/security.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- security.html 1999/07/02 13:42:31 1.4
+++ security.html 1999/08/17 19:03:45 1.5
@@ -33,6 +33,12 @@
<LI><A HREF="#Non_authenticated_access_for_int">Non authenticated access for internal IPs, but authenticated by external IPs</A>
</UL>
+ <LI><A HREF="#Authentication_code_snippets">Authentication code snippets</A>
+ <UL>
+
+ <LI><A HREF="#Forcing_reauthenticating">Forcing reauthenticating</A>
+ </UL>
+
</UL>
<!-- INDEX END -->
@@ -217,6 +223,27 @@
<CODE>userB</CODE> according on the IP, if non matched <CODE>PerlAuthenHandler</CODE> will be not set to OK, and the next Authentication stage will ask the user
for a login and password.
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H1><A NAME="Authentication_code_snippets">Authentication code snippets</A></H1></CENTER>
+<P>
+<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
+<CENTER><H2><A NAME="Forcing_reauthenticating">Forcing reauthenticating</A></H2></CENTER>
+<P>
+To force authenticated user to reauthenticate just send the following
+header to the browser:
+
+<P>
+<PRE> HTTP/1.0 401 Unauthorized
+</PRE>
+<P>
+This will pop-up (on Netscape at least) a window saying that the
+<STRONG>Authorization Failed. Retry?</STRONG> And an <STRONG>OK</STRONG> and a <STRONG>Cancel</STRONG> buttons. When that window pops up you know that the password has been
+cleared. If the user hits the <STRONG>Cancel</STRONG> button the username will also be cleared, and you can have a page that will
+be output written after the header if this is a CGI (or PHP, or anything
+else like that). If the user hits the <STRONG>OK</STRONG> button, the authentication window will be brought up again with their
+previous username already in the username field.
+
<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>
@@ -240,7 +267,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
1.15 +66 -38 modperl-site/guide/snippets.html
Index: snippets.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/snippets.html,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- snippets.html 1999/06/19 21:15:13 1.14
+++ snippets.html 1999/08/17 19:03:45 1.15
@@ -27,9 +27,9 @@
<UL>
<LI><A HREF="#Sending_MIME_headers">Sending MIME headers</A>
- <LI><A HREF="#How_to_avoid_printing_the_header">How to avoid printing the header more than once.</A>
+ <LI><A HREF="#How_to_avoid_printing_the_header">How to avoid printing the header more than once</A>
<LI><A HREF="#More_on_relative_paths">More on relative paths</A>
- <LI><A HREF="#Watching_the_error_log_file_with">Watching the error_log file without telneting to the server.</A>
+ <LI><A HREF="#Watching_the_error_log_file_with">Watching the error_log file without telneting to the server</A>
<LI><A HREF="#Accessing_variables_from_the_cal">Accessing variables from the caller's package</A>
<LI><A HREF="#Handling_cookies">Handling cookies</A>
</UL>
@@ -52,31 +52,32 @@
<CENTER><H1><A NAME="Sending_MIME_headers">Sending MIME headers</A></H1></CENTER>
<P>
By default, mod_perl does not send any headers by itself, however, you may
-wish to change this behavior by setting in config file:
+wish to change this behavior by setting in the config file:
<P>
<PRE> PerlSendHeader On
</PRE>
<P>
-The safest bet is to use CGI.pm's <CODE>print header();</CODE> method (If you use this, you don't need the above setting)
+The safest bet is to use CGI.pm's <CODE>header()</CODE> method. (If you do <CODE>print header();</CODE>, you don't need the above setting.)
<P>
-Also there is $ENV{PERL_SEND_HEADER} to see if PerlSendHeader is On or Off.
+Also there is <CODE>$ENV{PERL_SEND_HEADER}</CODE> to see if <CODE>PerlSendHeader</CODE> is <CODE>On</CODE> or
+<CODE>Off</CODE>.
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="How_to_avoid_printing_the_header">How to avoid printing the header more than once.</A></H1></CENTER>
+<CENTER><H1><A NAME="How_to_avoid_printing_the_header">How to avoid printing the header more than once</A></H1></CENTER>
<P>
-I'm sure you have been in the situations, where you wish you knew whether
-the MIME header has been already printed. Since if it was printing it again
-will cause an ugly ``Content-type: ...'' string show up at the web page. So
-how do we solve it? With help of closure.
+I'm sure you have been in situations where you wish you knew whether the
+MIME header has already been printed. Since if it is printed again it will
+cause an ugly ``Content-type: ...'' string to show up in the browser. So
+how do we solve it? With the help of a closure.
<P>
-Just copy the code below as it is, including the block's curly parentheses.
-And everywhere in your code use the <CODE>print_header()</CODE> sub to
-print the header. <CODE>$need_header</CODE> is the same beast as static variable in C, so it remembers its value from
-call to call.
+Just copy the code below, including the block's curly parentheses. And
+everywhere in your code you print the header use the <CODE>print_header()</CODE> sub.
+<CODE>$need_header</CODE> is the same kind of beast as a static variable in C, so it remembers its
+value from call to call.
<P>
<PRE> {
@@ -90,38 +91,66 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="More_on_relative_paths">More on relative paths</A></H1></CENTER>
<P>
-Many use a relative require call, or write to the file in the current or
-relative to the current directory. But this will fail if you wouldn't
-<CODE>chdir()</CODE> into the directory first. So you have to either do
-this in the code or to use a nice <CODE>FindBin.pm</CODE> package.
+Many people use relative paths for <CODE>require</CODE>, <CODE>use</CODE>, etc., or open files in the current directory or relative to the current
+directory. But this will fail if you don't <CODE>chdir()</CODE> into the correct directory first (e.g when you call the script by its full
+path). This code would work:
<P>
+<PRE> /home/httpd/perl/test.pl:
+ -------------------------
+ #!/usr/bin/perl
+ open IN, "./foo.txt";
+ -------------------------
+</PRE>
+<P>
+if we call the script by:
+
+<P>
+<PRE> % chdir /home/httpd/perl
+ % ./test.pl
+</PRE>
+<P>
+since <CODE>foo.txt</CODE> is located at the same directory the script is being called from. if we
+call the script by:
+
+<P>
+<PRE> % /home/httpd/perl/test.pl
+</PRE>
+<P>
+when we aren't chdir to the <CODE>/home/httpd/perl</CODE>, the script will fail to find <CODE>foo.txt</CODE>. If you don't want to use hardcoded directories in your scripts, <CODE>FindBin.pm</CODE> package will come to rescue.
+
+<P>
<PRE> use FindBin qw($Bin);
use lib $Bin;
- # or
+ open IN, "./foo.txt";
+</PRE>
+<P>
+or
+
+<P>
+<PRE> use FindBin qw($Bin);
open IN, "$Bin/foo.txt";
</PRE>
<P>
-Now <CODE>$Bin</CODE> includes the path of the directory the script resides on, so you can move
-the script from one directory to the other and call it from anywhere else,
-the paths will be always correct.
+Now <CODE>$Bin</CODE> includes the path of the directory the script resides in, so you can move
+the script from one directory to the other and call it from anywhere else.
+The paths will be always correct.
<P>
-It's different from using the ``./foo'', for you have to chdir to the
-directory the script located at first. (Think about crontabs!!!)
+It's different from using <CODE>"./foo"</CODE>, for you first have to <CODE>chdir</CODE> to the directory in which the script is located. (Think about <CODE>crontab</CODE>s!!!)
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
-<CENTER><H1><A NAME="Watching_the_error_log_file_with">Watching the error_log file without telneting to the server.</A></H1></CENTER>
+<CENTER><H1><A NAME="Watching_the_error_log_file_with">Watching the error_log file without telneting to the server</A></H1></CENTER>
<P>
-I wrote this script long time ago, when I have had to debug my cgi scripts
-but I didn't have the access to the error_log file. I have asked the admin
-to install this script and happily used it since then.
+I wrote this script a long time ago, when I had to debug my CGI scripts but
+didn't have the access to the <CODE>error_log</CODE> file. I asked the admin to install this script and have used it happily
+since then.
<P>
-If your scripts are running on these 'Get-free-site' servers, and your
+If your scripts are running on these 'Get-free-site' servers, and you
cannot debug your script because you can't telnet to the server or can't
-see the error_log, you can ask your sysadmin to install this script.
+see the <CODE>error_log</CODE>, you can ask your sysadmin to install this script.
<P>
Ok, here is the code:
@@ -209,8 +238,8 @@
<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:
+Sometimes you want to access variables from the caller's package. One way
+is to do:
<P>
<PRE> my $caller = caller;
@@ -220,16 +249,15 @@
<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
+Unless you use some well known module 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}.
+Cookies come in the <CODE>$ENV{HTTP_COOKIE}</CODE> variable. You can print the raw cookie string as <CODE>$ENV{HTTP_COOKIE}</CODE>.
<P>
-This is a fairly well-known bit of code to take cookie values and put them
-into a hash.
+Here is a fairly well-known bit of code to take cookie values and put them
+into a hash:
<P>
<PRE> sub getCookies {
@@ -269,7 +297,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 05/17/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
1.16 +66 -68 modperl-site/guide/start.html
Index: start.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/start.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- start.html 1999/07/02 13:42:31 1.15
+++ start.html 1999/08/17 19:03:46 1.16
@@ -46,120 +46,118 @@
<P>
<CENTER><H1><A NAME="What_s_inside_">What's inside?</A></H1></CENTER>
<P>
-Before you start with mod_perl installation, you should see an overall
-picture of this wonderful technology. There is more then one way to use
-mod_perl enabled webserver. You have to decide what mod_perl schema you
+Before you start installing mod_perl, you should have an overall picture of
+this wonderful technology. There is more then one way to use a
+mod_perl-enabled webserver. You have to decide what mod_perl scheme you
want to use. <A HREF="././strategy.html#">Picking the Right Strategy</A>
-chapter presents various approaches and discusses the pros and cons of
-them.
+chapter presents various approaches and discusses their pros and cons.
<P>
-Once you know what fits your requirements the best, you should proceed to <A HREF="././scenario.html#">Real World Scenarios Implementaion</A>. This chapter provides a very detailed scenarios of the schemas discussed
-in the
+Once you know what fits your requirements the best, you should proceed to <A HREF="././scenario.html#">Real World Scenarios Implementaion</A>. This chapter provides very detailed scenarios of the schemes discussed in
+the
<A HREF="././strategy.html#">Picking the Right Strategy</A> chapter.
<P>
-<A HREF="././install.html#">Server Installation</A> chapter completes the <A HREF="././scenario.html#">Real World Scenarios Implementaion</A> by providing more indepth installation details.
+The <A HREF="././install.html#">Server Installation</A> chapter follows on to the <A HREF="././scenario.html#">Real World Scenarios Implementaion</A> chapter by providing more in-depth installation details.
<P>
-<A HREF="././config.html#">Server Configuration</A> adds to the basic configurations presented in the <A HREF="././scenario.html#">Real World Scenarios Implementaion</A>
-extended configurations and various configuration examples.
+The <A HREF="././config.html#">Server Configuration</A> chapter adds to the basic configurations presented in the <A HREF="././scenario.html#">Real World Scenarios Implementaion</A> chapter with extended configurations and various configuration examples.
<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.
+The <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 encountered mod_perl problems. So this is the
+first place you should check if you have got a problem.
<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 run under mod_perl. Along with the porting notes it provides
-guidelines for a proper mod_perl programming.
+Probably the most important chapter is <A HREF="././porting.html#">CGI to mod_perl Porting. mod_perl Coding guidelines</A>. It explains the differences between scripts running under mod_cgi and
+mod_perl, and what should be done in order to make existing scripts run
+under mod_perl. Along with the porting notes it provides guidelines for
+proper mod_perl programming.
<P>
<A HREF="././performance.html#">Performance. Benchmarks</A> is the biggest and a very important chapter. It explains the details of
-tuning the mod_perl and the scripts running under it, so you can squeeze
-every ounce of the power from your server. A big part of the chapter are
+tuning mod_perl and the scripts running under it, so you can squeeze every
+ounce of the power from your server. A big part of the chapter are
benchmarks, the numbers that IT managers love to read. But these are
-different benchmarks - they are not comparing mod_perl with other alike
-technologies but different configurations of mod_perl servers, to guide you
-through 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
-acquire this knowledge - you can make a magic with your server.
+different benchmarks: they are not comparing mod_perl with similar
+technologies, rather with different configurations of mod_perl servers, to
+guide you through 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 acquire this knowledge you can make magic with your server.
<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 too obvious to them. This is not true
-for a newbie, this chapter tries to talk about such things.
+The <A HREF="././obvious.html#">Things obvious to others, but not to you</A> chapter is exactly what it claims to be. Some people have been in this
+business too long, and many things have become too obvious to them. This is
+not true for a newbie, so this chapter talks about such things.
<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 speaks a secret
+While developing your mod_perl applications, you will begin 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 is that it speaks 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>.
+the chapter <A HREF="././warnings.html#">Warnings and Errors: Where and Why</A>.
<P>
-If you are into a driving of relational databases with your cgi scripts, <A HREF="././databases.html#">mod_perl and Relational Databases</A> chapter will tell you all about database related goodies mod_perl has
+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 the database-related goodies mod_perl has
prepared for you.
<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.
+If you are using good old dbm files for your databases, the <A HREF="././dbm.html#">mod_perl and dbm files</A> chapter explains how to utilize them better under mod_perl.
<P>
-More and more Internet Service Providers (ISPs) are evaluating a
-possibility to provide the mod_perl services to their users. Is it
-possible? Is it secure? Will it work? How much resources does it takes? <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
+More and more Internet Service Providers (ISPs) are evaluating the
+possibility of providing mod_perl services to their users. Is this
+possible? Is it secure? Will it work? What resources does it take? The <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 root access, read this chapter as well, either to
+learn how do it yourself, or maybe to persuade your ISP to provide this
service.
<P>
-If you have to administrate your apache mod_perl server -
-<A HREF="././control.html#">Controlling and Monitoring the Server</A> chapter is for you. Among the topics there are server restarting and
-monitoring techniques, preventing from server to eat up all your disk space
-in a matter of minutes and more.
-
-<P>
-<A HREF="././status.html#">mod_perl Status. Peeking into the Server's Perl Innards</A>
-chapter shows you the ways you can peek at what is going on in the mod_perl
-enabled server while it is running. Like looking what is the value of some
-global variable, what database connections are open, looking up what
-modules were loaded and their pathes, what is the value of
-<CODE>@INC</CODE> and much more.
+If you have to administer your Apache mod_perl server the
+<A HREF="././control.html#">Controlling and Monitoring the Server</A> chapter is for you. Among the topics are: server restarting and monitoring
+techniques, preventing the server from eating up all your disk space in a
+matter of minutes, and more.
<P>
-Every programmer needs to know how to debug the program she writes. It is
-an _easy_ task with plain perl. Just invoke the program with <CODE>-d</CODE>
+The <A HREF="././status.html#">mod_perl Status. Peeking into the Server's Perl Innards</A>
+chapter shows you the ways you can peek at what is going on in a
+mod_perl-enabled server while it is running. Like looking at the value of
+some global variable, what database connections are open, looking up what
+modules were loaded and their paths, what is the value of <CODE>@INC</CODE>, and much more.
+
+<P>
+Every programmer needs to know how to debug her program. It is an _easy_
+task with plain Perl. Just invoke the program with the <CODE>-d</CODE>
flag and debug it. Is it possible to do the same under mod_perl? After all
-you cannot debug every CGI script by executing it from the command line,
-some scripts will not run from the command line. <A HREF="././debug.html#">Debugging mod_perl</A> chapter proves it possible and real.
+you cannot debug every CGI script by executing it from the command line:
+some scripts will not run from the command line. The <A HREF="././debug.html#">Debugging mod_perl</A> chapter proves debugging under mod_perl is possible and real.
<P>
-Sometimes browsers that interact with our servers have bugs, which cause a
-strong headache to CGI developers. Preventing these bugs from happening is
-being discussed in <A HREF="././browserbugs.html#">Workarounds for some known bugs in browsers</A> chapter.
+Sometimes browsers that interact with our servers have bugs, which cause
+big headaches for CGI developers. Preventing these bugs from happening is
+discussed in the <A HREF="././browserbugs.html#">Workarounds for some known bugs in browsers</A> chapter.
<P>
Many modules were written to extend the mod_perl's core functionality. Some
-of important modules are being covered in
+important modules are covered in the
<A HREF="././modules.html#">Apache::* modules</A> chapter.
<P>
-Some folks decide to go mod_perl, but they miss the basic understanding of
-the perl, which is absolutely not tolerant by mod_perl. If you are such a
-person, there is nothing to be ashamed of, we all went through this. Get a
-good perl book and start reading. <A HREF="././perl.html#">Perl Reference</A> gives some basic perl lessons, delivering the knowledge you cannot start to
-program mod_perl scripts without.
+Some folks decide to go with mod_perl, but they are missing a basic
+understanding of Perl, which is absolutely not tolerated by mod_perl. If
+you are such a person, there is nothing to be ashamed of; we all went
+through this. Get a good Perl book and start reading. The <A HREF="././perl.html#">Perl Reference</A> chapter gives some basic perl lessons, delivering the knowledge without
+which you cannot start to program mod_perl scripts.
<P>
-<A HREF="././snippets.html#">Code Snippets</A> chapter is just a collection of code snippets I have found useful while
+The <A HREF="././snippets.html#">Code Snippets</A> chapter is just a collection of code snippets I have found useful while
writing the scripts.
<P>
-<A HREF="././help.html#">Getting Helped and Further Learning</A> refers you to other related information resources, like learning perl
-programming and SQL, understanding security, building databases and more.
+The <A HREF="././help.html#">Getting Helped and Further Learning</A> chapter refers you to other related information resources, like learning
+Perl programming and SQL, understanding security, building databases, and
+more.
<P>
<A HREF="././download.html#">Appendix A: Downloading software and documentation</A>
@@ -189,7 +187,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
1.16 +18 -21 modperl-site/guide/status.html
Index: status.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/status.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- status.html 1999/07/02 13:42:31 1.15
+++ status.html 1999/08/17 19:03:46 1.16
@@ -53,9 +53,9 @@
<P>
<CENTER><H1><A NAME="Watching_the_server">Watching the server</A></H1></CENTER>
<P>
-Very useful feature. You can watch what happens to the perl parts of the
-server. Below you will find the instructions of configuration and usage of
-this feature
+This is a very useful feature. You can watch what happens to the Perl parts
+of the server. Here are the instructions for configuring and using this
+feature:
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
@@ -73,8 +73,8 @@
</Location>
</PRE>
<P>
-If you are going to use Apache::Status. It's important to put it as a first
-module in the start-up file, or in the httpd.conf.
+If you are going to use <CODE>Apache::Status</CODE> it's important to put it as the first module in the start-up file, or in
+the httpd.conf:
<P>
<PRE> # startup.pl
@@ -83,17 +83,16 @@
use Apache::DBI ();
</PRE>
<P>
-If you don't put Apache::Status before Apache::DBI then you don't get
-Apache::DBI's menu entry in status.
+If you don't put <CODE>Apache::Status</CODE> before <CODE>Apache::DBI</CODE>, you wouldn't get <CODE>Apache::DBI</CODE>'s menu entry in status.
<P>
-For more about Apache::DBI see <A HREF="././performance.html#Persistent_DB_Connections">Persistent DB Connections</A>.
+For more about <CODE>Apache::DBI</CODE> 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><H2><A NAME="Usage">Usage</A></H2></CENTER>
<P>
-Assuming that your mod_perl server listens to port 81, fetch <A
+Assuming that your mod_perl server listens on port 81, fetch <A
HREF="http://www.myserver.com:81/perl-status">http://www.myserver.com:81/perl-status</A>
@@ -118,27 +117,25 @@
Symbol Table Dump
</PRE>
<P>
-Let's follow for example : PerlRequire'd Files => we see:
+Let's follow, for example, <CODE>PerlRequire</CODE>'d Files. We see:
<P>
-<PRE> PerlRequire Location
- /usr/apps/pais/lib/apache-startup.pl /usr/apps/pais/lib/apache-startup.pl
+<PRE> PerlRequire Location
+ /home/perl/apache-startup.pl /home/perl/apache-startup.pl
</PRE>
<P>
-From some menus you can continue dipper to peek into internals of the
+From some menus you can continue deeper to peek into the internals of the
server, to see the values of the global variables in the packages, to the
-the cached scripts and modules and much more. Just click around...
+cached scripts and modules, and much more. Just click around...
<P>
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H2><A NAME="Compiled_Registry_Scripts_sectio">Compiled Registry Scripts section seems to be empty.</A></H2></CENTER>
<P>
-Sometimes when you fetch /perl-status you and follow the <STRONG>Compiled
-Registry Scripts</STRONG> -- you see no listing of scripts at all. This is absolutely correct --
-Apache::Status shows the registry scripts compiled in the httpd child which
-is serving your request for /perl-status. If a child has not compiled yet
-the script you are asking for, /perl-status will just show you the main
-menu.
+Sometimes when you fetch <CODE>/perl-status</CODE> and follow the <STRONG>Compiled
+Registry Scripts</STRONG> you see no listing of scripts at all. This is absolutely correct: <CODE>Apache::Status</CODE> shows the registry scripts compiled in the httpd child which is serving
+your request for /perl-status. If a child has not compiled yet the script
+you are asking for, /perl-status will just show you the main menu.
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
The <a href="http://www.modperl.com/">
@@ -163,7 +160,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/26/1999
+ <BR>Last Modified at 07/29/1999
</FONT>
</B>
</TD>
1.6 +25 -21 modperl-site/guide/strategy.html
Index: strategy.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/strategy.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- strategy.html 1999/07/02 13:42:31 1.5
+++ strategy.html 1999/08/17 19:03:46 1.6
@@ -106,7 +106,7 @@
and work on getting your feet wet with apache and mod_perl. Later, you can
decide whether to move to the second one which allows better tuning at the
expense of more complicated administration, or to the third option -- the
-more state-of-the-art-yet-suspiciously-new DSO system, or to the forth
+more state-of-the-art-yet-suspiciously-new DSO system, or to the fourth
option which gives you even more power.
<OL>
@@ -244,9 +244,10 @@
<CENTER><H1><A NAME="One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl-enabled Apache Servers</A></H1></CENTER>
<P>
As I have mentioned before, when running scripts under mod_perl, you will
-notice that the httpd processes consume a huge amount of memory, from 5M to
-25M, or even more. That is the price you pay for the enormous speed
-improvements under mod_perl. (Again -- shared memory keeps them smaller :)
+notice that the httpd processes consume a huge amount of virtual memory,
+from 5Mb to 15Mb and even more. That is the price you pay for the enormous
+speed improvements under mod_perl. (Again -- shared memory keeps the real
+memory that is being used much smaller :)
<P>
Using these large processes to serve static objects like images and html
@@ -400,14 +401,17 @@
At the beginning there were 2 servers: one - plain apache server, which was <STRONG>very light</STRONG>, and configured to serve static objects, the other -- mod_perl enabled,
which was <STRONG>very heavy</STRONG> 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
+by listening to different ports: 80 -- for <CODE>httpd_docs</CODE>
+(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
+) and 8080 -- for
+<CODE>httpd_perl</CODE> (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. (Later on, I will be
-moving the httpd_docs server to port 81.)
+moving the
+<CODE>httpd_docs</CODE> server to port 81.)
<P>
Now I am going to convince you that you <STRONG>want</STRONG> to use a proxy server (in the http accelerator mode). The advantages are:
@@ -416,7 +420,7 @@
<P><LI>
<P>
Allow serving of static objects from the proxy's cache (objects that
-previously were entirely served by the httpd_docs server).
+previously were entirely served by the <CODE>httpd_docs</CODE> server).
<P><LI>
<P>
@@ -452,9 +456,9 @@
to you as an exercise :)
<P>
-To make your download time numbers even worse, let me remind you that many
-users like to open many browser windows and do many things at once
-(download files and browse <STRONG>heavy</STRONG> sites). So the speed of 3.6kb/sec we were assuming before, may many times
+To make your estimation of download time numbers even worse, let me remind
+you that many users like to open many browser windows and do many things at
+once (download files and browse <STRONG>heavy</STRONG> sites). So the speed of 3.6kb/sec we were assuming before, may many times
be 5-10 times slower.
<P><LI>
@@ -563,14 +567,14 @@
<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.
+HTTP protocol level. Squid is pretty much a <CODE>HTTP/1.0</CODE> server, which seriously limits the deployment of <CODE>HTTP/1.1</CODE> features.
<P><LI>
<P>
-HTTP headers / dates, freshness. The squid server might give out ``old''
+HTTP headers, dates and freshness. The squid server might give out ``old''
pages, confusing downstream/client caches. Also chances are that you will
-be giving out stale pages.
+be giving out stale pages. (You update the some documents on the site, but
+squid will still serve the old ones.)
<P><LI>
<P>
@@ -594,9 +598,9 @@
<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
<CENTER><H1><A NAME="An_Apache_s_mod_proxy">An 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
+I do not think the difference in speed between apache's <STRONG>mod_proxy</STRONG>
+and <STRONG>squid</STRONG> 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
@@ -631,7 +635,7 @@
</PRE>
<P><LI>
<P>
-It does mod_perl output buffering like squid does. See the <A HREF="././scenario.html#Using_mod_proxy">Using mod_proxy</A> notes for more details.
+It does mod_perl output buffering like squid does. See the <A HREF="././scenario.html#Building_and_Using_mod_proxy">Using mod_proxy</A> notes for more details.
<P><LI>
<P>
@@ -667,7 +671,7 @@
</UL>
<P>
-For implementation see <A HREF="././scenario.html#Using_mod_proxy">Using mod_proxy</A>.
+For implementation see <A HREF="././scenario.html#Building_and_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/">
@@ -692,7 +696,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 07/02/1999
+ <BR>Last Modified at 08/17/1999
</FONT>
</B>
</TD>
1.17 +1 -1 modperl-site/guide/warnings.html
Index: warnings.html
===================================================================
RCS file: /export/home/cvs/modperl-site/guide/warnings.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- warnings.html 1999/07/02 13:42:32 1.16
+++ warnings.html 1999/08/17 19:03:46 1.17
@@ -431,7 +431,7 @@
<B>
<FONT SIZE=-1>
Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
- <BR>Last Modified at 06/19/1999
+ <BR>Last Modified at 07/09/1999
</FONT>
</B>
</TD>