You are viewing a plain text version of this content. The canonical link for it is here.
Posted to modperl-cvs@perl.apache.org by sb...@locus.apache.org on 2000/08/21 15:18:24 UTC
cvs commit: modperl-site/guide CHANGES config.html control.html correct_headers.html help.html index.html index_long.html install.html mod_perl_guide.pdf.gz performance.html perl.html porting.html scenario.html security.html snippets.html strategy.html troubleshooting.html obvious.html
sbekman 00/08/21 06:18:23
Modified: guide CHANGES config.html control.html
correct_headers.html help.html index.html
index_long.html install.html mod_perl_guide.pdf.gz
performance.html perl.html porting.html
scenario.html security.html snippets.html
strategy.html troubleshooting.html
Removed: guide obvious.html
Log:
* mod_perl guide's build process is now completely migrated into an
external module, distributed in package Pod::HtmlPSPdf.
* install.pod: Raven SSL installation notes updated (Doug, Geoffrey
Young)
* troubleshooting.pod: install_driver(Oracle) failed: Can't load
'.../DBD/Oracle/Oracle.so' for module DBD::Oracle (Yann Ramin,
Richard Chen)
* security.pod: a code sample in "Non authenticated access for
internal IPs, Authenticated for external IPs" is corrected (Will
Trillich)
* porting.pod: "CHECK Blocks" (Doug)
* scenario.pod: "The dual server installation scenario was complete
rewritten, to accomodate a better in my opinion directories layout
and simpler installation process"
* perl.pod: "Exception Handling for mod_perl" was improved by Matt
Sergeant.
* Minor corrections:
o config (Ron Pero)
Revision Changes Path
1.26 +26 -0 modperl-site/guide/CHANGES
Index: CHANGES
===================================================================
RCS file: /home/cvs/modperl-site/guide/CHANGES,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -r1.25 -r1.26
--- CHANGES 2000/08/05 20:48:04 1.25
+++ CHANGES 2000/08/21 13:18:00 1.26
@@ -2,6 +2,32 @@
### mod_perl Guide CHANGES file ###
###################################
+08.21.2000 ver 1.26
+
+* mod_perl guide's build process is now completely migrated into an
+ external module, distributed in package Pod::HtmlPSPdf.
+
+* install.pod: Raven SSL installation notes updated (Doug, Geoffrey
+ Young)
+
+* troubleshooting.pod: install_driver(Oracle) failed: Can't load
+ '.../DBD/Oracle/Oracle.so' for module DBD::Oracle (Yann Ramin,
+ Richard Chen)
+
+* security.pod: a code sample in "Non authenticated access for
+ internal IPs, Authenticated for external IPs" is corrected (Will
+ Trillich)
+
+* porting.pod: "CHECK Blocks" (Doug)
+
+* scenario.pod: "The dual server installation scenario was complete
+ rewritten, to accomodate a better in my opinion directories layout
+ and simpler installation process"
+
+* perl.pod: "Exception Handling for mod_perl" was improved by Matt.
+
+* Minor corrections:
+ o config (Ron Pero)
08.05.2000 ver 1.25
1.28 +11 -10 modperl-site/guide/config.html
Index: config.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/config.html,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -r1.27 -r1.28
--- config.html 2000/08/05 20:48:04 1.27
+++ config.html 2000/08/21 13:18:00 1.28
@@ -52,7 +52,7 @@
<LI><A HREF="#Alias_Configurations">Alias Configurations</A>
<UL>
- <LI><A HREF="#Running_CGI_PerlRun_and_Regist">Running CGI, PerlRun, and Registry Scripts located in the same Directory</A>
+ <LI><A HREF="#Running_CGI_PerlRun_and_Regist">Running CGI, PerlRun, and Registry Scripts Located in the Same Directory</A>
</UL>
<LI><A HREF="#_Location_Configuration"><Location> Configuration</A>
@@ -808,7 +808,7 @@
<P>
where latter directive invokes mod_cgi. You shouldn't use the
<CODE>ScriptAlias</CODE> directive unless you want the request to be processed under mod_cgi.
-Therefore when you configure a mod_perl sections use
+Therefore when you configure mod_perl sections use
<CODE>Alias</CODE> instead.
<P>
@@ -818,8 +818,9 @@
<A HREF="././config.html#Perl_Handlers">Perl*Handlers</A> for more information about handlers for the various request phases.
<P>
-When you have decided what methods to use to run your scripts and where you
-will keep them, you can add the configuration <CODE>directive(s)</CODE> to <EM>httpd.conf</EM>. They will look like those below, but they will of course reflect the
+When you have decided which methods to use to run your scripts and where
+you will keep them, you can add the configuration <CODE>directive(s)</CODE>
+to <EM>httpd.conf</EM>. They will look like those below, but they will of course reflect the
locations of your scripts in your file-system and the decisions you have
made about how to run the scripts:
@@ -846,7 +847,7 @@
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
-<CENTER><H3><A NAME="Running_CGI_PerlRun_and_Regist">Running CGI, PerlRun, and Registry Scripts located in the same Directory</A></H3></CENTER>
+<CENTER><H3><A NAME="Running_CGI_PerlRun_and_Regist">Running CGI, PerlRun, and Registry Scripts Located in the Same Directory</A></H3></CENTER>
<P>
<table>
@@ -881,8 +882,8 @@
<P>
This technique makes it easy to migrate your scripts to mod_perl. If your
script does not seem to be working while running under mod_perl, then in
-most cases you can easily call the script in straight mod_cgi mode without
-making any script changes. Simply change the URL you use to invoke it.
+most cases you can easily call the script in straight mod_cgi mode or under <CODE>Apache::PerlRun</CODE> without making any script changes. Simply change the URL you use to invoke
+it.
<P>
Although in the configuration above we have configured all three
@@ -891,8 +892,8 @@
<P>
You should remember that it is undesirable to run scripts in plain mod_cgi
-mode from a mod_perl-enabled server--the resource consumption is too high,
-it is better to run these on a plain Apache server. See
+mode from a mod_perl-enabled server--the resource consumption is too high.
+It is better to run these on a plain Apache server. See
<A HREF="././strategy.html#Standalone_mod_perl_Enabled_Apac">Standalone mod_perl Enabled Apache Server</A>.
<P>
@@ -4275,7 +4276,7 @@
<td align=center valign=center>
<b><font size=-1>Written by <a
-href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/05/2000
+href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/09/2000
</font></b>
<br>
1.28 +16 -16 modperl-site/guide/control.html
Index: control.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/control.html,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -r1.27 -r1.28
--- control.html 2000/08/05 20:48:04 1.27
+++ control.html 2000/08/21 13:18:01 1.28
@@ -1,7 +1,7 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
- <title>mod_perl guide: Controlling and Monitoring the Server</title>
+ <title>mod_perl guide: Restarting Techniques</title>
<meta name="Author" content="Stas Bekman">
<meta name="Description" content="All Apache/Perl related information: Hints, Guidelines, Scenarios and Troubleshottings">
<meta name="keywords" content="mod_perl modperl perl cgi apache webserver speed fast guide mod_perl apache guide help info faq mod_perl installation cgi troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
@@ -14,7 +14,7 @@
<h1 align=center>
<a href="http://perl.apache.org"><img src="images/mod_perl.gif" alt="Mod Perl Icon" border=0 height=30 width=90 align=left></a>
<a href="http://perl.apache.org"><img src="images/mod_perl.gif" alt="Mod Perl Icon" border=0 height=30 width=90 align=right></a>
- Controlling and Monitoring the Server
+ Restarting Techniques
</h1>
<hr>
<p>
@@ -1226,8 +1226,8 @@
<td>
<pre> /etc/rc.d/init.d/httpd_docs
/etc/rc.d/init.d/httpd_perl
- /etc/rc.d/rc3.d/S86httpd_docs -> ../init.d/httpd_docs
- /etc/rc.d/rc3.d/S86httpd_perl -> ../init.d/httpd_perl
+ /etc/rc.d/rc3.d/S91httpd_docs -> ../init.d/httpd_docs
+ /etc/rc.d/rc3.d/S91httpd_perl -> ../init.d/httpd_perl
/etc/rc.d/rc6.d/K16httpd_docs -> ../init.d/httpd_docs
/etc/rc.d/rc6.d/K16httpd_perl -> ../init.d/httpd_perl</pre>
</td>
@@ -1243,7 +1243,7 @@
<P>
When the system starts (level 3) we want the Apache to be started when
almost all of the services are running already, therefore I've used
-<EM>S86</EM>. For example if the mod_perl enabled Apache issues a
+<EM>S91</EM>. For example if the mod_perl enabled Apache issues a
<CODE>connect_on_init()</CODE> the SQL server should be started before Apache.
<P>
@@ -1259,7 +1259,7 @@
<P>
Under RedHat Linux and similar systems, when a machine is booted and its
runlevel set to 3 (multiuser + network), Linux goes into
-<EM>/etc/rc.d/rc3.d/</EM> and executes the scripts the symbolic links point to with the <CODE>start</CODE> argument. When it sees <EM>S86httpd_perl</EM>, it executes:
+<EM>/etc/rc.d/rc3.d/</EM> and executes the scripts the symbolic links point to with the <CODE>start</CODE> argument. When it sees <EM>S91httpd_perl</EM>, it executes:
<P>
@@ -1341,7 +1341,7 @@
<td>
<pre> # Comments to support chkconfig on RedHat Linux
- # chkconfig: 2345 86 16
+ # chkconfig: 2345 91 16
# description: mod_perl enabled Apache Server</pre>
</td>
@@ -1367,7 +1367,7 @@
# 1997/08/23
# Comments to support chkconfig on RedHat Linux
- # chkconfig: 2345 86 16
+ # chkconfig: 2345 91 16
# description: mod_perl enabled Apache Server
#
@@ -1390,14 +1390,14 @@
</td>
<td>
- <pre> # chkconfig: 2345 86 16</pre>
+ <pre> # chkconfig: 2345 91 16</pre>
</td>
</tr>
</table>
<P>
to your needs. The above setting says to says that the script should be
-started in levels 2, 3, 4, and 5, that its start priority should be 86, and
+started in levels 2, 3, 4, and 5, that its start priority should be 91, and
that its stop priority should be 16.
<P>
@@ -1457,10 +1457,10 @@
/etc/rc.d/init.d/httpd_perl
/etc/rc.d/rc0.d/K16httpd_perl
/etc/rc.d/rc1.d/K16httpd_perl
- /etc/rc.d/rc2.d/S86httpd_perl
- /etc/rc.d/rc3.d/S86httpd_perl
- /etc/rc.d/rc4.d/S86httpd_perl
- /etc/rc.d/rc5.d/S86httpd_perl
+ /etc/rc.d/rc2.d/S91httpd_perl
+ /etc/rc.d/rc3.d/S91httpd_perl
+ /etc/rc.d/rc4.d/S91httpd_perl
+ /etc/rc.d/rc5.d/S91httpd_perl
/etc/rc.d/rc6.d/K16httpd_perl</pre>
</td>
@@ -1480,7 +1480,7 @@
</td>
<td>
- <pre> # chkconfig: 2345 86 16</pre>
+ <pre> # chkconfig: 2345 91 16</pre>
</td>
</tr>
@@ -2855,7 +2855,7 @@
<td align=center valign=center>
<b><font size=-1>Written by <a
-href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/03/2000
+href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/09/2000
</font></b>
<br>
1.11 +0 -0 modperl-site/guide/correct_headers.html
Index: correct_headers.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/correct_headers.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- correct_headers.html 2000/08/05 20:48:04 1.10
+++ correct_headers.html 2000/08/21 13:18:01 1.11
@@ -291,7 +291,7 @@
use Date::Parse;
# Date::Parse parses RCS format, Apache::Util::parsedate doesn't
$Mtime ||=
- Date::Parse::str2time(substr q$Date: 2000/08/05 20:48:04 $, 6);
+ Date::Parse::str2time(substr q$Date: 2000/08/21 13:18:01 $, 6);
$r->set_last_modified($Mtime);</pre>
</td>
1.25 +2 -2 modperl-site/guide/help.html
Index: help.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/help.html,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -r1.24 -r1.25
--- help.html 2000/06/07 22:45:31 1.24
+++ help.html 2000/08/21 13:18:01 1.25
@@ -108,7 +108,7 @@
<P>
Hi, I wrote this document to help people with mod_perl. It does not mean
that if you have any question regarding mod_perl, perl or whatever you
-think I might know, that you should send it directly to me. Please see the <A HREF="#Get_help_with_mod_perl">Get help with mod_perl</A>
+think I might know, that you should send it directly to me. Please see the <A HREF="././help.html#Get_help_with_mod_perl">Get help with mod_perl</A>
section and follow the guidelines described there.
<P>
@@ -668,7 +668,7 @@
<td align=center valign=center>
<b><font size=-1>Written by <a
-href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 05/27/2000
+href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/20/2000
</font></b>
<br>
1.30 +4 -4 modperl-site/guide/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/index.html,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -r1.29 -r1.30
--- index.html 2000/08/05 20:48:05 1.29
+++ index.html 2000/08/21 13:18:02 1.30
@@ -16,13 +16,13 @@
<center>
<p>
<b>
- Deploying mod_perl technology to give the rocket speed to
+ Deploying mod_perl technology to give rocket speed to
your CGI/Perl scripts.
</b>
</p>
</center>
- <center><p><b>Version 1.25 Aug 5, 2000</b></p></center>
+ <center><p><b>Version 1.26 Aug 21, 2000</b></p></center>
<table align=center width="70%">
@@ -78,7 +78,7 @@
<LI><A HREF="config.html">mod_perl Configuration</A></LI>
-<LI><A HREF="control.html">Controlling and Monitoring the Server</A></LI>
+<LI><A HREF="control.html">Restarting Techniques</A></LI>
<LI><A HREF="strategy.html">Choosing the Right Strategy</A></LI>
@@ -325,7 +325,7 @@
<b><font size=-1>
Written by <a
href="help.html#Contacting_me">Stas
- Bekman</a>.<br> Last Modified at 08/05/2000
+ Bekman</a>.<br> Last Modified at 08/21/2000
</font></b>
<br>
1.4 +10 -8 modperl-site/guide/index_long.html
Index: index_long.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/index_long.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- index_long.html 2000/08/05 20:48:05 1.3
+++ index_long.html 2000/08/21 13:18:02 1.4
@@ -16,13 +16,13 @@
<center>
<p>
<b>
- Deploying mod_perl technology to give the rocket speed to
+ Deploying mod_perl technology to give rocket speed to
your CGI/Perl scripts.
</b>
</p>
</center>
- <center><p><b>Version 1.25 Aug 5, 2000</b></p></center>
+ <center><p><b>Version 1.26 Aug 21, 2000</b></p></center>
<table align=center width="70%">
@@ -161,8 +161,8 @@
<LI><A HREF="perl.html#Overriding_the_Core_die_Functi">Overriding the Core die() Function</A>
</UL>
+ <LI><A HREF="perl.html#A_Single_UnCaught_Exception_Clas">A Single UnCaught Exception Class</A>
<LI><A HREF="perl.html#Some_Uses">Some Uses</A>
- <LI><A HREF="perl.html#A_Warning">A Warning</A>
<LI><A HREF="perl.html#Conclusions">Conclusions</A>
<LI><A HREF="perl.html#The_My_Exception_class_in_its_e">The My::Exception class in its entirety</A>
<LI><A HREF="perl.html#Other_Implementations">Other Implementations</A>
@@ -173,7 +173,7 @@
<LI><A HREF="install.html"><B><FONT SIZE=+1>mod_perl Installation</FONT></B></A></LI><P>
<UL>
- <LI><A HREF="install.html#Installing_mod_perl_in_10_Minute">Installing mod_perl in 10 Minutes and 10 Command Lines</A>
+ <LI><A HREF="install.html#A_Summary_of_a_Basic_mod_perl_In">A Summary of a Basic mod_perl Installation</A>
<LI><A HREF="install.html#The_Gory_Details">The Gory Details</A>
<UL>
@@ -360,7 +360,7 @@
<LI><A HREF="config.html#Alias_Configurations">Alias Configurations</A>
<UL>
- <LI><A HREF="config.html#Running_CGI_PerlRun_and_Regist">Running CGI, PerlRun, and Registry Scripts located in the same Directory</A>
+ <LI><A HREF="config.html#Running_CGI_PerlRun_and_Regist">Running CGI, PerlRun, and Registry Scripts Located in the Same Directory</A>
</UL>
<LI><A HREF="config.html#_Location_Configuration"><Location> Configuration</A>
@@ -419,7 +419,7 @@
<LI><A HREF="config.html#Adding_Custom_Configuration_Dire">Adding Custom Configuration Directives </A>
</UL>
<P>
-<LI><A HREF="control.html"><B><FONT SIZE=+1>Controlling and Monitoring the Server</FONT></B></A></LI><P>
+<LI><A HREF="control.html"><B><FONT SIZE=+1>Restarting Techniques</FONT></B></A></LI><P>
<UL>
<LI><A HREF="control.html#Restarting_Techniques">Restarting Techniques</A>
@@ -640,7 +640,8 @@
<LI><A HREF="porting.html#NPH_Non_Parsed_Headers_scripts">NPH (Non Parsed Headers) scripts</A>
<LI><A HREF="porting.html#BEGIN_blocks">BEGIN blocks </A>
<LI><A HREF="porting.html#END_blocks">END blocks</A>
- <LI><A HREF="porting.html#Command_line_Switches_w_T_e">Command line Switches (-w, -T, etc)</A>
+ <LI><A HREF="porting.html#CHECK_Blocks">CHECK Blocks</A>
+ <LI><A HREF="porting.html#Command_Line_Switches_w_T_e">Command Line Switches (-w, -T, etc)</A>
<UL>
<LI><A HREF="porting.html#Warnings">Warnings</A>
@@ -864,6 +865,7 @@
<UL>
<LI><A HREF="troubleshooting.html#libexec_libperl_so_open_failed_">libexec/libperl.so: open failed: No such file or directory</A>
+ <LI><A HREF="troubleshooting.html#install_driver_Oracle_failed_C">install_driver(Oracle) failed: Can't load '.../DBD/Oracle/Oracle.so' for module DBD::Oracle</A>
<LI><A HREF="troubleshooting.html#Invalid_command_PerlHandler_">Invalid command 'PerlHandler'...</A>
<LI><A HREF="troubleshooting.html#RegistryLoader_Translation_of_u">RegistryLoader: Translation of uri [...] to filename failed</A>
<LI><A HREF="troubleshooting.html#_Apache_pm_failed_to_load_">"Apache.pm failed to load!"</A>
@@ -1486,7 +1488,7 @@
<b><font size=-1>
Written by <a
href="help.html#Contacting_me">Stas
- Bekman</a>.<br> Last Modified at 08/05/2000
+ Bekman</a>.<br> Last Modified at 08/21/2000
</font></b>
<br>
1.17 +212 -19 modperl-site/guide/install.html
Index: install.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/install.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- install.html 2000/08/05 20:48:05 1.16
+++ install.html 2000/08/21 13:18:02 1.17
@@ -34,7 +34,7 @@
<UL>
- <LI><A HREF="#Installing_mod_perl_in_10_Minute">Installing mod_perl in 10 Minutes and 10 Command Lines</A>
+ <LI><A HREF="#A_Summary_of_a_Basic_mod_perl_In">A Summary of a Basic mod_perl Installation</A>
<LI><A HREF="#The_Gory_Details">The Gory Details</A>
<UL>
@@ -240,11 +240,11 @@
<HR>
<P>
-<CENTER><H1><A NAME="Installing_mod_perl_in_10_Minute">Installing mod_perl in 10 Minutes and 10 Command Lines</A></H1></CENTER>
+<CENTER><H1><A NAME="A_Summary_of_a_Basic_mod_perl_In">A Summary of a Basic mod_perl Installation</A></H1></CENTER>
<P>
-Did you know that it takes about 10 minutes to build and install mod_perl
-enabled Apache on a pretty average processor with a decent amount of system
-memory? It goes like this:
+The following 10 commands summarize the execution steps required to build
+and install a basic mod_perl enabled Apache server on almost any standard
+flavor of Unix OS.
<P>
@@ -272,15 +272,9 @@
</tr>
</table>
<P>
-That's all!
-
-<P>
-* Of course you should replace <EM>x.xx</EM> and <EM>x.x.x</EM> with the real version numbers of mod_perl and Apache.
+Of course you should replace <EM>x.xx</EM> and <EM>x.x.x</EM> with the real version numbers of mod_perl and Apache.
<P>
-* The GNU <CODE>tar</CODE> utility knows how to uncompress (the <CODE>z</CODE> flag).
-
-<P>
All that's left is to add a few configuration lines to <CODE>httpd.conf</CODE>, the Apache configuration file, start the server and enjoy mod_perl.
<P>
@@ -289,7 +283,7 @@
<P>
Of course there is a way of installing mod_perl in only a couple of minutes
-if you are using a Linux distrbution that uses RPM or deb files:
+if you are using a Linux distribution that uses RPM or deb files:
<P>
@@ -3453,9 +3447,206 @@
</tr>
</table>
+ <P>
+This is an example of setup scenario:
+
+<UL>
+<P><LI>
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> Please select the directory where you want to
+ install Raven SSL and related packages
+ Directory [/usr/local] -> </pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+Accept the default or supply a different directory.
+
+<P><LI>
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> Installing the Apache binary is the easiest
+ and quickest way to secure Apache with Raven SSL.
+ Do you want to install Apache? [Y/n] -> n</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+Answer <CODE>n</CODE>, we want to install it from mod_perl sources.
+
+<P><LI>
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> Please select the directory where you want to
+ install Raven SSL.
+ Directory [/usr/local/raven] -> </pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+Accept the default or supply a different directory.
+
+<P><LI>
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> Apache will not be installed
+ Raven SSL will be installed in:
+ /usr/local/raven</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+Sure, we know that :)
+
+<P><LI>
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> Do you want to proceed with installation? [Y/n] -> Y</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+Yes, we want to proceeed.
+
+<P><LI>
+<P>
+Now Raven completes the installation of its files.
+
+</UL>
+<P><LI>
+<P>
+Now it's a time to patch the Apache source with Raven.
+
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> % /usr/local/raven/bin/raven_admin_tls
+ select Option 1, 'Export Raven'</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+Note: this option exports the required EAPI patches and the needed Raven
+SSL module files into your Apache source tree
+
+<UL>
+<P><LI>
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> Choose Apache version to export to:
+ Available Apache versions :
+ (1) 1.3.12
+ Selection? -> 1</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+Choose the version you want to build Raven with.
+
+<P><LI>
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> Export Raven SSL Module to Apache source root:
+ Apache source root directory [] -> </pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+Specify the Apache source root directory, e.g.:
+
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> /usr/src/apache-1.x.x</pre>
+ </td>
+
+ </tr>
+ </table>
<P><LI>
<P>
+Back to the main menu:
+<P>
+
<table>
<tr>
@@ -3464,17 +3655,19 @@
</td>
<td>
- <pre> % /usr/local/raven/bin/ravenctl
- select Option 1, 'Raven SSL Module Manager'
- select Option 2, 'Export Raven SSL module to Apache source'</pre>
+ <pre> Choose an action :
+ (1) Export Raven SSL
+ (2) Upgrade Raven SSL
+ (3) Exit
+ Selection? [1] -> 3</pre>
</td>
</tr>
</table>
<P>
-Note: Option 2 exports the required EAPI patches and the needed Raven SSL
-module files into your Apache source tree
+Choose 3 to finish.
+</UL>
<P><LI>
<P>
@@ -6483,7 +6676,7 @@
<td align=center valign=center>
<b><font size=-1>Written by <a
-href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/03/2000
+href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/21/2000
</font></b>
<br>
1.7 +4847 -4746modperl-site/guide/mod_perl_guide.pdf.gz
<<Binary file>>
1.29 +170 -13 modperl-site/guide/performance.html
Index: performance.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/performance.html,v
retrieving revision 1.28
retrieving revision 1.29
diff -u -r1.28 -r1.29
--- performance.html 2000/08/05 20:48:07 1.28
+++ performance.html 2000/08/21 13:18:08 1.29
@@ -5208,7 +5208,8 @@
<HR>
<CENTER><H2><A NAME="PerlSetupEnv_Off">PerlSetupEnv Off</A></H2></CENTER>
<P>
-<CODE>PerlSetupEnv Off</CODE> is another optimization you might consider.
+<CODE>PerlSetupEnv Off</CODE> is another optimization you might consider. This directive requires
+mod_perl 1.25 or later.
<P>
<EM>mod_perl</EM> fiddles with the environment to make it appear as if the script were being
@@ -5218,13 +5219,14 @@
<P>
But <CODE>%ENV</CODE> population is expensive. Those who have moved to the Perl Apache API no
-longer need this extra <CODE>%ENV</CODE> population, and can gain by turning it <STRONG>Off</STRONG>.
+longer need this extra <CODE>%ENV</CODE> population, and can gain by turning it <STRONG>Off</STRONG>. Scripts using the <CODE>CGI.pm</CODE> module require
+<CODE>PerlSetupEnv On</CODE> because that module relies on a properly populated CGI environment table.
<P>
By default it is On.
<P>
-Note that you can still set enviroment variables. For example when you use
+Note that you can still set environment variables. For example when you use
the following configuration:
<P>
@@ -5237,9 +5239,10 @@
</td>
<td>
- <pre> PerlModule Apache::RegistryNG
+ <pre> PerlSetupEnv Off
+ PerlModule Apache::RegistryNG
<Location /perl>
- PerlSetupEnv Off
+ PerlSetupEnv On
PerlSetEnv TEST hi
SetHandler perl-script
PerlHandler Apache::RegistryNG
@@ -5289,7 +5292,7 @@
<td>
<pre> $VAR1 = {
'GATEWAY_INTERFACE' => 'CGI-Perl/1.1',
- 'MOD_PERL' => 'mod_perl/1.22',
+ 'MOD_PERL' => 'mod_perl/1.25',
'PATH' => '/usr/lib/perl5/5.00503:... snipped ...',
'TEST' => 'hi'
};</pre>
@@ -5363,11 +5366,7 @@
</tr>
</table>
<P>
-You can blame the default installed <CODE>TransHandler</CODE> for this inefficiency. Of course you could supply your own, which will be
-smart enough not to look for this virtual path and immediately return
-<CODE>OK</CODE>. But in cases where you have a virtual host that serves only dynamically
-generated documents, you can override the default
-<CODE>PerlTransHandler</CODE> with this one:
+How expensive those calls are? Let's use the <CODE>Time::HiRes</CODE> module to find out.
<P>
@@ -5379,6 +5378,164 @@
</td>
<td>
+ <pre> stat_call_sample.pl
+ -------------------
+ use Time::HiRes qw(gettimeofday tv_interval);
+ my $calls = 1_000_000;
+
+ my $start_time = [ gettimeofday ];
+
+ stat "/foo" for 1..$calls;
+
+ my $end_time = [ gettimeofday ];
+
+ my $elapsed = tv_interval($start_time,$end_time) / $calls;
+
+ print "The average execution time: $elapsed seconds\n";</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+This script takes a time sample at the beginnig, then does 1_000_000
+<CODE>stat()</CODE> calls to a non-existing file, samples the time at the end and prints the
+average time it took to make a single <CODE>stat()</CODE> call. I'm sampling a 1M stats, so I'd get a correct average result.
+
+<P>
+Before we actually run the script one should destinguish between two
+different situation. When the server is idle the time between the first and
+the last system call will be much shorter than the same time measured on
+the loaded system. That is because on the idle system, a process can use
+CPU very often, and on the loaded system lots of processes compete over it
+and each process has to wait for a longer time to get the same amount of
+CPU time.
+
+<P>
+So first we run the above code on the unloaded system:
+
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> % perl stat_call_sample.pl
+ The average execution time: 4.209645e-06 seconds</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+So it takes about 4 microseconds to execute a <CODE>stat()</CODE> call. Now
+let start a CPU intensive process in one console. The following code keeps
+CPU busy all the time.
+
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> % perl -e '1**1 while 1'</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+And now run the <EM>stat_call_sample.pl</EM> script in the other console.
+
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> % perl stat_call_sample.pl
+ The average execution time: 8.777301e-06 seconds</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+You can see that the average time has doubled (about 8 microseconds). And
+this is obvious, since there were two processes competing over CPU. Now if
+run 4 occurences of the above code:
+
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> % perl -e '1**1 while 1' &
+ % perl -e '1**1 while 1' &
+ % perl -e '1**1 while 1' &
+ % perl -e '1**1 while 1' &</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+And when running our script in parallel with this processes, we get:
+
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> % perl stat_call_sample.pl
+ 2.0853558e-05 seconds</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+about 20 microseconds. So the average <CODE>stat()</CODE> system call is 5
+times longer now. Now if you have 50 mod_perl processes that keep the CPU
+busy all the time, the <CODE>stat()</CODE> call will be 50 times slower and
+it'll take 0.2 milliseconds to complete a series of call. If you have five
+redundant calls as in the strace example above, they adds up to one
+millisecond. If you have more processes constantly consuming CPU, this time
+adds up. Now multiply this time by the number of processes that you have
+and you get a few seconds lost. As usual, for some services this loss is
+insignificant, while for others a very significant one.
+
+<P>
+So why Apache does all these redundant <CODE>stat()</CODE> calls? You can blame the default installed <CODE>TransHandler</CODE> for this inefficiency. Of course you could supply your own, which will be
+smart enough not to look for this virtual path and immediately return <CODE>OK</CODE>. But in cases where you have a virtual host that serves only dynamically
+generated documents, you can override the default <CODE>PerlTransHandler</CODE> with this one:
+
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
<pre> <VirtualHost 10.10.10.10:80>
...
PerlTransHandler Apache::OK
@@ -5664,7 +5821,7 @@
</tr>
</table>
<P>
-in the normal way (no <CODE><Perl></CODE> section required.
+in the normal way (no <CODE><Perl></CODE> section required).
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
@@ -9626,7 +9783,7 @@
<td align=center valign=center>
<b><font size=-1>Written by <a
-href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/05/2000
+href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/21/2000
</font></b>
<br>
1.15 +169 -63 modperl-site/guide/perl.html
Index: perl.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/perl.html,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- perl.html 2000/08/05 20:48:07 1.14
+++ perl.html 2000/08/21 13:18:09 1.15
@@ -105,8 +105,8 @@
<LI><A HREF="#Overriding_the_Core_die_Functi">Overriding the Core die() Function</A>
</UL>
+ <LI><A HREF="#A_Single_UnCaught_Exception_Clas">A Single UnCaught Exception Class</A>
<LI><A HREF="#Some_Uses">Some Uses</A>
- <LI><A HREF="#A_Warning">A Warning</A>
<LI><A HREF="#Conclusions">Conclusions</A>
<LI><A HREF="#The_My_Exception_class_in_its_e">The My::Exception class in its entirety</A>
<LI><A HREF="#Other_Implementations">Other Implementations</A>
@@ -3600,7 +3600,9 @@
The reasoning behind this document is the current broken status of
<CODE>$SIG{__DIE__}</CODE> in the perl core - see both the perl5-porters and the mod_perl mailing list
archives for details on this discussion. (It's broken in at least Perl
-v5.6.0 and probably in later versions as well.)
+v5.6.0 and probably in later versions as well). In short summary,
+$SIG{__DIE__} is a little bit too global, and catches exceptions even when
+you want to catch them yourself, using an <CODE>eval{}</CODE> block.
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
@@ -3611,7 +3613,8 @@
the <CODE>eval
EXPR</CODE> construct, which compiles and executes code at run time, but that's not the
case. <CODE>eval{}</CODE> compiles at compile time, just like the rest of your code, and has next to
-zero run-time penalty.
+zero run-time penalty. For the hardcore C programmers among you, it uses
+the <CODE>setjmp/longjmp</CODE> POSIX routines internally, just like C++ exceptions.
<P>
When in an eval block, if the code being executed <CODE>die()'s</CODE> for
@@ -3820,6 +3823,13 @@
However this won't work under <CODE>Apache::Registry</CODE> - you're always in an eval block there!
<P>
+The other problem with <CODE>$SIG{__DIE__}</CODE> also relates to its global nature. Because you might have more than one
+application running under mod_perl, you can't be sure which has set a <CODE>$SIG{__DIE__}</CODE> handler when and for what. This can become extremely confusing when you
+start scaling up from a set of simple registry scripts that might rely on
+CGI::Carp for global exception handling (which uses <CODE>$SIG{__DIE__}</CODE> to trap exceptions) to having many applications installed with a variety of
+exception handling mechanisms in place.
+
+<P>
You should warn people about this danger of <CODE>$SIG{__DIE__}</CODE> and inform them of better ways to code. The following material is an
attempt to do just that.
@@ -3834,13 +3844,22 @@
occurred, in order to construct a sensible error message, and again in your
exception handler to de-construct that string into something meaningful
(unless of course all you want your exception handler to do is dump the
-error to the browser).
+error to the browser). The other problem is that you have no way of
+automatically detecting where the exception occured using <CODE>eval{}</CODE> construct. In a <CODE>$SIG{__DIE__}</CODE>
+block you always have the use of the <CODE>caller()</CODE> function to
+detect where the error occured. But we can fix that...
<P>
A little known fact about exceptions in perl 5.005 is that you can call die
with an object. The exception handler receives that object in
<CODE>$@</CODE>. This is how you are advised to handle exceptions now, as it provides an
-extremely flexible and scalable exceptions solution.
+extremely flexible and scalable exceptions solution, potentially providing
+almost all of the power Java exceptions.
+
+<P>
+[As a footnote here, the only thing that is really missing here from Java
+exceptions is a guaranteed Finally clause, although its possible to get
+about 98.62% of the way towards providing that using <CODE>eval{}</CODE>.]
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
@@ -3852,7 +3871,9 @@
is entered, and then dispatches itself to a routine depending on the
parameters passed and/or the form values. In a normal C program this is
your <CODE>main()</CODE> function, in a mod_perl handler this is your
-<CODE>handler()</CODE> function/method.
+<CODE>handler()</CODE> function/method. The exception to this rule seems to
+be Apache::Registry scripts, although the techniques described here can be
+easily adapted.
<P>
In order for you to be able to use exception handling to its best advantage
@@ -3876,28 +3897,24 @@
# Apache::Registry script
eval {
- dispatch();
+ dispatch();
};
- catch($@);
+ if ($@) {
+ # handle exception
+ }
sub dispatch {
...
}
- sub catch {
- my $exception = shift;
- ...
- }</pre>
+This is easier with an ordinary mod_perl handler as it is natural to
+have separate functions, rather than a long run-on script:</pre>
</td>
</tr>
</table>
<P>
-This is easier with an ordinary mod_perl handler as it is natural to have
-separate functions, rather than a long run-on script:
-<P>
-
<table>
<tr>
@@ -3912,9 +3929,11 @@
my $r = shift;
eval {
- dispatch($r);
+ dispatch($r);
};
- catch ($@);
+ if ($@) {
+ # handle exception
+ }
}
sub dispatch {
@@ -3922,19 +3941,13 @@
...
}
- sub catch {
- my $exception = shift;
- ...
- }</pre>
+Now that the skeleton code is setup, let's create an exception class,
+making use of Perl 5.005's ability to throw exception objects.</pre>
</td>
</tr>
</table>
<P>
-Now that the skeleton code is setup, let's create an exception class,
-making use of Perl 5.005's ability to throw exception objects.
-
-<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<CENTER><H3><A NAME="An_Exception_Class">An Exception Class</A></H3></CENTER>
@@ -3959,13 +3972,13 @@
package My::Exception;
sub AUTOLOAD {
- my ($package, $filename, $line) = caller;
no strict 'refs', 'subs';
if ($AUTOLOAD =~ /.*::([A-Z]\w+)$/) {
my $exception = $1;
*{$AUTOLOAD} =
sub {
- shift;
+ shift;
+ my ($package, $filename, $line) = caller;
push @_, caller => {
package => $package,
filename => $filename,
@@ -4053,7 +4066,10 @@
<P>
All this does is catch your exception and re-throw it. It's not as
dangerous as we stated earlier that <CODE>$SIG{__DIE__}</CODE> can be, because we're actually re-throwing the exception, rather than
-catching it and stopping there.
+catching it and stopping there. Even though $SIG{__DIE__} is a global
+handler, because we are simply re-throwing the exception we can let other
+applications outside of our control simply catch the exception and not
+worry about it.
<P>
There's only one slight buggette left, and that's if some external code
@@ -4110,7 +4126,12 @@
</tr>
</table>
<P>
-We can now let other code happily continue.
+We can now let other code happily continue. Note that there is a bug in
+Perl 5.6 which may affect people here: Stringification does not occur when
+an object is operated on by a regular expression (via the =~ operator). A
+work around is to explicitly stringify using qq double quotes, however that
+doesn't help the poor soul who is using other applications. This bug has
+been fixed in later versions of Perl.
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
@@ -4155,18 +4176,117 @@
if (!ref($_[0])) {
CORE::die My::Exception->UnCaught(text => join('', @_));
}
- CORE::die $_[0];
+ CORE::die $_[0]; # only use first element because its an object
+ }</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+That wasn't so bad, was it? We're relying on Exporter's
+<CODE>export()</CODE> function to do the hard work for us, exporting the
+<CODE>die()</CODE> function into the <CODE>CORE::GLOBAL</CODE> namespace. If we don't want to overload <CODE>die()</CODE> everywhere this
+can still be an extremely useful technique. By just using Exporter's
+default <CODE>import()</CODE> method we can export our new
+<CODE>die()</CODE> method into any package of our choosing. This allows us
+to short-cut the long calling convention and simply <CODE>die()</CODE> with
+a string, and let the system handle the actual construction into an object
+for us.
+
+<P>
+Along with the above overloaded stringification, we now have a complete
+exception system (well, mostly complete. Exception die-hards would argue
+that there's no ``finally'' clause, and no exception stack, but that's
+another topic for another time).
+
+<P>
+[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
+<HR>
+<CENTER><H2><A NAME="A_Single_UnCaught_Exception_Clas">A Single UnCaught Exception Class</A></H2></CENTER>
+<P>
+Until the Perl core gets its own base exception class (which will likely
+happen for Perl 6, but not sooner), it is vitally important that you decide
+upon a single base exception class for all of the applications that you
+install on your server, and a single exception handling technique. The
+problem comes when you have multiple applications all doing exception
+handling and all expecting a certain type of ``UnCaught'' exception class.
+Witness the following application:
+
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> package Foo;
+
+ eval {
+ # do something
+ }
+ if ($@) {
+ if ($@->isa('Foo::Exception::Bar')) {
+ # handle "Bar" exception
+ }
+ elsif ($@->isa('Foo::Exception::UnCaught')) {
+ # handle uncaught exceptions
+ }
+ }</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+All will work well until someone installs application ``TrapMe'' on the
+same machine, which installs its own UnCaught exception handler,
+overloading CORE::GLOBAL::die or installing a $SIG{__DIE__} handler. This
+is actually a case where using $SIG{__DIE__} might actually be preferable,
+because you can change your <CODE>handler()</CODE> routine to look like
+this:
+
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> sub handler {
+ my $r = shift;
+
+ local $SIG{__DIE__};
+ Foo::Exception->Init(); # sets $SIG{__DIE__}
+
+ eval {
+ dispatch($r);
+ };
+ if ($@) {
+ # handle exception
+ }
+ }
+
+ sub dispatch {
+ my $r = shift;
+ ...
}</pre>
</td>
</tr>
</table>
<P>
-That wasn't so bad, was it? We're relying on Exporter's export function to
-do the hard work for us, exporting the <CODE>die()</CODE> function into the <CODE>CORE::GLOBAL</CODE> namespace. Along with the above overloaded stringification, we now have a
-complete exception system (well, mostly complete. Exception die-hards would
-argue that there's no ``finally'' clause, and no exception stack, but
-that's another topic for another time).
+In this case the very nature of $SIG{__DIE__} being a lexical variable has
+helped us, something we couldn't fix with overloading CORE::GLOBAL::die.
+However there is still a gotcha. If someone has overloaded
+<CODE>die()</CODE> in one of the applications installed on your mod_perl
+machine, you get the same problems still. So in short: Watch out, and check
+the source code of anything you install to make sure it follows your
+exception handling technique, or just uses <CODE>die()</CODE> with strings.
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
@@ -4174,10 +4294,10 @@
<CENTER><H2><A NAME="Some_Uses">Some Uses</A></H2></CENTER>
<P>
I'm going to come right out and say now: I abuse this system horribly! I
-throw exceptions all over my code, not because I've hit an exceptional bit
-of code, but because I want to get straight back out of the current
-function, without having to have every single level of function call check
-error codes. One way I use this is to return Apache return codes:
+throw exceptions all over my code, not because I've hit an ``exceptional''
+bit of code, but because I want to get straight back out of the current
+call stack, without having to have every single level of function call
+check error codes. One way I use this is to return Apache return codes:
<P>
@@ -4233,21 +4353,6 @@
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
-<CENTER><H2><A NAME="A_Warning">A Warning</A></H2></CENTER>
-<P>
-Just a brief warning about this system. Because mod_perl can run several
-different applications at once, it becomes very important that you only
-have one exception class that either sets <CODE>$SIG{__DIE__}</CODE>, or overloads <CODE>CORE::die</CODE>. This can be quite problematic, because several different modules might
-set their own <CODE>$SIG{__DIE__}</CODE>
-handler, or maybe even overload <CODE>CORE::die</CODE>. For this reason I suggest that you very carefully consider your options
-for blessing uncaught exceptions into your own exceptions class. Also note
-that the last module to be imported that overloads <CODE>CORE::die</CODE> will be the one used. In short: Make sure you have a tight policy for
-controlling exceptions not just for your application--but for your entire
-server.
-
-<P>
-[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
-<HR>
<CENTER><H2><A NAME="Conclusions">Conclusions</A></H2></CENTER>
<P>
Here I've demonstrated a simple and scalable (and useful) exception
@@ -4286,7 +4391,8 @@
sub import {
my $pkg = shift;
- $pkg->export('CORE::GLOBAL', 'die');
+ # allow "use My::Exception 'die';" to mean import locally only
+ $pkg->export('CORE::GLOBAL', 'die') unless @_;
Exporter::import($pkg,@_);
}
@@ -4343,7 +4449,9 @@
<P><LI><STRONG><A NAME="item_Error">Error.pm</A></STRONG>
<P>
Graham Barr's excellent OO styled ``try, throw, catch'' module (from
-<A HREF="././download.html#Perl">CPAN</A>).
+<A HREF="././download.html#Perl">CPAN</A>). This should be considered your best option for structured exception
+handling because it is well known and well supported and used by a lot of
+other applications.
<P><LI><STRONG><A NAME="item_Exception">Exception.pm and StackTrace.pm</A></STRONG>
<P>
@@ -4358,12 +4466,10 @@
<P><LI><STRONG><A NAME="item_Try">Try.pm</A></STRONG>
<P>
-Tony Olekshy's. Adds an unwind stack. Not on CPAN (yet?).
+Tony Olekshy's. Adds an unwind stack and some other interesting features.
+Not on the CPAN. Available at <A
+HREF="http://www.avrasoft.com/perl/rfc/try-1136.zip">http://www.avrasoft.com/perl/rfc/try-1136.zip</A>
-<P><LI><STRONG><A NAME="item_Exceptions">Exceptions.pm</A></STRONG>
-<P>
-Peter Seibel's <CODE>Exceptions</CODE> module doesn't work with modern Perl and has been superceded by Graham
-Barr's <CODE>Error</CODE> module.
</UL>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
@@ -4419,7 +4525,7 @@
<td align=center valign=center>
<b><font size=-1>Written by <a
-href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 07/27/2000
+href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/14/2000
</font></b>
<br>
1.30 +36 -5 modperl-site/guide/porting.html
Index: porting.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/porting.html,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -r1.29 -r1.30
--- porting.html 2000/08/05 20:48:08 1.29
+++ porting.html 2000/08/21 13:18:09 1.30
@@ -85,7 +85,8 @@
<LI><A HREF="#NPH_Non_Parsed_Headers_scripts">NPH (Non Parsed Headers) scripts</A>
<LI><A HREF="#BEGIN_blocks">BEGIN blocks </A>
<LI><A HREF="#END_blocks">END blocks</A>
- <LI><A HREF="#Command_line_Switches_w_T_e">Command line Switches (-w, -T, etc)</A>
+ <LI><A HREF="#CHECK_Blocks">CHECK Blocks</A>
+ <LI><A HREF="#Command_Line_Switches_w_T_e">Command Line Switches (-w, -T, etc)</A>
<UL>
<LI><A HREF="#Warnings">Warnings</A>
@@ -4285,8 +4286,38 @@
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
-<CENTER><H1><A NAME="Command_line_Switches_w_T_e">Command line Switches (-w, -T, etc)</A></H1></CENTER>
+<CENTER><H1><A NAME="CHECK_Blocks">CHECK Blocks</A></H1></CENTER>
<P>
+-- available since perl5.6.0
+
+<P>
+This block runs when compilation is complete, but before the program
+starts. <STRONG>CHECK</STRONG> can mean ``checkpoint'' or ``double-check'' or even jus ``stop'').
+
+<P>
+Perl only calls <STRONG>CHECK</STRONG> blocks during <CODE>perl_parse(),</CODE> which mod_perl calls once at
+startup time. Therefore <STRONG>CHECK</STRONG> blocks don't work for the same reason this doesn't:
+
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> % perl -e 'eval qq(CHECK { print "ok\n" })'</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
+<HR>
+<CENTER><H1><A NAME="Command_Line_Switches_w_T_e">Command Line Switches (-w, -T, etc)</A></H1></CENTER>
+<P>
Normally when you run perl from the command line, you have the shell invoke
it with <CODE>#!/bin/perl</CODE> (sometimes referred to as the shebang line). In scripts running under
mod_cgi, you may use perl execution switch arguments as described in the <CODE>perlrun</CODE> manpage, such as
@@ -4841,7 +4872,7 @@
<HR>
<CENTER><H1><A NAME="Code_has_been_changed_but_it_se">Code has been changed, but it seems the script is running the old code</A></H1></CENTER>
<P>
-Files pulled in via <STRONG>use</STRONG> or <STRONG>require</STRONG> statements are not automatically reloaded when they change on disk. See <A HREF="#Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A> for more info.
+Files pulled in via <STRONG>use</STRONG> or <STRONG>require</STRONG> statements are not automatically reloaded when they change on disk. See <A HREF="././porting.html#Reloading_Modules_and_Required_F">Reloading Modules and Required Files</A> for more info.
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
@@ -4881,7 +4912,7 @@
</tr>
</table>
<P>
-See <A HREF="#Apache_PerlRun_a_closer_look">Apache::PerlRun--a closer look</A>
+See <A HREF="././porting.html#Apache_PerlRun_a_closer_look">Apache::PerlRun--a closer look</A>
@@ -5894,7 +5925,7 @@
<td align=center valign=center>
<b><font size=-1>Written by <a
-href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/03/2000
+href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/20/2000
</font></b>
<br>
1.28 +108 -211 modperl-site/guide/scenario.html
Index: scenario.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/scenario.html,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -r1.27 -r1.28
--- scenario.html 2000/08/05 20:48:08 1.27
+++ scenario.html 2000/08/21 13:18:10 1.28
@@ -694,17 +694,19 @@
<CENTER><H1><A NAME="One_Plain_and_One_mod_perl_enabl">One Plain and One mod_perl enabled Apache Servers</A></H1></CENTER>
<P>
Since we are going to run two Apache servers we will need two complete (and
-different) sets of configuration, log and other files. 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. From now on I will refer to
-these two servers as <STRONG>httpd_docs</STRONG> (plain Apache) and
-<STRONG>httpd_perl</STRONG> (Apache/mod_perl).
+different) sets of configuration, log and other files. In this scenario
+we'll use a dedicated root directory for each server, which is a personal
+choice. You can choose to have both servers living under the same roof, but
+it might lead to a mess, since it requires a slightly more complicated
+configuration. This decision might be nice since you will be able to share
+some directories like <EM>include</EM>
+(which contains Apache headers), but in fact this can become a problem
+later, when you decide to upgrade one server but not the other. You will
+have to solve this problem then, so why not to avoid it in first place.
<P>
-For this illustration, we will use <EM>/usr/local</EM> as our <EM>root</EM>
-directory. The Apache installation directories will be stored under this
-root. (<EM>/usr/local/bin</EM>, <EM>/usr/local/lib</EM> and so on.)
+From now on we will refer to these two servers as <STRONG>httpd_docs</STRONG> (plain Apache) and <STRONG>httpd_perl</STRONG> (Apache/mod_perl). We will use
+<EM>/usr/local</EM> as our <EM>root</EM> directory.
<P>
First let's prepare the sources. We will assume that all the sources go
@@ -715,7 +717,7 @@
<P>
Having two independent source trees will prove helpful unless you use
-dynamically shared objects (<CODE>DSO</CODE>) which is covered later in this section.
+dynamically shared objects (<CODE>DSO</CODE>) which is covered later in this chapter.
<P>
Make two subdirectories:
@@ -818,8 +820,9 @@
</tr>
</table>
<P>
-Time to decide on the desired directory structure layout (where the Apache
-files go):
+We are going to use a default Apache directory layout, and place each
+server directories under its dedicated directory. The two directories are
+as you have already guessed:
<P>
@@ -831,78 +834,13 @@
</td>
<td>
- <pre> ROOT = /usr/local</pre>
+ <pre> /usr/local/httpd_perl/
+ /usr/local/httpd_docs/</pre>
</td>
</tr>
</table>
<P>
-The two servers can share the following directories (so we will not
-duplicate data):
-
-<P>
-
- <table>
- <tr>
-
- <td bgcolor="blue" width="1">
-
- </td>
-
- <td>
- <pre> /usr/local/bin/
- /usr/local/lib
- /usr/local/include/
- /usr/local/man/
- /usr/local/share/</pre>
- </td>
-
- </tr>
- </table>
- <P>
-<STRONG>Important:</STRONG> we assume that both servers are built from the same Apache source version.
-
-<P>
-The two servers will store their specific files in either the
-<EM>httpd_docs/</EM> or the <EM>httpd_perl/</EM> sub-directories:
-
-<P>
-
- <table>
- <tr>
-
- <td bgcolor="blue" width="1">
-
- </td>
-
- <td>
- <pre> /usr/local/etc/httpd_docs/
- httpd_perl/
-
- /usr/local/sbin/httpd_docs/
- httpd_perl/
-
- /usr/local/var/httpd_docs/logs/
- proxy/
- run/
- httpd_perl/logs/
- proxy/
- run/</pre>
- </td>
-
- </tr>
- </table>
- <P>
-After completion of the compilation and the installation of both servers,
-you will need to configure them.
-
-<P>
-To make things clear before we proceed to the details, you should for
-example configure the plain Apache server (<EM>/usr/local/etc/httpd_docs/httpd.conf</EM>) to listen to <CODE>Port 80</CODE>. Configure the mod_perl Apache server (<EM>/usr/local/etc/httpd_perl/httpd.conf</EM>) with a different <CODE>Port</CODE>
-(e.g. 8080) from the one which the plain Apache server listens to. The port
-numbers issue will be discussed later.
-
-<P>
The next step is to configure and compile the sources: Below are the
procedures to compile both servers, using the directory layout I have just
suggested.
@@ -912,8 +850,11 @@
<HR>
<CENTER><H2><A NAME="Configuration_and_Compilation_of">Configuration and Compilation of the Sources.</A></H2></CENTER>
<P>
-I will use x.x.x instead of real version numbers so this document will
-never become obsolete :).
+As usual we use <EM>x.x.x</EM> instead of real version numbers so this document will never become
+obsolete. But the most important thing -- it's not misleading. It's quite
+possible that since the moment this document was written a new version has
+come out and you will be not aware of this fact if you will not check for
+it.
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
@@ -933,22 +874,20 @@
<td>
<pre> % cd /usr/src/httpd_docs/apache_x.x.x
% make clean
- % env CC=gcc \
- ./configure --prefix=/usr/local \
- --sbindir=/usr/local/sbin/httpd_docs \
- --sysconfdir=/usr/local/etc/httpd_docs \
- --localstatedir=/usr/local/var/httpd_docs \
- --runtimedir=/usr/local/var/httpd_docs/run \
- --logfiledir=/usr/local/var/httpd_docs/logs \
- --proxycachedir=/usr/local/var/httpd_docs/proxy</pre>
+ % ./configure --prefix=/usr/local/httpd_docs \
+ --enable-module=rewrite --enable-module=proxy</pre>
</td>
</tr>
</table>
<P>
-Notice that you actually don't have to enlist all these options, it's
-enough to replace them all with <CODE>--target=httpd_docs</CODE>.
+We need the <EM>mod_rewrite</EM> and <EM>mod_proxy</EM> modules as we will see later, so we tell <EM>./configure</EM> to build them in.
+
+<P>
+You might want to add <CODE>--layout</CODE> to see the resulting directories' layout without actually running the
+configuration process.
+<P><DT><STRONG><A NAME="item_Source">Source Compilation and Installation</A></STRONG><DD>
<P>
<table>
@@ -959,21 +898,14 @@
</td>
<td>
- <pre> % ./configure --prefix=/usr/local \
- --target=httpd_docs</pre>
+ <pre> % make
+ % make install</pre>
</td>
</tr>
</table>
<P>
-This will use the default directory layout, but will replace <EM>apache</EM>
-with <EM>httpd_docs</EM> everywhere. It'll even rename <EM>apachectl</EM> to be
-<EM>httpd_docsctl</EM>. But we will continue with the manual directory tuning in the scenario
-below.
-
-<P>
-If you need some other modules, such as mod_rewrite and mod_include (SSI),
-add them to the end of this list:
+Rename <CODE>httpd</CODE> to <CODE>http_docs</CODE>:
<P>
@@ -985,30 +917,16 @@
</td>
<td>
- <pre> ....
- ....
- --proxycachedir=/usr/local/var/httpd_docs/proxy \
- --enable-module=include --enable-module=rewrite</pre>
+ <pre> % mv /usr/local/httpd_docs/bin/httpd \
+ /usr/local/httpd_docs/bin/httpd_docs</pre>
</td>
</tr>
</table>
<P>
-OS specific note: The httpd executable is at least 100K smaller if compiled
-by <CODE>gcc</CODE> than if compiled with <CODE>cc</CODE> on AIX. Remove the line
-<CODE>env CC=gcc</CODE> if you want to use the default compiler. If you want to use it and you are
-a (ba)?sh user you will not need the <CODE>env</CODE>
-function, t?csh users will have to keep it.
-
-<P>
-It's very important to use the same compiler you build the perl with. See
-the section '<A HREF="././install.html#What_Compiler_Should_Be_Used_to_">What Compiler Should Be Used to Build mod_perl</A>' for more information.
-
-<P>
-Note: Add <CODE>--layout</CODE> to see the resulting directories' layout without actually running the
-configuration process.
+Now modify the <STRONG>apachectl</STRONG> utility to point to the renamed httpd via your favorite text editor or by
+using perl:
-<P><DT><STRONG><A NAME="item_Source">Source Compilation:</A></STRONG><DD>
<P>
<table>
@@ -1019,14 +937,16 @@
</td>
<td>
- <pre> % make
- % make install</pre>
+ <pre> % perl -pi -e 's|bin/httpd|bin/httpd_docs|' \
+ /usr/local/httpd_docs/bin/apachectl</pre>
</td>
</tr>
</table>
- <P>
-Rename <CODE>httpd</CODE> to <CODE>http_docs</CODE>:
+ </DL>
+<P>
+Another approach would be to use the <EM>--target</EM> option while configuring the source, which makes the last two commands
+unnecessary.
<P>
@@ -1038,47 +958,36 @@
</td>
<td>
- <pre> % mv /usr/local/sbin/httpd_docs/httpd \
- /usr/local/sbin/httpd_docs/httpd_docs</pre>
+ <pre> % ./configure --prefix=/usr/local/httpd_docs \
+ --target=httpd_docs \
+ --enable-module=rewrite --enable-module=proxy
+ % make && make install</pre>
</td>
</tr>
</table>
<P>
-Now modify the <STRONG>apachectl</STRONG> utility to point to the renamed httpd via your favorite text editor or by
-using perl:
+Since we told <EM>./configure</EM> that we want the executable to be called
+<CODE>httpd_docs</CODE> (via <CODE>--target=httpd_docs</CODE>) -- it performs all the naming adjustment for us.
<P>
-
- <table>
- <tr>
+The only thing that you might find unusual, is that <EM>apachectl</EM> will be now called <EM>httpd_docsctl</EM> and the configuration file
+<EM>httpd.conf</EM> now will be called <EM>httpd_docs.conf</EM>.
- <td bgcolor="blue" width="1">
-
- </td>
+<P>
+We will leave the decision making about the preffered configuration and
+installation way to the reader. In the rest of the guide we will continue
+using the regular names resulted from using the standard configuration and
+the manual executable name adjustment as described at the beginning of this
+section .
- <td>
- <pre> % perl -p -i -e 's|httpd_docs/httpd|httpd_docs/httpd_docs|' \
- /usr/local/sbin/httpd_docs/apachectl</pre>
- </td>
-
- </tr>
- </table>
- </DL>
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<CENTER><H3><A NAME="Building_the_httpd_perl_Server">Building the httpd_perl Server</A></H3></CENTER>
-<P>
-Before you start to configure the mod_perl sources, you should be aware
-that there are a few Perl modules that have to be installed before building
-mod_perl. You will be alerted if any required modules are missing when you
-run the <CODE>perl Makefile.PL</CODE> command below. If you discover that something is missing, grab it from your
-nearest CPAN repository (if you do not know what that is, pay a visit to <A
-HREF="http://www.perl.com/CPAN">http://www.perl.com/CPAN</A>) or run the <CODE>CPAN</CODE> interactive shell via the command line <CODE>perl -MCPAN -e shell</CODE>.
-
<P>
-Make sure the sources are clean:
+Now we proceed with the sources configuration and installation of the
+<EM>httpd_perl</EM> server. First make sure the sources are clean:
<P>
@@ -1128,47 +1037,21 @@
</td>
<td>
- <pre> % /usr/local/bin/perl Makefile.PL \
- APACHE_PREFIX=/usr/local \
- APACHE_SRC=../apache_x.x.x/src \
- DO_HTTPD=1 \
- USE_APACI=1 \
- PERL_STACKED_HANDLERS=1 \
- ALL_HOOKS=1 \
- APACI_ARGS='--sbindir=/usr/local/sbin/httpd_perl, \
- --sysconfdir=/usr/local/etc/httpd_perl, \
- --localstatedir=/usr/local/var/httpd_perl, \
- --runtimedir=/usr/local/var/httpd_perl/run, \
- --logfiledir=/usr/local/var/httpd_perl/logs, \
- --proxycachedir=/usr/local/var/httpd_perl/proxy'</pre>
+ <pre> % /usr/bin/perl Makefile.PL \
+ APACHE_SRC=../apache_x.x.x/src \
+ DO_HTTPD=1 USE_APACI=1 EVERYTHING=1 \
+ APACHE_PREFIX=/usr/local/httpd_perl \
+ APACI_ARGS='--prefix=/usr/local/httpd_perl'</pre>
</td>
</tr>
</table>
<P>
-Notice that <STRONG>all</STRONG> <CODE>APACI_ARGS</CODE> (above) must be passed as one long line if you work with <CODE>t?csh</CODE>!!! However with <CODE>(ba)?sh</CODE> it works correctly the way it is shown above, breaking the long lines with
-'<CODE>\</CODE>'. When <CODE>t?csh</CODE> passes the <CODE>APACI_ARGS</CODE> arguments to
-<CODE>./configure</CODE> it does not alter the newlines, but it strips the backslashes, thus
-breaking the configuration process.
+If you need to pass any other configuration options to Apache's
+<CODE>configure</CODE>, add them after the <EM>--prefix</EM> option. e.g:
<P>
-Notice that just like in httpd_docs configuration you can use
-<CODE>--target=httpd_perl</CODE> instead of specifying each directory separately. Note that this option has
-to be the very last argument in
-<CODE>APACI_ARGS</CODE>, otherwise 'make test' tries to run ``httpd_perl,'' which fails.
-
-<P>
-This will use the default directory layout, but will replace <EM>apache</EM>
-with <EM>httpd_perl</EM> everywhere. It'll even rename <EM>apachectl</EM> to be
-<EM>httpd_perlctl</EM>. But we will continue with the manual directory tuning in the scenario
-below.
-<P>
-As with httpd_docs you might need other modules such as
-<CODE>mod_rewrite</CODE>, so add them at the end of this list:
-
-<P>
-
<table>
<tr>
@@ -1177,18 +1060,33 @@
</td>
<td>
- <pre> ....
- ....
- --proxycachedir=/usr/local/var/httpd_perl/proxy, \
- --enable-module=rewrite</pre>
+ <pre> APACI_ARGS='--prefix=/usr/local/httpd_perl \
+ --enable-module=status'</pre>
</td>
</tr>
</table>
<P>
-Note: <CODE>PERL_STACKED_HANDLERS=1</CODE> is needed for <CODE>Apache::DBI</CODE>
+Notice that <STRONG>all</STRONG> <CODE>APACI_ARGS</CODE> (above) must be passed as one long line if you work with <CODE>t?csh</CODE>!!! However with <CODE>(ba)?sh</CODE> it works correctly the way it is shown above, breaking the long lines with
+'<CODE>\</CODE>'. As of tcsh version 6.08.0, when it passes the <CODE>APACI_ARGS</CODE>
+arguments to <CODE>configure</CODE> it does not alter the newlines, but it strips the backslashes, thus
+breaking the configuration process.
+
+<P>
+Notice that just like in httpd_docs configuration you can use
+<CODE>--target=httpd_perl</CODE> instead of specifying each directory separately. Note that this option has
+to be the very last argument in
+<CODE>APACI_ARGS</CODE>, otherwise 'make test' tries to run <CODE>'httpd_perl'</CODE>, which fails.
+<P>
+[META: It's very important to use the same compiler you build the perl
+with. See the section '<A HREF="././install.html#What_Compiler_Should_Be_Used_to_">What Compiler Should Be Used to Build mod_perl</A>' for more information.
+<P>
+[META: --- Hmm, what's the option that overrides the compiler when building
+Apache from mod_perl. Check also whether mod_perl supplies the right
+compiler (the one used for building itself) -- if it does there is no need
+for the above note. ]
<P>
Now, build, test and install the <CODE>httpd_perl</CODE>.
@@ -1209,21 +1107,20 @@
</tr>
</table>
<P>
-Note: Apache puts a stripped version of <CODE>httpd</CODE> at
-<EM>/usr/local/sbin/httpd_perl/httpd</EM>. The original version which includes debugging symbols (if you need to run
+Upon installation Apache puts a stripped version of <CODE>httpd</CODE> at
+<EM>/usr/local/httpd_perl/bin/httpd</EM>. The original version which includes debugging symbols (if you need to run
a debugger on this executable) is located at
<EM>/usr/src/httpd_perl/apache_x.x.x/src/httpd</EM>.
<P>
-Note: You may have noticed that we did not run <CODE>make install</CODE> in the Apache source directory. When <CODE>USE_APACI</CODE> is enabled,
-<CODE>APACHE_PREFIX</CODE> will specify the <CODE>--prefix</CODE> option for Apache's
-<CODE>configure</CODE> utility, which gives the installation path for Apache. When this option is
-used, mod_perl's <CODE>make install</CODE> will also <CODE>make
-install</CODE> for Apache, installing the httpd binary, the support tools, and the
-configuration, log and document trees.
+You may have noticed that we did not run <CODE>make install</CODE> in the Apache source directory. When <CODE>USE_APACI</CODE> is enabled, <CODE>APACHE_PREFIX</CODE> will specify the <CODE>--prefix</CODE> option for Apache's <CODE>configure</CODE> utility, which gives the installation path for Apache. When this option is
+used, mod_perl's <CODE>make install</CODE> will also <CODE>make install</CODE> for Apache, installing the httpd binary, the support tools, and the
+configuration, log and document trees. If this option is not used you will
+have to explicitly run make install in the Apache source directory.
<P>
-If <CODE>make test</CODE> fails, look into <CODE>t/logs</CODE> and see what is in there. Also see <A HREF="././install.html#make_test_fails">make test fails</A>.
+If <CODE>make test</CODE> fails, look into
+<EM>/usr/src/httpd_perl/mod_perl-x.xx/t/logs</EM> and read the error.log file. Also see <A HREF="././install.html#make_test_fails">make test fails</A>.
<P>
While doing <CODE>perl Makefile.PL ...</CODE> mod_perl might complain by warning you about a missing library <CODE>libgdbm</CODE>. This is a crucial warning. See
@@ -1242,14 +1139,14 @@
</td>
<td>
- <pre> % mv /usr/local/sbin/httpd_perl/httpd \
- /usr/local/sbin/httpd_perl/httpd_perl</pre>
+ <pre> % mv /usr/local/httpd_perl/bin/httpd \
+ /usr/local/httpd_perl/bin/httpd_perl</pre>
</td>
</tr>
</table>
<P>
-Update the apachectl utility to drive the renamed httpd:
+Update the <EM>apachectl</EM> utility to drive the renamed httpd:
<P>
@@ -1261,8 +1158,8 @@
</td>
<td>
- <pre> % perl -p -i -e 's|httpd_perl/httpd|httpd_perl/httpd_perl|' \
- /usr/local/sbin/httpd_perl/apachectl</pre>
+ <pre> % perl -p -i -e 's|bin/httpd|bin/httpd_perl|' \
+ /usr/local/httpd_perl/bin/apachectl</pre>
</td>
</tr>
@@ -1282,8 +1179,8 @@
<P>
Configuring of the <CODE>httpd_docs</CODE> server is a very easy task. Starting from version 1.3.4 of Apache, there is
only one file to edit. Open
-<EM>/usr/local/etc/httpd_docs/httpd.conf</EM> in your favorite text editor and configure it as you usually would, except
-make sure that you configure the log file directory (<EM>/usr/local/var/httpd_docs/logs</EM>
+<EM>/usr/local/httpd_docs/conf/httpd.conf</EM> in your favorite text editor and configure it as you usually would, except
+make sure that you configure the log file directory (<EM>/usr/local/httpd_docs/logs</EM>
and so on) and the other paths according to the layout you have decided to
use.
@@ -1300,7 +1197,7 @@
</td>
<td>
- <pre> /usr/local/sbin/httpd_docs/apachectl start</pre>
+ <pre> /usr/local/httpd_docs/bin/apachectl start</pre>
</td>
</tr>
@@ -1310,7 +1207,7 @@
<HR>
<CENTER><H3><A NAME="Basic_httpd_perl_Server_Configur">Basic httpd_perl Server Configuration</A></H3></CENTER>
<P>
-Edit the <EM>/usr/local/etc/httpd_perl/httpd.conf</EM>. As with the
+Edit the <EM>/usr/local/httpd_perl/conf/httpd.conf</EM>. As with the
<CODE>httpd_docs</CODE> server configuration, make sure that <CODE>ErrorLog</CODE> and other file location directives are set to point to the right places,
according to the chosen directory layout.
@@ -1331,7 +1228,7 @@
<P>
Now we proceed to the mod_perl specific directives. It will be a good idea
-to add them all at the end of <CODE>httpd.conf</CODE>, since you are going to fiddle about with them a lot in the early stages.
+to add them all at the end of <CODE>httpd.conf</CODE>, since you are going to fiddle with them a lot in the early stages.
<P>
First, you need to specify the location where all mod_perl scripts will be
@@ -1351,14 +1248,14 @@
<td>
<pre> # mod_perl scripts will be called from
- Alias /perl/ /usr/local/myproject/perl/</pre>
+ Alias /perl/ /usr/local/httpd_perl/perl/</pre>
</td>
</tr>
</table>
<P>
From now on, all requests for URIs starting with <EM>/perl</EM> will be executed under mod_perl and will be mapped to the files in
-<EM>/usr/local/myproject/perl/</EM>.
+<EM>/usr/local/httpd_perl/perl/</EM>.
<P>
Now we configure the <EM>/perl</EM> location.
@@ -1432,7 +1329,7 @@
</td>
<td>
- <pre> /usr/local/sbin/httpd_perl/apachectl start</pre>
+ <pre> /usr/local/httpd_perl/bin/apachectl start</pre>
</td>
</tr>
@@ -3625,7 +3522,7 @@
<td align=center valign=center>
<b><font size=-1>Written by <a
-href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/05/2000
+href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/21/2000
</font></b>
<br>
1.14 +10 -6 modperl-site/guide/security.html
Index: security.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/security.html,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- security.html 2000/08/05 20:48:08 1.13
+++ security.html 2000/08/21 13:18:10 1.14
@@ -200,6 +200,8 @@
AuthName realm
AuthType Basic
Require valid-user
+ Order deny, allow
+ Deny from all
</Location></pre>
</td>
@@ -250,26 +252,28 @@
my $user = $r->connection->user;
# authenticate through DBI
- my $reason = authen_dbi ($r, $user, $sent_pw, $level);
+ my $reason = authen_dbi($r, $user, $sent_pw);
if ($reason) {
$r->note_basic_auth_failure;
- $r->log_reason ($reason, $r->uri);
+ $r->log_reason($reason, $r->uri);
return AUTH_REQUIRED;
}
return OK;
}
sub authen_dbi{
- my ($r, $user, $sent_pw, $level) = @_;
+ my ($r, $user, $sent_pw) = @_;
# validate username/passwd
- return 0 if (*PASSED*)
+ return 0 if (*PASSED*) # replace with real code!!!
return "Failed for X reason";
- }</pre>
+ }
+ # don't forget 1;
+ 1;</pre>
</td>
</tr>
@@ -541,7 +545,7 @@
<td align=center valign=center>
<b><font size=-1>Written by <a
-href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 06/26/2000
+href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/21/2000
</font></b>
<br>
1.26 +2 -2 modperl-site/guide/snippets.html
Index: snippets.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/snippets.html,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -r1.25 -r1.26
--- snippets.html 2000/08/05 20:48:08 1.25
+++ snippets.html 2000/08/21 13:18:11 1.26
@@ -1783,7 +1783,7 @@
</table>
<P>
This will have all the urls starting with <EM>/some/url</EM> proxied off to the other server at the same url. It will append the <CODE>REMOTE_HOST</CODE>
-header as a query string arguement. (QSA = Query String Append, P = Proxy).
+header as a query string argument. (QSA = Query String Append, P = Proxy).
There is probably a way to remap it as an X-Header of some sort, but if
query string is good enough for you, then this should work really nicely.
@@ -2327,7 +2327,7 @@
<td align=center valign=center>
<b><font size=-1>Written by <a
-href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 06/26/2000
+href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/21/2000
</font></b>
<br>
1.16 +43 -57 modperl-site/guide/strategy.html
Index: strategy.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/strategy.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- strategy.html 2000/06/07 22:45:37 1.15
+++ strategy.html 2000/08/21 13:18:11 1.16
@@ -288,8 +288,8 @@
<UL>
<P><LI>
<P>
-The process size of a mod_perl-enabled Apache server is huge (maybe 4Mb at
-startup and growing to 10Mb and more, depending on how you use it) compared
+The process size of a mod_perl-enabled Apache server is huge (maybe 4MB at
+startup and growing to 10MB and more, depending on how you use it) compared
to typical plain Apache. Of course if memory sharing is in place, RAM
requirements will be smaller.
@@ -300,7 +300,7 @@
price you pay for the additional performance boost of mod_perl. With memory
prices so cheap nowadays, the additional cost is low -- especially when you
consider the dramatic performance boost mod_perl gives to your services
-with every 100Mb of RAM you add.
+with every 100MB of RAM you add.
<P>
While you will be happy to have these monster processes serving your
@@ -351,7 +351,7 @@
<P>
As I have mentioned before, when running scripts under mod_perl you will
notice that the httpd processes consume a huge amount of virtual memory --
-from 5Mb to 15Mb and even more. That is the price you pay for the enormous
+from 5MB to 15MB and even more. That is the price you pay for the enormous
speed improvements under mod_perl. (Again -- shared memory keeps the real
memory that is being used much smaller :)
@@ -386,14 +386,14 @@
</UL>
<P>
An <STRONG>important</STRONG> note: When a user browses static pages and the base URL in the <STRONG>Location</STRONG> window points to the static server, for example
-<CODE>http://www.nowhere.com/index.html</CODE> -- all relative URLs (e.g. <CODE><A
-HREF="/main/download.html"></CODE>) are being served by the light plain Apache server. But this is not the
-case with dynamically generated pages. For example when the base URL in the <STRONG>Location</STRONG> window points to the dynamic server -- (e.g. <CODE>http://www.nowhere.com:8080/perl/index.pl</CODE>) all relative URLs in the dynamically generated HTML will be served by the
+<CODE>http://www.example.com/index.html</CODE> -- all relative URLs (e.g. <CODE><A HREF="/main/download.html"></CODE>) are being served by the light plain Apache server. But this is not the
+case with dynamically generated pages. For example when the base URL in the
+<STRONG>Location</STRONG> window points to the dynamic server -- (e.g. <CODE>http://www.example.com:8080/perl/index.pl</CODE>) all relative URLs in the dynamically generated HTML will be served by the
heavy mod_perl processes. You must use fully qualified URLs and not
relative ones!
-<CODE>http://www.nowhere.com/icons/arrow.gif</CODE> is a full URL, while
+<CODE>http://www.example.com/icons/arrow.gif</CODE> is a full URL, while
<CODE>/icons/arrow.gif</CODE> is a relative one. Using <CODE><BASE
-HREF="http://www.nowhere.com/"></CODE> in the generated HTML is another way to handle this problem. Also, the <CODE>httpd_perl</CODE> server could rewrite the requests back to <CODE>httpd_docs</CODE> (much slower) and you still need the attention of the heavy servers. This
+HREF="http://www.example.com/"></CODE> in the generated HTML is another way to handle this problem. Also, the <CODE>httpd_perl</CODE> server could rewrite the requests back to <CODE>httpd_docs</CODE> (much slower) and you still need the attention of the heavy servers. This
is not an issue if you hide the internal port implementations, so the
client sees only one server running on port <CODE>80</CODE>. (See <A HREF="././config.html#Publishing_Port_Numbers_other_th">Publishing Port Numbers other than 80</A>)
@@ -408,12 +408,7 @@
<UL>
<P><LI>
<P>
-The need for two different sets of configuration, log and other files. We
-need a special directory layout to manage these. While some directories can
-be shared between the two servers (like the <CODE>include</CODE>
-directory, containing the Apache include files -- assuming that both are
-built from the same source distribution), most of them should be separated
-and the configuration files updated to reflect the changes.
+The need for two configuration files.
<P><LI>
<P>
@@ -479,7 +474,7 @@
The memory savings are significantly smaller if your OS supports memory
sharing with Dynamically Shared Objects (DSO) and you have configured
Apache to use it. If you do allow memory sharing, 30 light Apache servers
-ought to use only about 3 to 4Mb, because most of it will be shared. There
+ought to use only about 3 to 4MB, because most of it will be shared. There
is no memory sharing if Apache modules are statically compiled into the
httpd executable.
@@ -500,8 +495,12 @@
</UL>
<P>
-META: It seems that khttpd, or Phhttpd should be even faster for static
-content serving, add more info about these two!
+Another interesting choice is a kHTTPd webserver for Linux. kHTTPd is
+different from other webservers in that it runs from within the
+Linux-kernel as a module (device-driver). kHTTPd handles only static (file
+based) web-pages, and passes all requests for non-static information to a
+regular userspace-webserver such as Apache. For more information see <A
+HREF="http://www.fenrus.demon.nl/.">http://www.fenrus.demon.nl/.</A>
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
@@ -513,12 +512,12 @@
<P>
The two servers coexist at the same IP address by listening to different
ports: <CODE>httpd_docs</CODE> listens to port 80 (e.g. <A
-HREF="http://www.nowhere.com/images/test.gif">http://www.nowhere.com/images/test.gif</A>)
+HREF="http://www.example.com/images/test.gif">http://www.example.com/images/test.gif</A>)
and <CODE>httpd_perl</CODE>
listens to port 8080 (e.g. <A
-HREF="http://www.nowhere.com:8080/perl/test.pl">http://www.nowhere.com:8080/perl/test.pl</A>).
+HREF="http://www.example.com:8080/perl/test.pl">http://www.example.com:8080/perl/test.pl</A>).
Note that I did not write <A
-HREF="http://www.nowhere.com:80">http://www.nowhere.com:80</A> for the
+HREF="http://www.example.com:80">http://www.example.com:80</A> for the
first example, since port 80 is the default port for the http service.
Later on, I will be changing the configuration of the <CODE>httpd_docs</CODE> server to make it listen to port 81.
@@ -549,13 +548,13 @@
<P>
Using numbers is always more convincing :) Let's take a user connected to
-your site with 28.8 kbps (bps == bits/sec) modem. It means that the speed
-of the user's link is 28.8/8 = 3.6 kbytes/sec. I assume an average
-generated HTML page to be of 40kb (kb == kilobytes) and an average script
-that generates this output in 1 second. How long will the server wait
-before the user gets the whole output response? A simple calculation
+your site with 56 kbps (bps == bits/sec) modem. 1 byte == 8 bits. It means
+that the speed of the user's link is 56/8 = 7 kbytes/sec. I assume an
+average generated HTML page to be of 42KB (KB == kilobytes) and an average
+script that generates this output in 0.5 second. How long will the server
+wait before the user gets the whole output response? A simple calculation
reveals pretty scary numbers -- it will have to wait for another 12 secs
-(40kb/3.6kb), when it could serve another 11 (12/1-1) dynamic requests in
+(42kb/0.5*7KB), when it could serve another 11 (12/1-1) dynamic requests in
this time.
<P>
@@ -571,8 +570,8 @@
<P>
Many users like to open many browser windows and do many things at once
-(download files and browse graphically <EM>heavy</EM> sites). So the speed of 3.6kb/sec we were assuming before, may often be
-5-10 times slower.
+(download files and browse graphically <EM>heavy</EM> sites). So the speed of 7K/sec we were assuming before, may often be 5-10
+times slower.
<P><LI>
<P>
@@ -752,7 +751,7 @@
<P><LI>
<P>
-The <CODE>ProxyPass</CODE> and <CODE>ProxyPassReverse</CODE> directives allow you to hide the internal redirects, so if <CODE>http://nowhere.com/modperl/</CODE> is actually <CODE>http://localhost:81/modperl/</CODE>, it will be absolutely transparent to the user. <CODE>ProxyPass</CODE> redirects the request to the mod_perl server, and when it gets the
+The <CODE>ProxyPass</CODE> and <CODE>ProxyPassReverse</CODE> directives allow you to hide the internal redirects, so if <CODE>http://example.com/modperl/</CODE> is actually <CODE>http://localhost:81/modperl/</CODE>, it will be absolutely transparent to the user. <CODE>ProxyPass</CODE> redirects the request to the mod_perl server, and when it gets the
response, <CODE>ProxyPassReverse</CODE>
rewrites the URL back to the original one, e.g:
@@ -801,19 +800,6 @@
</UL>
<P>
-The Disadvantages:
-
-<UL>
-<P><LI>
-<P>
-Users have reported that it might be a bit slow, but the latest version is
-fast enough.
-
-<P>
-(META: How fast is enough? :) Any figures here?
-
-</UL>
-<P>
For implementation see the ``<A HREF="././scenario.html#mod_proxy">Using mod_proxy</A>'' section in the implementation chapter.
<P>
@@ -1117,9 +1103,9 @@
little or nothing in common; different modules, no code sharing. Typical
numbers can be four megabytes of unshared and four megabytes of shared
memory for each code set, plus three megabytes of shared basic mod_perl
-stuff. Which makes each process 17Mb in size when the two code sets are
-loaded. (3Mb (server) + 4Mb (shared 1st code set ) + 4Mb (unshared 1st code
-set ) + 4Mb (shared 2nd code set ) + 4Mb (unshared 2nd code set ). Under
+stuff. Which makes each process 17MB in size when the two code sets are
+loaded. (3MB (server) + 4MB (shared 1st code set ) + 4MB (unshared 1st code
+set ) + 4MB (shared 2nd code set ) + 4MB (unshared 2nd code set ). Under
this scenario, eleven megabytes are shared and eight megabytes not.
<P>
@@ -1182,7 +1168,7 @@
<P>
Let's look at the figures again. After the split we will have 20 servers of
-eleven megabytes (4Mb unshared + 7mb shared) and another 20 servers of
+eleven megabytes (4MB unshared + 7mb shared) and another 20 servers of
eleven megabytes.
<P>
@@ -1223,8 +1209,8 @@
</tr>
</table>
<P>
-A total of 182 megabytes of memory required. But, hey, we have 260Mb of
-memory. We've got 78Mb of memory freed up. If we recalculate again the <CODE>MaxClients</CODE> we will see that we can run almost 60 servers:
+A total of 182 megabytes of memory required. But, hey, we have 260MB of
+memory. We've got 78MB of memory freed up. If we recalculate again the <CODE>MaxClients</CODE> we will see that we can run almost 60 servers:
<P>
@@ -1254,19 +1240,19 @@
<P>
Let's assume that based on the usage statistics we know that the first code
set is called in 70% of requests and the other 30% are used by the second
-set. Now we assume that the first code set requires only 5Mbytes of RAM
-(3Mb shared plus 2Mb unshared) over the basic mod_perl server size, and the
-second set needs 11Mbytes (7Mb shared and 4Mb unshared).
+set. Now we assume that the first code set requires only 5MB of RAM (3MB
+shared plus 2MB unshared) over the basic mod_perl server size, and the
+second set needs 11MBytes (7MB shared and 4MB unshared).
<P>
Lets compare this new requirement with our original 50:50 setup.
<P>
So now the first mod_perl server running the first code set will have all
-its processes using 8Mb (3Mb (server shared) + 3Mb (code shared) + 2Mb
-(code unshared), and the second 14Mb (3+7+4). Given that we have a 70:30
-hits relation and that we have 260Mbytes of available memory, we have to
-solve these two equations:
+its processes using 8MB (3MB (server shared) + 3MB (code shared) + 2MB
+(code unshared), and the second 14MB (3+7+4). Given that we have a 70:30
+hits relation and that we have 260MB of available memory, we have to solve
+these two equations:
<P>
@@ -1562,7 +1548,7 @@
<td align=center valign=center>
<b><font size=-1>Written by <a
-href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 05/27/2000
+href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/21/2000
</font></b>
<br>
1.8 +54 -3 modperl-site/guide/troubleshooting.html
Index: troubleshooting.html
===================================================================
RCS file: /home/cvs/modperl-site/guide/troubleshooting.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- troubleshooting.html 2000/08/05 20:48:08 1.7
+++ troubleshooting.html 2000/08/21 13:18:11 1.8
@@ -40,6 +40,7 @@
<UL>
<LI><A HREF="#libexec_libperl_so_open_failed_">libexec/libperl.so: open failed: No such file or directory</A>
+ <LI><A HREF="#install_driver_Oracle_failed_C">install_driver(Oracle) failed: Can't load '.../DBD/Oracle/Oracle.so' for module DBD::Oracle</A>
<LI><A HREF="#Invalid_command_PerlHandler_">Invalid command 'PerlHandler'...</A>
<LI><A HREF="#RegistryLoader_Translation_of_u">RegistryLoader: Translation of uri [...] to filename failed</A>
<LI><A HREF="#_Apache_pm_failed_to_load_">"Apache.pm failed to load!"</A>
@@ -201,6 +202,56 @@
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
+<CENTER><H2><A NAME="install_driver_Oracle_failed_C">install_driver(Oracle) failed: Can't load '.../DBD/Oracle/Oracle.so' for module DBD::Oracle</A></H2></CENTER>
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> install_driver(Oracle) failed: Can't load
+ '/usr/lib/perl5/site_perl/5.005/i386-linux/auto/DBD/Oracle/Oracle.so'
+ for module DBD::Oracle:
+ libclntsh.so.8.0: cannot open shared object file:
+ No such file or directory at
+ /usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm line 169.
+ at (eval 27) line 3
+ Perhaps a required shared
+ library or dll isn't installed where expected at
+ /usr/local/apache/perl/tmp.pl line 11</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+On BSD style filesystems <CODE>LD_LIBRARY_PATH</CODE> is not searched for setuid programs (a.k.a., Apache). This isn't a problem
+for CGIs since they don't do a setuid (and are forked off), but Apache
+does, and mod_perl is in Apache. Therefore a solution is to explicitly load
+the library from the system wide <EM>ldconfig</EM> configuration file:
+
+<P>
+
+ <table>
+ <tr>
+
+ <td bgcolor="blue" width="1">
+
+ </td>
+
+ <td>
+ <pre> # echo $ORACLE_HOME/lib >> /etc/ld.so.conf
+ # ldconfig</pre>
+ </td>
+
+ </tr>
+ </table>
+ <P>
+[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
+<HR>
<CENTER><H2><A NAME="Invalid_command_PerlHandler_">Invalid command 'PerlHandler'...</A></H2></CENTER>
<P>
@@ -533,7 +584,7 @@
<HR>
<CENTER><H2><A NAME="Incorrect_line_number_reporting_">Incorrect line number reporting in error/warn log messages</A></H2></CENTER>
<P>
-See <A HREF="#Use_of_uninitialized_value_at_e">Use of uninitialized value at (eval 80) line 12.</A>
+See <A HREF="././troubleshooting.html#Use_of_uninitialized_value_at_e">Use of uninitialized value at (eval 80) line 12.</A>
@@ -614,7 +665,7 @@
</table>
<P>
You may see this message in mod_perl versions less than 1.17. See also
-<A HREF="#caught_SIGPIPE_in_process">caught SIGPIPE in process</A>.
+<A HREF="././troubleshooting.html#caught_SIGPIPE_in_process">caught SIGPIPE in process</A>.
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
@@ -1234,7 +1285,7 @@
<td align=center valign=center>
<b><font size=-1>Written by <a
-href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 06/15/2000
+href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 08/21/2000
</font></b>
<br>