This document describes how to set up Connect 1.1 on a simple JBoss cluster. Load-balancing was set up with sticky sessions, in which a each browser session is bound to a given node.
Environment Setup The tools listed below were used. -Java Platform Standard Edition Development Kit (JDK) 5.0 -Microsoft SQL Server 2000, Service Pack 4 -Apache HTTP Server 2.0.58 -JBoss Application Server 4.0.4 GA
Apache HTTP Server Installation Apache handles the load-balancing configuration for the cluster, and must be installed to take advantage of JBoss clustering. This should be done on at least one of the cluster’s nodes.
Step 1: Download and run the Apache HTTP Server 2.0.58 Windows Installer from
http://www.apache.org/dist/jakarta/tomcat-connectors/jk/binaries/ . Follow the instructions to find the stable version that matches your Apache installation. Rename the file to mod_jk.so, and copy it to the <APACHE_HOME>/modules directory.
Step 3: Create a file named mod-jk.conf in the <APACHE_HOME>/conf directory. The
file should read:
# Load mod_jk module # Specify the filename of the mod_jk lib LoadModule jk_module modules/mod_jk.so # Where to find workers.properties JkWorkersFile conf/workers.properties # Where to put jk logs JkLogFile logs/mod_jk.log
# Set the jk log level [debug/error/info] JkLogLevel info # Select the log format JkLogStampFormat "[%a %b %d %H:%M:%S %Y]" # JkOptions indicates to send SSK KEY SIZE JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories # JkRequestLogFormat JkRequestLogFormat "%w %V %T" # Mount your applications JkMount /connect/* loadbalancer # You can use external file for mount points. # It will be checked for updates each 60 seconds. # The format of the file is: /url=worker # /examples/*=loadbalancer # COMMENT NEXT LINE IF JkMountFile conf/uriworkermap.properties # Add shared memory. # This directive is present with 1.2.10 and # later versions of mod_jk, and is needed for # for load balancing to work properly JkShmFile logs/jk.shm # Add jkstatus for managing runtime data <Location /jkstatus/> JkMount status Order deny,allow Deny from all Allow from 127.0.0.1 </Location>
LoadModule should reference the location of mod_jk.so in your Apache install, and JkMount should list the URLs to forward to the load-balancer. For example, to load-balance all URLs, JkMount /* can be used. If you don’t want to add an external file for more complex forwarding, remove the JkMountFile line and skip Step 4.
Step 4: (optional) To further customize forwarding, create a file named
uriworkermap.properties in the <APACHE_HOME>/conf directory. The file could read:
# Simple worker configuration file # Mount the Servlet context to the ajp13 worker /jmx-console=loadbalancer /jmx-console/*=loadbalancer /web-console=loadbalancer /web-console/*=loadbalancer
That example would forward requests to the listed URLs to Tomcat.
Step 5: Create a file named workers.properties in the <APACHE_HOME>/conf directory.
The file should read:
# Define list of workers that will be used # for mapping requests worker.list=loadbalancer,status # Define Node1 # modify the host as your host IP or DNS name. worker.node1.port=8009 worker.node1.host=DR72N81.phys.misyshealthcare.com worker.node1.type=ajp13 worker.node1.lbfactor=1 worker.node1.cachesize=10 # Define Node2 # modify the host as your host IP or DNS name. worker.node2.port=8009 worker.node2.host= BR72N81.phys.misyshealthcare.com worker.node2.type=ajp13 worker.node2.lbfactor=1 worker.node2.cachesize=10 # Load-balancing behaviour worker.loadbalancer.type=lb worker.loadbalancer.balance_workers=node1,node2 worker.loadbalancer.sticky_session=1 #worker.list=loadbalancer # Status worker for managing load balancer worker.status.type=status
This would set up evenly-weighted round-robin load balancing with sticky sessions. Make sure to enter the correct host for each node. To add additional nodes, follow the example of first two, adding the new node’s name to the worker.loadbalancer.balance_workers line.
JBoss Application Server Installation Next, JBoss must be installed. Note that these steps must be taken on each node in the cluster.
Step 1: Run the installer for JBoss Application Server 4.0.4 from
http://labs.jboss.com/portal/jbossas/download/index.html . Be sure to run the installer, not to choose “Download.” This ensures you will download all the needed components into one “default” server directory, minimizing the customization needed. For simplicity, select the “all” configuration, select all the install packs
listed, and keep “default” as the config name. Do not enable deployment isolation/call by value, and leave the security options unchecked.
Step 2: Locate the file jboss-service.xml in <JBOSS_HOME>/server/default/deploy/tc5-
cluster.sar/META-INF . Change the <attribute name=”ClusterName”> property to Tomcat-Cluster .
Step 3: Locate the file server.xml in <JBOSS_HOME>/server/default/deploy/jbossweb-
tomcat55.sar. Change the <Engine name=”jboss.web”> property to match each node’s worker name. For example, for node 1:
<Engine name="jboss.web" defaultHost="localhost" jvmRoute="node1">.
Step 4: Locate the file jboss-service.xml in
<JBOSS_HOME>/server/default/deploy/jbossweb-tomcat55.sar/META-INF . Change the <attribute name=”SnapshotMode”> property to instant. and the <attribute name=”UseJK”> to true .
Step 5: (optional) You may notice the JBoss server log outputs a “message received from
member of another partition” message every 15-30 seconds. If you wish to suppress this message to clean the console output, locate the file log4j.xml in <JBOSS_HOME>/server/default/conf . Add the following code to the file: <category name=org.jgroups.protocols.UDP"> tag, and set <priority
<category name="org.jgroups.protocols.UDP"> <priority value="FATAL"/> </category>
JBoss Configuration for SQL Server JBoss is configured by default to use HSQL, and must be modified to use MS SQL Server. These steps must be taken on each node.
Step 1: Download the SQL Server 2000 JDBC Service Pack 3 drivers from
http://www.microsoft.com/sql/downloads . Extract the downloaded file, and locate msutil.jar, msbase.jar, and mssqlserver.jar in the extract directory. Copy those files to <JBOSS_HOME>/server/default/lib .
Step 2: Create a database for Connect to use in SQL Server Enterprise Manager, and create
a user with owner permissions.
Step 3: Locate mssql-ds.xml in the <JBOSS_HOME>/docs/examples/jca directory. Copy
it to <JBOSS_HOME>/server/default/deploy, and modify it to read as follows:
<?xml version="1.0" encoding="UTF-8"?>
Make sure to change the highlighted properties to match your database and hostname.
Step 4: Delete hsqldb-ds.xml from the <JBOSS_HOME>/server/default/deploy directory. Step 5: Locate standardjaws.xml in the <JBOSS_HOME>/server/default/conf directory. Modify <datasource> to java:/Connect , <create-table> to true and <remove-
table> to false.
Step 6: Locate standardjbosscmp-jdbc.xml in the <JBOSS_HOME>/server/default/conf directory. Modify <datasource> to java:/Connect , <type-mapping> to MS SQLSERVER2000 and <debug> to false. Step 7: Locate login-config.xml in the <JBOSS_HOME>/server/default/conf directory.
Make sure there is the following code, and add it if necessary. Make sure to change the highlighted fields to match your local database.
<application-policy name = "MSSQLDbRealm"> <authentication> <login-module code = "org.jboss.resource.security.ConfiguredIdentityLoginModule" flag = "required"> <module-option name = "principal">sa</module-option> <module-option name = "userName">connect11 </module-option> <module-option name = "password">connect11 </module-option> <module-option name = "managedConnectionFactoryName"> jboss.jca:service=LocalTxCM,name=Connect </module-option> </login-module> </authentication> </application-policy>
JBoss Configuration for Connect 1.1 Finally, each node’s JBoss installation must be configured to deploy Connect.
Step 1: Follow the steps in the document titled “Misys Connect Installation Guide.” Step 2: It may be necessary to copy standard.jar from Connect1/connect.war/WEB-INF/lib to
How To Use the Cluster The JBoss cluster setup should now be complete. The steps below should be taken to make sure it is properly configured.
Step 1: Start JBoss on each node one of two ways:
-navigate to <JBOSS_HOME>/bin and run the run.bat file. -on a command prompt, set the working directory to <JBOSS_HOME>/bin and type the command run.
Step 2: On one node, stop Apache HTTP Server if it is currently running, and restart it. Step 3: From a web browser, navigate to http://hostname (with no port number) where hostname is replaced by the name of the computer running Apache. If Apache is
properly configured, you should see a JBoss welcome screen.
Step 4: Click on the JMX-Console link, which can also be reached directly at
http://hostname/jmx-console . Under the “jboss” heading, look for service=”DefaultPartition” and click that link. The “CurrentView” field should show the IP address of each node in the cluster currently running a JBoss instance.
Step 5: Return to the JBoss welcome screen, and click the “full” link beside “Tomcat Status”.
If Connect is properly deployed, its address should be listed under “Application List”. Make a note of that address.
Step 6: In the web browser, navigate to http://hostname/connect where connect is replaced, if
necessary, by the address found in Step 5. If the load-balancing was correctly set up, this session’s output should be shown completely in one node’s server log.
Step 7: Begin a new browser session, either on the same computer or a different one, and
navigate to the same URL as in Step 6. This session’s output should be shown completely in the other node’s server log.
Other Sources For information more advanced clustering setups, including HTTP state session replication and failover, see JBoss’s clustering setup guide at the following link. http://docs.jboss.org/jbossas/jboss4guide/r5/html/cluster.chapt.html#clustering-http