<!doctype linuxdoc system>
<article>
<title>Apache+DSO+mod_ssl+mod_perl+php+mod_auth_nds+mod_auth_mysql+mod_fastcgi</title>
<author>Ray Van Dolson, <tt/rayvd@firetail.org/
<date>v0.91, 5 April 2000</date>
<abstract>
Details the installation of an Apache based webserver suite configured to handle
DSO, and various useful modules including mod_perl, mod_ssl and php.
</abstract>
<toc>
<sect>Legal Stuff
<p>
Apache+mods mini-HOWTO for Linux Systems 
</p><p>
Copyright (C)2000 Ray Van Dolson. 
</p><p>
This document is free; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. 
</p><p>
This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. 
</p><p>
You can get a copy of the GNU GPL at at <url url="http://www.gnu.org/copyleft/gpl.html" name="http://www.gnu.org/copyleft/gpl.html">.
</p>
<sect>Introduction
<p>
This document outlines the process used to install Apache & modules onto the
web-server at Walla Walla College (www.wwc.edu).  While it will be, for the
most part, system specific--hopefully it can serve as a useful reference for
performing other installations.
</p>
<p>
This document will attempt to outline the exact process used to install the
server.  Notes will be made when things should have been gone about
differently, but the original steps will be given (assuming they worked).
</p>
<sect1>Description of the Components
<p>
The platform on which the web-server was set up is a Red Hat 6.1 based system.
Linux kernel 2.2.14 (compiled from scratch) running on a Dual PIII 600 based
system with RAID5 and lots of other goodies.
</p>
<p>
The web-server software is Apache 1.3.12.  The following modules were added
to the server:
</p>
<p>
<itemize>
<item>mod_fastcgi SNAP (also mod_rewrite), for use with Zope.
<item>Auth-MySQL 2.20
<item>mod_ssl 2.6.2 (Open-SSL 0.9.5)
<item>mod_perl 1.21
<item>PHP 3.0.15
<item>mod_auth_nds 0.3a
</itemize>
</p>
<sect1>History
<p>
v0.91 (April 5, 2000)
<itemize>
<item>Updated mod_fastcgi to correct version.
</itemize>
</p><p>
v0.9 (April 4, 2000)
<itemize>
<item>Completed first draft
<item>Spelling/Grammar errors
</itemize>
</p>
<p>
v0.1 (March 2000)
<itemize>
<item>Initial draft
</itemize>
</p>

<sect>Component Installation
<sect1>Preparations
<p>
You will need the following software:
<itemize>
<item><url url="http://www.apache.org/dist/apache_1.3.12.tar.gz" name="Apache 1.3.12">
<item><url url="http://www.php.net/distributions/php-3.0.15.tar.gz" name="PHP 3.0.15">
 <itemize>
  <item>GD 1.3 (to make use of GIF files)
   <itemize>
    <item><url url="http://www.boutell.com/gd/http/gd-1.3.tar.gz" name="Source">
    <item><url url="ftp://rpmfind.net/linux/redhat/redhat-6.0/i386/RedHat/RPMS/gd-1.3-5.i386.rpm" name="RPM">
    <item><url url="ftp://rpmfind.net/linux/redhat/redhat-6.0/i386/RedHat/RPMS/gd-devel-1.3-5.i386.rpm" name="RPM-devel">
   </itemize>
  <item>GD 1.8.1 (to make use of PNG files)
   <itemize>
    <item><url url="http://www.boutell.com/gd/http/gd-1.8.1.tar.gz" name="Source">
    <item><url url="ftp://rpmfind.net/linux/contrib/libc6/i386/gd-1.8.1-1.i386.rpm" name="RPM">
    <item><url url="ftp://rpmfind.net/linux/contrib/libc6/i386/gd-devel-1.8.1-1.i386.rpm" name="RPM-devel">
   </itemize>
  <item>IMAP 4.5+
   <itemize>
    <item><url url="ftp://ftp.cac.washington.edu/imap/imap-4.7b.tar.Z" name="Source">
    <item><url url="ftp://rpmfind.net/linux/redhat/redhat-6.1/i386/RedHat/RPMS/imap-4.5-4.i386.rpm" name="RPM">
   </itemize>
  <item>OpenLDAP 1.2.9+
   <itemize>
    <item><url url="ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-1.2.9.tgz" name="Source">
    <item><url url="ftp://rpmfind.net/linux/rawhide/1.0/i386/RedHat/RPMS/openldap-1.2.9-5.i386.rpm" name="RPM">
    <item><url url="ftp://rpmfind.net/linux/rawhide/1.0/i386/RedHat/RPMS/openldap-devel-1.2.9-5.i386.rpm" name="RPM-devel">
   </itemize>
 </itemize>
<item><url url="http://perl.apache.org/dist/mod_perl-1.22.tar.gz" name="mod_perl 1.22+">
 <itemize>
  <item><em>Perl5 Modules Required</em>
  <item><url url="http://amaunet.informatik.uni-dortmund.de/cgi-bin/CPAN/authors/id/GAAS/MIME-Base64-2.11.tar.gz" name="MIME::Base64">
  <item><url url="http://www.perl.com/CPAN-local/modules/by-module/URI/URI-1.05.tar.gz" name="URI">
  <item><url url="http://www.perl.com/CPAN-local/modules/by-module/HTML/HTML-Parser-3.07.tar.gz" name="HTML-Parser">
  <item><url url="http://www.perl.com/CPAN-local/modules/by-module/Digest/Digest-MD5-2.09.tar.gz" name="Digest-MD5">
  <item><url url="http://www.perl.com/CPAN-local/modules/by-module/Net/libnet-1.0703.tar.gz" name="libnet">
  <item><url url="http://www.perl.com/CPAN-local/modules/by-module/WWW/libwww-perl-5.47.tar.gz" name="libwww">
 </itemize>
<item><url url="http://www.modssl.org/source/mod_ssl-2.6.2-1.3.12.tar.gz" name="mod_ssl 2.6.2+">
 <itemize>
  <item>OpenSSL 0.9.5
   <itemize>
    <item><url url="http://www.openssl.org/source/openssl-0.9.5.tar.gz" name="Source">
    <item><url url="ftp://rpmfind.net/linux/contrib/libc6/i386/openssl-0.9.5-1.i386.rpm" name="RPM">
    <item><url url="ftp://rpmfind.net/linux/contrib/libc6/i386/openssl-devel-0.9.5-1.i386.rpm" name="RPM-devel">
   </itemize>
  <item><url url="ftp://ftp.wwc.edu/pub/apache/modules/mod_ssl/depend/rsaref20.1996.tar.Z" name="RSAREF 2.0">
  <item><url url="http://www.engelschall.com/sw/mm/mm-1.0.12.tar.gz" name="MM 1.0.12">
 </itemize>
<item><url url="http://www.mysql.com/Downloads/MySQL-3.22/mysql-3.22.32.tar.gz" name="MySQL 3.22.32">
<item><url url="ftp://vrooom.at.drew.edu/pub/mod_auth_nds/mod_auth_nds-0.4.tar.gz" name="mod_auth_nds 0.4">
 <itemize>
  <item><url url="ftp://vrooom.at.drew.edu/pub/mod_auth_nds/ncpfs/ncpfs-2.2.0.17.tgz" name="ncpfs 2.2.0.17">
  Note: the kernel must also be compiled with IPX support.
 </itemize>
<item><url url="http://bourbon.netvision.net.il/mysql/mod_auth_mysql/mod_auth_mysql-2.20.tar.gz" name="mod_auth_mysql 2.20">
<item><url url="http://www.FastCGI.com/dist/mod_fastcgi_SNAP_Oct06.tar.gz" name="mod_fastcgi SNAP Oct06">
</itemize>
</p>
<p>
This is the directory layout scheme I use and recommend:
</p>
<p>
<verb>
+ /usr/src
|
+-+ apache
  |
  +-+ apache-1.3.12
  |
  +-+ modules
  | |
  | +-+ mod_perl
  | | |
  | | +- mod_perl-1.21
  | | |
  | | +-+ depend
  | |   |
  | |   +- <perl modules here>
  | |
  | +-+ mod_ssl
  | | |
  | | +- mod_ssl-2.6.2-1.3.12
  | | |
  | | +-+ depend
  | |   |
  | |   +- openssl-0.9.5
  | |   |
  | |   +- rsaref-2.0
  | |   |
  | |   +- mm-1.0.12
  | |
  | +-+ mod_fastcgi_SNAP
  | |
  | +-+ php
  | | |
  | | +- php-3.0.15
  | | |
  | | +-+ depend
  | |   |
  | |   +- gd-1.3
  | |   |
  | |   +- imap-4.5
  | |   |
  | |   +- openldap-1.2.9
  | |
  | +-+ mod_auth_nds
  | | |
  | | +- mod_auth_nds-0.4
  | | |
  | | +-+ depend
  | |   |
  | |   +- ncpfs-2.2.0.17
  | |
  | +-+ mod_auth_mysql
  |
  +-+ mysql
</verb></p>
<p>
Check to see if some of the above modules/software packages are already installed
on your system.  It usually doesn't hurt, however, to download everything and install
it just in case.  You might have an older version installed on your system.
</p>
<sect1>mod_ssl
<sect2>Installing and Compiling OpenSSL
<p>
mod_ssl requires some sort of SSL engine be installed.  OpenSSL is the natural
choice for the Linux environment.  You can either install it via RPM (as I did),
or compile it from source.  Since I did not compile it from source, you're on
your own, although I would think it pretty straightforward.  Most likely you'll
either install it on the system (into /usr/local or something) or leave it in
its directory and simply point whichever applications need OpenSSL to its
directory.
</p>
<p>
RPM will install OpenSSL into system directories.
</p>
<sect2>Installing and Compiling RSAREF 2.0
<p>
Create the rsaref-2.0 directory wherever you like.  For me this is in
/usr/src/apache/modules/mod_ssl-blah/depend/.  Change to this directory.
</p>
<p>
<verb>
cd rsaref-2.0
cp -rp install/unix local
cd local
make
mv rsaref librsaref.a
</verb>
</p>
<p>
These commands should build you the rsaref library!  Just leave the stuff here
and when you need to link against it, just point the appropriate configure
script to this location.
</p>
<sect2>Installing and Compiling MM
<p>
Extract mm-1.0.12 (or whichever version is most current) to the depend
directory of the mod_ssl-blah subdirectory.  Perform the following steps:
</p>
<p>
<verb>
cd mm-1.0.12
./configure --disable-shared
make
</verb>
</p>
<p>
This should build your mm libraries.  As above, reference this path when
needed.  You're on your own if you want to install this library to the system.
</p>
<sect2>Installing and Compiling mod_ssl (at last!)
<p>
The normal procedure with apxs is to compile Apache first, and then, using
apxs, compile the modules you want to use and insert them into the server.
However, mod_ssl needs to be compiled into the server the normal way before you
can use it via apxs.  Once mod_ssl is in the server for the first time, you can
then upgrade it via apxs without having to completely recompile Apache.
</p><p>
Enter the directory where you are compiling mod_ssl and execute the following
configuration directive (here is the file I use) for the initial compile:
</p><p>
<verb>
#!/bin/sh

./configure \
        --with-apache=/usr/src/apache/apache_1.3.12 \
        --with-ssl \
        --with-rsa=../depend/rsaref-2.0/local \
        --with-mm=../depend/mm-1.0.12 \
        --enable-shared=ssl
</verb>
</p><p>
You don't need to run 'make' or anything here.  When we compile Apache, it
will do it all for us.
</p><p>
This configuration line gives two examples of how your system could be set up.
In my case, OpenSSL was already installed somewhere in the system (probably
in /usr/lib, /usr/include).  Therefore, I didn't need to pass it any location
parameters.  However, rsa and mm were -not- on the system, and I compiled them
myself and left them within their source trees (didn't run make install, et
al).  In that case, you need to point configure to the appropriate directory
so it can find the headers/libraries.
</p><p>
From this point on, unless you upgrade Apache (in which case you'd need to
perform the above step again for the new version of Apache), you can use apxs
to upgrade and recompile mod_ssl.  Here is the configure script I use for
this:
</p><p>
<verb>
./configure \
        --with-apxs=/apps/apache-1.3.12/bin/apxs \
        --with-ssl=../depend/openssl-0.9.4 \
        --with-rsa=../depend/rsaref-2.0/local \
        --with-mm=../depend/mm-1.0.12
</verb>
</p><p>
Or some combination of the above.  Then run:
</p><p>
<verb>
make
make install
make distclean
</verb>
</p><p>
to complete the installation.
</p><p>
Notes: <em>MM is -not- required to compile mod_ssl.  If you're having problems
getting it to work, simply omit compiling it and also from the ./configure
line(s).</em>
</p><p>
<em>When I compiled mod_ssl, I had errors regarding DBM.  To fix this, I had to
add -lndbm to the Makefile:</em>
</p><p>
<itemize>
 <item>Run the above configure script.
 <item>cd to pkg.sslmod
 <item>Edit the makefile and add -lndbm to LIBS_SHLIB.  It should look like:
 <item><tt>LIBS_SHLIB=-lm -lcrypt -lndbdm</tt>
</itemize>
</p><p>
<em>Hopefully that will save you some grief.</em>
</p>


<sect1>Apache
<p>
Extract apache-1.3.12.tar.gz to /usr/src/apache or wherever.  Next we want to
compile Apache enabling the following options:
</p><p>
<itemize>
 <item>mod_ssl (In order to compile mod_ssl as a DSO, it has to be first
                 compiled into the server normally.  After doing this, the
                 module can then be upgraded via apxs.)
 <item>mod_proxy
 <item>mod_so
 <item>mod_rewrite (For use with Zope)
</itemize>
</p><p>
Here is the configuration file I used to initially compile Apache:
</p><p>
<verb>
#!/bin/sh

SSL_BASE=../depend/openssl-0.9.4 \
RSA_BASE=../depend/rsaref-2.0/local \
EAPI_MM=../depend/mm-1.0.12 \
./configure \
        --enable-module=ssl \
        --enable-module=proxy\
        --enable-shared=proxy\
        --enable-module=rewrite \
        --enable-shared=rewrite \
        --prefix=/apps/apache-1.3.12 \
        --enable-shared=ssl \
        --enable-rule=SHARED_CORE \
        --enable-rule=SHARED_CHAIN \
        --enable-module=so
</verb>
</p><p>
Then run
</p><p>
<verb>
make
make certificate
make install
</verb>
</p><p>
Apache should now be compiled and installed into whicever directory you
specified with --prefix.  Test it out and make sure it starts up.
</p><p>
<tt>/path/to/apache/bin/apachectl start</tt>
</p><p>or</p><p>
<tt>/path/to/apache/bin/apachectl startssl</tt>
</p><p>
Hopefully it all runs smoothly.  If not, trace back over your steps and ensure
you didn't forget anything.
</p>
<sect1>MySQL
<p>
php as well as mod_auth_mysql and possibly mod_perl will require that MySQL
be installed and running on your system.  It is beyond the scope of this
document to go into the details of installing MySQL, but download the archive
and follow the directions in the INSTALL file(s).  It is a fairly straight-forward 
procedure to get MySQL up and running.  Something like:
</p><p>
<verb>
./configure
make
make install
</verb>
</p><p>
Should get everything installed so that you can compile the other Apache
modules.
</p>
<sect1>PHP 3.0.15
<p>
We will compile php-3.0.15 as a DSO which means that it is a separate module
that can be loaded and unloaded from the server.  This makes it easy to
upgrade php without having to recompile everything (which can be a pain if
you use a lot of modules with Apache).
</p>
<sect2>GD
<p>
In our installation of Apache, php uses gd to create images, and such.  I used
an older version of gd (installed via RPM) to link php against.  This way we
can use output GIF files.  This probably isn't too desirable do to copyright
issues, and thus you may wish to use a version later than 1.3 which only
supports PNG files.
</p><p>
Either install via RPM (rpm -i gd*.rpm) or compile from source and install
to the system.
</p>
<sect2>IMAP
<p>
If you want IMAP support, the procedure is similar to that of gd.  I used the
RPM since I'm on a Red Hat system, but installing from source should be a
relatively simple procedure of ./configure;make;make install.
</p>
<sect2>OpenLDAP
<p>
Once again you can install OpenLDAP either via RPM or source.  I chose to do
it via source since the latest version was not yet available via RPM at the
time we were setting things up.
</p><p>
<verb>
./configure
make
make install
</verb>
</p><p>
should do the trick!  (Or rpm -i openldap*.rpm)
</p>
<sect2>Installing and Compiling PHP 3.0.15
<p>
Once the above items are installed and working, we can go ahead and compile
PHP as a DSO.  The process is very straightforward and simple.
</p><p>
<verb>
cd /usr/src/apache/modules/php/php-3.0.15

./configure \
        --with-apxs=/apps/apache/bin/apxs \
        --with-config-file-path=/apps/etc \
        --with-gd \
        --with-imap \
        --with-mysql=/apps/mysql \
        --with-ldap=/apps \
        --with-zlib \
        --enable-track-vars
</verb>
</p><p>
<em>Make sure that if any of your --with libraries are not installed
in /usr/local or /usr, that you tack on an =/location/ line so that configure
can find the stuff it needs!
</em>
</p><p>
<verb>
make
make install
</verb>
</p><p>
If everything completes properly, 'make install' will use apxs to install
libphp3.so to /apache/libexec/libphp3.so and add the proper entries into
httpd.conf and activate php3.  Pretty slick.
</p>
<sect1>mod_perl
<p>
This section documents the installation of mod_perl as a DSO for Apache.
There are a number of perl modules (in addition, of course, to perl5,
which I will assume you already have installed) that must be added before
mod_perl will compile without complaining.  If you don't install these
modules, mod_perl should complain and tell you which ones you are missing.
</p><p>
There is a certain order in which the modules must be installed.  Some
depend on others and thus I've listed the install order that I used without
any problems.
</p>
<sect2>Required Perl Modules
<p>
The perl modules can be obtained from locations detailed further up in this
document.  Download them and put them wherever you like or in the location
I used as depicted in the directory map (also above).  Installing a module
is fairly simple.  After extracting the module to a directory (usually with
tar xvfz), you simply change to that directory and execute the following
commands:
</p><p>
<verb>
perl Makefile.PL
make
make install
</verb>
</p><p>
If everything goes as it should, this will configure, build and install the
perl module for you.  Of course, check the README for each module if things
don't work quite as expected.
</p><p>
Here is the order I used to install the modules necessary for mod_perl:
</p><p>
<enum>
 <item>MIME::Base64
 <item>URI
 <item>HTML::Parser
 <item>Digest-MD5
 <item>libnet
 <item>libwww
</enum>
</p>
<sect2>Installing and Compiling mod_perl 1.2x
<p>
After installing the perl modules, we're ready to compile and install
mod_perl into Apache.  Change to the directory where you extracted mod_perl
to, and run the following script:
</p><p>
<verb>
perl Makefile.PL \
        USE_APXS=1 \
        WITH_APXS=/path/to/apache/bin/apxs \
        EVERYTHING=1
</verb>
</p><p>
This will set up your Makefile and tell mod_perl to compile itself as a DSO
using apxs (the location of which you must specify).  After this step,
simply run
</p><p>
<verb>
make
make install
</verb>
</p><p>
And mod_perl will be moved to the appropriate directory and lines added to
your httpd.conf file.
</p>
<sect1>mod_auth_mysql
<p>
mod_auth_mysql lets the Apache web-server authorize against a MySQL user
database.  Installation of the module as a DSO isn't exactly documented
in the README file, but it can be done.
</p><p>
First, change to the directory you extracted mod_auth_mysql to.  I assume
that you have MySQL installed somewhere (along with the headers, etc).  Make
sure you know the location of the MySQL libraries and header files.  If in
doubt, check /usr/lib/mysql and /usr/include/mysql.
</p><p>
In order to compile mod_auth_mysql, we'll first have to rename the 'config.h'
file to 'auth_mysql_config.h'.  I'm not sure why this file wasn't named
correctly, but simply execute the following command:
</p><p>
<verb>
cp config.h auth_mysql_config.h
</verb>
</p><p>
Now for the final step:
</p><p>
<verb>
/path/to/apache/bin/apxs -i -a -I/usr/include/mysql -L/usr/lib/mysql \
        -lmysqlclient -c mod_auth_mysql.c
</verb>
</p><p>
You may need to run as root if you do not have read/write access to the Apache
directory.
</p>
<sect1>mod_auth_nds
<p>
At my school, the Windows network of choice is Netware.  It's been in place
for a long time, and although hopefully someday it will be retired, for now
it is still the main network on campus for filesharing and email.  Every student
has a Netware account on which their personal files--including their webpages
are stored.  We mount these directories on our linux server and it's nice to
be able to password protect certain ones with the Netware username and password
information.  With this module, Apache can authenticate straight to the Netware
server itself.
</p>
<sect2>ncpfs
<p>
In order to compile mod_auth_nds, we need to have ncpfs installed (along with its
headers of course).  Before compiling ncpfs, you must ensure that your kernel
has IPX support compiled in.  If this is the case, simply running
</p><p>
<verb>
./configure
make
make install (optional)
</verb>
</p><p>
will compile (and install) the libraries.
</p>
<sect2>Compiling and Installing mod_auth_nds
<p>
With ncpfs installed, running the following command should compile mod_auth_nds
as a DSO:
</p><p>
<verb>
/path/to/apache/bin/apxs -c -lncp -L/usr/lib -I/usr/include mod_auth_nds.c
/path/to/apache/bin/apxs -i mod_auth_nds.so
</verb>
</p><p>
Then add the following lines to your httpd.conf (by hand):
</p><p>
<verb>
LoadModule nds_auth_module libexec/mod_auth_nds.so
AddModule mod_auth_nds.c
</verb>
</p><p>
Then, restart Apache!
</p>
<sect1>mod_fastcgi
<p>
Installing mod_fastcgi is necessary if you want to allow access to your Zope server
through Apache.  This might be useful simply because Apache is inherently more
secure and much more configurable than the Zope server itself.
</p><p>
The current stable version of mod_fastcgi is 2.2.2, however, this version does not
work properly with Zope.  You must get the SNAP release which is dated Oct 06.  The
link is provided above.
</p><p>
Change to the mod_fastcgi directory and run the following commands:
</p><p>
<verb>
/path/to/apache/bin/apxs -o mod_fastcgi.so -c *.c
/path/to/apache/bin/apxs -i -a -n fastcgi mod_fastcgi.so
</verb>
</p><p>
See the mod_fastcgi documentation for a description of its use.
</p>
<sect>Final Words
<p>
Much of this information can be obtained by reading the README and INSTALL files
included with the various modules.  However, this document is useful in the
cases which didn't work as expected for me, or else for which the installation
procedure was not as well defined as I would have liked.  It also has the added
benefit of being one, sequential document, which should hopefully be easier to
follow and understand than a slew of README files.
</p>
<sect1>Credits
<p>
<verb>
Phillip R. Wilson <pwilson@drew.edu>, author of mod_auth_nds, for helping me get
 mod_auth_nds to compile and install with apxs.

John Ash <jash@wwc.edu>, my boss, for all sorts of help and of course, a job.

Marcus Faure <marcus@faure.de>, author of the Apache SSL PHP/FI frontpage mini-
 HOWTO, whose document this one is loosely based on.
</verb>
</p>
<sect1>Contact Information
<p>
If you find any blatant errors in this document, spelling, grammatical,
content or otherwise, please don't hesitate to drop me an email.  You can get
ahold of me via a number of means.
</p><p>
<verb>
Ray Van Dolson
Email: <url url="mailto:rayvd@firetail.org" name="rayvd@firetail.org">
IRC: DALnet, #Bludgeon (nick Variant)
</verb>
<sect1>Anything Else
<p>
Everything mentioned in this document will eventually be available for ftp
from ftp.wwc.edu/pub/apache.  I will have everything laid out as described
above, and hopefully installation scripts to install everything from scratch.
(A very dumb script mind you).
</p>
</article>
