Building mod_jk.so

The mod_jk.so library is a dynamically loaded module that Apache uses to recognize JSP, Servlet, or XML (using Cocoon) requests that need to be handled by Tomcat. The communitation between Apache and Tomcat is coordinated by mod_jk over TCPIP port 8007.

IMPORTANT NOTE: This process has been causing people a lot of problems. If you have my new Tomcat+Cocoon-2.pkg, I've automated this entire process. (You don't actually have to install the package, but I've hidden all the needed source code in it. If you installed my original Tomcat+Cocoon package, DON'T bother installing the new package, just download it.)

Getting the required components

Building mod_jk.so should be simple, but has been complicated by two annoying oversights.

In their infinite wisdom, Apple left out some semi-common Unix functions covered in the dlfcn.h header. What's really amusing is that you can type "man dlfcn.h" in a terminal window and get descriptions of the missing functions. Fortunately, Christoph Pfisterer put together a download that adds the missing functions. Unpack the package. You'll only need two files: dlfcn.h and dlopen.c.
The current "stable" release of Tomcat is missing the source files for mod_jk. Therefore, I suggest unpacking the most recent version of Tomcat 3.3. This may sound questionable, but mod_jk is actually run by Apache, not Tomcat, so mixing versions like this isn't as bad as you might think. Go to the Jakarta Tomcat web site and download the most recent milestone Tomcat 3.3 source release. As I write this, the most recent release can be found here.

Compiling mod_jk.so

Okay, now to build the module. Unpack the Tomcat 3.3. source in some temporary location. (Your home directory is just fine.) Copy the two files dlfcn.h and dlopen.c into the jakarta-tomcat/src/native/mod_jk/apache1.3 directory. Now execute the following command:

/usr/sbin/apxs -o mod_jk.so -I../common -I/System/Library/Frameworks/JavaVM.framework/Headers -I. -DFREEBSD -c mod_jk.c dlopen.c ../common/*.c

(errata: earlier I'd left the "dlopen.c" part out of that command. Oops! Thanks to all the reader feedback!)

Now, if you've got Apache 2.x, you will want to be in the apache2.0 directory instead of apache1.3. I suspect the above command will need some modification. PLEASE, if anyone gets this going with 2.0, drop me a note so I can post the proper instructions. A hint: I think there will be a directory in the Apache 2.0 tree called /something/include/apr-util. You will want to include a "-I/something/include/apr-util" to the above command.

Installing the module

You should now have mod_jk.so in your current directory. Copy it to the /usr/libexec/http directory. You should check to make sure that there's still a symlink of /usr/libexec/mod_jk.so pointing to /usr/libexec/httpd/mod_jk.so. If you installed my Tomcat+Cocoon package, it (the symlink) should already be there.

Was that Greek to you? For those of you who are new to Unix, go to the /usr/libexec directory and get a detailed directory listing with "ls -l". You should see a line that looks like:

lrwxr-xr-x 1 root wheel 28 Apr 13 21:07 mod_jk.so -> /usr/libexec/httpd/mod_jk.so

You see, due to another minor annoyance, Tomcat insists that mod_jk.so be placed in /usr/libexec instead of where it belongs in /usr/libexec/http. Therefore, we create a symlink or "shortcut" for mod_jk.so where Tomcat expects to find it. You can do this with the command:

ln -sf /usr/libexec/httpd/mod_jk.so /usr/libexec/mod_jk.so

In case of problems...

Few things would be worse than trying to add something cool to Apache and suddenly discovering that the entire Web Server has stopped working. Fortunately, you can fix Apache so it doesn't try to run mod_jk.so by removing the files "mod_jk.conf" and "xml.conf" from the directory /private/etc/httpd/users. Tomcat should still run fine (you can browse to it by changing http://youraddress to http:/youraddress:8080).

Best of luck!

Back to Murray's Tomcat and Cocoon Page