 |
 |
Home / Documentation / 1.0 / mod_perl 1.0 User Guide / |  |
|
|
||||
|
|
|||
|
|
|||
|
||||
|
   |
|
||
|
mod_perl Installation | |
||
|
||||
|
|
|
||
|
||||
  |
|
|||
|
|
Home / Documentation / 1.0 / mod_perl 1.0 User Guide / | |
|
|
||||
|
|
|||
|
|
|||
|
||||
|
|
|
||
|
mod_perl Installation | |
||
|
||||
|
|
|
||
|
||||
|
|
|||
|
|
|
|
||
|
||
|
|
|
|
||
|
||
|
|
|
|
||
|
||
|
|
|
|
||
|
||
|
|
|
|
||
|
||
|
|
|
|
||
|
||
|
The mod_perl Developer's Cookbook
By Geoffrey Young, Paul Lindner, Randy Kobes |
||
|
||
|
mod_perl Pocket Reference
By Andrew Ford |
||
|
||
|
Writing Apache Modules with Perl and C
By Lincoln Stein, Doug MacEachern |
||
|
||
|
Embedding Perl in HTML with Mason
By Dave Rolsky, Ken Williams |
||
|
||
|
||
|
|
||
|
||
An in-depth explanation of the mod_perl installation process, from the basic installation (in 10 steps), to a more complex one (with all the possible options you might want to use, including DSO build). It includes troubleshooting tips too.
First of all:
Apache 2.0 doesn't work with mod_perl 1.0. Apache 1.0 doesn't work with mod_perl 2.0.
The following 10 commands summarize the execution steps required to build and install a basic mod_perl enabled Apache server on almost any standard flavor of Unix OS.
% cd /usr/src
% lwp-download http://www.apache.org/dist/httpd/apache_1.3.xx.tar.gz
% lwp-download http://perl.apache.org/dist/mod_perl-1.xx.tar.gz
% tar xzvf apache_1.3.xx.tar.gz
% tar xzvf mod_perl-1.xx.tar.gz
% cd mod_perl-1.xx
% perl Makefile.PL APACHE_SRC=../apache_1.3.xx/src \
DO_HTTPD=1 USE_APACI=1 EVERYTHING=1
% make && make test && make install
% cd ../apache_1.3.xx
% make install
Of course you should replace 1.xx and 1.3.x with the real version numbers of mod_perl and Apache.
All that's left is to add a few configuration lines to httpd.conf,
the Apache configuration file, start the server and enjoy mod_perl.
If you have stumbled upon a problem at any of the above steps, don't despair, the next sections will explain in detail each and every step.
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 packages:
% rpm -i apache-1.3.xx.rpm % rpm -i mod_perl-1.xx.rpm
or apt system:
% apt-get install libapache-mod-perl
These should set up both Apache and mod_perl correctly for your system. Using a packaged distribution can make installing and reinstalling a lot quicker and easier. (Note that the filenames will vary, and xx will differ.)
Since mod_perl can be configured in many different ways (features can be enabled or disabled, directories can be modified, etc.) it's preferable to use a manual installation, as a prepackaged version might not suit your needs. Manual installation will allow you to make the fine tuning for the best performance as well.
In this chapter we will talk extensively about the prepackaged versions, and ways to prepare your own packages for reuse on many machines. Win32 users should consult the Win32 documentation for details on that platform.
We saw that the basic mod_perl installation is quite simple and takes
about 10 commands. You can copy and paste them from these pages. The
parameter EVERYTHING=1 selects a lot of options, but sometimes you
will need different ones. You may need to pass only specific
parameters, to bundle other components with mod_perl etc. You may
want to build mod_perl as a loadable object instead of compiling it
into Apache, so that it can be upgraded without rebuilding Apache
itself.
To accomplish this you will need to understand various techniques for mod_perl configuration and building. You need to know what configuration parameters are available to you and when and how to use them.
As with Perl, with mod_perl simple things are simple. But when you need to accomplish more complicated tasks you may have to invest some time to gain a deeper understanding of the process. In this chapter I will take the following route. I'll start with a detailed explanation of the four stages of the mod_perl installation process, then continue with the different paths each installation might take according to your goal, followed by a few copy-and-paste real world installation scenarios. Towards the end of the chapter I will show you various approaches that make the installations easier, automating most of the steps. Finally I'll cover some of the general issues that can cause new users to stumble while installing mod_perl.
We can clearly separate the installation process into the following stages:
Before building and installing mod_perl you have to configure it. You configure mod_perl just like any other Perl module:
% perl Makefile.PL [parameters]
In this section we will go through most of the parameters mod_perl can accept and explain each one of them.
First let's see what configuration mechanisms we have available.
Basically they all define a special set of parameters to be passed to
perl Makefile.PL. Depending on the chosen configuration, the final
product might be a stand-alone httpd binary or a loadable object.
The source configuration mechanism in Apache 1.3 provides four major features (which of course are available to mod_perl):
This is a mechanism modules can use to link themselves into the
configuration process. It is useful for automatically adjusting the
configuration and build parameters from the modules sources. It is
triggered by ConfigStart/ConfigEnd sections inside
modulename.module files (e.g. libperl.module).
This is the new top-level configure script from Apache 1.3 which
provides a GNU Autoconf-style interface. It is useful for configuring
the source tree without manually editing any src/Configuration
files. Any parameterization can be done via command line options to
the configure script. Internally this is just a nifty wrapper to
the old src/Configure script.
Since Apache 1.3 this is the way to install mod_perl as cleanly as possible. Currently this is a pure Unix-based solution because at present the complete Apache 1.3 source configuration mechanism is only available under Unix. It doesn't work on the Win32 platform for example.
Besides Windows NT support this is one of most interesting features in
Apache 1.3. Its a way to build Apache modules as so-called dynamic
shared objects (usually named modulename.so) which can be loaded
via the LoadModule directive in Apache's httpd.conf file. The
benefit is that the modules are part of the httpd executable only
on demand, i.e. only when the user wants a module it is loaded into
the address space of the httpd executable. This is interesting for
instance in relation to memory consumption and upgrading.
The DSO mechanism is provided by Apache's mod_so module which needs
to be compiled into the httpd binary. This is done automatically
when DSO is enabled for module mod_foo via:
./configure --enable-module=foo
or by explicitly adding mod_so via:
./configure --enable-module=so
This is a new support tool from Apache 1.3 which can be used to build
an Apache module as a DSO even outside the Apache source-tree. One
can say APXS is for Apache what MakeMaker and XS are for
Perl. It knows the platform dependent build parameters for making DSO
files and provides an easy way to run the build commands with them.
(MakeMaker allows an easy automatic configuration, build,
testing and installation of the Perl modules, and XS allows to call
functions implemented in C/C++ from Perl code.)
Taking these four features together provides a way to integrate mod_perl into Apache in a very clean and smooth way. No patching of the Apache source tree is needed in the standard situation and in the APXS situation not even the Apache source tree is needed.
To benefit from the above features a new hybrid build environment was
created for the Apache side of mod_perl. The Apache-side consists of
the mod_perl C source files which have to be compiled into the
httpd program. They are usually copied to the subdirectory
src/modules/perl/ in the Apache source tree. To integrate this
subtree into the Apache build process a lot of adjustments were done
by mod_perl's Makefile.PL in the past. And additionally the
Makefile.PL controlled the Apache build process.
This approach is problematic in several ways. It is very restrictive and not very clean because it assumes that mod_perl is the only third-party module which has to be integrated into Apache.
The new approach described below avoids these problems. It prepares only the src/modules/perl/ subtree inside the Apache source tree without adjusting or editing anything else. This way, no conflicts can occur. Instead, mod_perl is activated later (when the Apache source tree is configured, via APACI calls) and then it configures itself.
We will return to each of the above configuration mechanisms when describing different installation passes, once the overview of the four building steps is completed.
The command perl Makefile.PL, which is also known as a
"configuration stage", accepts various parameters. In this section
we will learn what they are, and when should they be used.
If you specify neither the DO_HTTPD nor the NO_HTTPD parameters
you will be asked the following question during the configuration
stage:
Configure mod_perl with ../apache_1.3.xx/src ?
APACHE_SRC should be used to define Apache's source tree directory.
For example:
APACHE_SRC=../apache_1.3.xx/src
Unless APACHE_SRC is specified, Makefile.PL makes an intelligent
guess by looking at the directories at the same level as the mod_perl
sources and suggests a directory with the highest version of Apache
found there.
Answering 'y' confirms either Makefile.PL's guess about the
location of the tree, or the directory you have specified with
APACHE_SRC.
If you use DO_HTTPD=1 or NO_HTTPD, the first Apache source tree
found or the one you have defined will be used for the rest of the
build process.
Unless any of DO_HTTPD, NO_HTTPD or PREP_HTTPD is used, you
will be prompted by the following question:
Shall I build httpd in ../apache_1.3.xx/src for you?
Answering 'y' will make sure an httpd binary will be built in
../apache_1.3.xx/src when you run make.
To avoid this prompt when the answer is Yes specify the following argument:
DO_HTTPD=1
Note that if you set DO_HTTPD=1, but do not use
APACHE_SRC=../apache_1.3.xx/src then the first apache source tree
found will be used to configure and build against. Therefore it's
highly advised to always use an explicit APACHE_SRC parameter, to
avoid confusion.
PREP_HTTPD=1 just means default 'n' to the latter prompt,
meaning: Do not build (make) httpd in the Apache source tree. But
it will still ask you about Apache's source location even if you have
used the APACHE_SRC parameter. Providing the APACHE_SRC
parameter will just eliminate the need for perl Makefile.PL to make
a guess.
To avoid the two prompts:
Configure mod_perl with ../apache_1.3.xx/src ? Shall I build httpd in ../apache_1.3.xx/src for you?
and avoid building httpd, use:
NO_HTTPD=1
If you choose not to build the binary you will have to do that
manually. We will talk about it later. In any case you will need to
run make install in the mod_perl source tree, so the Perl side of
mod_perl will be installed. Note that, make test won't work until
you have built the server.
A callback hook (abbrev. callback) is a reference to a
subroutine. In Perl we create callbacks with the $callback = \&subroutine syntax, where in this example, $callback contains a
reference to the subroutine called "subroutine". Callbacks are used
when we want some action (subroutine call) to occur when some event
takes place. Since we don't know exactly when the event will take
place we give the event handler a callback to the subroutine we want
executed. The handler will call our subroutine at the right time.
By default, most of the callback hooks except for
PerlHandler,PerlChildInitHandler, PerlChildExitHandler,
PerlConnectionApi, and PerlServerApi are turned off. You may
enable them by editing src/modules/perl/Makefile, or when running
perl Makefile.PL.
The possible parameters for the appropriate hooks are:
PERL_POST_READ_REQUEST PERL_TRANS PERL_INIT PERL_RESTART (experimental)
PERL_HEADER_PARSER PERL_AUTHEN PERL_AUTHZ PERL_ACCESS PERL_TYPE PERL_FIXUP PERL_LOG PERL_CLEANUP PERL_CHILD_INIT PERL_CHILD_EXIT PERL_DISPATCH PERL_STACKED_HANDLERS PERL_METHOD_HANDLERS PERL_SECTIONS PERL_SSI
As with any parameters that are either defined or not, use
PERL_hookname=1 to enable them (e.g. PERL_AUTHEN=1).
To enable all, but the last 4 callback hooks use:
ALL_HOOKS=1
By default, the Apache source headers files are installed into the $Config{sitearchexp}/auto/Apache/include directory.
The reason for installing the header files is to make life simpler for
module authors/users when building/installing a module that taps into
some Apache C functions, e.g. Embperl, Apache::Peek, etc.
If you don't wish to install these files use:
APACHE_HEADER_INSTALL=0
Normally, if an extension is statically linked with Perl it is listed in
Config.pm's $Config{static_exts}, in which case mod_perl will
also statically link this extension with httpd. However, if an extension
is statically linked with Perl after it is installed, it is not listed in
Config.pm. You may either edit Config.pm and add these
extensions, or configure mod_perl like this:
perl Makefile.PL "PERL_STATIC_EXTS=Something::Static Another::One"
When you use the USE_APACI=1 parameter, you can tell Makefile.PL
to pass any arguments you want to the Apache ./configure utility,
e.g:
% perl Makefile.PL USE_APACI=1 \
APACI_ARGS='--sbindir=/usr/local/httpd_perl/sbin, \
--sysconfdir=/usr/local/httpd_perl/etc, \
--localstatedir=/usr/local/httpd_perl/var, \
--runtimedir=/usr/local/httpd_perl/var/run, \
--logfiledir=/usr/local/httpd_perl/var/logs, \
--proxycachedir=/usr/local/httpd_perl/var/proxy'
Notice that all APACI_ARGS (above) must be passed as one long
line if you work with t?csh!!! However it works correctly as shown
above (breaking the long lines with '\') with (ba)?sh. If you
use t?csh it does not work, since t?csh passes the APACI_ARGS
arguments to ./configure leaving the newlines untouched, but
stripping the backslashes. This causes all the arguments except the
first to be ignored by the configuration process.
Alternatively to:
APACI_ARGS='--prefix=/usr/local/httpd_perl'
from the previous section you can use the APACHE_PREFIX parameter.
When USE_APACI is enabled, this attribute will specify the
--prefix option just like the above setting does.
In addition when the APACHE_PREFIX option is used make install
be executed in the Apache source directory, which makes these two
equivalent:
% perl Makefile.PL APACHE_SRC=../apache_1.3.xx/src \
DO_HTTPD=1 USE_APACI=1 EVERYTHING=1 \
APACI_ARGS='--prefix=/usr/local/httpd_perl'
% make && make test && make install
% cd ../apache_1.3.xx
% make install
% perl Makefile.PL APACHE_SRC=../apache_1.3.xx/src \
DO_HTTPD=1 USE_APACI=1 EVERYTHING=1 \
APACHE_PREFIX=/usr/local/httpd_perl
% make && make test && make install
Now you can pick your favorite installation method.
You can use the environment variables APACHE_USER and
APACHE_GROUP to override the default User and Group settings
in the httpd.conf used for 'make test' stage. (Introduced in
mod_perl v1.23.)
When you have to upgrade the server, it's quite hard to remember what parameters were used in a mod_perl build. So it's better to save them in a file. For example if you create a file at ~/.mod_perl_build_options, with contents:
APACHE_SRC=../apache_1.3.xx/src DO_HTTPD=1 USE_APACI=1 \ EVERYTHING=1
You can build the server with the following command:
% perl Makefile.PL `cat ~/.mod_perl_build_options` % make && make test && make install
But mod_perl has a standard method to perform this trick. If a file named makepl_args.mod_perl is found in the same directory as the mod_perl build location with any of these options, it will be read in by Makefile.PL. Parameters supplied at the command line will override the parameters given in this file.
% ls -1 /usr/src apache_1.3.xx/ makepl_args.mod_perl mod_perl-1.xx/ % cat makepl_args.mod_perl APACHE_SRC=../apache_1.3.xx/src DO_HTTPD=1 USE_APACI=1 \ EVERYTHING=1 % cd mod_perl-1.xx % perl Makefile.PL % make && make test && make install
Now the parameters from makepl_args.mod_perl file will be used, as if they were directly typed in.
Notice that this file can be located in your home directory or in the ../ directory relative to the mod_perl distribution directory. This file can also start with dot (.makepl_args.mod_perl) so you can keep it nicely hidden along with the rest of the dot files in your home directory.
There is a sample makepl_args.mod_perl in the eg/ directory of the mod_perl distribution package, in which you might find a few options to enable experimental features to play with too!
If you are faced with a compiled Apache and no trace of the parameters
used to build it, you can usually still find them if the sources were
not make clean'd. You will find the Apache specific parameters in
apache_1.3.xx/config.status and the mod_perl parameters in
mod_perl-1.xx/apaci/mod_perl.config.
mod_perl version 1.25 has introduced Apache::Myconfig, 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.
To see whether some feature was built in or not, check the
%Apache::MyConfig::Setup hash. For example after installing
mod_perl with the following options:
panic% perl Makefile.PL EVERYTHING=1
but on the next day we don't remember what callback hooks were
enabled, and we want to know whether PERL_LOG callback hook is
enabled. One of the ways to find this out is to run the following
code:
panic% perl -MApache::MyConfig \
-e 'print $Apache::MyConfig::Setup{PERL_LOG}'
1
which prints '1'--meaning that PERL_LOG callback hook was
enabled. (That's because EVERYTHING=1 enables them all.)
Another approach is to configure Apache::Status and run
http://localhost/perl-status?hooks to check for enabled hooks.
You also may try to look at the symbols inside the httpd executable
with help of nm(1) or a similar utility. For example if you want
to see whether you enabled PERL_LOG=1 while building mod_perl, we
can search for a symbol with the same name but in lowercase:
panic% nm httpd | grep perl_log 08071724 T perl_logger
Indeed we can see that in our example PERL_LOG=1 was enabled. But
this will only work if you have an unstripped httpd binary. By
default, make install strips the binary before installing it. Use
the --without-execstrip ./Configure option to prevent stripping
during make install phase.
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
By default mod_perl provides its own copy of the Configuration file
to Apache's ./configure utility. If you wish to pass it your own
version, do this:
% perl Makefile.PL CONFIG=Configuration.custom
Where Configuration.custom is the pathname of the file relative to the Apache source tree you build against.
When you see this during the perl Makefile.PL stage:
** A test compilation with your Makefile configuration ** failed. This is most likely because your C compiler ** is not ANSI. Apache requires an ANSI C Compiler, such ** as gcc. The above error message from your compiler ** will also provide a clue. Aborting!
you've got a problem with your compiler. It is possible that it's improperly installed or not installed at all. Sometimes the reason is that your Perl executable was built on a different machine, and the software installed on your machine is not the same. Generally this happens when you install the prebuilt packages, like RPM or deb. The dependencies weren't properly defined in the Perl binary package and you were allowed to install it, although some essential package is not installed.
The most frequent pitfall is a missing gdbm library. See Missing or Misconfigured libgdbm.so for more info.
But why guess, when we can actually see the real error message and understand what the real problem is. To get a real error message, edit the Apache src/Configure script. Down around line 2140 you will see a line like this:
if ./helpers/TestCompile sanity; then
change it to:
if ./helpers/TestCompile -v sanity; then
and try again. Now you should get a useful error message.
On some Linux RedHat systems you might encounter a problem during the
perl Makefile.PL stage, when the installed from the rpm package
Perl was built with the gdbm library, but the library isn't
actually installed. If this is your situation make sure you install
it before proceeding with the build process.
You can check how Perl was built by running the perl -V command:
% perl -V | grep libs
On my machine I get:
libs=-lnsl -lndbm -lgdbm -ldb -ldl -lm -lc -lposix -lcrypt
Sometimes the problem is even more obscure: you do have libgdbm
installed but it's not properly installed. Do this:
% ls /usr/lib/libgdbm.so*
If you get at least three lines like I do:
lrwxrwxrwx /usr/lib/libgdbm.so -> libgdbm.so.2.0.0 lrwxrwxrwx /usr/lib/libgdbm.so.2 -> libgdbm.so.2.0.0 -rw-r--r-- /usr/lib/libgdbm.so.2.0.0
you are all set. On some installations the libgdbm.so symbolic link is missing, so you get only:
lrwxrwxrwx /usr/lib/libgdbm.so.2 -> libgdbm.so.2.0.0 -rw-r--r-- /usr/lib/libgdbm.so.2.0.0
To fix this problem add the missing symbolic link:
% cd /usr/lib % ln -s libgdbm.so.2.0.0 libgdbm.so
Now you should be able to build mod_perl without any problems.
Note that you might need to prepare this symbolic link as well:
lrwxrwxrwx /usr/lib/libgdbm.so.2 -> libgdbm.so.2.0.0
with:
% ln -s libgdbm.so.2.0.0 libgdbm.so.2
Of course if when you read this a new version of the libgdbm
library will be released, you will have to adjust the version
numbers. We didn't use the usual xx version replacement here, to
make it easier to understand how the symbolic links should be set.
Both the gdbm and db libraries offer ndbm emulation, which is the interface that Apache actually uses, so when you build mod_perl you end up with whichever library was linked first by the perl compile. If you build apache without mod_perl you end up with whatever appears to be your ndbm library which will vary between systems, and especially Linux distributions. You may have to work a bit to get both Apache and Perl to use the same library and you are likely to have trouble copying the dbm file from one system to another or even using it after an upgrade.
When manually building mod_perl using the shared library:
cd mod_perl-1.xx perl Makefile.PL PREP_HTTPD=1 make make test make install cd ../apache_1.3.xx ./configure --with-layout=RedHat --target=perlhttpd --activate-module=src/modules/perl/libperl.a
you might get:
gcc -c -I./os/unix -I./include -DLINUX=2 -DTARGET=\"perlhttpd\" -DUSE_HSREGEX
-DUSE_EXPAT -I./lib/expat-lite `./apaci` buildmark.c
gcc -DLINUX=2 -DTARGET=\"perlhttpd\" -DUSE_HSREGEX -DUSE_EXPAT
-I./lib/expat-lite `./apaci` \
-o perlhttpd buildmark.o modules.o modules/perl/libperl.a
modules/standard/libstandard.a main/libmain.a ./os/unix/libos.a ap/libap.a
regex/libregex.a lib/expat-lite/libexpat.a -lm -lcrypt
modules/perl/libperl.a(mod_perl.o): In function `perl_shutdown':
mod_perl.o(.text+0xf8): undefined reference to `PL_perl_destruct_level'
mod_perl.o(.text+0x102): undefined reference to `PL_perl_destruct_level'
mod_perl.o(.text+0x10c): undefined reference to `PL_perl_destruct_level'
mod_perl.o(.text+0x13b): undefined reference to `Perl_av_undef'
[more errors snipped]
This happens when you have a statically linked perl build (i.e. without a shared libperl.so library). Build a dynamically linked perl (with libperl.so) and the problem will disappear. See the "Building a shared Perl library" section from the INSTALL file that comes with Perl source.
Also see "Chapter 15.4 - Perl Build Options" from Practical mod_perl.
Library files such as libfoo.a are archives that are used at linking time - these files are completely included in the final application that linked it.
Whereas libfoo.so indicates that it's a shared library. At the linking time the application only knows which library it wants. Only at the loading time (runtime) that shared library will be loaded.
One of the benefits of using a shared library, is that it's loaded only once. If there are two application linking to libperl.so that run at the same time, only the first application will need to load it. The second application will share that loaded library (that service is provided by the OS kernel). In the case of static libfoo.a, it'll be loaded as many times as there are applications that included it, thus consuming more memory. Of course this is not the only benefit of using shared libs.
In mod_perl 1.0, the library file is unfortunately named libperl.(so|a). So you have libperl.(so|a) which is perl, and you have libperl.(so|a) which is modperl. You are certainly looking at the modperl version of libperl.a if you find it in the apache directory. perl's libperl.(so|a) lives under the perl tree (e.g. in 5.8.6/i686-linux/CORE/libperl.so).
Some distributions (notably Debian) have chosen to put libperl.so and libperl.a into the global library loader path (e.g., /usr/lib) which will cause linking problems when compiling mod_perl (if compiling against static perl), in which case you should move aside the libperl.a while building mod_perl or else will likely encounter further errors. If building against the dynamic perl's libperl.so, you may have similar problems but at startup time. It's the best to get rid of perl that installs its libs into /usr/lib (or similar) and reinstall a new perl, which puts its library under the perl tree. Also see libperl.so and libperl.a.
After completing the configuration you build the server, by calling:
% make
which compiles the source files and creates an httpd binary and/or a
separate library for each module, which can either be inserted into
the httpd binary when make is called from the Apache source directory
or loaded later, at run time.
Note: don't put the mod_perl directory inside the Apache directory. This confuses the build process.
This and similar error messages may show up during the make
process. Generally it happens when you have a broken Perl
installation. Make sure it's not installed from a broken RPM or
another binary package. If it is, build Perl from source or use
another properly built binary package. Run perl -V to learn what
version of Perl you are using and other important details.
This error usually reported due to the problems with some versions of SFIO library. Try to use the latest version to get around this problem. Or if you don't really need SFIO, rebuild Perl without this library.
After building the server, it's a good idea to test it thoroughly, by calling:
% make test
Fortunately mod_perl comes with a bunch of tests, which attempt to use
all the features you asked for at the configuration stage. If any of
the tests fails, the make test stage will fail.
Running make test will start a freshly built httpd on port 8529
running under the uid and gid of the perl Makefile.PL process. The
httpd will be terminated when the tests are finished.
Each file in the testing suite generally includes more than one test,
but when you do the testing, the program will only report how many
tests were passed and the total number of tests defined in the test
file. However if only some of the tests in the file fail you want to know
which ones failed. To gain this information you should run the tests in
verbose mode. You can enable this mode by using the TEST_VERBOSE
parameter:
% make test TEST_VERBOSE=1
To change the default port (8529) used for the test do this:
% perl Makefile.PL PORT=xxxx
To start the newly built Apache:
% make start_httpd
To shutdown Apache:
% make kill_httpd
NOTE to Ben-SSL users: httpsd does not seem to handle /dev/null as
the location of certain files (for example some of the configuration
files mentioned in httpd.conf can be ignored by reading them from
/dev/null) so you'll have to change these by hand. The tests are
run with the SSLDisable directive.
Tests are invoked by running the ./TEST script located in the
./t directory. Use the -v option for verbose tests. You might
run an individual test like this:
% t/TEST -v modules/file.t
or all tests in a test sub-directory:
% t/TEST modules
The TEST script starts the server before the test is executed. If
for some reason it fails to start, use make start_httpd to start it
manually.
You cannot run make test before you build Apache, so if you told
perl Makefile.PL not to build the httpd executable, there is no
httpd to run the test against. Go to the Apache source tree and run
make, then return to the mod_perl source tree and continue with the
server testing.
If you had a stale old Apache header layout in one of the include
paths during the build process you will see this message when you try
to execute httpd. Run the find (or locate) utility in order to
locate the file ap_mmn.h. Delete it and rebuild Apache. RedHat
installed a copy of /usr/local/include/ap_mmn.h on my system.
For all RedHat fans, before you build Apache yourself, do:
% rpm -e apache
to remove the pre-installed RPM package first!
Users with apt systems would do:
% apt-get remove apache
instead.
While doing make test you will notice that some of the tests are
reported as skipped. The reason is that you are missing some
optional modules for these test to be passed. For a hint you might
want to peek at the content of each test (you will find them all in
the ./t directory (mnemonic - t, tests). I'll list a few examples,
but of course things may change in the future.
modules/cookie......skipping test on this platform modules/request.....skipping test on this platform
Install libapreq package which includes among others the
Apache::Request and Apache::Cookie modules.
modules/psections...skipping test on this platform
Install Devel::Symdump and Data::Dumper
modules/sandwich....skipping test on this platform
Install Apache::Sandwich
modules/stage.......skipping test on this platform
Install Apache::Stage
modules/symbol......skipping test on this platform
Install Devel::Symdump
Chances are that all of these are installed if you use CPAN.pm to
install Bundle::Apache.
The make test suite uses localhost to run the tests that require
a network. Make sure you have this entry in /etc/hosts:
127.0.0.1 localhost.localdomain localhost
Also make sure that you have the loopback device [lo] configured. [Hint: try 'ifconfig lo' to test for its existence.]
After testing the server, the last step left is to install it. First install all the Perl side files:
% make install
Then go to the Apache source tree and complete the Apache installation (installing the configuration files, httpd and utilities):
% cd ../apache_1.3.xx % make install
Now the installation should be considered complete. You may now configure your server and start using it.
If you wish to build httpd separately from mod_perl, you should use
the NO_HTTPD=1 option during the perl Makefile.PL (mod_perl
build) stage. Then you will need to configure various things by hand
and proceed to build Apache. You shouldn't run perl Makefile.PL
before following the steps described in this section.
If you choose to manually build mod_perl, there are three things you may need to set up before the build stage:
When perl Makefile.PL is executed,
$APACHE_SRC/modules/perl/Makefile may need to be modified to enable
various options (e.g. ALL_HOOKS=1).
Optionally, instead of tweaking the options during perl Makefile.PL
you may edit mod_perl-1.xx/src/modules/perl/Makefile before running
perl Makefile.PL.
Add to apache_1.3.xx/src/Configuration :
AddModule modules/perl/libperl.a
We suggest you add this entry at the end of the Configuration file if you want your callback hooks to have precedence over core handlers.
Add the following to EXTRA_LIBS:
EXTRA_LIBS=`perl -MExtUtils::Embed -e ldopts`
Add the following to EXTRA_CFLAGS:
EXTRA_CFLAGS=`perl -MExtUtils::Embed -e ccopts`
Return to the mod_perl directory and copy the mod_perl source files into the apache build directory:
% cp -r src/modules/perl apache_1.3.xx/src/modules/
When you have done with the configuration parts, run:
% perl Makefile.PL NO_HTTPD=1 DYNAMIC=1 EVERYTHING=1\ APACHE_SRC=../apache_1.3.xx/src
DYNAMIC=1 enables a build of the shared mod_perl library. Add
other options if required.
% make install
Now you may proceed with the plain Apache build process. Note that in
order for your changes to the apache_1.3.xx/src/Configuration file
to take effect, you must run apache_1.3.xx/src/Configure instead of
the default apache_1.3.xx/configure script:
% cd ../apache_1.3.xx/src % ./Configure % make % make install
There are various ways available to build Apache with the new hybrid
build environment (using USE_APACI=1):
If your goal is just to build and install Apache with mod_perl out of their source trees and have no special interest in further adjusting or enhancing Apache proceed as before:
% tar xzvf apache_1.3.xx.tar.gz
% tar xzvf mod_perl-1.xx.tar.gz
% cd mod_perl-1.xx
% perl Makefile.PL APACHE_SRC=../apache_1.3.xx/src \
DO_HTTPD=1 USE_APACI=1 EVERYTHING=1
% make && make test && make install
% cd ../apache_1.3.xx
% make install
This builds Apache statically with mod_perl, installs Apache under the
default /usr/local/apache tree and mod_perl into the site_perl
hierarchy of your existing Perl installation. All in one step.
This is the normal situation where you want to be flexible while
building. Statically building mod_perl into the Apache binary
(httpd) but via different steps, so you have a chance to include
other third-party Apache modules, etc.
The first step is as before, extract the distributions:
% tar xvzf apache_1.3.xx.tar.gz % tar xzvf mod_perl-1.xx.tar.gz
The second step is to install the Perl-side of mod_perl into the Perl
hierarchy and prepare the src/modules/perl/ subdirectory inside the
Apache source tree:
$ cd mod_perl-1.xx
$ perl Makefile.PL \
APACHE_SRC=../apache_1.3.xx/src \
NO_HTTPD=1 \
USE_APACI=1 \
PREP_HTTPD=1 \
EVERYTHING=1 \
[...]
$ make
$ make install
$ cd ..
The APACHE_SRC option sets the path to your Apache source tree, the
NO_HTTPD option forces this path and only this path to be used, the
USE_APACI option triggers the new hybrid build environment and the
PREP_HTTPD option forces preparation of the
APACHE_SRC/modules/perl/ tree but no automatic build.
Then the configuration process prepares the Apache-side of mod_perl in the Apache source tree but doesn't touch anything else in it. It then just builds the Perl-side of mod_perl and installs it into the Perl installation hierarchy.
Important: If you use PREP_HTTPD as described above, to complete
the build you must go into the Apache source directory and run make
and make install.
Now you have a chance to prepare third-party modules. For instance the PHP language can be added in a manner similar to the mod_perl procedure.
Finally it's time to build the Apache package and thus also the Apache-side of mod_perl and any other third-party modules you've prepared:
$ cd apache_1.3.xx
$ ./configure \
--prefix=/path/to/install/of/apache \
--activate-module=src/modules/perl/libperl.a \
[...]
$ make
$ make install
The --prefix option is needed if you want to change the default
target directory of the Apache installation and the
--activate-module option activates mod_perl for the configuration
process and thus also for the build process. If you choose
--prefix=/usr/share/apache the Apache directory tree will be
installed in /usr/share/apache.
Note that the files activated by --activate-module do not exist at
this time. They will be generated during compilation.
The last three steps build, test and install the Apache-side of the mod_perl enabled server. Presumably your new server includes third-party components, otherwise you probably won't choose this method of building.
The method described above enables you to insert mod_perl into Apache without having to mangle the Apache source tree for mod_perl. It also gives you the freedom to add third-party modules.
Perl versions prior to 5.6.0, built with -Dusemymalloc, and
versions 5.6.0 and newer, built with -Dusemymalloc and
-Dbincompat5005, pollute the main httpd program with free
and malloc symbols. When httpd restarts (happens at startup
too), any references in the main program to free and malloc
become invalid, and this causes memory leaks and segfaults.
To determine if you can use a DSO mod_perl with your version of Perl, first find out which malloc your Perl was built with by running:
% perl -V:usemymalloc
If you get:
usemymalloc='n';
then it means that Perl is using the system malloc, so mod_perl will work fine as DSO.
If you get:
usemymalloc='y';
it means that Perl is using its own malloc. If you are running Perl
older than 5.6.0, you must rebuild Perl with -Uusemymalloc in
order to use it with a DSO mod_perl. If you are running Perl 5.6.0 or
newer, you must either rebuild Perl with -Uusemymalloc, or make sure
that binary compatibility with Perl 5.005 turned off. To find out, run:
% perl -V:bincompat5005
If you get:
bincompat5005='define';
then you must either rebuild Perl with -Ubincompat5005 or with
-Uusemymalloc to use it with a DSO mod_perl. We recommend that you
rebuild Perl with -Ubincompat5005 if Perl's malloc is a better choice
for your OS.
Note that mod_perl's build system issues a warning about this problem.
If you needed to rebuild Perl don't forget to rebuild mod_perl too.
We have already said that the new mod_perl build environment
(USE_APACI) is a hybrid. What does it mean? It means for instance
that the same src/modules/perl/ stuff can be used to build mod_perl
as a DSO or not, without having to edit anything especially for this.
When you want to build libperl.so all you have to do is to add one
single option to the above steps.
libmodperl.so would be more correct for the mod_perl file, but the
name has to be libperl.so because of prehistoric Apache issues.
Don't confuse the libperl.so for mod_perl with the file of the same
name which comes with Perl itself. They are two different things. It
is unfortunate that they happen to have the same name.
There is also a libperl.a which comes with the Perl installation.
That's different too.
You have two options here, depending on which way you have chosen above: If you choose the All-In-One way from above then add
USE_DSO=1
to the perl Makefile.PL options. If you choose the Flexible way
then add:
--enable-shared=perl
to Apache's ./configure options.
As you can see only an additional USE_DSO=1 or
--enable-shared=perl option is needed. Everything else is done
automatically: mod_so is automatically enabled, the Makefiles are
adjusted automatically and even the install target from APACI now
additionally installs libperl.so into the Apache installation tree.
And even more: the LoadModule and AddModule directives (which
dynamically load and insert mod_perl into httpd) are automatically
added to httpd.conf.
Above we've seen how to build mod_perl as a DSO inside the Apache
source tree. But there is a nifty alternative: building mod_perl as a
DSO outside the Apache source tree via the new Apache 1.3 support
tool apxs (APache eXtension). The advantage is obvious: you can
extend an already installed Apache with mod_perl even if you don't
have the sources (for instance, you may have installed an Apache
binary package from your vendor).
Here are the build steps:
% tar xzvf mod_perl-1.xx.tar.gz
% cd mod_perl-1.xx
% perl Makefile.PL \
USE_APXS=1 \
WITH_APXS=/path/to/bin/apxs \
EVERYTHING=1 \
[...]
% make && make test && make install
This will build the DSO libperl.so outside the Apache source
tree with the new Apache 1.3 support tool apxs and install it into
the existing Apache hierarchy.
([ReaderMETA]: Please send more scenarios of mod_perl + other components installation guidelines. Thanks!)
You have now seen very detailed installation instructions for specific cases, but since mod_perl is used with many other components that plug into Apache, you will definitely want to know how to build them together with mod_perl.
Since all the steps are simple, and assuming that you now understand how the build process works, I'll show only the commands to be executed with no comments unless there is something we haven't discussed before.
Generally every example that I'm going to show consist of:
downloading the source distributions of the components to be used
un-packing them
configuring them
building Apache using the parameters appropriate to each component
make test and make install.
All these scenarios were tested on a Linux platform, you might need to refer to the specific component's documentation if something doesn't work for you as described below. The intention of this section is not to show you how to install other non-mod_perl components alone, but how to do this in a bundle with mod_perl.
Also, notice that the links I've used below are very likely to have changed by the time you read this document. That's why I have used the x.x.x convention, instead of using hardcoded version numbers. Remember to replace the xx place-holders with the version numbers of the distributions you are about to use. To find out the latest stable version number, visit the components' sites. So if the instructions say:
http://perl.apache.org/dist/mod_perl-1.xx.tar.gz
go to http://perl.apache.org/download/ in order to learn the version number of the latest stable release and download the appropriate file.
Unless otherwise noted, all the components install themselves into a
default location. When you run make install the installation
program tells you where it's going to install the files.
mod_ssl provides strong cryptography for the Apache 1.3 webserver via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols by the help of the Open Source SSL/TLS toolkit OpenSSL, which is based on SSLeay from Eric A. Young and Tim J. Hudson.
Download the sources:
% lwp-download http://www.apache.org/dist/apache_1.3.xx.tar.gz % lwp-download http://perl.apache.org/dist/mod_perl-1.xx.tar.gz % lwp-download http://www.modssl.org/source/mod_ssl-x.x.x-x.x.x.tar.gz % lwp-download http://www.openssl.org/source/openssl-x.x.x.tar.gz
Un-pack:
% tar xvzf mod_perl-1.xx % tar xvzf apache_1.3.xx.tar.gz % tar xvzf mod_ssl-x.x.x-x.x.x.tar.gz % tar xvzf openssl-x.x.x.tar.gz
Configure, build and install openssl:
% cd openssl-x.x.x % ./config % make && make test && make install
Configure mod_ssl:
% cd mod_ssl-x.x.x-x.x.x % ./configure --with-apache=../apache_1.3.xx
Configure mod_perl:
% cd ../mod_perl-1.xx
% perl Makefile.PL USE_APACI=1 EVERYTHING=1 \
DO_HTTPD=1 SSL_BASE=/usr/local/ssl \
APACHE_PREFIX=/usr/local/apachessl \
APACHE_SRC=../apache_1.3.xx/src \
APACI_ARGS='--enable-module=ssl,--enable-module=rewrite'
Note: Do not forget that if you use csh or tcsh you may need to
put all the arguments to `perl Makefile.PL' on a single command line.
Note: If when specifying SSL_BASE=/usr/local/ssl Apache's configure
doesn't find the ssl libraries, please refer to the mod_ssl
documentation to figure out what SSL_BASE argument it expects
(usually needed when ssl is not installed in the standard places).
This topic is out of scope of this document. For some setups using
SSL_BASE=/usr/local does the trick.
Build, test and install:
% make && make test && make install % cd ../apache_1.3.xx % make certificate % make install
Now proceed with the mod_ssl and mod_perl parts of the server configuration before starting the server.
When the server starts you should see the following or similar in the error_log file:
[Fri Nov 12 16:14:11 1999] [notice] Apache/1.3.9 (Unix) mod_perl/1.21_01-dev mod_ssl/2.4.8 OpenSSL/0.9.4 configured -- resuming normal operations
As in the previous section this shows an installation of mod_perl and mod_ssl, but this time using sources/binaries prepackaged in RPMs.
As always, replace xx with the proper version numbers. And
replace i386 with the identifier for your platform if it is
different.
% get apache-mod_ssl-x.x.x.x-x.x.x.src.rpm
Source: http://www.modssl.org
% get openssl-x.x.x.i386.rpm
Source: http://www.openssl.org/
% lwp-download http://perl.apache.org/dist/mod_perl-1.xx.tar.gz
Source: http://perl.apache.org/dist
% lwp-download http://www.engelschall.com/sw/mm/mm-x.x.xx.tar.gz
% rpm -ivh openssl-x.x.x.i386.rpm
% rpm -ivh apache-mod_ssl-x.x.x.x-x.x.x.src.rpm
% cd /usr/src/redhat/SPECS
% rpm -bp apache-mod_ssl.spec
% cd /usr/src/redhat/BUILD/apache-mod_ssl-x.x.x.x-x.x.x
% tar xvzf mod_perl-1.xx.tar.gz
% cd mod_perl-1.xx
% perl Makefile.PL APACHE_SRC=../apache_1.3.xx/src \
DO_HTTPD=1 \
USE_APACI=1 \
PREP_HTTPD=1 \
EVERYTHING=1
Add or remove parameters if appropriate.
% make
% make install
% cd ../mm-x.x.xx/
% ./configure --disable-shared
% make
% cd ../mod_ssl-x.x.x-x.x.x
% ./configure \
--with-perl=/usr/bin/perl \
--with-apache=../apache_1.3.xx\
--with-ssl=SYSTEM \
--with-mm=../mm-x.x.x \
--with-layout=RedHat \
--disable-rule=WANTHSREGEX \
--enable-module=all \
--enable-module=define \
--activate-module=src/modules/perl/libperl.a \
--enable-shared=max \
--disable-shared=perl
% make
% make certificate
with whatever option is suitable to your configuration.
% make install
You should be all set.
Note: If you use the standard config for mod_ssl don't forget to run Apache like this:
% httpd -DSSL
Apache-SSL is a secure Webserver, based on Apache and SSLeay/OpenSSL. It is licensed under a BSD-style license which means, in short, that you are free to use it for commercial or non-commercial purposes, so long as you retain the copyright notices.
Download the sources:
% lwp-download http://www.apache.org/dist/apache_1.3.xx.tar.gz % lwp-download http://perl.apache.org/dist/mod_perl-1.xx.tar.gz % lwp-download http://www.apache-ssl.org/.../apache_1.3.xx+ssl_x.xx.tar.gz % lwp-download http://www.openssl.org/source/openssl-x.x.x.tar.gz
Un-pack:
% tar xvzf mod_perl-1.xx % tar xvzf apache_1.3.xx.tar.gz % tar xvzf openssl-x.x.x.tar.gz
Configure and install openssl:
% cd openssl-x.x.x % ./config % make && make test && make install
Patch Apache with SSLeay paths
% cd apache_x.xx % tar xzvf ../apache_1.3.xx+ssl_x.xx.tar.gz % FixPatch Do you want me to apply the fixed-up Apache-SSL patch for you? [n] y
Now edit the src/Configuration file if needed and then configure:
% cd ../mod_perl-1.xx
% perl Makefile.PL USE_APACI=1 EVERYTHING=1 \
DO_HTTPD=1 SSL_BASE=/usr/local/ssl \
APACHE_SRC=../apache_1.3.xx/src
Build, test and install:
% make && make test && make install % cd ../apache_1.3.xx/src % make certificate % make install
Note that you might need to modify the 'make test' stage, as it takes
much longer for this server to get started and make test waits only
a few seconds for Apache to start before it times out.
Now proceed with configuration of the apache_ssl and mod_perl parts of the server configuration files, before starting the server.
Stronghold is a secure SSL Web server for Unix which allows you to give your web site full-strength, 128-bit encryption.
You must first build and install Stronghold without mod_perl, following Stronghold's install procedure. For more information visit http://www.c2.net/products/sh2/ .
Having done that, download the sources:
% lwp-download http://perl.apache.org/dist/mod_perl-1.xx.tar.gz
Unpack:
% tar xvzf mod_perl-1.xx.tar.gz
Configure (assuming that you have the Stronghold sources extracted at /usr/local/stronghold):
% cd mod_perl-1.xx
% perl Makefile.PL APACHE_SRC=/usr/local/stronghold/src \
DO_HTTPD=1 USE_APACI=1 EVERYTHING=1
Build:
% make
Before running make test, you must add your StrongholdKey to
t/conf/httpd.conf. If you are configuring by hand, be sure to edit
src/modules/perl/Makefile and uncomment the #APACHE_SSL
directive.
Test and Install:
% make test && make install % cd /usr/local/stronghold % make install
There has been a report related to the REGEX library that comes
with Stronghold, that after building Apache with mod_perl it would
produce core dumps. To work around this problem, in
$STRONGHOLD/src/Configuration change:
Rule WANTHSREGEX=default
to:
Rule WANTHSREGEX=no
This is a simple installation scenario of the mod_perl and mod_php in Apache server:
Configure Apache.
% cd apache_1.3.xx % ./configure --prefix=/usr/local/etc/httpd
(this step might be redundant with the recent versions of mod_php, but it's harmless.)
Build mod_perl.
% cd ../mod_perl-1.xx
% perl Makefile.PL APACHE_SRC=../apache_1.3.xxx/src NO_HTTPD=1 \
USE_APACI=1 PREP_HTTPD=1 EVERYTHING=1
% make
Build mod_php.
% cd ../php-x.x.xx
% ./configure --with-apache=../apache_1.3.xxx \
--with-mysql --enable-track-vars
% make
% make install
Build Apache:
% cd ../apache_1.3.xxx
% ./configure --prefix=/usr/local/etc/httpd \
--activate-module=src/modules/perl/libperl.a \
--activate-module=src/modules/php4/libphp4.a \
--enable-module=stats \
--enable-module=rewrite
% make
Note: libperl.a and libphp4.a do not exist at this time. They will be generated during compilation.
Test and install mod_perl
% cd ../mod_perl-1.xx % make test # make install.
Complete the Apache installation.
% cd ../apache_1.3.xxx # make install
Note: If you need to build mod_ssl as well, make sure that you add the mod_ssl first.