perl-modperl-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sbek...@hyperreal.org
Subject cvs commit: modperl-site/guide guide.tar.gz CHANGES all.html config.html control.html debug.html index.html intro.html performance.html porting.html scenario.html snippets.html start.html status.html warnings.html
Date Tue, 16 Mar 1999 08:20:42 GMT
sbekman     99/03/16 00:20:40

  Modified:    guide    CHANGES all.html config.html control.html
                        debug.html index.html intro.html performance.html
                        porting.html scenario.html snippets.html start.html
                        status.html warnings.html
  Added:       guide    guide.tar.gz
  Log:
  * Added a downloadable guide.tar.gz as someone requested
  
  * snippets.pod: Accessing variables from the caller's package (Ken
   Williams)
  
  * porting.pod: Redirecting mod_perl error_log messages to the browser
   - added an extensive example
  
  * control.pod: added hints - Preventing from modperl process to eat up
   all the disk's space, when it goes wild. (Andreas J. Koenig, Ulrich
   Pfeifer)
  
  * performance.pod: cleared out where one can get the 'ab' Apache
   Benchmark utility
  
  * warning.pod: covered - Evil things might happen when using
   PerlFreshRestart (Doug)
  
  * status.pod: covered - Compiled Registry Scripts section seems to be
   empty (Radu Greab)
  
  * warning.pod: covered - RegistryLoader: Cannot translate the URI...
  
  * scenario.pod: added a note: when using USE_APACI and APACHE_PREFIX,
   make install will run also the make install at Apache's source
   tree... (Doug)
  
  * debug.pod Getting some decent debug info when running under mod_perl
   (Doug)
  
  * ScriptAlias vs. Alias updated and explaned in config.pod. (Doug, Ask
   and Eric)
  
  * scenario.pod, intro.html, config.pod, control.pod and start.pod were
   purified by Steve Reppucci. Steve has fixed my incorrect English
   expressions and tenses, corrected some technical details! Enormous
   help, Steve! Thanks!
  
  If you see some incorrect English in the guide, don't hesitate to send
  an email to me. Thanks!
  
  Revision  Changes    Path
  1.7       +57 -0     modperl-site/guide/CHANGES
  
  Index: CHANGES
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/CHANGES,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- CHANGES	1999/01/23 18:09:56	1.6
  +++ CHANGES	1999/03/16 08:20:09	1.7
  @@ -1,6 +1,63 @@
   This is a CHANGES file for mod_perl mini guide
   
   
  +03.15.99
  +
  +
  +* Added a downloadable guide.tar.gz as someone requested
  +
  +
  +* snippets.pod: Accessing variables from the caller's package (Ken
  + Williams)
  +
  +
  +* porting.pod: Redirecting mod_perl error_log messages to the browser
  + - added an extensive example
  +
  +
  +* control.pod: added hints - Preventing from modperl process to eat up
  + all the disk's space, when it goes wild. (Andreas J. Koenig, Ulrich
  + Pfeifer)
  +
  +
  +* performance.pod: cleared out where one can get the 'ab' Apache
  + Benchmark utility
  +
  +
  +* warning.pod: covered - Evil things might happen when using
  + PerlFreshRestart (Doug)
  +
  +
  +* status.pod: covered - Compiled Registry Scripts section seems to be
  + empty (Radu Greab)
  +
  +
  +* warning.pod: covered - RegistryLoader: Cannot translate the URI...
  +
  +
  +* scenario.pod: added a note: when using USE_APACI and APACHE_PREFIX,
  + make install will run also the make install at Apache's source
  + tree... (Doug)
  +
  +
  +* debug.pod Getting some decent debug info when running under mod_perl
  + (Doug)
  +
  +
  +* ScriptAlias vs. Alias updated and explaned in config.pod. (Doug, Ask
  + and Eric)
  +
  +
  +* scenario.pod, intro.html, config.pod, control.pod and start.pod were
  + purified by Steve Reppucci. Steve has fixed my incorrect English
  + expressions and tenses, corrected some technical details! Enormous
  + help, Steve! Thanks!
  +
  +
  +If you see some incorrect English in the guide, don't hesitate to send
  +an email to me. Thanks!
  +
  +
   01.22.99
   
   
  
  
  
  1.7       +787 -456  modperl-site/guide/all.html
  
  Index: all.html
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/all.html,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- all.html	1999/01/23 18:06:52	1.6
  +++ all.html	1999/03/16 08:20:11	1.7
  @@ -15,7 +15,7 @@
   <CENTER><P><B>Deploying apache/mod_perl accelerator to give a rocket speed
   to your perl cgi-bin scripts.</B></P></CENTER>
   
  -<CENTER><P><B>Version 1.06 Jan, 23 1999</B></P></CENTER>
  +<CENTER><P><B>Version 1.07 Mar, 16 1999</B></P></CENTER>
   
   <P>
   <HR WIDTH="100%"></P>
  @@ -55,6 +55,8 @@
   
   <LI><A HREF="#search">Search perl.apache.org along with this guide</A></LI>
   
  +<LI><A HREF="guide.tar.gz">Download as one file</A></LI>
  +
   </UL>
   
   <HR>
  @@ -88,9 +90,10 @@
   </TR>
   
   <TR ALIGN=CENTER VALIGN=TOP>
  -<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A HREF="help.html#author">Stas
  -Bekman</A>.<BR>
  -Last Modified at 12/09/1998 </FONT></B></TD>
  +
  +<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A
  +HREF="help.html#author">Stas Bekman</A>.<BR> Last Modified at
  +03/16/1999 </FONT></B></TD>
   
   <TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg"  BORDER=0 ALT="Mod Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
   </TD>
  @@ -142,69 +145,77 @@
   
   <P>The Apache/Perl integration project brings together the full power of
   the Perl programming language and the Apache HTTP server. With mod_perl
  -it is possible to write Apache modules entirely in Perl. In addition, the
  -persistent interpreter embedded in the server avoids the overhead of starting
  -an external interpreter, the penalty of Perl start-up time and loading
  -and compiling the modules and the scripts. </P>
  +it is possible to write Apache modules entirely in Perl. In addition,
  +the persistent interpreter embedded in the server avoids the overhead of
  +starting an external interpreter, the penalty of Perl start-up time and
  +loading and compiling the modules and the scripts. </P>
   
   <P>The primary advantages of mod_perl are power and speed. You have full
   access to the inner-workings of the web server and can intervene at any
  -stage of request-processing. This allows for customized processing of (to
  -name just a few of the phases) URI-&gt;filename translation, authentication,
  -response generation and logging. There is very little run-time overhead.
  -In particular, it is not necessary to start a separate process, as is often
  -done with web-server extensions. The most wide-spread such extension mechanism,
  -the Common Gateway Interface (CGI), can be replaced entirely with perl-code
  -that handles the response generation phase of request processing. Mod_perl
  -includes 2 general purpose modules for this purpose (Apache::Registry)
  -that can transparently run existing perl CGI scripts and Apache::PerlRun,
  -which does a similar job but allows you to run dirty (to some extent) written
  +stage of request-processing. This allows for customized processing of
  +(to name just a few of the phases) URI-&gt;filename translation,
  +authentication, response generation and logging. There is very little
  +run-time overhead. In particular, it is not necessary to start a
  +separate process, as is often done with web-server extensions. The most
  +wide-spread such extension mechanism, the Common Gateway Interface
  +(CGI), can be replaced entirely with perl-code that handles the response
  +generation phase of request processing. Mod_perl includes 2 general
  +purpose modules for this purpose: Apache::Registry, which can
  +transparently run existing perl CGI scripts and Apache::PerlRun, which
  +does a similar job but allows you to run "dirtier" (to some extent)
   scripts.</P>
   
  -<P>Many people wonder and ask &quot;How much of a performance improvement
  -does mod_perl give?&quot;. Well, it all depends on what you're doing with
  -mod_perl and possibly who you ask. People report speed boosts from 200%
  -to 2000%.&nbsp;The best way to measure is to try it and see for yourself!
  -(see <A HREF="http://perl.apache.org/tidbits.html">Tidbit </A>and <A HREF="http://perl.apache.org/stories/">Stories
  -</A>pages for the facts)</P>
  +<P>Many people wonder and ask &quot;How much of a performance
  +improvement does mod_perl give?&quot;. Well, it all depends on what
  +you're doing with mod_perl and possibly who you ask. People report speed
  +boosts from 200% to 2000%. The best way to measure is to try it and
  +see for yourself! (see <A
  +HREF="http://perl.apache.org/tidbits.html">Tidbit </A>and <A
  +HREF="http://perl.apache.org/stories/">Stories </A>pages for the
  +facts)</P>
   
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B> 
   <HR WIDTH="100%"></P>
   
   <H3 ALIGN=CENTER><A NAME="2"></A>What is covered in this document</H3>
  -
  -<P>This document was written to help you to start using the mod_perl as
  -soon as possible and with as less as possible obstacles. It includes an
  -information about installation and configuration of perl and apache
  -web server and goes deeply into an issues of writing and porting the perl
  -scripts for mod_perl. Note, that it doesn't enter the big world of using
  -the Perl API or C API. You will find the Pointers covering these topics at
  -<A HREF="help.html">Help Seek and Learning more</A> section of this document.<B>
  -This guide tries to cover the most of the Apache::Registry and Apache::PerlRun.</B></P>
  -
  -<P>It's assumed that you know the basics of building and installing of
  -      perl and apache
  -(If you don't just read the INSTALL docs coming with distribution of each
  -package). However you will find in the document specific perl and
  -      apache related installation and
  -configuration notes, which will help you to successfully 
  -complete the mod_perl installation.</P>
  -
  -<P>If after reading this guide and other documents listed at <A HREF="help.html">Help
  -section</A>, you feel that your question is yet not answered, please ask
  -the apache/mod_perl mailing list to help you. But first try to browse the
  -mailing list archive. Most of the time you will find the answer for your
  -question by searching the mailing archive, since there is a big chance
  -someone else already have encountered the problem and found a solution
  -for it. If you ignore this advice, don't be surprised if your question
  -will be left unanswered - it bores people to answer the same question more
  -than once (twice?). It doesn't mean that you should avoid asking questions. Just
  -don't abuse the available help and <B>RTFM </B>before you call for <B>HELP</B>.
  -(You have certainly heard the infamous fable of the shepherd boy and the
  -wolves)</P>
   
  -<P>If you find incorrect details, my grammar mistakes or you want to contribute
  -to this document please feel free to send me an <A HREF="mailto:sbekman@iil.intel.com">email</A>.</P>
  +<P>This document was written in an effort to help one to start using
  +Apache's mod_perl extension as quickly and easily as possible. It
  +includes information about installation and configuration of perl and
  +the Apache web server and delves deeply into issues of writing and
  +porting existing perl scripts to run under mod_perl. Note that it
  +doesn't attempt to enter the big world of using the Perl API or C API.
  +You will find the Pointers covering these topics at <A
  +HREF="help.html">Help Seek and Learning more</A> section of this
  +document.<B> This guide tries to cover the most of the Apache::Registry
  +and Apache::PerlRun modules.</B></P>
  +
  +<P>It is assumed that you know the basics of building and installing
  +perl and Apache (If you don't, just read the INSTALL docs coming with
  +distribution of each package). However you will find in the document
  +specific perl and Apache related installation and configuration notes,
  +which will help you to successfully complete the mod_perl
  +installation.</P>
  +
  +<P>If after reading this guide and other documents listed at <A
  +HREF="help.html">Help section</A>, you feel that your question is yet
  +not answered, please ask the apache/mod_perl mailing list to help you.
  +But first try to browse the mailing list archive (located at <A
  +HREF="http://forum.swarthmore.edu/epigone/modperl">
  +http://forum.swarthmore.edu/epigone/modperl</A>). Often you will find
  +the answer to your question by searching the mailing archive, since
  +there is a good chance someone else has already encountered the problem
  +and found a solution for it. If you ignore this advice, don't be
  +surprised if your question goes unanswered - it bores people to answer
  +the same question more than once (twice?). This doesn't mean that you
  +should avoid asking questions, just don't abuse the available help and
  +<B>RTFM</B>before you call for <B>HELP</B>. (You have certainly heard
  +the infamous fable of the shepherd boy and the wolves...)</P>
  +
  +<P>If you find incorrect details, my grammar mistakes or you want to
  +contribute to this document please feel free to send me an <A
  +HREF="mailto:sbekman@iname.com">email</A> at
  +<B>sbekman@iname.com</B>.</P>
   
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B> 
   <HR WIDTH="100%"></P>
  @@ -238,7 +249,8 @@
   </UL>
   
   <P>As I said, I've quoted many information snippets from FAQs and emails,
  -      and I didn't credit people after each quote in the guide. I didn't mean to
  +      and I didn't credit people after each quote in the guide.
  +      I didn't mean to
         take the credits for myself, it's just that I've tried to keep
         track of names, and became lost, so I preferred not to credit at
         all in the guide, but to centralize it here. If you think that
  @@ -272,14 +284,15 @@
         <LI>Nathan Torkington
         <LI>Ralf Engelschall
         <LI>Randal Schwartz
  +      <LI>Steve Reppucci
         <LI>Vivek Khera
         <LI>
         <LI>Did I miss you? Tell me!
       </UL>
   </P>
   
  -<P>I&nbsp;want to thank all the people who donated their time and efforts
  -to made this amazing idea of mod_perl to become reality. It includes Doug
  +<P>I want to thank all the people who donated their time and efforts to
  +made this amazing idea of mod_perl to become reality. This includes Doug
   MacEachern, the author of mod_perl and all the developers who contributed
   bug patches, modules and help. And of course the numerous unseen users who
   helped to find the bugs and advocate mod_perl around the world.</P>
  @@ -295,10 +308,9 @@
   <HR></TD>
   </TR>
   
  -<TR ALIGN=CENTER VALIGN=TOP>
  -<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A HREF="help.html#author">Stas
  -Bekman</A>.<BR>
  -Last Modified at 12/10/1998 </FONT></B></TD>
  +<TR ALIGN=CENTER VALIGN=TOP> <TD ALIGN=CENTER VALIGN=CENTER><B><FONT
  +SIZE=-1>Written by <A HREF="help.html#author">Stas Bekman</A>.<BR> Last
  +Modified at 03/16/1999 </FONT></B></TD>
   
   <TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg"  BORDER=0 ALT="Mod Perl Icon" HEIGHT=59 WIDTH=150></A>
   </TD>
  @@ -355,10 +367,10 @@
   	<UL>
   
   		<LI><A HREF="#Testing_by_checking_the_error_lo">Testing by checking the error_log file</A>
  -		<LI><A HREF="#Testing_by_calling_the_perl_sta">Testing by calling the /perl-status </A>
  -		<LI><A HREF="#Testing_by_telneting_to_the_port">Testing by telneting to the port, server's listening to</A>
  -		<LI><A HREF="#Run_a_cgi_that_shows_you_your_se">Run a cgi that shows you your server's environment</A>
  -		<LI><A HREF="#with_lwp_request">with lwp-request</A>
  +		<LI><A HREF="#Testing_by_viewing_perl_status">Testing by viewing /perl-status </A>
  +		<LI><A HREF="#Testing_via_telnet">Testing via telnet</A>
  +		<LI><A HREF="#Testing_via_a_CGI_script">Testing via a CGI script</A>
  +		<LI><A HREF="#Testing_via_lwp_request">Testing via lwp-request</A>
   	</UL>
   
   	<LI><A HREF="#Starting_to_use_the_server">Starting to use the server</A>
  @@ -369,28 +381,28 @@
   <P>
   <CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
   <P>
  -This sections gets you a quick review of configuration and installation of
  -the required tools. For a kick start tutorial, which will allow you make to
  -make copy and paste slick installation, see
  +These sections give a quick review of configuration and installation of the
  +required tools. For a quick-start tutorial, which will allow you make to
  +make a copy-and-paste slick installation, see
   <A HREF="././scenario.html#">Real World Scenario</A>
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Downloading_the_needed_component">Downloading the needed components.</A></H1></CENTER>
   <P>
  -In order to start using the mod_perl - you will need to get first Perl,
  -Apache webserver and mod_perl itself. Below you will find the needed
  +In order to start using mod_perl you will first need to get Perl, the
  +Apache webserver, and mod_perl itself. Below you will find the needed
   information.
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H2><A NAME="Perl_Download">Perl Download</A></H2></CENTER>
   <P>
  -Probably perl is already installed at your machine. But check the version
  -you use. You better get the perl5.004 and higher version. 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
  +Perl is most likely already installed on your machine, but you should at
  +least check the version you using. It is highly recommended that you have
  +at least perl version 5.004 or higher. You can get the latest perl version
  +from <A HREF="http://www.perl.com/.">http://www.perl.com/.</A> Try the
  +direct download link <A
   HREF="http://www.perl.com/pace/pub/perldocs/latest.html.">http://www.perl.com/pace/pub/perldocs/latest.html.</A>
    
   
  @@ -400,7 +412,8 @@
   <P>
   Get the latest apache webserver from <A
   HREF="http://www.apache.org.">http://www.apache.org.</A> Try the direct
  -download link [http://www.apache.org/dist/]. 
  +download link <A
  +HREF="http://www.apache.org/dist/.">http://www.apache.org/dist/.</A> 
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  @@ -408,7 +421,8 @@
   <P>
   Get the latest mod_perl from <A
   HREF="http://perl.apache.org.">http://perl.apache.org.</A> Try the direct
  -download link [http://perl.apache.org/dist/].
  +download link <A
  +HREF="http://perl.apache.org/dist/.">http://perl.apache.org/dist/.</A>
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  @@ -432,11 +446,12 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H2><A NAME="Apache">Apache</A></H2></CENTER>
   <P>
  -It will be a good idea to try to install the Apache webserver without
  -mod_perl first. So later if something going wrong you will know that it's
  -not apache's server problem. But you can skip this stage. In any case you
  -have to open the source distribution of apache preferably at the same level
  -with modperl distribution.
  +It is a good idea to try to install the Apache webserver without mod_perl
  +first. This way, if something going wrong, you will know that it's not the
  +Apache server's problem. But you can skip this stage if you already have a
  +working (non-mod_perl) Apache server, or if you're just the daring type. In
  +any case you should unpack the Apache source distribution, preferably at
  +the same level as the mod_perl distribution.
   
   <P>
   <PRE>  % ls -l /usr/src
  @@ -447,16 +462,15 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H2><A NAME="Mod_Perl">Mod_Perl</A></H2></CENTER>
   <P>
  -Now we come to the main point. 
  +Now we come to the main point of this document. 
   
   <P>
   Here I'll give only a short example of mod_perl installation. You should
  -read the real world scenario for a more complete description.
  +read the real world scenarios for a more complete description.
   
   <P>
  -As with any perl package the installation of mod_perl is very easy and
  -standard. perldoc INSTALL will guide you thru the configuration and
  -installation process.
  +As with any perl package, the installation of mod_perl is very easy and
  +standard. <CODE>perldoc INSTALL</CODE> will guide you thru the configuration and installation process.
   
   <P>
   The fastest way to install would be:
  @@ -467,13 +481,13 @@
     % make &amp;&amp; make test &amp;&amp; make install
   </PRE>
   <P>
  -(Note: if you use an apache version different then apache_1.3.2, the line
  -above and later should be changed appropriately)
  +(Note: if you use an apache version different then apache_1.3.2, change the
  +version number in the example above and in all later examples
  +appropriately)
   
   <P>
  -To change the installation target (either if you aren't root or you need to
  -install a second copy for testing purposes), assuming you use /foo/server
  -as a base directory root, you have to run this:
  +To change the installation target (either if you aren't <CODE>root</CODE> or you need to install a second copy for testing purposes), assuming you
  +use /foo/server as a base directory root, you have to run this:
   
   <P>
   <PRE>  % perl Makefile.PL APACHE_SRC=../apache_1.3.2/src \
  @@ -481,12 +495,12 @@
       APACHE_PREFIX=/foo/server PREFIX=/foo/server
   </PRE>
   <P>
  -Where <CODE>PREFIX</CODE> says where to install the perl modules,
  +Where <CODE>PREFIX</CODE> specifies where to install the perl modules,
   <CODE>APACHE_PREFIX</CODE> - the same for the apache files.
   
   <P>
  -Next step is to configure the mod_perl sections in the apache conf files.
  -See <A HREF="././config.html#">ModPerlConfiguration</A>
  +The next step is to configure the mod_perl sections of the apache conf
  +files. See <A HREF="././config.html#">ModPerlConfiguration</A>
   
   <P>
   Fire up the server with <CODE>/foo/server/sbin/apachectl start</CODE>, Watch the error log file if server doesn't start up (No error message
  @@ -507,13 +521,12 @@
   </PRE>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="Testing_by_calling_the_perl_sta">Testing by calling the /perl-status</A></H2></CENTER>
  +<CENTER><H2><A NAME="Testing_by_viewing_perl_status">Testing by viewing /perl-status</A></H2></CENTER>
   <P>
  -Fetch: <A
  +Assuming that you have configured the <CODE>&lt;Location /perl-status</CODE>&gt; Section in the server configuration file (refer to
  +<A HREF="././config.html#">ModPerlConfiguration</A>), fetch: <A
   HREF="http://www.yourserver.com/perl-status">http://www.yourserver.com/perl-status</A>
  -from your favorite Netscape browser :-) (Assuming you have configured the
  -&lt;Location /perl-status&gt; Section in the server config file (refer to
  -<A HREF="././config.html#">ModPerlConfiguration</A>)
  +using your favorite Netscape browser :-)
   
   <P>
   You should see something like this:
  @@ -524,17 +537,20 @@
   </PRE>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="Testing_by_telneting_to_the_port">Testing by telneting to the port, server's listening to</A></H2></CENTER>
  +<CENTER><H2><A NAME="Testing_via_telnet">Testing via telnet</A></H2></CENTER>
   <P>
  -Assume that you set <CODE>Port 8080</CODE> in the httpd.conf for your mod_perl server. You have to telnet to your
  -server port 8080, then you should type <CODE>HEAD / HTTP/1.0</CODE> then press the &lt;ENTER&gt; key TWICE!
  +Knowing the port you've configured Apache to listen on, you can use <CODE>telnet</CODE> to talk directly to the web server.
   
   <P>
  +Assume that you set <CODE>Port 8080</CODE> in the httpd.conf for your mod_perl enabled server. Telnet to your server
  +at port 8080, and type <CODE>HEAD / HTTP/1.0</CODE> then press the &lt;ENTER&gt; key TWICE!
  +
  +<P>
   <PRE>  % telnet yourserver.com 8080&lt;ENTER&gt;
     HEAD / HTTP/1.0&lt;ENTER&gt;&lt;ENTER&gt;
   </PRE>
   <P>
  -You should see a respond like this:
  +You should see a response like this:
   
   <P>
   <PRE>  HTTP/1.1 200 OK
  @@ -546,18 +562,22 @@
     Connection closed.
   </PRE>
   <P>
  -So you see <CODE>Server: Apache/1.3.2 (Unix) mod_perl/1.16_01</CODE> - which says that you do have mod_perl installed and it's 1.16_01. Of
  -course in your case it would be the version you have installed.
  +So you see <CODE>Server: Apache/1.3.2 (Unix) mod_perl/1.16_01</CODE> - which says that you <STRONG>do</STRONG> have mod_perl installed and it is version 1.16_01. Of course in your case
  +it would be the version you have installed.
   
   <P>
  -However, just because you've got it linked in there, that doesn't meant
  -that you have your server configured to use mod_perl to handle Perl
  +However, just because you've got mod_perl linked in there, that doesn't
  +meant that you have your server configured to use mod_perl to handle Perl
   scripts. You will find the configuration assistance at
   <A HREF="././config.html#">ModPerlConfiguration</A>
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="Run_a_cgi_that_shows_you_your_se">Run a cgi that shows you your server's environment</A></H2></CENTER>
  +<CENTER><H2><A NAME="Testing_via_a_CGI_script">Testing via a CGI script</A></H2></CENTER>
  +<P>
  +Another method is to invoke a CGI script which dumps the server's
  +environment.
  +
   <P>
   Copy and paste the script below (no need for perl line!). Let's say you
   called it test.pl, you saved it into the root of the cgi scripts, and cgi
  @@ -579,9 +599,9 @@
   <PRE>  % chmod a+x test.pl
   </PRE>
   <P>
  -Now fetch the <A
  -HREF="http://www.you.com:8080/perl/test.pl">http://www.you.com:8080/perl/test.pl</A>
  -. You should see something like this (part of the output was snipped).
  +Now fetch the URL <A
  +HREF="http://www.you.com:8080/perl/test.pl.">http://www.you.com:8080/perl/test.pl.</A>
  +You should see something like this (part of the output was snipped).
   
   <P>
   <PRE>  SERVER_SOFTWARE    Apache/1.3.2 (Unix) mod_perl/1.16_01
  @@ -595,7 +615,8 @@
   </PRE>
   <P>
   Now if I run the same script in mod_cgi mode (configured with /cgi-bin)
  -(you must add the perl line #!/bin/perl for the above script) and fetch <A
  +(you'll need to add the perl line #!/bin/perl for the above script) and
  +fetch <A
   HREF="http://www.you.com/cgi-bin/test.pl">http://www.you.com/cgi-bin/test.pl</A>
   
   <P>
  @@ -604,43 +625,45 @@
     [...snipped]
   </PRE>
   <P>
  -You will see that 2 environment variables <CODE>SERVER_SOFTWARE</CODE> and
  -<CODE>GATEWAY_INTERFACE</CODE> are different from the case above. So you've got the hint how to tell in
  -what mode you are running in your cgi scripts. I start all my cgi scripts
  -that are mod_perl aware with:
  +You will see that two variables, <CODE>SERVER_SOFTWARE</CODE> and
  +<CODE>GATEWAY_INTERFACE</CODE>, are different from the case above. This gives you a hint of how to tell
  +in what mode you are running in your cgi scripts. I start all my cgi
  +scripts that are mod_perl aware with:
   
   <P>
   <PRE>  BEGIN {
         # Auto-detect if we are running under mod_perl or CGI.
  -    $USE_MOD_PERL = ( (exists $ENV{'GATEWAY_INTERFACE'} and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
  -                      or exists $ENV{'MOD_PERL'} ) ? 1 : 0;
  +    $USE_MOD_PERL = ((exists $ENV{'GATEWAY_INTERFACE'}
  +                  and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
  +                   or exists $ENV{'MOD_PERL'} );
         # perl5.004 is a must under mod_perl
       require 5.004 if $USE_MOD_PERL;
     }
   </PRE>
   <P>
  -You might wander why in the world you will need to know in what mode you
  +You might wonder why in the world you would need to know in what mode you
   are running. For example you will want to use <CODE>Apache::exit()</CODE>
   and not <CODE>CORE::exit()</CODE> in your scripts, but if you think that your script might be used in both
   environments (mod_cgi vs mod_perl), you will have to override the <CODE>exit()</CODE> subroutine and to make the runtime decision of what method you will use.
  -For reasons and implementations see: <A HREF="././porting.html#using_exit_">Using exit()</A> and the whole <A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs to it</A> page.
  +For reasons and implementations see: <A HREF="././porting.html#using_exit_">Using exit()</A> and the whole
  +<A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs to it</A> page.
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="with_lwp_request">with lwp-request</A></H2></CENTER>
  +<CENTER><H2><A NAME="Testing_via_lwp_request">Testing via lwp-request</A></H2></CENTER>
   <P>
   Yet another one. Why do I show all these approaches? While here they are
   serving a very simple purpose, they can be helpful in other situations. 
   
   <P>
  -Assuming you have the libwww-perl package installed (LWP), you will need it
  -installed for passing the mod_perl's <CODE>make test</CODE> anyway.
  +Assuming you have the libwww-perl (LWP) package installed (you will need it
  +installed in order to pass mod_perl's <CODE>make test</CODE> anyway):
   
   <P>
   <PRE>  % lwp-request -e -d www.site.com
   </PRE>
   <P>
  -Will show you all the headers.
  +Will show you all the headers. (The <CODE>-d</CODE> option disables printing the response content.) 
   
   <P>
   <PRE>  % lwp-request -e -d www.site.com | egrep '^Server:'
  @@ -652,13 +675,13 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Starting_to_use_the_server">Starting to use the server</A></H1></CENTER>
   <P>
  -Now you want to writing the cgis. You better start writing it very clean
  -and with understanding of the new running environment. You have to learn
  -how to write correctly for mod_perl. There is nothing new here, all you
  -have to remember that your script wouldn't die after it finishes to serve
  -the request, but will stay in memory and might affect all other scripts
  -running under the same server process (child). You will read more about it
  -in the following sections: <A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs</A>
  +Now you are ready to start writing CGIs. Note here -- you had better start
  +writing your scripts with an eye towards making them clean (i.e., <CODE>use strict;</CODE>), and with understanding of the new running environment. You have to learn
  +how to write correctly for mod_perl. This is nothing new, the major item to
  +remember is that your script won't die after it finishes serving the
  +request, but will stay in memory and might affect all other scripts running
  +under the same server process (child). You will read more about it in the
  +following sections: <A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs</A>
   
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
  @@ -674,7 +697,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/01/99 
         </FONT>
       </B>
     </TD>
  @@ -718,13 +741,13 @@
   <P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
   <UL>
   
  -	<LI><A HREF="#Making_a_strategic_decision">Making a strategic decision</A>
  -	<LI><A HREF="#Deciding_on_directories_layout">Deciding on directories layout</A>
  -	<LI><A HREF="#Configuration_and_compilation_of">Configuration and compilation of the sources. </A>
  +	<LI><A HREF="#Making_a_Strategic_Decision">Making a Strategic Decision</A>
  +	<LI><A HREF="#Deciding_on_a_Directory_Layout">Deciding on a Directory Layout</A>
  +	<LI><A HREF="#Configuration_and_Compilation_of">Configuration and Compilation of the Sources. </A>
   	<UL>
   
  -		<LI><A HREF="#httpd_docs_server">httpd_docs server</A>
  -		<LI><A HREF="#httpd_perl_server_mod_perl_">httpd_perl server (mod_perl):</A>
  +		<LI><A HREF="#httpd_docs_Server">httpd_docs Server</A>
  +		<LI><A HREF="#httpd_perl_Server_mod_perl_">httpd_perl Server (mod_perl):</A>
   	</UL>
   
   	<LI><A HREF="#Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A>
  @@ -733,73 +756,70 @@
   
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P>
  -<CENTER><H1><A NAME="Making_a_strategic_decision">Making a strategic decision</A></H1></CENTER>
  +<CENTER><H1><A NAME="Making_a_Strategic_Decision">Making a Strategic Decision</A></H1></CENTER>
   <P>
  -When you will run your scripts under mod_perl - you will notice that the
  -httpd processes consumes a huge pieces of memory, from 5M to 25M and more.
  -Since there is no free dinner, that's the price we pay for the great speed
  -improvements under mod_perl. But it doesn't mean that you should serve the
  -static objects like images and html docs with these processes. It's an
  -overkill. The best approach is to run 2 servers: a light apache server with
  -no mod_perl compiled in to serve the static pages, and a heavy
  -apache/mod_perl server to server the cgis in mod_perl mode only. This
  +When running your scripts under mod_perl, you will notice that the httpd
  +processes consume a huge amount of memory, from 5M to 25M and more. That's
  +the price you pay for the great speed improvements under mod_perl -- the
  +function of Perl has has embedded in the Apache server binary.
  +
  +<P>
  +It's overkill to serve the static objects like images and html docs with
  +these larger processes. The best approach is to run two servers: a light
  +Apache server with no mod_perl compiled in serving the static pages, and a
  +heavy Apache/mod_perl server serving the CGIs in mod_perl mode only. This
   section describes a real world example ready for copy and paste to start
   with. You will probably will want to change the base directories, but
  -basically you can pick it as it is. 
  +basically you can use it as it is.
   
   <P>
  -Since we run 2 apache servers we will need 2 different configuration files,
  -log files and etc. We need a special directory layout. While some of the
  -directories can be shared between 2 servers (assuming that use the same
  -source distribution for both servers, other should be separated. I choose
  -to make the difference between 2 servers by calling them httpd_docs
  -(apache) and httpd_perl (apache/mod_perl). 
  +Since we run two apache servers we will need two different configuration
  +files, log files and etc. We need a special directory layout. While some of
  +the directories can be shared between the two servers (assuming that both
  +are built from the same source distribution) others should be separated.
  +We'll refer to these two servers as <STRONG>httpd_docs</STRONG>
  +(vanilla Apache) and <STRONG>httpd_perl</STRONG> (Apache/mod_perl). 
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H1><A NAME="Deciding_on_directories_layout">Deciding on directories layout</A></H1></CENTER>
  +<CENTER><H1><A NAME="Deciding_on_a_Directory_Layout">Deciding on a Directory Layout</A></H1></CENTER>
   <P>
  -We will make /usr/apps our <STRONG>root</STRONG> directory. We will build all the dir tree there. (/usr/apps/bin
  -/usr/apps/etc and etc...) 
  +For this illustration, we'll use <CODE>/usr/apps</CODE> as our <STRONG>root</STRONG> directory. The Apache installation directories will be stored under this
  +root (/usr/apps/bin /usr/apps/etc and etc...)
   
   <P>
  -First let's prepare the sources. We assume that all the sources go to
  -/usr/apps/usr/src dir. First lets make 2 subdirs: 
  +First let's prepare the sources. We'll assume that all the sources go to
  +/usr/apps/usr/src dir. First let's make two subdirectories:
   
   <P>
   <PRE>      % mkdir /usr/apps/usr/src/httpd_docs
         % mkdir /usr/apps/usr/src/httpd_perl
   </PRE>
   <P>
  -Now we put the apache source into /usr/apps/usr/src/httpd_docs: 
  +Now we'll put the Apache source into <CODE>/usr/apps/usr/src/httpd_docs</CODE>:
   
   <P>
   <PRE>      % cd /usr/apps/usr/src/httpd_docs
  -      % cp ~/apache.tar.gz .
  -      % gzip -d apache.tar.gz
  -      % tar xvf apache.tar
  +      % gzip -dc /path/to/tarfile/apache.tar.gz | tar xvf -
   </PRE>
   <P>
  -let's check: 
  +(Replace '<CODE>/path/to/tarfile</CODE>' with the location where you've downloaded the file in all examples.)
  +Let's check:
   
   <P>
   <PRE>      % ls -l
         drwxr-xr-x  8 stas  stas 2048 Oct 29 17:38 apache_1.3.2/
   </PRE>
   <P>
  -Prepare the httpd_perl server sources 
  +Now we'll prepare the httpd_perl server sources:
   
   <P>
   <PRE>      % cd /usr/apps/usr/src/httpd_perl
  -      % cp ~/apache.tar.gz .
  -      % gzip -d apache.tar.gz
  -      % tar xvf apache.tar
  -      % cp ~/modperl.tar.gz .
  -      % gzip -d modperl.tar.gz
  -      % tar xvf modperl.tar
  +      % gzip -dc /path/to/tarfile/apache.tar.gz | tar xvf -
  +      % gzip -dc /path/to/tarfile/modperl.tar.gz | tar xvf -
   </PRE>
   <P>
  -let's check
  +Let's check
   
   <P>
   <PRE>      % ls -l
  @@ -807,14 +827,15 @@
         drwxr-xr-x  8 stas  stas 2048 Oct 29 17:38 modperl-1.16/
   </PRE>
   <P>
  -Time to decide the desired directories structure layout (Where apache files
  -go): 
  +Time to decide one the desired directory structure layout (where the apache
  +files go): 
   
   <P>
   <PRE>      ROOT = /usr/apps 
   </PRE>
   <P>
  -Both Servers Can share the following dirs (so we will not duplicate data): 
  +The two servers can share the following directories (so we will not
  +duplicate data): 
   
   <P>
   <PRE>      /usr/apps/bin/
  @@ -824,7 +845,7 @@
         /usr/apps/share/
   </PRE>
   <P>
  -<STRONG>Important:</STRONG> we assume that both servers comes from the same source
  +<STRONG>Important:</STRONG> we assume that both servers are built from the same Apache source version.
   
   <P>
   Servers store their specific files either in httpd_docs or httpd_perl:
  @@ -846,15 +867,16 @@
                                  run/
   </PRE>
   <P>
  -Next step is to configure and compile the sources: Below are the procedures
  -to compile both servers taking into account the above directories layout:
  +The next step is to configure and compile the sources: Below are the
  +procedures to compile both servers taking into account the above directory
  +layout:
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H1><A NAME="Configuration_and_compilation_of">Configuration and compilation of the sources.</A></H1></CENTER>
  +<CENTER><H1><A NAME="Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A></H1></CENTER>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="httpd_docs_server">httpd_docs server</A></H2></CENTER>
  +<CENTER><H2><A NAME="httpd_docs_Server">httpd_docs Server</A></H2></CENTER>
   <DL>
   <P><DT><STRONG><A NAME="item_Configuration">Configuration</A></STRONG><DD>
   <P>
  @@ -879,7 +901,7 @@
   </PRE>
   <P>
   Note: add --layout to see the resulting dirs layout without actually making
  -the configuration. 
  +the configuration.
   
   <P><DT><STRONG><A NAME="item_Compilation">Compilation:</A></STRONG><DD>
   <P>
  @@ -889,14 +911,14 @@
   <PRE>      % make install
   </PRE>
   <P>
  -Rename the 'httpd' to 'http_docs' 
  +Rename 'httpd' to 'http_docs' 
   
   <P>
   <PRE>      % mv /usr/apps/sbin/httpd_docs/httpd /usr/apps/sbin/httpd_docs/httpd_docs
   </PRE>
   <P>
  -Now update the apachectl utility to point to a new httpd name (by hand or
  -by using perl)
  +Now update the apachectl utility to point to the new httpd name (via your
  +favorite text editor or by using perl)
   
   <P>
   <PRE>      % perl -p -i -e 's|httpd_docs/httpd|httpd_docs/httpd_docs|' /usr/apps/sbin/httpd_docs/apachectl
  @@ -904,15 +926,15 @@
   </DL>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="httpd_perl_server_mod_perl_">httpd_perl server (mod_perl):</A></H2></CENTER>
  +<CENTER><H2><A NAME="httpd_perl_Server_mod_perl_">httpd_perl Server (mod_perl):</A></H2></CENTER>
   <P>
  -Before you start to configure the mod_perl, you should be aware that there
  -a few required modules that have to be installed before. You will know
  -whether you have all the required installed or not, during the run <CODE>perl Makefile.PL</CODE> below. If you discover that you don't have these, go to your nearest CPAN
  -repository (if you don't know what is it, go to <A
  +Before you start to configure the mod_perl sources, you should be aware
  +that there a few Perl modules that have to be installed before building
  +mod_perl. You will be alerted of any missing required when you run the
  +<CODE>perl Makefile.PL</CODE> command line below. If you discover that you don't have these, go to your
  +nearest CPAN repository (if you don't know what is it, go to <A
   HREF="http://www.perl.com/CPAN">http://www.perl.com/CPAN</A> ) or run the
  -interactive shell by
  -<CODE>perl -MCPAN -e shell</CODE> .
  +CPAN interactive shell via the command line <CODE>perl -MCPAN -e shell</CODE> .
   
   <P>
   Now back to installation.
  @@ -924,7 +946,7 @@
         % make clean
   </PRE>
   <P>
  -It's important to <STRONG>make clean</STRONG> since some of the versions aren't binary compatible (e.g apache 1.3.3 vs
  +It is important to <STRONG>make clean</STRONG> since some of the versions aren't binary compatible (e.g apache 1.3.3 vs
   1.3.4) so any ``third-party'' C modules need to be re-compiled against the
   1.3.4 header files.
   
  @@ -961,56 +983,74 @@
   /usr/apps/usr/src/httpd_perl/apache_1.3.2/src/httpd
   
   <P>
  +Note: You have noted that we didn't go to the apache's source dir and run <CODE>make install</CODE>. When <CODE>USE_APACI</CODE> is enabled, <CODE>APACHE_PREFIX</CODE> will specify the --prefix option for Apache's configure script, specifying
  +the installation path for Apache. When this option is used, mod_perl's make
  +install will also make install on the Apache side, installing the httpd
  +binary, support tools, along with the configuration, log and document
  +trees.
  +
  +<P>
   If make test fails, look into t/logs and see what's in there.
   
   <P>
  -rename the 'httpd' to 'httpd_perl' 
  +Rename the 'httpd' to 'httpd_perl' 
   
   <P>
   <PRE>      % mv /usr/apps/sbin/httpd_perl/httpd /usr/apps/sbin/httpd_perl/httpd_perl
   </PRE>
   <P>
  -now update the apachectl utility to point to a new httpd name (by hand or
  +Now update the apachectl utility to point to a new httpd name (by hand or
   by using perl)
   
   <P>
   <PRE>      % perl -p -i -e 's|httpd_perl/httpd|httpd_perl/httpd_perl|' /usr/apps/sbin/httpd_perl/apachectl
   </PRE>
   <P>
  -Now proceed to <A HREF="././config.html#">Server Configuration</A> section.
  +Now proceed to the <A HREF="././config.html#">Server Configuration</A> section.
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A></H1></CENTER>
   <P>
   Yes, no problem with that. Follow the instructions above and when you
  -encounter APACI_ARGS use your home directory or alike as a prefix (e.g
  +encounter APACI_ARGS use your home directory (or some other directory which
  +you have write access to as a prefix, for example,
   <CODE>/home/stas/www</CODE>) and everything will be installed there. There is a chance that some perl
   libs will be not installed on your server by root and you will have to
   install these locally too. See the <A
   HREF="http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html#7">http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html#7</A>
   for more information on local perl installations.
   
  +<P>
  +You will not be able to have the server listen to a port lower then 1024 if
  +you aren't starting it as <CODE>root</CODE>, so choose a port number above 1024. (I use 8080 in most cases). Note that
  +you will have to use a URL like <CODE>http://www.you.com:8080</CODE> in that case, but that's not a problem since generally users don't directly
  +access URLs to CGI scripts, but rather are directed to them from a link on
  +a webpage or as the '<CODE>ACTION</CODE>' of an HTML form, so they shouldn't know at all that the port is different
  +from the default port 80.
  +
  +<P>
  +If you want your Apache server to start automatically on system reboot, you
  +will need to invoke the server startup script from somewhere within the
  +init scripts on your host. (This is often somewhere under
  +<CODE>/etc/rc.d</CODE>, but this path can vary depending upon the flavor of Unix you're using.)
  +
  +<P>
  +One more important thing to keep in mind is system resources. Mod_perl is
  +memory hungry -- if you run a lot of mod_perl processes on that machine
  +(and it's not your own host...), most likely the system administrator of
  +the host will ask you to shutdown your mod_perl server, or to find another
  +home for it. You have a few solutions:
  +
  +<P>
  +<STRONG>a</STRONG>. Reduce resource usage - see <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>
  +
   <P>
  -You will not be able to set the server to listen to port lower then 1024
  -(if you aren't a root). So pick your port as a number above the 1024. (I
  -use 8080 in most cases). Note that you will have to use the <A
  -HREF="http://www.you.com:8080">http://www.you.com:8080</A> in that case.
  -But it's not a problem since generally users don't access directly the cgi
  -but from the webpage, so they shouldn't know at all that the port is
  -different.
  -
  -<P>
  -You will need to worry to put the start server script into rc.d directory
  -of your machine, so if the last will be rebooted - your webserver will be
  -restarted automatically.
  -
  -<P>
  -One more important thing is Resources, mod_perl is very memory greedy and
  -if you will run lots of mod_perl processes on that machine, most likely
  -your host will ask you to shutdown the mod_perl server, or to find another
  -home. You have a few solutions: <STRONG>a.</STRONG> reduce resource usage - see <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>  <STRONG>b.</STRONG> ask your ISP if you can put a dedicated machine into their computer room
  -and be root there. <STRONG>c.</STRONG> look for another ISP with lots of resources or one that supports mod_perl
  +<STRONG>b</STRONG>. Ask your ISP if you can put a dedicated machine into their computer room
  +and be root there.
  +
  +<P>
  +<STRONG>c</STRONG>. Look for another ISP with lots of resources or one that supports mod_perl
   (not likely)
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
  @@ -1026,7 +1066,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/14/99 
         </FONT>
       </B>
     </TD>
  @@ -1070,16 +1110,16 @@
   <P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
   <UL>
   
  -	<LI><A HREF="#configuration">configuration</A>
  +	<LI><A HREF="#Configuration">Configuration</A>
   	<UL>
   
  -		<LI><A HREF="#aliases_configurations">aliases configurations</A>
  +		<LI><A HREF="#Alias_Configurations">Alias Configurations</A>
   	</UL>
   
  -	<LI><A HREF="#Configuration_of_Location">Configuration of Location</A>
  +	<LI><A HREF="#Location_Configuration">Location Configuration </A>
   	<UL>
   
  -		<LI><A HREF="#perl_status_location">perl-status location </A>
  +		<LI><A HREF="#_perl_status_location">/perl-status location </A>
   		<LI><A HREF="#perl_startup_file">perl-startup file</A>
   		<LI><A HREF="#PerlFreshRestart">PerlFreshRestart</A>
   		<LI><A HREF="#What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A>
  @@ -1093,10 +1133,10 @@
   	<UL>
   
   		<LI><A HREF="#My_cgi_perl_code_is_being_return">My cgi/perl code is being returned as a plain text instead of being executed by the webserver?</A>
  -		<LI><A HREF="#Script_working_under_cgi_bin_wh">Script working under cgi-bin, when called as mod_perl I see A 'Save-As' prompt</A>
  +		<LI><A HREF="#My_script_works_under_cgi_bin_b">My script works under cgi-bin, but when called via mod_perl I see A 'Save-As' prompt</A>
   		<LI><A HREF="#Is_there_a_way_to_provide_a_diff">Is there a way to provide a different startup.pl file for each individual virtual host</A>
   		<LI><A HREF="#Is_there_a_way_to_modify_INC_on">Is there a way to modify @INC on a per-virtual-host basis. </A>
  -		<LI><A HREF="#Sometimes_script_from_one_virtua">Sometimes script from one virtual host calls the script with the same path from the second virtual host</A>
  +		<LI><A HREF="#Sometimes_the_script_from_one_vi">Sometimes the script from one virtual host calls a script with the same path from the second virtual host</A>
   	</UL>
   
   </UL>
  @@ -1104,74 +1144,86 @@
   
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P>
  -<CENTER><H1><A NAME="configuration">configuration</A></H1></CENTER>
  +<CENTER><H1><A NAME="Configuration">Configuration</A></H1></CENTER>
  +<P>
  +The next step after building and installing your new mod_perl-enabled
  +Apache server, is to configure the server's configuration files. To learn
  +how to modify Apache's configuration files, please refer to the
  +documentation included with the Apache distribution. or just view the files
  +in conf directory and follow the instructions in these files - the embedded
  +comments within the file do a good job of explaining the options.
  +
   <P>
  -You have just installed the new apache/mod_perl server. Now you have to
  -configure server's configuration files. To learn how to configure the
  -apache's config files, please the use the apache's documentation or just
  -open the files in conf directory and follow the instructions in these files
  -- they are self explainable...
  +Before you start the mod_perl configuration, configure Apache, and see that
  +it works. When done, return here to continue...
   
   <P>
  -Before you start configuration of mod_perl, configure the apache, and see
  -that it works. When done, come back to continue...
  +[ Note that prior to version 1.3.4, the default Apache install used three
  +configuration files -- <STRONG>httpd.conf</STRONG>, <STRONG>srm.conf</STRONG>, and <STRONG>access.conf</STRONG>. The 1.3.4 version began distributing the configuration directives in a
  +single file -- <STRONG>httpd.conf</STRONG>. The remainder of this chapter refers to the location of the configuration
  +directives using their historical location. ]
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="aliases_configurations">aliases configurations</A></H2></CENTER>
  +<CENTER><H2><A NAME="Alias_Configurations">Alias Configurations</A></H2></CENTER>
   <P>
  -OK, first thing you will want to specify the location from where all
  -mod_perl scripts will be called.
  +First, you need to specify the location where all mod_perl scripts will be
  +located.
   
   <P>
  -in srm.conf add:
  +Add the following configuration directives to srm.conf:
   
   <P>
   <PRE>    # plain cgi-bin:
     ScriptAlias /cgi-bin/ /usr/apps/myproject/cgi/
       
       # Apache::Registry mode
  -  ScriptAlias /perl/ /usr/apps/myproject/cgi/
  +  Alias /perl/ /usr/apps/myproject/cgi/
   </PRE>
   <P>
   <PRE>    # Apache::PerlRun mode
  -  ScriptAlias /cgi-perl/ /usr/apps/myproject/cgi/
  +  Alias /cgi-perl/ /usr/apps/myproject/cgi/
   </PRE>
   <P>
  -Alias allows the server to locate the script that was called at the
  -filesystem.
  +Alias provides a mapping of URL to filesystem object.
   
   <P>
  -Alias is the start of the URL path to the script you call, like when you
  -fetch <A
  -HREF="http://www.you.com/perl/test.pl">http://www.you.com/perl/test.pl</A>
  -, server will look for the file test.pl at /usr/apps/myproject/cgi but
  -execute it as a Apache::Registry script, after you set this (see the next
  -section). <A
  -HREF="http://www.you.com/perl/test.pl">http://www.you.com/perl/test.pl</A>
  -will be mapped to /usr/apps/myproject/cgi/test.pl . Basically you can have
  -all your cgis located at the same place at filesystem, and to call the same
  -script in any of 3 modes by just replacing the first directory of the URL
  -(cgi-bin|perl|cgi-perl) - Isn't that cool? (That's the configuration you
  -see above - all 3 ScriptAliases point to the same directory at the
  -filesystem, but ofcourse they can be different). If something is going
  -wrong with your mod_perl you can easily call the scripts in the mod_cgi
  -mode without changing the script (in most cases) but only the URL to call
  -it, and then to put it back!!!
  +Alias defines the start of the URL path to the script you are referencing.
  +For example, using the above configuration, fetching
  +<STRONG>http://www.you.com/perl/test.pl</STRONG>, will cause the server to look for the file <STRONG>test.pl</STRONG> at <STRONG>/usr/apps/myproject/cgi</STRONG>, and execute it as an <STRONG>Apache::Registry</STRONG> script. The URL
  +<STRONG>http://www.you.com/perl/test.pl</STRONG> will be mapped to
  +<STRONG>/usr/apps/myproject/cgi/test.pl</STRONG>. This means you can have all your CGIs located at the same place at
  +filesystem, and call the script in any of three modes simply by changing
  +the directory name component of the URL (cgi-bin|perl|cgi-perl) - isn't
  +that cool? (That's the configuration you see above - all three Aliases
  +point to the same directory within your filesystem, but of course they can
  +be different). If your script doesn't seem to be working while running
  +under mod_perl, you can easily call the script in straight mod_cgi mode
  +without making any script changes (in most cases), but rather by changing
  +the URL you invoke it by.
  +
  +<P>
  +FYI: for modperl ScriptAlias is the same thing as an Alias command +
  +'sethandler cgi-handler'. The latter will be overwritten if you enable
  +Apache::Registry. In other words, ``ScriptAlias does not work for
  +mod_perl'', it only appears to work when the additional config is in there.
  +If the Apache::Registry config came before the ScriptAlias, scripts would
  +be run under mod_cgi. While handy, ScriptAlias is a known kludge, always
  +better to use `Alias' and `SetHandler'.
   
   <P>
   Of course you can choose any other alias (you will use it later in
  -http.conf), you can choose to use all 3 modes or only one of these (It's
  -unlikely to run plain cgi-bin scripts from mod_perl server - the price is
  -too high, you better run these at plain apache server. See
  -<A HREF="././scenario.html#Making_a_strategic_decision">Real World scenario</A> for details)
  +http.conf), you can choose to use all three modes or only one of these
  +(It's undesirable to run plain cgi-bin scripts from a mod_perl-enabled
  +server - the price is too high, it's better to run these on plain Apache
  +server. See <A HREF="././scenario.html#Making_a_strategic_decision">Real World scenario</A> for details.)
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H1><A NAME="Configuration_of_Location">Configuration of Location</A></H1></CENTER>
  +<CENTER><H1><A NAME="Location_Configuration">Location Configuration</A></H1></CENTER>
   <P>
  -Now we work with httpd.conf, I add all the mod_perl stuff at the end of
  -file, after the native apache configurations finish.
  +Now we will work with the httpd.conf file. I add all the mod_perl stuff at
  +the end of the file, after the native Apache configurations.
   
   <P>
   First we add:
  @@ -1187,23 +1239,22 @@
     &lt;/Location&gt;
   </PRE>
   <P>
  -This location's configuration makes all scripts that has been called with
  -/perl path at the beginning to be executed under
  -<STRONG>Apache::Registry</STRONG> module and as cgi (so the <CODE>ExecCGI</CODE>, if you omit this option the script will be just printed to the caller's
  -browser as a plain text or will trigger the 'Save-As' window). 
  +This configuration causes all scripts that are called with a <STRONG>/perl</STRONG> path prefix to be executed under the
  +<STRONG>Apache::Registry</STRONG> module and as a CGI (so the <STRONG>ExecCGI</STRONG>, if you omit this option the script will be printed to the caller's
  +browser as a plain text or will possibly will trigger a 'Save-As' window). 
   
   <P>
  -<CODE>PerlSendHeader On</CODE> tells the server to send an HTTP header to the browser, on every script
  -invocation. You will want to turn it off for you nph (non-parsed-headers)
  +<STRONG>PerlSendHeader On</STRONG> tells the server to send an HTTP header to the browser on every script
  +invocation. You will want to turn this off for nph (non-parsed-headers)
   scripts.
   
   <P>
  -Remember the Alias from the section above? We must use the same Alias here,
  -if you use Location that doesn't have the same Alias defined in srm.conf,
  -the server will fail to locate the script at the filesystem. I'm talking
  -about scripts execution (There are cases where Location is something that's
  +Remember the <STRONG>Alias</STRONG> from the section above? We must use the same Alias here, if you use
  +Location that doesn't have the same Alias defined in srm.conf, the server
  +will fail to locate the script in the filesystem. (We're talking about
  +script execution here -- there are cases where Location is something that's
   being executed by the server itself, without having the corresponding file,
  -like <A HREF="#perl_status">perl-status</A>)
  +like <A HREF="#perl_status">perl-status</A>.)
   
   <P>
   Note that sometimes you will have to add : PerlModule Apache::Registry
  @@ -1218,7 +1269,7 @@
   with mod_perl
   
   <P>
  -A similar location configuration for Apache::PerlRun. (More about
  +Here's a similar location configuration for Apache::PerlRun. (More about
   <A HREF="././porting.html#Apache_PerlRun_a_closer_look">Apache::PerlRun</A>)
   
   <P>
  @@ -1233,10 +1284,9 @@
   </PRE>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="perl_status_location">perl-status location</A></H2></CENTER>
  +<CENTER><H2><A NAME="_perl_status_location">/perl-status location</A></H2></CENTER>
   <P>
  -/perl-status location allows you to see many things about your server. See
  -/<A HREF="././status.html#Configuration">perl-status</A>
  +Adding a directive to enable a <STRONG>/perl-status</STRONG> location allows you to see many things about your server. See /<A HREF="././status.html#Configuration">perl-status</A>
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  @@ -1244,8 +1294,9 @@
   <P>
   Since many times you have to add many perl directives to the config file,
   it can be a good idea to put all of these into one file, so the config file
  -will be cleaner, also you can call <CODE>perl -c perl-startup</CODE>
  -to test the file's syntax. What is takes? Add this line to httpd.conf:
  +will be cleaner, also you can call <STRONG>perl -c perl-startup</STRONG>
  +to test the file's syntax. What does this take? Add this line to
  +httpd.conf:
   
   <P>
   <PRE>    # startup.perl loads all functions that we want to use within mod_perl
  @@ -1280,14 +1331,14 @@
     use CGI ();
     CGI-&gt;compile(':all');
     
  -Note that starting from CGI::VERSION &gt; 2.46, the new method for
  -CGI-&gt;compile is:
  +Note that starting with CGI::VERSION 2.46, the recommended method to
  +precompile the code in CGI.pm is:
   </PRE>
   <P>
   <PRE>  use CGI qw(-compile :all);    
   </PRE>
   <P>
  -But the old method stays for backword compatibility.
  +But the old method is still available for backword compatibility.
   
   <P>
   See also <A HREF="././status.html#Configuration">Apache::Status</A>
  @@ -1296,13 +1347,16 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H2><A NAME="PerlFreshRestart">PerlFreshRestart</A></H2></CENTER>
   <P>
  -To reload <CODE>PerlRequire</CODE>, <CODE>PerlModule</CODE>, other <CODE>use()'d</CODE> modules and flush the Apache::Registry cache
  +To reload <STRONG>PerlRequire</STRONG>, <STRONG>PerlModule</STRONG>, other <CODE>use()'d</CODE> modules and flush the Apache::Registry cache
   on server restart, add:
   
   <P>
   <PRE>  PerlFreshRestart On  
   </PRE>
   <P>
  +Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
  +
  +<P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H2><A NAME="What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A></H2></CENTER>
   <P>
  @@ -1325,7 +1379,7 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H2><A NAME="Perl_behavior_controls">Perl behavior controls</A></H2></CENTER>
   <P>
  -For <CODE>PerlWarn</CODE> and <CODE>PerlTaintCheck</CODE> see <A HREF="././porting.html#Switches_w_T">Switches -w, -T</A>
  +For <STRONG>PerlWarn</STRONG> and <STRONG>PerlTaintCheck</STRONG> see <A HREF="././porting.html#Switches_w_T">Switches -w, -T</A>
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  @@ -1337,17 +1391,15 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Perl_Sections">Perl Sections</A></H1></CENTER>
   <P>
  -With &lt;Perl&gt;&lt;/Perl&gt; sections, it is possible to configure your
  -server entirely in Perl.  
  +With <STRONG>&lt;Perl&gt;&lt;/Perl&gt;</STRONG> sections, it is possible to configure your server entirely in Perl.  
   
   <P>
  -&lt;Perl&gt; sections can contain *any* and as much Perl code as you wish.
  -These sections are compiled into a special package who's symbol table
  -mod_perl can then walk and grind the names and values of Perl
  -variables/structures through the Apache core config gears. Most of the
  -configurations directives can be represented as <CODE>$Scalars</CODE> or
  -@Lists. A <CODE>@List</CODE> inside these sections is simply converted into
  -a single-space delimited string for you inside. Here's an example:  
  +<STRONG>&lt;Perl&gt;</STRONG> sections can contain *any* and as much Perl code as you wish. These
  +sections are compiled into a special package whose symbol table mod_perl
  +can then walk and grind the names and values of Perl variables/structures
  +through the Apache core configuration gears. Most of the configurations
  +directives can be represented as scalars (<STRONG>$scalar</STRONG>) or lists (<STRONG>@list</STRONG>). An <CODE>@List</CODE> inside these sections is simply converted into a space delimited string for
  +you inside. Here's an example:  
   
   <P>
   <PRE>  #httpd.conf
  @@ -1379,26 +1431,28 @@
     };
   </PRE>
   <P>
  -If a Directive can take say, two *or* three arguments you may push strings
  -and the lowest number of arguments will be shifted off the
  -<CODE>@List</CODE> or use array reference to handle any number greater than
  -the minimum for that directive push @Redirect, ``/foo'',
  -``http://www.foo.com/'';
  +If a Directive can take two *or* three arguments you may push strings and
  +the lowest number of arguments will be shifted off the
  +<CODE>@List</CODE> or use array reference to handle any number greater than the minimum for
  +that directive:
   
   <P>
  +<PRE>  push @Redirect, &quot;/foo&quot;, &quot;<A HREF="http://www.foo.com/&quot">http://www.foo.com/&quot</A>;;
  +</PRE>
  +<P>
   <PRE>  push @Redirect, &quot;/imdb&quot;, &quot;<A HREF="http://www.imdb.com/&quot">http://www.imdb.com/&quot</A>;;
   </PRE>
   <P>
   <PRE>  push @Redirect, [qw(temp &quot;/here&quot; &quot;<A HREF="http://www.there.com&quot">http://www.there.com&quot</A>;)];
   </PRE>
   <P>
  -Other section counterparts include %VirtualHost, <CODE>%Directory</CODE>
  -and %Files. 
  +Other section counterparts include <STRONG>%VirtualHost</STRONG>,
  +<STRONG>%Directory</STRONG> and <STRONG>%Files</STRONG>. 
   
   <P>
  -To pass all environmental variables with a single configuration directive
  -to the children rather than listing each one via PassEnv or PerlPassEnv - A
  -&lt;Perl&gt; section could read in a file and:
  +To pass all environment variables to the children with a single
  +configuration directive, rather than listing each one via PassEnv or
  +PerlPassEnv, a <STRONG>&lt;Perl&gt;</STRONG> section could read in a file and:
   
   <P>
   <PRE>  push @PerlPassEnv, [$key =&gt; $val];
  @@ -1410,7 +1464,7 @@
   <PRE>  Apache-&gt;httpd_conf(&quot;PerlPassEnv $key $val&quot;);
   </PRE>
   <P>
  -These are somewhat boring examples, but they should give you the basic
  +These are somewhat simple examples, but they should give you the basic
   idea. You can mix in any Perl code your heart desires. See eg/httpd.conf.pl
   and eg/perl_sections.txt in mod_perl distribution for some examples. 
   
  @@ -1427,10 +1481,11 @@
     &lt;/Perl&gt;
   </PRE>
   <P>
  -Now you may run perl -cx httpd.conf. 
  +Now you may run <STRONG>perl -cx httpd.conf</STRONG>.
   
   <P>
  -To configure this feature build with 'perl Makefile.PL PERL_SECTIONS=1'  
  +To configure this feature build with
  +<STRONG>perl Makefile.PL PERL_SECTIONS=1' </STRONG>
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  @@ -1453,9 +1508,9 @@
   </PRE>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="Script_working_under_cgi_bin_wh">Script working under cgi-bin, when called as mod_perl I see A 'Save-As' prompt</A></H2></CENTER>
  +<CENTER><H2><A NAME="My_script_works_under_cgi_bin_b">My script works under cgi-bin, but when called via mod_perl I see A 'Save-As' prompt</A></H2></CENTER>
   <P>
  -Did you put <CODE>PerlSendHeader On</CODE> in the config part of the &lt;Location foo&gt;&lt;/Location&gt;?
  +Did you put <STRONG>PerlSendHeader On</STRONG> in the config part of the &lt;Location foo&gt;&lt;/Location&gt;?
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  @@ -1473,12 +1528,13 @@
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="Sometimes_script_from_one_virtua">Sometimes script from one virtual host calls the script with the same path from the second virtual host</A></H2></CENTER>
  +<CENTER><H2><A NAME="Sometimes_the_script_from_one_vi">Sometimes the script from one virtual host calls a script with the same path from the second virtual host</A></H2></CENTER>
   <P>
  -It has been a bug before, last fixed in 1.15_01, i.e. if you're running
  +This has been a bug before, last fixed in 1.15_01, i.e. if you're running
   1.15, that could be the problem. The other option to try is set this
   variable in a startup file (PerlRequire):
  -$Apache::Registry::NameWithVirtualHost = 1;
  +<STRONG>$Apache::Registry::NameWithVirtualHost = 1;</STRONG>
  +
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
   
  @@ -1493,7 +1549,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/15/99 
         </FONT>
       </B>
     </TD>
  @@ -1520,7 +1576,7 @@
   <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
   <HTML>
   <HEAD>
  -   <TITLE>mod_perl guide: Server Controlling and Monitoring</TITLE>
  +   <TITLE>mod_perl guide: Controlling and Monitoring the Server</TITLE>
      <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
      <META NAME="Author" CONTENT="Bekman Stas">
      <META NAME="Description" CONTENT="mod_perl,perl,apache">
  @@ -1531,20 +1587,21 @@
   <H1 ALIGN=CENTER>
   <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
   <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
  -Server Controlling and Monitoring</H1>
  +Controlling and Monitoring the Server</H1>
   <HR WIDTH="100%">
   	    <!-- INDEX BEGIN -->
   <P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
   <UL>
   
   	<LI><A HREF="#Restarting_techniques">Restarting techniques</A>
  -	<LI><A HREF="#The_implication_of_sending_TERM_">The implication of sending TERM, HUP, and USR1 to the server and the scripts</A>
  +	<LI><A HREF="#Implications_of_sending_TERM_HU">Implications of sending TERM, HUP, and USR1 to the server</A>
   	<LI><A HREF="#Using_apachectl_to_control_the_s">Using apachectl to control the server</A>
   	<LI><A HREF="#Monitoring_the_Server_A_watchdo">Monitoring the Server. A watchdog.</A>
  -	<LI><A HREF="#Single_Mode_Running">Single Mode Running</A>
  +	<LI><A HREF="#Running_in_Single_Mode">Running in Single Mode</A>
   	<LI><A HREF="#Starting_a_personal_server_for_e">Starting a personal server for each developer</A>
   	<LI><A HREF="#Wrapper_to_emulate_the_server_en">Wrapper to emulate the server environment</A>
   	<LI><A HREF="#Log_Rotation">Log Rotation</A>
  +	<LI><A HREF="#Preventing_from_modperl_process_">Preventing from modperl process to eat up all the disk's space, when it goes wild.</A>
   </UL>
   <!-- INDEX END -->
   
  @@ -1552,9 +1609,9 @@
   <P>
   <CENTER><H1><A NAME="Restarting_techniques">Restarting techniques</A></H1></CENTER>
   <P>
  -In all these techniques you will have to know the server PID (Process ID).
  -The easiest way to find it the PID is to look it up in the httpd.pid file.
  -With my configuration it's
  +All of these techniques require that you know the server PID (Process ID).
  +The easiest way to find the PID is to look it up in the httpd.pid file.
  +With my configuration it exists as
   <CODE>/usr/apps/var/httpd_perl/run/httpd.pid</CODE>. It's easy to discover where to look at, by checking out the httpd.conf
   file. Open the file and locate the entry <CODE>PidFile</CODE>:
   
  @@ -1567,27 +1624,34 @@
   <P>
   <PRE>  % ps auxc | grep httpd_perl
   </PRE>
  +<P>
  +or maybe:
  +
  +<P>
  +<PRE>  % ps -ef | grep httpd_perl
  +</PRE>
   <P>
  -You will receive a list of all httpd_perl (the parent and the children).
  -You are looking after the parent process. If you run it as a root - you
  -will easily locate it, since it belongs to root. If you run the server as
  -user (when you <A HREF="././scenario.html#Is_it_possible_to_install_mod_pe">don't have a root access</A>, most likely all the processes will belong to that user (unless defined
  -different in the httpd.conf), but it's still easy to know 'who is the
  +This will produce a list of all httpd_perl (the parent and the children)
  +processes. You are looking for the parent process. If you run your server
  +as root - you will easily locate it, since it belongs to root. If you run
  +the server as user (when you <A HREF="././scenario.html#Is_it_possible_to_install_mod_pe">don't have a root access</A>, most likely all the processes will belong to that user (unless defined
  +differently in the httpd.conf), but it's still easy to know 'who is the
   parent' -- the one of the smallest size...
   
   <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 PidFile. That is to say you shouldn't ever need to send signals to any
  -process except the parent. There are three signals that you can send the
  -parent: TERM, HUP, and USR1.
  +the <CODE>PidFile</CODE>. That is to say you shouldn't ever need to send signals to any process
  +except the parent. There are three signals that you can send the parent:
  +TERM, HUP, and USR1.
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H1><A NAME="The_implication_of_sending_TERM_">The implication of sending TERM, HUP, and USR1 to the server and the scripts</A></H1></CENTER>
  +<CENTER><H1><A NAME="Implications_of_sending_TERM_HU">Implications of sending TERM, HUP, and USR1 to the server</A></H1></CENTER>
   <P>
  -We will concentrate here at the implications of sending these signals to
  -mod_perl server. For docs about implication on plain apache server see <A
  +We will concentrate here on the implications of sending these signals to a
  +mod_perl-enabled server. For documentation on the implications of sending
  +these signals to a plain Apache server see <A
   HREF="http://www.apache.org/docs/stopping.html">http://www.apache.org/docs/stopping.html</A>
   .
   
  @@ -1595,14 +1659,13 @@
   <P><DT><STRONG><A NAME="item_TERM">TERM Signal: stop now</A></STRONG><DD>
   <P>
   Sending the TERM signal to the parent causes it to immediately attempt to
  -kill off all of its children. It may take several seconds to complete
  -killing off its children. Then the parent itself exits. Any requests in
  -progress are terminated, and no further requests are served. 
  +kill off all of its children. This process may take several seconds to
  +complete, following which the parent itself exits. Any requests in progress
  +are terminated, and no further requests are served. 
   
   <P>
   That's the moment that the accumulated END{} blocks will be executed! Note
  -that if you use Apache::Registry or Apache::PerRun END {} blocks are being
  -executed upon each request (at the end).
  +that if you use <STRONG>Apache::Registry</STRONG> or <STRONG>Apache::PerRun</STRONG>, then END {} blocks are being executed upon each request (at the end).
   
   <P><DT><STRONG><A NAME="item_HUP">HUP Signal: restart now</A></STRONG><DD>
   <P>
  @@ -1612,9 +1675,9 @@
   files. Then it spawns a new set of children and continues serving hits.
   
   <P>
  -Server will rerun its config files. Flush all the compiled and preloaded
  -modules. Rerun any startup files. It's equal to starting a server after it
  -was stopped.
  +The server will reread its config files, flush all the compiled and
  +preloaded modules, and rerun any startup files. It's equivalent to
  +stopping, then restarting a server.
   
   <P>
   Note: If your configuration file has errors in it when you issue a restart
  @@ -1631,34 +1694,37 @@
   immediately. 
   
   <P>
  -The only difference between USR1 and HUP, is that USR1 allows children to
  -complete the request prior to put them to death.
  +The only difference between USR1 and HUP is that USR1 allows children to
  +complete any in-progress request prior to killing them off.
   
   <P>
  -By default, if a server is restarted (ala kill -USR1 `cat logs/httpd.pid`
  -or with HUP signal), Perl scripts and modules are not reloaded. To reload
  -PerlRequire's, PerlModule's, other <CODE>use()'d</CODE> modules and flush
  -the Apache::Registry cache, enable with this command:
  +By default, if a server is restarted (ala <CODE>kill -USR1 `cat
  +logs/httpd.pid`</CODE> or with HUP signal), Perl scripts and modules are not reloaded. To reload <STRONG>PerlRequire</STRONG>'s, <STRONG>PerlModule</STRONG>'s, other <CODE>use()'d</CODE> modules and flush the Apache::Registry
  +cache, enable with this command:
   
   <P>
   <PRE> PerlFreshRestart On              (in httpd.conf) 
   </PRE>
  +<P>
  +Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
  +
   </DL>
   <P>
   It's worth mentioning that restart or termination can sometimes take quite
  -a lot of time. Check out an PERL_DESTRUCT_LEVEL=-1 option during the
  +a lot of time. Check out the PERL_DESTRUCT_LEVEL=-1 option during the
   mod_perl ./Configure stage, which speeds this up and leads to more robust
   operation in the face of problems, like running out of memory. It is only
   usable if no significant cleanup has to be done by perl END{} blocks and
  -DESTROY methods when the child terminates, of course. What's 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.
  +DESTROY methods when the child terminates, of course. What constitutes
  +significant cleanup? Any change of state outside of the current process
  +that would not be handled by the operating system itself. So committing
  +database transactions is significant but closing an ordinary file isn't.
   
   <P>
  -Some folks used to numbers instead of symbolics, if you are looking for
  -these check out your <CODE>kill(3)</CODE> man page, my page points to
  -/usr/include/sys/signal.h . and the relevant entries are:
  +Some folks prefer to specify signals using numerical values, rather than
  +symbolics. If you are looking for these, check out your
  +<CODE>kill(3)</CODE> man page. My page points to
  +<CODE>/usr/include/sys/signal.h</CODE>, the relevant entries are:
   
   <P>
   <PRE>  #define SIGHUP     1    /* hangup, generated when terminal disconnects */ 
  @@ -1669,9 +1735,9 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Using_apachectl_to_control_the_s">Using apachectl to control the server</A></H1></CENTER>
   <P>
  -apache's distribution provides a nice script to control the server. It's
  -called apachectl and it's being installed into the same location with
  -httpd. In our scenario - it's /usr/apps/sbin/httpd_perl/apachectl
  +Apache's distribution provides a nice script to control the server. It's
  +called <STRONG>apachectl</STRONG> and it's installed into the same location with httpd. In our scenario -
  +it's /usr/apps/sbin/httpd_perl/apachectl
   
   <P>
   Start httpd
  @@ -1707,18 +1773,27 @@
   See the next section for the implication of the above calls.
   
   <P>
  -Replace the httpd_perl to httpd_docs in the above calls to get the control
  -over httpd_docs server.
  +Replace 'httpd_perl' with 'httpd_docs' in the above calls to control the
  +httpd_docs server.
   
   <P>
  -There are other options for apachectl, use 'help' option to see them all.
  +There are other options for <STRONG>apachectl</STRONG>, use 'help' option to see them all.
   
   <P>
   It's important to understand that this script is based on the PID file
   which is PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid. If you delete the
  -file by hand - the apachectl will fail to run.
  +file by hand - <STRONG>apachectl</STRONG> will fail to run.
   
   <P>
  +Also, note that <STRONG>apachectl</STRONG> is suitable to use from within your Unix system's startup files so that
  +your web server is automatically restarted upon system reboot. Either copy
  +the <STRONG>apachectl</STRONG> file to the appropriate location (<CODE>/etc/rc.d/rc3.d/S99apache</CODE> works on my RedHat Linux system) or create a symlink with that name
  +pointing to the the canonical location. (If you do this, make certain that
  +the script is writeable only by root -- the startup scripts have root
  +privileges during init processing, and you don't want to be opening any
  +security holes.)
  +
  +<P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Monitoring_the_Server_A_watchdo">Monitoring the Server. A watchdog.</A></H1></CENTER>
   <P>
  @@ -1727,10 +1802,9 @@
   any other critical service you need to run some kind of watchdog.
   
   <P>
  -One simple solution is to use a slightly modified apachectl script which I
  -called apache.watchdog and to put it into the crontab to be called every 30
  -minutes or even every minute - if it's so critical to make sure the server
  -will be up all the time.
  +One simple solution is to use a slightly modified <STRONG>apachectl</STRONG> script which I called apache.watchdog and to put it into the crontab to be
  +called every 30 minutes or even every minute - if it's so critical to make
  +sure the server will be up all the time.
   
   <P>
   Crontab entry:
  @@ -1745,9 +1819,11 @@
   <PRE>  #!/bin/sh
     
     # this script is a watchdog to see whether the server is online
  -  # It tries to restart the server if it's down and sends an email alert to admin
  -  
  -  # admin's email
  +  # It tries to restart the server if it's
  +  # down and sends an email alert to admin 
  +</PRE>
  +<P>
  +<PRE>  # admin's email
     EMAIL=webmaster@somewhere.far
     #EMAIL=root@localhost
     
  @@ -1812,10 +1888,10 @@
     use HTTP::Status;
     
     ###### Config ########
  -  my $test_script_url = &quot;<A HREF="http://www.stas.com:81/perl/test.pl&quot">http://www.stas.com:81/perl/test.pl&quot</A>;;
  -  my $monitor_email = 'root@localhost';
  +  my $test_script_url = '<A HREF="http://www.stas.com:81/perl/test.pl">http://www.stas.com:81/perl/test.pl</A>';
  +  my $monitor_email   = 'root@localhost';
     my $restart_command = '/usr/apps/sbin/httpd_perl/apachectl start';
  -  my $mail_program = &quot;/usr/lib/sendmail -t -n&quot;;   
  +  my $mail_program    = '/usr/lib/sendmail -t -n';
     ######################
     
     $ua  = new LWP::UserAgent;
  @@ -1833,13 +1909,13 @@
     #  print &quot;Status $status\n&quot;;
     
     my $message = ($status == 0) 
  -   ? &quot;Server was down and successfully restarted!&quot; 
  -   : &quot;Server is down. Can't restart.&quot;;
  +              ? &quot;Server was down and successfully restarted!&quot; 
  +              : &quot;Server is down. Can't restart.&quot;;
   </PRE>
   <P>
   <PRE>  my $subject = ($status == 0) 
  -    ? &quot;Attention! Webserver restarted&quot;
  -    : &quot;Attention! Webserver is down. can't restart&quot;;
  +              ? &quot;Attention! Webserver restarted&quot;
  +              : &quot;Attention! Webserver is down. can't restart&quot;;
   </PRE>
   <P>
   <PRE>  # email the monitoring person
  @@ -1870,7 +1946,8 @@
       my($from,$to,$subject,$messagebody) = @_;
   </PRE>
   <P>
  -<PRE>    open MAIL, &quot;|$mail_program&quot; or die &quot;Can't open a pipe to a $mail_program :$!\n&quot;;
  +<PRE>    open MAIL, &quot;|$mail_program&quot;
  +        or die &quot;Can't open a pipe to a $mail_program :$!\n&quot;;
      
       print MAIL &lt;&lt;__END_OF_MAIL__;
     To: $to
  @@ -1897,13 +1974,13 @@
   </PRE>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H1><A NAME="Single_Mode_Running">Single Mode Running</A></H1></CENTER>
  +<CENTER><H1><A NAME="Running_in_Single_Mode">Running in Single Mode</A></H1></CENTER>
   <P>
  -Many times while developing a new code, you will want to run the server in
  -the single process mode. See <A HREF="././porting.html#Sometimes_it_works_Sometimes_Not">Sometimes it works Sometimes Not</A> and <A HREF="././porting.html#Names_collisions_with_Modules_an">Names collisions with Modules and libs</A> 
  +Often while developing new code, you will want to run the server in single
  +process mode. See <A HREF="././porting.html#Sometimes_it_works_Sometimes_Not">Sometimes it works Sometimes Not</A> and <A HREF="././porting.html#Names_collisions_with_Modules_an">Names collisions with Modules and libs</A> 
  +Running in single process mode inhibits the server from ``daemonizing'',
  +allowing you to run it more easily under debugger control.
   
  - 
  -
   <P>
   <PRE>  % /usr/apps/sbin/httpd_perl/httpd_perl -X
   </PRE>
  @@ -1912,34 +1989,33 @@
   the shell you have called it from. So to kill you just kill it with Ctrl-C. 
   
   <P>
  -Note that in -X mode the server will run very slowly on fetching the
  -images. If you use Netscape while your server is running in single-process
  -mode, the ``KeepAlive'' feature gets in the way. Netscape tries to open
  +Note that in -X mode the server will run very slowly while fetching images.
  +If you use Netscape while your server is running in single-process mode,
  +HTTP's ``KeepAlive'' feature gets in the way. Netscape tries to open
   multiple connections and keep them open. Because there is only one server
   process listening, each connection has to time-out before the next
   succeeds. Turn off KeepAlive in httpd.conf to avoid this effect while
  -developing or you can press <STRONG>STOP</STRONG> after a few secs of run (assuming you use the image size params, so the
  +developing or you can press <STRONG>STOP</STRONG> after a few seconds (assuming you use the image size params, so the
   Netscape will be able to render the rest of the page). 
   
   <P>
  -In addition you should know that you will not see any control messages
  -(when running with -X), you generally see in the error_log that the parent
  -server writes: Like ``server started, server stopped and etc''. Since httpd
  --X runs immediately as a child, so there is no controlling parent to write
  -all the status messages.
  +In addition you should know that when running with -X you will not see any
  +control messages that the parent server normally writes to the error_log.
  +(Like ``server started, server stopped and etc''.) Since <CODE>httpd -X</CODE> causes the server to handle all requests itself, without forking any
  +children, there is no controlling parent to write status messages.
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Starting_a_personal_server_for_e">Starting a personal server for each developer</A></H1></CENTER>
   <P>
   If you are the only developer working on the specific server:port - you
  -have no problems, since you have a complete control over the server. Now
  -many times you have a group of developers who need to concurrently develop
  -their mod_perl scripts. It means that each one will want to get the control
  -over the server - to kill it, to run it in single server mode, to restart
  -it again and soon. As well to have to control over the log files and other
  -configuration like MaxClients and etc . You can workaround this problem by
  -preparing a few httpd.conf file and to force each developer to use: 
  +have no problems, since you have a complete control over the server.
  +However, many times you have a group of developers who need to concurrently
  +develop their own mod_perl scripts. This means that each one will want to
  +have control over the server - to kill it, to run it in single server mode,
  +to restart it again, etc., as well to have control over the location of the
  +log files and other configuration settings like <STRONG>MaxClients</STRONG>, etc. You can work around this problem by preparing a few httpd.conf file
  +and forcing each developer to use: 
   
   <P>
   <PRE>  httpd_perl -f /path/to/httpd.conf  
  @@ -1977,39 +2053,38 @@
     &lt;/IfDefine&gt;
   </PRE>
   <P>
  -So what we have achieved with this technique is: A full control over
  -start/stop, number of children, separate error log file, and different
  -port. Now I wouldn't get the call every few minutes - ``Stas, I'm going to
  -restart the server''.
  +What we have achieved with this technique: Full control over start/stop,
  +number of children, separate error log file, and port selection. This saves
  +me from getting called every few minutes - ``Stas, I'm going to restart the
  +server''.
   
   <P>
  -To make things even more easier. (In the above technique, you have to
  -discover the PID of your parent httpd_perl process - written in
  -/usr/apps/var/httpd_perl/run/httpd.pid.userfoo) . We change the apachectl
  -script to do the work for us. We make a copy for each developer called
  -apachectl.username and we change 2 lines in script:
  +To make things even easier. (In the above technique, you have to discover
  +the PID of your parent httpd_perl process - written in
  +/usr/apps/var/httpd_perl/run/httpd.pid.userfoo) . We change the
  +<STRONG>apachectl</STRONG> script to do the work for us. We make a copy for each developer called <STRONG>apachectl.username</STRONG> and we change 2 lines in script:
   
   <P>
   <PRE>  PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid.sbekman
     HTTPD='/usr/apps/sbin/httpd_perl/httpd_perl -Dsbekman'
   </PRE>
   <P>
  -Of course you think you can use only one control file and to know who is
  +Of course you think you can use only one control file and know who is
   calling by using uid, but since you have to be root to start the server -
   it's not so simple. 
   
   <P>
   The last thing was to let developers an option to run in single process
  -node by:
  +mode by:
   
   <P>
   <PRE>  /usr/apps/sbin/httpd_perl/httpd_perl -Dsbekman -X
   </PRE>
   <P>
  -In addition to make life easier we decided to use relative links everywhere
  -in the static docs (including the calls to cgis). You will ask how using
  -the relative link you will get to the right server? Very simple - we have
  -utilized the mod_rewrite to solve our problems:
  +In addition to making life easier, we decided to use relative links
  +everywhere in the static docs (including the calls to CGIs). You may ask
  +how using the relative link you will get to the right server? Very simple -
  +we have utilized the mod_rewrite to solve our problems:
   
   <P>
   In access.conf of the httpd_docs server we have the following code: (you
  @@ -2034,9 +2109,9 @@
     
   </PRE>
   <P>
  -where IP numbers are then IPs of the developers they run the browser at. (I
  -have tried to use REMOTE_USER since we have all the users authenticated but
  -it didn't work for me)
  +where IP numbers are the IPs of the developers' client machine (where they
  +are running their web browser.) (I have tried to use REMOTE_USER since we
  +have all the users authenticated but it didn't work for me)
   
   <P>
   So if I have a relative URL like /perl/test.pl written in some html or even
  @@ -2053,20 +2128,20 @@
   above scheme will not work. There 2 solutions:
   
   <P>
  -First to generate relative URL so it will reuse the technique above, with
  +First, generate relative URL so it will reuse the technique above, with
   redirect (which is transparent for user) but it will not work if you have
   something to POST (redirect looses all the data!).
   
   <P>
  -Second to use a general config module which generates a correct full URL
  +Second, use a general config module which generates a correct full URL
   according to REMOTE_USER, so if $ENV{REMOTE_USER} eq 'sbekman', I return <A
   HREF="http://ourserver.com:8000/perl/">http://ourserver.com:8000/perl/</A>
   as cgi_base_url. Again this will work if the user is authenticated.
   
   <P>
  -All this good for development. It's better to use the full URLs in
  +All this is good for development. It's better to use the full URLs in
   production, since if you have a static form and the Action is relative but
  -the static document sits on another server, pressing form's submit will
  +the static document sits on another server, pressing the form's submit will
   cause a redirect to mod_perl server, but all the form's data will be lost
   during the redirect.
   
  @@ -2074,27 +2149,27 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Wrapper_to_emulate_the_server_en">Wrapper to emulate the server environment</A></H1></CENTER>
   <P>
  -Many times you start off with debugging your script by running it at your
  +Many times you start off debugging your script by running it from your
   favorite shell. Sometimes you encounter a very weird situation when script
  -runs from the shell but dies when called as cgi. The real problem lays in
  -the difference of the environment that's being used by your server and your
  -shell. An example can be a different perl path or having PERL5LIB env
  +runs from the shell but dies when called as a CGI. The real problem lies in
  +the difference between the environment that's being used by your server and
  +your shell. An example can be a different perl path or having PERL5LIB env
   variable which includes paths that aren't in the <CODE>@INC</CODE> of the
   perl compiled with mod_perl server and configured during the startup.
   
   <P>
  -The best thing is to write a wrapper that emulates the exact environment of
  -the server, By deleting first the environment variables like PERL5LIB and
  -calling the same perl that it's being used by the server. Then setting the
  -environment identical to the server's by copying the perl run directives
  -from server startup and config files. It'll also allow you to remove
  -completely the first line of the script - since mod_perl skip it and
  -wrapper knows how to call the script.
  +The best debugging approach is to write a wrapper that emulates the exact
  +environment of the server, by first deleting the environment variables like
  +PERL5LIB and calling the same perl binary that it's being used by the
  +server. Next, set the environment identical to the server's by copying the
  +perl run directives from server startup and config files. It'll also allow
  +you to remove completely the first line of the script - since mod_perl
  +skips it and the wrapper knows how to call the script.
   
   <P>
  -Below is the example of such a script. Note that we force the -wT when we
  +Below is the example of such a script. Note that we force the -Tw when we
   call the real script. (I have also added the ability to pass params, which
  -is not happen when you call the cgi from the web)
  +will not happen when you call the cgi from the web)
   
   <P>
   <PRE>  #!/usr/apps/bin/perl -w    
  @@ -2148,15 +2223,15 @@
     
       # run the cgi from the script's directory
       # Note that we invoke warnings and Taintness ON!!!
  -  system qq{$basedir/bin/perl -I$PERL5LIB -wT $cgi $params};
  +  system qq{$basedir/bin/perl -I$PERL5LIB -Tw $cgi $params};
   </PRE>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Log_Rotation">Log Rotation</A></H1></CENTER>
   <P>
   A little bit off topic but good to know and use with mod_perl where your
  -error_log can grow at 10-100Mb a day rate if your scripts spit lots of
  -warnings...
  +error_log can grow at a 10-100Mb per day rate if your scripts spit out lots
  +of warnings...
   
   <P>
   To rotate the logs do:
  @@ -2171,6 +2246,8 @@
   <P>
   The effect of SIGUSR1 and SIGHUP is detailed in: <A
   HREF="http://www.apache.org/docs/stopping.html">http://www.apache.org/docs/stopping.html</A>
  +
  +<P>
   &lt;META&gt;I tried to kill -USR1 and it didn't reset the logs!!! kill -HUP
   did work&lt;/META&gt; 
   
  @@ -2318,7 +2395,49 @@
   
   </BLOCKQUOTE>
   
  +<P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  +<CENTER><H1><A NAME="Preventing_from_modperl_process_">Preventing from modperl process to eat up all the disk's space, when it goes wild.</A></H1></CENTER>
  +<P>
  +Sometimes an error happens and causes the server to write millions of lines
  +into your error_log file and in a few minutes to put your server down on
  +its knees. For example I get an error <CODE>Callback called exit</CODE>
  +show up in my error_log file many times. The error_log files grows to 300
  +Mbytes in size in a few minutes. You should run a cron job to make sure
  +this doesn't happen and if it does to take care of it. Andreas J. Koenig is
  +running this shell script every minute:
  +
  +<P>
  +<PRE>  S=`ls -s /usr/local/apache/logs/error_log | awk '{print $1}'`
  +  if [ &quot;$S&quot; -gt 100000 ] ; then
  +    /etc/rc.d/init.d/httpd restart
  +    date | /bin/mail -s &quot;error_log $S kB on inx&quot; myemail@domain.com
  +  fi
  +</PRE>
  +<P>
  +It seems that his script will trigger restart every minute, since once the
  +logfile grows to be of 100000 lines, it'll stay of this size, unless you
  +remove or rename it, before you do restart. On my server I run a watchdog
  +every five minutes which restarts the server if it's getting stucked (it
  +always works since when some modperl child process goes wild, the I/O it
  +causes is so heavy that other brother processes can't normally to serve the
  +requests.) See <A HREF="././control.html#Monitoring_the_Server_A_watchdo">Monitoring the Server</A> for more hints.
  +
  +<P>
  +Ulrich Pfeifer told us this: You may also look at the daemontools from D.
  +J. Bernstein - <A
  +HREF="ftp://koobera.math.uic.edu/www/daemontools.html">ftp://koobera.math.uic.edu/www/daemontools.html</A>
  +
  +<P>
  +<PRE>  ,-----
  +  | cyclog writes a log to disk. It automatically synchronizes the log
  +  | every 100KB (by default) to guarantee data integrity after a crash. It
  +  | automatically rotates the log to keep it below 1MB (by default). If
  +  | the disk fills up, cyclog pauses and then tries again, without losing
  +  | any data.
  +  `-----
  +</PRE>
  +<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
   
   <CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
  @@ -2332,7 +2451,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/16/99 
  +	     <BR>Last Modified at 03/16/99 
         </FONT>
       </B>
     </TD>
  @@ -2411,6 +2530,7 @@
   		<LI><A HREF="#Apache_PerlRun_a_closer_look">Apache::PerlRun - a closer look</A>
   	</UL>
   
  +	<LI><A HREF="#Redirecting_Errors_to_Client_ins">Redirecting Errors to Client instead of error_log</A>
   </UL>
   <!-- INDEX END -->
   
  @@ -2843,6 +2963,9 @@
   On.
   
   <P>
  +Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
  +
  +<P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H3><A NAME="END_blocks">END blocks</A></H3></CENTER>
   <P>
  @@ -3393,7 +3516,7 @@
   
   <P>
   <PRE>  # srm.conf
  -  ScriptAlias /cgi-perl/ /home/httpd/cgi/
  +  Alias /cgi-perl/ /home/httpd/cgi/
   </PRE>
   <P>
   <PRE>  # httpd.conf
  @@ -3484,7 +3607,144 @@
   In this case, under mod_perl you wouldn't see 'Foo-&gt;DESTROY' until the
   server shutdown, or your module properly took care of things.
   
  +<P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  +<CENTER><H1><A NAME="Redirecting_Errors_to_Client_ins">Redirecting Errors to Client instead of error_log</A></H1></CENTER>
  +<P>
  +To trap all/most Perl run-time errors and send the output to the client
  +instead of Apache's error log add this line to your script.
  +
  +<P>
  +<PRE>  use CGI::Carp qw(fatalsToBrowser);
  +</PRE>
  +<P>
  +Refer to <CODE>CGI::Carp</CODE> man page for more related info.
  +
  +<P>
  +Also you can write your custom DIE/WARN signal handler. I don't want users
  +to see the error message, but I want it to be emailed to me if it's severe
  +enough. The handler traps various errors and performs accordingly to the
  +defined logic. My handler was written for the modperl environment, but
  +works correctly when is being called from the shell. A stipped version of
  +the code is shown here:
  +
  +<P>
  +<PRE>  # assign the DIE sighandler to call mydie(error_message) whenever a
  +  # die() sub is being called. Can be added anywhere in the code.
  +  $SIG{'__DIE__'} = \&amp;mydie;
  +  
  +  # and the handler itself
  +  sub mydie{
  +    my $why = shift;
  +  
  +    my $UNDER_MOD_PERL = ( (exists $ENV{'GATEWAY_INTERFACE'} 
  +                           and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
  +                         or exists $ENV{'MOD_PERL'} ) ? 1 : 0;
  +  
  +    chomp $why;
  +    my $orig_why = $why;                # an ascii copy for email report
  +  
  +    # handle the shell execution case (so we will not get all the HTML)
  +    print(&quot;Error: $why\n&quot;), exit unless $UNDER_MOD_PERL;
  +  
  +    my $should_email = 0;
  +    my $message = '';
  +  
  +    $why =~ s/[&lt;&amp;&gt;]/&quot;&amp;#&quot;.ord($&amp;).&quot;;&quot;/ge;    # entity escape
  +  
  +    # Now we need to trap various kinds of errors, that come from CGI.pm
  +    # And we don't want these error to be emailed to us, ofcourse -
  +    # these aren't programmatical errors
  +    if ($orig_why =~ /Client attempted to POST (\d+) bytes/o) {
  +  
  +      $message = qq{
  +                  You can not POST messages bigger than 
  +                  @{[1024*$c{max_image_size}]} bytes.&lt;BR&gt;
  +                  You have tried to post $1 bytes&lt;BR&gt;
  +                  If you are trying to upload an image, make sure its size is not 
  +                  bigger than @{[1024*$c{max_image_size}]} bytes.&lt;P&gt;
  +                  Thank you!
  +                 };
  +  
  +    } elsif ($orig_why =~ /Malformed multipart POST/o) {
  +  
  +      $message = qq{
  +                  Have you tried to upload an image in the wrong way?&lt;P&gt;
  +                  To sucessfully upload an image you must use a browser that supports
  +                  image upload and use the 'Browse' button to select that image.
  +                  DO NOT type the path to the image into the upload field.&lt;P&gt;
  +                  Thank you!
  +                 };
  +  
  +    } elsif ($orig_why =~ /closed socket during multipart read/o) {
  +  
  +      $message = qq{
  +                  Have you pressed a 'STOP' button?&lt;BR&gt;
  +                  Please try again!&lt;P&gt;
  +                  Thank you!
  +                 };
  +  
  +    } else {
  +  
  +      $message = qq{
  +                    &lt;B&gt;There is no action to be performed on your side, since
  +                  the error report has been already sent to webmaster. &lt;BR&gt;&lt;P&gt;
  +                  &lt;B&gt;Thank you for your patience!&lt;/B&gt;
  +                 };
  +  
  +      $should_email = 1;
  +    }
  +  
  +  
  +    print qq|Content-type: text/html
  +  
  +  &lt;HTML&gt;&lt;BODY BGCOLOR=&quot;white&quot;&gt;
  +  &lt;B&gt;Oops, An error has happened.&lt;/B&gt;&lt;P&gt;
  +    |;  
  +  
  +    print HTML::warn_box($message);
  +  
  +      # print the tail!
  +    HTML::custom_tail();
  +  
  +      # send email report if appropriate
  +    if ($should_email){
  +  
  +        # import sendmail subs
  +      use Mail ();
  +        # prepare the email error report:
  +      my $subject =&quot;Error Report&quot;;
  +      my $body = qq|
  +    An error has happened:
  +  
  +    $orig_why
  +  
  +      |;
  +  
  +        # send error reports to admin and author
  +      send_mail($c{email}{'admin'},$c{email}{'admin'},$subject,$body);
  +      send_mail($c{email}{'admin'},$c{email}{'author'},$subject,$body);
  +      print STDERR &quot;[&quot;.scalar localtime().&quot;] [SIGDIE] Sending Error Email\n&quot;;
  +    }
  +  
  +       # print to error_log so we will know we've sent
  +    print STDERR &quot;[&quot;.scalar localtime().&quot;] [SIGDIE] $orig_why \n&quot;;
  +  
  +    exit 1;
  +  }                             # end of sub mydie
  +  
  +</PRE>
  +<P>
  +You have noticed that I trap the CGI.pm's <CODE>die()</CODE> calls here, I
  +don't see any reason why my users should see an ugly error messages, but
  +that's the way CGI.pm written. The workaround was to trap them myself.
  +
  +<P>
  +Please note that as of ver 2.49, CGI.pm provides a <CODE>cgi_error()</CODE>
  +method to print the errors and wouldn't <CODE>die()</CODE> unless you want
  +it.
  +
  +<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
   
   <CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
  @@ -3498,7 +3758,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/16/99 
         </FONT>
       </B>
     </TD>
  @@ -4218,6 +4478,8 @@
   	<LI><A HREF="#Callback_called_exit">Callback called exit</A>
   	<LI><A HREF="#Out_of_memory_">Out of memory!</A>
   	<LI><A HREF="#_warn_child_process_30388_did_n">[warn] child process 30388 did not exit, sending another SIGHUP</A>
  +	<LI><A HREF="#RegistryLoader_Cannot_translate">RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl</A>
  +	<LI><A HREF="#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>
   </UL>
   <!-- INDEX END -->
   
  @@ -4523,7 +4785,7 @@
   to your PerlScript, it will allocate the $^M emergency pool and the
   $SIG{__DIE__} handler will call Carp::confess, giving you a stack trace
   which should reveal where the problem is. See the Apache::Resource module
  -for prevention of spinning httpds. 
  +for prevention of spinning httpds.
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  @@ -4536,7 +4798,44 @@
   restart. If your code does not contain and <STRONG>END</STRONG> blocks or <STRONG>DESTROY</STRONG> methods which need to be run during child server shutdown, this destruction
   can be avoided by setting the <EM>PERL_DESTRUCT_LEVEL</EM> environment variable to <CODE>-1</CODE>.
   
  +<P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  +<CENTER><H1><A NAME="RegistryLoader_Cannot_translate">RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl</A></H1></CENTER>
  +<P>
  +<PRE>  RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl
  +              into a real path to the filename. Please refer to the
  +              manpage for more information
  +              or use the complete method's call like:
  +              $r-&gt;handler(uri,filename);\n&quot;;
  +</PRE>
  +<P>
  +This warning shows up when RegistryLoader fails to translate the URI into
  +the corresponding filesystem path. Most of failures happen when one passes
  +a file path instead of URI. (A reminder: /home/httpd/perl/test.pl is a file
  +path, while /perl/test.pl is an URI). In most cases all you have to do is
  +to path something that RegistryLoader expects to get - the URI, but there
  +are more complex cases, RegistryLoader's man page shows how to handle these
  +cases as well (watch for the <CODE>trans()</CODE> sub).
  +
  +<P>
  +<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  +<CENTER><H1><A NAME="Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A></H1></CENTER>
  +<P>
  +Not all Perl modules can survive a reload. PerlFreshRestart does nothing
  +more than:
  +
  +<P>
  +while (my($k,$v) = each %INC) { delete $INC{$k}; require $k; }
  +
  +<P>
  +Besides that, it flushes the Apache::Registry cache, and empties any
  +dynamic stacked handlers (e.g. PerlChildInitHandler).
  +
  +<P>
  +Lots of SegFaults and other problems were reported by users who have turned <CODE>PerlFreshRestart</CODE>  <STRONG>On</STRONG>. Most of them have gone away when it was turned off. It doesn't mean that
  +you shouldn't use it, if it works for you. Just be aware of the dragons...
  +
  +<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
   
   <CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
  @@ -4550,7 +4849,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/16/99 
  +	     <BR>Last Modified at 03/15/99 
         </FONT>
       </B>
     </TD>
  @@ -5293,8 +5592,8 @@
   <P>
   <STRONG>ab</STRONG> is a tool for benchmarking your Apache HTTP server. It is designed to give
   you an impression on how performable is your current Apache installation.
  -This especially shows you how much requests per time your Apache
  -installation is capable to serve.
  +Particularly it shows you how much requests per secs your Apache server is
  +capable to serve. The <STRONG>ab</STRONG> comes bundled with apache source distribution (and it's free :).
   
   <P>
   Lets try it. We will simulate 10 users concurrently requesting the script <CODE>www.you.com:81/test/test.pl</CODE> which a very light one. Each one does it for 10 times.
  @@ -6107,7 +6406,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/15/99 
         </FONT>
       </B>
     </TD>
  @@ -6156,6 +6455,7 @@
   
   		<LI><A HREF="#Configuration">Configuration</A>
   		<LI><A HREF="#Usage">Usage</A>
  +		<LI><A HREF="#Compiled_Registry_Scripts_sectio">Compiled Registry Scripts section seems to be empty.</A>
   	</UL>
   
   </UL>
  @@ -6240,7 +6540,18 @@
   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...
   
  +<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.
  +
  +<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
   
   <CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
  @@ -6254,7 +6565,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/16/99 
  +	     <BR>Last Modified at 03/15/99 
         </FONT>
       </B>
     </TD>
  @@ -6300,6 +6611,7 @@
   
   	<LI><A HREF="#Sometimes_script_works_Sometime">Sometimes script works, Sometimes Not</A>
   	<LI><A HREF="#Debug_Tracing">Debug Tracing</A>
  +	<LI><A HREF="#Getting_some_decent_debug_info_w">Getting some decent debug info when running under mod_perl</A>
   </UL>
   <!-- INDEX END -->
   
  @@ -6342,6 +6654,27 @@
   
   <P>
   PerlSetVar MOD_PERL_TRACE d
  +
  +<P>
  +<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  +<CENTER><H1><A NAME="Getting_some_decent_debug_info_w">Getting some decent debug info when running under mod_perl</A></H1></CENTER>
  +<P>
  +As many of you know, the interactive Perl debugger does not run under
  +Apache/mod_perl (yet). However, Dean Gaudet made the discovery last night
  +of the NonStop option. This enables us to get some decent debug info when
  +running under mod_perl. For example, before starting the server:
  +
  +<P>
  +<PRE>  % setenv PERL5OPT -d
  +  % setenv PERLDB_OPTS &quot;NonStop=1 LineInfo=db.out AutoTrace=1 frame=2&quot;
  +</PRE>
  +<P>
  +Now watch db.out for line:filename info. This is most useful for tracking
  +those core dumps that normally leave us guessing, even with a stacktrace
  +from gdb. db.out will show you what Perl code triggered the core. `man
  +perldebug' for more PERLDB_OPTS. Note, Perl will ignore PERL5OPT if
  +PerlTaintCheck is On.
  +
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
   
  @@ -6356,7 +6689,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/13/99 
         </FONT>
       </B>
     </TD>
  @@ -6400,7 +6733,6 @@
   <P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
   <UL>
   
  -	<LI><A HREF="#Redirecting_Errors_to_Client_ins">Redirecting Errors to Client instead of error_log</A>
   	<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="#More_on_relative_paths">More on relative paths</A>
  @@ -6410,16 +6742,6 @@
   
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P>
  -<CENTER><H1><A NAME="Redirecting_Errors_to_Client_ins">Redirecting Errors to Client instead of error_log</A></H1></CENTER>
  -<P>
  -To trap all/most Perl run-time errors and send the output to the client
  -instead of Apache's error log add this line to your script.
  -
  -<P>
  -<PRE>  use CGI::Carp qw(fatalsToBrowser);
  -</PRE>
  -<P>
  -<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <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
  @@ -6578,7 +6900,16 @@
     }
     
     
  +=head1 Accessing variables from the caller's package
   </PRE>
  +<P>
  +Sometimes you want to access some variables from the caller's package. One
  +way is to do:
  +
  +<P>
  +<PRE>  my $caller = caller;
  +  print qq[$caller --- ${&quot;${caller}::var&quot;}];
  +</PRE>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
   
  @@ -6593,7 +6924,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/16/99 
         </FONT>
       </B>
     </TD>
  
  
  
  1.8       +113 -95   modperl-site/guide/config.html
  
  Index: config.html
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/config.html,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- config.html	1999/01/23 18:06:53	1.7
  +++ config.html	1999/03/16 08:20:14	1.8
  @@ -18,16 +18,16 @@
   <P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
   <UL>
   
  -	<LI><A HREF="#configuration">configuration</A>
  +	<LI><A HREF="#Configuration">Configuration</A>
   	<UL>
   
  -		<LI><A HREF="#aliases_configurations">aliases configurations</A>
  +		<LI><A HREF="#Alias_Configurations">Alias Configurations</A>
   	</UL>
   
  -	<LI><A HREF="#Configuration_of_Location">Configuration of Location</A>
  +	<LI><A HREF="#Location_Configuration">Location Configuration </A>
   	<UL>
   
  -		<LI><A HREF="#perl_status_location">perl-status location </A>
  +		<LI><A HREF="#_perl_status_location">/perl-status location </A>
   		<LI><A HREF="#perl_startup_file">perl-startup file</A>
   		<LI><A HREF="#PerlFreshRestart">PerlFreshRestart</A>
   		<LI><A HREF="#What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A>
  @@ -41,10 +41,10 @@
   	<UL>
   
   		<LI><A HREF="#My_cgi_perl_code_is_being_return">My cgi/perl code is being returned as a plain text instead of being executed by the webserver?</A>
  -		<LI><A HREF="#Script_working_under_cgi_bin_wh">Script working under cgi-bin, when called as mod_perl I see A 'Save-As' prompt</A>
  +		<LI><A HREF="#My_script_works_under_cgi_bin_b">My script works under cgi-bin, but when called via mod_perl I see A 'Save-As' prompt</A>
   		<LI><A HREF="#Is_there_a_way_to_provide_a_diff">Is there a way to provide a different startup.pl file for each individual virtual host</A>
   		<LI><A HREF="#Is_there_a_way_to_modify_INC_on">Is there a way to modify @INC on a per-virtual-host basis. </A>
  -		<LI><A HREF="#Sometimes_script_from_one_virtua">Sometimes script from one virtual host calls the script with the same path from the second virtual host</A>
  +		<LI><A HREF="#Sometimes_the_script_from_one_vi">Sometimes the script from one virtual host calls a script with the same path from the second virtual host</A>
   	</UL>
   
   </UL>
  @@ -52,74 +52,86 @@
   
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P>
  -<CENTER><H1><A NAME="configuration">configuration</A></H1></CENTER>
  +<CENTER><H1><A NAME="Configuration">Configuration</A></H1></CENTER>
   <P>
  -You have just installed the new apache/mod_perl server. Now you have to
  -configure server's configuration files. To learn how to configure the
  -apache's config files, please the use the apache's documentation or just
  -open the files in conf directory and follow the instructions in these files
  -- they are self explainable...
  +The next step after building and installing your new mod_perl-enabled
  +Apache server, is to configure the server's configuration files. To learn
  +how to modify Apache's configuration files, please refer to the
  +documentation included with the Apache distribution. or just view the files
  +in conf directory and follow the instructions in these files - the embedded
  +comments within the file do a good job of explaining the options.
   
   <P>
  -Before you start configuration of mod_perl, configure the apache, and see
  -that it works. When done, come back to continue...
  +Before you start the mod_perl configuration, configure Apache, and see that
  +it works. When done, return here to continue...
   
   <P>
  +[ Note that prior to version 1.3.4, the default Apache install used three
  +configuration files -- <STRONG>httpd.conf</STRONG>, <STRONG>srm.conf</STRONG>, and <STRONG>access.conf</STRONG>. The 1.3.4 version began distributing the configuration directives in a
  +single file -- <STRONG>httpd.conf</STRONG>. The remainder of this chapter refers to the location of the configuration
  +directives using their historical location. ]
  +
  +<P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="aliases_configurations">aliases configurations</A></H2></CENTER>
  +<CENTER><H2><A NAME="Alias_Configurations">Alias Configurations</A></H2></CENTER>
   <P>
  -OK, first thing you will want to specify the location from where all
  -mod_perl scripts will be called.
  +First, you need to specify the location where all mod_perl scripts will be
  +located.
   
   <P>
  -in srm.conf add:
  +Add the following configuration directives to srm.conf:
   
   <P>
   <PRE>    # plain cgi-bin:
     ScriptAlias /cgi-bin/ /usr/apps/myproject/cgi/
       
       # Apache::Registry mode
  -  ScriptAlias /perl/ /usr/apps/myproject/cgi/
  +  Alias /perl/ /usr/apps/myproject/cgi/
   </PRE>
   <P>
   <PRE>    # Apache::PerlRun mode
  -  ScriptAlias /cgi-perl/ /usr/apps/myproject/cgi/
  +  Alias /cgi-perl/ /usr/apps/myproject/cgi/
   </PRE>
   <P>
  -Alias allows the server to locate the script that was called at the
  -filesystem.
  +Alias provides a mapping of URL to filesystem object.
   
   <P>
  -Alias is the start of the URL path to the script you call, like when you
  -fetch <A
  -HREF="http://www.you.com/perl/test.pl">http://www.you.com/perl/test.pl</A>
  -, server will look for the file test.pl at /usr/apps/myproject/cgi but
  -execute it as a Apache::Registry script, after you set this (see the next
  -section). <A
  -HREF="http://www.you.com/perl/test.pl">http://www.you.com/perl/test.pl</A>
  -will be mapped to /usr/apps/myproject/cgi/test.pl . Basically you can have
  -all your cgis located at the same place at filesystem, and to call the same
  -script in any of 3 modes by just replacing the first directory of the URL
  -(cgi-bin|perl|cgi-perl) - Isn't that cool? (That's the configuration you
  -see above - all 3 ScriptAliases point to the same directory at the
  -filesystem, but ofcourse they can be different). If something is going
  -wrong with your mod_perl you can easily call the scripts in the mod_cgi
  -mode without changing the script (in most cases) but only the URL to call
  -it, and then to put it back!!!
  +Alias defines the start of the URL path to the script you are referencing.
  +For example, using the above configuration, fetching
  +<STRONG>http://www.you.com/perl/test.pl</STRONG>, will cause the server to look for the file <STRONG>test.pl</STRONG> at <STRONG>/usr/apps/myproject/cgi</STRONG>, and execute it as an <STRONG>Apache::Registry</STRONG> script. The URL
  +<STRONG>http://www.you.com/perl/test.pl</STRONG> will be mapped to
  +<STRONG>/usr/apps/myproject/cgi/test.pl</STRONG>. This means you can have all your CGIs located at the same place at
  +filesystem, and call the script in any of three modes simply by changing
  +the directory name component of the URL (cgi-bin|perl|cgi-perl) - isn't
  +that cool? (That's the configuration you see above - all three Aliases
  +point to the same directory within your filesystem, but of course they can
  +be different). If your script doesn't seem to be working while running
  +under mod_perl, you can easily call the script in straight mod_cgi mode
  +without making any script changes (in most cases), but rather by changing
  +the URL you invoke it by.
  +
  +<P>
  +FYI: for modperl ScriptAlias is the same thing as an Alias command +
  +'sethandler cgi-handler'. The latter will be overwritten if you enable
  +Apache::Registry. In other words, ``ScriptAlias does not work for
  +mod_perl'', it only appears to work when the additional config is in there.
  +If the Apache::Registry config came before the ScriptAlias, scripts would
  +be run under mod_cgi. While handy, ScriptAlias is a known kludge, always
  +better to use `Alias' and `SetHandler'.
   
   <P>
   Of course you can choose any other alias (you will use it later in
  -http.conf), you can choose to use all 3 modes or only one of these (It's
  -unlikely to run plain cgi-bin scripts from mod_perl server - the price is
  -too high, you better run these at plain apache server. See
  -<A HREF="././scenario.html#Making_a_strategic_decision">Real World scenario</A> for details)
  +http.conf), you can choose to use all three modes or only one of these
  +(It's undesirable to run plain cgi-bin scripts from a mod_perl-enabled
  +server - the price is too high, it's better to run these on plain Apache
  +server. See <A HREF="././scenario.html#Making_a_strategic_decision">Real World scenario</A> for details.)
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H1><A NAME="Configuration_of_Location">Configuration of Location</A></H1></CENTER>
  +<CENTER><H1><A NAME="Location_Configuration">Location Configuration</A></H1></CENTER>
   <P>
  -Now we work with httpd.conf, I add all the mod_perl stuff at the end of
  -file, after the native apache configurations finish.
  +Now we will work with the httpd.conf file. I add all the mod_perl stuff at
  +the end of the file, after the native Apache configurations.
   
   <P>
   First we add:
  @@ -135,23 +147,22 @@
     &lt;/Location&gt;
   </PRE>
   <P>
  -This location's configuration makes all scripts that has been called with
  -/perl path at the beginning to be executed under
  -<STRONG>Apache::Registry</STRONG> module and as cgi (so the <CODE>ExecCGI</CODE>, if you omit this option the script will be just printed to the caller's
  -browser as a plain text or will trigger the 'Save-As' window). 
  +This configuration causes all scripts that are called with a <STRONG>/perl</STRONG> path prefix to be executed under the
  +<STRONG>Apache::Registry</STRONG> module and as a CGI (so the <STRONG>ExecCGI</STRONG>, if you omit this option the script will be printed to the caller's
  +browser as a plain text or will possibly will trigger a 'Save-As' window). 
   
   <P>
  -<CODE>PerlSendHeader On</CODE> tells the server to send an HTTP header to the browser, on every script
  -invocation. You will want to turn it off for you nph (non-parsed-headers)
  +<STRONG>PerlSendHeader On</STRONG> tells the server to send an HTTP header to the browser on every script
  +invocation. You will want to turn this off for nph (non-parsed-headers)
   scripts.
   
   <P>
  -Remember the Alias from the section above? We must use the same Alias here,
  -if you use Location that doesn't have the same Alias defined in srm.conf,
  -the server will fail to locate the script at the filesystem. I'm talking
  -about scripts execution (There are cases where Location is something that's
  +Remember the <STRONG>Alias</STRONG> from the section above? We must use the same Alias here, if you use
  +Location that doesn't have the same Alias defined in srm.conf, the server
  +will fail to locate the script in the filesystem. (We're talking about
  +script execution here -- there are cases where Location is something that's
   being executed by the server itself, without having the corresponding file,
  -like <A HREF="#perl_status">perl-status</A>)
  +like <A HREF="#perl_status">perl-status</A>.)
   
   <P>
   Note that sometimes you will have to add : PerlModule Apache::Registry
  @@ -166,7 +177,7 @@
   with mod_perl
   
   <P>
  -A similar location configuration for Apache::PerlRun. (More about
  +Here's a similar location configuration for Apache::PerlRun. (More about
   <A HREF="././porting.html#Apache_PerlRun_a_closer_look">Apache::PerlRun</A>)
   
   <P>
  @@ -181,10 +192,9 @@
   </PRE>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="perl_status_location">perl-status location</A></H2></CENTER>
  +<CENTER><H2><A NAME="_perl_status_location">/perl-status location</A></H2></CENTER>
   <P>
  -/perl-status location allows you to see many things about your server. See
  -/<A HREF="././status.html#Configuration">perl-status</A>
  +Adding a directive to enable a <STRONG>/perl-status</STRONG> location allows you to see many things about your server. See /<A HREF="././status.html#Configuration">perl-status</A>
   
   
   
  @@ -194,8 +204,9 @@
   <P>
   Since many times you have to add many perl directives to the config file,
   it can be a good idea to put all of these into one file, so the config file
  -will be cleaner, also you can call <CODE>perl -c perl-startup</CODE>
  -to test the file's syntax. What is takes? Add this line to httpd.conf:
  +will be cleaner, also you can call <STRONG>perl -c perl-startup</STRONG>
  +to test the file's syntax. What does this take? Add this line to
  +httpd.conf:
   
   <P>
   <PRE>    # startup.perl loads all functions that we want to use within mod_perl
  @@ -230,14 +241,14 @@
     use CGI ();
     CGI-&gt;compile(':all');
     
  -Note that starting from CGI::VERSION &gt; 2.46, the new method for
  -CGI-&gt;compile is:
  +Note that starting with CGI::VERSION 2.46, the recommended method to
  +precompile the code in CGI.pm is:
   </PRE>
   <P>
   <PRE>  use CGI qw(-compile :all);    
   </PRE>
   <P>
  -But the old method stays for backword compatibility.
  +But the old method is still available for backword compatibility.
   
   <P>
   See also <A HREF="././status.html#Configuration">Apache::Status</A>
  @@ -248,13 +259,16 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H2><A NAME="PerlFreshRestart">PerlFreshRestart</A></H2></CENTER>
   <P>
  -To reload <CODE>PerlRequire</CODE>, <CODE>PerlModule</CODE>, other <CODE>use()'d</CODE> modules and flush the Apache::Registry cache
  +To reload <STRONG>PerlRequire</STRONG>, <STRONG>PerlModule</STRONG>, other <CODE>use()'d</CODE> modules and flush the Apache::Registry cache
   on server restart, add:
   
   <P>
   <PRE>  PerlFreshRestart On  
   </PRE>
   <P>
  +Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
  +
  +<P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H2><A NAME="What_modules_should_you_add_to_t">What modules should you add to the startup file and why.</A></H2></CENTER>
   <P>
  @@ -279,7 +293,7 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H2><A NAME="Perl_behavior_controls">Perl behavior controls</A></H2></CENTER>
   <P>
  -For <CODE>PerlWarn</CODE> and <CODE>PerlTaintCheck</CODE> see <A HREF="././porting.html#Switches_w_T">Switches -w, -T</A>
  +For <STRONG>PerlWarn</STRONG> and <STRONG>PerlTaintCheck</STRONG> see <A HREF="././porting.html#Switches_w_T">Switches -w, -T</A>
   
   
   
  @@ -295,17 +309,15 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Perl_Sections">Perl Sections</A></H1></CENTER>
   <P>
  -With &lt;Perl&gt;&lt;/Perl&gt; sections, it is possible to configure your
  -server entirely in Perl.  
  +With <STRONG>&lt;Perl&gt;&lt;/Perl&gt;</STRONG> sections, it is possible to configure your server entirely in Perl.  
   
   <P>
  -&lt;Perl&gt; sections can contain *any* and as much Perl code as you wish.
  -These sections are compiled into a special package who's symbol table
  -mod_perl can then walk and grind the names and values of Perl
  -variables/structures through the Apache core config gears. Most of the
  -configurations directives can be represented as <CODE>$Scalars</CODE> or
  -@Lists. A <CODE>@List</CODE> inside these sections is simply converted into
  -a single-space delimited string for you inside. Here's an example:  
  +<STRONG>&lt;Perl&gt;</STRONG> sections can contain *any* and as much Perl code as you wish. These
  +sections are compiled into a special package whose symbol table mod_perl
  +can then walk and grind the names and values of Perl variables/structures
  +through the Apache core configuration gears. Most of the configurations
  +directives can be represented as scalars (<STRONG>$scalar</STRONG>) or lists (<STRONG>@list</STRONG>). An <CODE>@List</CODE> inside these sections is simply converted into a space delimited string for
  +you inside. Here's an example:  
   
   <P>
   <PRE>  #httpd.conf
  @@ -337,26 +349,28 @@
     };
   </PRE>
   <P>
  -If a Directive can take say, two *or* three arguments you may push strings
  -and the lowest number of arguments will be shifted off the
  -<CODE>@List</CODE> or use array reference to handle any number greater than
  -the minimum for that directive push @Redirect, ``/foo'',
  -``http://www.foo.com/'';
  +If a Directive can take two *or* three arguments you may push strings and
  +the lowest number of arguments will be shifted off the
  +<CODE>@List</CODE> or use array reference to handle any number greater than the minimum for
  +that directive:
   
   <P>
  +<PRE>  push @Redirect, &quot;/foo&quot;, &quot;<A HREF="http://www.foo.com/&quot">http://www.foo.com/&quot</A>;;
  +</PRE>
  +<P>
   <PRE>  push @Redirect, &quot;/imdb&quot;, &quot;<A HREF="http://www.imdb.com/&quot">http://www.imdb.com/&quot</A>;;
   </PRE>
   <P>
   <PRE>  push @Redirect, [qw(temp &quot;/here&quot; &quot;<A HREF="http://www.there.com&quot">http://www.there.com&quot</A>;)];
   </PRE>
   <P>
  -Other section counterparts include %VirtualHost, <CODE>%Directory</CODE>
  -and %Files. 
  +Other section counterparts include <STRONG>%VirtualHost</STRONG>,
  +<STRONG>%Directory</STRONG> and <STRONG>%Files</STRONG>. 
   
   <P>
  -To pass all environmental variables with a single configuration directive
  -to the children rather than listing each one via PassEnv or PerlPassEnv - A
  -&lt;Perl&gt; section could read in a file and:
  +To pass all environment variables to the children with a single
  +configuration directive, rather than listing each one via PassEnv or
  +PerlPassEnv, a <STRONG>&lt;Perl&gt;</STRONG> section could read in a file and:
   
   <P>
   <PRE>  push @PerlPassEnv, [$key =&gt; $val];
  @@ -368,7 +382,7 @@
   <PRE>  Apache-&gt;httpd_conf(&quot;PerlPassEnv $key $val&quot;);
   </PRE>
   <P>
  -These are somewhat boring examples, but they should give you the basic
  +These are somewhat simple examples, but they should give you the basic
   idea. You can mix in any Perl code your heart desires. See eg/httpd.conf.pl
   and eg/perl_sections.txt in mod_perl distribution for some examples. 
   
  @@ -385,11 +399,14 @@
     &lt;/Perl&gt;
   </PRE>
   <P>
  -Now you may run perl -cx httpd.conf. 
  +Now you may run <STRONG>perl -cx httpd.conf</STRONG>.
   
   <P>
  -To configure this feature build with 'perl Makefile.PL PERL_SECTIONS=1'  
  +To configure this feature build with
  +<STRONG>perl Makefile.PL PERL_SECTIONS=1' </STRONG>
  +
   
  +
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="General_pitfalls">General pitfalls</A></H1></CENTER>
  @@ -411,9 +428,9 @@
   </PRE>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="Script_working_under_cgi_bin_wh">Script working under cgi-bin, when called as mod_perl I see A 'Save-As' prompt</A></H2></CENTER>
  +<CENTER><H2><A NAME="My_script_works_under_cgi_bin_b">My script works under cgi-bin, but when called via mod_perl I see A 'Save-As' prompt</A></H2></CENTER>
   <P>
  -Did you put <CODE>PerlSendHeader On</CODE> in the config part of the &lt;Location foo&gt;&lt;/Location&gt;?
  +Did you put <STRONG>PerlSendHeader On</STRONG> in the config part of the &lt;Location foo&gt;&lt;/Location&gt;?
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  @@ -431,12 +448,13 @@
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="Sometimes_script_from_one_virtua">Sometimes script from one virtual host calls the script with the same path from the second virtual host</A></H2></CENTER>
  +<CENTER><H2><A NAME="Sometimes_the_script_from_one_vi">Sometimes the script from one virtual host calls a script with the same path from the second virtual host</A></H2></CENTER>
   <P>
  -It has been a bug before, last fixed in 1.15_01, i.e. if you're running
  +This has been a bug before, last fixed in 1.15_01, i.e. if you're running
   1.15, that could be the problem. The other option to try is set this
   variable in a startup file (PerlRequire):
  -$Apache::Registry::NameWithVirtualHost = 1;
  +<STRONG>$Apache::Registry::NameWithVirtualHost = 1;</STRONG>
  +
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
   
  @@ -451,7 +469,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/15/99 
         </FONT>
       </B>
     </TD>
  
  
  
  1.9       +187 -122  modperl-site/guide/control.html
  
  Index: control.html
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/control.html,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- control.html	1999/01/23 18:06:53	1.8
  +++ control.html	1999/03/16 08:20:14	1.9
  @@ -1,7 +1,7 @@
   <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
   <HTML>
   <HEAD>
  -   <TITLE>mod_perl guide: Server Controlling and Monitoring</TITLE>
  +   <TITLE>mod_perl guide: Controlling and Monitoring the Server</TITLE>
      <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
      <META NAME="Author" CONTENT="Bekman Stas">
      <META NAME="Description" CONTENT="mod_perl,perl,apache">
  @@ -12,20 +12,21 @@
   <H1 ALIGN=CENTER>
   <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
   <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon" BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
  -Server Controlling and Monitoring</H1>
  +Controlling and Monitoring the Server</H1>
   <HR WIDTH="100%">
   	    <!-- INDEX BEGIN -->
   <P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
   <UL>
   
   	<LI><A HREF="#Restarting_techniques">Restarting techniques</A>
  -	<LI><A HREF="#The_implication_of_sending_TERM_">The implication of sending TERM, HUP, and USR1 to the server and the scripts</A>
  +	<LI><A HREF="#Implications_of_sending_TERM_HU">Implications of sending TERM, HUP, and USR1 to the server</A>
   	<LI><A HREF="#Using_apachectl_to_control_the_s">Using apachectl to control the server</A>
   	<LI><A HREF="#Monitoring_the_Server_A_watchdo">Monitoring the Server. A watchdog.</A>
  -	<LI><A HREF="#Single_Mode_Running">Single Mode Running</A>
  +	<LI><A HREF="#Running_in_Single_Mode">Running in Single Mode</A>
   	<LI><A HREF="#Starting_a_personal_server_for_e">Starting a personal server for each developer</A>
   	<LI><A HREF="#Wrapper_to_emulate_the_server_en">Wrapper to emulate the server environment</A>
   	<LI><A HREF="#Log_Rotation">Log Rotation</A>
  +	<LI><A HREF="#Preventing_from_modperl_process_">Preventing from modperl process to eat up all the disk's space, when it goes wild.</A>
   </UL>
   <!-- INDEX END -->
   
  @@ -33,9 +34,9 @@
   <P>
   <CENTER><H1><A NAME="Restarting_techniques">Restarting techniques</A></H1></CENTER>
   <P>
  -In all these techniques you will have to know the server PID (Process ID).
  -The easiest way to find it the PID is to look it up in the httpd.pid file.
  -With my configuration it's
  +All of these techniques require that you know the server PID (Process ID).
  +The easiest way to find the PID is to look it up in the httpd.pid file.
  +With my configuration it exists as
   <CODE>/usr/apps/var/httpd_perl/run/httpd.pid</CODE>. It's easy to discover where to look at, by checking out the httpd.conf
   file. Open the file and locate the entry <CODE>PidFile</CODE>:
   
  @@ -49,26 +50,33 @@
   <PRE>  % ps auxc | grep httpd_perl
   </PRE>
   <P>
  -You will receive a list of all httpd_perl (the parent and the children).
  -You are looking after the parent process. If you run it as a root - you
  -will easily locate it, since it belongs to root. If you run the server as
  -user (when you <A HREF="././scenario.html#Is_it_possible_to_install_mod_pe">don't have a root access</A>, most likely all the processes will belong to that user (unless defined
  -different in the httpd.conf), but it's still easy to know 'who is the
  +or maybe:
  +
  +<P>
  +<PRE>  % ps -ef | grep httpd_perl
  +</PRE>
  +<P>
  +This will produce a list of all httpd_perl (the parent and the children)
  +processes. You are looking for the parent process. If you run your server
  +as root - you will easily locate it, since it belongs to root. If you run
  +the server as user (when you <A HREF="././scenario.html#Is_it_possible_to_install_mod_pe">don't have a root access</A>, most likely all the processes will belong to that user (unless defined
  +differently in the httpd.conf), but it's still easy to know 'who is the
   parent' -- the one of the smallest size...
   
   <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 PidFile. That is to say you shouldn't ever need to send signals to any
  -process except the parent. There are three signals that you can send the
  -parent: TERM, HUP, and USR1.
  +the <CODE>PidFile</CODE>. That is to say you shouldn't ever need to send signals to any process
  +except the parent. There are three signals that you can send the parent:
  +TERM, HUP, and USR1.
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H1><A NAME="The_implication_of_sending_TERM_">The implication of sending TERM, HUP, and USR1 to the server and the scripts</A></H1></CENTER>
  +<CENTER><H1><A NAME="Implications_of_sending_TERM_HU">Implications of sending TERM, HUP, and USR1 to the server</A></H1></CENTER>
   <P>
  -We will concentrate here at the implications of sending these signals to
  -mod_perl server. For docs about implication on plain apache server see <A
  +We will concentrate here on the implications of sending these signals to a
  +mod_perl-enabled server. For documentation on the implications of sending
  +these signals to a plain Apache server see <A
   HREF="http://www.apache.org/docs/stopping.html">http://www.apache.org/docs/stopping.html</A>
   .
   
  @@ -76,14 +84,13 @@
   <P><DT><STRONG><A NAME="item_TERM">TERM Signal: stop now</A></STRONG><DD>
   <P>
   Sending the TERM signal to the parent causes it to immediately attempt to
  -kill off all of its children. It may take several seconds to complete
  -killing off its children. Then the parent itself exits. Any requests in
  -progress are terminated, and no further requests are served. 
  +kill off all of its children. This process may take several seconds to
  +complete, following which the parent itself exits. Any requests in progress
  +are terminated, and no further requests are served. 
   
   <P>
   That's the moment that the accumulated END{} blocks will be executed! Note
  -that if you use Apache::Registry or Apache::PerRun END {} blocks are being
  -executed upon each request (at the end).
  +that if you use <STRONG>Apache::Registry</STRONG> or <STRONG>Apache::PerRun</STRONG>, then END {} blocks are being executed upon each request (at the end).
   
   <P><DT><STRONG><A NAME="item_HUP">HUP Signal: restart now</A></STRONG><DD>
   <P>
  @@ -93,9 +100,9 @@
   files. Then it spawns a new set of children and continues serving hits.
   
   <P>
  -Server will rerun its config files. Flush all the compiled and preloaded
  -modules. Rerun any startup files. It's equal to starting a server after it
  -was stopped.
  +The server will reread its config files, flush all the compiled and
  +preloaded modules, and rerun any startup files. It's equivalent to
  +stopping, then restarting a server.
   
   <P>
   Note: If your configuration file has errors in it when you issue a restart
  @@ -112,34 +119,37 @@
   immediately. 
   
   <P>
  -The only difference between USR1 and HUP, is that USR1 allows children to
  -complete the request prior to put them to death.
  +The only difference between USR1 and HUP is that USR1 allows children to
  +complete any in-progress request prior to killing them off.
   
   <P>
  -By default, if a server is restarted (ala kill -USR1 `cat logs/httpd.pid`
  -or with HUP signal), Perl scripts and modules are not reloaded. To reload
  -PerlRequire's, PerlModule's, other <CODE>use()'d</CODE> modules and flush
  -the Apache::Registry cache, enable with this command:
  +By default, if a server is restarted (ala <CODE>kill -USR1 `cat
  +logs/httpd.pid`</CODE> or with HUP signal), Perl scripts and modules are not reloaded. To reload <STRONG>PerlRequire</STRONG>'s, <STRONG>PerlModule</STRONG>'s, other <CODE>use()'d</CODE> modules and flush the Apache::Registry
  +cache, enable with this command:
   
   <P>
   <PRE> PerlFreshRestart On              (in httpd.conf) 
   </PRE>
  +<P>
  +Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
  +
   </DL>
   <P>
   It's worth mentioning that restart or termination can sometimes take quite
  -a lot of time. Check out an PERL_DESTRUCT_LEVEL=-1 option during the
  +a lot of time. Check out the PERL_DESTRUCT_LEVEL=-1 option during the
   mod_perl ./Configure stage, which speeds this up and leads to more robust
   operation in the face of problems, like running out of memory. It is only
   usable if no significant cleanup has to be done by perl END{} blocks and
  -DESTROY methods when the child terminates, of course. What's 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.
  +DESTROY methods when the child terminates, of course. What constitutes
  +significant cleanup? Any change of state outside of the current process
  +that would not be handled by the operating system itself. So committing
  +database transactions is significant but closing an ordinary file isn't.
   
   <P>
  -Some folks used to numbers instead of symbolics, if you are looking for
  -these check out your <CODE>kill(3)</CODE> man page, my page points to
  -/usr/include/sys/signal.h . and the relevant entries are:
  +Some folks prefer to specify signals using numerical values, rather than
  +symbolics. If you are looking for these, check out your
  +<CODE>kill(3)</CODE> man page. My page points to
  +<CODE>/usr/include/sys/signal.h</CODE>, the relevant entries are:
   
   <P>
   <PRE>  #define SIGHUP     1    /* hangup, generated when terminal disconnects */ 
  @@ -150,9 +160,9 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Using_apachectl_to_control_the_s">Using apachectl to control the server</A></H1></CENTER>
   <P>
  -apache's distribution provides a nice script to control the server. It's
  -called apachectl and it's being installed into the same location with
  -httpd. In our scenario - it's /usr/apps/sbin/httpd_perl/apachectl
  +Apache's distribution provides a nice script to control the server. It's
  +called <STRONG>apachectl</STRONG> and it's installed into the same location with httpd. In our scenario -
  +it's /usr/apps/sbin/httpd_perl/apachectl
   
   <P>
   Start httpd
  @@ -188,16 +198,25 @@
   See the next section for the implication of the above calls.
   
   <P>
  -Replace the httpd_perl to httpd_docs in the above calls to get the control
  -over httpd_docs server.
  +Replace 'httpd_perl' with 'httpd_docs' in the above calls to control the
  +httpd_docs server.
   
   <P>
  -There are other options for apachectl, use 'help' option to see them all.
  +There are other options for <STRONG>apachectl</STRONG>, use 'help' option to see them all.
   
   <P>
   It's important to understand that this script is based on the PID file
   which is PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid. If you delete the
  -file by hand - the apachectl will fail to run.
  +file by hand - <STRONG>apachectl</STRONG> will fail to run.
  +
  +<P>
  +Also, note that <STRONG>apachectl</STRONG> is suitable to use from within your Unix system's startup files so that
  +your web server is automatically restarted upon system reboot. Either copy
  +the <STRONG>apachectl</STRONG> file to the appropriate location (<CODE>/etc/rc.d/rc3.d/S99apache</CODE> works on my RedHat Linux system) or create a symlink with that name
  +pointing to the the canonical location. (If you do this, make certain that
  +the script is writeable only by root -- the startup scripts have root
  +privileges during init processing, and you don't want to be opening any
  +security holes.)
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  @@ -208,10 +227,9 @@
   any other critical service you need to run some kind of watchdog.
   
   <P>
  -One simple solution is to use a slightly modified apachectl script which I
  -called apache.watchdog and to put it into the crontab to be called every 30
  -minutes or even every minute - if it's so critical to make sure the server
  -will be up all the time.
  +One simple solution is to use a slightly modified <STRONG>apachectl</STRONG> script which I called apache.watchdog and to put it into the crontab to be
  +called every 30 minutes or even every minute - if it's so critical to make
  +sure the server will be up all the time.
   
   <P>
   Crontab entry:
  @@ -226,9 +244,11 @@
   <PRE>  #!/bin/sh
     
     # this script is a watchdog to see whether the server is online
  -  # It tries to restart the server if it's down and sends an email alert to admin
  -  
  -  # admin's email
  +  # It tries to restart the server if it's
  +  # down and sends an email alert to admin 
  +</PRE>
  +<P>
  +<PRE>  # admin's email
     EMAIL=webmaster@somewhere.far
     #EMAIL=root@localhost
     
  @@ -293,10 +313,10 @@
     use HTTP::Status;
     
     ###### Config ########
  -  my $test_script_url = &quot;<A HREF="http://www.stas.com:81/perl/test.pl&quot">http://www.stas.com:81/perl/test.pl&quot</A>;;
  -  my $monitor_email = 'root@localhost';
  +  my $test_script_url = '<A HREF="http://www.stas.com:81/perl/test.pl">http://www.stas.com:81/perl/test.pl</A>';
  +  my $monitor_email   = 'root@localhost';
     my $restart_command = '/usr/apps/sbin/httpd_perl/apachectl start';
  -  my $mail_program = &quot;/usr/lib/sendmail -t -n&quot;;   
  +  my $mail_program    = '/usr/lib/sendmail -t -n';
     ######################
     
     $ua  = new LWP::UserAgent;
  @@ -314,13 +334,13 @@
     #  print &quot;Status $status\n&quot;;
     
     my $message = ($status == 0) 
  -   ? &quot;Server was down and successfully restarted!&quot; 
  -   : &quot;Server is down. Can't restart.&quot;;
  +              ? &quot;Server was down and successfully restarted!&quot; 
  +              : &quot;Server is down. Can't restart.&quot;;
   </PRE>
   <P>
   <PRE>  my $subject = ($status == 0) 
  -    ? &quot;Attention! Webserver restarted&quot;
  -    : &quot;Attention! Webserver is down. can't restart&quot;;
  +              ? &quot;Attention! Webserver restarted&quot;
  +              : &quot;Attention! Webserver is down. can't restart&quot;;
   </PRE>
   <P>
   <PRE>  # email the monitoring person
  @@ -351,7 +371,8 @@
       my($from,$to,$subject,$messagebody) = @_;
   </PRE>
   <P>
  -<PRE>    open MAIL, &quot;|$mail_program&quot; or die &quot;Can't open a pipe to a $mail_program :$!\n&quot;;
  +<PRE>    open MAIL, &quot;|$mail_program&quot;
  +        or die &quot;Can't open a pipe to a $mail_program :$!\n&quot;;
      
       print MAIL &lt;&lt;__END_OF_MAIL__;
     To: $to
  @@ -378,13 +399,13 @@
   </PRE>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H1><A NAME="Single_Mode_Running">Single Mode Running</A></H1></CENTER>
  +<CENTER><H1><A NAME="Running_in_Single_Mode">Running in Single Mode</A></H1></CENTER>
   <P>
  -Many times while developing a new code, you will want to run the server in
  -the single process mode. See <A HREF="././porting.html#Sometimes_it_works_Sometimes_Not">Sometimes it works Sometimes Not</A> and <A HREF="././porting.html#Names_collisions_with_Modules_an">Names collisions with Modules and libs</A> 
  +Often while developing new code, you will want to run the server in single
  +process mode. See <A HREF="././porting.html#Sometimes_it_works_Sometimes_Not">Sometimes it works Sometimes Not</A> and <A HREF="././porting.html#Names_collisions_with_Modules_an">Names collisions with Modules and libs</A> 
  +Running in single process mode inhibits the server from ``daemonizing'',
  +allowing you to run it more easily under debugger control.
   
  - 
  -
   <P>
   <PRE>  % /usr/apps/sbin/httpd_perl/httpd_perl -X
   </PRE>
  @@ -393,34 +414,33 @@
   the shell you have called it from. So to kill you just kill it with Ctrl-C. 
   
   <P>
  -Note that in -X mode the server will run very slowly on fetching the
  -images. If you use Netscape while your server is running in single-process
  -mode, the ``KeepAlive'' feature gets in the way. Netscape tries to open
  +Note that in -X mode the server will run very slowly while fetching images.
  +If you use Netscape while your server is running in single-process mode,
  +HTTP's ``KeepAlive'' feature gets in the way. Netscape tries to open
   multiple connections and keep them open. Because there is only one server
   process listening, each connection has to time-out before the next
   succeeds. Turn off KeepAlive in httpd.conf to avoid this effect while
  -developing or you can press <STRONG>STOP</STRONG> after a few secs of run (assuming you use the image size params, so the
  +developing or you can press <STRONG>STOP</STRONG> after a few seconds (assuming you use the image size params, so the
   Netscape will be able to render the rest of the page). 
   
   <P>
  -In addition you should know that you will not see any control messages
  -(when running with -X), you generally see in the error_log that the parent
  -server writes: Like ``server started, server stopped and etc''. Since httpd
  --X runs immediately as a child, so there is no controlling parent to write
  -all the status messages.
  +In addition you should know that when running with -X you will not see any
  +control messages that the parent server normally writes to the error_log.
  +(Like ``server started, server stopped and etc''.) Since <CODE>httpd -X</CODE> causes the server to handle all requests itself, without forking any
  +children, there is no controlling parent to write status messages.
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Starting_a_personal_server_for_e">Starting a personal server for each developer</A></H1></CENTER>
   <P>
   If you are the only developer working on the specific server:port - you
  -have no problems, since you have a complete control over the server. Now
  -many times you have a group of developers who need to concurrently develop
  -their mod_perl scripts. It means that each one will want to get the control
  -over the server - to kill it, to run it in single server mode, to restart
  -it again and soon. As well to have to control over the log files and other
  -configuration like MaxClients and etc . You can workaround this problem by
  -preparing a few httpd.conf file and to force each developer to use: 
  +have no problems, since you have a complete control over the server.
  +However, many times you have a group of developers who need to concurrently
  +develop their own mod_perl scripts. This means that each one will want to
  +have control over the server - to kill it, to run it in single server mode,
  +to restart it again, etc., as well to have control over the location of the
  +log files and other configuration settings like <STRONG>MaxClients</STRONG>, etc. You can work around this problem by preparing a few httpd.conf file
  +and forcing each developer to use: 
   
   <P>
   <PRE>  httpd_perl -f /path/to/httpd.conf  
  @@ -458,39 +478,38 @@
     &lt;/IfDefine&gt;
   </PRE>
   <P>
  -So what we have achieved with this technique is: A full control over
  -start/stop, number of children, separate error log file, and different
  -port. Now I wouldn't get the call every few minutes - ``Stas, I'm going to
  -restart the server''.
  +What we have achieved with this technique: Full control over start/stop,
  +number of children, separate error log file, and port selection. This saves
  +me from getting called every few minutes - ``Stas, I'm going to restart the
  +server''.
   
   <P>
  -To make things even more easier. (In the above technique, you have to
  -discover the PID of your parent httpd_perl process - written in
  -/usr/apps/var/httpd_perl/run/httpd.pid.userfoo) . We change the apachectl
  -script to do the work for us. We make a copy for each developer called
  -apachectl.username and we change 2 lines in script:
  +To make things even easier. (In the above technique, you have to discover
  +the PID of your parent httpd_perl process - written in
  +/usr/apps/var/httpd_perl/run/httpd.pid.userfoo) . We change the
  +<STRONG>apachectl</STRONG> script to do the work for us. We make a copy for each developer called <STRONG>apachectl.username</STRONG> and we change 2 lines in script:
   
   <P>
   <PRE>  PIDFILE=/usr/apps/var/httpd_perl/run/httpd.pid.sbekman
     HTTPD='/usr/apps/sbin/httpd_perl/httpd_perl -Dsbekman'
   </PRE>
   <P>
  -Of course you think you can use only one control file and to know who is
  +Of course you think you can use only one control file and know who is
   calling by using uid, but since you have to be root to start the server -
   it's not so simple. 
   
   <P>
   The last thing was to let developers an option to run in single process
  -node by:
  +mode by:
   
   <P>
   <PRE>  /usr/apps/sbin/httpd_perl/httpd_perl -Dsbekman -X
   </PRE>
   <P>
  -In addition to make life easier we decided to use relative links everywhere
  -in the static docs (including the calls to cgis). You will ask how using
  -the relative link you will get to the right server? Very simple - we have
  -utilized the mod_rewrite to solve our problems:
  +In addition to making life easier, we decided to use relative links
  +everywhere in the static docs (including the calls to CGIs). You may ask
  +how using the relative link you will get to the right server? Very simple -
  +we have utilized the mod_rewrite to solve our problems:
   
   <P>
   In access.conf of the httpd_docs server we have the following code: (you
  @@ -515,9 +534,9 @@
     
   </PRE>
   <P>
  -where IP numbers are then IPs of the developers they run the browser at. (I
  -have tried to use REMOTE_USER since we have all the users authenticated but
  -it didn't work for me)
  +where IP numbers are the IPs of the developers' client machine (where they
  +are running their web browser.) (I have tried to use REMOTE_USER since we
  +have all the users authenticated but it didn't work for me)
   
   <P>
   So if I have a relative URL like /perl/test.pl written in some html or even
  @@ -534,20 +553,20 @@
   above scheme will not work. There 2 solutions:
   
   <P>
  -First to generate relative URL so it will reuse the technique above, with
  +First, generate relative URL so it will reuse the technique above, with
   redirect (which is transparent for user) but it will not work if you have
   something to POST (redirect looses all the data!).
   
   <P>
  -Second to use a general config module which generates a correct full URL
  +Second, use a general config module which generates a correct full URL
   according to REMOTE_USER, so if $ENV{REMOTE_USER} eq 'sbekman', I return <A
   HREF="http://ourserver.com:8000/perl/">http://ourserver.com:8000/perl/</A>
   as cgi_base_url. Again this will work if the user is authenticated.
   
   <P>
  -All this good for development. It's better to use the full URLs in
  +All this is good for development. It's better to use the full URLs in
   production, since if you have a static form and the Action is relative but
  -the static document sits on another server, pressing form's submit will
  +the static document sits on another server, pressing the form's submit will
   cause a redirect to mod_perl server, but all the form's data will be lost
   during the redirect.
   
  @@ -555,27 +574,27 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Wrapper_to_emulate_the_server_en">Wrapper to emulate the server environment</A></H1></CENTER>
   <P>
  -Many times you start off with debugging your script by running it at your
  +Many times you start off debugging your script by running it from your
   favorite shell. Sometimes you encounter a very weird situation when script
  -runs from the shell but dies when called as cgi. The real problem lays in
  -the difference of the environment that's being used by your server and your
  -shell. An example can be a different perl path or having PERL5LIB env
  +runs from the shell but dies when called as a CGI. The real problem lies in
  +the difference between the environment that's being used by your server and
  +your shell. An example can be a different perl path or having PERL5LIB env
   variable which includes paths that aren't in the <CODE>@INC</CODE> of the
   perl compiled with mod_perl server and configured during the startup.
   
   <P>
  -The best thing is to write a wrapper that emulates the exact environment of
  -the server, By deleting first the environment variables like PERL5LIB and
  -calling the same perl that it's being used by the server. Then setting the
  -environment identical to the server's by copying the perl run directives
  -from server startup and config files. It'll also allow you to remove
  -completely the first line of the script - since mod_perl skip it and
  -wrapper knows how to call the script.
  +The best debugging approach is to write a wrapper that emulates the exact
  +environment of the server, by first deleting the environment variables like
  +PERL5LIB and calling the same perl binary that it's being used by the
  +server. Next, set the environment identical to the server's by copying the
  +perl run directives from server startup and config files. It'll also allow
  +you to remove completely the first line of the script - since mod_perl
  +skips it and the wrapper knows how to call the script.
   
   <P>
  -Below is the example of such a script. Note that we force the -wT when we
  +Below is the example of such a script. Note that we force the -Tw when we
   call the real script. (I have also added the ability to pass params, which
  -is not happen when you call the cgi from the web)
  +will not happen when you call the cgi from the web)
   
   <P>
   <PRE>  #!/usr/apps/bin/perl -w    
  @@ -629,15 +648,15 @@
     
       # run the cgi from the script's directory
       # Note that we invoke warnings and Taintness ON!!!
  -  system qq{$basedir/bin/perl -I$PERL5LIB -wT $cgi $params};
  +  system qq{$basedir/bin/perl -I$PERL5LIB -Tw $cgi $params};
   </PRE>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Log_Rotation">Log Rotation</A></H1></CENTER>
   <P>
   A little bit off topic but good to know and use with mod_perl where your
  -error_log can grow at 10-100Mb a day rate if your scripts spit lots of
  -warnings...
  +error_log can grow at a 10-100Mb per day rate if your scripts spit out lots
  +of warnings...
   
   <P>
   To rotate the logs do:
  @@ -652,6 +671,9 @@
   <P>
   The effect of SIGUSR1 and SIGHUP is detailed in: <A
   HREF="http://www.apache.org/docs/stopping.html">http://www.apache.org/docs/stopping.html</A>
  +
  +
  +<P>
   &lt;META&gt;I tried to kill -USR1 and it didn't reset the logs!!! kill -HUP
   did work&lt;/META&gt; 
   
  @@ -799,6 +821,49 @@
   
   </BLOCKQUOTE>
   
  +<P>
  +<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  +<CENTER><H1><A NAME="Preventing_from_modperl_process_">Preventing from modperl process to eat up all the disk's space, when it goes wild.</A></H1></CENTER>
  +<P>
  +Sometimes an error happens and causes the server to write millions of lines
  +into your error_log file and in a few minutes to put your server down on
  +its knees. For example I get an error <CODE>Callback called exit</CODE>
  +show up in my error_log file many times. The error_log files grows to 300
  +Mbytes in size in a few minutes. You should run a cron job to make sure
  +this doesn't happen and if it does to take care of it. Andreas J. Koenig is
  +running this shell script every minute:
  +
  +<P>
  +<PRE>  S=`ls -s /usr/local/apache/logs/error_log | awk '{print $1}'`
  +  if [ &quot;$S&quot; -gt 100000 ] ; then
  +    /etc/rc.d/init.d/httpd restart
  +    date | /bin/mail -s &quot;error_log $S kB on inx&quot; myemail@domain.com
  +  fi
  +</PRE>
  +<P>
  +It seems that his script will trigger restart every minute, since once the
  +logfile grows to be of 100000 lines, it'll stay of this size, unless you
  +remove or rename it, before you do restart. On my server I run a watchdog
  +every five minutes which restarts the server if it's getting stucked (it
  +always works since when some modperl child process goes wild, the I/O it
  +causes is so heavy that other brother processes can't normally to serve the
  +requests.) See <A HREF="././control.html#Monitoring_the_Server_A_watchdo">Monitoring the Server</A> for more hints.
  +
  +<P>
  +Ulrich Pfeifer told us this: You may also look at the daemontools from D.
  +J. Bernstein - <A
  +HREF="ftp://koobera.math.uic.edu/www/daemontools.html">ftp://koobera.math.uic.edu/www/daemontools.html</A>
  +
  +
  +<P>
  +<PRE>  ,-----
  +  | cyclog writes a log to disk. It automatically synchronizes the log
  +  | every 100KB (by default) to guarantee data integrity after a crash. It
  +  | automatically rotates the log to keep it below 1MB (by default). If
  +  | the disk fills up, cyclog pauses and then tries again, without losing
  +  | any data.
  +  `-----
  +</PRE>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
   
  @@ -813,7 +878,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/16/99 
  +	     <BR>Last Modified at 03/16/99 
         </FONT>
       </B>
     </TD>
  
  
  
  1.7       +23 -1     modperl-site/guide/debug.html
  
  Index: debug.html
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/debug.html,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- debug.html	1999/01/23 18:06:53	1.6
  +++ debug.html	1999/03/16 08:20:16	1.7
  @@ -20,6 +20,7 @@
   
   	<LI><A HREF="#Sometimes_script_works_Sometime">Sometimes script works, Sometimes Not</A>
   	<LI><A HREF="#Debug_Tracing">Debug Tracing</A>
  +	<LI><A HREF="#Getting_some_decent_debug_info_w">Getting some decent debug info when running under mod_perl</A>
   </UL>
   <!-- INDEX END -->
   
  @@ -64,6 +65,27 @@
   
   <P>
   PerlSetVar MOD_PERL_TRACE d
  +
  +<P>
  +<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  +<CENTER><H1><A NAME="Getting_some_decent_debug_info_w">Getting some decent debug info when running under mod_perl</A></H1></CENTER>
  +<P>
  +As many of you know, the interactive Perl debugger does not run under
  +Apache/mod_perl (yet). However, Dean Gaudet made the discovery last night
  +of the NonStop option. This enables us to get some decent debug info when
  +running under mod_perl. For example, before starting the server:
  +
  +<P>
  +<PRE>  % setenv PERL5OPT -d
  +  % setenv PERLDB_OPTS &quot;NonStop=1 LineInfo=db.out AutoTrace=1 frame=2&quot;
  +</PRE>
  +<P>
  +Now watch db.out for line:filename info. This is most useful for tracking
  +those core dumps that normally leave us guessing, even with a stacktrace
  +from gdb. db.out will show you what Perl code triggered the core. `man
  +perldebug' for more PERLDB_OPTS. Note, Perl will ignore PERL5OPT if
  +PerlTaintCheck is On.
  +
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
   
  @@ -78,7 +100,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/13/99 
         </FONT>
       </B>
     </TD>
  
  
  
  1.9       +9 -4      modperl-site/guide/index.html
  
  Index: index.html
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/index.html,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- index.html	1999/01/23 18:06:54	1.8
  +++ index.html	1999/03/16 08:20:19	1.9
  @@ -15,7 +15,7 @@
   to your perl cgi-bin scripts.</B></P></CENTER>
   
   
  -<CENTER><P><B>Version 1.06 Jan, 23 1999</B></P></CENTER>
  +<CENTER><P><B>Version 1.07 Mar, 16 1999</B></P></CENTER>
   
   
   <P>
  @@ -74,6 +74,9 @@
   <LI><A HREF="#search">Search perl.apache.org along with this guide</A></LI>
   
   
  +<LI><A HREF="guide.tar.gz">Download as one file</A></LI>
  +
  +
   </UL>
   
   
  @@ -110,9 +113,11 @@
   
   
   <TR ALIGN=CENTER VALIGN=TOP>
  -<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A HREF="help.html#author">Stas
  -Bekman</A>.<BR>
  -Last Modified at 12/09/1998 </FONT></B></TD>
  +
  +
  +<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A
  +HREF="help.html#author">Stas Bekman</A>.<BR> Last Modified at
  +03/16/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       +71 -62    modperl-site/guide/intro.html
  
  Index: intro.html
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/intro.html,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- intro.html	1998/12/10 09:22:22	1.5
  +++ intro.html	1999/03/16 08:20:20	1.6
  @@ -43,33 +43,36 @@
   
   <P>The Apache/Perl integration project brings together the full power of
   the Perl programming language and the Apache HTTP server. With mod_perl
  -it is possible to write Apache modules entirely in Perl. In addition, the
  -persistent interpreter embedded in the server avoids the overhead of starting
  -an external interpreter, the penalty of Perl start-up time and loading
  -and compiling the modules and the scripts. </P>
  +it is possible to write Apache modules entirely in Perl. In addition,
  +the persistent interpreter embedded in the server avoids the overhead of
  +starting an external interpreter, the penalty of Perl start-up time and
  +loading and compiling the modules and the scripts. </P>
   
   
   <P>The primary advantages of mod_perl are power and speed. You have full
   access to the inner-workings of the web server and can intervene at any
  -stage of request-processing. This allows for customized processing of (to
  -name just a few of the phases) URI-&gt;filename translation, authentication,
  -response generation and logging. There is very little run-time overhead.
  -In particular, it is not necessary to start a separate process, as is often
  -done with web-server extensions. The most wide-spread such extension mechanism,
  -the Common Gateway Interface (CGI), can be replaced entirely with perl-code
  -that handles the response generation phase of request processing. Mod_perl
  -includes 2 general purpose modules for this purpose (Apache::Registry)
  -that can transparently run existing perl CGI scripts and Apache::PerlRun,
  -which does a similar job but allows you to run dirty (to some extent) written
  +stage of request-processing. This allows for customized processing of
  +(to name just a few of the phases) URI-&gt;filename translation,
  +authentication, response generation and logging. There is very little
  +run-time overhead. In particular, it is not necessary to start a
  +separate process, as is often done with web-server extensions. The most
  +wide-spread such extension mechanism, the Common Gateway Interface
  +(CGI), can be replaced entirely with perl-code that handles the response
  +generation phase of request processing. Mod_perl includes 2 general
  +purpose modules for this purpose: Apache::Registry, which can
  +transparently run existing perl CGI scripts and Apache::PerlRun, which
  +does a similar job but allows you to run "dirtier" (to some extent)
   scripts.</P>
   
   
  -<P>Many people wonder and ask &quot;How much of a performance improvement
  -does mod_perl give?&quot;. Well, it all depends on what you're doing with
  -mod_perl and possibly who you ask. People report speed boosts from 200%
  -to 2000%.&nbsp;The best way to measure is to try it and see for yourself!
  -(see <A HREF="http://perl.apache.org/tidbits.html">Tidbit </A>and <A HREF="http://perl.apache.org/stories/">Stories
  -</A>pages for the facts)</P>
  +<P>Many people wonder and ask &quot;How much of a performance
  +improvement does mod_perl give?&quot;. Well, it all depends on what
  +you're doing with mod_perl and possibly who you ask. People report speed
  +boosts from 200% to 2000%. The best way to measure is to try it and
  +see for yourself! (see <A
  +HREF="http://perl.apache.org/tidbits.html">Tidbit </A>and <A
  +HREF="http://perl.apache.org/stories/">Stories </A>pages for the
  +facts)</P>
   
   
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B> 
  @@ -79,43 +82,48 @@
   <H3 ALIGN=CENTER><A NAME="2"></A>What is covered in this document</H3>
   
   
  -<P>This document was written to help you to start using the mod_perl as
  -soon as possible and with as less as possible obstacles. It includes an
  -information about installation and configuration of perl and apache
  -web server and goes deeply into an issues of writing and porting the perl
  -scripts for mod_perl. Note, that it doesn't enter the big world of using
  -the Perl API or C API. You will find the Pointers covering these topics at
  -<A HREF="help.html">Help Seek and Learning more</A> section of this document.<B>
  -This guide tries to cover the most of the Apache::Registry and Apache::PerlRun.</B></P>
  -
  -
  -<P>It's assumed that you know the basics of building and installing of
  -      perl and apache
  -(If you don't just read the INSTALL docs coming with distribution of each
  -package). However you will find in the document specific perl and
  -      apache related installation and
  -configuration notes, which will help you to successfully 
  -complete the mod_perl installation.</P>
  -
  -
  -<P>If after reading this guide and other documents listed at <A HREF="help.html">Help
  -section</A>, you feel that your question is yet not answered, please ask
  -the apache/mod_perl mailing list to help you. But first try to browse the
  -mailing list archive. Most of the time you will find the answer for your
  -question by searching the mailing archive, since there is a big chance
  -someone else already have encountered the problem and found a solution
  -for it. If you ignore this advice, don't be surprised if your question
  -will be left unanswered - it bores people to answer the same question more
  -than once (twice?). It doesn't mean that you should avoid asking questions. Just
  -don't abuse the available help and <B>RTFM </B>before you call for <B>HELP</B>.
  -(You have certainly heard the infamous fable of the shepherd boy and the
  -wolves)</P>
  +<P>This document was written in an effort to help one to start using
  +Apache's mod_perl extension as quickly and easily as possible. It
  +includes information about installation and configuration of perl and
  +the Apache web server and delves deeply into issues of writing and
  +porting existing perl scripts to run under mod_perl. Note that it
  +doesn't attempt to enter the big world of using the Perl API or C API.
  +You will find the Pointers covering these topics at <A
  +HREF="help.html">Help Seek and Learning more</A> section of this
  +document.<B> This guide tries to cover the most of the Apache::Registry
  +and Apache::PerlRun modules.</B></P>
  +
  +
  +<P>It is assumed that you know the basics of building and installing
  +perl and Apache (If you don't, just read the INSTALL docs coming with
  +distribution of each package). However you will find in the document
  +specific perl and Apache related installation and configuration notes,
  +which will help you to successfully complete the mod_perl
  +installation.</P>
  +
  +
  +<P>If after reading this guide and other documents listed at <A
  +HREF="help.html">Help section</A>, you feel that your question is yet
  +not answered, please ask the apache/mod_perl mailing list to help you.
  +But first try to browse the mailing list archive (located at <A
  +HREF="http://forum.swarthmore.edu/epigone/modperl">
  +http://forum.swarthmore.edu/epigone/modperl</A>). Often you will find
  +the answer to your question by searching the mailing archive, since
  +there is a good chance someone else has already encountered the problem
  +and found a solution for it. If you ignore this advice, don't be
  +surprised if your question goes unanswered - it bores people to answer
  +the same question more than once (twice?). This doesn't mean that you
  +should avoid asking questions, just don't abuse the available help and
  +<B>RTFM</B>before you call for <B>HELP</B>. (You have certainly heard
  +the infamous fable of the shepherd boy and the wolves...)</P>
  +
  +
  +<P>If you find incorrect details, my grammar mistakes or you want to
  +contribute to this document please feel free to send me an <A
  +HREF="mailto:sbekman@iname.com">email</A> at
  +<B>sbekman@iname.com</B>.</P>
   
   
  -<P>If you find incorrect details, my grammar mistakes or you want to contribute
  -to this document please feel free to send me an <A HREF="mailto:sbekman@iil.intel.com">email</A>.</P>
  -
  -
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B> 
   <HR WIDTH="100%"></P>
   
  @@ -158,7 +166,8 @@
   
   
   <P>As I said, I've quoted many information snippets from FAQs and emails,
  -      and I didn't credit people after each quote in the guide. I didn't mean to
  +      and I didn't credit people after each quote in the guide.
  +      I didn't mean to
         take the credits for myself, it's just that I've tried to keep
         track of names, and became lost, so I preferred not to credit at
         all in the guide, but to centralize it here. If you think that
  @@ -193,6 +202,7 @@
         <LI>Nathan Torkington
         <LI>Ralf Engelschall
         <LI>Randal Schwartz
  +      <LI>Steve Reppucci
         <LI>Vivek Khera
         <LI>
         <LI>Did I miss you? Tell me!
  @@ -200,8 +210,8 @@
   </P>
   
   
  -<P>I&nbsp;want to thank all the people who donated their time and efforts
  -to made this amazing idea of mod_perl to become reality. It includes Doug
  +<P>I want to thank all the people who donated their time and efforts to
  +made this amazing idea of mod_perl to become reality. This includes Doug
   MacEachern, the author of mod_perl and all the developers who contributed
   bug patches, modules and help. And of course the numerous unseen users who
   helped to find the bugs and advocate mod_perl around the world.</P>
  @@ -221,10 +231,9 @@
   </TR>
   
   
  -<TR ALIGN=CENTER VALIGN=TOP>
  -<TD ALIGN=CENTER VALIGN=CENTER><B><FONT SIZE=-1>Written by <A HREF="help.html#author">Stas
  -Bekman</A>.<BR>
  -Last Modified at 12/10/1998 </FONT></B></TD>
  +<TR ALIGN=CENTER VALIGN=TOP> <TD ALIGN=CENTER VALIGN=CENTER><B><FONT
  +SIZE=-1>Written by <A HREF="help.html#author">Stas Bekman</A>.<BR> Last
  +Modified at 03/16/1999 </FONT></B></TD>
   
   
   <TD><A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg"  BORDER=0 ALT="Mod Perl Icon" HEIGHT=59 WIDTH=150></A>
  
  
  
  1.9       +3 -3      modperl-site/guide/performance.html
  
  Index: performance.html
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/performance.html,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- performance.html	1999/01/23 18:06:54	1.8
  +++ performance.html	1999/03/16 08:20:21	1.9
  @@ -734,8 +734,8 @@
   <P>
   <STRONG>ab</STRONG> is a tool for benchmarking your Apache HTTP server. It is designed to give
   you an impression on how performable is your current Apache installation.
  -This especially shows you how much requests per time your Apache
  -installation is capable to serve.
  +Particularly it shows you how much requests per secs your Apache server is
  +capable to serve. The <STRONG>ab</STRONG> comes bundled with apache source distribution (and it's free :).
   
   <P>
   Lets try it. We will simulate 10 users concurrently requesting the script <CODE>www.you.com:81/test/test.pl</CODE> which a very light one. Each one does it for 10 times.
  @@ -1548,7 +1548,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/15/99 
         </FONT>
       </B>
     </TD>
  
  
  
  1.10      +143 -2    modperl-site/guide/porting.html
  
  Index: porting.html
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/porting.html,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- porting.html	1999/01/23 18:06:54	1.9
  +++ porting.html	1999/03/16 08:20:22	1.10
  @@ -53,6 +53,7 @@
   		<LI><A HREF="#Apache_PerlRun_a_closer_look">Apache::PerlRun - a closer look</A>
   	</UL>
   
  +	<LI><A HREF="#Redirecting_Errors_to_Client_ins">Redirecting Errors to Client instead of error_log</A>
   </UL>
   <!-- INDEX END -->
   
  @@ -486,6 +487,9 @@
   On.
   
   <P>
  +Make sure you read <A HREF="././warnings.html#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>.
  +
  +<P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H3><A NAME="END_blocks">END blocks</A></H3></CENTER>
   <P>
  @@ -1040,7 +1044,7 @@
   
   <P>
   <PRE>  # srm.conf
  -  ScriptAlias /cgi-perl/ /home/httpd/cgi/
  +  Alias /cgi-perl/ /home/httpd/cgi/
   </PRE>
   <P>
   <PRE>  # httpd.conf
  @@ -1133,6 +1137,143 @@
   In this case, under mod_perl you wouldn't see 'Foo-&gt;DESTROY' until the
   server shutdown, or your module properly took care of things.
   
  +<P>
  +<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  +<CENTER><H1><A NAME="Redirecting_Errors_to_Client_ins">Redirecting Errors to Client instead of error_log</A></H1></CENTER>
  +<P>
  +To trap all/most Perl run-time errors and send the output to the client
  +instead of Apache's error log add this line to your script.
  +
  +<P>
  +<PRE>  use CGI::Carp qw(fatalsToBrowser);
  +</PRE>
  +<P>
  +Refer to <CODE>CGI::Carp</CODE> man page for more related info.
  +
  +<P>
  +Also you can write your custom DIE/WARN signal handler. I don't want users
  +to see the error message, but I want it to be emailed to me if it's severe
  +enough. The handler traps various errors and performs accordingly to the
  +defined logic. My handler was written for the modperl environment, but
  +works correctly when is being called from the shell. A stipped version of
  +the code is shown here:
  +
  +<P>
  +<PRE>  # assign the DIE sighandler to call mydie(error_message) whenever a
  +  # die() sub is being called. Can be added anywhere in the code.
  +  $SIG{'__DIE__'} = \&amp;mydie;
  +  
  +  # and the handler itself
  +  sub mydie{
  +    my $why = shift;
  +  
  +    my $UNDER_MOD_PERL = ( (exists $ENV{'GATEWAY_INTERFACE'} 
  +                           and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
  +                         or exists $ENV{'MOD_PERL'} ) ? 1 : 0;
  +  
  +    chomp $why;
  +    my $orig_why = $why;                # an ascii copy for email report
  +  
  +    # handle the shell execution case (so we will not get all the HTML)
  +    print(&quot;Error: $why\n&quot;), exit unless $UNDER_MOD_PERL;
  +  
  +    my $should_email = 0;
  +    my $message = '';
  +  
  +    $why =~ s/[&lt;&amp;&gt;]/&quot;&amp;#&quot;.ord($&amp;).&quot;;&quot;/ge;    # entity escape
  +  
  +    # Now we need to trap various kinds of errors, that come from CGI.pm
  +    # And we don't want these error to be emailed to us, ofcourse -
  +    # these aren't programmatical errors
  +    if ($orig_why =~ /Client attempted to POST (\d+) bytes/o) {
  +  
  +      $message = qq{
  +                  You can not POST messages bigger than 
  +                  @{[1024*$c{max_image_size}]} bytes.&lt;BR&gt;
  +                  You have tried to post $1 bytes&lt;BR&gt;
  +                  If you are trying to upload an image, make sure its size is not 
  +                  bigger than @{[1024*$c{max_image_size}]} bytes.&lt;P&gt;
  +                  Thank you!
  +                 };
  +  
  +    } elsif ($orig_why =~ /Malformed multipart POST/o) {
  +  
  +      $message = qq{
  +                  Have you tried to upload an image in the wrong way?&lt;P&gt;
  +                  To sucessfully upload an image you must use a browser that supports
  +                  image upload and use the 'Browse' button to select that image.
  +                  DO NOT type the path to the image into the upload field.&lt;P&gt;
  +                  Thank you!
  +                 };
  +  
  +    } elsif ($orig_why =~ /closed socket during multipart read/o) {
  +  
  +      $message = qq{
  +                  Have you pressed a 'STOP' button?&lt;BR&gt;
  +                  Please try again!&lt;P&gt;
  +                  Thank you!
  +                 };
  +  
  +    } else {
  +  
  +      $message = qq{
  +                    &lt;B&gt;There is no action to be performed on your side, since
  +                  the error report has been already sent to webmaster. &lt;BR&gt;&lt;P&gt;
  +                  &lt;B&gt;Thank you for your patience!&lt;/B&gt;
  +                 };
  +  
  +      $should_email = 1;
  +    }
  +  
  +  
  +    print qq|Content-type: text/html
  +  
  +  &lt;HTML&gt;&lt;BODY BGCOLOR=&quot;white&quot;&gt;
  +  &lt;B&gt;Oops, An error has happened.&lt;/B&gt;&lt;P&gt;
  +    |;  
  +  
  +    print HTML::warn_box($message);
  +  
  +      # print the tail!
  +    HTML::custom_tail();
  +  
  +      # send email report if appropriate
  +    if ($should_email){
  +  
  +        # import sendmail subs
  +      use Mail ();
  +        # prepare the email error report:
  +      my $subject =&quot;Error Report&quot;;
  +      my $body = qq|
  +    An error has happened:
  +  
  +    $orig_why
  +  
  +      |;
  +  
  +        # send error reports to admin and author
  +      send_mail($c{email}{'admin'},$c{email}{'admin'},$subject,$body);
  +      send_mail($c{email}{'admin'},$c{email}{'author'},$subject,$body);
  +      print STDERR &quot;[&quot;.scalar localtime().&quot;] [SIGDIE] Sending Error Email\n&quot;;
  +    }
  +  
  +       # print to error_log so we will know we've sent
  +    print STDERR &quot;[&quot;.scalar localtime().&quot;] [SIGDIE] $orig_why \n&quot;;
  +  
  +    exit 1;
  +  }                             # end of sub mydie
  +  
  +</PRE>
  +<P>
  +You have noticed that I trap the CGI.pm's <CODE>die()</CODE> calls here, I
  +don't see any reason why my users should see an ugly error messages, but
  +that's the way CGI.pm written. The workaround was to trap them myself.
  +
  +<P>
  +Please note that as of ver 2.49, CGI.pm provides a <CODE>cgi_error()</CODE>
  +method to print the errors and wouldn't <CODE>die()</CODE> unless you want
  +it.
  +
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
   
  @@ -1147,7 +1288,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/16/99 
         </FONT>
       </B>
     </TD>
  
  
  
  1.8       +102 -83   modperl-site/guide/scenario.html
  
  Index: scenario.html
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/scenario.html,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- scenario.html	1999/01/23 18:06:55	1.7
  +++ scenario.html	1999/03/16 08:20:23	1.8
  @@ -18,13 +18,13 @@
   <P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
   <UL>
   
  -	<LI><A HREF="#Making_a_strategic_decision">Making a strategic decision</A>
  -	<LI><A HREF="#Deciding_on_directories_layout">Deciding on directories layout</A>
  -	<LI><A HREF="#Configuration_and_compilation_of">Configuration and compilation of the sources. </A>
  +	<LI><A HREF="#Making_a_Strategic_Decision">Making a Strategic Decision</A>
  +	<LI><A HREF="#Deciding_on_a_Directory_Layout">Deciding on a Directory Layout</A>
  +	<LI><A HREF="#Configuration_and_Compilation_of">Configuration and Compilation of the Sources. </A>
   	<UL>
   
  -		<LI><A HREF="#httpd_docs_server">httpd_docs server</A>
  -		<LI><A HREF="#httpd_perl_server_mod_perl_">httpd_perl server (mod_perl):</A>
  +		<LI><A HREF="#httpd_docs_Server">httpd_docs Server</A>
  +		<LI><A HREF="#httpd_perl_Server_mod_perl_">httpd_perl Server (mod_perl):</A>
   	</UL>
   
   	<LI><A HREF="#Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A>
  @@ -33,73 +33,70 @@
   
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P>
  -<CENTER><H1><A NAME="Making_a_strategic_decision">Making a strategic decision</A></H1></CENTER>
  +<CENTER><H1><A NAME="Making_a_Strategic_Decision">Making a Strategic Decision</A></H1></CENTER>
   <P>
  -When you will run your scripts under mod_perl - you will notice that the
  -httpd processes consumes a huge pieces of memory, from 5M to 25M and more.
  -Since there is no free dinner, that's the price we pay for the great speed
  -improvements under mod_perl. But it doesn't mean that you should serve the
  -static objects like images and html docs with these processes. It's an
  -overkill. The best approach is to run 2 servers: a light apache server with
  -no mod_perl compiled in to serve the static pages, and a heavy
  -apache/mod_perl server to server the cgis in mod_perl mode only. This
  +When running your scripts under mod_perl, you will notice that the httpd
  +processes consume a huge amount of memory, from 5M to 25M and more. That's
  +the price you pay for the great speed improvements under mod_perl -- the
  +function of Perl has has embedded in the Apache server binary.
  +
  +<P>
  +It's overkill to serve the static objects like images and html docs with
  +these larger processes. The best approach is to run two servers: a light
  +Apache server with no mod_perl compiled in serving the static pages, and a
  +heavy Apache/mod_perl server serving the CGIs in mod_perl mode only. This
   section describes a real world example ready for copy and paste to start
   with. You will probably will want to change the base directories, but
  -basically you can pick it as it is. 
  +basically you can use it as it is.
   
   <P>
  -Since we run 2 apache servers we will need 2 different configuration files,
  -log files and etc. We need a special directory layout. While some of the
  -directories can be shared between 2 servers (assuming that use the same
  -source distribution for both servers, other should be separated. I choose
  -to make the difference between 2 servers by calling them httpd_docs
  -(apache) and httpd_perl (apache/mod_perl). 
  +Since we run two apache servers we will need two different configuration
  +files, log files and etc. We need a special directory layout. While some of
  +the directories can be shared between the two servers (assuming that both
  +are built from the same source distribution) others should be separated.
  +We'll refer to these two servers as <STRONG>httpd_docs</STRONG>
  +(vanilla Apache) and <STRONG>httpd_perl</STRONG> (Apache/mod_perl). 
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H1><A NAME="Deciding_on_directories_layout">Deciding on directories layout</A></H1></CENTER>
  +<CENTER><H1><A NAME="Deciding_on_a_Directory_Layout">Deciding on a Directory Layout</A></H1></CENTER>
   <P>
  -We will make /usr/apps our <STRONG>root</STRONG> directory. We will build all the dir tree there. (/usr/apps/bin
  -/usr/apps/etc and etc...) 
  +For this illustration, we'll use <CODE>/usr/apps</CODE> as our <STRONG>root</STRONG> directory. The Apache installation directories will be stored under this
  +root (/usr/apps/bin /usr/apps/etc and etc...)
   
   <P>
  -First let's prepare the sources. We assume that all the sources go to
  -/usr/apps/usr/src dir. First lets make 2 subdirs: 
  +First let's prepare the sources. We'll assume that all the sources go to
  +/usr/apps/usr/src dir. First let's make two subdirectories:
   
   <P>
   <PRE>      % mkdir /usr/apps/usr/src/httpd_docs
         % mkdir /usr/apps/usr/src/httpd_perl
   </PRE>
   <P>
  -Now we put the apache source into /usr/apps/usr/src/httpd_docs: 
  +Now we'll put the Apache source into <CODE>/usr/apps/usr/src/httpd_docs</CODE>:
   
   <P>
   <PRE>      % cd /usr/apps/usr/src/httpd_docs
  -      % cp ~/apache.tar.gz .
  -      % gzip -d apache.tar.gz
  -      % tar xvf apache.tar
  +      % gzip -dc /path/to/tarfile/apache.tar.gz | tar xvf -
   </PRE>
   <P>
  -let's check: 
  +(Replace '<CODE>/path/to/tarfile</CODE>' with the location where you've downloaded the file in all examples.)
  +Let's check:
   
   <P>
   <PRE>      % ls -l
         drwxr-xr-x  8 stas  stas 2048 Oct 29 17:38 apache_1.3.2/
   </PRE>
   <P>
  -Prepare the httpd_perl server sources 
  +Now we'll prepare the httpd_perl server sources:
   
   <P>
   <PRE>      % cd /usr/apps/usr/src/httpd_perl
  -      % cp ~/apache.tar.gz .
  -      % gzip -d apache.tar.gz
  -      % tar xvf apache.tar
  -      % cp ~/modperl.tar.gz .
  -      % gzip -d modperl.tar.gz
  -      % tar xvf modperl.tar
  +      % gzip -dc /path/to/tarfile/apache.tar.gz | tar xvf -
  +      % gzip -dc /path/to/tarfile/modperl.tar.gz | tar xvf -
   </PRE>
   <P>
  -let's check
  +Let's check
   
   <P>
   <PRE>      % ls -l
  @@ -107,14 +104,15 @@
         drwxr-xr-x  8 stas  stas 2048 Oct 29 17:38 modperl-1.16/
   </PRE>
   <P>
  -Time to decide the desired directories structure layout (Where apache files
  -go): 
  +Time to decide one the desired directory structure layout (where the apache
  +files go): 
   
   <P>
   <PRE>      ROOT = /usr/apps 
   </PRE>
   <P>
  -Both Servers Can share the following dirs (so we will not duplicate data): 
  +The two servers can share the following directories (so we will not
  +duplicate data): 
   
   <P>
   <PRE>      /usr/apps/bin/
  @@ -124,7 +122,7 @@
         /usr/apps/share/
   </PRE>
   <P>
  -<STRONG>Important:</STRONG> we assume that both servers comes from the same source
  +<STRONG>Important:</STRONG> we assume that both servers are built from the same Apache source version.
   
   <P>
   Servers store their specific files either in httpd_docs or httpd_perl:
  @@ -146,15 +144,16 @@
                                  run/
   </PRE>
   <P>
  -Next step is to configure and compile the sources: Below are the procedures
  -to compile both servers taking into account the above directories layout:
  +The next step is to configure and compile the sources: Below are the
  +procedures to compile both servers taking into account the above directory
  +layout:
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H1><A NAME="Configuration_and_compilation_of">Configuration and compilation of the sources.</A></H1></CENTER>
  +<CENTER><H1><A NAME="Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A></H1></CENTER>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="httpd_docs_server">httpd_docs server</A></H2></CENTER>
  +<CENTER><H2><A NAME="httpd_docs_Server">httpd_docs Server</A></H2></CENTER>
   <DL>
   <P><DT><STRONG><A NAME="item_Configuration">Configuration</A></STRONG><DD>
   <P>
  @@ -179,7 +178,7 @@
   </PRE>
   <P>
   Note: add --layout to see the resulting dirs layout without actually making
  -the configuration. 
  +the configuration.
   
   <P><DT><STRONG><A NAME="item_Compilation">Compilation:</A></STRONG><DD>
   <P>
  @@ -189,14 +188,14 @@
   <PRE>      % make install
   </PRE>
   <P>
  -Rename the 'httpd' to 'http_docs' 
  +Rename 'httpd' to 'http_docs' 
   
   <P>
   <PRE>      % mv /usr/apps/sbin/httpd_docs/httpd /usr/apps/sbin/httpd_docs/httpd_docs
   </PRE>
   <P>
  -Now update the apachectl utility to point to a new httpd name (by hand or
  -by using perl)
  +Now update the apachectl utility to point to the new httpd name (via your
  +favorite text editor or by using perl)
   
   <P>
   <PRE>      % perl -p -i -e 's|httpd_docs/httpd|httpd_docs/httpd_docs|' /usr/apps/sbin/httpd_docs/apachectl
  @@ -204,15 +203,15 @@
   </DL>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="httpd_perl_server_mod_perl_">httpd_perl server (mod_perl):</A></H2></CENTER>
  +<CENTER><H2><A NAME="httpd_perl_Server_mod_perl_">httpd_perl Server (mod_perl):</A></H2></CENTER>
   <P>
  -Before you start to configure the mod_perl, you should be aware that there
  -a few required modules that have to be installed before. You will know
  -whether you have all the required installed or not, during the run <CODE>perl Makefile.PL</CODE> below. If you discover that you don't have these, go to your nearest CPAN
  -repository (if you don't know what is it, go to <A
  +Before you start to configure the mod_perl sources, you should be aware
  +that there a few Perl modules that have to be installed before building
  +mod_perl. You will be alerted of any missing required when you run the
  +<CODE>perl Makefile.PL</CODE> command line below. If you discover that you don't have these, go to your
  +nearest CPAN repository (if you don't know what is it, go to <A
   HREF="http://www.perl.com/CPAN">http://www.perl.com/CPAN</A> ) or run the
  -interactive shell by
  -<CODE>perl -MCPAN -e shell</CODE> .
  +CPAN interactive shell via the command line <CODE>perl -MCPAN -e shell</CODE> .
   
   <P>
   Now back to installation.
  @@ -224,7 +223,7 @@
         % make clean
   </PRE>
   <P>
  -It's important to <STRONG>make clean</STRONG> since some of the versions aren't binary compatible (e.g apache 1.3.3 vs
  +It is important to <STRONG>make clean</STRONG> since some of the versions aren't binary compatible (e.g apache 1.3.3 vs
   1.3.4) so any ``third-party'' C modules need to be re-compiled against the
   1.3.4 header files.
   
  @@ -261,56 +260,76 @@
   /usr/apps/usr/src/httpd_perl/apache_1.3.2/src/httpd
   
   <P>
  +Note: You have noted that we didn't go to the apache's source dir and run <CODE>make install</CODE>. When <CODE>USE_APACI</CODE> is enabled, <CODE>APACHE_PREFIX</CODE> will specify the --prefix option for Apache's configure script, specifying
  +the installation path for Apache. When this option is used, mod_perl's make
  +install will also make install on the Apache side, installing the httpd
  +binary, support tools, along with the configuration, log and document
  +trees.
  +
  +<P>
   If make test fails, look into t/logs and see what's in there.
   
   <P>
  -rename the 'httpd' to 'httpd_perl' 
  +Rename the 'httpd' to 'httpd_perl' 
   
   <P>
   <PRE>      % mv /usr/apps/sbin/httpd_perl/httpd /usr/apps/sbin/httpd_perl/httpd_perl
   </PRE>
   <P>
  -now update the apachectl utility to point to a new httpd name (by hand or
  +Now update the apachectl utility to point to a new httpd name (by hand or
   by using perl)
   
   <P>
   <PRE>      % perl -p -i -e 's|httpd_perl/httpd|httpd_perl/httpd_perl|' /usr/apps/sbin/httpd_perl/apachectl
   </PRE>
   <P>
  -Now proceed to <A HREF="././config.html#">Server Configuration</A> section.
  +Now proceed to the <A HREF="././config.html#">Server Configuration</A> section.
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Is_it_possible_to_install_and_us">Is it possible to install and use apache/mod_perl without having a root access?</A></H1></CENTER>
   <P>
   Yes, no problem with that. Follow the instructions above and when you
  -encounter APACI_ARGS use your home directory or alike as a prefix (e.g
  +encounter APACI_ARGS use your home directory (or some other directory which
  +you have write access to as a prefix, for example,
   <CODE>/home/stas/www</CODE>) and everything will be installed there. There is a chance that some perl
   libs will be not installed on your server by root and you will have to
   install these locally too. See the <A
   HREF="http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html#7">http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html#7</A>
   for more information on local perl installations.
   
  +<P>
  +You will not be able to have the server listen to a port lower then 1024 if
  +you aren't starting it as <CODE>root</CODE>, so choose a port number above 1024. (I use 8080 in most cases). Note that
  +you will have to use a URL like <CODE>http://www.you.com:8080</CODE> in that case, but that's not a problem since generally users don't directly
  +access URLs to CGI scripts, but rather are directed to them from a link on
  +a webpage or as the '<CODE>ACTION</CODE>' of an HTML form, so they shouldn't know at all that the port is different
  +from the default port 80.
  +
  +<P>
  +If you want your Apache server to start automatically on system reboot, you
  +will need to invoke the server startup script from somewhere within the
  +init scripts on your host. (This is often somewhere under
  +<CODE>/etc/rc.d</CODE>, but this path can vary depending upon the flavor of Unix you're using.)
  +
  +<P>
  +One more important thing to keep in mind is system resources. Mod_perl is
  +memory hungry -- if you run a lot of mod_perl processes on that machine
  +(and it's not your own host...), most likely the system administrator of
  +the host will ask you to shutdown your mod_perl server, or to find another
  +home for it. You have a few solutions:
  +
  +<P>
  +<STRONG>a</STRONG>. Reduce resource usage - see <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>
  +
  +
  +
  +<P>
  +<STRONG>b</STRONG>. Ask your ISP if you can put a dedicated machine into their computer room
  +and be root there.
  +
   <P>
  -You will not be able to set the server to listen to port lower then 1024
  -(if you aren't a root). So pick your port as a number above the 1024. (I
  -use 8080 in most cases). Note that you will have to use the <A
  -HREF="http://www.you.com:8080">http://www.you.com:8080</A> in that case.
  -But it's not a problem since generally users don't access directly the cgi
  -but from the webpage, so they shouldn't know at all that the port is
  -different.
  -
  -<P>
  -You will need to worry to put the start server script into rc.d directory
  -of your machine, so if the last will be rebooted - your webserver will be
  -restarted automatically.
  -
  -<P>
  -One more important thing is Resources, mod_perl is very memory greedy and
  -if you will run lots of mod_perl processes on that machine, most likely
  -your host will ask you to shutdown the mod_perl server, or to find another
  -home. You have a few solutions: <STRONG>a.</STRONG> reduce resource usage - see <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting the size of the processes</A>  <STRONG>b.</STRONG> ask your ISP if you can put a dedicated machine into their computer room
  -and be root there. <STRONG>c.</STRONG> look for another ISP with lots of resources or one that supports mod_perl
  +<STRONG>c</STRONG>. Look for another ISP with lots of resources or one that supports mod_perl
   (not likely)
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
  @@ -326,7 +345,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/14/99 
         </FONT>
       </B>
     </TD>
  
  
  
  1.7       +10 -12    modperl-site/guide/snippets.html
  
  Index: snippets.html
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/snippets.html,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- snippets.html	1999/01/23 18:06:55	1.6
  +++ snippets.html	1999/03/16 08:20:24	1.7
  @@ -18,7 +18,6 @@
   <P><A NAME="toc"></A><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
   <UL>
   
  -	<LI><A HREF="#Redirecting_Errors_to_Client_ins">Redirecting Errors to Client instead of error_log</A>
   	<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="#More_on_relative_paths">More on relative paths</A>
  @@ -28,16 +27,6 @@
   
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P>
  -<CENTER><H1><A NAME="Redirecting_Errors_to_Client_ins">Redirecting Errors to Client instead of error_log</A></H1></CENTER>
  -<P>
  -To trap all/most Perl run-time errors and send the output to the client
  -instead of Apache's error log add this line to your script.
  -
  -<P>
  -<PRE>  use CGI::Carp qw(fatalsToBrowser);
  -</PRE>
  -<P>
  -<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <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
  @@ -196,6 +185,15 @@
     }
     
     
  +=head1 Accessing variables from the caller's package
  +</PRE>
  +<P>
  +Sometimes you want to access some variables from the caller's package. One
  +way is to do:
  +
  +<P>
  +<PRE>  my $caller = caller;
  +  print qq[$caller --- ${&quot;${caller}::var&quot;}];
   </PRE>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
  @@ -211,7 +209,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/16/99 
         </FONT>
       </B>
     </TD>
  
  
  
  1.8       +83 -72    modperl-site/guide/start.html
  
  Index: start.html
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/start.html,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- start.html	1999/01/23 18:06:55	1.7
  +++ start.html	1999/03/16 08:20:25	1.8
  @@ -39,10 +39,10 @@
   	<UL>
   
   		<LI><A HREF="#Testing_by_checking_the_error_lo">Testing by checking the error_log file</A>
  -		<LI><A HREF="#Testing_by_calling_the_perl_sta">Testing by calling the /perl-status </A>
  -		<LI><A HREF="#Testing_by_telneting_to_the_port">Testing by telneting to the port, server's listening to</A>
  -		<LI><A HREF="#Run_a_cgi_that_shows_you_your_se">Run a cgi that shows you your server's environment</A>
  -		<LI><A HREF="#with_lwp_request">with lwp-request</A>
  +		<LI><A HREF="#Testing_by_viewing_perl_status">Testing by viewing /perl-status </A>
  +		<LI><A HREF="#Testing_via_telnet">Testing via telnet</A>
  +		<LI><A HREF="#Testing_via_a_CGI_script">Testing via a CGI script</A>
  +		<LI><A HREF="#Testing_via_lwp_request">Testing via lwp-request</A>
   	</UL>
   
   	<LI><A HREF="#Starting_to_use_the_server">Starting to use the server</A>
  @@ -53,9 +53,9 @@
   <P>
   <CENTER><H1><A NAME="Coverage">Coverage</A></H1></CENTER>
   <P>
  -This sections gets you a quick review of configuration and installation of
  -the required tools. For a kick start tutorial, which will allow you make to
  -make copy and paste slick installation, see
  +These sections give a quick review of configuration and installation of the
  +required tools. For a quick-start tutorial, which will allow you make to
  +make a copy-and-paste slick installation, see
   <A HREF="././scenario.html#">Real World Scenario</A>
   
   
  @@ -64,19 +64,19 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Downloading_the_needed_component">Downloading the needed components.</A></H1></CENTER>
   <P>
  -In order to start using the mod_perl - you will need to get first Perl,
  -Apache webserver and mod_perl itself. Below you will find the needed
  +In order to start using mod_perl you will first need to get Perl, the
  +Apache webserver, and mod_perl itself. Below you will find the needed
   information.
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H2><A NAME="Perl_Download">Perl Download</A></H2></CENTER>
   <P>
  -Probably perl is already installed at your machine. But check the version
  -you use. You better get the perl5.004 and higher version. 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
  +Perl is most likely already installed on your machine, but you should at
  +least check the version you using. It is highly recommended that you have
  +at least perl version 5.004 or higher. You can get the latest perl version
  +from <A HREF="http://www.perl.com/.">http://www.perl.com/.</A> Try the
  +direct download link <A
   HREF="http://www.perl.com/pace/pub/perldocs/latest.html.">http://www.perl.com/pace/pub/perldocs/latest.html.</A>
    
   
  @@ -86,7 +86,8 @@
   <P>
   Get the latest apache webserver from <A
   HREF="http://www.apache.org.">http://www.apache.org.</A> Try the direct
  -download link [http://www.apache.org/dist/]. 
  +download link <A
  +HREF="http://www.apache.org/dist/.">http://www.apache.org/dist/.</A> 
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  @@ -94,7 +95,8 @@
   <P>
   Get the latest mod_perl from <A
   HREF="http://perl.apache.org.">http://perl.apache.org.</A> Try the direct
  -download link [http://perl.apache.org/dist/].
  +download link <A
  +HREF="http://perl.apache.org/dist/.">http://perl.apache.org/dist/.</A>
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  @@ -118,11 +120,12 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H2><A NAME="Apache">Apache</A></H2></CENTER>
   <P>
  -It will be a good idea to try to install the Apache webserver without
  -mod_perl first. So later if something going wrong you will know that it's
  -not apache's server problem. But you can skip this stage. In any case you
  -have to open the source distribution of apache preferably at the same level
  -with modperl distribution.
  +It is a good idea to try to install the Apache webserver without mod_perl
  +first. This way, if something going wrong, you will know that it's not the
  +Apache server's problem. But you can skip this stage if you already have a
  +working (non-mod_perl) Apache server, or if you're just the daring type. In
  +any case you should unpack the Apache source distribution, preferably at
  +the same level as the mod_perl distribution.
   
   <P>
   <PRE>  % ls -l /usr/src
  @@ -133,16 +136,15 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H2><A NAME="Mod_Perl">Mod_Perl</A></H2></CENTER>
   <P>
  -Now we come to the main point. 
  +Now we come to the main point of this document. 
   
   <P>
   Here I'll give only a short example of mod_perl installation. You should
  -read the real world scenario for a more complete description.
  +read the real world scenarios for a more complete description.
   
   <P>
  -As with any perl package the installation of mod_perl is very easy and
  -standard. perldoc INSTALL will guide you thru the configuration and
  -installation process.
  +As with any perl package, the installation of mod_perl is very easy and
  +standard. <CODE>perldoc INSTALL</CODE> will guide you thru the configuration and installation process.
   
   <P>
   The fastest way to install would be:
  @@ -153,13 +155,13 @@
     % make &amp;&amp; make test &amp;&amp; make install
   </PRE>
   <P>
  -(Note: if you use an apache version different then apache_1.3.2, the line
  -above and later should be changed appropriately)
  +(Note: if you use an apache version different then apache_1.3.2, change the
  +version number in the example above and in all later examples
  +appropriately)
   
   <P>
  -To change the installation target (either if you aren't root or you need to
  -install a second copy for testing purposes), assuming you use /foo/server
  -as a base directory root, you have to run this:
  +To change the installation target (either if you aren't <CODE>root</CODE> or you need to install a second copy for testing purposes), assuming you
  +use /foo/server as a base directory root, you have to run this:
   
   <P>
   <PRE>  % perl Makefile.PL APACHE_SRC=../apache_1.3.2/src \
  @@ -167,12 +169,12 @@
       APACHE_PREFIX=/foo/server PREFIX=/foo/server
   </PRE>
   <P>
  -Where <CODE>PREFIX</CODE> says where to install the perl modules,
  +Where <CODE>PREFIX</CODE> specifies where to install the perl modules,
   <CODE>APACHE_PREFIX</CODE> - the same for the apache files.
   
   <P>
  -Next step is to configure the mod_perl sections in the apache conf files.
  -See <A HREF="././config.html#">ModPerlConfiguration</A>
  +The next step is to configure the mod_perl sections of the apache conf
  +files. See <A HREF="././config.html#">ModPerlConfiguration</A>
   
   
   
  @@ -195,13 +197,12 @@
   </PRE>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="Testing_by_calling_the_perl_sta">Testing by calling the /perl-status</A></H2></CENTER>
  +<CENTER><H2><A NAME="Testing_by_viewing_perl_status">Testing by viewing /perl-status</A></H2></CENTER>
   <P>
  -Fetch: <A
  +Assuming that you have configured the <CODE>&lt;Location /perl-status</CODE>&gt; Section in the server configuration file (refer to
  +<A HREF="././config.html#">ModPerlConfiguration</A>), fetch: <A
   HREF="http://www.yourserver.com/perl-status">http://www.yourserver.com/perl-status</A>
  -from your favorite Netscape browser :-) (Assuming you have configured the
  -&lt;Location /perl-status&gt; Section in the server config file (refer to
  -<A HREF="././config.html#">ModPerlConfiguration</A>)
  +using your favorite Netscape browser :-)
   
   <P>
   You should see something like this:
  @@ -212,17 +213,20 @@
   </PRE>
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="Testing_by_telneting_to_the_port">Testing by telneting to the port, server's listening to</A></H2></CENTER>
  +<CENTER><H2><A NAME="Testing_via_telnet">Testing via telnet</A></H2></CENTER>
   <P>
  -Assume that you set <CODE>Port 8080</CODE> in the httpd.conf for your mod_perl server. You have to telnet to your
  -server port 8080, then you should type <CODE>HEAD / HTTP/1.0</CODE> then press the &lt;ENTER&gt; key TWICE!
  +Knowing the port you've configured Apache to listen on, you can use <CODE>telnet</CODE> to talk directly to the web server.
   
   <P>
  +Assume that you set <CODE>Port 8080</CODE> in the httpd.conf for your mod_perl enabled server. Telnet to your server
  +at port 8080, and type <CODE>HEAD / HTTP/1.0</CODE> then press the &lt;ENTER&gt; key TWICE!
  +
  +<P>
   <PRE>  % telnet yourserver.com 8080&lt;ENTER&gt;
     HEAD / HTTP/1.0&lt;ENTER&gt;&lt;ENTER&gt;
   </PRE>
   <P>
  -You should see a respond like this:
  +You should see a response like this:
   
   <P>
   <PRE>  HTTP/1.1 200 OK
  @@ -234,12 +238,12 @@
     Connection closed.
   </PRE>
   <P>
  -So you see <CODE>Server: Apache/1.3.2 (Unix) mod_perl/1.16_01</CODE> - which says that you do have mod_perl installed and it's 1.16_01. Of
  -course in your case it would be the version you have installed.
  +So you see <CODE>Server: Apache/1.3.2 (Unix) mod_perl/1.16_01</CODE> - which says that you <STRONG>do</STRONG> have mod_perl installed and it is version 1.16_01. Of course in your case
  +it would be the version you have installed.
   
   <P>
  -However, just because you've got it linked in there, that doesn't meant
  -that you have your server configured to use mod_perl to handle Perl
  +However, just because you've got mod_perl linked in there, that doesn't
  +meant that you have your server configured to use mod_perl to handle Perl
   scripts. You will find the configuration assistance at
   <A HREF="././config.html#">ModPerlConfiguration</A>
   
  @@ -247,7 +251,11 @@
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="Run_a_cgi_that_shows_you_your_se">Run a cgi that shows you your server's environment</A></H2></CENTER>
  +<CENTER><H2><A NAME="Testing_via_a_CGI_script">Testing via a CGI script</A></H2></CENTER>
  +<P>
  +Another method is to invoke a CGI script which dumps the server's
  +environment.
  +
   <P>
   Copy and paste the script below (no need for perl line!). Let's say you
   called it test.pl, you saved it into the root of the cgi scripts, and cgi
  @@ -269,9 +277,9 @@
   <PRE>  % chmod a+x test.pl
   </PRE>
   <P>
  -Now fetch the <A
  -HREF="http://www.you.com:8080/perl/test.pl">http://www.you.com:8080/perl/test.pl</A>
  -. You should see something like this (part of the output was snipped).
  +Now fetch the URL <A
  +HREF="http://www.you.com:8080/perl/test.pl.">http://www.you.com:8080/perl/test.pl.</A>
  +You should see something like this (part of the output was snipped).
   
   <P>
   <PRE>  SERVER_SOFTWARE    Apache/1.3.2 (Unix) mod_perl/1.16_01
  @@ -285,7 +293,8 @@
   </PRE>
   <P>
   Now if I run the same script in mod_cgi mode (configured with /cgi-bin)
  -(you must add the perl line #!/bin/perl for the above script) and fetch <A
  +(you'll need to add the perl line #!/bin/perl for the above script) and
  +fetch <A
   HREF="http://www.you.com/cgi-bin/test.pl">http://www.you.com/cgi-bin/test.pl</A>
   
   
  @@ -295,43 +304,45 @@
     [...snipped]
   </PRE>
   <P>
  -You will see that 2 environment variables <CODE>SERVER_SOFTWARE</CODE> and
  -<CODE>GATEWAY_INTERFACE</CODE> are different from the case above. So you've got the hint how to tell in
  -what mode you are running in your cgi scripts. I start all my cgi scripts
  -that are mod_perl aware with:
  +You will see that two variables, <CODE>SERVER_SOFTWARE</CODE> and
  +<CODE>GATEWAY_INTERFACE</CODE>, are different from the case above. This gives you a hint of how to tell
  +in what mode you are running in your cgi scripts. I start all my cgi
  +scripts that are mod_perl aware with:
   
   <P>
   <PRE>  BEGIN {
         # Auto-detect if we are running under mod_perl or CGI.
  -    $USE_MOD_PERL = ( (exists $ENV{'GATEWAY_INTERFACE'} and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
  -                      or exists $ENV{'MOD_PERL'} ) ? 1 : 0;
  +    $USE_MOD_PERL = ((exists $ENV{'GATEWAY_INTERFACE'}
  +                  and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
  +                   or exists $ENV{'MOD_PERL'} );
         # perl5.004 is a must under mod_perl
       require 5.004 if $USE_MOD_PERL;
     }
   </PRE>
   <P>
  -You might wander why in the world you will need to know in what mode you
  +You might wonder why in the world you would need to know in what mode you
   are running. For example you will want to use <CODE>Apache::exit()</CODE>
   and not <CODE>CORE::exit()</CODE> in your scripts, but if you think that your script might be used in both
   environments (mod_cgi vs mod_perl), you will have to override the <CODE>exit()</CODE> subroutine and to make the runtime decision of what method you will use.
  -For reasons and implementations see: <A HREF="././porting.html#using_exit_">Using exit()</A> and the whole <A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs to it</A> page.
  +For reasons and implementations see: <A HREF="././porting.html#using_exit_">Using exit()</A> and the whole
  +<A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs to it</A> page.
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  -<CENTER><H2><A NAME="with_lwp_request">with lwp-request</A></H2></CENTER>
  +<CENTER><H2><A NAME="Testing_via_lwp_request">Testing via lwp-request</A></H2></CENTER>
   <P>
   Yet another one. Why do I show all these approaches? While here they are
   serving a very simple purpose, they can be helpful in other situations. 
   
   <P>
  -Assuming you have the libwww-perl package installed (LWP), you will need it
  -installed for passing the mod_perl's <CODE>make test</CODE> anyway.
  +Assuming you have the libwww-perl (LWP) package installed (you will need it
  +installed in order to pass mod_perl's <CODE>make test</CODE> anyway):
   
   <P>
   <PRE>  % lwp-request -e -d www.site.com
   </PRE>
   <P>
  -Will show you all the headers.
  +Will show you all the headers. (The <CODE>-d</CODE> option disables printing the response content.) 
   
   <P>
   <PRE>  % lwp-request -e -d www.site.com | egrep '^Server:'
  @@ -343,13 +354,13 @@
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <CENTER><H1><A NAME="Starting_to_use_the_server">Starting to use the server</A></H1></CENTER>
   <P>
  -Now you want to writing the cgis. You better start writing it very clean
  -and with understanding of the new running environment. You have to learn
  -how to write correctly for mod_perl. There is nothing new here, all you
  -have to remember that your script wouldn't die after it finishes to serve
  -the request, but will stay in memory and might affect all other scripts
  -running under the same server process (child). You will read more about it
  -in the following sections: <A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs</A>
  +Now you are ready to start writing CGIs. Note here -- you had better start
  +writing your scripts with an eye towards making them clean (i.e., <CODE>use strict;</CODE>), and with understanding of the new running environment. You have to learn
  +how to write correctly for mod_perl. This is nothing new, the major item to
  +remember is that your script won't die after it finishes serving the
  +request, but will stay in memory and might affect all other scripts running
  +under the same server process (child). You will read more about it in the
  +following sections: <A HREF="././porting.html#">Writing Mod Perl scripts and Porting plain CGIs</A>
   
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
  @@ -365,7 +376,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/23/99 
  +	     <BR>Last Modified at 03/01/99 
         </FONT>
       </B>
     </TD>
  
  
  
  1.8       +13 -1     modperl-site/guide/status.html
  
  Index: status.html
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/status.html,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- status.html	1999/01/23 18:06:55	1.7
  +++ status.html	1999/03/16 08:20:25	1.8
  @@ -23,6 +23,7 @@
   
   		<LI><A HREF="#Configuration">Configuration</A>
   		<LI><A HREF="#Usage">Usage</A>
  +		<LI><A HREF="#Compiled_Registry_Scripts_sectio">Compiled Registry Scripts section seems to be empty.</A>
   	</UL>
   
   </UL>
  @@ -108,6 +109,17 @@
   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...
   
  +<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.
  +
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
   
  @@ -122,7 +134,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/16/99 
  +	     <BR>Last Modified at 03/15/99 
         </FONT>
       </B>
     </TD>
  
  
  
  1.8       +41 -2     modperl-site/guide/warnings.html
  
  Index: warnings.html
  ===================================================================
  RCS file: /export/home/cvs/modperl-site/guide/warnings.html,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- warnings.html	1999/01/23 18:06:55	1.7
  +++ warnings.html	1999/03/16 08:20:26	1.8
  @@ -33,6 +33,8 @@
   	<LI><A HREF="#Callback_called_exit">Callback called exit</A>
   	<LI><A HREF="#Out_of_memory_">Out of memory!</A>
   	<LI><A HREF="#_warn_child_process_30388_did_n">[warn] child process 30388 did not exit, sending another SIGHUP</A>
  +	<LI><A HREF="#RegistryLoader_Cannot_translate">RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl</A>
  +	<LI><A HREF="#Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A>
   </UL>
   <!-- INDEX END -->
   
  @@ -346,7 +348,7 @@
   to your PerlScript, it will allocate the $^M emergency pool and the
   $SIG{__DIE__} handler will call Carp::confess, giving you a stack trace
   which should reveal where the problem is. See the Apache::Resource module
  -for prevention of spinning httpds. 
  +for prevention of spinning httpds.
   
   <P>
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  @@ -359,6 +361,43 @@
   restart. If your code does not contain and <STRONG>END</STRONG> blocks or <STRONG>DESTROY</STRONG> methods which need to be run during child server shutdown, this destruction
   can be avoided by setting the <EM>PERL_DESTRUCT_LEVEL</EM> environment variable to <CODE>-1</CODE>.
   
  +<P>
  +<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  +<CENTER><H1><A NAME="RegistryLoader_Cannot_translate">RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl</A></H1></CENTER>
  +<P>
  +<PRE>  RegistryLoader: Cannot translate the URI /home/httpd/perl/test.pl
  +              into a real path to the filename. Please refer to the
  +              manpage for more information
  +              or use the complete method's call like:
  +              $r-&gt;handler(uri,filename);\n&quot;;
  +</PRE>
  +<P>
  +This warning shows up when RegistryLoader fails to translate the URI into
  +the corresponding filesystem path. Most of failures happen when one passes
  +a file path instead of URI. (A reminder: /home/httpd/perl/test.pl is a file
  +path, while /perl/test.pl is an URI). In most cases all you have to do is
  +to path something that RegistryLoader expects to get - the URI, but there
  +are more complex cases, RegistryLoader's man page shows how to handle these
  +cases as well (watch for the <CODE>trans()</CODE> sub).
  +
  +<P>
  +<P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
  +<CENTER><H1><A NAME="Evil_things_might_happen_when_us">Evil things might happen when using PerlFreshRestart</A></H1></CENTER>
  +<P>
  +Not all Perl modules can survive a reload. PerlFreshRestart does nothing
  +more than:
  +
  +<P>
  +while (my($k,$v) = each %INC) { delete $INC{$k}; require $k; }
  +
  +<P>
  +Besides that, it flushes the Apache::Registry cache, and empties any
  +dynamic stacked handlers (e.g. PerlChildInitHandler).
  +
  +<P>
  +Lots of SegFaults and other problems were reported by users who have turned <CODE>PerlFreshRestart</CODE>  <STRONG>On</STRONG>. Most of them have gone away when it was turned off. It doesn't mean that
  +you shouldn't use it, if it works for you. Just be aware of the dragons...
  +
   <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR WIDTH="100%"></P>
   <P><A HREF="index.html">[Back to the main page]</A></P>
   
  @@ -373,7 +412,7 @@
       <B>
         <FONT SIZE=-1>
   	     Written by <A HREF="help.html#author">Stas Bekman</A>.
  -	     <BR>Last Modified at 01/16/99 
  +	     <BR>Last Modified at 03/15/99 
         </FONT>
       </B>
     </TD>
  
  
  
  1.1                  modperl-site/guide/guide.tar.gz
  
  	<<Binary file>>
  
  

Mime
View raw message