sbekman 01/04/27 09:57:30 Modified: guide CHANGES browserbugs.html config.html control.html correct_headers.html dbm.html debug.html download.html help.html index.html index_long.html install.html intro.html mod_perl_guide.pdf.gz modules.html multiuser.html performance.html perl.html porting.html scenario.html snippets.html start.html strategy.html troubleshooting.html Log: * dbm.pod: o updated "Flawed Locking Methods Which Must Not Be Used" with notes about lock upgrading (David Harris) * strategy.pod: o added a ref to a light and fast Boa webserver * scenario.pod: o cleared out the section on open proxying with mod_proxy (Eric Cholet) * multiuser.pod: o extended the "Virtual Servers Technologies" section with freevsd, freevmware, vmware and S/390 references. * snippets.pod: o removed the cache control section -- it's covered in the HTTP headers chapter. o subrequests and notes working together (Darren Chamberlain) * performance.pod: o "Interpolation vs List" update: wrongly used the 'concatenation' term instead of interpolation (Mark Summerfield) o "Interpolation, Concatenation or List" was rewritten o new: "Architecture Specific Compile Options" (Tim Bunce, Perrin Harkins, Greg Cope, Owen Williams, Vivek Khera, Steve Fink, James W Walden) * modules.pod: o Extended the docs of Apache::SubProcess module * porting.pod: o "using register_cleanup in startup.pl to register cleanup action at the server shutdown or restart" (Doug) * config.pod: o Cleared the item which was falsely stating that the globals defined in startup.pl cannot be seen by child process. (Richard Chen) * install.pod: o updated "Discovering Whether Some Option Was Configured": added Apache::MyConfig o debian/apt install notes updates (Neil Conway) o some callback hooks aren't enabled by ALL_HOOKS=1 (Neil Conway) * download.pod o update the location of mod_proxy_add_forward.c (Ask Bjorn Hansen) * help.pod o added a link to Andrew Ford's Apache and mod_perl pocket books. o added a link to take23.org o added a XS resources section o added a link to the scalable list archive o remove the mailing list post address, to make it easier of Ask to filter SPAM. * troubleshooting.pod o new: "exit signal Segmentation fault (11)" with mysql: (Matt Sergeant) o improved the docs of fixing a broken /dev/null * debug.pod o updated "gdb says there are no debugging symbols" -- a simpler technique to have the binary unstripped during make install. * Minor corrections: o debug.pod (Alexander Farber) o performance.pod (Marc Lehmann, Kees Vonk) o snippets.pod (Ime Smits) o porting.pod (Michele Beltrame) o config.pod (Surat Singh Bhati, Paul Cotter ) o control.pod (Aaron Johnson, Cliff Rayman, Yann Kerhervé) o modules.pod (Daniel Bohling) o install.pod (Kevin Swope, Jamie) Revision Changes Path 1.29 +105 -1 modperl-site/guide/CHANGES Index: CHANGES =================================================================== RCS file: /home/cvs/modperl-site/guide/CHANGES,v retrieving revision 1.28 retrieving revision 1.29 diff -u -r1.28 -r1.29 --- CHANGES 2001/01/11 13:48:14 1.28 +++ CHANGES 2001/04/27 16:57:09 1.29 @@ -2,7 +2,111 @@ ### mod_perl Guide CHANGES file ### ################################### -01.01.2001 ver 1.28 +04.26.2001 ver 1.29 + +* dbm.pod: + + o updated "Flawed Locking Methods Which Must Not Be Used" with notes + about lock upgrading (David Harris) + +* strategy.pod: + + o added a ref to a light and fast Boa webserver + +* scenario.pod: + + o cleared out the section on open proxying with mod_proxy (Eric Cholet) + +* multiuser.pod: + + o extended the "Virtual Servers Technologies" section with freevsd, + freevmware, vmware and S/390 references. + +* snippets.pod: + + o removed the cache control section -- it's covered in the HTTP + headers chapter. + + o subrequests and notes working together (Darren Chamberlain) + +* performance.pod: + + o "Interpolation vs List" update: wrongly used the 'concatenation' + term instead of interpolation (Mark Summerfield) + + o "Interpolation, Concatenation or List" was rewritten + + o new: "Architecture Specific Compile Options" (Tim Bunce, Perrin + Harkins, Greg Cope, Owen Williams, Vivek Khera, Steve Fink, James + W Walden) + +* modules.pod: + + o Extended the docs of Apache::SubProcess module + +* porting.pod: + + o "using register_cleanup in startup.pl to register cleanup action + at the server shutdown or restart" (Doug) + +* config.pod: + + o Cleared the item which was falsely stating that the globals + defined in startup.pl cannot be seen by child process. (Richard + Chen) + +* install.pod: + + o updated "Discovering Whether Some Option Was Configured": added + Apache::MyConfig + + o debian/apt install notes updates (Neil Conway) + + o some callback hooks aren't enabled by ALL_HOOKS=1 (Neil Conway) + +* download.pod + + o update the location of mod_proxy_add_forward.c (Ask Bjorn Hansen) + +* help.pod + + o added a link to Andrew Ford's Apache and mod_perl pocket books. + + o added a link to take23.org + + o added a XS resources section + + o added a link to the scalable list archive + + o remove the mailing list post address, to make it easier of Ask to + filter SPAM. + +* troubleshooting.pod + + o new: "exit signal Segmentation fault (11)" with mysql: (Matt + Sergeant) + + o improved the docs of fixing a broken /dev/null + +* debug.pod + + o updated "gdb says there are no debugging symbols" -- a simpler + technique to have the binary unstripped during make install. + +* Minor corrections: + + o debug.pod (Alexander Farber) + o performance.pod (Marc Lehmann, Kees Vonk) + o snippets.pod (Ime Smits) + o porting.pod (Michele Beltrame) + o config.pod (Surat Singh Bhati, Paul Cotter ) + o control.pod (Aaron Johnson, Cliff Rayman, Yann Kerhervé) + o modules.pod (Daniel Bohling) + o install.pod (Kevin Swope, Jamie) + + + +01.11.2001 ver 1.28 * Makefile.PL: fixed to generate a correct Makefile on Solaris: removed space/extra new line after some manually created targets 1.14 +1 -1 modperl-site/guide/browserbugs.html Index: browserbugs.html =================================================================== RCS file: /home/cvs/modperl-site/guide/browserbugs.html,v retrieving revision 1.13 retrieving revision 1.14 diff -u -r1.13 -r1.14 --- browserbugs.html 2001/01/11 13:48:14 1.13 +++ browserbugs.html 2001/04/27 16:57:09 1.14 @@ -157,7 +157,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/21/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 06/22/2000 </font></b> <br> 1.31 +10 -28 modperl-site/guide/config.html Index: config.html =================================================================== RCS file: /home/cvs/modperl-site/guide/config.html,v retrieving revision 1.30 retrieving revision 1.31 diff -u -r1.30 -r1.31 --- config.html 2001/01/11 13:48:14 1.30 +++ config.html 2001/04/27 16:57:09 1.31 @@ -75,7 +75,6 @@ <LI><A HREF="#The_Sample_Startup_File">The Sample Startup File</A> <LI><A HREF="#What_Modules_You_Should_Add_to_t">What Modules You Should Add to the Startup File and Why</A> <LI><A HREF="#The_Confusion_with_use_in_the_">The Confusion with use() in the Server Startup File</A> - <LI><A HREF="#The_Confusion_with_Global_Variab">The Confusion with Global Variables in the Startup File</A> </UL> <LI><A HREF="#Apache_Configuration_in_Perl">Apache Configuration in Perl</A> @@ -1056,19 +1055,21 @@ </tr> </table> <P> -<CODE>PerlSendHeader On</CODE> tells the server to send an HTTP header to the browser on every script +<CODE>PerlSendHeader On</CODE> tells the server to send an HTTP headers to the browser on every script invocation. You will want to turn this off for nph (non-parsed-headers) scripts. <P> The <CODE>PerlSendHeader On</CODE> setting invokes the Apache's <CODE>ap_send_http_header()</CODE> method after parsing the headers generated by the script. It is only meant -for CGI emulation, and to send the HTTP header it's always better either to -use the <CODE>$q->header</CODE> method from the <CODE>CGI.pm</CODE> module or to use the <CODE>$r->send_http_header</CODE> -method using the Apache Perl API. +for emulation of mod_cgi behavior with regard to headers. <P> +To send the HTTP headers it's always better either to use the +<CODE>$r->send_http_header</CODE> method using the Apache Perl API or to use the <CODE>$q->header</CODE> method from the <CODE>CGI.pm</CODE> module. +<P> + <table> <tr> @@ -1359,7 +1360,7 @@ <P> <CODE>PerlInitHandler</CODE> changes its behaviour depending upon where it is used. In any case it is the first handler to be invoked in serving a request. If found outside any <CODE><Location></CODE>, -<CODE><Directory></CODE> or <CODE><Files></CODE> section, it is an alias for <CODE>PerlPostReadRequestHandler</CODE>. When outside any such section it is an alias for <CODE>PerlHeaderParserHandler</CODE>. +<CODE><Directory></CODE> or <CODE><Files></CODE> section (at the top level), it is an alias for <CODE>PerlPostReadRequestHandler</CODE>. When inside any such section it is an alias for <CODE>PerlHeaderParserHandler</CODE>. <P> Starting from <CODE>PerlHeaderParserHandler</CODE> the requested URI has been mapped to a physical server pathname, and thus @@ -2371,9 +2372,8 @@ # Initialize the database connections for each child Apache::DBI->connect_on_init - ("DBI:mysql:$Match::Config::c{db}{DB_NAME}::$Match::Config::c{db}{SERVER}", - $Match::Config::c{db}{USER}, - $Match::Config::c{db}{USER_PASSWD}, + ("DBI:mysql:database=test;host=localhost", + "user","password", { PrintError => 1, # warn() on errors RaiseError => 0, # don't die on error @@ -2750,24 +2750,6 @@ <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> -<CENTER><H2><A NAME="The_Confusion_with_Global_Variab">The Confusion with Global Variables in the Startup File</A></H2></CENTER> -<P> -<CODE>PerlRequire</CODE> allows you to execute code that preloads modules and performs other -functions. Imported or defined variables are visible in the scope of the -startup file. It is wrong to assume that global variables that were defined -in the startup file will be visible to child processes. - -<P> -If you define or import variables in your scripts they will be visible -inside the child process which is running the script: but they will not be -shared between siblings. Remember that every script is running in a -specially (uniquely) named package - so it cannot access variables from -other packages unless it inherits from them or -<CODE>use()</CODE>'s them. - -<P> -[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] -<HR> <CENTER><H1><A NAME="Apache_Configuration_in_Perl">Apache Configuration in Perl</A></H1></CENTER> <P> With <CODE><Perl></CODE>...<CODE></Perl></CODE> sections, it is possible to configure your server entirely in Perl. @@ -4311,7 +4293,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 01/11/2001 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 03/20/2001 </font></b> <br> 1.31 +4 -3 modperl-site/guide/control.html Index: control.html =================================================================== RCS file: /home/cvs/modperl-site/guide/control.html,v retrieving revision 1.30 retrieving revision 1.31 diff -u -r1.30 -r1.31 --- control.html 2001/01/11 13:48:15 1.30 +++ control.html 2001/04/27 16:57:10 1.31 @@ -879,7 +879,8 @@ Please, bear with us. Thank you! }; return OK; - }</pre> + } + 1;</pre> </td> </tr> @@ -2768,7 +2769,7 @@ <td> <pre> sub UNIVERSAL::AUTOLOAD { my $class = shift; - warn "$class can't \$UNIVERSAL::AUTOLOAD!\n"; + warn "$class can't \$UNIVERSAL::AUTOLOAD=$UNIVERSAL::AUTOLOAD!\n"; }</pre> </td> @@ -2837,7 +2838,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 11/20/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 04/19/2001 </font></b> <br> 1.14 +1 -1 modperl-site/guide/correct_headers.html Index: correct_headers.html =================================================================== RCS file: /home/cvs/modperl-site/guide/correct_headers.html,v retrieving revision 1.13 retrieving revision 1.14 diff -u -r1.13 -r1.14 --- correct_headers.html 2001/01/11 13:48:15 1.13 +++ correct_headers.html 2001/04/27 16:57:10 1.14 @@ -292,7 +292,7 @@ use Date::Parse; # Date::Parse parses RCS format, Apache::Util::parsedate doesn't $Mtime ||= - Date::Parse::str2time(substr q$Date: 2001/01/11 13:48:15 $, 6); + Date::Parse::str2time(substr q$Date: 2001/04/27 16:57:10 $, 6); $r->set_last_modified($Mtime);</pre> </td> @@ -1283,7 +1283,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 11/20/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 11/21/2000 </font></b> <br> 1.18 +115 -6 modperl-site/guide/dbm.html Index: dbm.html =================================================================== RCS file: /home/cvs/modperl-site/guide/dbm.html,v retrieving revision 1.17 retrieving revision 1.18 diff -u -r1.17 -r1.18 --- dbm.html 2001/01/11 13:48:15 1.17 +++ dbm.html 2001/04/27 16:57:11 1.18 @@ -115,12 +115,11 @@ <P> There is a number of Perl interfaces to the major dbm implementations, to -list a few: <CODE>DBM</CODE>, <CODE>NDBM</CODE>, <CODE>ODBM</CODE>, <CODE>GDBM</CODE>, and <CODE>SDBM</CODE>. The original Perl module for Berkeley DB was DB_File, which was written +list a few: <CODE>DB_File</CODE>, <CODE>NDBM_File</CODE>, <CODE>ODBM_File</CODE>, <CODE>GDBM_File</CODE>, and <CODE>SDBM_File</CODE>. The original Perl module for Berkeley DB was DB_File, which was written to interface to Berkeley DB version 1.85. The newer Perl module for Berkeley DB is <CODE>BerkeleyDB</CODE>, which was written to interface to version 2.0 and subsequent releases. Because Berkeley DB version 2.X has a compatibility API for version 1.85, -you can (and should!) build -<CODE>DB_File</CODE> using version 2.X of Berkeley DB, although <CODE>DB_File</CODE> will still only support the 1.85 functionality. +you can (and should!) build <CODE>DB_File</CODE> using version 2.X of Berkeley DB, although <CODE>DB_File</CODE> will still only support the 1.85 functionality. <P> Several different indexing algorithms (known also as access methods) can be @@ -363,6 +362,116 @@ inventing your own. <P> +If your dbm file is used only in the read-only mode generally there is no +need for locking at all. If you access the dbm file in read/write mode, the +safest method is to <CODE>tie()</CODE> the dbm file after acquiring an +external lock and <CODE>untie()</CODE> before the lock is released. So to +access the file in shared mode (FLOCK_SH) one should following this +pseudo-code: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> flock FLOCK_SH <===== start critical section + tie() + read... + untie() + flock FLOCK_UN <===== end critical section</pre> + </td> + + </tr> + </table> + <P> +Similar for the exclusive (EX), write access: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> flock FLOCK_EX <===== start critical section + tie() + write... + sync() + untie() + flock FLOCK_UN <===== end critical section</pre> + </td> + + </tr> + </table> + <P> +However you might want to save a few <CODE>tie()/untie()</CODE> calls if +the same request accesses the dbm file more than once. You should be +careful though. Based on the caching effect explained above, a process can +perform an atomic downgrade of an exclusive lock to a shared one without +re-tie()ing the file: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> flock FLOCK_EX <===== start critical section + tie() + write... + sync() + <===== end critical section + flock FLOCK_SH <===== start critical section + read... + untie() + flock FLOCK_UN <===== end critical section</pre> + </td> + + </tr> + </table> + <P> +because it has the updated data in its cache. By atomic, we mean it's +ensured that the lock status gets changed, without any other process +getting an exclusive access in between. + +<P> +If you can ensure that one process safely upgrades a shared lock with an +exclusive lock, one can save on <CODE>tie()/untie().</CODE> But this +operation might lead to a dead-lock if two processes try to upgrade a +shared lock with exclusive at the same time. Remember that in order to +acquire an exclusive lock, all other processes need to release *all* locks. +If your OS locking implementation resolves this deadlock by denying one of +the upgrade requests, make sure your program handles that appropriately. +The process that were denied has to <CODE>untie()</CODE> the dbm file and +then ask for an exclusive lock. + +<P> +A dbm file has always to be <CODE>untie()'ed</CODE> before the locking is +released (unless you do an atomic downgrade from exclusive to shared as we +have just explained). Remember that if at any given moment a process wants +to lock and access the dbm file it has to re-tie() this file, if it was +tied already. If this is not done, the integrity of the dbm file is not +ensured. + +<P> +To conclude, the safest method of reading from dbm file is to lock the file +before <CODE>tie()-ing</CODE> it, <CODE>untie()</CODE> it before releasing +the lock, and in the case of write to call <CODE>sync()</CODE> before +<CODE>untie()-ing</CODE> it. + +<P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H1><A NAME="Locking_Wrappers_Overview">Locking Wrappers Overview</A></H1></CENTER> @@ -383,13 +492,13 @@ <P><LI> <P> -<CODE>Tie::DB_LockFile</CODE> -- <CODE>DB_File</CODE> wrapper that has the ability to lock and unlock the database while it is +<CODE>Tie::DB_FileLock</CODE> -- <CODE>DB_File</CODE> wrapper that has the ability to lock and unlock the database while it is being used. Avoids the tie-before-flock problem by simply re-tie-ing the database when you get or drop a lock. Because of the flexibility in dropping and re-acquiring the lock in the middle of a session, this can be used in a system that will work with long updates and/or reads. Refer to the -<CODE>Tie::DB_LockFile</CODE> manpage for more information. +<CODE>Tie::DB_FileLock</CODE> manpage for more information. <P><LI> <P> @@ -644,7 +753,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 12/11/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 03/26/2001 </font></b> <br> 1.28 +103 -88 modperl-site/guide/debug.html Index: debug.html =================================================================== RCS file: /home/cvs/modperl-site/guide/debug.html,v retrieving revision 1.27 retrieving revision 1.28 diff -u -r1.27 -r1.28 --- debug.html 2001/01/11 13:48:15 1.27 +++ debug.html 2001/04/27 16:57:11 1.28 @@ -988,6 +988,48 @@ But in general case, you don't need to use the above setting. <P> +If you use this setting and you would like to log when a request was +cancelled by a SIGPIPE in your Apache <EM>access_log</EM>, you must define a custom <CODE>LogFormat</CODE> in your <EM>httpd.conf</EM>, like so: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> PerlFixupHandler Apache::SIG + LogFormat "%h %l %u %t \"%r\" %s %b %{SIGPIPE}e"</pre> + </td> + + </tr> + </table> + <P> +If the server has noticed that the request was cancelled via a +<CODE>SIGPIPE</CODE>, then the log line will end with <CODE>1</CODE>, otherwise it will just be a dash. e.g.: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> 127.0.0.1 - - [09/Jan/2001:10:27:15 +0100] + "GET /perl/stopping_detector.pl HTTP/1.0" 200 16 1 + 127.0.0.1 - - [09/Jan/2001:10:28:18 +0100] + "GET /perl/test.pl HTTP/1.0" 200 10 -</pre> + </td> + + </tr> + </table> + <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H2><A NAME="Detecting_Aborted_Connections">Detecting Aborted Connections</A></H2></CENTER> @@ -1215,84 +1257,6 @@ where 17 is a file descriptor of the opened <EM>access_log</EM> file <P> -Let's see how can we make the code more general-purpose: - -<P> -<CODE>Apache::SIG</CODE> helps us, use this configuration setting in -<EM>httpd.conf</EM>: - -<P> - - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> PerlFixupHandler Apache::SIG</pre> - </td> - - </tr> - </table> - <P> -Now the following script doesn't need to check for aborted connections. - -<P> - - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> my $r = shift; - $r->send_http_header('text/plain'); - - print "PID = $$\n"; - $r->rflush; - while(1){ - $r->print("\0"); - $r->rflush; - $i++; - sleep 1; - }</pre> - </td> - - </tr> - </table> - <P> -<CODE>Apache::SIG</CODE> installs the <CODE>SIGPIPE</CODE> handler, which stops the script's execution for us when it sees the broken -pipe. This setting affects all processes of course. - -<P> -If you would like to log when a request was cancelled by a SIGPIPE in your -Apache <EM>access_log</EM>, you must define a custom <CODE>LogFormat</CODE> in your <EM>httpd.conf</EM>, like so: - -<P> - - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> PerlFixupHandler Apache::SIG - LogFormat "%h %l %u %t \"%r\" %s %b %{SIGPIPE}e"</pre> - </td> - - </tr> - </table> - <P> -If the server has noticed that the request was cancelled via a -<CODE>SIGPIPE</CODE>, then the log line will end with <CODE>1</CODE>, otherwise it will just be a dash. - -<P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H2><A NAME="The_Importance_of_Cleanup_Code">The Importance of Cleanup Code</A></H2></CENTER> @@ -5268,7 +5232,7 @@ while loop), it gets blocked by some system call or because of a resource deadlock) or for some other reason. In order to fix the problem we need to learn what circumstances the process hangs in (detection), so we can -reproduce the problem and after than to discover why there is problem +reproduce the problem and after that to discover why there is problem (diagnostics). <P> @@ -5561,7 +5525,7 @@ <P> If you get such reports constantly something is wrong with your web service and you should revise your code. Note that it's possible that your server -is being overloaded by more requests that it can handle, so the requests +is being overloaded by more requests than it can handle, so the requests are being queued and not processed for a while, which triggers the watchdog's alarm. If this is a case you may need to add more servers or more memory, or perhaps split your single machine across a cluster of @@ -6400,11 +6364,22 @@ will: <OL> -<P><LI><STRONG><A NAME="item_Add_g_to_EXTRA_CFLAGS">Add `-g' to EXTRA_CFLAGS</A></STRONG> -<P><LI><STRONG><A NAME="item_Turn_on_PERL_TRACE">Turn on PERL_TRACE</A></STRONG> -<P><LI><STRONG><A NAME="item_Set_PERL_DESTRUCT_LEVEL_2">Set PERL_DESTRUCT_LEVEL=2</A></STRONG> -<P><LI><STRONG><A NAME="item_Link_against_libperld_if_e_Con">Link against libperld if -e -$Config{archlibexp}/CORE/libperld$Config{lib_ext}</A></STRONG> +<P><LI> +<P> +Add `-g' to EXTRA_CFLAGS + +<P><LI> +<P> +Turn on PERL_TRACE + +<P><LI> +<P> +Set PERL_DESTRUCT_LEVEL=2 + +<P><LI> +<P> +Link against <CODE>libperld</CODE> if -e $Config{archlibexp}/CORE/libperld$Config{lib_ext} + </OL> <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] @@ -6572,11 +6547,50 @@ <HR> <CENTER><H1><A NAME="gdb_says_there_are_no_debugging_">gdb says there are no debugging symbols</A></H1></CENTER> <P> +During <EM>make install</EM> Apache strips all the debugging symbols. To prevent this you should use <EM>--without-execstrip</EM> <CODE>./configure</CODE> +option. So if you configure Apache via mod_perl, you should do: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> panic% perl Makefile.PL USE_APACI=1 \ + APACI_ARGS='--without-execstrip' [other options]</pre> + </td> + + </tr> + </table> + <P> +Alternatively you can copy the unstripped binary manually. For example we +did: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> panic# cp apache_1.3.17/src/httpd /home/httpd/httpd_perl/bin/httpd_perl</pre> + </td> + + </tr> + </table> + <P> As you know you need an unstripped executable to be able to debug it. While you can compile mod_perl with <A HREF="#item__g">-g</A> (or <CODE>PERL_DEBUG=1</CODE>), the Apache <CODE>install</CODE> strips the symbols. <P> -Makefile.tmpl contains a line: +<EM>Makefile.tmpl</EM> contains a line: <P> @@ -6594,7 +6608,8 @@ </tr> </table> <P> -Removing the -s does the trick. +Removing the -s does the trick (If you cannot find it in +<EM>Makefile.tmpl</EM> do it directly in <EM>Makefile</EM>). Alternatively you rerun <CODE>make</CODE> and copy the unstripped httpd binary away. <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] @@ -7181,7 +7196,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 01/09/2001 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 02/19/2001 </font></b> <br> 1.16 +2 -2 modperl-site/guide/download.html Index: download.html =================================================================== RCS file: /home/cvs/modperl-site/guide/download.html,v retrieving revision 1.15 retrieving revision 1.16 diff -u -r1.15 -r1.16 --- download.html 2001/01/11 13:48:16 1.15 +++ download.html 2001/04/27 16:57:12 1.16 @@ -226,7 +226,7 @@ available from one of these URLs: <A HREF="http://modules.apache.org/search?id=124">http://modules.apache.org/search?id=124</A>, <A -HREF="ftp://ftp.netcetera.dk/pub/apache/mod_proxy_add_forward.c">ftp://ftp.netcetera.dk/pub/apache/mod_proxy_add_forward.c</A> +HREF="http://develooper.com/code/mpaf/mod_proxy_add_forward.c">http://develooper.com/code/mpaf/mod_proxy_add_forward.c</A> or <A HREF="http://www.cpan.org/authors/id/ABH/mod_proxy_add_forward.c">http://www.cpan.org/authors/id/ABH/mod_proxy_add_forward.c</A>, complete with instructions on how to compile it and whatnot. @@ -450,7 +450,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 12/08/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 02/09/2001 </font></b> <br> 1.28 +65 -15 modperl-site/guide/help.html Index: help.html =================================================================== RCS file: /home/cvs/modperl-site/guide/help.html,v retrieving revision 1.27 retrieving revision 1.28 diff -u -r1.27 -r1.28 --- help.html 2001/01/11 13:48:16 1.27 +++ help.html 2001/04/27 16:57:12 1.28 @@ -140,10 +140,10 @@ <P> <A HREF="http://perl.apache.org">http://perl.apache.org</A> -<P><LI><STRONG><A NAME="item_mod_perl">mod_perl Source Garden project</A></STRONG> +<P><LI><STRONG><A NAME="item_News">News and Resources</A></STRONG> <P> -<A -HREF="http://modperl.sourcegarden.org">http://modperl.sourcegarden.org</A> +Take23: News and Resources for the mod_perl world <A +HREF="http://take23.org">http://take23.org</A> <P><LI><STRONG><A NAME="item_mod_perl">mod_perl Books</A></STRONG> <UL> @@ -177,16 +177,31 @@ </tr> </table> - <P><LI><STRONG><A NAME="item__Enabling_web_services_with_mod_">'Enabling web services with mod_perl' Book</A></STRONG> + <P><LI><STRONG><A NAME="item__Managing_and_Programming_mod_pe">'Managing and Programming mod_perl' Book</A></STRONG> <P> <A HREF="http://www.modperlbook.com">http://www.modperlbook.com</A> is the home site of the new mod_perl book, that Eric Cholet and Stas Bekman are -co-authoring. We expect the book to be published in fall 2000. +co-authoring. We expect the book to be published in 2001. <P> Ideas, suggestions and comments are welcome. Please send them to <A HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A> . +<P><LI><STRONG><A NAME="item_mod_perl">mod_perl Quick Reference Card</A></STRONG> +<P> +<EM>mod_perl Pocket Reference</EM> by Andrew Ford was published by O'Reilly and Associates <A +HREF="http://www.oreilly.com/catalog/modperlpr/">http://www.oreilly.com/catalog/modperlpr/</A> + + +<P> +You should probably get also the <EM>Apache Pocket Reference</EM> by the same author and the same publisher: <A +HREF="http://www.oreilly.com/catalog/apachepr/">http://www.oreilly.com/catalog/apachepr/</A> + + +<P> +See also Andrew's collection of reference card for Apache and other +programs: <A HREF="http://www.refcards.com.">http://www.refcards.com.</A> + </UL> <P><LI><STRONG><A NAME="item_mod_perl">mod_perl Guide</A></STRONG> <P> @@ -221,20 +236,19 @@ HREF="http://perl.apache.org/dist/mod_perl_traps.html">http://perl.apache.org/dist/mod_perl_traps.html</A> . -<P><LI><STRONG><A NAME="item_mod_perl">mod_perl Quick Reference Card</A></STRONG> -<P> -<A HREF="http://www.refcards.com">http://www.refcards.com</A> (Reference -cards for Apache and other programs are available from this link) - <P><LI><STRONG><A NAME="item_Articles">Articles</A></STRONG> <UL> <P><LI><STRONG><A NAME="item_PerlMonth">PerlMonth</A></STRONG> <P> <A HREF="http://perlmonth.com">http://perlmonth.com</A> -<P><LI><STRONG><A NAME="item_Basic">Basic knowledge about Apache stages and -mod_perl handlers article in German</A></STRONG> +<P><LI><STRONG><A NAME="item_ApacheToday">ApacheToday</A></STRONG> <P> +<A HREF="http://apachetoday.com">http://apachetoday.com</A> + +<P><LI><STRONG><A NAME="item_Basic">Basic knowledge about Apache stages and mod_perl handlers +article in German</A></STRONG> +<P> <A HREF="http://www.heise.de/ix/artikel/2000/01/156/">http://www.heise.de/ix/artikel/2000/01/156/</A> @@ -250,8 +264,7 @@ HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A> . To unsubscribe send email to <A HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A> -. Send email to <A HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A> -to post to the list. +. <P> To subscribe to the digest list send email to <A @@ -362,6 +375,41 @@ - This page describes the mechanics of creating, compiling, releasing and maintaining Perl modules. +<P><LI><STRONG><A NAME="item_XS">XS tutorials</A></STRONG> +<P> +Perl manpages: <EM>perlguts</EM>, <EM>perlxs</EM>, and <EM>perlxstut</EM> manpages. + +<P> +Dean Roehrich's XS CookBookA and CookBookB <A +HREF="http://search.cpan.org/search?dist=CookBookA">http://search.cpan.org/search?dist=CookBookA</A> +<A +HREF="http://search.cpan.org/search?dist=CookBookB">http://search.cpan.org/search?dist=CookBookB</A> + + +<P> +a series of articles at PerlMonth.com by Steven McDougall: <A +HREF="http://www.perlmonth.com/columns/modules/modules.html?issue=6">http://www.perlmonth.com/columns/modules/modules.html?issue=6</A> +<A +HREF="http://www.perlmonth.com/columns/modules/modules.html?issue=7">http://www.perlmonth.com/columns/modules/modules.html?issue=7</A> +<A +HREF="http://www.perlmonth.com/columns/modules/modules.html?issue=8">http://www.perlmonth.com/columns/modules/modules.html?issue=8</A> +<A +HREF="http://www.perlmonth.com/columns/modules/modules.html?issue=9">http://www.perlmonth.com/columns/modules/modules.html?issue=9</A> +<A +HREF="http://www.perlmonth.com/columns/modules/modules.html?issue=10">http://www.perlmonth.com/columns/modules/modules.html?issue=10</A> + + +<P> +<EM>Advanced Perl Programming</EM> By Sriram Srinivasan. Published by O'Reilly & Associates. ISBN: +1-56592-220-4. Chapters 18-20. + +<P> +perl-xs mailing list on perl.org (mail <A +HREF="mailto:[EMAIL PROTECTED])">[EMAIL PROTECTED])</A> + +<P> +Take a look also at Inline.pm (CPAN) and SWIG (http://www.swig.org/) + <P><LI><STRONG><A NAME="item_perl5">perl5-porters mailing list</A></STRONG> <P> Send an email: @@ -654,6 +702,8 @@ HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A> Subscribe by sending a message to <A HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A> +Archive: <A +HREF="http:[EMAIL PROTECTED]/">http:[EMAIL PROTECTED]/</A> <P><LI> @@ -736,7 +786,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 12/25/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 03/20/2001 </font></b> <br> 1.33 +3 -3 modperl-site/guide/index.html Index: index.html =================================================================== RCS file: /home/cvs/modperl-site/guide/index.html,v retrieving revision 1.32 retrieving revision 1.33 diff -u -r1.32 -r1.33 --- index.html 2001/01/11 13:48:16 1.32 +++ index.html 2001/04/27 16:57:12 1.33 @@ -22,7 +22,7 @@ </p> </center> - <center><p><b>Version 1.28 Jan 11, 2001</b></p></center> + <center><p><b>Version 1.29 Apr 28, 2001</b></p></center> <table align=center width="70%"> @@ -313,7 +313,7 @@ <div class="notice"> Full Version Master Copy URL: <a href="http://perl.apache.org/guide/"><b>http://perl.apache.org/guide</b></a><br> - Copyright © 1998-2000 Stas Bekman. All rights + Copyright © 1998-2001 Stas Bekman. All rights reserved. (Distributed under GPL license) </div> </td> @@ -333,7 +333,7 @@ <b><font size=-1> Written by <a href="help.html#Contacting_me">Stas - Bekman</a>.<br> Last Modified at 01/11/2001 + Bekman</a>.<br> Last Modified at 04/28/2001 </font></b> <br> 1.7 +14 -16 modperl-site/guide/index_long.html Index: index_long.html =================================================================== RCS file: /home/cvs/modperl-site/guide/index_long.html,v retrieving revision 1.6 retrieving revision 1.7 diff -u -r1.6 -r1.7 --- index_long.html 2001/01/11 13:48:17 1.6 +++ index_long.html 2001/04/27 16:57:13 1.7 @@ -22,7 +22,7 @@ </p> </center> - <center><p><b>Version 1.28 Jan 11, 2001</b></p></center> + <center><p><b>Version 1.29 Apr 28, 2001</b></p></center> <table align=center width="70%"> @@ -202,7 +202,7 @@ </UL> <LI><A HREF="install.html#Reusing_Configuration_Parameters">Reusing Configuration Parameters</A> - <LI><A HREF="install.html#Discovering_whether_some_option_">Discovering whether some option was configured</A> + <LI><A HREF="install.html#Discovering_Whether_Some_Option_">Discovering Whether Some Option Was Configured</A> <LI><A HREF="install.html#Using_an_Alternative_Configurati">Using an Alternative Configuration File</A> <LI><A HREF="install.html#perl_Makefile_PL_Troubleshooting">perl Makefile.PL Troubleshooting</A> <UL> @@ -384,7 +384,6 @@ <LI><A HREF="config.html#The_Sample_Startup_File">The Sample Startup File</A> <LI><A HREF="config.html#What_Modules_You_Should_Add_to_t">What Modules You Should Add to the Startup File and Why</A> <LI><A HREF="config.html#The_Confusion_with_use_in_the_">The Confusion with use() in the Server Startup File</A> - <LI><A HREF="config.html#The_Confusion_with_Global_Variab">The Confusion with Global Variables in the Startup File</A> </UL> <LI><A HREF="config.html#Apache_Configuration_in_Perl">Apache Configuration in Perl</A> @@ -775,7 +774,7 @@ </UL> <LI><A HREF="performance.html#Imported_Symbols_and_Memory_Usag">Imported Symbols and Memory Usage</A> - <LI><A HREF="performance.html#Concatenation_or_List">Concatenation or List</A> + <LI><A HREF="performance.html#Interpolation_Concatenation_or_">Interpolation, Concatenation or List</A> <LI><A HREF="performance.html#Using_Perl_stat_Call_s_Cached_">Using Perl stat() Call's Cached Results</A> </UL> @@ -857,6 +856,7 @@ <LI><A HREF="performance.html#_Dusemymalloc_Perl_Build_Option">-Dusemymalloc Perl Build Option</A> </UL> + <LI><A HREF="performance.html#Architecture_Specific_Compile_Op">Architecture Specific Compile Options</A> </UL> <P> <LI><A HREF="frequent.html"><B><FONT SIZE=+1>Frequent mod_perl problems </FONT></B></A></LI><P> @@ -896,6 +896,7 @@ <LI><A HREF="troubleshooting.html#Runtime">Runtime</A> <UL> + <LI><A HREF="troubleshooting.html#_exit_signal_Segmentation_fault_">"exit signal Segmentation fault (11)" with mysql</A> <LI><A HREF="troubleshooting.html#foo_at_dev_null_line_0">foo ... at /dev/null line 0</A> <LI><A HREF="troubleshooting.html#Preventing_mod_perl_Processes_Fr">Preventing mod_perl Processes From Going Wild</A> <LI><A HREF="troubleshooting.html#Segfaults_when_using_XML_Parser">Segfaults when using XML::Parser</A> @@ -1055,7 +1056,7 @@ <LI><A HREF="multiuser.html#ISPs_providing_mod_perl_services">ISPs providing mod_perl services - a fantasy or a reality</A> <UL> - <LI><A HREF="multiuser.html#Other_resources_related_to_mod_p">Other resources related to mod_perl hosting to look at</A> + <LI><A HREF="multiuser.html#Virtual_Servers_Technologies">Virtual Servers Technologies</A> </UL> <LI><A HREF="multiuser.html#Virtual_Hosts_in_the_guide">Virtual Hosts in the guide</A> @@ -1181,8 +1182,8 @@ <LI><A HREF="modules.html#Apache_RegistryNG_Apache_Re">Apache::RegistryNG -- Apache::Registry New Generation</A> <LI><A HREF="modules.html#Apache_RegistryBB_Apache_Re">Apache::RegistryBB -- Apache::Registry Bare Bones </A> <LI><A HREF="modules.html#Apache_OutputChain_Chain_Sta">Apache::OutputChain -- Chain Stacked Perl Handlers</A> - <LI><A HREF="modules.html#Apache_GzipChain_compress_HTM">Apache::GzipChain - compress HTML (or anything) in the OutputChain</A> <LI><A HREF="modules.html#Apache_Filter_Alter_the_outpu">Apache::Filter - Alter the output of previous handlers</A> + <LI><A HREF="modules.html#Apache_GzipChain_compress_HTM">Apache::GzipChain - compress HTML (or anything) in the OutputChain</A> <LI><A HREF="modules.html#Apache_Gzip_Auto_compress_web">Apache::Gzip - Auto-compress web files with Gzip</A> <LI><A HREF="modules.html#Apache_PerlVINC_Allows_Module">Apache::PerlVINC - Allows Module Versioning in Location blocks and Virtual Hosts</A> <LI><A HREF="modules.html#Apache_LogSTDERR">Apache::LogSTDERR</A> @@ -1194,12 +1195,8 @@ <UL> <LI><A HREF="snippets.html#Redirecting_Errors_to_the_Client">Redirecting Errors to the Client Instead of error_log</A> - <LI><A HREF="snippets.html#Emulating_the_Authentication_Mec">Emulating the Authentication Mechanism</A> - <LI><A HREF="snippets.html#Caching_POSTed_Data">Caching POSTed Data</A> - <LI><A HREF="snippets.html#Cache_Control_for_Regular_and_Er">Cache Control for Regular and Error Modes</A> - <LI><A HREF="snippets.html#Convert_a_POST_Request_into_a_GE">Convert a POST Request into a GET Request</A> - <LI><A HREF="snippets.html#Redirect_a_POST_Request_Forward">Redirect a POST Request, Forwarding the Content</A> - <LI><A HREF="snippets.html#Reading_POST_Data_then_Redirect">Reading POST Data, then Redirecting or Doing Something Else</A> + <LI><A HREF="snippets.html#Reusing_Data_from_POST_request">Reusing Data from POST request</A> + <LI><A HREF="snippets.html#Redirecting_POST_Requests">Redirecting POST Requests</A> <LI><A HREF="snippets.html#Redirecting_While_Maintaining_En">Redirecting While Maintaining Environment Variables</A> <LI><A HREF="snippets.html#Terminating_a_Child_Process_on_R">Terminating a Child Process on Request Completion</A> <LI><A HREF="snippets.html#More_on_Relative_Paths">More on Relative Paths</A> @@ -1215,12 +1212,13 @@ <LI><A HREF="snippets.html#Subclassing_Apache_Request">Subclassing Apache::Request</A> <LI><A HREF="snippets.html#Sending_Email_from_mod_perl">Sending Email from mod_perl</A> <LI><A HREF="snippets.html#A_Simple_Handler_To_Print_The_En">A Simple Handler To Print The Environment Variables</A> - <LI><A HREF="snippets.html#mod_rewrite_Based_On_Query_Strin">mod_rewrite Based On Query String and URI Implemented in Perl</A> - <LI><A HREF="snippets.html#PerlTransHandler_example">PerlTransHandler example</A> + <LI><A HREF="snippets.html#mod_rewrite_in_Perl">mod_rewrite in Perl</A> + <LI><A HREF="snippets.html#URI_Rewrite_in_PerlTransHandler">URI Rewrite in PerlTransHandler </A> <LI><A HREF="snippets.html#Setting_PerlHandler_Based_on_MIM">Setting PerlHandler Based on MIME Type</A> <LI><A HREF="snippets.html#SSI_and_Embperl_Doing_Both">SSI and Embperl -- Doing Both</A> <LI><A HREF="snippets.html#Getting_the_Front_end_Server_s_N">Getting the Front-end Server's Name in the Back-end Server</A> <LI><A HREF="snippets.html#Authentication_Snippets">Authentication Snippets</A> + <LI><A HREF="snippets.html#Emulating_the_Authentication_Mec">Emulating the Authentication Mechanism</A> <LI><A HREF="snippets.html#An_example_of_using_Apache_Sess">An example of using Apache::Session::DBI with cookies</A> <LI><A HREF="snippets.html#Using_DESTROY_to_Finalize_Output">Using DESTROY to Finalize Output</A> <LI><A HREF="snippets.html#Setting_Environment_Variables_Fo">Setting Environment Variables For Scripts Called From CGI.</A> @@ -1500,7 +1498,7 @@ <div class="notice"> Full Version Master Copy URL: <a href="http://perl.apache.org/guide/"><b>http://perl.apache.org/guide</b></a><br> - Copyright © 1998-2000 Stas Bekman. All rights + Copyright © 1998-2001 Stas Bekman. All rights reserved. (Distributed under GPL license) </div> </td> @@ -1520,7 +1518,7 @@ <b><font size=-1> Written by <a href="help.html#Contacting_me">Stas - Bekman</a>.<br> Last Modified at 01/11/2001 + Bekman</a>.<br> Last Modified at 04/28/2001 </font></b> <br> 1.20 +137 -52 modperl-site/guide/install.html Index: install.html =================================================================== RCS file: /home/cvs/modperl-site/guide/install.html,v retrieving revision 1.19 retrieving revision 1.20 diff -u -r1.19 -r1.20 --- install.html 2001/01/11 13:48:17 1.19 +++ install.html 2001/04/27 16:57:13 1.20 @@ -62,7 +62,7 @@ </UL> <LI><A HREF="#Reusing_Configuration_Parameters">Reusing Configuration Parameters</A> - <LI><A HREF="#Discovering_whether_some_option_">Discovering whether some option was configured</A> + <LI><A HREF="#Discovering_Whether_Some_Option_">Discovering Whether Some Option Was Configured</A> <LI><A HREF="#Using_an_Alternative_Configurati">Using an Alternative Configuration File</A> <LI><A HREF="#perl_Makefile_PL_Troubleshooting">perl Makefile.PL Troubleshooting</A> <UL> @@ -283,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 distribution that uses RPM or deb files: +if you are using a Linux distribution that uses RPM packages: <P> @@ -302,7 +302,7 @@ </tr> </table> <P> -or +or apt system: <P> @@ -314,8 +314,7 @@ </td> <td> - <pre> % dpkg -i apache-xx.xx.deb - % dpkg -i mod_perl-xx.xx.deb</pre> + <pre> % apt-get install libapache-mod-perl</pre> </td> </tr> @@ -712,7 +711,8 @@ <td> <pre> PERL_POST_READ_REQUEST PERL_TRANS - PERL_INIT</pre> + PERL_INIT + PERL_RESTART (experimental)</pre> </td> </tr> @@ -752,7 +752,7 @@ <CODE>PERL_hookname=1</CODE> to enable them (e.g. <CODE>PERL_AUTHEN=1</CODE>). <P> -To enable all callback hooks use: +To enable all, but the last 4 callback hooks use: <P> @@ -898,7 +898,7 @@ <HR> <CENTER><H4><A NAME="APACHE_PREFIX">APACHE_PREFIX</A></H4></CENTER> <P> -If you want to use a non-default Apache installation directory, use the <CODE>APACHE_PREFIX</CODE> parameter, e.g.: +Alternatively to: <P> @@ -910,14 +910,14 @@ </td> <td> - <pre> % perl Makefile.PL APACHE_PREFIX=/usr/local/ [...]</pre> + <pre> APACI_ARGS='--prefix=/usr/local/httpd_perl'</pre> </td> </tr> </table> <P> -This should be used together with the <A HREF="././install.html#APACI_ARGS">APACI_ARGS</A> -option. +from the previous section you can use the <CODE>APACHE_PREFIX</CODE> parameter. When <CODE>USE_APACI</CODE> is enabled, this attribute will specify the +<EM>--prefix</EM> option just like the above setting does. <P> In addition when the <CODE>APACHE_PREFIX</CODE> option is used <CODE>make install</CODE> @@ -1078,11 +1078,15 @@ <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> -<CENTER><H3><A NAME="Discovering_whether_some_option_">Discovering whether some option was configured</A></H3></CENTER> +<CENTER><H3><A NAME="Discovering_Whether_Some_Option_">Discovering Whether Some Option Was Configured</A></H3></CENTER> +<P> +mod_perl version 1.25 has introduced <CODE>Apache::Myconfig</CODE>, which provides access to the various hooks and features set when mod_perl +is built. This circumvents the need to set up a live server just to find +out if a certain callback hook is available. + <P> -To find out whether some parameter was included in the server, you can take -a look at the symbols inside the httpd executable with help of -<CODE>nm</CODE> or a similar utility. For example if you want to see whether you enabled <CODE>PERL_AUTH=1</CODE> while building mod_perl, you do: +To see whether some feature was built in or not, check the +<CODE>%Apache::MyConfig::Setup</CODE> hash. For example after installing mod_perl with the following options: <P> @@ -1094,29 +1098,72 @@ </td> <td> - <pre> % nm httpd | grep perl_authenticate</pre> + <pre> panic% perl Makefile.PL EVERYTHING=1</pre> </td> </tr> </table> <P> -But this will only work if you have an unstripped httpd binary. By default, <CODE>make install</CODE> strips the binary before installing it. +but on the next day we don't remember what callback hooks were enabled, and +we want to know whether <CODE>PERL_LOG</CODE> callback hook is enabled. One of the ways to find this out is to run the +following code: <P> -Another approach is to configure <A HREF="././debug.html#Apache_Status_Embedded_Inter">/perl-status location</A> and run <A + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> panic% perl -MApache::MyConfig \ + -e 'print $Apache::MyConfig::Setup{PERL_LOG}' + 1</pre> + </td> + + </tr> + </table> + <P> +which prints '1'--meaning that <CODE>PERL_LOG</CODE> callback hook was enabled. (That's because <CODE>EVERYTHING=1</CODE> enables them all.) + +<P> +Another approach is to configure <CODE>Apache::Status</CODE> as explain on page XXX of Chapter YYY and run <A HREF="http://localhost/perl-status?hooks">http://localhost/perl-status?hooks</A> -to check the enabled hooks. +to check for enabled hooks. <P> -Yet another approach is to try to use this parameter in the configuration -file. If it wasn't enabled Apache will tell you when you start the server, -by reporting an unknown directive. +You also may try to look at the symbols inside the httpd executable with +help of <CODE>nm(1)</CODE> or a similar utility. For example if you want to see whether you enabled <CODE>PERL_LOG=1</CODE> while building mod_perl, we can search for a symbol with the same name but +in lowercase: <P> -Similarly, for example, when you attempt to use <CODE>PerlAuthenHandler</CODE> -without building Apache with the <CODE>PERL_AUTHEN=1</CODE> parameter, Apache will give an error message. + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> panic% nm httpd | grep perl_log + 08071724 T perl_logger</pre> + </td> + + </tr> + </table> + <P> +Indeed we can see that in our example <CODE>PERL_LOG=1</CODE> was enabled. But this will only work if you have an unstripped httpd +binary. By default, <CODE>make install</CODE> strips the binary before installing it. Use the <CODE>--without-execstrip</CODE> <CODE>./Configure</CODE> option to prevent stripping during <EM>make install</EM> phase. + <P> +Yet another approach that will work in most of the cases is to try to use +the feature in question. If it wasn't configured Apache will give an error +message + +<P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H3><A NAME="Using_an_Alternative_Configurati">Using an Alternative Configuration File</A></H3></CENTER> @@ -1733,7 +1780,7 @@ to remove the pre-installed RPM package first! <P> -Debian users would do: +Users with apt systems would do: <P> @@ -1745,7 +1792,7 @@ </td> <td> - <pre> % dpkg -r apache</pre> + <pre> % apt-get remove apache</pre> </td> </tr> @@ -2186,18 +2233,17 @@ </td> <td> - <pre> $ cd mod_perl-x.xx - $ perl Makefile.PL \ - APACHE_SRC=../apache_x.x.x/src \ - NO_HTTPD=1 \ - USE_APACI=1 \ - PREP_HTTPD=1 \ - EVERYTHING=1 \ - [...] - $ make - $ make test - $ make install - $ cd ..</pre> + <pre> $ cd mod_perl-x.xx + $ perl Makefile.PL \ + APACHE_SRC=../apache_x.x.x/src \ + NO_HTTPD=1 \ + USE_APACI=1 \ + PREP_HTTPD=1 \ + EVERYTHING=1 \ + [...] + $ make + $ make install + $ cd ..</pre> </td> </tr> @@ -2240,14 +2286,13 @@ </td> <td> - <pre> $ cd apache_x.x.x - $ ./configure \ - --prefix=/path/to/install/of/apache \ - --activate-module=src/modules/perl/libperl.a \ - [...] - $ make - $ make test - $ make install</pre> + <pre> $ cd apache_x.x.x + $ ./configure \ + --prefix=/path/to/install/of/apache \ + --activate-module=src/modules/perl/libperl.a \ + [...] + $ make + $ make install</pre> </td> </tr> @@ -3860,9 +3905,7 @@ <pre> % cd ../mod_perl-x.xx % perl Makefile.PL APACHE_SRC=../apache_x.x.xx/src NO_HTTPD=1 \ USE_APACI=1 PREP_HTTPD=1 EVERYTHING=1 - % make - % make test - % make install</pre> + % make</pre> </td> </tr> @@ -3892,7 +3935,7 @@ </table> <P><LI> <P> -Complete the Apache installation. +Build Apache: <P> @@ -3909,7 +3952,49 @@ --activate-module=src/modules/perl/libperl.a \ --activate-module=src/modules/php3/libphp3.a \ --enable-module=stats \ - --enable-module=rewrite</pre> + --enable-module=rewrite + % make</pre> + </td> + + </tr> + </table> + <P><LI> +<P> +Test and install mod_perl + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> % cd ../mod_perl-x.xx + % make test + # make install.</pre> + </td> + + </tr> + </table> + <P><LI> +<P> +Complete the Apache installation. + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> % cd ../apache_x.x.xx + # make install</pre> </td> </tr> @@ -6881,7 +6966,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 12/12/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 04/19/2001 </font></b> <br> 1.26 +5 -4 modperl-site/guide/intro.html Index: intro.html =================================================================== RCS file: /home/cvs/modperl-site/guide/intro.html,v retrieving revision 1.25 retrieving revision 1.26 diff -u -r1.25 -r1.26 --- intro.html 2001/01/11 13:48:17 1.25 +++ intro.html 2001/04/27 16:57:14 1.26 @@ -593,10 +593,11 @@ <P><LI> <P> -<STRONG>mod_perl mailing list emails</STRONG>. Answers to some of the questions posted to <A -HREF="mailto:[EMAIL PROTECTED]">[EMAIL PROTECTED]</A> Apache/Perl mailing -list. +<STRONG>mod_perl mailing list emails</STRONG>. Answers to some of the questions posted to Apache/Perl mailing list. (To +send email to <A +HREF="mailto:[EMAIL PROTECTED])">[EMAIL PROTECTED])</A> + <P><LI> <P> <STRONG>My personal experience with mod_perl</STRONG>. @@ -916,7 +917,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 01/07/2001 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 03/20/2001 </font></b> <br> 1.10 +5036 -4975modperl-site/guide/mod_perl_guide.pdf.gz <<Binary file>> 1.20 +179 -73 modperl-site/guide/modules.html Index: modules.html =================================================================== RCS file: /home/cvs/modperl-site/guide/modules.html,v retrieving revision 1.19 retrieving revision 1.20 diff -u -r1.19 -r1.20 --- modules.html 2001/01/11 13:48:20 1.19 +++ modules.html 2001/04/27 16:57:19 1.20 @@ -45,8 +45,8 @@ <LI><A HREF="#Apache_RegistryNG_Apache_Re">Apache::RegistryNG - Apache::Registry New Generation</A> <LI><A HREF="#Apache_RegistryBB_Apache_Re">Apache::RegistryBB - Apache::Registry Bare Bones </A> <LI><A HREF="#Apache_OutputChain_Chain_Sta">Apache::OutputChain - Chain Stacked Perl Handlers</A> - <LI><A HREF="#Apache_GzipChain_compress_HTM">Apache::GzipChain - compress HTML (or anything) in the OutputChain</A> <LI><A HREF="#Apache_Filter_Alter_the_outpu">Apache::Filter - Alter the output of previous handlers</A> + <LI><A HREF="#Apache_GzipChain_compress_HTM">Apache::GzipChain - compress HTML (or anything) in the OutputChain</A> <LI><A HREF="#Apache_Gzip_Auto_compress_web">Apache::Gzip - Auto-compress web files with Gzip</A> <LI><A HREF="#Apache_PerlVINC_Allows_Module">Apache::PerlVINC - Allows Module Versioning in Location blocks and Virtual Hosts</A> <LI><A HREF="#Apache_LogSTDERR">Apache::LogSTDERR</A> @@ -164,8 +164,8 @@ <P> Using <CODE>Apache::Session</CODE> is easy: simply tie a hash to the session object, stick any data structure into the hash, and the data you put in automatically persists until the -next invocation. Here is a quick example which uses cookies to track the -user's session. +next invocation. Here is an example which uses cookies to track the user's +session. <P> @@ -177,18 +177,18 @@ </td> <td> - <pre> # Pull in the required packages + <pre> # pull in the required packages use Apache::Session::DBI; use Apache; use strict; - # Read in the cookie if this is an old session + # read in the cookie if this is an old session my $r = Apache->request; my $cookie = $r->header_in('Cookie'); $cookie =~ s/SESSION_ID=(\w*)/$1/; - # Create a session object based on the cookie we got from the + # create a session object based on the cookie we got from the # browser, or a new session if we got no cookie my %session; tie %session, 'Apache::Session::DBI', $cookie, @@ -197,7 +197,7 @@ Password => $db_pass }; - # Might be a new session, so lets give them their cookie back + # might be a new session, so lets give them their cookie back my $session_cookie = "SESSION_ID=$session{_session_id};"; $r->header_out("Set-Cookie" => $session_cookie);</pre> </td> @@ -206,8 +206,8 @@ </table> <P> After setting this up, you can stick anything you want into -<CODE>%session</CODE> (except file handles and code references), and it -will still be there when the user invokes the next page. +<CODE>%session</CODE> (except file handles and code references and using +<EM>_session_id</EM>), and it will still be there when the user invokes the next page. <P> It is possible to write an Apache authentication handler using @@ -229,8 +229,8 @@ Linux. IIS? <P> -An alternative to <CODE>Apache::Session</CODE> is Apache::ASP, which has session tracking abilities. HTML::Embperl hooks -into <CODE>Apache::Session</CODE> for you. +An alternative to <CODE>Apache::Session</CODE> is <CODE>Apache::ASP</CODE>, which has session tracking abilities. <CODE>HTML::Embperl</CODE> hooks into +<CODE>Apache::Session</CODE> for you. <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] @@ -437,7 +437,7 @@ <pre> PerlModule Apache::RegistryNG <Location /perl> SetHandler perl-script - PerlHandler ApacheRegistryNG->handler + PerlHandler Apache::RegistryNG->handler </Location></pre> </td> @@ -486,9 +486,9 @@ <HR> <CENTER><H1><A NAME="Apache_RegistryBB_Apache_Re">Apache::RegistryBB -- Apache::Registry Bare Bones</A></H1></CENTER> <P> -It works just like <CODE>Apache::Registry</CODE>, but does not test the x bit (-x) only compiles the file once (no -<CODE>stat()</CODE> call is made per requsest), skips the OPT_EXECCGI -checks and does not <CODE>chdir()</CODE> into the script parent directory. It uses the Object Oriented interface. +It works just like <CODE>Apache::Registry</CODE>, but does not test the x bit (-x file test for executable mode), only +compiles the file once (no <CODE>stat()</CODE> call is made per request), +skips the <CODE>OPT_EXECCGI</CODE> checks and does not <CODE>chdir()</CODE> into the script parent directory. It uses the Object Oriented interface. <P> Configuration: @@ -506,16 +506,13 @@ <pre> PerlModule Apache::RegistryBB <Location /perl> SetHandler perl-script - PerlHandler ApacheRegistryBB->handler + PerlHandler Apache::RegistryBB->handler </Location></pre> </td> </tr> </table> <P> -See <A HREF="././modules.html#Apache_RegistryNG_Apache_Re">Apache::RegistryNG</A> for more info. - -<P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H1><A NAME="Apache_OutputChain_Chain_Sta">Apache::OutputChain -- Chain Stacked Perl Handlers</A></H1></CENTER> @@ -553,13 +550,12 @@ </tr> </table> <P> -The modules are listed in the reverse order of their execution -- here the <CODE>Apache::PassHtml</CODE> module simply picks a file's content and sends it to STDOUT ... then it's -processed by <CODE>Apache::SSIChain</CODE>, which sends its output to STDOUT again ... then it's processed by +The modules are listed in the reverse order of their execution -- here the <CODE>Apache::PassHtml</CODE> module simply picks a file's content and sends it to STDOUT, then it's +processed by <CODE>Apache::SSIChain</CODE>, which sends its output to STDOUT again. Then it's processed by <CODE>Apache::OutputChain</CODE>, which finally sends the result to the browser. <P> -An alternative to this approach is <CODE>Apache::Filter</CODE>, which has a more natural ``forward'' configuration order and is easier to -interface with other modules. +An alternative to this approach is <CODE>Apache::Filter</CODE>, which has a more natural <EM>forward</EM> configuration order and is easier to interface with other modules. <P> It works with <CODE>Apache::Registry</CODE> as well, for example: @@ -593,6 +589,14 @@ <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> +<CENTER><H1><A NAME="Apache_Filter_Alter_the_outpu">Apache::Filter - Alter the output of previous handlers</A></H1></CENTER> +<P> +META: to be written (actually summarized the info from Apache::Filter +manpage) + +<P> +[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] +<HR> <CENTER><H1><A NAME="Apache_GzipChain_compress_HTM">Apache::GzipChain - compress HTML (or anything) in the OutputChain</A></H1></CENTER> <P> Have you ever served a huge HTML file (e.g. a file bloated with JavaScript @@ -656,11 +660,11 @@ </tr> </table> <P> -Hint: Watch the <CODE>access_log</CODE> file to see how many bytes were actually sent, and compare that with the +Hint: Watch the <EM>access_log</EM> file to see how many bytes were actually sent, and compare that with the bytes sent using a regular configuration. <P> -(See also <CODE>perldoc Apache::GzipChain</CODE>). +(See also <CODE>Apache::GzipChain</CODE>). <P> Notice that the rightmost PerlHandler must be a content producer. Here we @@ -669,18 +673,9 @@ <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> -<CENTER><H1><A NAME="Apache_Filter_Alter_the_outpu">Apache::Filter - Alter the output of previous handlers</A></H1></CENTER> -<P> -META: to be written (actually summarized the info from Apache::Filter -manpage) - -<P> -[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] -<HR> <CENTER><H1><A NAME="Apache_Gzip_Auto_compress_web">Apache::Gzip - Auto-compress web files with Gzip</A></H1></CENTER> <P> -Similar to <A HREF="././modules.html#Apache_GzipChain_compress_HTM">Apache::GzipChain</A> -but works with <CODE>Apache::Filter</CODE>. +Similar to <CODE>Apache::GzipChain</CODE> but works with <CODE>Apache::Filter</CODE>. <P> This configuration: @@ -733,7 +728,8 @@ </tr> </table> <P> -Will compess the output of the <CODE>Apache::Registry</CODE> scripts. Yes, you should write <CODE>Apache::RegistryFilter</CODE> and not <CODE>Apache::Registry</CODE>. +will compess the output of the <CODE>Apache::Registry</CODE> scripts. Yes, you should use <CODE>Apache::RegistryFilter</CODE> instead of <CODE>Apache::Registry</CODE> +for it to work. <P> You can use as many filters as you want: @@ -772,7 +768,7 @@ </td> <td> - <pre> telnet localhost 8000 + <pre> panic% telnet localhost 8000 Trying 127.0.0.1 Connected to 127.0.0.1 Escape character is '^]'. @@ -1019,8 +1015,8 @@ <HR> <CENTER><H1><A NAME="Apache_SubProcess">Apache::SubProcess</A></H1></CENTER> <P> -The output of <CODE>system()</CODE>, <CODE>exec()</CODE>, and <CODE>open(PIPE,"|program")</CODE> calls will not be sent to the browser unless your Perl was configured with -<CODE>sfio</CODE>. +The output of <CODE>system()</CODE>, <CODE>exec()</CODE>, and <CODE>open(PIPE,"|program")</CODE> +calls will not be sent to the browser unless your Perl was configured with <CODE>sfio</CODE>. <P> One workaround is to use backticks: @@ -1058,67 +1054,177 @@ </td> <td> - <pre> use strict; - use Apache::SubProcess qw(system exec); + <pre> use Apache::SubProcess qw(system); + my $r = shift; + $r->send_http_header('text/plain'); + system "/bin/echo hi there";</pre> + </td> + + </tr> + </table> + <P> +overrides built-in <CODE>system()</CODE> function and sends the output to +the browser. + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> use Apache::SubProcess qw(exec); my $r = shift; $r->send_http_header('text/plain'); - # override built-in system() function - system "/bin/echo hi there"; + exec "/usr/bin/cal"; + + print "NOT REACHED\n";</pre> + </td> + + </tr> + </table> + <P> +overrides built-in <CODE>exec()</CODE> function and sends the output to the +browser. As you can see the print statement after the <CODE>exec()</CODE> +call will be never executed. + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> use Apache::SubProcess (); + my $r = shift; + $r->send_http_header('text/plain'); - # send the output of a program my $efh = $r->spawn_child(\&env); $r->send_fd($efh); - # pass arguments to a program and sends its output - my $fh = $r->spawn_child(\&banner); - $r->send_fd($fh); - - # pipe data to a program and send its output - use vars qw($String); - $String = "hello world"; - my($out, $in, $err) = $r->spawn_child(\&echo); - print $out $String; - $r->send_fd($in); - - # override the built-in exec() function - exec "/usr/bin/cal"; - - print "NOT REACHED\n"; - sub env { my $r = shift; - #$r->subprocess_env->clear; $r->subprocess_env(HELLO => 'world'); $r->filename("/bin/env"); $r->call_exec; - } + }</pre> + </td> + + </tr> + </table> + <P> +<CODE>env()</CODE> is a function that sets an environment variable that can +be seen by the main and sub-processes, then it executes <EM>/bin/env</EM> program via <CODE>call_exec().</CODE> The main code spawn a process, and +tells it to execute the <CODE>env()</CODE> function. This call returns an +output filehandler from the spawned child process. Finally it takes the +output generated by the child process and sends it to the browser via +<CODE>send_fd(),</CODE> that expects the filehandler as an argument. + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> use Apache::SubProcess (); + my $r = shift; + $r->send_http_header('text/plain'); + my $fh = $r->spawn_child(\&banner); + $r->send_fd($fh); + sub banner { my $r = shift; # /usr/games/banner on many Unices - $r->filename("/usr/bin/banner"); - $r->args("-w40+Hello%20World"); + $r->filename("/usr/bin/banner"); + $r->args("-w40+Hello%20World"); $r->call_exec; - } + }</pre> + </td> + + </tr> + </table> + <P> +This example is very similar to the previous, but shows how can you pass +arguments to the external process. It passes the string to print as a +banner to via a subprocess. + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> use Apache::SubProcess (); + my $r = shift; + $r->send_http_header('text/plain'); + use vars qw($String); + $String = "hello world"; + my($out, $in, $err) = $r->spawn_child(\&echo); + print $out $String; + $r->send_fd($in); + sub echo { my $r = shift; $r->subprocess_env(CONTENT_LENGTH => length $String); $r->filename("/tmp/pecho"); $r->call_exec; - } - # where /tmp/pecho is: - # -------------------- - #!/usr/bin/perl - #read STDIN, $buf, $ENV{CONTENT_LENGTH}; - #print "STDIN: `$buf' ($ENV{CONTENT_LENGTH})\n";</pre> + }</pre> </td> </tr> </table> - [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] + <P> +The last example shows how you can have a full access to STDIN, STDOUT and +STDERR streams of the spawned sub process, so you can pipe data to a +program and send its output to the browser. The <CODE>echo()</CODE> +function is similar to the earlier example's <CODE>env()</CODE> function. +The <EM>/tmp/pecho</EM> is as follows: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> !/usr/bin/perl + read STDIN, $buf, $ENV{CONTENT_LENGTH}; + print "STDIN: `$buf' ($ENV{CONTENT_LENGTH})\n";</pre> + </td> + + </tr> + </table> + <P> +So in the last example a string is defined as a global variable, so it's +length could be calculated in the <CODE>echo()</CODE> function. The +subprocess reads from STDIN, to which the main process writes the string (<EM>hello +world</EM>). It reads only a number of bytes specified by +<CODE>CONTENT_LENGTH</CODE> passed to the external program via environment variable. Finally the +external program prints the data that it read to STDOUT, the main program +intercepts it and sends to the client's socket (browser in most cases). + +[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> @@ -1171,7 +1277,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 12/25/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 03/26/2001 </font></b> <br> 1.17 +59 -5 modperl-site/guide/multiuser.html Index: multiuser.html =================================================================== RCS file: /home/cvs/modperl-site/guide/multiuser.html,v retrieving revision 1.16 retrieving revision 1.17 diff -u -r1.16 -r1.17 --- multiuser.html 2001/01/11 13:48:20 1.16 +++ multiuser.html 2001/04/27 16:57:19 1.17 @@ -37,7 +37,7 @@ <LI><A HREF="#ISPs_providing_mod_perl_services">ISPs providing mod_perl services - a fantasy or a reality</A> <UL> - <LI><A HREF="#Other_resources_related_to_mod_p">Other resources related to mod_perl hosting to look at</A> + <LI><A HREF="#Virtual_Servers_Technologies">Virtual Servers Technologies</A> </UL> <LI><A HREF="#Virtual_Hosts_in_the_guide">Virtual Hosts in the guide</A> @@ -342,7 +342,14 @@ <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> -<CENTER><H2><A NAME="Other_resources_related_to_mod_p">Other resources related to mod_perl hosting to look at</A></H2></CENTER> +<CENTER><H2><A NAME="Virtual_Servers_Technologies">Virtual Servers Technologies</A></H2></CENTER> +<P> +As we have just seen one of the obstacles of using mod_perl in ISP +environments, is the problem of isolating customers using the same machine +from each other. A number of virtual servers (don't confuse with virtual +hosts) technologies (both commercial and Open Source) exist today. Here are +some of them: + <UL> <P><LI><STRONG><A NAME="item_The">The User-mode Linux Kernel</A></STRONG> <P> @@ -370,8 +377,55 @@ from your users this might be yet another alternative to the solutions suggested at the beginning of this chapter. -<P><LI> -<P><LI> +<P><LI><STRONG><A NAME="item_VMWare">VMWare Technology</A></STRONG> +<P> +Allows running a few instances of the same or different OSs on the same +machine. This technology comes in two flavors: + +<P> +open source: <A +HREF="http://www.freemware.org/">http://www.freemware.org/</A> also known +as plex86 + +<P> +commercial: <A HREF="http://www.vmware.com/">http://www.vmware.com/</A> + +<P> +So you may want to run a separate OS for each of your clients + +<P><LI><STRONG><A NAME="item_freeVSD">freeVSD Technology</A></STRONG> +<P> +freeVSD (http://www.freevsd.org), an open source project sponsored by Idaya +Ltd. The software enables ISPs to securely partition their physical servers +into many <EM>virtual servers</EM>, each capable of running popular hosting applications such as Apache, +Sendmail and MySQL. + +<P><LI><STRONG><A NAME="item_S">S/390 IBM server</A></STRONG> +<P> +Quoting from: <A +HREF="http://www.s390.ibm.com/linux/vif/">http://www.s390.ibm.com/linux/vif/</A> + + +<P> +``The S/390 Virtual Image Facility enables you to run tens to hundreds of +Linux server images on a single S/390 server. It is ideally suited for +those who want to move Linux and/or UNIX workloads deployed on multiple +servers onto a single S/390 server, while maintaining the same number of +distinct server images. This provides centralized management and operation +of the multiple image environment, reducing complexity, easing +administration and lowering costs.'' + +<P> +In two words, this a great solution to huge ISPs, as it allows you to run +hundreds of mod_perl servers while having only one box to maintain. The +drawback is the price :) + +<P> +Check out this scalable mailing list thread for more details from those who +know: <A +HREF="http:[EMAIL PROTECTED]/msg00235.html">http:[EMAIL PROTECTED]/msg00235.html</A> + + </UL> <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] @@ -458,7 +512,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 11/20/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 03/11/2001 </font></b> <br> 1.32 +247 -90 modperl-site/guide/performance.html Index: performance.html =================================================================== RCS file: /home/cvs/modperl-site/guide/performance.html,v retrieving revision 1.31 retrieving revision 1.32 diff -u -r1.31 -r1.32 --- performance.html 2001/01/11 13:48:21 1.31 +++ performance.html 2001/04/27 16:57:20 1.32 @@ -134,7 +134,7 @@ </UL> <LI><A HREF="#Imported_Symbols_and_Memory_Usag">Imported Symbols and Memory Usage</A> - <LI><A HREF="#Concatenation_or_List">Concatenation or List</A> + <LI><A HREF="#Interpolation_Concatenation_or_">Interpolation, Concatenation or List</A> <LI><A HREF="#Using_Perl_stat_Call_s_Cached_">Using Perl stat() Call's Cached Results</A> </UL> @@ -216,6 +216,7 @@ <LI><A HREF="#_Dusemymalloc_Perl_Build_Option">-Dusemymalloc Perl Build Option</A> </UL> + <LI><A HREF="#Architecture_Specific_Compile_Op">Architecture Specific Compile Options</A> </UL> </div> @@ -3135,7 +3136,7 @@ </tr> </table> <P> -We are going to run memory benchmarks on five different versions of the <EM>startup.pl</EM> file. We always preload these modules: +We always preload these modules: <P> @@ -3153,7 +3154,10 @@ </tr> </table> - <DL> + <P> +We are going to run memory benchmarks on five different versions of the <EM>startup.pl</EM> file. + +<DL> <P><DT><STRONG><A NAME="item_option">option 1</A></STRONG><DD> <P> Leave the file unmodified. @@ -3228,8 +3232,13 @@ </tr> </table> - </DL> + <P><DT><STRONG>option 5</STRONG><DD> <P> +Options 2 and 4: using <CODE>connect_on_init()</CODE> and +<CODE>install_driver().</CODE> + +</DL> +<P> Here is the <CODE>Apache::Registry</CODE> test script that we have used: <P> @@ -3284,7 +3293,7 @@ </tr> </table> <P> -The script opens a connection to the database <EM>'test'</EM> and issues a query to learn what tables the databases has. When the data is +The script opens a opens a connection to the database <EM>'test'</EM> and issues a query to learn what tables the databases has. When the data is collected and printed the connection would be closed in the regular case, but <CODE>Apache::DBI</CODE> overrides it with empty method. When the data is processed a familiar to you already code to print the memory usage follows. @@ -3311,13 +3320,13 @@ </td> <td> - <pre> Version Size Shared Diff Test type - -------------------------------------------------------------------- - 1 3465216 2621440 843776 install_driver - 2 3461120 2609152 851968 install_driver & connect_on_init - 3 3465216 2605056 860160 preload driver - 4 3461120 2494464 966656 nothing added - 5 3461120 2482176 978944 connect_on_init</pre> + <pre> Test type Size Shared Diff + -------------------------------------------------------------- + install_driver (2) 3465216 2621440 843776 + install_driver & connect_on_init (5) 3461120 2609152 851968 + preload driver (3) 3465216 2605056 860160 + nothing added (1) 3461120 2494464 966656 + connect_on_init (4) 3461120 2482176 978944</pre> </td> </tr> @@ -3337,13 +3346,13 @@ </td> <td> - <pre> Version Size Shared Diff Test type - -------------------------------------------------------------------- - 1 3469312 2609152 860160 install_driver - 2 3481600 2605056 876544 install_driver & connect_on_init - 3 3469312 2588672 880640 preload driver - 4 3477504 2482176 995328 nothing added - 5 3481600 2469888 1011712 connect_on_init</pre> + <pre> Test type Size Shared Diff + -------------------------------------------------------------- + install_driver (2) 3469312 2609152 860160 + install_driver & connect_on_init (5) 3481600 2605056 876544 + preload driver (3) 3469312 2588672 880640 + nothing added (1) 3477504 2482176 995328 + connect_on_init (4) 3481600 2469888 1011712</pre> </td> </tr> @@ -3357,15 +3366,15 @@ <P> But both tables show the same pattern of memory usage. We can clearly see -that the real winner is the <EM>startup.pl</EM> file's version where the MySQL driver was installed (1). Since we want to +that the real winner is the <EM>startup.pl</EM> file's version where the MySQL driver was installed (2). Since we want to have a connection ready for the first request made to the freshly spawned -child process, we generally use the second version (2) which uses somewhat -more memory, but has almost the same number of shared memory pages. The -third version only preloads the driver which results in smaller shared -memory. The last two versions having nothing initialized (4) and having -only the <CODE>connect_on_init()</CODE> method used (5). The former is a -little bit better than the latter, but both significantly worse than the -first two versions. +child process, we generally use the version (5) which uses somewhat more +memory, but has almost the same number of shared memory pages. The version +(3) only preloads the driver which results in smaller shared memory. The +last two versions having nothing initialized (1) and having only the +<CODE>connect_on_init()</CODE> method used (4). The former is a little bit +better than the latter, but both significantly worse than the first two +versions. <P> To remind you why do we look for the smallest value in the column @@ -3391,9 +3400,9 @@ Notice that the smaller the diff is, the bigger the number of processes you can have using the same amount of RAM. Therefore every 100K difference counts, when you multiply it by the number of processes. If we take the -number from the version version (1) vs. (4) and assume that we have 256M of -memory dedicated to mod_perl processes we will get the following numbers -using the formula derived from the above formula: +number from the version (2) vs. (4) and assume that we have 256M of memory +dedicated to mod_perl processes we will get the following numbers using the +formula derived from the above formula: <P> @@ -3423,7 +3432,7 @@ <td> <pre> 268435456 - 2609152 - (ver 1) N = ------------------- = 309 + (ver 2) N = ------------------- = 309 860160</pre> </td> @@ -3440,7 +3449,7 @@ <td> <pre> 268435456 - 2469888 - (ver 5) N = ------------------- = 262 + (ver 4) N = ------------------- = 262 1011712</pre> </td> @@ -4143,7 +4152,7 @@ Note that you cannot localize this setting with <CODE>local()</CODE>. If you do, it won't have the desired effect. <P> -[META: Anyone can explain why localization doesn't work?] +[META: Can anyone explain why localization doesn't work?] <P> So now the code would look like this: @@ -4318,8 +4327,8 @@ <P> The HTTP header is sent next, with the <EM>Content-type</EM> of -<EM>text/plain</EM>. The gets ready to ignore the child, to avoid zombies and the fork is -called. +<EM>text/plain</EM>. The parent process gets ready to ignore the child, to avoid zombies and +the fork is called. <P> The program gets its personality split after fork and the if conditional @@ -5566,7 +5575,7 @@ <td> <pre> 500 - MaxClients = --------- = 50 + MaxClients = --------- = 50 10</pre> </td> @@ -5591,24 +5600,11 @@ <td> <pre> Total_RAM = 500Mb Max_Process_Size = 10Mb - Shared_RAM_per_Child = 8Mb</pre> - </td> - - </tr> - </table> - <P> - - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> 500 - 8 - MaxClients = --------- = 246 - 10 - 8</pre> + Shared_RAM_per_Child = 8Mb + + 500 - 8 + MaxClients = --------- = 246 + 10 - 8</pre> </td> </tr> @@ -5870,7 +5866,7 @@ You might want to consider enabling this option if the client's browser needs to request more than one object from your server for a single HTML page. If this is the situation the by setting -<CODE>KeepAlive</CODE> <CODE>Off</CODE> then for each page you save the HTTP connection overhead for all requests +<CODE>KeepAlive</CODE> <CODE>On</CODE> then for each page you save the HTTP connection overhead for all requests but the first one. <P> @@ -7718,6 +7714,48 @@ </tr> </table> <P> +Imported symbols act just like global variables, they can add up quick: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> % perlbloat.pl 'use POSIX ()' + use POSIX () added 316k</pre> + </td> + + </tr> + </table> + <P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> % perlbloat.pl 'use POSIX' + use POSIX added 696k</pre> + </td> + + </tr> + </table> + <P> +That's 380k worth of aliases. Now let's say 6 different +<CODE>Apache::Registry</CODE> scripts <CODE>'use POSIX;'</CODE> for <CODE>strftime()</CODE> or some other function: 6 * 380k = 2.3Mb + +<P> +One could save 2.3Mb per single process with <CODE>'use POSIX ();'</CODE> and using fully qualifying <CODE>POSIX::</CODE> function calls. + +<P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H2><A NAME="Object_Methods_Calls_vs_Functio">Object Methods Calls vs. Function Calls</A></H2></CENTER> @@ -8209,13 +8247,19 @@ <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> -<CENTER><H2><A NAME="Concatenation_or_List">Concatenation or List</A></H2></CENTER> +<CENTER><H2><A NAME="Interpolation_Concatenation_or_">Interpolation, Concatenation or List</A></H2></CENTER> <P> -When the strings are small, it's almost doesn't matter whether a -concatination or a list is used: +Somewhat overlapping with the previous section we want to revisit the +various approaches of mungling with strings, and compare the speed of using +lists of strings compared to interpolatoin. We will add a string +concatenation angle as well. <P> +When the strings are small, it almost doesn't matter whether interpolation +or a list is used. Here is a benchmark: +<P> + <table> <tr> @@ -8232,26 +8276,46 @@ my($one, $two, $three, $four) = ('a'..'d'); timethese(1_000_000, - { - concat => sub { - print $fh "$one$two$three$four"; - }, - list => sub { - print $fh $one, $two, $three, $four; - }, - });</pre> + { + interp => sub { + print $fh "$one$two$three$four"; + }, + list => sub { + print $fh $one, $two, $three, $four; + }, + conc => sub { + print $fh $one.$two.$three.$four; + }, + });</pre> </td> </tr> </table> <P> -Benchmark: timing 1000000 iterations of concat, list... concat: 5 wallclock -secs ( 4.76 usr + 0.00 sys = 4.76 CPU) list: 4 wallclock secs ( 4.30 usr + -0.00 sys = 4.30 CPU) -<P> -When the strings are big lists are faster: + <table> + <tr> + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> Benchmark: timing 1000000 iterations of conc, interp, list... + conc: 3 wallclock secs ( 3.38 usr + 0.00 sys = 3.38 CPU) + interp: 3 wallclock secs ( 3.45 usr + -0.01 sys = 3.44 CPU) + list: 2 wallclock secs ( 2.58 usr + 0.00 sys = 2.58 CPU)</pre> + </td> + + </tr> + </table> + <P> +The concatenation technique is very similar to interpolation. The list +technique is a little bit faster than interpolation. But when the strings +are large, lists are significantly faster. We have seen this in the +previous section and here is another benchmark to increase our confidence +in our conclusion. This time we use 1000 character long strings: + <P> <table> @@ -8270,20 +8334,48 @@ my($one, $two, $three, $four) = map { $_ x 1000 } ('a'..'d'); timethese(500_000, - { - concat => sub { - print $fh "$one$two$three$four"; - }, - list => sub { - print $fh $one, $two, $three, $four; - }, - });</pre> + { + interp => sub { + print $fh "$one$two$three$four"; + }, + list => sub { + print $fh $one, $two, $three, $four; + }, + conc => sub { + print $fh $one.$two.$three.$four; + }, + });</pre> + </td> + + </tr> + </table> + <P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + </td> + + <td> + <pre> Benchmark: timing 500000 iterations of interp, list... + conc: 5 wallclock secs ( 4.47 usr + 0.27 sys = 4.74 CPU) + interp: 4 wallclock secs ( 4.25 usr + 0.26 sys = 4.51 CPU) + list: 4 wallclock secs ( 2.87 usr + 0.16 sys = 3.03 CPU)</pre> + </td> </tr> </table> <P> +In this case using a list is about 30% faster than interpolation. +Concatenation is a little bit slower than interpolation. + +<P> +Let's look at this code: +<P> + <table> <tr> @@ -8292,24 +8384,31 @@ </td> <td> - <pre> Benchmark: timing 500000 iterations of concat, list... - concat: 10 wallclock secs ( 9.04 usr + 0.53 sys = 9.57 CPU) - list: 6 wallclock secs ( 5.72 usr + 0.56 sys = 6.28 CPU)</pre> + <pre> $title = 'My Web Page'; + print "<h1>$title</h1>"; # Interpolation (slow) + print '<h1>' . $title . '</h1>'; # Concatenation (slow) + print '<h1>', $title, '</h1>'; # List (fast for long strings)</pre> </td> </tr> </table> <P> -A list is almost 50% faster than concatenation. +When you use <EM>"<h1>$title</h1>"</EM> Perl does interpolation (since <CODE>""</CODE> is an operator in Perl), which must parse the contents of the string and +replace any variables or expressions it finds with their respective values. +This uses more memory and is slower than using a list. Of course if there +are no variables to interpolate it makes no difference whether to use <CODE>"string"</CODE> or +<CODE>'string'</CODE>. <P> -Also when you use <EM>"string"</EM> you use interpolation (since <CODE>""</CODE> is an operator in Perl), which turns into concatination, which uses more -memory and is slower than using a list. When you use <EM>'string'</EM> there is no interpolation, therefore it's faster and you have to use a list -if you need to pass more than one argument. +Concatenation is also potentially slow since Perl might create a temporary +string which it then prints. <P> -There will be exceptions, like <EM>"string\n"</EM> where you cannot use single quotes. But if you do <EM>'string',"\n"</EM> readability gets hurt. And we want want our code to be readable and -maintainable. +Lists are fast because Perl can simply deal with each element in turn. This +is true if you don't run <CODE>join()</CODE> on the list at the end to +create a single string from the elements of list. This operation might be +slower than direct append to the string whenever a new string springs into +existance. <P> [ReaderMETA]: Please send more mod_perl relevant Perl performance hints @@ -8734,7 +8833,7 @@ <td> <pre> $sth->execute; - while(@row_ary = $sth->fetchrow_array;) { + while(@row_ary = $sth->fetchrow_array) { # do DB accumulation into some variable } # print the output using the the data returned from the DB</pre> @@ -10585,6 +10684,64 @@ configure Perl with -Dusemymalloc. Perl's malloc is not much of a win under linux, but makes a <STRONG>huge</STRONG> difference under Solaris. +<P> +[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] +<HR> +<CENTER><H1><A NAME="Architecture_Specific_Compile_Op">Architecture Specific Compile Options</A></H1></CENTER> +<P> +When you build Apache and Perl you can optimize the compiled applications +to take the benefits of your machine's architecture. + +<P> +Everything depends on the kind of compiler that you use, the kind of CPU +and + +<P> +For example if you use <CODE>gcc(1)</CODE> you might want to use: + +<UL> +<P><LI> +<P> +<EM>-march=pentium</EM> if you have a pentium CPU + +<P><LI> +<P> +<EM>-march=pentiumpro</EM> for pentiumpro and above (but the binary won't run on i386) + +<P><LI> +<P> +<EM>-fomit-frame-pointer</EM> makes extra register available but disables debugging + +<P><LI> +<P> +you can try these options were reported to improve the performance: +<EM>-ffast-math</EM>, <EM>-malign-double</EM>, <EM>-funroll-all-loops</EM>, +<EM>-fno-rtti</EM>, <EM>-fno-exceptions</EM>. + +<P> +see the <CODE>gcc(1)</CODE> manpage for the details about these + +<P><LI> +<P> +and of course you may want to change the usually default <CODE>-02</CODE> flag with a higher number like <EM>-O3</EM>. <EM>-OX</EM> (where X is a number between 1 and 6) defines a collection of various +optimization flags, the higher the number the more flags are bundled. The +gcc man page will tell you what flags are used for each number. + +</UL> +<P> +Test your applications thoroughly when you change the default optimization +flags, especially when you go beyond <CODE>-02</CODE>. It's possible that the optimization will make the code work incorrectly +and/or cause segmentation faults. + +<P> +See your preferred compiler's man page for detailed information about +optimization. + +<P> +Also see: <A +HREF="http://members.nbci.com/Alex_Maranda/gnuintel/GNUintel.htm">http://members.nbci.com/Alex_Maranda/gnuintel/GNUintel.htm</A> + + [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> @@ -10638,7 +10795,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 01/11/2001 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 04/28/2001 </font></b> <br> 1.18 +10 -14 modperl-site/guide/perl.html Index: perl.html =================================================================== RCS file: /home/cvs/modperl-site/guide/perl.html,v retrieving revision 1.17 retrieving revision 1.18 diff -u -r1.17 -r1.18 --- perl.html 2001/01/11 13:48:21 1.17 +++ perl.html 2001/04/27 16:57:20 1.18 @@ -162,11 +162,6 @@ frequent pure Perl questions being asked at the list. <P> -Update: I'm moving most of the pure Perl related topics from everywhere in -the Guide to this chapter. From now on other chapters will refer to -sections in this chapter if required. - -<P> Before you decide to skip this chapter make sure you know all the information provided here. The rest of the Guide assumes that you have read this chapter and understood it. @@ -182,13 +177,15 @@ fingertips is a great time saver. It always has the up-to-date information for the version of perl you're using. +<P> +Of course you can use online Perl documentation at the Web. The two major +sites are <A HREF="http://www.perldoc.com">http://www.perldoc.com</A> and +<A +HREF="http://theoryx5.uwinnipeg.ca/CPAN/perl/.">http://theoryx5.uwinnipeg.ca/CPAN/perl/.</A> + + <P> -Of course you can use online Perl documentation at the Web. I prefer <A -HREF="http://theoryx5.uwinnipeg.ca/CPAN/perl/">http://theoryx5.uwinnipeg.ca/CPAN/perl/</A> -to the official URL: <A -HREF="http://www.perl.com/pub/v/documentation">http://www.perl.com/pub/v/documentation</A> -is very slow :( . The -<CODE>perldoc</CODE> utility provides you with access to the documentation installed on your +The <CODE>perldoc</CODE> utility provides you with access to the documentation installed on your system. To find out what Perl manpages are available execute: <P> @@ -1832,8 +1829,7 @@ </tr> </table> <P> -The approach given above is generally not recommended because most Perl -programmers will not expect <CODE>$counter</CODE> to be changed by the function; the example where we used <CODE>\$counter</CODE>, i.e. pass-by-reference would be preferred. +The approach given above should be properly documented of course. <P> Here is a solution that avoids the problem entirely by splitting the code @@ -4690,7 +4686,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 11/26/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 04/10/2001 </font></b> <br> 1.33 +62 -14 modperl-site/guide/porting.html Index: porting.html =================================================================== RCS file: /home/cvs/modperl-site/guide/porting.html,v retrieving revision 1.32 retrieving revision 1.33 diff -u -r1.32 -r1.33 --- porting.html 2001/01/11 13:48:21 1.32 +++ porting.html 2001/04/27 16:57:20 1.33 @@ -415,11 +415,30 @@ Firstly, the file <EM>/tmp/db.out</EM> was written, with a complete trace of the code that was executed. <P> -Secondly, <EM>error_log</EM> now contains the real code that was actually executed. This is produced as -a side effect of reporting the -<EM>Variable "$counter" will not stay shared at...</EM> warning that we saw earlier. +Secondly, if you have loaded the <CODE>Carp</CODE> module already, <EM>error_log</EM> +now contains the real code that was actually executed. This is produced as +a side effect of reporting the <EM>Variable "$counter" will +not stay shared at...</EM> warning that we saw earlier. To load the Carp module, you can add: <P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> use Carp;</pre> + </td> + + </tr> + </table> + <P> +in your <EM>startup.pl</EM> file or in the executed code. + +<P> Here is the code that was actually executed: <P> @@ -484,11 +503,10 @@ doesn't occur. <P> -For example if we move wrap the code from the script into the subroutine <EM>thecode</EM>, place the both subroutines into the the -<EM>mylib.pl</EM> file, save it in the same directory as the script itself and +For example if we move the code from the script into the subroutine +<EM>run</EM>, place the subroutines into the <EM>mylib.pl</EM> file, save it in the same directory as the script itself and <CODE>require()</CODE> it, there will be no problem at all. (Don't forget -the -<CODE>1;</CODE> at the end of the library or the <CODE>require()</CODE> might fail.) +the <CODE>1;</CODE> at the end of the library or the <CODE>require()</CODE> might fail.) <P> @@ -1337,8 +1355,7 @@ <HR> <CENTER><H3><A NAME="Availability">Availability</A></H3></CENTER> <P> -This module is available from <A HREF="././download.html#CPAN_Downloads">CPAN</A>. In one of the next mod_perl releases, it should become a part of the CORE -distribution. +This module is available from <A HREF="././download.html#CPAN_Downloads">CPAN</A>. <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] @@ -4219,8 +4236,8 @@ pass them to <CODE>$r->send_http_header</CODE>. This happens in <CODE>src/modules/perl/Apache.xs</CODE> (<CODE>print</CODE>) and <CODE>Apache/Apache.pm</CODE> (<CODE>send_cgi_header</CODE>). There is a shortcut in there, namely the assumption that each print statement contains one or more complete headers. If for example you -generate a -<CODE>Set-Cookie</CODE> header by multiple <CODE>print()</CODE> statements, like this: +generate a <CODE>Set-Cookie</CODE> +header by multiple <CODE>print()</CODE> statements, like this: <P> @@ -4586,6 +4603,32 @@ The last paragraph is very important for handling the case of <A HREF="././debug.html#Handling_the_User_pressed_Stop_">'User Pressed the Stop Button'</A>. <P> +If you only want something to run once in the parent on shutdown or restart +you can use <CODE>$r->register_cleanup()</CODE> in the <EM>startup.pl</EM>. + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> #PerlRequire startup.pl + warn "parent pid is $$\n"; + Apache->server->register_cleanup + (sub { warn "server cleanup in $$\n"});</pre> + </td> + + </tr> + </table> + <P> +This is usually useful when some server wide cleanup should be performed +when the server is stopped or restarted. + +<P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H1><A NAME="CHECK_Blocks">CHECK Blocks</A></H1></CENTER> @@ -5013,7 +5056,7 @@ </td> <td> - <pre> local $^T=time;</pre> + <pre> local $^T = time;</pre> </td> </tr> @@ -5062,6 +5105,11 @@ </tr> </table> <P> +This technique is better performance-wise as it skips the +<CODE>time()</CODE> system call, and uses the already available time of the +request has been started at via <CODE>$r->request_time</CODE> method. + +<P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H1><A NAME="Apache_and_syslog">Apache and syslog</A></H1></CENTER> @@ -5654,7 +5702,7 @@ Now we are going to modify the script itself. We copy the content to the file <EM>Cookie.pm</EM> and place it into one of the directories listed in <CODE>@INC</CODE>. For example if <EM>/home/httpd/perl</EM> is a part of <CODE>@INC</CODE> and since we want to call this package <CODE>Test::Cookie</CODE>, we can put -<EM>/Cookie.pm</EM> into the <EM>/home/httpd/perl/Test/</EM> directory. +<EM>Cookie.pm</EM> into the <EM>/home/httpd/perl/Test/</EM> directory. <P> So this is the new code. Notice that all the subroutines were left @@ -6313,7 +6361,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 12/15/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 04/17/2001 </font></b> <br> 1.31 +4 -57 modperl-site/guide/scenario.html Index: scenario.html =================================================================== RCS file: /home/cvs/modperl-site/guide/scenario.html,v retrieving revision 1.30 retrieving revision 1.31 diff -u -r1.30 -r1.31 --- scenario.html 2001/01/11 13:48:22 1.30 +++ scenario.html 2001/04/27 16:57:20 1.31 @@ -2260,64 +2260,11 @@ <CENTER><H3><A NAME="Security_Issues">Security Issues</A></H3></CENTER> <P> Whenever you use mod_proxy you need to make sure that your server will not -become a proxy for free riders. To block this you should have this setting: +become a proxy for free riders. Allowing clients to issue proxy requests is +controlled by the <CODE>ProxyRequests</CODE> directive. Its default setting is <CODE>off</CODE>, which means proxy requests are handled only if generated internally (by <CODE>ProxyPass</CODE> or <CODE>RewriteRule...[P]</CODE> +directives.) Do not use the <CODE>ProxyRequests</CODE> directive on your reverse proxy servers. <P> - - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> RewriteRule ^proxy:.* - [F]</pre> - </td> - - </tr> - </table> - <P> -which makes sure that requests of type proxy:http://www.example.com -wouldn't keep your processes busy and will return the status <EM>Forbidden</EM>. - -<P> -Start by testing your own server, by telnetting to the port the server is -listening on and issuing an external proxy request: - -<P> - - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> % telnet www.example.com 80 -Trying 128.9.176.32... -Connected to www.example.com -Escape character is '^]'. -HEAD <A HREF="http://www.example.org/">http://www.example.org/</A> HTTP/1.1 -Host: www.example.org</pre> - </td> - - </tr> - </table> - <P> -HTTP/1.0 403 Forbidden Date: Mon, 10 Apr 2000 08:42:31 GMT Server: -Apache/1.3.13-dev (Unix) Connection: close Content-Type: text/html; -charset=iso-8859-1 - -<P> -Connection closed by foreign host. - -<P> -As you can see we are not allowed to make a proxy request to a different -server, so our <EM>lock down</EM> has worked. It means that this particular hole has been secured on our box. - -<P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H2><A NAME="Buffering_Feature">Buffering Feature</A></H2></CENTER> @@ -3396,7 +3343,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 12/25/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 03/11/2001 </font></b> <br> 1.29 +317 -308 modperl-site/guide/snippets.html Index: snippets.html =================================================================== RCS file: /home/cvs/modperl-site/guide/snippets.html,v retrieving revision 1.28 retrieving revision 1.29 diff -u -r1.28 -r1.29 --- snippets.html 2001/01/11 13:48:23 1.28 +++ snippets.html 2001/04/27 16:57:21 1.29 @@ -35,12 +35,8 @@ <UL> <LI><A HREF="#Redirecting_Errors_to_the_Client">Redirecting Errors to the Client Instead of error_log</A> - <LI><A HREF="#Emulating_the_Authentication_Mec">Emulating the Authentication Mechanism</A> - <LI><A HREF="#Caching_POSTed_Data">Caching POSTed Data</A> - <LI><A HREF="#Cache_Control_for_Regular_and_Er">Cache Control for Regular and Error Modes</A> - <LI><A HREF="#Convert_a_POST_Request_into_a_GE">Convert a POST Request into a GET Request</A> - <LI><A HREF="#Redirect_a_POST_Request_Forward">Redirect a POST Request, Forwarding the Content</A> - <LI><A HREF="#Reading_POST_Data_then_Redirect">Reading POST Data, then Redirecting or Doing Something Else</A> + <LI><A HREF="#Reusing_Data_from_POST_request">Reusing Data from POST request</A> + <LI><A HREF="#Redirecting_POST_Requests">Redirecting POST Requests</A> <LI><A HREF="#Redirecting_While_Maintaining_En">Redirecting While Maintaining Environment Variables</A> <LI><A HREF="#Terminating_a_Child_Process_on_R">Terminating a Child Process on Request Completion</A> <LI><A HREF="#More_on_Relative_Paths">More on Relative Paths</A> @@ -56,12 +52,13 @@ <LI><A HREF="#Subclassing_Apache_Request">Subclassing Apache::Request</A> <LI><A HREF="#Sending_Email_from_mod_perl">Sending Email from mod_perl</A> <LI><A HREF="#A_Simple_Handler_To_Print_The_En">A Simple Handler To Print The Environment Variables</A> - <LI><A HREF="#mod_rewrite_Based_On_Query_Strin">mod_rewrite Based On Query String and URI Implemented in Perl</A> - <LI><A HREF="#PerlTransHandler_example">PerlTransHandler example</A> + <LI><A HREF="#mod_rewrite_in_Perl">mod_rewrite in Perl</A> + <LI><A HREF="#URI_Rewrite_in_PerlTransHandler">URI Rewrite in PerlTransHandler </A> <LI><A HREF="#Setting_PerlHandler_Based_on_MIM">Setting PerlHandler Based on MIME Type</A> <LI><A HREF="#SSI_and_Embperl_Doing_Both">SSI and Embperl - Doing Both</A> <LI><A HREF="#Getting_the_Front_end_Server_s_N">Getting the Front-end Server's Name in the Back-end Server</A> <LI><A HREF="#Authentication_Snippets">Authentication Snippets</A> + <LI><A HREF="#Emulating_the_Authentication_Mec">Emulating the Authentication Mechanism</A> <LI><A HREF="#An_example_of_using_Apache_Sess">An example of using Apache::Session::DBI with cookies</A> <LI><A HREF="#Using_DESTROY_to_Finalize_Output">Using DESTROY to Finalize Output</A> <LI><A HREF="#Setting_Environment_Variables_Fo">Setting Environment Variables For Scripts Called From CGI.</A> @@ -302,9 +299,22 @@ Have you pressed a 'STOP' button?<BR> Please try again!<P> Thank you! - }; - - } else { + };</pre> + </td> + + </tr> + </table> + <P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> } else { $message = qq{ <B>You need take no action since @@ -335,10 +345,23 @@ An error has happened: $orig_why - - |; - # send error reports to admin + |;</pre> + </td> + + </tr> + </table> + <P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> # send error reports to admin send_mail($admin_email,$admin_email,$subject,$body); print STDERR "[".scalar localtime()."] [SIGDIE] Sending Error Email\n"; } @@ -366,53 +389,24 @@ <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> -<CENTER><H1><A NAME="Emulating_the_Authentication_Mec">Emulating the Authentication Mechanism</A></H1></CENTER> -<P> -You can provide your own mechanism to authenticate users, instead of the -standard one. If you want to make Apache think that the user was -authenticated by the standard mechanism, set the username with: - +<CENTER><H1><A NAME="Reusing_Data_from_POST_request">Reusing Data from POST request</A></H1></CENTER> <P> - - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> $r->connection->user('username');</pre> - </td> - - </tr> - </table> - <P> -Now you can use this information for example during the logging, so that -you can have your ``username'' passed as if it was transmitted to Apache -through HTTP authentication. - -<P> -[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] -<HR> -<CENTER><H1><A NAME="Caching_POSTed_Data">Caching POSTed Data</A></H1></CENTER> -<P> What happens if you need to access the POSTed data more than once, say to reuse it on subsequent requests? POSTed data comes directly from the socket, and at the low level data can only be read from a socket once. So you have to store it to make it available for reuse. <P> -There is an experimental option for <CODE>Makefile.PL</CODE> called -<CODE>PERL_STASH_POST_DATA</CODE>. If you turn it on, you can get at it again with <CODE>$r->subprocess_env("POST_DATA")</CODE>. This is not on by default because it adds overhead. +There is an experimental option for <CODE>Makefile.PL</CODE> called +<CODE>PERL_STASH_POST_DATA</CODE>. If you turn it on, you can get at it again with <CODE>$r->subprocess_env("POST_DATA")</CODE>. This is not <EM>enabled</EM> +by default because it adds a processing overhead for each POST request. <P> -And what do we do with large multipart file uploads? Because <CODE>POST</CODE> +But what do we do with large multipart file uploads? Because <CODE>POST</CODE> data is not all read in one clump, it's a problem that's not easy to solve -in a general way. You might try the following approach: - -<P> -In httpd.conf: +in a general way. A transparent way to do this is to switch the request +method from POST to GET, and store the POST data in the query string. This +handler does exactly this: <P> @@ -424,51 +418,30 @@ </td> <td> - <pre> <Limit POST> - PerlFixupHandler My::fixup_handler - </Limit></pre> - </td> - - </tr> - </table> - <P> -In your script: - -<P> - - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> use Apache::Constants; - sub My::fixup_handler { + <pre> Apache/POST2GET.pm + ------------------ + package Apache::POST2GET; + use Apache::Constants qw(M_GET OK DECLINED); + + sub handler { my $r = shift; return DECLINED unless $r->method eq "POST"; $r->args(scalar $r->content); - $r->method("GET"); + $r->method('GET'); $r->method_number(M_GET); $r->headers_in->unset('Content-length'); - OK; - }</pre> + return OK; + } + 1; + __END__</pre> </td> </tr> </table> <P> -Now when <CODE>CGI.pm</CODE>, <CODE>Apache::Request</CODE> or whatever parses the client data, it can do so more than once since <CODE>$r->args</CODE> doesn't go away (unless you make it go away). +In <EM>httpd.conf</EM> add: <P> -[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] -<HR> -<CENTER><H1><A NAME="Cache_Control_for_Regular_and_Er">Cache Control for Regular and Error Modes</A></H1></CENTER> -<P> -To disable caching you should use the headers: - -<P> <table> <tr> @@ -478,14 +451,13 @@ </td> <td> - <pre> Pragma: no-cache - Cache-control: no-cache</pre> + <pre> PerlInitHandler Apache::POST2GET</pre> </td> </tr> </table> <P> -For normally generated response use: +or even this: <P> @@ -497,45 +469,31 @@ </td> <td> - <pre> $r->header_out("Pragma","no-cache"); - $r->header_out("Cache-control","no-cache"); - $r->no_cache(1);</pre> + <pre> <Limit POST> + PerlInitHandler Apache::POST2GET + </Limit></pre> </td> </tr> </table> <P> -If for some reason you need to use them in Error control code use: +To save a few more cycles, so the handler will be called only for POST +requests. <P> +Effectively, this trick turns the POST request into a GET request +internally. Now when <CODE>CGI.pm</CODE>, <CODE>Apache::Request</CODE> or whatever module parses the client data, it can do so more than once +since +<CODE>$r->args</CODE> doesn't go away (unless you make it go away by resetting it). - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> $r->err_header_out("Pragma","no-cache"); - $r->err_header_out("Cache-control","no-cache");</pre> - </td> - - </tr> - </table> - <P> -META: $r->no_cache(1); ? - <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> -<CENTER><H1><A NAME="Convert_a_POST_Request_into_a_GE">Convert a POST Request into a GET Request</A></H1></CENTER> -<P> -Remember that <STRONG>you can only read POST data from the socket once</STRONG>. If you need to use it more than once, you need to save it somewhere. - +<CENTER><H1><A NAME="Redirecting_POST_Requests">Redirecting POST Requests</A></H1></CENTER> <P> -A transparent way to do this is to switch the request method from POST to -GET, and store the POST data in the query string: +Under mod_cgi it's not easy to redirect POST requests to some other +location. With mod_perl you can easily redirect POST requests. All you have +to do is read in the content, set the method to <CODE>GET</CODE>, populate <CODE>args()</CODE> with the content to be forwarded and finally do the redirect: <P> @@ -547,61 +505,8 @@ </td> <td> - <pre> package Apache::POST2GET; - use Apache::Constants qw(M_GET); - - sub handler { - my $r = shift; - if ($r->method eq 'POST') { - my $content = $r->content; - $r->args($content); - $r->method('GET'); - $r->method_number(M_GET); - $r->headers_in->unset('Content-length'); - } - } - __END__</pre> - </td> - - </tr> - </table> - <P> -Then add this directive to <EM>httpd.conf</EM>: - -<P> - - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> PerlInitHandler Apache::POST2GET</pre> - </td> - - </tr> - </table> - <P> -[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] -<HR> -<CENTER><H1><A NAME="Redirect_a_POST_Request_Forward">Redirect a POST Request, Forwarding the Content</A></H1></CENTER> -<P> -With mod_perl you can easily redirect a POST request to some other -location. All you have to do is read in the contents, set the method to <CODE>GET</CODE>, populate <CODE>args()</CODE> with the content to be forwarded and finally do the redirect: - -<P> - - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> my $r = shift; + <pre> use Apache::Constants qw(M_GET); + my $r = shift; my $content = $r->content; $r->method("GET"); $r->method_number(M_GET); @@ -618,38 +523,6 @@ <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> -<CENTER><H1><A NAME="Reading_POST_Data_then_Redirect">Reading POST Data, then Redirecting or Doing Something Else</A></H1></CENTER> -<P> -If you read POST data, then redirect, you need to do this before the -redirect or apache will hang: - -<P> - - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> $r->method_number(M_GET); - $r->method('GET'); - $r->headers_in->unset('Content-length'); - $r->header_out('Location' => $ENV{SCRIPT_NAME}); - $r->status(REDIRECT); - $r->send_http_header;</pre> - </td> - - </tr> - </table> - <P> -After the first time you read POST data, you need the code above to prevent -somebody else from trying to read post data that's already been read. - -<P> -[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] -<HR> <CENTER><H1><A NAME="Redirecting_While_Maintaining_En">Redirecting While Maintaining Environment Variables</A></H1></CENTER> <P> Let's say you have a module that sets some environment variables. @@ -660,9 +533,9 @@ are preserved. <P> -However, if you're using <CODE>internal_redirect(),</CODE> then -<CODE>subprocess_env()</CODE> should do the trick, but the <CODE>%ENV</CODE> keys will be prefixed with -<CODE>REDIRECT_</CODE>. +However, if you're using <CODE>internal_redirect(),</CODE> you can make the +environment variables seen in the sub-process via +<CODE>subprocess_env().</CODE> The only nuance is that the <CODE>%ENV</CODE> keys will be prefixed with <CODE>REDIRECT_</CODE>. <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] @@ -917,7 +790,8 @@ <HR> <CENTER><H1><A NAME="Handling_Cookies">Handling Cookies</A></H1></CENTER> <P> -Unless you use some well known module like <CODE>CGI.pm</CODE>, handle cookies yourself. +Unless you use some well known module like <CODE>CGI::Cookie</CODE> or +<CODE>Apache::Cookie</CODE>, you need to handle cookies yourself. <P> Cookies come in the <CODE>$ENV{HTTP_COOKIE}</CODE> variable. You can print the raw cookie string as <CODE>$ENV{HTTP_COOKIE}</CODE>. @@ -979,7 +853,7 @@ <HR> <CENTER><H1><A NAME="Sending_Multiple_Cookies_with_th">Sending Multiple Cookies with the Perl API</A></H1></CENTER> <P> -Given that you have prepared your cookies in <CODE>@cookies</CODE>, the following would do: +Given that you have prepared your cookies in <CODE>@cookies</CODE>, the following code will submit all the cookies: <P> @@ -991,9 +865,9 @@ </td> <td> - <pre> for(@cookies){ + <pre> for (@cookies){ $r->headers_out->add( 'Set-Cookie' => $_ ); - }</pre> + }</pre> </td> </tr> @@ -1016,7 +890,9 @@ </td> <td> - <pre> my $r = shift; + <pre> use Apache::Constants qw(REDIRECT OK); + my $r = shift; + # prepare the cookie in $cookie $r->err_headers_out->add('Set-Cookie' => $cookie); $r->headers_out(Location => $location); $r->status(REDIRECT); @@ -1033,8 +909,7 @@ <P> Let's say that you wrote a few handlers to process a request, and they all need to share some custom Perl data structure. The <CODE>pnotes()</CODE> -method comes to your rescue. Given that one of the handlers stored some -data in a hash <CODE>%my_data</CODE>, then before it terminates: +method comes to your rescue. <P> @@ -1046,15 +921,17 @@ </td> <td> - <pre> # First handler: - my %my_data = (foo => 1, bar => 2); + <pre> # a handler that gets executed first + my %my_data = (foo => 'mod_perl', bar => 'rules'); $r->pnotes('my_data' => \%my_data);</pre> </td> </tr> </table> <P> -All the subsequent handlers will be able to retrieve the stored data with: +The handler prepares the data in hash <CODE>%my_data</CODE> and calls <CODE>pnotes()</CODE> method to store the data internally for +other handlers to re-use. All the subsequently called handlers can retrieve +the stored data in this way: <P> @@ -1066,30 +943,41 @@ </td> <td> - <pre> # Later handler: - my $info = $r->pnotes('my_data'); + <pre> my $info = $r->pnotes('my_data'); print $info->{foo};</pre> </td> </tr> </table> <P> +prints: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> mod_perl</pre> + </td> + + </tr> + </table> + <P> The stored information will be destroyed at the end of the request. <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H1><A NAME="Passing_Notes_Between_mod_perl_a">Passing Notes Between mod_perl and other (non-Perl) Apache Modules</A></H1></CENTER> -<P> -the <CODE>notes()</CODE> method can be used to make various Apache modules -talk to each other. In this snippet the php application calls the mod_perl -application by marking up a bunch of notes in its own request and then -issuing a sub-request to a mod_perl page. The mod_perl request handler that -gets this internal sub-request reads those notes and writes its replies in -the same place. - <P> -First you read the request with (the following code is in PHP): +The <CODE>notes()</CODE> method can be used to make various Apache modules +talk to each other. In the following snippet the PHP module talks to the +mod_perl code (PHP code): <P> @@ -1102,12 +990,11 @@ <td> <pre> if (isset($user) && substr($user,0,1) == "+") { - apache_note("imp_euser", substr($user,1)); + apache_note("user", substr($user,1)); virtual("/internal/getquota"); - $quota = apache_note("imp_quota"); - $quota_pp = apache_note("imp_quota_pp"); - $usage_pp = apache_note("imp_usage_pp"); - $percent_pp = apache_note("imp_percent_pp"); + $quota = apache_note("quota"); + $usage_pp = apache_note("usage_pp"); + $percent_pp = apache_note("percent_pp"); if ($quota) $message .= " | Using $percent_pp% of $quota_pp limit"; }</pre> @@ -1116,15 +1003,93 @@ </tr> </table> <P> -and then you read and write the notes with <CODE>$r->main->notes</CODE> -from mod_perl. +The PHP code sets the <EM>user</EM> and the username pair using the notes mechanism. Then issuing a sub-request +to a perl handler: <P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> use Apache::Constants qw(REDIRECT OK); + my $r = shift; + my $notes = $r->main->notes(); + my ($quota,usage_pp,percent_pp) = getquota($notes->{user}||''); + $r->notes('quota',$quota); + $r->notes('usage_pp',$usage_pp); + $r->notes('percent_pp',$percent_pp); + return OK;</pre> + </td> + + </tr> + </table> + <P> +which retrieves the username from the notes (using +<CODE>$r->main->notes</CODE>), uses some <CODE>getquota()</CODE> function to get the quota related data +and then sets the acquired data in the notes for the PHP code. Now the PHP +code reads the data from the notes and proceeds with setting <CODE>$message</CODE> if <CODE>$quota</CODE> is set. + +<P> +So any Apache modules can communicate with each other over the Apache +<CODE>notes()</CODE> mechanism. + +<P> +You can use notes along with the sub-request methods +<CODE>lookup_uri()</CODE> and <CODE>lookup_filename()</CODE> too. To make +it work, you need to set a note in the sub-request. For example if you want +to call a php sub-request from within mod_perl and pass it a note, you can +do it in the following way: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> my $subr = $r->lookup_uri('wizard.php3'); + $subr->notes('answer' => 42); + $subr->run;</pre> + </td> + + </tr> + </table> + <P> +As of the time of this writing you cannot access the parent request tables +from a PHP handler, therefore you must set this note for the sub-request. +Whereas if the sub-request is running in the mod_perl domain, you can +always keep the notes in the parent request notes table and access them via +the method <CODE>main():</CODE> + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> $r->main->notes('answer');</pre> + </td> + + </tr> + </table> + <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H1><A NAME="Passing_Environment_Variables_Be">Passing Environment Variables Between Handlers</A></H1></CENTER> <P> -A simple example of passing environment variables between handlers: +This is a simple example of passing environment variables between handlers: <P> Having a configuration: @@ -1182,7 +1147,8 @@ <HR> <CENTER><H1><A NAME="CGI_params_in_the_mod_perl_ish_">CGI::params in the mod_perl-ish Way</A></H1></CENTER> <P> -Extracting request parameters in the mod_perl-ish way: +You can retrieve the request parameters in a similar to <CODE>CGI::params</CODE> +way using this technique: <P> @@ -1201,7 +1167,11 @@ </tr> </table> <P> -Also take a look at <CODE>Apache::Request</CODE> which has the same API for extracting and setting parameters. +assuming that all your variables are single key-value pairs. + +<P> +Also take a look at <CODE>Apache::Request</CODE> which has the same API as +<CODE>CGI.pm</CODE> for extracting and setting request parameters. <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] @@ -1236,7 +1206,7 @@ my ($self, $key) = @_; my $apr = $self->{_r}; # Here we are calling the Apache::Request object's param method - $apr->param($key) . '42'; + $apr->param($key); } sub sum { @@ -1262,15 +1232,15 @@ <P> There is nothing special about sending email from mod_perl, it's just that we do it a lot. There are a few important issues. The most widely used -approach is starting a <CODE>sendmail</CODE> process and piping the headers and the body to it. The problem is that -<CODE>sendmail</CODE> is a very heavy process and it makes mod_perl processes less efficient. +approach is starting a <CODE>sendmail</CODE> process and piping the headers and the body to it. The problem is that <CODE>sendmail</CODE> is a very heavy process and it makes mod_perl processes less efficient. <P> If you don't want your process to wait until delivery is complete, you can tell <CODE>sendmail</CODE> not to deliver the email straight away, but either do it in the background or just queue the job until the next queue run. This can significantly reduce the delay for the mod_perl process which would otherwise have to -wait for the <CODE>sendmail</CODE> process to complete. This can be specified for all deliveries in <EM>sendmail.cf</EM> or on each invocation on the sendmail command line: +wait for the <CODE>sendmail</CODE> process to complete. This can be specified for all deliveries in +<EM>sendmail.cf</EM> or on each invocation on the sendmail command line: <UL> <P><LI> @@ -1287,12 +1257,16 @@ </UL> <P> -Some people prefer using lighter mail delivery programs like -<CODE>qmail</CODE>. +The trend is to move away from <CODE>sendmail(1)</CODE> and switch to using +lighter mail delivery programs like <CODE>qmail(1)</CODE> or +<CODE>postfix(1).</CODE> You should check the manpage of your favorite +mailer application for equivalent configuration presented for +<CODE>sendmail(1).</CODE> <P> The most efficient approach is to talk directly to the SMTP server. Luckily <CODE>Net::SMTP</CODE> modules makes this very easy. The only problem is when <Net::SMTP> fails to deliver the mail, because the destination peer -server is temporarily down. But from the other side <CODE>Net::SMTP</CODE> allows you to send email much much faster, since you don't have to invoke a +server is temporarily down. But from the other side <CODE>Net::SMTP</CODE> +allows you to send email much much faster, since you don't have to invoke a dedicated process. Here is an example of a subroutine that sends email. <P> @@ -1439,14 +1413,12 @@ <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> -<CENTER><H1><A NAME="mod_rewrite_Based_On_Query_Strin">mod_rewrite Based On Query String and URI Implemented in Perl</A></H1></CENTER> -<P> -The task: we need to perform a redirect based on the query string and the -logical path (URI). - +<CENTER><H1><A NAME="mod_rewrite_in_Perl">mod_rewrite in Perl</A></H1></CENTER> <P> -The solution: we write a PerlTransHandler that does what mod_rewrite does. -You can get the query string from <CODE>$r->args</CODE> and send redirect headers. +We can easily implement everything mod_rewrite does in Perl. We do this +with help of PerlTransHandler, which is invoked at the beginning of request +processing. For example consider that we need to perform a redirect based +on query string and URI, the following handler does that. <P> @@ -1458,20 +1430,18 @@ </td> <td> - <pre> package Apache::Redirect::Based::On::Query::String::Plus::URI; - use Apache::Constants 'OK','REDIRECT'; - use constant DEFAULT_URI => '<A HREF="http://www.boston.com">http://www.boston.com</A>'; # shameless plug! + <pre> package Apache::MyRedirect; + use Apache::Constants qw(OK REDIRECT); + use constant DEFAULT_URI => '<A HREF="http://www.example.org">http://www.example.org</A>'; sub handler { my $r = shift; my %args = $r->args; my $path = $r->uri; - # $uri holds something like '<A HREF="http://www.mysite.com/news/">http://www.mysite.com/news/</A>' if the initial - # request was '<A HREF="http://www.yoursite.com/news/?uri=http://www.mysite.com/">http://www.yoursite.com/news/?uri=http://www.mysite.com/</A>' my $uri = (($args{'uri'}) ? $args{'uri'} : DEFAULT_URI) . $path; - $r->header_out->add('Location' => $uri); + $r->header_out(Location => $uri); $r->status(REDIRECT); $r->send_http_header; @@ -1493,18 +1463,44 @@ </td> + <td> + <pre> PerlTransHandler Apache::MyRedirect</pre> + </td> + + </tr> + </table> + <P> +The code consists of three parts: request data retrieval, deciding what to +do based on this data and finally setting the headers and the status and +issuing redirect. + +<P> +So if a client submits a request of this kind: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + <td> - <pre> PerlTransHandler Apache::Redirect::Based::On::Query::String::Plus::URI</pre> + <pre> <A HREF="http://www.example.com/news/?uri=http://www.example-2.com/">http://www.example.com/news/?uri=http://www.example-2.com/</A></pre> </td> </tr> </table> <P> +<CODE>$uri</CODE> will hold <EM>http://www.example-2.com/news/</EM> and that's where the request will be redirected. + +<P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> -<CENTER><H1><A NAME="PerlTransHandler_example">PerlTransHandler example</A></H1></CENTER> +<CENTER><H1><A NAME="URI_Rewrite_in_PerlTransHandler">URI Rewrite in PerlTransHandler</A></H1></CENTER> <P> -Suppose that before a content handler is invoked you want make this +Suppose that before a content handler is invoked you want to make this translation: <P> @@ -1572,26 +1568,26 @@ </tr> </table> <P> -Notice the technique to set the <EM>args</EM>. By the time the apache-request object has been created, args are handled -in a separate slot, so you cannot just push them into the original URI. +The handler code retrieves the request object and the URI. Then it +retrieves the <EM>id</EM> using the regular expression. Finally it sets the new value of the URI and +the arguments string. The handler returns +<CODE>DECLINED</CODE> so the default Apache transhandler will take care of URI to filename +remapping. <P> -Also notice that the handler returns <CODE>DECLINED</CODE> so the default Apache transhandler will take care of URI to filename -remapping. +Notice the technique to set the arguments. By the time the Apache-request +object has been created, arguments are handled in a separate slot, so you +cannot just push them into the original URI. Therefore the +<CODE>args()</CODE> method should be used. <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H1><A NAME="Setting_PerlHandler_Based_on_MIM">Setting PerlHandler Based on MIME Type</A></H1></CENTER> -<P> -Q: Is there a way to set a PerlHandler for a specific MIME type? Something -like <EM>"PerlTypeHandler text/html HTML::Template"</EM>? (One can use a <CODE><Files></CODE> section. Not quite as slick, and that mucks up -<CODE>$r->location</CODE>.) - <P> -A: There's no built-in configuration directive like that, though you could -do magic with directive handlers. Otherwise, something like this should -work: +It's very easy to implement a dispatching module based on the MIME type of +request. So a different content handler will be called for a different MIME +type. This is an example of such a dispatcher: <P> @@ -1603,52 +1599,30 @@ </td> <td> - <pre> package My::MimeTypeDispatch;</pre> - </td> - - </tr> - </table> - <P> - - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> my %mime_types = ( - 'text/html' => \&HTML::Template::handler, - );</pre> - </td> - - </tr> - </table> - <P> - - <table> - <tr> - - <td bgcolor="#eeeeee" width="1"> - - </td> - - <td> - <pre> sub handler { + <pre> package My::MimeTypeDispatch; + use Apache::Constants qw(DECLINED); + + my %mime_types = ( + 'text/html' => \&HTML::Template::handler, + 'text/plain' => \&My::Text::handler, + ); + + sub handler { my $r = shift; if (my $h = $mime_types{$r->content_type}) { $r->push_handlers(PerlHandler => $h); $r->handler('perl-script'); } + return DECLINED; } + 1; __END__</pre> </td> </tr> </table> <P> -And in <EM>httpd.conf</EM>: +And in <EM>httpd.conf</EM> we add: <P> @@ -1666,6 +1640,13 @@ </tr> </table> <P> +After declaring the package name and importing constants, we set a +translation table of MIME types and corresponding handlers to be called. +Then comes the handler, where the request object is retrieved and if its +MIME type is found in our translation table we set the handler that should +handle this request. Otherwise we do nothing. At the end we return <CODE>DECLINED</CODE> so some other fixup handler could take over. + +<P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H1><A NAME="SSI_and_Embperl_Doing_Both">SSI and Embperl -- Doing Both</A></H1></CENTER> @@ -1762,7 +1743,7 @@ <P> Compile apache with both mod_proxy and mod_rewrite, then use a directive -something like this +something like this: <P> @@ -1794,8 +1775,7 @@ <HR> <CENTER><H1><A NAME="Authentication_Snippets">Authentication Snippets</A></H1></CENTER> <P> -Getting the authenticated username: <CODE>$r->connection->user()</CODE>, or -<CODE>$ENV{REMOTE_USER}</CODE> if you're in a CGI emulation. +Getting the authenticated username: <CODE>$r->connection->user()</CODE>, or <CODE>$ENV{REMOTE_USER}</CODE> if you're in a CGI emulation. <P> Example: @@ -1823,6 +1803,35 @@ <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> +<CENTER><H1><A NAME="Emulating_the_Authentication_Mec">Emulating the Authentication Mechanism</A></H1></CENTER> +<P> +You can provide your own mechanism to authenticate users, instead of the +standard one. If you want to make Apache think that the user was +authenticated by the standard mechanism, set the username with: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> $r->connection->user('username');</pre> + </td> + + </tr> + </table> + <P> +Now you can use this information for example during the logging, so that +you can have your ``username'' passed as if it was transmitted to Apache +through HTTP authentication. + +<P> +[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] +<HR> <CENTER><H1><A NAME="An_example_of_using_Apache_Sess">An example of using Apache::Session::DBI with cookies</A></H1></CENTER> <P> META: should be annotated at some point. (an example was posted to the @@ -2329,7 +2338,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 12/13/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 03/21/2001 </font></b> <br> 1.26 +1 -1 modperl-site/guide/start.html Index: start.html =================================================================== RCS file: /home/cvs/modperl-site/guide/start.html,v retrieving revision 1.25 retrieving revision 1.26 diff -u -r1.25 -r1.26 --- start.html 2001/01/11 13:48:23 1.25 +++ start.html 2001/04/27 16:57:21 1.26 @@ -257,7 +257,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/19/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 06/20/2000 </font></b> <br> 1.19 +13 -13 modperl-site/guide/strategy.html Index: strategy.html =================================================================== RCS file: /home/cvs/modperl-site/guide/strategy.html,v retrieving revision 1.18 retrieving revision 1.19 diff -u -r1.18 -r1.19 --- strategy.html 2001/01/11 13:48:23 1.18 +++ strategy.html 2001/04/27 16:57:21 1.19 @@ -452,10 +452,6 @@ does not spawn child processes. <P> -Meta: Hey, No personal experience here, only rumours. Please let me know if -I have missed some pros/cons here. Thanks! - -<P> The Advantages: <UL> @@ -502,6 +498,10 @@ HREF="http://www.fenrus.demon.nl/.">http://www.fenrus.demon.nl/.</A> <P> +Also check out the Boa webserver: <A +HREF="http://www.boa.org/">http://www.boa.org/</A> + +<P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> <CENTER><H1><A NAME="Adding_a_Proxy_Server_in_http_Ac">Adding a Proxy Server in http Accelerator Mode</A></H1></CENTER> @@ -544,7 +544,7 @@ <P><LI> <P> And the extra functionality provided by the http-acceleration mode, which -make the proxy server act as a sort of output buffer for the dynamic +makes the proxy server act as a sort of output buffer for the dynamic content. The mod_perl server sends the entire response to the proxy and is then free to deal with other requests. The proxy server is responsible for sending the response to the browser. So if the transfer is over a slow @@ -557,17 +557,17 @@ <P> First let's explain the abbreviation used in the networking world. If someone claims to have a 56 kbps connection -- it means that the connection -is of 56 killo-bits per second (~56000 bits/sec). It's not 56 killo-bytes -per second, but 7 killo-bytes per second, because 1 byte equals to 8 bits. -So don't let the merchants fool you--your modem gives you 7 killo-bytes per -second connection at most and not 56 killo-bytes per second as one might +is of 56 kilo-bits per second (~56000 bits/sec). It's not 56 kilo-bytes per +second, but 7 kilo-bytes per second, because 1 byte equals to 8 bits. So +don't let the merchants fool you--your modem gives you 7 kilo-bytes per +second connection at most and not 56 kilo-bytes per second as one might think. <P> Another convention used in computer literature is that if you see 10Kb it -usually means 10 killo-bits and 10KB is 10 killo-bytes. So if you see upper +usually means 10 kilo-bits and 10KB is 10 kilo-bytes. So if you see upper case <CODE>B</CODE> it generally refers to bytes, and lower case <CODE>b</CODE> -to bits (and <CODE>K</CODE> of course means killo and equals to 1024 or to 1000 depending on the field +to bits (and <CODE>K</CODE> of course means kilo and equals to 1024 or to 1000 depending on the field it's used in). Remember that the latter convention is not followed everywhere, so use this knowledge with care. This document is following this convention. @@ -591,7 +591,7 @@ </td> <td> - <pre> 42KB / 0.5s * 7KB/s = 12</pre> + <pre> 42KB / (0.5s * 7KB/s) = 12</pre> </td> </tr> @@ -1550,7 +1550,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 12/25/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 04/04/2001 </font></b> <br> 1.11 +56 -10 modperl-site/guide/troubleshooting.html Index: troubleshooting.html =================================================================== RCS file: /home/cvs/modperl-site/guide/troubleshooting.html,v retrieving revision 1.10 retrieving revision 1.11 diff -u -r1.10 -r1.11 --- troubleshooting.html 2001/01/11 13:48:23 1.10 +++ troubleshooting.html 2001/04/27 16:57:21 1.11 @@ -60,6 +60,7 @@ <LI><A HREF="#Runtime">Runtime</A> <UL> + <LI><A HREF="#_exit_signal_Segmentation_fault_">"exit signal Segmentation fault (11)" with mysql</A> <LI><A HREF="#foo_at_dev_null_line_0">foo ... at /dev/null line 0</A> <LI><A HREF="#Preventing_mod_perl_Processes_Fr">Preventing mod_perl Processes From Going Wild</A> <LI><A HREF="#Segfaults_when_using_XML_Parser">Segfaults when using XML::Parser</A> @@ -354,10 +355,10 @@ </tr> </table> <P> -This warning shows up when <CODE>RegistryLoader</CODE> fails to translate the URI into the corresponding filesystem path. Most +This error shows up when <CODE>Apache::RegistryLoader</CODE> fails to translate the URI into the corresponding filesystem path. Most failures happen when one passes a file path instead of URI. (A reminder: <EM>/home/httpd/perl/test.pl</EM> is a file path, while <EM>/perl/test.pl</EM> is a URI). In most cases all you have to do is to pass something that -<CODE>RegistryLoader</CODE> expects to get - the URI, but there are more complex cases. <CODE>RegistryLoader</CODE>'s man page shows how to handle these cases as well (look for the +<CODE>Apache::RegistryLoader</CODE> expects to get - the URI, but there are more complex cases. <CODE>Apache::RegistryLoader</CODE>'s man page shows how to handle these cases as well (look for the <CODE>trans()</CODE> sub). <P> @@ -474,11 +475,8 @@ <P> Most often you will find that you really do have a syntax error. However the other reason might be that a script running under -<CODE>Apache::Registry</CODE> is using <__DATA__> or <__END__> tokens. See -<A HREF="././porting.html#_END_and_DATA_tokens">Learn why</A> +<CODE>Apache::Registry</CODE> is using <CODE>__DATA__</CODE> or <CODE>__END__</CODE> tokens. <A HREF="././porting.html#_END_and_DATA_tokens">Learn why</A>. - - <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> @@ -574,6 +572,33 @@ <P> [ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] <HR> +<CENTER><H2><A NAME="_exit_signal_Segmentation_fault_">"exit signal Segmentation fault (11)" with mysql</A></H2></CENTER> +<P> +If you build mod_perl and php in the same binary, you might get +Segmentation fault followed by this error: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + + <td> + <pre> exit signal Segmentation fault (11)</pre> + </td> + + </tr> + </table> + <P> +Solution: re-compile PHP without the built-in MySQL support (you can still +connect to MySQL). + +<P> +[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ] +<HR> <CENTER><H2><A NAME="foo_at_dev_null_line_0">foo ... at /dev/null line 0</A></H2></CENTER> <P> Under mod_perl you may receive a warning or an error in the @@ -849,8 +874,9 @@ </tr> </table> <P> -In the second case, <CODE>$param</CODE> will always be <CODE>defined</CODE>, either with -<CODE>$q->param('test')</CODE>'s return value, or if the parameter doesn't exist or is <CODE>undef</CODE>ined then the empty string, <CODE>''</CODE>, will be assigned to <CODE>$param</CODE>. +In the second case, <CODE>$param</CODE> will always be <EM>defined</EM>, either with +<CODE>$q->param('test')</CODE>'s return value or the default value (<CODE>''</CODE> +empty string in our example). <P> Also read about <A HREF="././debug.html#Finding_the_Line_Which_Triggered">Finding the Line Which Triggered the Error or Warning</A>. @@ -1022,8 +1048,28 @@ </td> + <td> + <pre> % echo > /dev/null</pre> + </td> + + </tr> + </table> + <P> +Alternatively you should try to remove this special file and recreate it: + +<P> + + <table> + <tr> + + <td bgcolor="#eeeeee" width="1"> + + </td> + <td> - <pre> % sudo echo > /dev/null</pre> + <pre> # rm /dev/null + # mknod /dev/null c 1 3 + # chmod a+rw /dev/null</pre> </td> </tr> @@ -1341,7 +1387,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 11/20/2000 +href="help.html#Contacting_me">Stas Bekman</a>.<br> Last Modified at 03/29/2001 </font></b> <br>