Using Apache to Load Balance Across Several Ephesoft UI Tomcat Servers

KB Articles

KB Article # 8944

Topic/Category: Installation, Clustering, Load Balancing

Ephesoft Version: ALL

Issue: Using Apache to Load Balance Across Several Ephesoft UI Tomcat Servers


Ephesoft will cluster processing of batches automatically.

If you want to secure your ephesoft servers behind the DMZ and spread the UI load across several Ephesoft UI Servers while your users access one URL to Ephesoft, you would want to setup Apache to Load Balance Across Several Ephesoft Tomcat Servers.


Step 1 – Install Tomcat instances and Apache HTTPD on a Server in DMZ

If you haven’t already installed them, the first thing to do is to download and install the latest stable versions of Apache Tomcat 6.x and Apache HTTPD. You can find the latest stable versions on the Apache HTTPD and Tomcat project sites.

For the purposes of this tutorial, we’ll assume that you understand how to install these components.

Step 2 – Download and install mod_jk

mod_jk is the Apache HTTPD module that will be used to provide our cluster with its load balancing and proxy capabilities. It uses the AJP protocol to facilitate fast communication between Tomcat servers and the Apache Web Server that will receive the client requests.

The mod_jk module is distributed separately from Apache HTTPD as part of the Tomcat project. Binary distributions of the module are available for most major platforms, and can be downloaded here. If the version and platform you are looking for is not yet available as a binary distribution, you can build the appropriate version from the source.

Once you have either downloaded and unzipped or built the module, place it in the ‘modules’ directory of your Apache HTTPD server.

Step 3 – Configure mod_jk

Next, we’ll have to set up the mod_jk module in Apache HTTPD’s configuration files. This configuration is a two step process, and can be a little confusing, as mod_jk does not separate its proxy capabilities from its load balancing capabilities.

First, let’s configure the module itself. This is done by adding a few lines to the main Apache HTTPD configuration file, apache\conf\httpd.conf. Take a look at this example configuration (we’ll explain what each attribute does in a second):

LoadModule jk_module modules/
JkWorkersFile conf/
JkLogLevel info
#JkShmFile logs/mod_jk.shm
JkLogFile logs/mod_jk.log
JkMount /* balancer

JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories +ForwardSSLCertChain
JkRequestLogFormat "%w %V %T"
# Should mod_jk send SSL information to Tomcat (default is On) 
JkExtractSSL On 
# What is the indicator for SSL (default is HTTPS) 
# What is the indicator for SSL session (default is SSL_SESSION_ID) 
# What is the indicator for client SSL cipher suit (default is SSL_CIPHER) 
# What is the indicator for the client SSL certificated (default is SSL_CLIENT_CERT) 

# When using mod_jk with Apache & mod_ssl, it is essential to specify "SSLOptions +StdEnvVars +ExportCertData" in the httpd.conf file. 
SSLOptions +StdEnvVars +ExportCertData

<Location /jkmanager/>
 JkMount jkstatus
 Order deny,allow
 Deny from all
 Allow from

Here’s a quick explanation of the parameters we just configured.

  • LoadModule – this command makes the mod_jk module available for use. The extension of the module itself will vary by operating system.
  • JkWorkersFile – sets the path to the worker configuration file, which we will create in the next step.
  • JkShmFile – sets the path to the shared memory files for the module. Generally, you’ll want to keep this with the logs.
  • JkLogFile – sets the path to the module log file.
  • JkLogLevel – sets the level of logging for the module. The valid values for this attribute, in descending order by verbosity, are “debug”, “error” or “info”.
  • JkMount – this is used to map a certain URL pattern to a specific worker configured in the worker configuration file. Here, we use it twice – once to enable /jkmanager as the access URL for jkstatus, a virtual monitoring worker, and once to map all requests we want to be handled by the cluster to the “lb” worker, a virtual worker that contains the load balancing capability
  • Location – this is a security constraint. The settings we have included allow access to the jkmanager only from the localhost (this is a Good Idea).

Step 4 – Configure the cluster workers

Now that we’ve configured the main settings, we will configure the workers. “Workers” is a blanket term used within mod_jk to refer to both real Tomcat servers that will process requests, and virtual servers included in the module to handle load balancing and monitoring. In other words, rather than creating a separate apparatus to manage load balancing, mod_jk simply loads an additional virtual worker with load balancing functionality. If this seems confusing to you, you’re not alone – this is one area where mod_jk shows its age compared to mod_proxy, which keeps all of its configuration in the main httpd.conf file, and doesn’t use the concept of virtual workers.

Here’s a (very) basic apache\conf\ configuration example (see below for an explanation of the configuration directives):

#Create a list of tomcat servers
#Initialize with Tomcat Server 1 configuration
#Initialize with Tomcat Server 2 configuration

#Set the balance type and the servers to be used

worker.balancer.balance_workers=worker1, worker2


Note: Sticky sessions must be enabled.

Step 5 – Configure the Ephesoft cluster workers

For each server:

Edit Ephesoft >> Application >> WEB-INF >> classes >> META-INF >> dcma-batch >>

  1. Look for the line batch.base_http_url=http\://computername\:8080/dcma-batches
    Change the computername to the apache server resolvable dns name or ip address
  2. Remove the port number part “\:8080″, save the file.


Edit Ephesoft >> JavaAppServer >> conf  >> server.xml

  1. Look for the line 

     <Engine name="Catalina" defaultHost="localhost" jvmRoute="worker1">

    Change <worker1> to match the correct worker number defined in

Step 6 – Start Apache and Ephesoft Tomcat Servers

* You may check the status of load balancing by going to on the apache server

< Back|KB Main Page | Next KB Article >