Configuration Guide

Configuring Engine Tier Container Properties

The following sections describe how to configure SIP Container features in the engine tier of a Oracle Communications Converged Application Server deployment:

Overview of SIP Container Configuration

You can configure SIP Container properties either by using a JMX utility such as the Administration Console or WebLogic Scripting Tool (WLST), or by programming a custom JMX application. Using the Administration Console to Configure Container Properties describes how to configure container properties using the Administration Console graphical user interface.

Configuring Container Properties Using WLST (JMX) describes how to directly access JMX MBeans to modify the container configuration. All examples use WLST to illustrate JMX access to the configuration MBeans.

Using the Administration Console to Configure Container Properties

The Administration Console included with Oracle Communications Converged Application Server enables you to configure and monitor core WebLogic Server functionality as well as the SIP Servlet container functionality provided with Oracle Communications Converged Application Server. To configure or monitor SIP Servlet features using the Administration Console:

Locking and Persisting the Configuration

In order to modify information on any of the Oracle Communications Converged Application Server configuration pages, you must first obtain a lock on the configuration by clicking the Lock & Edit button. Locking a configuration prevents other Administrators from modifying the configuration at the same time.

If you obtain a lock on the configuration, you can change SIP Servlet container attribute values on multiple configuration pages, saving the changes as needed. You then have two options depending on whether you want to keep or discard the changes you have made:

Note that Oracle Communications Converged Application Server automatically saves the original boot configuration in the file sipserver.xml.booted in the config/custom subdirectory of the domain directory. You can use this file to revert to the booted configuration if necessary to discard all configuration changes made since the server was started.

Configuring Container Properties Using WLST (JMX)

Managing Configuration Locks

Table 7-2 summarizes the WLST methods used to lock a configuration and apply changes.

A typical configuration session involves the following tasks:

Configuration MBeans for the SIP Servlet Container

ConfigManagerRuntimeMBean manages access to and persists the configuration MBean attributes described in Table 7-3. Although you can modify other configuration MBeans, such as WebLogic Server MBeans that manage resources such as network channels and other server properties, those MBeans are not managed by ConfigManagerRuntimeMBean.

Locating the Oracle Communications Converged Application Server MBeans

All SIP Servlet container configuration MBeans are located in the “serverConfig” MBean tree, accessed using the serverConfig() command in WLST. Within this bean tree, individual configuration MBeans can be accessed using the path:

CustomResources/sipserver/Resource/sipserver

For example, to browse the default Proxy MBean for a Oracle Communications Converged Application Server domain you would enter these WLST commands:

serverConfig()

cd(‘CustomResources/sipserver/Resource/sipserver/Proxy’)

ls()

Runtime MBeans, such as ConfigManagerRuntime, are accessed in the “custom” MBean tree, accessed using the custom() command in WLST. Runtime MBeans use the path:

mydomain:Location=myserver,Name=myserver,Type=mbeantype

Certain configuration settings, such as proxy and overload protection settings, are defined by default in sipserver.xml. Configuration MBeans are generated for these settings when you boot the associated server, so you can immediately browse the Proxy and OverloadProtection MBeans. Other configuration settings are not configured by default and you will need to create the associated MBeans before they can be accessed. See Creating and Deleting MBeans.

WLST Configuration Examples

The following sections provide example WLST scripts and commands for configuring SIP Servlet container properties.

Invoking WLST

To use WLST with Oracle Communications Converged Application Server, you must ensure that all Oracle Communications Converged Application Server JAR files are included in your classpath. Follow these steps:

WLST Template for Configuring Container Attributes

Because a typical configuration session involves accessing ConfigManagerRuntimeMBean twice—once for obtaining a lock on the configuration, and once for persisting the configuration and/or applying changes—JMX applications that manage container attributes generally have a similar structure. Listing 7-1 shows a WLST script that contains the common commands needed to access ConfigManagerRuntimeMBean. The example script modifies the proxy RoutingPolicy attribute, which is set to supplemental by default in new Oracle Communications Converged Application Server domains. You can use this listing as a basic template, modifying commands to access and modify the configuration MBeans as necessary.

# Connect to the Administration Server

connect('weblogic','weblogic','t3://localhost:7001')

# Navigate to ConfigManagerRuntimeMBean and start an edit session.

custom()

cd('mydomain:Location=myserver,Name=sipserver,ServerRuntime=myserver,Type=ConfigManagerRuntime')

cmo.startEdit()

# --MODIFY THIS SECTION AS NECESSARY--

# Edit SIP Servlet container configuration MBeans

cd('mydomain:DomainConfig=mydomain,Location=myserver,Name=myserver,SipServer=myserver,Type=Proxy')

set('RoutingPolicy','domain')

# Navigate to ConfigManagerRuntimeMBean and persist the configuration 

# to sipserver.xml

cd('mydomain:Location=myserver,Name=sipserver,ServerRuntime=myserver,Type=ConfigManagerRuntime')

cmo.activate()

Creating and Deleting MBeans

The SipServer MBean represents the entire contents of the sipserver.xml configuration file. In addition to having several attributes for configuring SIP timers and SIP application session timeouts, SipServer provides helper methods to help you create or delete MBeans representing proxy settings and overload protection controls.

Listing 7-2 shows an example of how to use the helper commands to create and delete configuration MBeans that configuration elements in sipserver.xml. See also Listing 7-3, SIP Container Configuration MBeans, on page 7-6 for a listing of other helper methods in SipServer, or refer to the Oracle Communications Converged Application Server JavaDocs.

connect()

custom()

cd('mydomain:Location=myserver,Name=sipserver,ServerRuntime=myserver,Type=ConfigManagerRuntime')

cmo.startEdit()

cd('mydomain:DomainConfig=mydomain,Location=myserver,Name=sipserver,ServerRuntime=myserver,Type=SipServer')

cmo.destroyOverloadProtection()

cmo.createProxy()

cd('mydomain:Location=myserver,Name=sipserver,ServerRuntime=myserver,Type=ConfigManagerRuntime')

cmo.save()

Working with URI Values

Configuration MBeans such as Proxy require URI objects passed as attribute values. Oracle provides a helper class, com.bea.wcp.sip.util.URIHelper, to help you easily generate URI objects from an array of Strings. Listing 7-3 modifies the sample shown in Listing 7-2, WLST Commands for Creating and Deleting MBeans, on page 7-10 to add a new URI attribute to the LoadBalancer MBean. See also the Oracle Communications Converged Application Server JavaDocs for a full reference to the URIHelper class.

# Import helper method for converting strings to URIs.

from com.bea.wcp.sip.util.URIHelper import stringToSipURIs

connect()

custom()

cd('mydomain:Location=myserver,Name=sipserver,ServerRuntime=myserver,Type=ConfigManagerRuntime')

cmo.startEdit()

cd('mydomain:DomainConfig=mydomain,Location=myserver,Name=sipserver,Type=SipServer')

cmo.createProxy()

cd('mydomain:DomainConfig=mydomain,Location=myserver,Name=sipserver,SipServer=sipserver,Type=Proxy')

stringarg = jarray.array([java.lang.String("sip://siplb.bea.com:5060")],java.lang.String)

uriarg = stringToSipURIs(stringarg)

set('ProxyURIs',uriarg)

cd('mydomain:Location=myserver,Name=sipserver,ServerRuntime=myserver,Type=ConfigManagerRuntime')

cmo.save()

Reverting to the Original Boot Configuration

When you boot the Administration Server for a Oracle Communications Converged Application Server domain, the server creates parses the current container configuration in sipserver.xml, and generates a copy of the initial configuration in a file named sipserver.xml.booted. This backup copy of the initial configuration is preserved until you next boot the server; modifying the configuration using JMX does not affect the backup copy.

If you modify the SIP Servlet container configuration and later decide to roll back the changes, copy the sipserver.xml.booted file over the current sipserver.xml file. Then reboot the server to apply the new configuration.

Configuring Timer Processing

As engine tier servers add new call state data to the SIP data tier, SIP data tier instances queue and maintain the complete list of SIP protocol timers and application timers associated with each call. Engine tier servers periodically poll partitions in the SIP data tier to determine which timers have expired, given the current time. By default, multiple engine tier polls to the SIP data tier are staggered to avoid contention on the timer tables. Engine tier servers then process all expired timers using threads allocated in the sip.timer.Default execute queue.

Configuring Timer Affinity (Optional)

With the default timer processing mechanism, a given engine tier server processes all timers that are currently due to fire, regardless of whether or not that engine was involved in processing the calls associated with those timers. However, some deployment scenarios require that a timer is processed on the same engine server that last modified the call associated with that timer. One example of this scenario is a hot standby system that maintains a secondary engine that should not process any call data until another engine fails. Oracle Communications Converged Application Server enables you to configure timer affinity in such scenarios.

When you enable timer affinity, replicas request that each engine tier server periodically poll the SIP data tier for processed timers. When polling the SIP data tier, an engine processes only those timers associated with calls that were last modified by that engine, or timers for calls that have no owner.

To enable timer affinity:

Note that the Enable Timer Affinity setting is persisted in sipserver.xml in the element, enable-timer-affinity.

Configuring NTP for Accurate SIP Timers

In order for the SIP protocol stack to function properly, all engine and SIP data tier servers must accurately synchronize their system clocks to a common time source, to within one or two milliseconds. Large differences in system clocks cause a number of severe problems such as:

Oracle recommends using a Network Time Protocol (NTP) client or daemon on each Oracle Communications Converged Application Server instance and synchronizing to a common NTP server.