perl-modperl-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sbek...@hyperreal.org
Subject cvs commit: modperl-site/guide install.html
Date Sat, 08 May 1999 18:05:54 GMT
sbekman     99/05/08 11:05:54

  Added:       guide    install.html
  Log:
  another one added
  
  Revision  Changes    Path
  1.1                  modperl-site/guide/install.html
  
  Index: install.html
  ===================================================================
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
  <HTML>
  <HEAD>
     <TITLE>mod_perl guide: Installation Notes</TITLE>
     <META NAME="GENERATOR" CONTENT="Mozilla/3.04Gold (X11; I; AIX 4.1) [Netscape]">
     <META NAME="Author" CONTENT="Bekman Stas">
     <META NAME="Description" CONTENT="All Apache/Perl related information: Hints, 
  Guidelines, Scenarios and Troubleshottings">
     <META NAME="keywords" CONTENT="mod_perl modperl perl apache cgi webserver speed 
  fast guide mod_perl apache guide help info faq mod_perl installation cgi
  troubleshooting help no sex speedup free open source OSS mod_perl apache guide">
  </HEAD>
       <LINK REL=STYLESHEET TYPE="text/css"
          HREF="style.css" TITLE="refstyle">
       <style type="text/css">
       <!-- 
          @import url(style.css);
       -->
       
       </style>
  <BODY TEXT="#000000" BGCOLOR="#E0FFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#FF0000">
  <A NAME="toc"></A>
  <H1 ALIGN=CENTER>
  <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon"
BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=LEFT></A>
  <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl.gif" ALT="Mod Perl Icon"
BORDER=0 HEIGHT=30 WIDTH=90 ALIGN=RIGHT></A>
  Installation Notes</H1>
  <HR WIDTH="100%">
  	    [    <A HREF="scenario.html">Prev</A> |      <A HREF="index.html">Main
Page</A> | <A HREF="config.html">Next</A>      ]<HR><!-- INDEX
BEGIN -->
  <P><B><FONT SIZE=-1>Table of Contents:</FONT></B></P>
  <UL>
  
  	<LI><A HREF="#Configuration_and_Installation">Configuration and Installation</A>
  	<UL>
  
  		<LI><A HREF="#Perl">Perl</A>
  		<LI><A HREF="#Apache">Apache</A>
  		<LI><A HREF="#Mod_Perl">Mod_Perl</A>
  	</UL>
  
  	<LI><A HREF="#How_can_I_tell_whether_mod_perl_">How can I tell whether mod_perl
is really installed</A>
  	<UL>
  
  		<LI><A HREF="#Testing_by_checking_the_error_lo">Testing by checking the error_log
file</A>
  		<LI><A HREF="#Testing_by_viewing_perl_status">Testing by viewing /perl-status</A>
  		<LI><A HREF="#Testing_via_telnet">Testing via telnet</A>
  		<LI><A HREF="#Testing_via_a_CGI_script">Testing via a CGI script</A>
  		<LI><A HREF="#Testing_via_lwp_request">Testing via lwp-request</A>
  	</UL>
  
  	<LI><A HREF="#Is_it_possible_to_install_and_us">Is it possible to install and
use apache/mod_perl without having a root access?</A>
  	<LI><A HREF="#Is_it_possible_to_determine_whic">Is it possible to determine
which options were given to modperl's Makefile.PL</A>
  	<LI><A HREF="#Server_Installation">Server Installation</A>
  	<UL>
  
  		<LI><A HREF="#make_test_fails">make test fails</A>
  	</UL>
  
  </UL>
  <!-- INDEX END -->
  
  <HR>
  
  	     The <a href="http://www.modperl.com/">
  	     <B>Writing Apache Modules with Perl and C</B></a>
  	     book can be purchased online from <a
  	     href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
  	     and <a
  	     href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
  	     Amazon.com</a>.
  
  	     <HR>
  
  	      <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <P>
  <CENTER><H1><A NAME="Configuration_and_Installation">Configuration and
Installation</A></H1></CENTER>
  <P>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <CENTER><H2><A NAME="Perl">Perl</A></H2></CENTER>
  <P>
  First install perl. Follow the instructions in the distribution's INSTALL
  file. During the configuration stage (while running
  <CODE>./Configure</CODE>), make sure you answer <CODE>YES</CODE>
to:
  
  <P>
  <PRE>  Do you wish to use dynamic loading? [y]
  </PRE>
  <P>
  You will want this feature on to dynamically load the Perl
  Modules/extensions.
  
  <P>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <CENTER><H2><A NAME="Apache">Apache</A></H2></CENTER>
  <P>
  It is a good idea to try to install the Apache webserver without mod_perl
  first. This way, if something going wrong, you will know that it's not the
  Apache server's problem. But you can skip this stage if you already have a
  working (non-mod_perl) Apache server, or if you are just the daring type.
  In any case you should unpack the Apache source distribution, preferably at
  the same level as the mod_perl distribution.
  
  <P>
  <PRE>  % ls -l /usr/src
    drwxr-xr-x   8 stas  bar         2048 Oct  6 09:46 apache_1.3.6/
    drwxr-xr-x  19 stas  bar         4096 Oct  2 14:33 mod_perl-1.19/
  </PRE>
  <P>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <CENTER><H2><A NAME="Mod_Perl">Mod_Perl</A></H2></CENTER>
  <P>
  Now we come to the main point of this document.
  
  <P>
  Here I will give only a short example of mod_perl installation. You should
  read the real world scenarios for a more complete description.
  
  <P>
  As with any perl package, the installation of mod_perl is very easy and
  standard. <CODE>perldoc INSTALL</CODE> will guide you thru the configuration
and installation process.
  
  <P>
  The fastest way to install would be:
  
  <P>
  <PRE>  % perl Makefile.PL APACHE_SRC=../apache_1.3.6/src \
      DO_HTTPD=1  USE_APACI=1 PERL_MARK_WHERE=1 EVERYTHING=1
    % make &amp;&amp; make test &amp;&amp; make install
  </PRE>
  <P>
  (Note: if you use an apache version different then apache_1.3.6, change the
  version number in the example above and in all later examples
  appropriately)
  
  <P>
  To change the installation target (either if you are not <CODE>root</CODE> or
you need to install a second copy for testing purposes), assuming you
  use /foo/server as a base directory root, you have to run this:
  
  <P>
  <PRE>  % perl Makefile.PL APACHE_SRC=../apache_1.3.6/src \
      DO_HTTPD=1 PERL_MARK_WHERE=1 EVERYTHING=1 \
      APACHE_PREFIX=/foo/server PREFIX=/foo/server
  </PRE>
  <P>
  Where <CODE>PREFIX</CODE> specifies where to install the perl modules,
  <CODE>APACHE_PREFIX</CODE> - the same for the apache files.
  
  <P>
  The next step is to configure the mod_perl sections of the apache conf
  files. See <A HREF="././config.html#">ModPerlConfiguration</A>
  
  
  
  <P>
  Fire up the server with <CODE>/foo/server/sbin/apachectl start</CODE>, Watch
the error log file if server does not start up (No error message
  will be printed to the console!)
  
  <P>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <CENTER><H1><A NAME="How_can_I_tell_whether_mod_perl_">How can I tell
whether mod_perl is really installed</A></H1></CENTER>
  <P>
  There a few ways. In older versions of apache ( &lt; 1.3.6 ?) you could check that by
running <CODE>httpd -v</CODE>, it no longer works. Now you should use <CODE>httpd
-l</CODE>. Please notice that it is not enough to have it installed - you should of
  course configure it and restart the server.
  
  <P>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <CENTER><H2><A NAME="Testing_by_checking_the_error_lo">Testing by checking
the error_log file</A></H2></CENTER>
  <P>
  <PRE>  [Thu Dec  3 17:27:52 1998] [notice] Apache/1.3.1 (Unix) mod_perl/1.15 configured
-- resuming normal operations
                                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  </PRE>
  <P>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <CENTER><H2><A NAME="Testing_by_viewing_perl_status">Testing by viewing
/perl-status</A></H2></CENTER>
  <P>
  Assuming that you have configured the <CODE>&lt;Location /perl-status</CODE>&gt;
Section in the server configuration file (refer to
  <A HREF="././config.html#">ModPerlConfiguration</A>), fetch: <A
  HREF="http://www.yourserver.com/perl-status">http://www.yourserver.com/perl-status</A>
  using your favorite Netscape browser :-)
  
  <P>
  You should see something like this:
  
  <P>
  <PRE>  Embedded Perl version 5.00502 for Apache/1.3.1 (Unix) mod_perl/1.19 
    process 50880, running since Tue Oct 6 14:31:45 1998
  </PRE>
  <P>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <CENTER><H2><A NAME="Testing_via_telnet">Testing via telnet</A></H2></CENTER>
  <P>
  Knowing the port you have configured Apache to listen on, you can use
  <CODE>telnet</CODE> to talk directly to the web server.
  
  <P>
  Assume that you set <CODE>Port 8080</CODE> in the httpd.conf for your mod_perl
enabled server. Telnet to your server
  at port 8080, and type <CODE>HEAD / HTTP/1.0</CODE> then press the &lt;ENTER&gt;
key TWICE!
  
  <P>
  <PRE>  % telnet yourserver.com 8080&lt;ENTER&gt;
    HEAD / HTTP/1.0&lt;ENTER&gt;&lt;ENTER&gt;
  </PRE>
  <P>
  You should see a response like this:
  
  <P>
  <PRE>  HTTP/1.1 200 OK
    Date: Tue, 01 Dec 1998 12:27:52 GMT
    Server: Apache/1.3.6 (Unix) mod_perl/1.19
    Connection: close
    Content-Type: text/html
    
    Connection closed.
  </PRE>
  <P>
  So you see <CODE>Server: Apache/1.3.6 (Unix) mod_perl/1.19</CODE> - which says
that you <STRONG>do</STRONG> have mod_perl installed and it is version 1.19. Of
course in your case it
  would be the version you have installed.
  
  <P>
  However, just because you have got mod_perl linked in there, that does not
  meant that you have your server configured to use mod_perl to handle Perl
  scripts. You will find the configuration assistance at
  <A HREF="././config.html#">ModPerlConfiguration</A>
  
  
  
  <P>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <CENTER><H2><A NAME="Testing_via_a_CGI_script">Testing via a CGI script</A></H2></CENTER>
  <P>
  Another method is to invoke a CGI script which dumps the server's
  environment.
  
  <P>
  Copy and paste the script below (no need for perl line!). Let's say you
  called it test.pl, you saved it into the root of the cgi scripts, and cgi
  root is mapped directly to /perl of your server.
  
  <P>
  <PRE>  print &quot;Content-type: text/html\n\n&quot;;
    print &quot;Server's environment&lt;P&gt;\n&quot;;
    print &quot;&lt;TABLE&gt;&quot;;
    foreach ( keys %ENV ) {
        print &quot;&lt;TR&gt;&lt;TD&gt;$_ &lt;/TD&gt;&lt;TD&gt;$ENV{$_}&lt;/TR&gt;&lt;/TD&gt;&quot;;
    }
    print &quot;&lt;/TABLE&gt;&quot;;
  </PRE>
  <P>
  Make it executable:
  
  <P>
  <PRE>  % chmod a+x test.pl
  </PRE>
  <P>
  Now fetch the URL <CODE>http://www.you.com:8080/perl/test.pl</CODE>. You should
see something like this (part of the output was snipped).
  
  <P>
  <PRE>  SERVER_SOFTWARE    Apache/1.3.6 (Unix) mod_perl/1.19
    GATEWAY_INTERFACE  CGI-Perl/1.1
    REQUEST_METHOD     GET
    HTTP_ACCEPT        image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
    MOD_PERL           1.19
    REQUEST_URI        /perl/test.pl
    SCRIPT_NAME        /perl/test.pl
    [...snipped]
  </PRE>
  <P>
  Now if I run the same script in mod_cgi mode (configured with /cgi-bin)
  (you will need to add the perl line <CODE>#!/bin/perl</CODE> for the above script)
and fetch <CODE>http://www.you.com/cgi-bin/test.pl</CODE>.
  
  <P>
  <PRE>  SERVER_SOFTWARE   Apache/1.3.6 (Unix)
    GATEWAY_INTERFACE CGI/1.1
    [...snipped]
  </PRE>
  <P>
  You will see that two variables, <CODE>SERVER_SOFTWARE</CODE> and
  <CODE>GATEWAY_INTERFACE</CODE>, are different from the case above. This gives
you a hint of how to tell
  in what mode you are running in your cgi scripts. I start all my cgi
  scripts that are mod_perl aware with:
  
  <P>
  <PRE>  BEGIN {
        # Auto-detect if we are running under mod_perl or CGI.
      $USE_MOD_PERL = ((exists $ENV{'GATEWAY_INTERFACE'}
                    and $ENV{'GATEWAY_INTERFACE'} =~ /CGI-Perl/)
                     or exists $ENV{'MOD_PERL'} );
        # perl5.004 is a must under mod_perl
      require 5.004 if $USE_MOD_PERL;
    }
  </PRE>
  <P>
  You might wonder why in the world you would need to know in what mode you
  are running. For example you will want to use <CODE>Apache::exit()</CODE>
  and not <CODE>CORE::exit()</CODE> in your scripts, but if you think that your
script might be used in both
  environments (mod_cgi vs. mod_perl), you will have to override the <CODE>exit()</CODE>
subroutine and to make the runtime decision of what method you will use.
  For reasons and implementations see: <A HREF="././porting.html#Using_exit_">Using
exit()</A> and the whole <A HREF="././porting.html#">Writing Mod Perl scripts
and Porting plain CGIs to it</A> page.
  
  <P>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <CENTER><H2><A NAME="Testing_via_lwp_request">Testing via lwp-request</A></H2></CENTER>
  <P>
  Yet another one. Why do I show all these approaches? While here they are
  serving a very simple purpose, they can be helpful in other situations.
  
  <P>
  Assuming you have the libwww-perl (LWP) package installed (you will need it
  installed in order to pass mod_perl's <CODE>make test</CODE> anyway):
  
  <P>
  <PRE>  % lwp-request -e -d www.site.com
  </PRE>
  <P>
  Will show you all the headers. (The <CODE>-d</CODE> option disables printing
the response content.)
  
  <P>
  <PRE>  % lwp-request -e -d www.site.com | egrep '^Server:'
  </PRE>
  <P>
  To see the server's version only.
  
  <P>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <CENTER><H1><A NAME="Is_it_possible_to_install_and_us">Is it possible
to install and use apache/mod_perl without having a root access?</A></H1></CENTER>
  <P>
  Yes, no problem with that. Follow the instructions above and when you
  encounter APACI_ARGS use your home directory (or some other directory which
  you have write access to as a prefix, for example,
  <CODE>/home/stas/www</CODE>) and everything will be installed there. There is
a chance that some perl
  libs will be not installed on your server by root and you will have to
  install these locally too. See the <A
  HREF="http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html#7">http://www.singlesheaven.com/stas/TULARC/webmaster/myfaq.html#7</A>
  for more information on local perl installations.
  
  <P>
  You will not be able to have the server listen to a port lower then 1024 if
  you are not starting it as <CODE>root</CODE>, so choose a port number above
1024. (I use 8080 in most cases). Note that
  you will have to use a URL like <CODE>http://www.you.com:8080</CODE> in that
case, but that is not a problem since generally users do not
  directly access URLs to CGI scripts, but rather are directed to them from a
  link on a web page or as the '<CODE>ACTION</CODE>' of an HTML form, so they
should not know at all that the port is
  different from the default port 80.
  
  <P>
  If you want your Apache server to start automatically on system reboot, you
  will need to invoke the server startup script from somewhere within the
  init scripts on your host. (This is often somewhere under <CODE>/etc/rc.d</CODE>,
but this path can vary depending upon the flavor of Unix you are using.)
  
  <P>
  One more important thing to keep in mind is system resources. Mod_perl is
  memory hungry -- if you run a lot of mod_perl processes on that machine
  (and it's not your own host...), most likely the system administrator of
  the host will ask you to shutdown your mod_perl server, or to find another
  home for it. You have a few solutions:
  
  <P>
  <STRONG>a</STRONG>. Reduce resource usage - see <A HREF="././performance.html#Limiting_the_size_of_the_process">Limiting
the size of the processes</A>
  
  
  
  <P>
  <STRONG>b</STRONG>. Ask your ISP if you can put a dedicated machine into their
computer room
  and be root there.
  
  <P>
  <STRONG>c</STRONG>. Look for another ISP with lots of resources or one that
supports mod_perl
  (not likely)
  
  <P>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <CENTER><H1><A NAME="Is_it_possible_to_determine_whic">Is it possible
to determine which options were given to modperl's Makefile.PL</A></H1></CENTER>
  <P>
  It is possible to determine which options were given to modperl's
  <CODE>Makefile.PL</CODE> during the configuration stage, so to be used later
in recreating the same
  build tree when rebuilding the server. This is relevant only if did not use
  the default config parameters and altered some of them during the
  configuration stage.
  
  <P>
  I was into this problem many times. I am going to build something by
  passing some non default parameters to the config script and then later
  when I need to rebuild the tool either to upgrade it or to make an
  identical copy at some other machine, I have found that I do not remember
  what parameters did I altered.
  
  <P>
  The best solution for this problem is to prepare the run file with all the
  parameters that are about to be used and then run it instead of typing it
  all by hand. So later I will have the script handy to be reused.
  
  <P>
  mod_perl suggests using the <CODE>makepl_args.mod_perl</CODE> file which comes
with mod_perl distribution. This is the file you specify
  all the parameters you are going to use.
  
  <P>
  But if you have found yourself with a compiled tool and no traces of the
  specified parameters left, you can still find them out if the sources were
  not <CODE>make clean</CODE>'d. So you will find the apache specific parameters
in <CODE>apache_x.x.x/config.status</CODE> and modperl's at in <CODE>mod_perl_x.xx/apaci/mod_perl.config</CODE>.
  
  <P>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <CENTER><H1><A NAME="Server_Installation">Server Installation</A></H1></CENTER>
  <P>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  <CENTER><H2><A NAME="make_test_fails">make test fails</A></H2></CENTER>
  <P>
  There are two configuration parameters <CODE>PREP_HTTPD</CODE> and <CODE>DO_HTTPD</CODE>
  you can use in <CODE>perl Makefile.PL [options]</CODE>.
  
  <P>
  <CODE>DO_HTTPD=1</CODE> means default to 'y' for the two prompts (which source
tree to configure
  against and to build the httpd in that tree).
  <CODE>PREP_HTTPD=1</CODE> just means default 'n' to the second prompt, meaning,
do not build httpd
  (make) in the Apache source tree.
  
  <P>
  In other words if you use <CODE>PREP_HTTPD=1</CODE> the httpd will be not build.
It will be build only if you use <CODE>DO_HTTPD=1</CODE> option and not use
  <CODE>PREP_HTTPD=1</CODE>.
  
  <P>
  If you did not build the httpd, chdir to the apache source, and execute:
  
  <P>
  <PRE>  make
  </PRE>
  <P>
  Then return to the mod_perl source and run:
  
  <P>
  <PRE>  make test
    make install
  </PRE>
  <P><B><FONT SIZE=-1><A HREF="#toc">[TOC]</A></FONT></B><HR
WIDTH="100%"></P>
  	     The <a href="http://www.modperl.com/">
  	     <B>Writing Apache Modules with Perl and C</B></a>
  	     book can be purchased online from <a
  	     href="http://www.ora.com/catalog/wrapmod/">O'Reilly </a>
  	     and <a
  	     href="http://www.amazon.com/exec/obidos/ASIN/156592567X/writinapachemodu">
  	     Amazon.com</a>.
  
  	     <HR>
  	     [    <A HREF="scenario.html">Prev</A> |      <A HREF="index.html">Main
Page</A> | <A HREF="config.html">Next</A>      ]
  
  <CENTER><TABLE CELLSPACING=2 CELLPADDING=2 WIDTH="100%" >
  <TR ALIGN=CENTER VALIGN=TOP>
    <TD ALIGN=CENTER VALIGN=CENTER COLSPAN="3">
  	     <HR>
    </TD>
  </TR>
  <TR ALIGN=CENTER VALIGN=TOP>
    <TD ALIGN=CENTER VALIGN=CENTER>
      <B>
        <FONT SIZE=-1>
  	     Written by <A HREF="help.html#This_document_s_Author">Stas Bekman</A>.
  	     <BR>Last Modified at 05/08/1999
        </FONT>
      </B>
    </TD>
  
    <TD>
  	     <A HREF="http://perl.apache.org"><IMG SRC="images/mod_perl2.jpg" ALT="Mod
Perl Icon" BORDER=0 HEIGHT=59 WIDTH=150></A>
    </TD>
  
    <TD>
      <FONT SIZE=-2>
  	     Use of the Camel for Perl is <BR>
  	     a trademark of <A HREF="http://www.ora.com">O'Reilly &amp; Associates</A>,<BR>
               and is used by permission. 
      </FONT> 
    </TD>
  </TR>
  </TABLE></CENTER>
  
  </BODY>
  </HTML>
  	    
  
  

Mime
View raw message