JBoss.orgCommunity Documentation
The following are the steps to set up a minimal working installation of mod_cluster on a single httpd server and a single back end server, either JBoss AS, JBossWeb or Tomcat. The steps can be repeated to add as many httpd servers or back end servers to your cluster as is desired.
The steps shown here are not intended to demonstrate how to set up a production install of mod_cluster; for example using SSL to secure access to the httpd-side mod_manager component is not covered. See the httpd-side and java-side configuration documentation for the full set of configuration options.
Download the latest httpd and java release bundles. If there is no pre-built httpd bundle appropriate for your OS or system architecture, you can build the binary from source.
The httpd-side bundles are gzipped tars and include a full httpd install. As they contain already an Apache httpd install you don't need to download Apache httpd. Just extract them in root, e.g.
cd / tar xvf mod-cluster-1.0.0-linux2-x86-ssl.tar.gz
That will give you a full httpd install in your /opt/jboss directory.
If you already have a working httpd install that you would prefer to use, you'll need to download the bundle named mod_cluster httpd dynamic libraries corresponding to you plaform, extract the modules and copy them directory to your httpd install's module directory.
cd /tmp tar xvf mod_cluster-1.0.0.CR2-linux2-x86-so.tar.gz
And then you have to copy the files below to you module directory:
* mod_proxy.so
* mod_proxy_ajp.so
* mod_slotmem.so
* mod_manager.so
* mod_proxy_cluster.so
* mod_advertise.so
Since 1.1.0.CR2 a script opt/jboss/httpd/sbin/installhome.sh allows reconfiguration of the bundle installation so that it can run in user's home directory. To do that just extract the bundle in your home directory and run the script. Once that done, httpd will run on port 8000 and will accept MCMP messages on localhost:6666 and offer /mod_cluster_manager on the same host and port.
To install in windows unzip the bundle corresponding to your architecture. You may run httpd directly by using:
httpd-2.2\bin\httpd.exe -k start
or install Apache httpd as a service:
httpd-2.2\bin\httpd.exe -k install
and start the service:
net start Apache2.2
Note that in the windows bundles have a flat directory structure, so you have httpd-2.2/modules/ instead of opt/jboss/httpd/lib/httpd/modules.
Since 1.1.0.CR2 httpd.conf is preconfigured with the Quick Start values. You should adapt the default values to your configuration with older mod_cluster we will have to add the following to httpd.conf. If you extracted the download bundle to root as shown above and are using that extract as your httpd install, httpd.conf is located in /opt/jboss/httpd/httpd/conf.
LoadModule proxy_module /opt/jboss/httpd/lib/httpd/modules/mod_proxy.so
LoadModule proxy_ajp_module /opt/jboss/httpd/lib/httpd/modules/mod_proxy_ajp.so
LoadModule slotmem_module /opt/jboss/httpd/lib/httpd/modules/mod_slotmem.so
LoadModule manager_module /opt/jboss/httpd/lib/httpd/modules/mod_manager.so
LoadModule proxy_cluster_module /opt/jboss/httpd/lib/httpd/modules/mod_proxy_cluster.so
LoadModule advertise_module /opt/jboss/httpd/lib/httpd/modules/mod_advertise.so
Listen 10.33.144.3:6666
<VirtualHost 10.33.144.3:6666>
<Directory />
Order deny,allow
Deny from all
Allow from 10.33.144.
</Directory>
KeepAliveTimeout 60
MaxKeepAliveRequests 0
ManagerBalancerName mycluster
AdvertiseFrequency 5
</VirtualHost>If you are using your own install of httpd, httpd.conf is found in your install's conf directory. The content to add to httpd.conf is slightly different from the above (different path to the various .so files):
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
LoadModule slotmem_module modules/mod_slotmem.so
LoadModule manager_module modules/mod_manager.so
LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
LoadModule advertise_module modules/mod_advertise.so
Listen 10.33.144.3:6666
<VirtualHost 10.33.144.3:6666>
<Directory />
Order deny,allow
Deny from all
Allow from 10.33.144.
</Directory>
KeepAliveTimeout 60
MaxKeepAliveRequests 0
ManagerBalancerName mycluster
AdvertiseFrequency 5
</VirtualHost>First, extract the java-side binary to a temporary directory. The following assumes it was extracted to /tmp/mod-cluster
Your next step depends on whether your target server is JBoss AS or JBossWeb/Tomcat.
You don't need to do anything to install the java-side binaries in AS 6.x; it's part of the AS distribution's default, standard and all configurations.
Assuming $JBOSS_HOME indicates the root of your JBoss AS install and that you want to use mod_cluster in the AS's all config:
cp -r /tmp/mod-cluster/mod-cluster.sar $JBOSS_HOME/server/all/deploy
Assuming $CATALINA_HOME indicates the root of your JBossWeb or Tomcat install:
cp -r /tmp/mod-cluster/JBossWeb-Tomcat/lib/*
$CATALINA_HOME/lib/ mod_cluster is integrated into your web server by adding an implementation of the Tomcat LifecycleListener interface to the server's configuration, and by giving each node a unique name.
Edit the $JBOSS_HOME/server/all/deploy/jbossweb.sar/server.xml file, adding the following next to the other Listener elements:
<Listener
className="org.jboss.web.tomcat.service.deployers.MicrocontainerIntegrationLifecycleListener"
delegateBeanName="ModClusterService"/> Edit the $JBOSS_HOME/server/all/deploy/jbossweb.sar/META-INF/jboss-beans.xml file, adding the following next to the other depends elements:
<depends>ModClusterService</depends> Edit the $CATALINA_HOME/conf/server.xml file, adding the following next to the other Listener elements:
<Listener
className="org.jboss.modcluster.ModClusterListener"
advertise="true"/> Edit the $JBOSS_HOME/server/all/deploy/jboss-web.deployer/server.xml file, adding the following next to the other Listener elements:
<Listener
className="org.jboss.modcluster.ModClusterListener"
advertise="true"/> Each back end server in your cluster needs to have a unique name, known as a "jvmRoute". This is configured by adding an attribute to the Engine element in server.xml.
<Engine name="jboss.web" defaultHost="localhost"
jvmRoute="node01"> If your cluster includes multiple back-end servers, you must assign a different jvmRoute to each server.
Beginning with the 1.1.0.BETA1 release, configuring a jvmRoute is no longer absolutely required; if one isn't provided mod_cluster will generate one from the address and port of the Connector used for receiving requests, plus the name of the Tomcat Engine. Still, configuring a jvmRoute is recommended, since the jvmRoute is appended to all session ids. The generated jvmRoute is lengthy and includes information you may not want to expose to the internet via session ids.
Repeat the back end server install and configuration steps; just be sure to use a different jvmRoute for each server.
The load balancing demo application is a good way to learn about mod_cluster's capabilities.