TechNote (Archived)

JRun 4.0: Building the Apache Connector for JRun4 and ColdFusion MX

There are times when it may be necessary to recompile the Apache connector for a specific hardware platform or operating system. The wsconfig.jar file now includes a file called ApacheModule.zip, which contains the source code and instructions for rebuilding the connector. For convenience, those instructions are reprinted in this article.

===========================================================
JRun Apache connector build for ColdFusion MX and JRun4
===========================================================

The connector source works with ColdFusion MX Updater 3 or higher,
ColdFusion MX 6.1 or higher, (and JRun4 SP1 or higher if JRun4 user).
Connectors compiled from this version will not work with prior versions of
either of these products.

==============================================================
Building from source is required for Apache 1.3.x in the following conditions
==============================================================

1) The Apache 1.3.x version is a mod_ssl or derivative or Apache StrongHold.
2) EAPI warning messages appear on startup similar to this:
[warn] Loaded DSO /opt/coldfusionmx/runtime/lib/wsconfig/1/mod_jrun.so uses
plain Apache 1.3 API, this module might crash under EAPI!
(please recompile it with -DEAPI).

There are no changes in the build steps regardless of Apache configuration.

The apxs utility can intelligently detect what type of Apache installation
and what switches are needed (-DEAPI) to build the connector correctly
without user intervention.

==============================================================
Instructions for building an Apache connector from source files
==============================================================

=====================
Terms and Definitions
=====================
Environment variables:

CFMX_CONNECTOR = the ColdFusion web server connector directory (ColdFusion MX users)
e.g. /opt/coldfusionmx/runtime/lib/wsconfig/1
or /opt/coldfusionmx/runtime/lib/wsconfig/2 if a second web server is configured

JRUN_CONNECTOR = the JRun4 Sp1 web server connector directory (JRun4 users).
e.g. /opt/jrun4/runtime/lib/wsconfig/1
or /opt/jrun4/runtime/lib/wsconfig/2 if a second web server is configured

APACHE_BIN = the Apache binaries directory.
e.g. /usr/sbin or /opt/apache/bin

NOTE: It is assumed that an Apache connector is already configured on the system
which will be replaced by the newly built connector.

==============
Detailed steps
==============

(Replace CFMX_CONNECTOR location with JRUN_CONNECTOR location where appropriate below for JRun4 users)

1.) Stop Apache (it is not necessary to stop ColdFusion MX or JRun)

2.) Place the ApacheModule.zip file in the CFMX_CONNECTOR directory and
use the unzip utility to extract the source files here.

unzip -a ApacheModule.zip
chmod 777 *

3.) Rename or delete the existing mod_jrun.so (Apache 1.3.x) or mod_jrun20.so (Apache 2.0.x) file.

4.) Use the Apache apxs utility to build the JRun connector from the source files:

Apache 1.3.x -

${APACHE_BIN}/apxs -c -Wc,-w -DJRUN_SSL mod_jrun.c \
jrun_maptable_impl.c jrun_property.c jrun_session.c \
platform.c jrun_mutex.c jrun_proxy.c jrun_ssl.c

strip mod_jrun.so

Apache 2.0.x -

${APACHE_BIN}/apxs -c -Wc,-w -n jrun20 -S LIBEXECDIR=${CFMX_CONNECTOR} mod_jrun20.c \
jrun_maptable_impl.c jrun_property.c jrun_session.c platform.c \
jrun_mutex.c jrun_proxy.c jrun_ssl.c

${APACHE_BIN}/apxs -i -n jrun20 -S LIBEXECDIR=${CFMX_CONNECTOR} mod_jrun20.la

strip mod_jrun20.so

5.) Restart Apache and check the Apache logs/error_log file.

6.) Delete the source files from the CFMX_CONNECTOR/JRUN_CONNECTOR directory when you have finished building the connector.

rm *.h *.c *.o *.lo *.slo *.la *.rc *.rc2

This procedure will need to be repeated after each ColdFusion MX/JRun4 Updater is installed since ColdFusion MX/JRun4 updaters automatically install updated connectors from the wsconfig.jar file for all installed web server connectors overwriting the user-compiled mod_jrun.so or mod_jrun20.so.

The wsconfig.jar binaries are standard modules.
Apache EAPI versions are not built automatically in wsconfig.jar.

==================================
Explanation of switches & options
=================================

unzip options:

-a convert source (text) files line endings as appropriate for platform

apxs options:

-c compile an Apache module

-i install an Apache module

-Wc,-w compiler switch to supress warnings

-DJRUN_SSL define the JRUN_SSL symbol
(note that this refers to SSL between the connector
and JRun, not to Web Server SSL on port 443)

-n jrun20 module name is jrun20

-S LIBEXECDIR=${CFMX_CONNECTOR} create mod_jrun20.so in the current directory

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Versions tested
===============
OK - Linux Redhat 7.2 Apache 2.0.43
OK - Linux Redhat 7.2 Apache 1.3.27
OK - Linux Redhat 7.2 Apache 1.3.27 with mod_ssl ( EAPI build )
OK - Linux Redhat 9.0 Apache 2.0.40
OK - Solaris 8 Apache 1.3.27
OK - Solaris 8 Apache 2.0.44

Note: be sure to set the PATH environment variable as required by your C compiler

FAILED - Solaris 8 Apache 2.0.43 - did not build (mod_jrun20.la incorrect values - apxs error?).
A working mod_jrun20.so can still be built by using the following command in place of the 'apxs -i' command:

ld -G -o mod_jrun20.so mod_jrun20.o \
jrun_maptable_impl.o jrun_property.o \
jrun_session.o jrun_mutex.o jrun_proxy.o \
platform.o jrun_ssl.o