Build Your Own Apache Server with mod_perl

by David Wheeler

Editor's note: be sure to see David Wheeler's update to this article, Installing libapreq on Jaguar: An Update.

When Apple released Mac OS X, it included as part of the operating system one of the most powerful and most-used applications on the Internet today: the Apache Web server. This has been a boon for Mac users and dedicated Unix jocks alike, as the combination of Apache's simplicity and power and the legendary Mac OS ease-of-use has made for a robust Internet application development platform. Largely due to the inclusion of Apache, along with a host of other necessary Unix power tools, Mac OS X has rapidly become the Unix developer's platform of choice.

And lest anyone be concerned, the Apache that ships with Mac OS X is the genuine article. We're not talking about a weak, proof-of-concept port of Apache that runs under Windows. Mac OS X's FreeBSD underpinnings allow for the Apache Web server to be as flexible and responsive as it is on any Unix-based operating system. See Kevin Hemenway's Apache Web-Serving with Mac OS X series for a comprehensive overview of those features and how to take advantage of them under Mac OS X.

However, the version of Apache included with Mac OS X is arguably unsatisfactory in a number of ways. If you're like me and plan to do some serious mod_perl-based Web development work on Mac OS X, you'll need to take the following issues into consideration as you begin working with Apple's Apache install:

Related Reading

Apache: The Definitive Guide
By Ben Laurie, Peter Laurie

For those whose Web serving needs have exceeded the capabilities of the Apple-supplied Apache, and for those who need to develop scalable Web applications built on Perl 5.8.0, mod_perl, and Apache::Requst & Apache::Cookie, an important alternative exists: you can build your own Apache Web server on Mac OS X. In this article, I guide you through the steps necessary to build your own Apache server with mod_perl.


Compiling your own applications means that you need a compiler. Apple kindly offers one with the Mac OS X Developer tools. You'll need to grab them from Apple's developer site (free registration) and install them.

If we're to install Apache with mod_perl, the first thing we need to do is install the latest version of Perl. Fortunately, Apple has provided the aforementioned instructions for downloading and compiling Perl 5.8.0. Although that article documents compiling Perl 5.8.0 on Jaguar, it should work reasonably well on Mac OS X 10.1.x, as well.

Next, we'll need to download and patch the latest Apache 1.3 and mod_perl 1.x sources. You can find the Apache sources on the Apache HTTP server Source Code Distributions page, or at your nearest mirror. As I write this, the latest version is 1.3.26, so that's what I'll use in the remainder of this article. The latest version of mod_perl is available from the mod_perl distribution page.

% cd /usr/local/src
% curl -O
% tar zxvf apache_1.3.26.tar.gz
% curl -O
% tar zxvf mod_perl-1.0-current.tar.gz

Following Apple's example, I move into the /usr/local/src directory and do all of the work there. I've used the handy curl utility to download the Apache and mod_perl sources right in my Terminal session. I then used the tar program to unpack the sources. The Apache sources will now be in the directory apache_1.3.26/, while the mod_perl sources will be in the directory mod_perl-1.xx/ As of this writing, the current version of mod_perl is 1.27, so I'll be working in the mod_perl-1.27/ directory in the examples below.

As I mentioned before, the mod_perl Apache::Request and Apache::Cookie modules--part of the apreq library--have not yet been ported to Mac OS X. However, as a workaround, the apreq developers have put together a patch to compile the C interface to apreq right into Apache. This approach circumvents the issues with the regular apreq library, allowing Apache::Request and Apache::Cookie to work perfectly well on Mac OS X.

% curl -O
% curl -O
% cd apache_1.3.26
% patch -p0 < ../apreq.patch

Once again, I use curl to download the files I need, in this case the apreq sources and the apreq patch to Apache. I then move into the apache source code directory and use the patch program to patch the Apache sources. What this means is that patch takes the contents of the apreq.patch file and uses them to change the existing Apache source files to directly support apreq.


Now we're ready to start building the software. At this point, you should have downloaded, compiled, and installed Perl as per the instructions from Apple (with the source code still living in /usr/local/src/perl-5.8.0), and followed the steps outlined above. Next we'll build mod_perl.

Like most source code installations, mod_perl offers a good number of configuration options. A quick perusal of the installation guide reveals all. However, I'm going to recommend a relatively straightforward configuration that includes support for all of the mod_perl features you're likely to need, while allowing the flexibility to build other Apache modules into Apache later on. Here it is:

% cd ../mod_perl-1.27
% perl Makefile.PL \
  APACHE_SRC=../apache_1.3.26/src \
  NO_HTTPD=1 \

The perl script Makefile.PL creates the Makefile that will be used to compile mod_perl. The APACHE_SRC option tells Makefile.PL where to find the Apache sources. The NO_HTTPD option, meanwhile, forces the build process to use this path but keeps it from compiling Apache before we're ready. The USE_APACI option is what allows that flexibility as it enables mod_perl's "hybrid build environment," wherein we can later compile other modules into Apache. Meanwhile, the PREP_HTTPD option triggers the build process to set up the Apache sources for mod_perl by preparing the APACHE_SRC/modules/perl/ directory tree. But we save the most important option for last. The EVERYTHING option enables all of mod_perl's features.

When this command runs, you'll be prompted to confirm to configure mod_perl with the APACHE_SRC sources. Do so by simply hitting the return key. At this point, mod_perl's configuration will quickly take care of all of its tasks without further intervention.

Next we'll build and install mod_perl. Fortunately, the tricky part is over. All we need to do is this:

% make
% sudo make install

These two steps build mod_perl and install it. But before we can take advantage of the newly installed mod_perl, we need to configure and build Apache.

% cd ../apache_1.3.26
% ./configure \
    --with-layout=Apache \
    --enable-module=so \
    --activate-module=src/modules/perl/libperl.a \
    --disable-shared=perl \

Once again the configuration is the most complex part of the process. The --with-layout=Apache option sets up Apache to be installed with its usual file system layout (i.e., in the /usr/local/apache directory). The --enable-module=so option enables dynamically loadable library support, should you decide later to build and use any third party modules as dynamically loadable objects. The --activate-module=src/modules/perl/libperl.a option activates mod_perl, while --disable-shared=perl option forces Apache to compile in mod_perl statically, rather than as a dynamically loadable library. And finally, the --without-execstrip option is required on Mac OS X to prevent the Apache binary from being stripped (whatever that means).

After configure does its job, we compile and install Apache with the usual commands:

% make
% sudo make install

The final step in this process is to compile the apreq libarary. Although the apreq patch added statically compiled support for apreq directly into the Apache binary, we still need to build and install the Perl modules that will allow us to take advantage of it. Fortunately, this last step is easy, as it follows the usual approach for installing Perl modules:

% tar zxvf apreq.tar.gz
% cd httpd-apreq
% perl Makefile.PL
% make
% sudo make install

Testing Your New Apache Build

And now Apache is completely compiled and installed with mod_perl. A quick test confirms that the installation was successful:

% sudo /usr/local/apache/bin/apachectl configtest
Syntax OK

This quick test confirms that Apache compiled properly and loads its default configuration file without error. But it's more interesting to actually get it to serve some Web pages. First, make sure that Apple's version of Apache isn't running by disabling Personal Web Sharing in the Sharing global system preference. Then start up your newly compiled version of Apache:

% sudo /usr/local/apache/bin/apachectl start
/usr/local/apache/bin/apachectl start: httpd started

Now fire up your favorite browser, and type in your Mac's domain name. Localhost will probably work fine. If you see a page that starts with, "Hey, it worked!", then you're in business.

Testing mod_perl

As the final part of this process, we confirm to ourselves for the sake of our own sanity, that mod_perl is functioning properly, too. Fortunately this is rather simple to do as mod_perl includes a module we can easily use for this purpose. The Apache::Status module is designed to display information about the status of your Apache Web server, as well as mod_perl itself. To use it, simply edit the default Apache configuration file, /usr/local/apache/conf/httpd.conf, and add these lines to it:

PerlModule Apache::Status
<Location /perl-status>
  SetHandler  perl-script
  PerlHandler Apache::Status

Restart Apache so that it loads the new module:

% sudo /usr/local/apache/bin/apachectl restart
/usr/local/apache/bin/apachectl restart: httpd restarted

Now hit your Web server again, this time entering the "perl-status" directory name, e.g, http://localhost/perl-status/. You should see a page appear with something like this at the top:

Embedded Perl version v5.8.0 for Apache/1.3.26 (Darwin) mod_perl/1.27 process 12365,
running since Thu Sep 19 01:05:43 2002

Apache Startup Bundle

Having a working Apache is all well and good but not worth much unless it's running. If you'd like your Mac OS X box to function as a Web server all the time, you might want to create a startup bundle for it. Apple has documented a specification for startup bundles in its Creating SystemStarter Startup Item Bundles HOWTO, but it's a simple matter to adapt Mac OS X's existing Apache startup bundle for our purposes.

Apple has created the /System/Library directory structure for use by the Mac OS X operating system, and the /Library directory structure for use by third party applications such as our new Apache server. All system startup bundles, including for Apple's build of Apache, go into the /System/Library/StartupItems directory. The startup bundles for third-party applications go into the /Library/StartupItems directory. So to adapt Apple's Apache startup bundle, we'll first copy it to a temporary location. Later, we'll move the copy to its new home:

% cp -rf /System/Library/StartupItems/Apache \

This command will copy the entire Apache startup bundle directory structure to the desktop where we can easily edit it. Next, using your favorite editor (TextEdit will work fine), open up the ~/Desktop/Apache/Apache file. The parts we're interested in look like this:

StartService ()
    if [ "${WEBSERVER:=-NO-}" = "-YES-" ]; then
        ConsoleMessage "Starting Apache web server"
        apachectl start

StopService ()
    ConsoleMessage "Stopping Apache web server"
    apachectl stop

RestartService ()
    if [ "${WEBSERVER:=-NO-}" = "-YES-" ]; then
        ConsoleMessage "Restarting Apache web server"
        apachectl restart

This file is a Unix Bourne shell script and is executed whenever your Mac starts up and shuts down. There are essentially two changes we need to make to convert this script for starting our newly compiled Apache server. The first is to remove all of the if statements. These statements programmatically test for a variable that gets set by the Personal Web Sharing check box in the Sharing system preference. Since our server won't handle Personal Web Sharing, we won't be needing these tests. The second change we need to make is to change the location of the apachectl startup script. Just calling apachectl will cause Apple's Apache server to start up. To get our new one to start, we need to change the location to /usr/local/apache/bin/apachectl. The result of our changes to the startup script looks like this:

StartService ()
    ConsoleMessage "Starting Apache web server"
    /usr/local/apache/bin/apachectl start

StopService ()
    ConsoleMessage "Stopping Apache web server"
    /usr/local/apache/bin/apachectl stop

RestartService ()
    ConsoleMessage "Restarting Apache web server"
    /usr/local/apache/bin/apachectl restart

Now all that's left is to move the entire startup bundle to its new home in /Library/StartupItems and test it:

% sudo mv ~/Desktop/Apache /Library/StartupItems
% sudo /Library/StartupItems/Apache/Apache start
Starting Apache web server
/usr/local/apache/bin/apachectl start: httpd started

Point your browser to your local computer again and make sure a page loads. If it does, you're in business, and the Apache server will be started whenever you boot into Mac OS X.

Next Up: mod_ssl

I hope that this article has served as a gentle introduction to compiling your own Apache server on Mac OS X. However, as I've suggested, there's a great deal more you can do when building Apache.

In part two of this article, I'll go back over this process, assisting you to compile support for the mod_ssl Apache module. This module allows Apache to encrypt communications with browsers using SSL, the secure sockets layer. Any time you securely connect to a Web site, for example, to complete a credit card transaction at, your browser communicates with the server via SSL. If you find you need to develop Web applications that use SSL, tune in to part two of this article to learn how to add SSL support to your custom build of Apache.

David Wheeler is a developer at Portland, Oregon-based Values of n, where he writes the code that makes Stikkit's little yellow notes think.

Return to Mac DevCenter

Copyright © 2017 O'Reilly Media, Inc.