Skip Headers

Oracle® Communication and Mobility Server Administrator's Guide 10g Release 3 (10.1.3) Part Number E12656-01 |
Home | Contents | Index | Contact Us

Previous | Next
| View PDF

# 5 Configuring High Availability

This chapter discusses configuring high availability through the following sections:

- "About Configuring High Availability"

- "Setting Up a Highly Available Cluster of OCMS Nodes"

- "Configuring the OCMS SIP Containers for High Availability"

- "Configuring the Edge Proxy Nodes for High Availability"

- "Configuring Highly Available SIP Servlet Applications"

- "Configuring an Overload Policy"

## About Configuring High Availability

OCMS provides high availability through redundancy, application state replication, and clustering. Highly available OCMS topologies are active-active, meaning that any redundant nodes actively function in the context of the topology. This makes OCMS scalable as well.

Figure 5-1 Highly Available OCMS Topology

Description of "Figure 5-1 Highly Available OCMS Topology"

A highly available OCMS topology (Figure 5-1) provides the following:

- Process death detection and automatic restart—Processes may die unexpectedly due to configuration or software problems. A proper process monitoring and restart system monitors all system processes constantly and restarts them if necessary.

- Clustering—Clustering components of a system together allows the components to be viewed functionally as a single entity from the perspective of a client for runtime processing and manageability. A cluster is a set of processes running on single or multiple computers that share the same workload. There is a close correlation between clustering and redundancy. A cluster provides redundancy for a system.

- Configuration management—A clustered group of similar components often need to share common configuration. Proper configuration management ensures that components provide the same reply to the same incoming request, allows these components to synchronize their configurations, and provides highly available configuration management for less administration downtime.

- State replication and routing—For stateful applications, client state can be replicated to enable stateful failover of requests in the event that processes servicing these requests fail.

- Server load balancing and failover—When multiple instances of identical server components are available, client requests to these components can be load balanced to ensure that the instances have roughly the same workload. With a load balancing mechanism in place, the instances are redundant. If any of the instances fails, then requests to the failed instance can be sent to the surviving instances.

Configuring a highly available OCMS environment involves the following main steps, depending on the OCMS topology you have chosen to deploy:

- Setting Up a Highly Available Cluster of OCMS Nodes—This involves associating each OCMS node with OPMN to form a manageable cluster.

- Configuring the OCMS SIP Containers for High Availability—Use the Application Server Control Console MBean browser to configure parameters affecting high availability in the SIP Servlet container.

- Configuring the Edge Proxy Nodes for High Availability—Optional. Required only if using Edge Proxy nodes in the OCMS topology.

- Configuring Highly Available SIP Servlet Applications—Edit the SIP Servlet application descriptor files to enable support for high availability. Configure state replication for each application.

- "Configuring an Overload Policy"—Optional. Required only if using the Proxy Registrar in the OCMS topology.

Table 5-1 Additional Information

For more information on... | See:
--- | ---
OCMS deployment topologies | Chapter 2, "Deployment Topologies" in this guide
OCMS installation | Oracle Communication and Mobility Server Installation Guide
Operating systems supported by highly available OCMS clusters | Oracle Communication and Mobility Server Certification Guide
Configuring a highly available clustered Oracle Application Server environment | The "Application Clustering" chapter in Containers for J2EE Configuration and Administration Guide. The "Active-Active Topologies" chapter in Oracle Application Server High Availability Guide.

## Setting Up a Highly Available Cluster of OCMS Nodes

Note:

If using UDP, place all servers on the same subnet or switch to avoid the defragmentation of large UDP packages.

Each OCMS node—including the Edge Proxy nodes—must be configured to support high availability.

Following are the main steps in setting up a cluster of OCMS servers:

1. Associating Nodes with OPMN—Oracle Process Manager and Notification Server provides a command-line interface for process control and monitoring for single or multiple Oracle Application Server components and instances. Using OPMN, you can start and stop each OCMS node and its sub-components.

2. Starting the Cluster—Starting the cluster with OPMN indicates that all OCMS nodes have been correctly associated with OPMN and are recognized as a cluster.

3. Verifying the Status of the Cluster—Using OPMN or Enterprise Manager, you can verify that each node in the cluster is up and running.

4. Stopping the Cluster—Having set up and verified the cluster of OCMS nodes, be sure to stop the cluster before configuring each SIP container for high availability (see "Configuring the OCMS SIP Containers for High Availability").

### Associating Nodes with OPMN

Setting up a cluster of OCMS nodes requires associating the nodes with OPMN. There are three ways to do this:

- Configuring the cluster during Oracle Application Server installation. For more information, refer to the Oracle Application Server Installation Guide.

- Associating Nodes with OPMN Using the Dynamic Discovery Method

- Associating Nodes with OPMN Using the Discovery Server Method

See also:

For more information regarding configuring and managing clusters using OPMN, see Oracle Process Manager and Notification Server Administrator's Guide.

#### Associating Nodes with OPMN Using the Dynamic Discovery Method

In this method -- one that is recommended by Oracle -- you define the same multicast address and port for each Oracle Application Server instance in the cluster. An advantage in using this method is that you do not have to specify the name of each Oracle Application Server instance in the cluster. Instead, you can dynamically add or remove instances from the cluster by editing the multicast address and port.

1. For each Oracle Application Server instance that you want to group in the same cluster, run the following command:

       $ORACLE_HOME/opmn/bin/opmnctl config topology update discover="*<multicastAddress>:<multicastPort>"

   For example:

       $ORACLE_HOME/opmn/bin/opmnctl config topology update
                              discover="*225.0.0.20:6200"

   where:

   - `multicastAddress` specifies the multicast address that you want to use for the cluster. The multicast address must be within the valid address range, which is 224.0.1.0 to 239.255.255.255. Note that the multicast address is preceded by an asterisk (*).

   - `multicastPort` can be any unused port number.

   Use the same multicast IP and port for all the instances.

2. On each Oracle Application Server instance where you ran the command in Step 1, run `opmnctl reload` so that OPMN reads the updated `opmn.xml` file.

       $ORACLE_HOME/opmn/bin/opmnctl reload

#### Associating Nodes with OPMN Using the Discovery Server Method

Although Oracle recommends associating nodes with OPMN using the dynamic discovery method, you can also define a cluster by specifying the names of the nodes running the Oracle Application Server instances in the `opmn.xml` file for each instance. For example, to cluster four instances (node1.example.com, node2.example.com, node3.example.com, node4.example.com), associate these nodes with OPMN using the discovery server method as follows:

1. Run Oracle Application Server on all nodes.

2. Designate one instance as the discovery server, which maintains the topology for the cluster. (In this example, node1.excample.com acts as the discovery server for the cluster.)

3. In the `opmn.xml` file for all instances in the cluster, specify the node that is running the discovery server (node1.example.com in Example 5-1). As illustrated in Example 5-1, the `opmn.xml` file includes the `<discover>` element. The `6200` value specifies the port number on which the notification server listens. Use the remote port number designated in the `<port>` sub-element of the `<notification-server>` element.

   Example 5-1 Designating an Instance as the Discovery Server

       <?xml version="1.0" encoding="UTF-8"?>
       <opmn xmlns="http://www.oracle.com/ias-instance">
          ...
          <notification-server interface="ipv4">
             <port local="6100" remote="6200" request="6003"/>
              ....
             <topology>
                <discover list="node1.example.com:6200"/>
             </topology>
             ...
          </notification-server>
          <process-manager>
          ...
          </process-manager>
       </opmn>

4. On all server instances, run `opmnctl reload` so that OPMN loads the updated `opmn.xml` file:

       $ORACLE_HOME/opmn/bin/opmnctl reload

### Starting the Cluster

To start the cluster using OPMN run the following command on each instance in the cluster:

    cd ORACLE_HOME/opmn/bin/
    $ORACLE_HOME/opmn/bin/opmnctl startall

### Verifying the Status of the Cluster

To verify the status of the OCMS nodes in the cluster:

1. In a Web browser, enter the URI of Enterprise Manager running on any SIP container in the cluster:

       http://<SIP container URI>:<port number>/em

2. Enter the administrator user name and password at the prompt.

   Enterprise Manager displays the status of the cluster topology.

### Stopping the Cluster

After verifying the status of the cluster, stop the nodes in the cluster using OPMN so that you can continue configuring the SIP containers (see "Configuring the OCMS SIP Containers for High Availability").

To stop OCMS, execute the following command on each node in the cluster:

    cd ORACLE_HOME/opmn/bin/
    $ORACLE_HOME/opmn/bin/opmnctl stopall

## Configuring the OCMS SIP Containers for High Availability

In the Application Server Control Console MBean browser, configure the following parameters under the MBean for each SIP Application Server node:

1. Configure the EdgeProxy parameter in the SIPContainer Mbean to point to the SIP URI of the Edge Proxy or to a third-party load balancer if more than one Edge Proxy is used.

   Use the following format:

       SIP:<Edge Proxy or Load Balancer IP address>:<port>;lr

2. Configure the DistributableRecordRoute parameter in the following format:

       SIP:<SIP Container IP address>:<port>

   Remove any appended transport methods (such as `transport=tcp`) to enable any type of transport to be used between the Edge Proxy and OCMS.

3. Configure the RecordRoute parameter using the following format:

       SIP:<SIP Container IP address>:<port>

   Remove any appended transport methods (such as `transport=tcp`) to enable any type of transport to be used between the Edge Proxy and OCMS.

## Configuring the Edge Proxy Nodes for High Availability

Note:

In the load balancer, you must disable stickiness for UDP datagrams sent to the Edge Proxy servers. Refer to the load balancer documentation for more information on disabling stickiness when sending datagrams over UDP.

To configure the Edge Proxy nodes for high availability:

- Configure each OCMS node running an Edge Proxy for high availability as described in "Setting Up a Highly Available Cluster of OCMS Nodes" and "Configuring the OCMS SIP Containers for High Availability".

- Point the edgeproxy parameter in the SIPContainer Mbean to one of the following:

  - The IP address of the Edge Proxy node.

  - For more than one Edge Proxy node -- The virtual IP address or host name of the third-party load balancer or DNS server if clients connect using DNS lookup.

  Note:

  When setting up OCMS in a high-availability environment with multiple Edge Proxy nodes and a load balancer, the SIP port for the Edge Proxy and the Virtual Server on the load balancer must be the same.

- Configure the interval at which SIP Container nodes ping the Edge Proxy nodes, as well as the number of missed ping intervals before the Edge Proxy nodes remove the unresponsive SIP Container from the routing table. These parameters enable the Edge Proxy node(s) to monitor the health of the SIP Container nodes.

For each Edge Proxy node in the topology, configure the following:

1. In the Application Server Control Console Mbean Browser, click the edgeproxy Mbean.

2. Configure the RecordRoute parameter to point to one of the following:

   - For a single Edge Proxy without a load balancer—Set the parameter to the IP address of the Edge Proxy node

   - For more than one Edge Proxy with a load balancer or DNS server—Set the parameter to the virtual IP address or host name of the third-party load balancer or DNS server (if clients connect using a DNS lookup)

3. Modify the `edgeproxy.xml` file (`sdp/edgeproxy/conf/edgeproxy.xml`, illustrated in Example 5-2) to include the `oc4j-ping` element:

       <oc4j-ping interval="1" allowed-miss-count="16"/>

   The `oc4j-ping` element configures the interval, in seconds, at which the Oracle Application Servers in the cluster ping the Edge Proxy. The `allowed-miss-count` attribute specifies the number of missed ping intervals allowed before the Edge Proxy removes an unresponsive Oracle Application Server from the routing table.

   Example 5-2 edgeproxy.xml

       <?xml version="1.0" encoding="UTF-8" ?>
       <edge-proxy xmlns:xsi="http://www.oracle.com/sdp">
            <record-route sip-uri="sip:%IPADDRESS%:%SIPPORT%"/>
            <jmx-rmi-connector port="%EPRMIPORT%"/>
            <oc4j-ping interval="1" allowed-miss-count="16"/>
            <nat-traverse enabled="true"/>
            <sip-stack ip="%IPADDRESS%">
                 <listening-point transport="tcp" port="%SIPPORT%" />
                 <listening-point transport="udp" port="%SIPPORT%" />
            </sip-stack>
       </edge-proxy>

4. In the `edgeproxy.xml` file, modify the `nat-traverse` element if necessary.

   - If the Edge Proxy enables SIP clients to traverse of NATs (Network Address Translators), then set the value to `true` (the default). The corresponding default value must be set in Oracle Communicator.

   - If NAT traversal is not used, then this attribute must be set to `false`. For more information disabling NAT traversal, see "Disabling NAT Traversal Enabled by the Edge Proxy".

5. Verify the status of the Edge Proxy node or nodes in the cluster by performing the following:

   - Starting the Cluster

   - Verifying the Status of the Cluster

For more information, refer to "Configuring OCMS in a Clustered Environment with Edge Proxy" in Oracle Communication and Mobility Server Installation Guide

### The NAT Traversal Option Enabled for the Edge Proxy

NAT traversal enables access to SIP User Agents even when they are located behind firewalls or NATs. To support SIP clients residing behind firewalls or NATs, proxy servers use the Path extension header mechanism (described in RFC 3327), which ensures that SIP clients follow specific paths that enable the traversal of NATs and firewalls throughout the network. When you enable the NAT traversal function in the Edge Proxy, an OCMS cluster supports the Path extension header mechanism by inserting a Path header field into REGISTER requests.

#### Disabling NAT Traversal Enabled by the Edge Proxy

By default, NAT traversal is enabled in `edgproxy.xml` (`nat-traverse enabled=true`, as noted in Example 5-2). To disable this function:

1. If the Edge Proxy is running, stop it by entering the following command:

       $ORACLE_HOME/opmn/bin/opmnctl stopproc process-type=EdgeProxy

2. Edit the `nat-traverse` element of `edgeproxy.xml` (located at ORACLE_HOME`/sdp/edgeproxy/conf/edgeproxy.xml`) as follows:

       <nat-traverse enabled="false"/>

3. Start the Edge Proxy using the following command:

       $ORACLE_HOME/opmn/bin/opmnctl startproc process-type=EdgeProxy

4. Repeat these steps for each Edge Proxy node in the OCMS cluster.

Caution:

When NAT traversal is enabled, the Edge Proxy nodes insert their local IP addresses into the RecordRoute headers of SIP requests. Therefore, the Edge Proxy nodes must be globally routable. This may not be the case if the cluster has been configured according to the white paper, Oracle Communication and Mobility Server in a High-Availability Environment Running with F5 BigIP (available at the Oracle Technology Network).

## Configuring Highly Available SIP Servlet Applications

This section describes how to configure high availability for SIP Servlet applications deployed to a cluster of OCMS nodes.

- Enabling High Availability in SIP Servlet Applications—Prior to deployment, each application's descriptor files (`web.xml` and `sip.xml`) must be configured for high availability. The `orion-application.xml` file for each application must also be configured for high availability.

- Configuring Application Session Data Replication—The session data of each SIP Servlet application can be replicated to other nodes in the cluster, in the event of node failure.

- Configuring High Availability for a Deployed SIP Servlet Application—You can also configure high availability for an application that you have already deployed.

- Disabling High Availability at the Application Level—You can remove support for high availability from your SIP Servlet applications.

- Upgrading SIP Servlet Applications in OCMS—This section explains how to perform a rolling upgrade on deployed SIP Servlet applications.

Notes:

- When configuring high availability for SIP Servlet applications that depend upon the Proxy Registrar, you must also configure the Proxy Registrar for high availability.

- High availability is not currently supported for converged applications (meaning applications comprised of both SIP and HTTP servlets).

### Enabling High Availability in SIP Servlet Applications

To configure a highly available SIP Servlet application:

1. Modify the `sip.xml` file (located at ORACLE_HOME`/j2ee/ocms/applications/<application name>/<web module name>/WEB-INF/sip.xml`) to include the `<distributable>` element.

   For example:

       <?xml version="1.0" encoding="UTF-8"?>
         <sip-app>
         <display-name>proxyregistrarssr</display-name>
          <distributable/>
       <!--Servlets-->
       <servlet>
         <servlet-name>Registrar</servlet-name>
         <servlet-class>oracle.sdp.registrar.VoipRegistrarServlet</servlet-class>
         <init-param>
           <param-name>LocationService</param-name>
           <param-value>oracle.sdp.locationdbservice.LocationDbServiceBD
           </param-value>
          </init-param>
         </servlet>
       </sip-app>

2. Modify the `web.xml` file (located at ORACLE_HOME`/j2ee/ocms/applications/<application name>/<web module name>/WEB-INF/web.xml`) to include the `<distributable>` element.

   For example:

       <?xml version="1.0" encoding="UTF-8"?>
       <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application
       2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
       <web-app>
            <display-name>proxyregistrarssr</display-name>
            <distributable/>
       </web-app>

3. Modify the `orion-application.xml` file (located at ORACLE_HOME`/j2ee/ocms/application-deployments/<application name>/orion-application.xml`) to include the `<cluster>` element which is used to configure clustering both for Oracle Application Server nodes as well as specific SIP servlet applications.

   For example:

       <orion-application ... >
          <cluster allow-colocation="false">
          ...
          </cluster>
       </orion-application>

   The `<cluster>` element, which is used in both `orion-application.xml` and `application.xml` files, includes the following sub-elements that control application replication:

   - `enabled`—Specifies whether clustering is enabled. The default value is `true`.

   - `group-name`—The name to use when establishing replication group channels. If not supplied, the application name as defined in `server.xml` (the Oracle Application Server configuration file) is used by default. New group channels are created for each enterprise application. If a value is specified, the application and all child applications use the channels associated with this group name.

   - `allow-colocation`—Specifies whether to allow application state to be replicated to a node residing on the same host machine. The default value is `true`.

     Note:

     Although the default value is `true`, set `allow-colocation` to `false` if multiple hosts are available. If multiple Oracle Application Server instances are instantiated on the same machine, specify different listener ports for each instance in the `default-web-site.xml`, `jms.xml`, and `rmi.xml` configuration files.

   - `write-quota`—The number of other group members to which the application state should replicate to. This attribute enables reducing overhead by limiting the number of nodes to which state is written. The default value is `1`.

     For additional information regarding the `<cluster>` element and its sub-elements, refer to the chapter "Configuring Application Clustering" in Containers for J2EE Configuration and Administration Guide.

     Note:

     Ensure that you use the correct spelling for attributes in the `orion-application.xml` file, as misspellings will not result in error messages. For example, if you misspell `start-port` in the cluster configuration section as `start-prt`, replication will appear to have started even though session replication does not work.

4. Repeat these steps for each application deployed on each OCMS instance.

Important:

Deploy the application symmetrically to all SIP application server nodes.

For information about developing highly available SIP Servlet applications, refer to Oracle Communication and Mobility Server Developer's Guide.

### Configuring Application Session Data Replication

OCMS supports multicast replication by defining the `orion-application.xml` file's `<cluster>` and `<property-config>` elements. The `<property-config>` element contains data required to use the JGroups group communication protocol to replicate session state across nodes in the cluster.

To set the replication policy, edit the ORACLE_HOME`/j2ee/ocms/application-deployments/<application name>/orion-application.xml` file as follows:

- Set the `<cluster>` element's `allow-colocation` attribute to `false.`

- Set the `<property-config>` element's `<url>` element to the path to the JGroup's XML file describing the application-related high-availability configuration (illustrated in Example 5-4).

  Example 5-3 Editing orion-application.xml File for Replication

      <orion-application ... >
         ...
         <cluster allow-colocation="false">
         ...
            <property-config>
               <url>file:///ORACLE_HOME/j2ee/ocms/application-deployments/
               <application name>/jgroups-tcp.xml</url>
            </property-config>
         </cluster>

Example 5-4 illustrates the JGroups XML file (referred to as `jgroups-tcp.xml`) in Example 5-3.

Example 5-4 A Sample JGroups Application High Availability Configuration File

    <config>
      <TCP/>
      <MPING mcast_addr="230.0.0.130" mcast_port="8500" ip_ttl="1"/>
      <MERGE2 min_interval="5000" max_interval="10000"/>
      <FD timeout="1000" max_tries="3" shun="false"/>
      <FD_SOCK/>
      <VERIFY_SUSPECT timeout="1000"/>
      <pbcast.NAKACK gc_lag="100" retransmit_timeout="3000"/>
      <pbcast.STABLE desired_avg_gossip="20000"/>
      <pbcast.GMS join_timeout="3000" join_retry_timeout="2000" shun="false"
      print_local_addr="true"/>
    </config>

In Example 5-4, failure detection (set by `<FD timeout>`) is set in milliseconds. In the sample JGroups file, it is set at 1000 milliseconds with three retries (`max_tries="3"`).

### Configuring High Availability for a Deployed SIP Servlet Application

Perform the following if the SIP Servlet application has already been developed and deployed, but not configured for high availability.

1. Undeploy the SIP Servlet application.

2. Unpack the application EAR.

3. Modify the `sip.xml` and `web.xml` files to include the `<distributable>` element, as described in "Enabling High Availability in SIP Servlet Applications". To edit the `sip.xml` and `web.xml` files, do the following:

   1. Create a new folder and name it `<Your SIP application>.`

   2. Unpack the EAR file to the new folder.

   3. Unpack the WAR file inside the EAR file to the folder `<Your SIP application>/<WAR module name>`.

   4. Edit the following files:

          <Your SIP application>/<WAR module name>/WEB-INF/sip.xml
          <Your SIP application>/<WAR module name>/WEB-INF/web.xml

   5. Under `<Your SIP application>/<WAR module name>`, re-package the contents of the WAR file using the original WAR file name. Replace the original WAR file with in the `<Your SIP application>` folder with the new one that you just created.

   6. Delete the `<Your SIP application>/<WAR module name>` folder.

   7. Package the contents of the `<Your SIP application>` into an EAR file. Use the file name of the original EAR file.

4. Re-deploy the application EAR to the SIP Servlet Container.

### Disabling High Availability at the Application Level

To remove an application from the cluster:

1. In a text editor, open the application-specific `orion-application.xml` file.

2. Set the `enabled` attribute of the `<cluster>` element to `false`. For more information, see "Configuring Application Session Data Replication".

   For example:

       <orion-application ... >
          ...
          <cluster enabled="false">
          ...
          </cluster>
       </orion-application>

3. Save the `orion-application.xml` file.

### Upgrading SIP Servlet Applications in OCMS

SIP Servlet applications can be upgraded using a rolling upgrade procedure that minimizes downtime.

To perform a rolling upgrade of a SIP servlet application in OCMS:

1. On the OCMS node where you want to upgrade the SIP Servlet application, execute the following command to stop running all OCMS processes on the node:

       $ORACLE_HOME/opmn/bin/opmnctl shutdown

2. Comment out the `<topology>` element in the ORACLE_HOME`/opmn/conf/opmn.xml` file to remove the SIP Application Server from the cluster.

3. Restart the SIP container by running the following command:

       $ORACLE_HOME/opmn/bin/opmnctl startall

4. Upgrade the SIP Servlet application on the SIP container you took out of the cluster.

5. Shut down the SIP container again so that you can put it back in the cluster:

       $ORACLE_HOME/opmn/bin/opmnctl shutdown

6. Uncomment the `<topology>` element in the `opmn.xml` file to place the SIP container back into the cluster.

7. Place the SIP container back into the cluster by executing the following command:

       $ORACLE_HOME/opmn/bin/opmnctl startall

   The SIP Servlet application upgrades following the completion of all in-progress calls.

8. Repeat the process with the remaining SIP containers.

## Configuring an Overload Policy

The Overload Policy enables OCMS to execute overload protection when capacity reaches high threshold levels. To configure this MBean, you first set the maximum value for number of SIP sessions (SipSessionTableMaxSize) and the maximum size for the Application (AppQueueMaxSize) and Network queues (StackQueueMaxSize) as described in Table 5-2). You then set the threshold values for each of these, as described in Configuring High and Low Thresholds.

In addition to the maximum values settings, the AllowedTrafficDuring503 attribute enables you to set the percentage of traffic allowed to pass through the system when it becomes overloaded and issues the 503 (Service Unavailable) error response to clients. The system does not process any new incoming requests if you set this attribute to zero (0), the default value.

Note:

Refer to the load figures displayed for the ApplicationPeakQueue, NetworkPeakQueue, Sessions, 503ResponseSent and MessagesDropped attributes of the SIP Servlet Container Monitor when setting these values.

Table 5-2 Default Values for SIP Sessions, Application and Network Queues

Attribute | Default Value
--- | ---
AppQueueMaxSize | 200
StackQueueMaxSize | 100
SipSessionTableMaxSize | 70000

Note:

Because of the internal use of the queues by OCMS, the actual peak values for the queues in an overload situation may exceed the maximum values configured in the Overload Policy.

### Overview of Overload Policy Architecture

The Overload Policy receives collectors and actions from the Policy Manager (the lookup service for collectors, actions and policies). The Policy Manager sends notifications to all observers when available collectors, actions, or policies have changed.

### Collectors

Collectors notify policies when states change. The Overload Policy subscribes to state changes for the following collectors:

- Memory Usage

- Application Queue

- Network Queue

- SIP Session Table Usage

Overview of Overload Policy

The Overload Policy implements the following default actions, for which it enacts an overload action when high threshold values are reached and then reverts this action when usage sinks to the low threshold value:

- Do not accept new connections: This overload action occurs when a high warning threshold value has been met.

- Send 503 (Service Unavailable) response on initial requests: This overload action occurs when a high alarm threshold value has been met.

- Stop reading from all connections: This overload action occurs when a high critical threshold has been met.

Configuring High and Low Thresholds

The Overload Policy MBean enables you to configure the high and low values for the Warning, Alarm and Critical levels for Memory Usage, Application Queue, Network Queue, and SIP Session Table Usage. At each level, there may be one or even several actions to execute if usage exceeds the specified threshold. When the high value set for a threshold is met, the Overload Policy calls overload actions. This value is the threshold at which these actions start. If usage drops to the low value set for a threshold, then the Overload Policy stops the overload action. For example, if a high level is set to 90 and low level is set to 80, overload actions that start when usage reaches 90% and are then stopped when usage drops back to 80%.

Starting and Stopping the Overload Policy

The start and stop operations for the Overload Policy MBean enable you manually start and stop the Overload Policy. To automatically start the Overload Policy at the startup of OCMS, set the Autostart attribute to true.

Memory Usage

The Memory Monitor reports memory usage to the Overload Policy. The usage is reported as percent of total memory. For example, if the Memory Monitor reports a value of 85, it means that 85% of total memory is currently in use and that 15% of it is free.

Using the Overload Policy MBean, you configure the Warning, Alarm and Critical threshold levels for the Overload Policy's memory usage. At each level, there may be one or several actions to execute if memory usage exceeds the specified threshold. The MBean enables you to set high and low threshold values for each of these levels. The high value is the threshold at which to start executing overload actions. The low level marks the threshold at which to stop executing the action. For example, if high level is set to 90 and low level is set to 80, the actions start when memory usage reaches 90% and then stop when memory usage drops to 80% again.

Delaying a Memory Overload Action

High and low levels keep overload actions from starting and stopping repeatedly for small changes in memory usage. In addition to the threshold level that sets the start of the executing actions, you can also configure a delay time (in seconds) for memory overload actions using the MemoryActionDelay attribute. When the high threshold is exceeded, a scheduled timer fires after the specified delay time (in seconds). Memory overload actions are not be executed before the delay time has passed, and if memory usage drops below high threshold during the delay time, the timer is canceled and no actions executes.

Configure the MemoryActionDelay attribute by entering the delay (in seconds) from the instance when the memory threshold value has been exceeded to the instant the actions are executed. The execution stops if the memory drops below the threshold during the delay. The value set for the delay must be greater than 0. The default value is 60 seconds.

Table 5-3 lists the attributes that you configure to set the values for the high and low warning thresholds for memory usage.

Table 5-3 Warning High and Low Thresholds for Memory Usage

Attribute | Description
--- | ---
MemoryWarningHigh | The high value for a warning threshold that triggers an overload action to decline new connections. This is the default overload action. The range of values is 0-100. 0 disables the action. The default value is 95.
MemoryWarningLow | The low value for a warning threshold that triggers an end to the overload action. The range of values is 0-100. The default value is 90.
MemoryWarningActions | A comma-separated list of actions performed when a memory warning level has been reached. The default value is oracle.sdp.networlayer.NetworkServiceImpl$StopAcceptAction.

Table 5-4 lists the attributes that you configure to set the high and low alarm thresholds for memory usage.

Table 5-4 The Alarm HIgh and Low Thresholds for Memory Usage

Attribute | Description
--- | ---
MemoryAlarmHigh | The high value for an alarm threshold for memory usage that triggers an action to send a 503 response (Service Unavailable) on initial requests. This is the default overload action. The range of values is 0-100. 0 disables the action. The default value is 95.
MemoryAlarmLow | The low value for the alarm threshold for memory usage that triggers an end to the overload action. The range of values is 0-100. The default value is 90.
MemoryAlarmActions | A comma-separated list of actions performed when a memory alarm threshold level has been reached. The default value is com.hotsip.jainsipimpl.javax.sip.context.SipContextImpl$Send503Action.

Table 5-5 lists the attributes that you configure to set the high and low critical thresholds for memory usage.

Table 5-5 Critical High and Low Thresholds for Memory Usage

Attribute | Description
--- | ---
MemoryCriticalHigh | The high value for a critical threshold for memory usage that triggers an overload action to stop reading connections. This is the default overload action. The range of values is 0-100; 0 disables the action. The default value is 98.
MemoryCriticalLow | The value that triggers an end to the overload action when the low threshold for memory usage has been reached. The range of values is 0-100. The default value is 90.
MemoryCriticalActions | A comma-separated list of action performed when the critical threshold of memory usage has been reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopReadAction.

Application Queue

The Application Queue is the communication link between the network layer and the applications. An event is added to the Application Queue when network packages are framed and ready for application consumption after a session timer fires or other network related events occur. The network layer's EventNotifier reports Application Queue usage to the Overload Policy. This usage is reported as a percent of the total queue capacity. For example, if the EventNotifier reports a value of 85, it means that 85% of total queue capacity is currently used and that 15% of the queue is empty. The AppQueMaxSize attribute sets the capacity of the Application Queue. The default value is 200. This value must always be greater than zero.

The EventNotifier does not report every change in Application Queue usage to the Overload Policy: below 95%, every 5% change is reported (that is 0, 5, 10, 15 and so on). From 95% and above, every 1% change is reported (that is, 95, 96, 97 and so on). The Overload Policy MBean enables you to configure the Warning (Table 5-6), Alarm (Table 5-7), and Critical (Table 5-8) thresholds of the Application Queue.

Table 5-6 lists the attributes of the Overload Policy that enable you to set the high and low warning thresholds for the Application Queue usage.

Table 5-6 Warning High and Low Threshold and Actions for the Application Queue

Attribute | Value
--- | ---
AppQueueWarningHigh | The high threshold warning value for Application Queue usage that triggers an action to decline new connections. This is the default overload action. The range of values is 0-100. Selecting 0 disables the action. The default value is 70.
AppQueueWarningLow | The low threshold warning value for Application Queue usage that triggers an end to the overload action. The range of values is 0-100. The default value is 50.
AppQueueWarningActions | A comma-separated list of actions performed when a warning threshold for Application Queue usage has been reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopAcceptAction.

Table 5-7 lists the attributes of the Overload Policy that enable you to set the high and low alarm thresholds for the Application Queue usage.

Table 5-7 Alarm High and Low Threshold Actions for the Application Queue

Attribute | Description
--- | ---
AppQueueAlarmHigh | The high alarm threshold value for the Application Queue usage that triggers an overload action to send a 503 Response (Service Unavailable) to initial requests. (This is the default overload action.) The range of values is 0-100. 0 disables the action. The default value is 80.
AppQueueAlarmLow | The low alarm threshold value for Application Queue usage that triggers an end to the overload action. The range of values is 0-100. The default value is 60.
AppQueueAlarmActions | A comma-separated list of action performed when an alarm threshold is reached. The default value is com.hotsip.jainsipimpl.javax.sip.context.SipContextImpl$Send503Action.

Table 5-8 lists the attributes of the Overload Policy MBean that enable you to set the high and low critical thresholds for the Application Queue usage.

Table 5-8 Critical High and Low Threshold Actions for the Application Queue

Attribute | Description
--- | ---
AppQueueCriticalHigh | The high threshold value for Application Queue usage that triggers an overload action to stop reading connections. This is the default overload action. The range of values is 0-100; 0 disables the action. The default value is 90.
AppQueueCriticalLow | The low threshold value for Application Queue usage that triggers an end to the overload action. The range of values is 0-100. The default value is 70.
AppQueueCriticalActions | A comma-separated list of actions performed when a critical level is reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopReadAction.

Network Queue

The network layer deposits the incoming unframed data from the network into the Network Queue. The network layer's EventQueue reports the Network Queue usage to the Overload Policy. The usage is reported as a percent of the total queue capacity. For example, if the EventQueue reports a value of 85, it means that 85% of total queue capacity is currently in use and 15% of the queue is empty. The StackQueueMaxSize attribute sets the Network Queue capacity. The default value for this attribute is 100. The value must always be greater than zero.

The EventQueue does not report every change in queue usage to the Overload Policy. Below 95%, every 5% change is reported (that is, 0, 5, 10, 15 and so on). From 95% and above, every 1% change is reported (that is, 95, 96, 97 and so on). The Overload Policy MBean enables you to configure the Warning (Table 5-9), Alarm (Table 5-10), and Critical (Table 5-11) thresholds of the Network Queue.

Table 5-9 lists the attributes that you configure to set the high and low threshold values that trigger Warning actions.

Table 5-9 Warning High and Low Threshold Actions for the Network Queue

Attribute | Description
--- | ---
StackQueueWarningHigh | The high warning threshold value for Network Queue usage that triggers the overload action to decline new connections. This is the default overload action. The range of values is 0-100; 0 disables the action. The default value is 70.
StackQueueWarningLow | The low warning threshold value that trigger end to the overload action. The range of values is 0-100. The default value is 50.
StackQueueWarningActions | A comma-separated list of actions performed when a warning threshold is reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopAcceptAction.

Table 5-10 lists the attributes that you configure to set the high and low threshold values that trigger Alarm actions.

Table 5-10 Alarm High and Low Threshold Actions for the Network Queue

Attribute | Description
--- | ---
StackQueueAlarmHigh | The high alarm threshold for Network Queue usage that triggers an overload action to send a 503 (Service Unavailable) response to initial requests. This is the default action. The range of values is 0-100; 0 disables the action. The default value is 80.
StackQueueAlarmLow | The low alarm threshold for Network Queue usage that triggers an end to the overload action. The range of values is 0-100. The default value is 60.
StackAlarmQueueActions | A comma-separated list of actions performed when a threshold is reached. The default value is com.hotsip.jainsipimpl.javax.sip.context.SipContexImpl$Send503Action.

Table 5-11 lists the attributes that you configure to set the high and low values that trigger Critical actions.

Table 5-11 Critical High and Low Threshold Actions for the Network Queue

Attribute | Description
--- | ---
StackQueueCriticalHigh | The high critical threshold value for Network Queue usage that triggers an overload action to stop reading all connections. (This is the default overload action.) The range of values is 0-100. 0 disables the action. The default value is 90.
StackQueueCriticalLow | The low critical threshold value that triggers an end to the overload action. The range of values is 0-100. The default value is 70.
StackQueueCriticalActions | A comma-separated list of actions performed when a critical level is reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopReadAction.

SIP Session Table Usage

The SIP servlet engine's Application Manager reports SIP session table usage to the Overload Policy. The usage is reported as a percent of total table capacity. For example, if the Application Manager reports a value of 85, it means that 85% of total table capacity is currently in use and 15% of it is free. The SessionTableMaxSizeSip attribute sets the SIP session table capacity. The default value of this attribute is 70000. The value must be greater than zero.

Not every change in table usage is reported back to overload policy. Below 95%, every 5% change is reported (that is, 0, 5, 10, 15 an so on). From 95% and above, every 1% change is reported (that is, 95, 96, 97 and so on). The Overload Policy MBean enables you to configure the Warning (Table 5-12), Alarm (Table 5-13), and Critical (Table 5-14) thresholds that trigger overload actions.

Table 5-12 lists the attributes that you configure to set the warning thresholds.

Table 5-12 Warning High and Low Threshold Actions for SIP Session Table Usage

Attribute | Description
--- | ---
SipSessionWarningHigh | The high warning threshold value for SIP session table usage that triggers an overload action to decline new connections. This is the default overload action. The range of values is 0-100; 0 disables the action. The default value is 90.
SipSessionWarningLow | The low warning threshold that triggers an end to the overload action. The range of values is 0-100. The default value is 85.
SipSessionWarningActions | A comma-separated list of actions performed when a critical level is reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopAcceptAction.

Table 5-13 lists the attributes that you configure to set the alarm level thresholds.

Table 5-13 Alarm High and Low Threshold Actions for SIP Session Table Usage

Attribute | Description
--- | ---
SipSessionAlarmHigh | The high alarm threshold of SIP session table usage that triggers an overload action to send a 503 Response (Service Unavailable) to initial requests. This is the default overload action. The range of values is 0-100; 0 disables the action. The default value is 98.
SipSessionAlarmLow | The low alarm threshold of SIP session table usage that triggers an end to the overload action. The range of values is 0-100. The default value is 97.
SipSessionAlarmActions | A comma-separated list of actions performed when an alarm threshold is reached. The default value is com.hotsip.jainsipimpl.javax.sip.context.SipContextImpl$Send503Action.

Table 5-14 lists the attributes that you configure to set the critical thresholds.

Table 5-14 Critical Threshold Actions for SIP Session Table Usage

Attribute | Description
--- | ---
SipSessionCriticalHigh | The high critical threshold value for SIP session table usage that triggers an overload action to stop reading all connections. This is the default overload action. The range of values is 0-100; 0 disables the action. The default value is 100.
SipSessionCriticalLow | The low critical threshold for SIP session table usage that triggers an end to the overload action. The range of values is 0-100. The default value is 99.
SipSessionCriticalActions | A comma-separated list of actions performed when a critical level is reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopReadAction.

### Deactivating the Overload Protection for System Tuning

Technically, overload protection is always activated. When you tune the system, you can prevent overload actions from executing by doing either of the following:

- Disabling all of the rules by setting all of the trigger values to zero (0).

- Setting the AppQueueMaxSize, StackQueueMaxSize, and SipSessionTableMaxSize attributes to high numbers.