In JBoss AS 4.0.5, support for buddy replication was added to the HTTP session replication feature set. In 4.2.2 buddy replication support was added for clustered EJB3 Stateful Session Beans.

With buddy replication, sessions are replicated to a configurable number of backup servers in the cluster (aka buddies), rather than to all servers in the cluster.  If a user fails over from the server that is hosting his or her session, the session data is transferred to the new server from one of the backup buddies.  See JBossCacheBuddyReplicationDesign and the JBoss Cache docs for more details on the basics of buddy replication.

Buddy replication provides three basic benefits:

1) Reduced memory utilization on each server, since a server only needs to store in RAM the sessions it itself is hosting as well as those of the servers for which it is acting as a backup.  So, in an 8 node cluster where each server is configured to have 1 buddy, each server would need to store 25% of the total sessions, rather than the 100% required with total replication.

2) Reduced CPU utilization for replication, as each server only needs to handle replication traffic related to its buddies.

3) Reduced network utilization, particulary if JGroups is configured to use TCP.

(Note that in the versions of JBoss Cache and JGroups bundled with 4.0.5.GA, the second and third benefits of buddy replication are largely unrealized.  This was corrected in JBoss Cache 1.4.1.GA and JGroups 2.4.1, to which it should be possible to upgrade a 4.0.5 server.  See http://jira.jboss.com/jira/browse/JGRP-338.)

Configuration

Buddy replication configuration varies slightly between the 4.x series and AS 5.

4.x Series -- HttpSessions

Buddy replication for web sessions is configured via the $JBOSS_HOME/server/all/deploy/tc5-cluster.sar/META-INF/jboss-service.xml file. (In the AS 4.2 series this was changed to $JBOSS_HOME/server/all/deploy/jboss-web-cluster.sar/META-INF/jboss-service.xml.) There you will find the following XML fragment:

<attribute name="BuddyReplicationConfig">
  <config>
      <buddyReplicationEnabled>false</buddyReplicationEnabled>

      <buddyLocatorClass>org.jboss.cache.buddyreplication.NextMemberBuddyLocator</buddyLocatorClass>
      <buddyLocatorProperties>
        numBuddies = 1
        ignoreColocatedBuddies = true
      </buddyLocatorProperties>

      <buddyPoolName>default</buddyPoolName>

      <buddyCommunicationTimeout>20000</buddyCommunicationTimeout>

      <autoDataGravitation>false</autoDataGravitation>
      <dataGravitationRemoveOnFind>true</dataGravitationRemoveOnFind>
      <dataGravitationSearchBackupTrees>true</dataGravitationSearchBackupTrees>

   </config>
</attribute>

The main things you would be likely to configure are:

• buddyReplicationEnabled -- true if you want buddy replication; false if data should be replicated to all nodes in the cluster. Disabled by default.

• numBuddies -- to how many backup nodes should each node replicate its state

• buddyPoolName -- allows logical subgrouping of nodes within the cluster; if possible, buddies will be chosen from nodes in the same buddy pool

The ignoreColocatedBuddies switch means that when the cache is trying to find a buddy, it will if possible not choose a buddy on the same physical host as itself. If the only server it can find is running on its own machine, it will use that server as a buddy.

Do not change the settings for autoDataGravitation, dataGravitationRemoveOnFind and dataGravitationSearchBackupTrees.  Session replication will not work properly if these are changed.

See JBossCacheBuddyReplicationDesign and the JBoss Cache docs for more details on buddy replication configuration.

4.x Series -- EJB3 SFSBs

The buddy replication configuration for EJB3 SFSBs is done via the $JBOSS_HOME/server/all/deploy/ejb3-clustered-sfsbcache-service.xml file. Configuration is exactly the same as is described for HttpSessions above.

AS 5

In JBoss AS 5, all JBoss Cache configuration is centralized in the CacheManager service. The standard-session-cache (for HttpSessions), field-granularity-session-cache (for FIELD replication-granularity HttpSessions) and sfsb-cache (for EJB3 SFSBs) configuration all include buddy replication configuration elements.  The configurations use the JBoss Microcontainer schema rather than the native JBC config format, but the underlying things being configured are the same as above:

<property name="buddyReplicationConfig">
   <bean class="org.jboss.cache.config.BuddyReplicationConfig">
               
      <!--  Just set to true to turn on buddy replication -->
      <property name="enabled">false</property>
               
      <!-- A way to specify a preferred replication group.  We try
           and pick a buddy who shares the same pool name (falling 
           back to other buddies if not available). -->
      <property name="buddyPoolName">default</property>
               
      <property name="buddyCommunicationTimeout">17500</property>
               
      <!-- Do not change these -->
      <property name="autoDataGravitation">false</property>
      <property name="dataGravitationRemoveOnFind">true</property>
      <property name="dataGravitationSearchBackupTrees">true</property>
               
      <property name="buddyLocatorConfig">
         <bean class="org.jboss.cache.buddyreplication.NextMemberBuddyLocatorConfig">
            <!-- The number of backup copies we maintain -->
            <property name="numBuddies">1</property>
            <!-- Means that each node will *try* to select a buddy on 
                 a different physical host. If not able to do so 
                 though, it will fall back to colocated nodes. -->
            <property name="ignoreColocatedBuddies">true</property>
          </bean>
      </property>
   </bean>
</property>

Buddy replication and Clustered SSO

Clustered SSO will not work properly if buddy replication is enabled for the cache that the Clustered SSO valve by default shares with the HttpSession replication service.  If buddy replication is enabled Clustered SSO will need to use a separate cache; see the Clustered SSO page for how to configure that.  The Buddy replication and Clustered SSO page has further details on why buddy replication is inappropriate for Clustered SSO.

Buddy replication and mod_jk

There is no need to make any changes to your mod_jk configuration if buddy replication is used, other than that sticky sessions must be used.  But sticky sessions are really necessary even if buddy replication is not used. If mod_jk is unable to reach the JBoss server to which a session is assigned, it will pick any other server in the cluster to handle the request.  It does not matter if that server is one of the original server's buddies; JBoss will migrate the session data from the buddies to the new server.

Referenced by: