Configuration Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Configuring Engine Tier Container Properties

The following sections describe how to configure SIP Container features in the engine tier of a WebLogic SIP 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 WebLogic SIP Server enables you to configure and monitor core WebLogic Server functionality as well as the SIP Servlet container functionality provided with WebLogic SIP Server. To configure or monitor SIP Servlet features using the Administration Console:

  1. Use your browser to access the URL http://address:port/console where address is the Administration Server’s listen address and port is the listen port.
  2. Select the SipServer node in the left pane.
  3. The right pane of the console provides two levels of tabbed pages that are used for configuring and monitoring WebLogic SIP Server. Table 6-1 summarizes the available pages and provides links to additional information about configuring SIP container properties.

    Table 6-1 WebLogic SIP Server Configuration and Monitoring Pages
    Overload Protection
    Configure the conditions for enabling and disabling automatic overload controls.
    Message Debug
    Enable or disable SIP message logging on a development system.
    SIP Security
    Identify trusted hosts for which authentication is not performed.
    Data Tier
    LoadBalancer Map
    Configure the mapping of multiple clusters to internal virtual IP addresses during a software upgrade.
    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.
    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).
    View runtime information about messages and sessions processed in engine tier servers.
    SIP Applications
    View runtime session information for deployed SIP applications.
    Data Tier Information
    View runtime information about the current status and the work performed by servers in the data tier.

Locking and Persisting the Configuration

In order to modify information on any of the WebLogic SIP 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 WebLogic SIP 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)

Notes: The WebLogic Scripting Tool (WLST) is a utility that you can use to observe or modify JMX MBeans available on a WebLogic Server or WebLogic SIP Server instance. Full documentation for WLST is available at
Note: Before using WLST to configure a WebLogic SIP Server domain, set you environment to add required WebLogic SIP Server classes to your classpath. Use either a domain environment script or the script located in WLSS_HOME/server/bin where WLSS_HOME is the root of your WebLogic SIP Server installation.

Managing Configuration Locks

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

Table 6-2 ConfigManagerRuntimeMBean Method Summary
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.
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.
Writes the current configuration MBean attributes (the current SIP Servlet container configuration) to a temporary configuration file.
Locks changes to the SIP Servlet container configuration. Other JMX applications cannot alter the configuration until you explicitly call stopEdit(), or until your edit session is terminated.
If you attempt to call startEdit() when another user has obtained the lock, you receive an error message that states the user who owns the lock.
Releases the lock obtained for modifying SIP container properties and rolls back any pending MBean changes, discarding any temporary files.

A typical configuration session involves the following tasks:

  1. Call startEdit() to obtain a lock on the active configuration.
  2. Modify existing SIP Servlet container configuration MBean attributes (or create or delete configuration MBeans) to modify the active configuration. See Configuration MBeans for the SIP Servlet Container for a summary of the configuration MBeans.
  3. Call save() to persist all changes to a temporary configuration file named sipserver.xml.saved, or
  4. Call activate() to persist changes to the sipserver.xml.saved file, rename sipserver.xml.saved to sipserver.xml (copying over the existing file), and apply changes to the running engine tier server nodes.
  5. Note: When you boot the Administration Server for a WebLogic SIP Server domain, the server parses the current container configuration in sipserver.xml and creates a copy of the initial configuration in a file named sipserver.xml.booted. You can use this copy to revert to the booted configuration, as described in Reverting to the Original Boot Configuration.

Configuration MBeans for the SIP Servlet Container

ConfigManagerRuntimeMBean manages access to and persists the configuration MBean attributes described in Table 6-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.

Table 6-3 SIP Container Configuration MBeans
MBean Type
MBean Attributes
ClusterName, LoadBalancerSipURI

Manages the mapping of multiple clusters to internal virtual IP addresses during a software upgrade. This attribute is not used during normal operations. See also Upgrading Software in the Operations Guide for more information.

RegulationPolicy, ThresholdValue, ReleaseValue
Manages overload settings for throttling incoming SIP requests. See also overload in the Configuration Reference Manual.
ProxyURIs, RoutingPolicy
Manages the URIs routing policies for proxy servers. See also proxy—Setting Up an Outbound Proxy Server in the Configuration Reference Manual.
Defines trusted hosts for which authentication is not performed. See also sip-security in the Configuration Reference Manual.
DefaultBehavior, EnableLocalDispatch, MaxApplicationSessionLifeTime, OverloadProtectionMBean, ProxyMBean, T1TimeoutInterval, T2TimeoutInterval, T4TimeoutInterval, TimerBTimeoutInterval, TimerFTimeoutInterval
SipServer also has several helper methods: createProxy(), destroyProxy(), createOverloadProtection(), destroyOverloadProtection(), createClusterToLoadBalancerMap(), destroyClusterToLoadBalancerMap()
Configuration MBean that represents the entire sipserver.xml configuration file. You can use this MBean to obtain and manage each of the individual MBeans described in this table, or to set SIP timer or SIP Session timeout values. See also Creating and Deleting MBeans, default-behavior, enable-local-dispatch, max-application-session-lifetime, t1-timeout-interval, t2-timeout-interval, t4-timeout-interval, timerB-timeout-interval, and timerF-timeout-interval in the Configuration Reference Manual.

Locating the WebLogic SIP 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:


For example, to browse the default Proxy MBean for a WebLogic SIP Server domain you would enter these WLST commands:


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


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 WebLogic SIP Server, you must ensure that all WebLogic SIP Server JAR files are included in your classpath. Follow these steps:

  1. Set your WebLogic SIP Server environment:
  2. cd ~/bea/sipserver31/server/bin
  3. Start WLST:
  4. java weblogic.WLST
  5. Connect to the Administration Server for your WebLogic SIP Server domain:
  6. connect('system','weblogic','t3://myadminserver:7001')

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 6-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 WebLogic SIP Server domains. You can use this listing as a basic template, modifying commands to access and modify the configuration MBeans as necessary.

Listing 6-1 Template WLST Script for Accessing ConfigManagerRuntimeMBean
# Connect to the Administration Server
# Navigate to ConfigManagerRuntimeMBean and start an edit session.
# Edit SIP Servlet container configuration MBeans
# Navigate to ConfigManagerRuntimeMBean and persist the configuration 
# to sipserver.xml

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 6-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 6-3, SIP Container Configuration MBeans, on page 6-6 for a listing of other helper methods in SipServer, or refer to the WebLogic SIP Server JavaDocs.

Listing 6-2 WLST Commands for Creating and Deleting MBeans

Working with URI Values

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

Listing 6-3 Invoking Helper Methods for Setting URI Attributes
# Import helper method for converting strings to URIs.
from com.bea.wcp.sip.util.URIHelper import stringToSipURIs
stringarg = jarray.array([java.lang.String("sip://")],java.lang.String)
uriarg = stringToSipURIs(stringarg)


Reverting to the Original Boot Configuration

When you boot the Administration Server for a WebLogic SIP 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 NTP for Accurate SIP Timers

As engine tier servers add new call state data to the data tier, 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 all partitions of the data tier to determine which timers have expired, given the current time. (Multiple engine tier polls to the data tier are staggered to avoid contention on the timer tables.) Engine tier servers then process expired timers using threads allocated in the sip.timer.Default execute queue.

In order for the SIP protocol stack to function properly, all engine and 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:

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

WARNING: 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.

  Back to Top       Previous  Next