2 Configuring SIP Servlet Container Properties

The following sections describe how to configure SIP Container features in the engine tier of an Oracle WebLogic Server SIP Container deployment:

2.1 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. Section 2.2, "Using the Administration Console to Configure Container Properties" describes how to configure container properties using the Administration Console graphical user interface.

Section 2.3, "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.

2.2 Using the Administration Console to Configure Container Properties

The Administration Console included with Oracle WebLogic SIP Container enables you to configure and monitor core WebLogic Server functionality as well as the SIP Servlet container functionality provided with Oracle WebLogic SIP Container. To configure or monitor SIP Servlet features using the Administration Console, see "Getting Started with Oracle WebLogic Server Administration Console" in Oracle Fusion Middleware Administrator's Guide.

Table 2-1 Oracle WebLogic Server SIP Container Configuration and Monitoring Pages

Page SubPage Function

Configuration

General

Configure SIP timer values, session timeout duration, default Oracle WebLogic Server SIP Container behavior (proxy or user agent), server header format, call state caching, DNS name resolution, timer affinity, domain aliases, rport support, and diagnostic image format.

Configuration

Application Router

Configure custom Application Router (AR) class name, configuration, or default application.

Configuration

Proxy

Configure proxy routing URIs and proxy policies.

Configuration

Overload Protection

Configure the conditions for enabling and disabling automatic overload controls.

Configuration

Message Debug

Enable or disable SIP message logging on a development system.

Configuration

SIP Security

Identify trusted hosts for which authentication is not performed.

Configuration

Persistence

Configure persistence options for storing long-lived session data in an RDBMS, or for replicating long-lived session data to a remote, geographically-redundant site.

Configuration

Data Tier

View the current configuration of SIP data tier servers. You can also add, delete and configure partitions here.

Configuration

LoadBalancer Map

Configure the mapping of multiple clusters to internal virtual IP addresses during a software upgrade.

Configuration

Targets

Configure the list of servers or clusters that receive the engine tier configuration. The target server list determines which servers and/or clusters provide SIP Servlet container functionality.

Configuration

Connection Pools

Configure connection reuse pools to minimize communication overhead with a Session Border Control (SBC) function or Serving Call Session Control Function (S-CSCF).

Monitoring

General

View runtime information about messages and sessions processed in engine tier servers.

Monitoring

SIP Applications

View runtime session information for deployed SIP applications.

Monitoring

Data Tier Information

View runtime information about the current status and the work performed by servers in the SIP data tier.


2.2.1 Locking and Persisting the Configuration

In order to modify information on any of the Oracle WebLogic Server SIP Container configuration pages, the configuration must be locked. Locking a configuration prevents other Administrators from modifying the configuration at the same time. Locking is automatically enabled in Production domains; it can be enabled or disabled in Development domains.

To make changes:

  1. Locate the Change Center in the upper left corner of the Administration Console.

  2. Click Lock & Edit to lock the editable configuration hierarchy for the domain. This enables you to make changes using the Administration Console.

  3. Make the changes you desire on the relevant page of the Console and click Save on each page where you make a change.

  4. When you have finished making all the desired changes, click Activate Changes in the Change Center.

Note:

Some changes you make in the Administration Console take place immediately when you activate them. Other changes require you to restart the server or module affected by the change. These latter changes are called non-dynamic changes. Non-dynamic changes are indicated in the Administration Console with a warning icon.

If an edit is made to a non-dynamic configuration setting, no edits to dynamic configuration settings will take effect until after you restart the server.

For more information on using Oracle WebLogic Server Administration Console, see Oracle Fusion Middleware Administrator's Guide.

2.3 Configuring Container Properties Using WLST (JMX)

The WebLogic Scripting Tool (WLST) is a utility that you can use to observe or modify JMX MBeans available on a WebLogic Server or Oracle WebLogic Server SIP Container instance. Full documentation for WLST is available in Oracle Fusion Middleware Oracle WebLogic Scripting Tool.

Before using WLST to configure a Oracle WebLogic Server SIP Container domain, set you environment to add required Oracle WebLogic Server SIP Container classes to your classpath. Use either a domain environment script or the setWLSEnv.sh script located in MIDDLEWARE_HOME/server/bin where MIDDLEWARE_HOME is the root of your Oracle WebLogic Server SIP Container installation.

2.3.1 Managing Configuration Locks

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

Table 2-2 MBean Method Summary

Method Description

activate

Writes the current configuration MBean attributes (the current SIP Servlet container configuration) to the sipserver.xml configuration file and applies changes to the running servers.

cancelEdit

Cancels an edit session, releasing the edit lock, and discarding all unsaved changes. This operation can be called by any user with administrator privileges, even if the user did not start the edit session.

cd

Navigate the hierarchy of configuration or runtime beans.

connect

Connect WLST to a WebLogic Server instance.

edit

Starts an edit session.

save

Writes the current configuration MBean attributes (the current SIP Servlet container configuration) to a temporary configuration file.

set

Set the specified attribute value for the current configuration bean.

stopEdit

Releases the lock obtained for modifying SIP container properties and rolls back any pending MBean changes, discarding any temporary files.


Here is an example of using the commands to modify the T1 Timer interval:

Example 2-1 Modifying T1 Timer Interval

connect()
edit()
cd('CustomResources/sipserver/Resource/sipserver')
set('T1TimeoutInterval',505)
activate()

2.3.2 Locating the Oracle WebLogic Server SIP Container 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 WebLogic Server SIP Container domain you would enter these WLST commands:

serverConfig()
cd('CustomResources/sipserver/Resource/sipserver/Proxy')
ls()

Runtime MBeans 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 Section 2.4.2, "Creating and Deleting MBeans".

2.4 WLST Configuration

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

2.4.1 Invoking WLST

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

  1. Set your Oracle WebLogic Server SIP Container environment:

    cd MIDDLEWARE_HOME/user_projects/domains/mydomain/bin
    ./setDomainEnv.sh
    
  2. Start WLST:

    java weblogic.WLST
    
  3. Connect to the Administration Server for your Oracle WebLogic Server SIP Container domain:

    connect('system','weblogic','t3://myadminserver:<portnumber>')
    

2.4.2 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. See Table 2-1, "Oracle WebLogic Server SIP Container Configuration and Monitoring Pages" for a listing of other helper methods in SipServer; see also Oracle Fusion Middleware Communication Services Java API Reference.

2.5 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.

2.5.1 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 WebLogic Server SIP Container 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.

Note:

When an engine tier server fails, any call states that were last modified by that engine no longer have an owner. Expired timers that have no owner are processed by the next engine server that polls the SIP data tier.

To enable timer affinity:

  1. Access the Administration Console for your domain.

  2. Click Lock & Edit (if enabled in your development environment) to obtain a configuration lock.

  3. Select the SipServer node in the left pane. The right pane of the console provides two levels of tabbed pages that are used for configuring and monitoring Oracle WebLogic Server SIP Container.

  4. Select the Configuration > General tab in the right pane.

  5. Select Enable Timer Affinity.

  6. Click Save to save your configuration changes.

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

2.5.2 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:

  • SIP timers firing prematurely on servers with fast clock settings.

  • Poor distribution of timer processing in the engine tier. For example, one engine tier server may process all expired timers, whereas other engine tier servers process no timers.

Oracle recommends using a Network Time Protocol (NTP) client or daemon on each Oracle WebLogic Server SIP Container instance and synchronizing to a common NTP server.

Caution:

You must accurately synchronize server system clocks to a common time source (to within one or two milliseconds) in order for the SIP protocol stack to function properly. Because the initial T1 timer value of 500 milliseconds controls the retransmission interval for INVITE request and responses, and also sets the initial values of other timers, even small differences in system clock settings can cause improper SIP protocol behavior. For example, an engine tier server with a system clock 250 milliseconds faster than other servers will process more expired timers than other engine tier servers, will cause retransmits to begin in half the allotted time, and may force messages to timeout prematurely.