You are viewing a plain text version of this content. The canonical link for it is here.
Posted to modperl-cvs@perl.apache.org by sb...@hyperreal.org on 1999/05/08 20:05:54 UTC
cvs commit: modperl-site/guide install.html
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 && make test && 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 ( < 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><Location /perl-status</CODE>> 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 <ENTER> key TWICE!
<P>
<PRE> % telnet yourserver.com 8080<ENTER>
HEAD / HTTP/1.0<ENTER><ENTER>
</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 "Content-type: text/html\n\n";
print "Server's environment<P>\n";
print "<TABLE>";
foreach ( keys %ENV ) {
print "<TR><TD>$_ </TD><TD>$ENV{$_}</TR></TD>";
}
print "</TABLE>";
</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 & Associates</A>,<BR>
and is used by permission.
</FONT>
</TD>
</TR>
</TABLE></CENTER>
</BODY>
</HTML>