Building Apache with mod_ssl and Other Modules

Introduction

This document is intended to be a down-and-dirty guide to building the Apache web server from source code. The task of building Apache itself from source is not very difficult. However, when you begin to throw additional modules and support programs into the mix, it can begin to get confusing. mod_ssl generally proves to be one of the more difficult modules to install, as it has several dependencies which must be compiled and installed first.

These steps were performed numerous times on Slackware Linux boxes ranging in version from 3.5 to 7.0. You should not have problems compiling Apache or any of its modules on almost any modern UNIX operating system. Note that this procedure documents building a static Apache binary without DSO support. This means that the web server needs to be recompiled each time a module is added or removed. You will not be able to dynamically add and remove modules with this method. If you wish to add DSO support to your Apache binary, please see Appendix B.

Required Software

In order to build our web server, the following packages are needed:

Be sure to download the latest versions available of each of these packages. At the time of writing, the file list above was the latest version of each package. Note that the version of mod_ssl is dependent on the version of Apache, as seen in the file name of mod_ssl, above. Make sure that the mod_ssl and Apache versions match.

Download these modules to a convenient place, such as /usr/src, and uncompress and untar them. Keep the original distributions around for backup purposes. The packages can be uncompressed and untarred in one step, if using GNU's version of tar. For example:

$ tar -xzvf apache_1.3.14.tar.gz

Compiling Modules and Supporting Software

The first step is to do an initial configuration of Apache. A few modules, such as PHP4, require Apache to have been configured at least once before they can be applied to the Apache source tree. We do not need to specify any special parameters at this point, as we will be doing the actual config of Apache much later.

$ cd apache_1.3.14
$ ./configure
$ cd ..

The next step is to compile the OpenSSL tools. This will create the necessary libraries for mod_ssl to compile against, as well as create the openssl command line tool for doing things like generating SSL certificates. The default install location for openssl is /usr/local/ssl, which can be overridden on the config command line, if so desired.

$ cd openssl-0.9.6
$ sh config -fPIC
$ make
$ make install
$ cd ..

Next, we compile and install Ralf Engelschall's (of mod_ssl fame) MM library. MM, according to the README, "simplifies the usage of shared memory between forked processes under Unix platforms."

$ cd mm-1.1.3
$ ./configure --disable-shared
$ make
$ make install
$ cd ..

Now, we configure the mod_ssl module. The configuration of mod_ssl is actually nothing more than a patch tool which applies the mod_ssl source to the Apache source tree specified on the configure command line. As such, we don't need to do any actual compilation in the mod_ssl distribution.

$ cd mod_ssl-2.7.1-1.3.14.tar.gz
$ ./configure --with-apache=../apache_1.3.14
$ cd ..

Compiling Optional Modules

At this point we can install additional modules, such as PHP4 and mod_perl.

PHP is an excellent scripting language for the web. Because PHP is directly compiled (or loaded as a DSO module) into the web server binary, it doesn't suffer from the performance hits of forking and executing a separate command interpreter. PHP also has built-in support for accessing many kinds of databases, such as MySQL. If MySQL is not installed in a typical location (such as /usr/local), pass the location to the configure command with the --with-mysql=/usr/local/mysql argument.

The php.ini file provides some global defaults for the way PHP behaves. This file can be edited later to change PHP options.

$ cd php-4.0.5
$ ./configure --with-mysql=/usr/local/mysql --with-apache=../apache_1.3.14 --enable-track-vars
$ make
$ make install
$ cp php.ini-dist /usr/local/lib/php.ini
$ cd ..

mod_perl is another module which is frequently added to Apache. mod_perl allows Perl code to be run by the web server without having to fork and exec an external interpreter, thereby eliminating the performance hits commonly associated with perl CGI scripts.

$ cd mod_perl-1.22
$ perl Makefile.PL \
?   APACHE_SRC=../apache_1.3.14/src \
?   DO_HTTPD=1 \
?   USE_APACI=1 \
?   PREP_HTTPD=1 \
?   EVERYTHING=1
$ make
$ make test
$ make install
$ cd ..

This builds and prepares the mod_perl source for inclusion into the Apache source tree. The DO_HTTPD option forces mod_perl to only update the source tree specified in APACHE_SRC parameter. The USE_ACAPI option is the key to building mod_perl in this kind of hybrid environment. (The default is for mod_perl to build Apache from within the mod_perl directory, which eliminates the ability to add additional modules and customizations to Apache). The PREP_HTTPD option tells mod_perl to only prep the perl module tree inside of Apache, rather than automatically building it. The perl module will be built later when the actual web server is built.

Compiling Apache

Finally, we get to the point where we can build our actual Apache binary. I like to use the config.status file to assist in configuring Apache. This file is automatically generated by the configure script each time it is run. Basically, it keeps a record of what options were used to build the web server. However, it provides a nice means of maintaining and updating the build configuration throughout additional module installs by simply updating this shell script, rather than re-running configure on the command line with new options each time. It makes things much easier to call a single shell script to build Apache rather than have a command line that grows too large. The config.status file we use to build Apache in this example is available here.

The config.status script first declares few environment variables to help configure find the location of needed libraries and headers. Some operating systems, such as Red Hat Linux may already include the MM and OpenSSL libraries. In cases such as this, simply change the environment variables as follows:

EAPI_MM=SYSTEM
SSL_BASE=SYSTEM

Next, we tell Apache that we wish to use the GNU-style directory tree with the root directory of Apache at /usr/local/apache. Inspect the config.layout file in the root of the Apache distribution for details on the various directory layouts available.

The next two lines tell Apache that we want to enable the rewrite and ssl modules. The rewrite module is a very powerful addition to Apache which allows the administrator to perform complex address and URL rewriting tasks. The next line, "--enable-rule=SSL_SDBM", tells mod_ssl to use its built-in SDBM library rather than the DBM available with the operating system. This step is extremely important on Slackware Linux boxes, particularly those under version 4.0. The DBM included in early Slackware releases caused numerous segmentation faults with mod_ssl when serving SSL enabled pages. This may have been fixed in later Slackware releases, but it still a good idea to use the SDBM library included with mod_ssl.

The final two lines of the config.status file tell Apache to build and activate the mod_perl and PHP4 modules. Without these lines those additional modules will not be built into the web server, even if they were earlier applied to the source tree.

Once the configuration step is complete, build the web server and install it. Optionally, use make certificate to build and install a dummy certificate for testing SSL. For more information on generating certificates for use with mod_ssl, please see this document, which includes step-by-step instructions on manually installing your own SSL certificate (negating the need to run make certificate).

$ cd apache_1.3.14
$ ./config.status
$ make
$ make certificate
$ make install

Configuring Apache

A few changes are still necessary at this point in order to fully take advantage of PHP. Add the following to Apache's httpd.conf file to allow the web server to recognize PHP files. Prior to PHP4, the standard for naming PHP files was .php3. The following lines will associate .php (the proper extension for PHP4) and .php3 (still very commonly used) with the PHP4 handler.

# Enable PHP4 support
AddType application/x-httpd-php .php
AddType application/x-httpd-php .php3
AddType application/x-httpd-php-source .phps

At this point, it may be a good idea to add index.php and index.php3 to your DirectoryIndex directive to allow PHP files to be used as a default directory index.

Starting Apache

Now that the web server has been built and configured, it is time to start it up and test its functionality. There are two ways to start Apache, by calling the httpd executable directly, or by using apachectl, a shell script front end which simplifies common administrative tasks.

To start Apache manually, issue the following command as root:

$ /usr/local/apache/sbin/httpd

$ /usr/local/apache/sbin/httpd -DSSL

$ /usr/local/apache/sbin/apachectl start

$ /usr/local/apache/sbin/apachectl startssl