HTTP state replication

This article explains what HTTP state replication is and how to set it up

1 Introduction

2 Cluster enabling a Web-module

    Any Web-module that is distributable (contains a <distributable/> tag in its web.xml descriptor) can be cluster enabled by following these steps:

    2.1 Step 1: Deploy the Web-module

      Deploy the Web-module on all Servers you want to use in your cluster.

      If the Web-module is part of an Application, you can follow this step-by-step guide for Application deployments.

      If the Web-module is a stand-alone module, you can follow this step-by-step guide for stand-alone Web-module deployments.

      Make sure to deploy your Applications using the same deployment name on all Servers.

      If so preferred, the Application (or stand-alone Web-module) can be placed on a shared drive that all Servers access

    2.2 Step 2: Bind the Web-module

      Bind the deployed Web-module to the Web-site that is to be used. Make sure to bind it to the same root on all Servers so that the Clients URL will be the same.

      Instructions for binding a Web-module to a Web-site can be found here.

    2.3 Step 3: Verify deployment and binding

      Verify that all deployment and bindings was without issues by accessing the Web-module with a client.

    2.4 Step 4: Configure Web-module to replicate its state

      Edit the orion-web.xml file of all involved Web-modules and add the following to the main body of the <orion-web-app> tag: 


                          <cluster-config host="[host]" id="[number]" port="[port]"/>
      Listing 1: Adding cluster-config tag to orion-web.xml

      Specify [host] if the default multicast host (230.0.0.1) should not be used.

      Specify [port] if the default multicast port should not be used. The default multicast port is 9127 plus the cluster island number, so for cluster island 1 the port would be 9128 and for cluster island 2 the port would be 9129.

      Specify [number] if the default id (random seed based on local machine IP) should not be used. The number given needs to be unique for the specific cluster node within the cluster (so multiple cluster-enabled Web-modules can use the same cluster id as long as they all reside on the same Server).

      If only the default values are needed, leave the tag empty as in listing 2 below.


          <cluster-config/>
      Listing 2: Example of cluster-config tag in orion-web.xml when default values are to be used.

      The multicast host and port is the multicast address that this Web-module's clustering service will use to transmit and receive state information on. It should therefore be the same for all Web-modules that should share state (part of the same cluster island).

      Sometimes different multicast addresses/ports are used for different cluster islands to enable "smart" routing of multicast packets in the network and just traffic on certain IPs to certain cluster nodes.

      If the ServletContext should also be replicated (adviced against in the Serlvet specification and therefore disabled by default), the replicate-servlet-context attribute of the <orion-web-app> tag must be given a value of "true", as exemplified in listing 3 below.

       


          <orion-web-app
              replicate-servlet-context="true"
          >
              <cluster-config/>
          </orion-web-app>
      Listing 3: Example of setting replicate-servlet-context attribute in orion-web-app tag to "true" in order to replicate ServletContext values.

      Where the value of the replicate-servlet-context attribute should be set to "true" in order for the ServletContext to be replicated ("false" by default).

      Please notice that only Serializable values bound to the ServletContext will be replicated.

    2.5 Step 5: Configure cluster islands

      If the cluster is going to use more than one cluster island, or if another cluster island than "0" (the default) is to be used, a value needs to be given for the cluster island attribute. Edit the web-site.xml file for the website the Web-module is bound to (for example default-web-site.xml if clustering the default Web-module) and add the following to the <web-site> tag: 


                          cluster-island="[number]"
      Listing 4: Specifying the cluster island in web-site.xml

      Substitute [number] with a number equal or greater than 1 if the default value (-1) is not to be used.

      If the cluster is to have more than one island, specify different island values for the Web-sites that belong in different islands. Remember that the default clustering port will be 9127 plus the value of the cluster-island attribute.

      In order for the LoadBalancer to be notified of the existance of the Web-site, a cluster-island value greater than 0 has to be used. Please see the Load Distribution article for more information.

      Notice that the cluster enabled Web-modules must be bound to web-sites with the same cluster island number in order for state changes to be received.

    2.6 Step 6: Verify cluster configuration

      Verify the HTTP-cluster configuration by starting up the Servers in cluster-debug mode as described here and then access a state altering resource of one of the clustered Web-mdoules. Console output on the Servers of the cluster should show that state is being replicated. Double-check by inspecting the session values of the Web-modules through the administration console view for Sessions.

      If no easily usable state altering resource exists in the Web-modules, either the SessionExample servlet or a simple JSP page can be used. A sample JSP page is given in listing 5 below.


                          <html>
                          <body>
                          <%
                          session.setAttribute("foo","bar");
                          %>
                          </body>
                          </html>
      Listing 5: A sample state altering JSP page

    2.7 Step 7: Configure a LoadBalancer

      If a load balancer is to be used in front of the Web-site to which the Web-module is bound, the Web-site needs to know about it so that all affected values can me modified. This is configured in the web-site.xml of the web-site the Web-module is bound to. In the main body of the <website> tag, add: 


                          <frontend host="balancer-host" port="balancer-port" />
      Listing 6: Specifying the location of the load distributor in web-site.xml.

      Where balancer-host should be replaced with the hostname of the server which will be running the load distributor and balancer-port with the port that will be used for the same. This host and port will make up the public hostname for the site, so port 80 is a good suggestion.

      In order for the LoadBalancer to be notified of the existance of the Web-site, a cluster-island value greater than 0 has to be used. Please see the Load Distribution article for more information.

    If the above steps have been completed successfully the Web-modules should now be able to share their state within the configured island(s).

    In order for the cluster to be transparent to the client, continue with setting up a LoadBalancer as described here.

3 Cluster enabling all Web-modules

    By cluster enabling the global Web-module, all Web-mdoule's that are distributable /contains a <distributable/> tag in its web.xml descriptor) can be cluster enabled.

    To cluster-enable all distributable Web-modules available on a certain Server, follow these steps:

    3.1 Step 1: Identify the global Web-module configuration file

      The global Web-module configuration file for a Server is pointed out in the server.xml file of the Server. This file is normally located at config/server.xml in the Orion installation directory.

      Open the file and look for the <global-web-app-config> tag. By default this tag looks like in listing 7 below:


                          <global-web-app-config path="global-web-application.xml" />
      Listing 7: The default global-web-app-config entry in server.xml

    3.2 Step 2: Configure global Web-module to replicate its state

      Follow the instructions given earlier for Web-module cluster configuration but use the file identified in step 1 above instead of a particular Web-module's orion-web.xml.

      Notice that all distributable Web-modules on the Server will inherit the specified values.

    3.3 Step 3: Configure cluster islands

      If needed, follow the instructions given earlier to configure cluster islands.

    3.4 Step 4: Verify cluster configuration

      If needed, follow the instructions given earlier to verify the configuration.

    3.5 Step 5: Configure a LoadBalancer

      If needed, follow the instructions given earlier to configure LoadBalancers.

    If the above steps have been completed successfully all the distributable Web-modules available on the Server should now be able to share their state within the configured cluster island(s).

    In order for the cluster to be transparent to the client, continue with setting up a LoadBalancer as describedhere.

4 Debugging

    This section describes common techniques that can be used to debug HTTP-clustering.

    4.1 Tracing

      In order to get trace information from the cluster services, start the Orion Server with the cluster.debug and http.cluster.debug system properties set to true, as exemplified in listing 8 below. 


                          java -Dhttp.cluster.debug=true -Dcluster.debug=true -jar orion.jar -console
      Listing 8: Starting a Orion server with cluster debug system properties turned on

      The cluster.debug property will list common debug information to the cosole.

      The http.cluster.debug property will list HTTP cluster debug information to the console.

    4.2 Application logs

      Issues the Web-module's clustering service has with either sending or receiving state can be found in the Web-modules Applications application.log file per default. If the Web-module was deployed as a stand-alone Web-module, this information can be found in the application.log file of the default application.

5 Troubleshooting

    This section describes common problems and possible solutions.

    5.1 Wrong IP address used for web-site

      It is not reliable to get the IP address of the local host on all platforms. It is therefore recommended that the value for the host attribute is set correctly. This issue is normally encountered when the LoadBalancer is having troubles identifying the web-site.

    5.2 Firewall issues

      Make sure that any firewalls allows for the Servers to communicate on the configured multicast address in both directions, both sending and receiving information.

      Using a simple multicast sender/receiver test application allows for testing the configured multicast address and make sure that packets can be both sent and received.

    5.3 Proxies/Gateways issues

      As multicast packets are known to hog down networks if allowed to roam free, most proxies and gateways won't let multicast packets pass. Make sure that the multicast packets can reach all nodes in the cluster and configure any proxies/gateways accordingly.

    5.4 Non distributable state

      If certain objects are not replicated within the cluster, make sure that these values are either Serializable or remote RMI-objects (this also goes for any objects this object is using/referring to).

Copyright © 2005 IronFlare AB