Chapter 2 Configuring Converged Load Balancing

This chapter describes the converged load balancer. It includes the following topics:

• How the Converged Load Balancer Works

• Setting Up Converged Load Balancing

• Configuring the Converged Load Balancer

• The Data Centric Rules File

This chapter discusses using the converged load balancer included with the Communications Server, which load balances HTTP, HTTPS, SIP, and SIPS messages.

Another load balancing option is to use the Sun Secure Application Switch with the Communications Server for a hardware-based load balancing solution. For a tutorial on configuring this solution, see the article Clustering and Securing Web Applications: A Tutorial.

How the Converged Load Balancer Works

The load balancer attempts to evenly distribute the workload among multiple instances (either stand-alone or clustered), thereby increasing the overall throughput of the system.

The Converged Load Balancer enables high availability of services deployed on Java EE application servers. While doing so, it fails over a session request to another server instance in the same cluster if the original servicing instance is detected to be unavailable or unhealthy to service a request.

The load balancer does not handle URI/URLs that are greater than 8k.

The following illustration depicts the working of a load balancer:

1. IP sprayer receives the client request.

   ---

   Note –

   The IP sprayer could be a hardware IP sprayer, which distributes requests evenly across all instances in a cluster. A network element such as the IP sprayer can front the converged load balancer and , at the transport level, distribute traffic over the cluster.

   ---

2. IP sprayer selects any of the SailFin instances in the cluster and forwards request to that instance. This example and illustration shows the request being forwarded to Instance1.

3. The converged load balancer on Instance1 selects an instance (Instance2, in this case) to service the request.

   The selection of the server instance to forward the request, is based on the configured Converged Load Balancing Algorithms. This key is added to the request as a header or parameter for maintaining stickiness.

4. In this example, the converged load balancer on Instance1 forwards the request to Instance2. If the converged load balancer chooses Instance1 to service this request, step 5 is bypassed.

5. The converged load balancer on Instance2 receives the request and detects that the request is already proxied from another instance. Without any further processing, Instance2 passes the request to the container so that it can be serviced. The converged load balancer on Instance2 sends the response back to the converged load balancer on Instance1.

6. The converged load balancer on Instance1 sends the response back to the client

7. Once a session is established, sticky information is set on the response and subsequent requests will carry this sticky information. Subsequent requests from the client will have the sticky information in the header/parameter. Even if Instance1 receives this request, it detects the sticky information and forwards the request to the converged load balancer on Instance2.

   To maintain HTTP and HTTPS session stickiness the load balancer uses cookies or , if the browser does not support cookies, uses URL rewriting. For SIP/SIPS sessions, the load balancer uses parameters such as the BEKeyand BERoute. For example, the converged load balancer stamps the BERoute parameter on the VIA header as part of the outgoing request.

Converged Load Balancing Algorithms

The load balancer automatically uses one of the following algorithms:

• Round-robin algorithm — The load balancer selects the instance for servicing new message in a round robin fashion.

• Consistent hash — The load balancer selects the instance for servicing new message based on hash-key extracted from request. The hash key is extracted by using the rule specified in the DCR file, if provided. If a DCR file is not provided, hash key is extracted using default headers.

  A DCR file, data-centric-rules.xml, provides rules for applying consistent hashing on both HTTP/HTTPS and SIP/SIPS messages from converged or pure SIP applications. If this file is specified, the instructions in this file override the mechanism to extract hash key using default headers. If a DCR file is not provided, SIP and HTTP messages that are part of the same session may be serviced by different instances. Ensure that you provide a DCR file when you are deploying a converged application. The default header used may not provide a correct load distribution for SIP messages either. Therefore, even for pure sip applications, it is recommended that you provide a DCR file. For more information about this file, see Editing Configuration Settings and The Data Centric Rules File.

  In addition to this XML, it is possible to configure DCR by using a plug-in in the form of a Java class.

Converged Load Balancing Algorithm for Web Applications

HTTP and HTTPS messages belonging to pure web applications, the converged load balancer uses a sticky round robin algorithm, by default. When a new request is sent to the load balancer, it is forwarded to an application server instance based on a simple round robin scheme. If the request is for a session-based application, it may result in creation of a session. In such a case, response will have sticky information, which is sent back on subsequent messages. Subsequent messages from the same client for the same session-based application are considered assigned or sticky messages and are routed by the load balancer to the same instance if that instance is found to be healthy. Hence, the name sticky round robin. Requests to a non-session-based application and the first request for a session-based application are new requests.

Converged Load Balancing Algorithm for SIP Applications

For SIP and SIPS messages belonging to pure SIP applications, the converged load balancer uses a consistent hash algorithm, by default. If any of the rules in the DCR file match the SIP/SIPS request, a hash key is extracted using that rule. If none of the instructions or rules in the DCR file match the SIP or SIPS request, a hash key is generated using the from-tag,call-id parameters of the request.

Converged Load Balancing Algorithm for Converged Applications

Converged load balancer applies appropriate algorithms for HTTP/HTTPS and SIP/SIPS messages from converged applications, as follows:

• If no DCR file is specified, applies the sticky round robin algorithm for HTTP/HTTPS messages and the consistent hash algorithm for SIP/SIPS messages.

• If a DCR file is specified, applies the consistent hash algorithm for both HTTP/HTTPS messages and SIP/SIPS messages.

  For HTTP and HTTPS messages belonging to converged applications, if any of the rules in the DCR file match the HTTP/HTTPS request, a hash key is extracted using that rule. If none of the instructions or rules in the DCR file match the HTTP/HTTPS request, a hash key is extracted using remote host and port of the HTTP request.

  For SIP and SIPS messages, if any of the rules in the DCR file match the SIP/SIPS request, a hash key is extracted using that rule. If none of the instructions or rules in the DCR file match the SIP or SIPS request, a hash key is generated using the from-tag,call-id parameters of the request.

Converged Load Balancer Deployments

You can configure your load balancer in different ways, depending on your goals and environment, as described in the following sections:

• Using Self-Load-Balancing Clusters

• Using Dedicated Load Balancing Server Instances

Using Self-Load-Balancing Clusters

In a development or production environment, you can designate that all server instances in a cluster participate in both redirecting and servicing requests, without using any dedicated load balancing instances. This is a self-load-balancing cluster, in which the target and the LB target are the same cluster.

A front-end hardware IP sprayer distributes request evenly across all instances in the cluster. If you do not use a hardware IP sprayer, a request can be forwarded to any server instance in the cluster. The converged load balancer component on that instance ensures that requests are distributed across the cluster. However, that instance is a single point of failure. The presence of a hardware IP sprayer ensures high availability.

Using Dedicated Load Balancing Server Instances

In a development environment, you can designate one or more stand-alone server instances as dedicated load balancers, which redirect requests to clusters or to other stand-alone instances that service those requests. These dedicated load balancers are called the targets of the load balancer.

The clusters or instances that service requests are called the LB targets of the load balancer. The LB targets of a specific load balancer can be clusters or stand-alone instances, but not a mixture of clusters and instances.

• Using Clustered Server Instances as LB Targets — The most common way to deploy the load balancer is with a cluster or clusters of server instances as the LB target or LB targets. By default all the instances in a cluster have the same configuration and the same applications deployed to them. The load balancer distributes the workload between the server instances and requests fail over from an unhealthy instance to a healthy one. If you have multiple clusters, requests can be load balanced across clusters but are only failed over between the instances in a single cluster.

• Using Multiple Stand-Alone Instances as LB Targets — It is also possible to configure your load balancer to use multiple stand-alone instances as LB targets, and to load balance and failover requests between these LB targets. However, in this configuration, you must manually ensure that the stand-alone instances have homogenous environments and the same applications deployed to them. Because clusters automatically maintain a homogenous environment, for most situations it is better and easier to use clusters.

  All instances in a cluster must have similar view for each other's IP address. For example, consider a cluster with two instances, say instance1 and instance2. When instance1 looks up instance2's IP address, it gets a.b.c.d. When instance2 looks up its own IP address, it should also see a.b.c.d, which is the same IP viewed by instance1. Ensure that the hosts file on your machine is correctly set up.

Dedicated load balancers are not supported in a production environment.

Setting Up Converged Load Balancing

This section describes how to set up the load balancer and includes the following sections:

• Prerequisites for Setting Up Converged Load Balancing

• Procedure to Set Up Converged Load Balancing

Prerequisites for Setting Up Converged Load Balancing

Before configuring your load balancer, you must:

• Create Communications Server clusters or server instances to participate in load balancing using the cluster profile. For more information, see Chapter 3, Setting Up Clusters in Communications Server.

• Make sure the group management service (GMS) is enabled. It is enabled by default. For more information, see Group Management Service.

• Create node agents for these clusters or server instances. For more information, see Chapter 4, Configuring Node Agents.

• Configure session persistence using in-memory replication. For more information, see Chapter 6, Configuring High Availability Session Persistence and Failover

• Deploy applications to these clusters or instances. For more information, see the Sun GlassFish Communications Server 2.0 Application Deployment Guide.

Procedure to Set Up Converged Load Balancing

Use the Admin Console or the asadmin command to configure load balancing in your environment. The following sections provide you more information.

To Set Up Converged Load Balancing Using the Admin Console

1. Create a load balancer.

   On the left frame, click Converged Load Balancers and then click New. In the New Converged Load Balancer page, provide the load balancer name and also select target clusters or instances that will act as load balancers.

   Optionally, you can specify the following settings:

   • Configuration File Name — Specifies the name of the converged load balancer's configuration file. The default path and name of the configuration file is domain-dir/config/cluster-config/converged-loadbalancer.xml.

   • Automatically Apply Changes — Specifies whether to automatically apply configuration changes to the target server instances. This setting is off by default. Set this to true and generate the converged load balancer's configuration file.

   • Self Load Balancing — Specifies whether the target cluster is self-load-balancing. This setting is on by default. For production environments, only self-load-balancing target clusters are supported.

2. For a load balancer that is not self-load-balancing, add references to clusters or stand-alone server instances for the load balancer to manage.

   On the left frame, click the Converged Load Balancers node and then click the desired load balancer listed under the node. Open the Converged Load Balancer LB Targets tab, click Manage LB Targets and in the Manage LB Targets page, select the required LB targets.

   You may select clusters or stand-alone instances as LB targets. Note that you cannot have a combination of both clusters and stand-alone instances as selected LB targets.

   ---

   Note –

   This step is not supported in a production environment.

   ---

3. If the cluster was already started when you created the load balancer, you must restart the cluster to start the load balancer.

See Also

For more information, see the Admin Console online help.

To Set Up Converged Load Balancing Using asadmin Commands

You can perform the following steps using a single asadmin command, create-converged-lb.

1. Create a load balancer configuration.

   Use the asadmin create-converged-lb-config command.

2. Add a reference to a cluster or stand-alone server instance for the load balancer to manage.

   Use the asadmin create-converged-lb-ref command.

   ---

   Note –

   While you perform the iterative process of setting up and defining the cluster deployment, it is recommended that --autocommit be set to false. By default, this option is set to false, primarily to prevent generation of intermediate converged load balancer files, which would get generated for every change in domain.xml, which impact the converged load balancer's view of its configuration. After the cluster deployment definition has reached a stable point in evolution, set --autocommit to true.

   ---

Example 2–1 Creating a Converged Load Balancer

The following series of asadmin commands sets up a cluster, a node agent, and a self-load-balanced converged load balancer.

asadmin> create-cluster cluster1
    Command create-cluster executed successfully.
asadmin>create-node-agent --user admin --passwordfile pass.txt 
--host host1 nodeagent1
    Command create-node-agent executed successfully.
asadmin>create-node-agent --user admin --passwordfile pass.txt 
--host host1 nodeagent2
    Command create-node-agent executed successfully.
asadmin>create-instance --user admin --passwordfile pass.txt --nodeagent nodeagent1 
--cluster cluster1 cluster1_instance1
   Command create-instance executed successfully.
asadmin> create-instance --user admin --passwordfile pass.txt 
--nodeagent nodeagent2 --cluster cluster1 cluster1_instance2
   Command create-instance executed successfully.
asadmin> create-converged-lb --user admin --passwordfile pass.txt 
--configfile clb.xml --autocommit=true --lbenableallinstances=true 
--target cluster1 clb-1
   Command create-converged-lb executed successfully.
asadmin> start-node-agent nodeagent1
   Command start-node-agent started successfully.
asadmin> start-node-agent nodeagent2
   Command start-node-agent started successfully.
asadmin> start-cluster cluster1
 cluster1_instance1 is running, does not require restart
 cluster1_instance2 is running, does not require restart
 Command start-cluster executed successfully.

If the cluster was already started when you created the load balancer, you must restart the cluster to start the load balancer.

See Also

For more information about these asadmin commands, see the Sun GlassFish Communications Server 2.0 Reference Manual.

Configuring the Converged Load Balancer

These sections describe, in more detail, how to modify and use a load balancer configuration:

• Editing Load Balancer Settings in the Admin Console

• Editing Load Balancer Settings

• Enabling or Disabling a Server Instance for Load Balancing

• Changing the Log Message Level for the Converged Load Balancer

Editing Load Balancer Settings in the Admin Console

After you have created a converged load balancer, you can edit its settings in the Admin Console as described in the following sections.

• Editing Configuration Settings

• Editing Load Balancer Details

• Editing Self Load Balancing (Load Balancer Target Details)

Editing Configuration Settings

To configure a load balancer in the Admin Console, on the left frame, click the Converged Load Balancers node and then click the desired load balancer listed under the node. Open the Settings tab. This displays the Edit Converged Load Balancer Configuration Settings page.

The following table describes the load balancer configuration settings.

Editing Load Balancer Details

You can change converged load balancer settings after you have created the load balancer.

To edit load balancer details in the Admin Console, on the left frame, click the Converged Load Balancers node and then click the desired load balancer listed under the node. Open the Targets tab. Select Edit Load Balancer Details. This displays the Edit Load Balancer Details page.

The following table describes the load balancer details settings.

Editing Self Load Balancing (Load Balancer Target Details)

You can change whether an Load Balancer target cluster is self-load-balancing after you have created the load balancer.

To edit Load Balancer target details in the Admin Console, on the left frame, click the Converged Load Balancers node and then click the desired load balancer listed under the node. Open the LB Targets tab. Select Edit LB Target Details. This displays the Edit LB Target Details page. This page has only one editable setting, Self Load Balancing, which you can enable or disable.

A load balancer with Self Load Balancing disabled is not supported in a production environment.

Editing Load Balancer Settings

After you have created a load balancer, you can edit its settings and the settings of its configuration using the asadmin set command.

To edit a converged load balancer setting, use the following command:

asadmin set config-name-config.availability-service.converged-load-balancer.setting

For example:

asadmin set c1-config.availability-service.converged-load-balancer.config-file=myclb.xml

asadmin set c1-config.availability-service.converged-load-balancer.auto-commit=true

asadmin set c1-config.availability-service.converged-load-balancer.converged-lb-config-name=myclb-config

To edit a converged load balancer proxy setting, use the following command:

asadmin set config-name-config.availability-service.converged-load-balancer.proxy.setting

For example:

asadmin set c1-config.availability-service.converged-load-balancer.proxy.request-pool-size=50
asadmin set c1-config.availability-service.converged-load-balancer.proxy.send-retry-count=3
asadmin set c1-config.availability-service.converged-load-balancer.proxy.read-time-out=1500

To edit a converged load balancer configuration policy setting, use the following command:

asadmin set domain.converged-lb-config.clb-config.converged-lb-policy.setting

For example:

asadmin set domain.converged-lb-configs.myclb-config.converged-lb-policy.http=round-robin

asadmin set domain.converged-lb-configs.myclb-config.converged-lb-policy.sip=from-tag,call-id

To edit the self-loadbalance setting for a cluster, use the following command:

asadmin set domain.converged-lb-config.clbcfg.converged-lb-cluster-ref.cluster.self-loadbalance=setting

For example:

asadmin set domain.converged-lb-configs.myclb-config.converged-lb-cluster-ref.clust1.self-loadbalance=true

A load balancer with Self Load Balancing disabled is not supported in a production environment.

For more information about the asadmin set command, see the Sun GlassFish Communications Server 2.0 Reference Manual.

Enabling or Disabling a Server Instance for Load Balancing

Before you stop a server instance, you should disable the instance for load balancing so that requests are failed over to another instance. To disable a server instance or cluster for load balancing, use the asadmin disable-converged-lb-server command.

For example:

asadmin disable-converged-lb-server --user admin --passwordfile pass.txt cluster1

You can use the asadmin enable-converged-lb-server command to enable a server instance or cluster for load balancing. A new instance or cluster is created with the lb-enabled option set to false by default. You need to explicitly enable an instance or cluster for load balancing.

For example:

asadmin enable-converged-lb-server --user admin --passwordfile pass.txt cluster1

For more information about the asadmin disable-converged-lb-server command and the asadmin enable-converged-lb-server, see the Sun GlassFish Communications Server 2.0 Reference Manual.

Changing the Log Message Level for the Converged Load Balancer

The default log level for converged load balancer messages is set to INFO. To change this setting, use the asadmin set command to set the javax.enterprise.system.container.clb property. For example, change the log level for c1-config to FINE as follows:

asadmin set c1-config.log-service.module-log-levels.property.clb=FINE

asadmin set c1-config.log-service.module-log-levels.property.sip=FINE

The Data Centric Rules File

A consistent hash algorithm determines the server instance to which the request is forwarded. The server instance selection is based on a hash key. You can define data centric rules, using which the key is extracted from incoming SIP and HTTP requests. Data centric rules are not application-specific and apply to all applications deployed on the LB targets. Only new initial requests are affected by such changes.

The default path to the data centric rules file is domain-dir/config/cluster-config-name. If the converged load balancer configuration that specifies the data centric rules file does not reference any cluster or stand-alone server instance, the default path is domain-dir/config/.

Data centric rules are dynamically re-configurable. The admin framework generates an admin event into the converged load balancer where the data centric rules file is supplied as an argument and the converged load balancer loads a new version of the data centric rules file.

If the data centric rules do not match any incoming SIP or HTTP requests, one of the following happens: .

• For HTTP requests, a hash key is generated using the remote host and port.

• For SIP requests, a hash key is generated using from-tag,call-id

The data centric rules file can be a JAR file or an XML file, as described in the following sections:

• Creating a Data Centric Rules JAR File

• Creating a Data Centric Rules XML File

  To set a data centric rules JAR or XML file for a converged load balancer, see the instructions at Setting the Data Centric Rules File for a Converged Load Balancer

Creating a Data Centric Rules JAR File

The data centric rules of the converged load balancer is configurable using an implementation of the org.glassfish.comms.api.datacentric.DcrPlugin interface , which is supplied as a pre-compiled Java class packaged in a JAR file. When routing a request, the converged load balancer calls the instantiated plug-in to extract the key from initial SIP and HTTP requests. The converged load balancer uses the result returned from the plug-in, to lookup the serving instance in the consistent hash.

The org.glassfish.comms.api.datacentric.DcrPlugin interface specifies two methods:

• String getKey(javax.servlet.sip.SipServletRequest request, javax.servlet.sip.SipFactory sipFactory, org.glassfish.comms.api.uriutils.UriTools uriTools, org.glassfish.comms.api.telurl.TelUrlResolver telUrlResolver)

• String getKey(javax.servlet.http.HttpServletRequest request, javax.servlet.sip.SipFactory sipFactory, org.glassfish.comms.api.uriutils.UriTools uriTools, org.glassfish.comms.api.telurl.TelUrlResolver telUrlResolver)

You can implement these methods to extract the key to be used for lookup in the consistent hash in the converged load balancer, for initial requests. Each method can return a non-null value, which indicates that the request matches a rule and a hash key is successfully extracted. If none of the rules match a request, a null value is returned and the hash key is extracted using default rules.

To facilitate the implementation of the data centric rules plug-in, the following entities are provided as method arguments:

• TelUrlResolver — For resolving Tel URIs

• UriTools— For normalizing and canonicalizing URIs

• SipFactory — For converting header values to URIs and extracting the various components from such a URI

The data centric rules JAR file must contain a compiled implementation of the plug-in interface. It can also contain other application specific helper classes. It must also have a manifest that specifies the class name of this data centric rules plug-in implementation. The converged load balancer uses the manifest to identify the class that implements data centric rules plug-in. It then loads the plug-in class and creates an instance.

Here is an example Java class file that specifies data centric rules:

package mydcr;

import org.glassfish.comms.api.datacentric.DcrPlugin;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.sip.SipFactory;
import javax.servlet.sip.SipServletRequest;
import javax.servlet.sip.SipURI;
import org.glassfish.comms.api.telurl.TelUrlResolver;
import org.glassfish.comms.api.uriutils.UriTools;

public class MyDcrPluginImpl implements DcrPlugin{

    public String getKey(SipServletRequest request,
            SipFactory sipFactory, UriTools uriTools,
            TelUrlResolver telUrlResolver) {
        String key = null;
        String method = request.getMethod().toUpperCase();
        if(method.equals( "PUBLISH" ) || method.equals( "INVITE" ) 
              || method.equals( "CANCEL" )){
           key = SipURI.class.cast(request.getTo().getURI()).getUser();
        } else if (method.equals( "REGISTER" )
                || method.equals( "SUBSCRIBE" )){
            key = SipURI.class.cast(request.getFrom().getURI()).getUser();
        }
        System.out.println("MY DCR PLUGIN - Key extracted from SIP request : " + key);
        return key;
    }

    public String getKey(HttpServletRequest request,
            SipFactory sipFactory, UriTools uriTools,
            TelUrlResolver telUrlResolver) {
        String key =  request.getParameter( "j_username" );
        System.out.println("MY DCR PLUGIN - Key extracted from HTTP request : " + key);
        return key;
    }


}

After you have written the data centric rules class, follow these steps:

1. Compile the data centric rules class as shown in the following example command. You must include ssa-api.jar, javaee.jar, and comms-appserv-api.jar in the classpath. The classes directory must exist.

   javac -classpath as-install/lib/ssa-api.jar:as-install/lib/javaee.jar:as-install/lib/comms-appserv-api.jar -d classes src/mydcr/MyDcrPluginImpl.java

2. Write the manifest file. For example:

   Manifest-Version: 1.0
   Dcr-Plugin-Class: mydcr.MyDcrPluginImpl

3. Create the data centric rules JAR file. For example:

   jar -cvfm mydcrplugin.jar mymanifest -C classes mydcr/MyDcrPluginImpl.class

4. Set the data centric rules file using the asadmin set-dcr-file command. Refer the instructions at Setting the Data Centric Rules File for a Converged Load Balancer.

Creating a Data Centric Rules XML File

The data centric rule language is similar to the triggering language for mapping requests to servlets. The rule language consists of conditions and variables supporting SIP and HTTP key extraction. In contrast to the servlet mapping language, the data centric rules file needs to return a value, either non-null (true) or null (false).

Each incoming SIP and HTTP request is matched with the current rule set. The first rule that matches is used for key extraction. The rules are evaluated sequentially until a condition returns a non-null value. For an OR expression, the first non-null sub-result is returned. For an AND expression, the last sub-result is returned. The key is set to null if no rule matches.

Here is an example XML file that specifies data centric rules:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE user-centric-rules PUBLIC "-//Sun Microsystems Inc.//DTD Sailfin 1.0//EN" 
"http://www.sun.com/software/appserver/dtds/sun-data-centric-rule_1_0.dtd">
<user-centric-rules>
  <sip-rules>
    <if>
      <session-case>
        <equal>ORIGINATING</equal>
        <if>   
          <header name="P-Asserted-Identity" 
              return="request.P-Asserted-Identity.uri.resolve.user">
            <exist/>
          </header>    
          <if> 
            <header name="P-Asserted-Identity" 
                return="request.from.uri.resolve.user">
              <notexist/>
            </header>    
            <if> 
              <header name="P-Asserted-Identity" 
                  return="request.to.uri.resolve.user">
                <notexist/>
              </header>    
            </if>
          </if>
        </if>
      </session-case>
      <else return="request.uri.resolve.user" />
    </if>
  </sip-rules>
  <http-rules>   
    <or>
      <request-uri return="match.resolve.user">
        <match>/users/([^/]+)</match>
      </request-uri>
      <and>
        <request-uri>
          <match>^/css/</match>
        </request-uri>
        <or>
          <request-uri parameter="referredBy" 
              return="parameter.requestUri.uri.resolve.user">
            <exist/>
          </request-uri>
          <request-uri parameter="referredBy" 
              return="parameter.from.uri.resolve.user">
            <notexist/>
          </request-uri>
        </or>
      </and>
    </or>
  </http-rules>    
</data-centric-rules>

The default name is data-centric-rules.xml. The DTD file that validates the file format is as-install/lib/dtds/sun-data-centric-rule_1_0.dtd.

The following sections describe the elements in the data-centric-rules.xml file:

• Top-Level Elements

• Operator Elements

• Condition Elements

• Condition Type Elements

• Variables

Top-Level Elements

The top-level elements determine the rules for SIP/SIPS and HTTP/HTTPS requests.

user-centric-rules

This is the top level or root element in the data-centric-rules.xml file.

Subelements

You can specify one or both of the following subelements: sip-rules, http-rules.

sip-rules

Determines the data centric rules for SIP and SIPS requests.

Superelements

user-centric-rules

Subelements

All of the following subelements are optional and can occur in any number and any order:

or, and, if, header, request-uri, session-case, cookie

http-rules

Determines the data centric rules for HTTP and HTTPS requests.

Superelements

user-centric-rules

Subelements

All of the following subelements are optional and can occur in any number and any order:

or, and, if, header, request-uri, session-case, cookie

Operator Elements

The operator elements specify decisions between different rules. The or, and, and if elements are recursive. You can specify any number of branches and levels of these elements, as long as the lowest level of each branch contains one of the Condition Elements.

or

Evaluates to true if and only if at least one contained condition evaluates to a non-null value.

Superelements

sip-rules, http-rules, or, and, if

Subelements

All of the following subelements are optional and can occur in any number and any order:

or, and, if, header, request-uri, session-case, cookie

and

Evaluates to true if and only if all contained conditions evaluate to a non-null value.

Superelements

sip-rules, http-rules, or, and, if

Subelements

All of the following subelements are optional and can occur in any number and any order:

or, and, if, header, request-uri, session-case, cookie

if

Contains a single condition. If the condition evaluates to a non-null value, the evaluation continues in the if branch. If the condition evaluates to null, the evaluation continues in the optional else branch.

Superelements

sip-rules, http-rules, or, and, if

Subelements

All of the following subelements are optional and can occur in any number and any order:

or, and, if, header, request-uri, session-case, cookie

The else subelement is optional and must occur last if specified.

else

Specifies an alternative when the parent if element's condition evaluates to null.

Superelements

if

Attributes

The following attribute is required and case-sensitive.

return

Specifies a variable that evaluates to the return value. See Variables.

Condition Elements

The condition elements specify the kind of data on which rule decisions are based. All attribute values are case-sensitive.

header

Specifies a rule based on a request header.

Superelements

sip-rules, http-rules, or, and, if

Subelements

Exactly one of the following subelements is required:

exist, notexist

Attributes

The following attributes are required.

name

Specifies the name of the request header.

return

Specifies a variable that evaluates to the return value. See Variables.

request-uri

Specifies a rule based on a request URI and its parameters.

Superelements

sip-rules, http-rules, or, and, if

Subelements

Exactly one of the following subelements is required:

exist, notexist, match

Attributes

The following attributes are required if the subelement is exist or notexist and optional if the subelement is match.

parameter

Specifies the request URI parameter.

return

Specifies a variable that evaluates to the return value. See Variables.

session-case

Specifies a rule based on the call parameter of a SIP session. Only relevant in IMS/3GPP (Internet Protocol Multimedia Subsystem Third Generation Partnership Project) environments. For details, see the equal subelement description.

Superelements

sip-rules, http-rules, or, and, if

Subelements

The equal subelement is required and must occur first.

All of the following subelements are optional and can occur in any number and any order:

or, and, if, header, request-uri, session-case, cookie

cookie

Specifies a rule based on an HTTP cookie.

Superelements

sip-rules, http-rules, or, and, if

Subelements

Exactly one of the following subelements is required:

exist, notexist

Attributes

The following attributes are required.

name

Specifies the name of the cookie.

return

Specifies a variable that evaluates to the return value. See Variables.

Condition Type Elements

The condition type elements compare request data to the data expected by the rules. All comparisons are case-sensitive.

exist

Specifies that a variable must evaluate to a header, request-uri, or cookie that exists in the request. See Variables.

Superelements

header, request-uri, cookie

notexist

Specifies that a variable must evaluate to a header, request-uri, or cookiethat does not exist in the request. See Variables.

Superelements

header, request-uri, cookie

equal

Specifies which part of a call is processed, the originating or terminating side of the call. Only relevant in IMS/3GPP environments. Allowed values are:

• EXTERNAL — Specifies that there is no route header in the SIP request or no call parameter in the route header.

• ORIGINATING — Specifies that the route header contains call=orig.

• TERMINATING — Specifies that the route header contains call=term_registered.

• TERMINATING_UNREGISTERED — Specifies that the route header contains call=term_unregistered.

Superelements

session-case

match

Specifies the regular expression that a request-uri must match. The return value is the match of the first capturing group in the regular expression. For more information about regular expressions, see http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html.

The match element may have an optional prefix that is prepended to the return value.

Superelements

request-uri

Variables

The name, parameter, and return attributes and the exist and notexist elements in the data centric rules file use variables. Variables containing the string resolve contain values retrieved by performing ENUM lookups of TEL URIs. Some variables contain replaceable text. For example, in the request.header variable, the header is replaced by the name of a SIP or HTTP header. The syntax for matching SIP and HTTP requests is slightly different.

The following SIP variables are supported:

request.uri
request.uri.scheme
request.uri.user
request.uri.host
request.uri.port
request.method

request.uri.resolve
request.uri.resolve.user
request.uri.resolve.host

request.header
request.header.uri
request.header.uri.scheme
request.header.uri.user
request.header.uri.host
request.header.uri.port
request.header.uri.display-name

request.header.uri.resolve
request.header.uri.resolve.user
request.header.uri.resolve.host

request.header.match
request.header.match.resolve.user

match
match.resolve.user

The following HTTP variables are supported:

request.header
request.header.uri
request.header.uri.user
request.header.uri.host
request.header.uri.resolve
request.header.uri.resolve.user
request.header.uri.resolve.host

parameter.parameter
parameter.parameter.uri
parameter.parameter.uri.user
parameter.parameter.uri.host
parameter.parameter.uri.resolve
parameter.parameter.uri.resolve.user
parameter.parameter.uri.resolve.host

match
match.resolve.user

cookie.cookie-name

The resolution of the HTTP variable parameter.parameter.uri.resolve.user is complex. The variable matches a parameter value in an HTTP request, and this value may be a single name-addr or a comma-separated sequence of them. The name-addr elements are resolved until a usable user centric hash key is found. The order of resolution is as follows:

1. If a name-addr contains a user=phone parameter, it is resolved as a TEL URL, otherwise the user part of the URI is extracted. Resolution of a SIP URI may thus fail if it specifies a telephone number entity that cannot be resolved by ENUM, or else because there is no user part present in the SIP URI.

2. If all SIP URIs have been considered, a second attempt is made, and the TEL URLs are read from left to right. Evaluation stops as soon as a usable user centric key has been found.

3. If every resolution attempt fails, no user centric key is found. If an HTTP request doesn't match any DCR file rules, a hash key is generated using the remote host and port. If a SIP request doesn't match any DCR file rules, a hash key is generated using from-tag,call-id.

For example, if the variable is parameter.from.uri.resolve.user and the HTTP request is GET ...?...&from=...&...HTTP/1.1, the outcome may be according to the values in the following table. Some of the characters in the examples may in reality need to be URL-encoded (< would appear as %3C and so on.)

<sip:server.xx.yy>

<sip:alice@server.xx.yy>

<tel:+1-333-555>,<sip:+1-22-22@server.xx.yy;user=phone>

Setting the Data Centric Rules File for a Converged Load Balancer

The following tasks use the Admin Console or the CLI to set a data centric rules file for a converged load balancer.

To Set the Data Centric Rules File Using the Admin Console

1. Create the data centric rules file.

2. Log in to the Admin Console.

   In you browser, type http://hostname:port

3. In the left-hand pane, click Converged Load Balancer.

4. Select a Converged Load Balancer from the list of Converged Load Balancers.

   The Settings page appears. The DCR File Settings section in this page displays the current data centric rules file.

5. In the Upload DCR File field, click Browse to upload the data centric rules XML or JAR file you have created.

   ---

   Note –

   Communications Server does not expect the file extension to be case-sensitive.

   ---

6. Click Save.

To Set the Data Centric Rules File Using CLI

1. Create the data centric rules file.

2. To set the XML or JAR file as the data centric rules file for Communications Server, use the asadmin set-dcr-file command.

   The following are sample commands:

   asadmin set-dcr-file --host myhost --port 4850 --clbconfig my-cluster-config mydcrfile.jar

   asadmin set-dcr-file --host myhost --port 4850 --clbconfig my-cluster-config mydcrfile.xml

Load Balancers with Enterprise Server and Communications Server

The converged load balancer is part of the Communications Server distribution. The HTTP load balancing plug-in is bundled with Sun GlassFish Enterprise Server with HADB bundle. The HTTP load balancing plug-in is also available as a separate download from http://glassfish.dev.java.net

HTTP Load Balancer and Converged Load Balancer

For pure web application enterprise deployments , use the HTTP load balancing plug-in with Sun GlassFish Enterprise Server 2.1. Sun GlassFish Communication Server with the Converged Load Balancer is targeted at enterprise deployments of SIP and converged applications.