Configuring and Managing WebLogic SIP Server

     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

As described in WebLogic SIP Server Configuration Overview, WebLogic SIP Server engine and data tier features are implemented using the sipserver J2EE application, and SIP Container configuration is managed by the config Web Application contained in sipserver, which contains the sipserver.xml file.

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:7001/console where address is the Administration Server's listen address and 7001 is the listen port.
  2. Expand the SIP Servers node in the left pane.
  3. Select the sipserver entry to display configuration and monitoring tabs in the right pane of the console.
  4. Note: In most cases your configuration will have only a single sipserver container beneath the SIP Servers node. Additional containers may be available when performing a production upgrade, as described in Upgrading Software and Converged Applications.

    The right pane of the console provides two levels of tabbed pages that are used for configuring and monitoring WebLogic SIP Server. Table 4-1 summarizes the available pages and provides links to additional information about configuring SIP container properties.

    Table 4-1 WebLogic SIP Server Configuration and Monitoring Pages
    Page
    Function
    Configuration->
    General
    Proxy
    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
    Monitoring->
    General
    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 Edit Configuration button. Locking a configuration prevents other Administrators from modifying the configuration at the same time. If you click Edit Configuration while another user has obtained a lock, you are unable to make configuration changes until the lock has been released.

If you obtain a lock on the configuration, you can change SIP Servlet container attribute values on multiple configuration pages as needed. You then have several options depending on whether you want to keep or discard the changes you have made. The available options are displayed as a series of buttons at the bottom of each configuration page:

Note that WebLogic SIP Server automatically saves the original boot configuration in the file sipserver.xml.booted in the sipserver/config subdirectory. 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. WLST is not distributed with WebLogic SIP Server, but can be downloaded from BEA's dev2dev site at https://submit-codesamples.projects.dev2dev.bea.com/servlets/Scarab?id=CS26. Documentation for WLST is included with the product download, and also at http://download.oracle.com/docs/cd/E13222_01/wls/docs90/config_scripting/index.html.
Note: Before using WLST to configure a WebLogic SIP Server domain, you must add to your classpath all JAR files in the APP-INF/lib directory of the sipserver application. By default these files are located in DOMAIN_DIR/sipserver/APP-INF/lib where DOMAIN_DIR is the root of your WebLogic SIP Server domain. The libraries are automatically added to your classpath using the setAdminClientEnv script, described in Invoking WLST.
Note: The APP-INF/lib classes are required in addition to the WLST JAR files described in the WLST documentation.

JMX configuration of the SIP Servlet container is managed by the configManagerRuntimeMBean. ConfigManagerRuntimeMBean manages tasks such as:

Although any JMX application can access the SIP container's configuration MBeans, all changes to those MBeans must be coordinated through ConfigManagerRuntimeMBean.

ConfigManagerRuntimeMBean Usage and Reference

Table 4-2 describes the methods provided by ConfigManagerRuntimeMBean.

Table 4-2 ConfigManagerRuntimeMBean 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 the config application.
save()
Writes the current configuration MBean attributes (the current SIP Servlet container configuration) to the sipserver.xml configuration file.
startEdit()
Locks changes to the active SIP Servlet container configuration. Other JMX application 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.
stopEdit()
Releases the lock obtained for modifying SIP container properties and rolls back any pending MBean changes.

A typical configuration session involves the following tasks (also summarized in Figure 4-1):

  1. Access the ConfigManagerRuntimeMBean for the WebLogic SIP Server instance that you want to configure and 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 ConfigManagerRuntimeMBean.save() to persist all changes to a temporary configuration file named sipserver.xml.saved, or
  4. Call ConfigManagerRuntimeMBean.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 config application.
  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.
    Figure 4-1 Typical ConfigManagerRuntimeMBean Workflow


    Typical ConfigManagerRuntimeMBean Workflow

Configuration MBeans for the SIP Servlet Container

ConfigManagerRuntimeMBean manages access to and persists the configuration MBean attributes described in Table 4-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 4-3 SIP Container Configuration MBeans
MBean Type
MBean Attributes
Description
ClusterToLoadBalancerMap
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 cluster-loadbalancer-map in the Configuration Reference Manual.
OverloadProtection
RegulationPolicy, ThresholdValue, ReleaseValue
Manages overload settings for throttling incoming SIP requests. See also overload in the Configuration Reference Manual.
Proxy
ProxyURIs, RoutingPolicy
Manages the URIs routing policies for proxy servers. See also proxy—Setting Up an Outbound Proxy Server in the Configuration Reference Manual.
SipSecurity
TrustedAuthenticationHosts
Defines trusted hosts for which authentication is not performed. See also sip-security in the Configuration Reference Manual.
SipServer
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, as well as ConfigManagerRuntimeMBean, are located in the "custom" MBean tree, accessed using the custom() command in WLST. Within the custom bean tree, individual configuration MBeans can be accessed using the path:

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

where:

Runtime MBeans, such as ConfigManagerRuntime, are accessed using the path:

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

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

custom()
cd(`mydomain:DomainConfig=mydomain,Location=myserver,Name=myserver,Type=Proxy')
ls()

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.

If no entries are present in sipserver.xml, only the SipServer and ConfigManagerRuntime MBean types are available for browsing.

 


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 along with the required WLST JAR files. Follow these steps:

  1. Set your WebLogic SIP Server client administration environment using a script installed with your domain:
  2. cd c:\bea\wlss220\server\bin
    .\setAdminClientEnv.cmd
  3. Add the required WLST JAR files to your class path:
  4. cd c:\wlst
    set CLASSPATH=%CLASSPATH%;c:\wlst\jython.jar;c:\wlst\wlst.jar
  5. Start WLST:
  6. java weblogic.WLST
  7. Connect to the Administration Server for your WebLogic SIP Server domain:
  8. 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 4-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 4-1 Template WLST Script for Accessing ConfigManagerRuntimeMBean
# 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 4-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 4-3, SIP Container Configuration MBeans, on page 4-7 for a listing of other helper methods in SipServer, or refer to the WebLogic SIP Server JavaDocs.

Listing 4-2 WLST Commands for Creating and Deleting MBeans
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. BEA provides a helper class, com.bea.wcp.sip.util.URIHelper, to help you easily generate URI objects from an array of Strings. Listing 4-3 modifies the sample shown in Listing 4-2, WLST Commands for Creating and Deleting MBeans, on page 4-11 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 4-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
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 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