Song of The Day: Hyperpower! - Artist: NIN
So you want to add custom modules to Apache on OS X. Well, you’ve come to the right place. I just recently decided to do this and wrote a few notes on the experience. It still surprises me how tough it can be to come across a fairly simple write-up on something like this without touching at least a couple of manuals or READMEs. Hopefully, someone will find this useful. As an added benefit, although the entry is focused upon OS X, the instructions should work on most Unix and Unix-variant platforms.
Currently, OS X 10.4.9 comes stock with Apache httpd 1.3.33, so you’ll need the 1.3 source code to start. That may be downloaded here. The last I checked the build number of the released version of Apache 1.3 is 1.3.37. In the future I plan to document any Apache 2.0 vagaries during a custom module setup; however, today the entry addresses 1.3.x solely.
<Note>
Be careful to not overwrite your existing Apache /usr/sbin/httpd or shared modules. If you do not want to affect the existing installation, then back it up and/or use the appropriate configuration commands during Apache compilation. For example,
</Note>
To get things moving quickly, I first decided to get mod_example.so working, which comes with the Apache distribution. I did this by adding the following to the file [src base]/src/Configuration:
To build the module just invoke make, or if the configuration options are not preset:
02: ./configure --prefix=/usr/local/apache --enable-shared=example --enable-module=example
03: make
Now, if you want to run the module, you may add the mod_example functions to Apache’s configuration by editing the httpd.conf with the following:
02: # httpd.conf
03: #
04: LoadModule example_module libexec/httpd/mod_example.so
05: AddModule mod_example.c
06:
07: <IfModule mod_example.c>
08: <Location /example-info>
09: SetHandler example-handler
10: </Location>
11: </IfModule>
To ensure success hit the URL (e.g., http://localhost/example-info) and something like the following should display: mod_example output.
<Note>
If Apache isn’t set up, then you can build most of the modules as shared objects with the following configuration options as a part of the build directives to configure:
02: ./configure --prefix=/usr/local/apache --enable-shared=max --enable-module=most --enable-module=example
02: make
03: sudo make install
</Note>
With a lot of the build environment issues behind us, we are ready to start creating our own module. Probably the best way to get started is by copying the mod_example code into a new directory and to configure the build settings. For this entry I have decided to use the name mod_cpeek for the Apache module. Here are the commands under the Apache source directory that I used:
02: # Under something like ~/apache_1.3.37/src/modules
03: #
04: cd [src base]/src/modules
05: cp -r example cpeek
06: cd cpeek
07: rm mod_example.lo mod_example.so
08: mv mod_example.c mod_cpeek.c.bak
09: mv Makefile Makefile.bak
10: sed -e ’s/example/cpeek/g’ <./Makfile.bak >./Makefile
11: sed -e ’s/example_module/cpeek_module/g’ -e ’s/example-handler/cpeek-handler/’ -e ’s/example_handlers/cpeek_handlers/g’ -e ’s/example_handler/cpeek_handler/g’ <./mod_cpeek.c.bak >./mod_cpeek.c
The sed commands allow us to use a different module name and handler from the mod_example ones. These changes help to avoid name collision when exporting the cpeek module and help to identify the cpeek handler in configurations. We may also add the custom module to the build path of Apache 1.3 by editing the [src base]/src/Configuration.tmpl and adding the following:
Afterwards, we need to run [src base]/src/Configure to update the configuration and make files.
Once that is complete, we should be able to copy [src base]/src/modules/cpeek/mod_cpeek.so to our libexec directory of shared modules for Apache. If there is a problem at this stage it may be useful to run the following again to clear any misconfigurations:
02: # Under something like ~/apache_1.3.37
03: #
04: cd [src base]
05: ./configure --enable-shared=cpeek --enable-module=cpeek
Now, the custom shared module should be in the same shared module directory of the Apache installation (e.g., /usr/local/apache/libexec for Apache directory structure and layouts or under /usr/libexec/httpd for the default OS X location.
Add the following to the httpd.conf:
02: AddModule mod_cpeek.c
03: <IfModule mod_cpeek.c>
04: <Location /cpeek-info>
05: SetHandler cpeek-handler
06: </Location>
07: </IfModule>
If everything is compiled and configured correctly the new URL “/cpeek-info” should display the same results as the /example-info using the cpeek-handler and namespace.
Okay. That concludes the fun for today. Next time we’ll take the Apache API for a whirl.