Building mod_perl with Other Components (Practical mod_perl)

mod_perl is often used with other components that plug into Apache, such as PHP and SSL. In this section, we'll show you a build combining mod_perl with PHP. We'll also show how to build a secure version of Apache with mod_perl support using each of the SSL options available for Apache today (mod_ssl, Apache-SSL, Stronghold, and Covalent).

Since you now understand how the build process works, we'll present these scenarios without much explanation (unless they involve something we haven't discussed yet).

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 here. 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 we've used are very likely to have changed by the time you read this document. That's why we have used the x.xx convention instead of using hardcoded version numbers. Remember to replace the x.xx placeholders with the version numbers of the distributions you are going to use. To find out the latest stable version number, visit the components' sites—e.g., if we say http://perl.apache.org/dist/mod_perl-1.xx.tar.gz, go to http://perl.apache.org/download/ to learn the version number of the latest stable release of mod_perl 1, 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.

3.6.1. Installing mod_perl with PHP

The following is a simple installation scenario of a combination mod_perl and PHP build for the Apache server. We aren't going to use a custom installation directory, so Apache will use the default /usr/local/apache directory.

Download the latest stable source releases:

Apache:   http://www.apache.org/dist/httpd/
mod_perl: http://perl.apache.org/download/
PHP:      http://www.php.net/downloads.php

Unpack them:

panic% tar xvzf mod_perl-1.xx
panic% tar xvzf apache_1.3.xx.tar.gz
panic% tar xvzf php-x.x.xx.tar.gz

Configure Apache:

panic% cd apache_1.3.xx
panic% ./configure

Build mod_perl:

panic% cd ../mod_perl-1.xx
panic% perl Makefile.PL APACHE_SRC=../apache_1.3.xx/src NO_HTTPD=1 \
    USE_APACI=1 PREP_HTTPD=1 EVERYTHING=1
panic% make

Build mod_php:

panic% cd ../php-x.x.xx
panic% ./configure --with-apache=../apache_1.3.xx \
    --with-mysql --enable-track-vars
panic% make
panic# make install

(mod_php doesn't come with a make test suite, so we don't need to run one.)

Reconfigure Apache to use mod_perl and PHP, and then build it:
```
panic% cd ../apache_1.3.xx
panic% ./configure \
    --activate-module=src/modules/perl/libperl.a \
    --activate-module=src/modules/php4/libphp4.a
panic% make
```
Note that if you are building PHP3, you should use php3/libphp3.a. Also remember that libperl.a and libphp4.a do not exist at this time. They will be generated during compilation.

Test and install mod_perl:

panic% cd ../mod_perl-1.xx
panic% make test
panic# make install

Complete the Apache installation:

panic# cd ../apache_1.3.xx
panic# make install

Now when you start the server:

panic# /usr/local/apache/bin/apachectl start

you should see something like this in /usr/local/apache/logs/error_log:

[Sat May 18 11:10:31 2002] [notice]
Apache/1.3.24 (Unix) PHP/4.2.0 mod_perl/1.26
configured -- resuming normal operations

If you need to build mod_ssl as well, make sure that you add the mod_ssl component first (see the next section).

3.6.2. Installing mod_perl with mod_ssl (+openssl)

mod_ssl provides strong cryptography for the Apache 1.3 web server via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols. mod_ssl uses the open source SSL/TLS toolkit OpenSSL, which is based on SSLeay, by Eric A. Young and Tim J. Hudson. As in the previous installation scenario, the default installation directory is used in this example.

Download the latest stable source releases. For mod_ssl, make sure that the version matches your version of Apache (e.g., get mod_ssl-2.8.8-1.3.24.tar.gz if you have Apache 1.3.24).

Apache:   http://www.apache.org/dist/httpd/
mod_perl: http://perl.apache.org/download/
mod_ssl:  http://www.modssl.org/source/
openssl:  http://www.openssl.org/source/

Unpack the sources:

panic% tar xvzf mod_perl-1.xx.tar.gz
panic% tar xvzf apache_1.3.xx.tar.gz
panic% tar xvzf mod_ssl-x.x.x-1.3.xx.tar.gz
panic% tar xvzf openssl-x.x.x.tar.gz

Configure, build, test, and install openssl if it isn't already installed:
```
panic% cd openssl-x.x.x
panic% ./config
panic% make && make test
panic# make install
```
(If you already have the openssl development environment installed, you can skip this stage.)

Configure mod_ssl:

panic% cd mod_ssl-x.x.x-1.3.xx
panic% ./configure --with-apache=../apache_1.3.xx

Configure, build, test, and install mod_perl:

panic% cd ../mod_perl-1.xx
panic% perl Makefile.PL USE_APACI=1 EVERYTHING=1 \
    DO_HTTPD=1 SSL_BASE=/usr/local/ssl \
    APACHE_SRC=../apache_1.3.xx/src \
    APACI_ARGS='--enable-module=ssl'
panic% make && make test
panic# make install

Create an SSL certificate and install Apache and certificate files:

panic% cd ../apache_1.3.xx
panic% make certificate
panic# make install

Now proceed with the mod_ssl and mod_perl parts of the server configuration in httpd.conf. The next chapter provides in-depth information about mod_perl configuration. For mod_ssl configuration, please refer to the mod_ssl documentation available from http://www.modssl.org/.

Now when you start the server:

panic# /usr/local/apache/bin/apachectl startssl

you should see something like this in /usr/local/apache/logs/error_log:

[Fri May 18 11:10:31 2001] [notice]
Apache/1.3.24 (Unix) mod_perl/1.26 mod_ssl/2.8.8
OpenSSL/0.9.6c configured -- resuming normal operations

If you used the default configuration, the SSL part won't be loaded if you use apachectl start and not apachectl startssl.

This scenario also demonstrates the fact that some third-party Apache modules can be added to Apache by just enabling them (as with mod_ssl), while others need to be separately configured and built (as with mod_perl and PHP).

3.6.3. Installing mod_perl with Apache-SSL (+openssl)

Apache-SSL is a secure web server based on Apache and SSLeay/OpenSSL. It is licensed under a BSD-style license, which means that you are free to use it for commercial or non-commercial purposes as long as you retain the copyright notices.

Apache-SSL provides similar functionality to mod_ssl. mod_ssl is what is known as a split—i.e., it was originally derived from Apache-SSL but has been extensively redeveloped so the code now bears little relation to the original. We cannot advise you to use one over another—both work fine with mod_perl, so choose whichever you want. People argue about which one to use all the time, so if you are interested in the finer points, you may want to check the mailing list archives of the two projects (http://www.apache-ssl.org/#Mailing_List and http://www.modssl.org/support/).

To install mod_perl with Apache-SSL:

Download the sources. You'll need to have matching Apache-SSL and Apache versions.

Apache:     http://www.apache.org/dist/httpd/
mod_perl:   http://perl.apache.org/download/
openssl:    http://www.openssl.org/source/
Apache-SSL: http://www.apache-ssl.org/#Download

Unpack the sources:

panic% tar xvzf mod_perl-1.xx
panic% tar xvzf apache_1.3.xx.tar.gz
panic% tar xvzf openssl-x.x.x.tar.gz

Configure and install openssl, if necessary:
```
panic% cd openssl-x.x.x
panic% ./config
panic% make && make test
panic# make install
```
If you already have the openssl development environment installed, you can skip this stage.
Apache-SSL comes as a patch to Apache sources. First unpack the Apache-SSL sources inside the Apache source tree and make sure that the Apache source is clean (in case you've used this source to build Apache before). Then run ./FixPatch and answer y to proceed with the patching of Apache sources:
```
panic% cd apache_1.3.xx
panic% make clean
panic% tar xzvf ../apache_1.3.xx+ssl_x.xx.tar.gz
panic% ./FixPatch
Do you want me to apply the fixed-up Apache-SSL patch for you? [n] y
```
Proceed with mod_perl configuration. The notable addition to the usual configuration parameters is that we use the SSL_BASE parameter to point to the directory in which openssl is installed:
```
panic% cd ../mod_perl-1.xx
panic% 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 mod_perl:

panic% make && make test
panic# make install

Create an SSL certificate and install Apache and the certificate files:

panic# cd ../apache_1.3.xx
panic# make certificate
panic# make install

Now proceed with the configuration of the Apache-SSL and mod_perl parts of the server configuration files before starting the server. Refer to the Apache-SSL documentation to learn how to configure the SSL section of httpd.conf.

Now start the server:

panic# /usr/local/apache/bin/httpsdctl start

Note that by default, Apache-SSL uses httpsdctl instead of apachectl.

You should see something like this in /usr/local/apache/logs/httpsd_error_log:

[Sat May 18 14:14:12 2002] [notice]
Apache/1.3.24 (Unix) mod_perl/1.26 Ben-SSL/1.48 (Unix)
configured -- resuming normal operations

3.6.4. Installing mod_perl with Stronghold

Stronghold is a secure SSL web server for Unix that allows you to give your web site full-strength, 128-bit encryption. It's a commercial product provided by Red Hat. See http://www.redhat.com/software/apache/stronghold/ for more information.

To install Stronghold:

First, build and install Stronghold without mod_perl, following Stronghold's installation procedure.

Having done that, download the mod_perl sources:

panic% lwp-download http://perl.apache.org/dist/mod_perl-1.xx.tar.gz

Unpack mod_perl:
```
panic% tar xvzf mod_perl-1.xx.tar.gz
```

Configure mod_perl with Stronghold (assuming that you have the Stronghold sources extracted to /usr/local/stronghold):

panic% cd mod_perl-1.xx
panic% perl Makefile.PL APACHE_SRC=/usr/local/stronghold/src \
    DO_HTTPD=1 USE_APACI=1 EVERYTHING=1

Build mod_perl:
```
panic% make
```
Before running make test, 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 mod_perl:
```
panic% make test
panic# make install
```

Install Stronghold:

panic# cd /usr/local/stronghold
panic# make install

Note for Solaris 2.5 Users

There has been a report that after building Apache with mod_perl, the the REGEX library that comes with Stronghold produces core dumps. To work around this problem, change the following line in $STRONGHOLD/src/Configuration:

Rule WANTHSREGEX=default

to:

Rule WANTHSREGEX=no

Now start the server:

panic# /usr/local/stronghold/bin/start-server

It's possible that the start script will have a different name on your platform.

You should see something like this in /usr/local/stronghold/logs/error_log:

[Sun May 19 11:54:39 2002] [notice]
StrongHold/3.0 Apache/1.3.24 (Unix) mod_perl/1.26
configured -- resuming normal operations


3.5. Installation Scenarios for Standalone mod_perl		3.7. Installing mod_perl with the CPAN.pm Interactive Shell

3.6. Building mod_perl with Other Components

3.6.1. Installing mod_perl with PHP

3.6.2. Installing mod_perl with mod_ssl (+openssl)

3.6.3. Installing mod_perl with Apache-SSL (+openssl)

3.6.4. Installing mod_perl with Stronghold

Note for Solaris 2.5 Users