JBoss Cluster Groups

JBoss clusters are based upon a communications module named JGroups. JGroups is installed with JBoss (it also can be used without JBoss). JGroups provides communications among groups, which share a common name, multicast address, and multicast port.

When you install a clustered JBoss server, JBoss defines two different JGroups groups for use in managing the cluster. One is called DefaultPartition and is defined in /deploy/cluster-service.xml. This cluster group is used by JBoss to provide core clustering services. JBoss also defines a second cluster group named Tomcat-Cluster. This cluster group is defined in /deploy/tc-cluster-service.xml. This cluster group provides session replication for the Tomcat server that runs inside JBoss.

The Identity Manager user application uses a third cluster group. This cluster group uses a UUID name to minimize the risk of conflicts with other cluster groups that users might add to their servers. By default, the cluster group is named c373e901aba5e8ee9966444553544200. This cluster isn't configured using a JBoss service file. Instead, the configuration settings are located in the directory and can be configured using the user application administration features. If you are familiar with JGroups and JBoss clustering, you can adjust the user application cluster configuration using this interface. Changes to the cluster configuration only take effect for a server node when that node is restarted.

The user application cluster group is used solely to coordinate user application caches in a clustered environment. It is independent of the two JBoss cluster groups and does not interact with them in any way. By default, the user application cluster group and the two JBoss groups use different group names, multicast addresses and multicast ports so no reconfiguration is necessary.

User application cluster group settings are shared by any Identity Manager 3 application that shares the directory configuration. The purpose of the local settings option in the user application administration interface is to allow an administrator to remove a node from a cluster, or change the membership of servers in a cluster. For example, you can disable clustering globally, then enable it locally for a subset of your servers sharing the directory configuration.

Application Farming

JBoss allows you to hot-deploy across the a cluster by copying an application EAR, WAR, or JAR into the farm directory of one clustered JBoss instance. Hot-deploying on one machine causes that component to be automatically deployed on all instances within the cluster, while the cluster is running.

This form of application deployment is not recommended with the release of JBoss Application Server (4.0.2) that was included with the user application installation program at the time that this document was written, as there are unresolved problems related to its use. However, we have provided the basic steps that you must perform (see Deploying the User Application to a Cluster Using JBoss Farming) to successfully deploy the user application using JBoss farming technology, as improvements to this technology can be expected after the publication of this document.

MySQL Database

The user application installation program either installs the MySQL database manager and creates a database for use with the user application, or it uses an existing Oracle, Microsoft SQL Server, or MySQL database. The database is responsible for data persistence. All nodes in the JBoss cluster must access the same database instance. The user application uses standard JDBC calls to access and update the database. The user application uses a JDBC data source bound to the JNDI tree to open a connection to the database. If you create the JBoss cluster by using the user application installation program, the data source will be installed for you. If you choose to set up the JBoss cluster manually, you will need to copy the data source file (IDM-ds.xml) to the deploy directory on all nodes in your cluster. Also, if you are using MySQL, you need to copy the MySQL JDBC driver (mysql-connector-java-3.1.10-utf8-clob-fix-bin.jar), located in the JBoss /server/IDM/lib directory, to the JBoss server/IDM/lib directory.

Logging

To enable logging for clusters you need to edit the log4j.xml configuration file, located in the \conf directory for the JBoss server configuration (for example, \server\IDM\conf), and uncomment the section at the bottom that looks like this:

<!--  Clustering logging 
  --> 
- <!-- 
 Uncomment the following to redirect the org.jgroups and
      org.jboss.ha categories to a cluster.log file.
   <appender name="CLUSTER" class="org.jboss.logging.appender.RollingFileAppender">
     <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
     <param name="File" value="${jboss.server.home.dir}/log cluster.log"/>
     <param name="Append" value="false"/>
     <param name="MaxFileSize" value="500KB"/>
     <param name="MaxBackupIndex" value="1"/>
     <layout class="org.apache.log4j.PatternLayout">
       <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
     </layout>
   </appender>
   <category name="org.jgroups">
     <priority value="DEBUG" />
     <appender-ref ref="CLUSTER"/>
   </category>
   <category name="org.jboss.ha">
     <priority value="DEBUG" />
     <appender-ref ref="CLUSTER"/>
   </category>
  --> 

You can find the cluster.log file in the log directory for the JBoss server configuration (for example, \server\IDM\log).

Using the User Application Installation Program on Each Node in the Cluster

JBoss comes with three different ready-to-use server configurations: minimal, default and all. Clustering is only enabled in the all configuration. A cluster-service.xml file in the /deploy folder describes the configuration for the default cluster partition. When you install the user application and indicate to the installation program that you want to install into a cluster, the installation program makes a copy of the all configuration, names the copy IDM (by default; the installation program allows you to change the name), and installs the user application into the this configuration.

Deploying the User Application to a Cluster Using JBoss Farming

Do not use JBoss farming with JBoss version 4.0.2 or earlier, as you may experience problems (see http://jira.jboss.com/jira/browse/JBAS-1899). We recommend that you install the user application, using the user application installation program, on each node in the cluster (see Using the User Application Installation Program on Each Node in the Cluster in this Chapter). However, if you want to use farming to deploy the user application to a JBoss cluster using JBoss 4.0.3 or higher, follow the steps below.