3 Using the Administration Console and WLST

This chapter describes managing Oracle Communications WebRTC Session Controller domain services using the Administration Console and WebLogic Scripting Tool (WLST).

Accessing the Administration Console

The Administration Console enables you to configure and monitor core Oracle WebLogic Server functionality and the SIP Servlet container functionality provided with WebRTC Session Controller.

See Oracle WebLogic Server Administration Console Online Help for more information about the Administration Console.

To configure or monitor SIP Servlet features using the Administration Console:

1. Ensure that your WebLogic Administration Server is running.

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

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 WebRTC Session Controller. Table 3-1 summarizes the available pages and provides links to additional information about configuring SIP container properties.

Table 3-1 WebRTC Session Controller Configuration and Monitoring Pages

Tab	SubTab	Function
Configuration	General	Configure SIP timer values, session timeout duration, default WebRTC Session Controller behavior (proxy or user agent), server header format, call state caching, DNS name resolution, timer affinity, domain aliases, report support, diagnostic image format, and stale session handling.
Configuration	Application Router	WebRTC Session Controller does not use this configuration tab.
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	Call State Storage	View call state Coherence cache service configuration settings supported by the Sip Server. You can specify the number of worker threads and the number of partitions used in the call-state Coherence cache service by the Sip Server.
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 configuration. The target server list determines which servers and 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 run-time information about messages and sessions processed in engine servers.
Monitoring	SIP Performance	View run-time performance information on SIP traffic throughput and number of successful and failed transactions.
Monitoring	SIP Applications	View run-time session information for deployed SIP applications.
Monitoring	Call State Storage	View run-time state and statistics information about call-state service, the call-state cache, and the call-state metadata cache used by the SIP server.

Locking and Persisting the Configuration

The Administration Console Change Center provides a way to lock a domain configuration allowing configuration changes while preventing other administrators from making changes during your edit session. You can enable or disable this feature in development domains. It is disabled by default when you create a development domain.

See "Enable and disable the domain configuration lock" in the Oracle WebLogic Server Administration Console Online Help for more information on the domain configuration lock.

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 containing an exclamation point. 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.

To make changes to your WebRTC Session Controller domain when domain configuration lock is enabled:

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.

3. Make the changes you want 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 changes, click Activate Changes in the Change Center.

   Note:

   • You can instead discard your current changes by clicking Undo All Changes. This deletes any temporary configuration files that were written with previous Save operations.

   • If you need to discard all configuration changes made since the server was started, you can revert to the original boot configuration file. See "Reverting to the Original Boot Configuration" for more information.

Using WLST (JMX) to Configure WebRTC Session Controller

The WebLogic Scripting Tool (WLST) is a utility that you can use to monitor or modify JMX MBeans available on a WebLogic Server or WebRTC Session Controller instance. You use WLST to configure both the WebRTC Session Controller SIP container and application. The following sections describe configuring WebRTC Session Controller with WLST:

• Configuring the SIP Container with WLST

• Configuring the WebRTC Session Controller Application with WLST

For more information on using the WLST, see "Using the WebLogic Scripting Tool" in the Oracle WebLogic Scripting Tool documentation.

Before using WLST to configure a WebRTC Session Controller domain, set your environment to add required WebRTC Session Controller classes to your classpath. Use either a domain environment script or the setWLSEnv.sh script located in WL_home/server/bin where WL_home is the directory where WebLogic Server is installed.

Configuring the SIP Container with WLST

This section provides information on configuring the WebRTC Session Controller SIP container using WLST.

Managing Configuration Locks

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

Table 3-2 SIP Container 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 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 run-time 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.
startEdit()	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.
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.

A typical configuration session using WLST 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. Do one of the following:

   • Call save() to persist all changes to a temporary configuration file named sipserver.xml.saved

   • 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 server nodes.

     Note:

     When you start the Administration Server for a WebRTC Session Controller 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 3-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.

See "Configuring the WebRTC Session Controller Application with WLST" for information on MBeans used to configure WebRTC Session Controller application properties.

Table 3-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.
OverloadProtection	RegulationPolicy, ThresholdValue, ReleaseValue	Manages overload settings for throttling incoming SIP requests. See also "overload".
Proxy	ProxyURIs, RoutingPolicy	Manages the URIs routing policies for proxy servers. See also "proxy—Setting Up an Outbound Proxy Server".
SipSecurity	TrustedAuthenticationHosts	Defines trusted hosts for which authentication is not performed. See also "sip-security".
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 timer-b-timeout-interval timer-f-timeout-interval

Locating the 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 WebRTC Session Controller domain you would enter these WLST commands:

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

Run-time MBeans, such as ConfigManagerRuntime, are accessed in the custom MBean tree, accessed using the custom() command in WLST. Run-time 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. Starting an associated server generates Configuration MBeans for these settings. 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" for more information.

Configuring the WebRTC Session Controller Application with WLST

This section provides information on configuring the WebRTC Session Controller application using WLST.

Managing Configuration Locks

Table 3-4 summarizes the WebRTC Session Controller methods included in ConfigAdminMBean.

Table 3-4 WebRTC Session Controller ConfigAdminMBean Method Summary

Method	Description
lockAndEdit()	Begins the configuration update transaction.
isLocked()	Checks if the configuration is locked (by any user).
getCurrentLock()	Gets current lock if one exist. The request fails if the lock is owned by another user.
revert()	Reverts a configuration update transaction.
commit()	Commits a configuration update transaction.
validate()	Validates the transaction.
validateAllScripts()	Validates all the scripts.
validateScript()	Validates a particular script.
validateScriptLibrary()	Validates the script libraries.
validateMediaEngines()	Validates all the Media Engines and checks to see if they are reachable from the Signaling Engine.

Configuration MBeans for WebRTC Session Controller

Table 3-5 lists the configuration MBeans for WebRTC Session Controller. See the oracle.wsc.core.configuration.admin.mbean package in Oracle Communications WebRTC Session Controller Configuration API Reference for detailed information about each MBean.

See "Accessing WebRTC Session Controller Application MBeans" for information on how to access and use the WebRTC Session Controller MBeans.

Table 3-5 WebRTC Session Controller Configuration MBeans

MBean	Description
ApplicationMBean	WebRTC Session Controller application configuration MBean.
AscMBean	Media Engine configuration MBean.
AscMBeans	Media Engine configuration MBean.
ConfigAdminMBean	WebRTC Session Controller configuration administration MBean.
PackageMBean	WebRTC Session Controller package configuration MBean.
ResourceLimitsProfileMBean	WebRTC Session Controller resource limits configuration MBean.
ScriptLibraryMBean	WebRTC Session Controller script library configuration MBean.
ScriptMBean	WebRTC Session Controller script configuration MBean.
SystemConfigurationsMBean	WebRTC Session Controller application configuration MBean.
WebSocketMBean	WebRTC Session Controller WebSocket configuration MBean.
WscConfigMBean	WebRTC Session Controller main configuration MBean.

Accessing WebRTC Session Controller Application MBeans

You configure the WebRTC Session Controller MBeans using the Java MbeanServerConnection interface. Use the mbs variable at the WLST interface prompt to access the MBeans.

See the "WLST Variable Reference" in WLST Command Reference for WebLogic Server for information about the mbs variable.

To configure the WebRTC Session Controller MBeans using mbs:

1. Connect to the WebLogic instance using WLST.

2. Use the MBeanServerConnection to interact with the WebRTC Session Controller MBean server. See the following link for more information, including available methods, about MBeanServerConnection:

   http://docs.oracle.com/javase/7/docs/api/javax/management/MBeanServerConnection.html

3. Access the WebRTC Session Controller administration MBean, which is the root of all WebRTC Session Controller MBeans, using the following object name:

   oracle.wsc:Location=AdminServer,Type=ConfigAdminMBean
   

4. Use the getAttribute, setAttribute, and invoke operations to interact with the MBeans and configure the WebRTC Session Controller.

See "WebRTC Session Controller Code Sample" for an example showing how to use the MBeanServerConnection method to perform common configuration tasks.

WLST Configuration Examples

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

Invoking WLST

To use WLST with WebRTC Session Controller, you must ensure that all WebRTC Session Controller JAR files are included in your classpath. Follow these steps:

1. Set your WebRTC Session Controller environment:

   cd ~/domain_home/bin
   ./setDomainEnv.sh
   

   where domain_home is the path to the domain's home directory.

2. Start WLST:

   java weblogic.WLST
   

3. Connect to the Administration Server for your WebRTC Session Controller domain:

   connect('system','weblogic','t3://myadminserver:port_number')
   

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 or applying changes—JMX applications that manage container attributes generally have a similar structure.

Example 3-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 WebRTC Session Controller domains. You can use this listing as a basic template, modifying commands to access and modify the configuration MBeans as necessary.

Example 3-1 Template WLST Script for Accessing ConfigManagerRuntimeMBean

# Connect to the Administration Server
connect('username','password','t3://localhost:7001')
# Start an edit session
edit()
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')
# Commit changes
save()
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.

Example 3-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 Oracle Communications WebRTC Session Controller JavaScript API Reference for more information.

Example 3-2 WLST Commands for Creating and Deleting MBeans

connect('username','password','t3://localhost:7001')
edit()
startEdit()
cd('CustomResources/sipserver/Resource/sipserver')
cmo.destroyOverload()
cmo.createProxy()
save()
activate()

WebRTC Session Controller Code Sample

Oracle recommends using MBeanServerConnection (mbs) methods when using WLST to perform WebRTC Session Controller configuration instead of the built-in WLST operations. Example 3-3 provides sample code including how to connect to an administration server, lock configuration, retrieve and modify attributes, create test packages, and commit configurations using the mbs variable.

See "Accessing WebRTC Session Controller Application MBeans" for more information on using MBeanServerConnection.

Example 3-3 Connecting and Performing MBean Operations with mbs

# Connect to Admin Server
connect('username', 'password', 't3://127.0.0.1:7001')
 
# Lock configuration
noObjs = jarray.array([],java.lang.Object)
noStrs = jarray.array([],java.lang.String)
admin = ObjectName('oracle.wsc:Location=AdminServer,Type=ConfigAdminMBean')
myLock = mbs.invoke(admin, 'lockAndEdit', noObjs, noStrs)
 
# Get some attribute
mbs.getAttribute(myLock, 'Packages') 
 
# Change some attributes
myApp=ObjectName('oracle.wsc:Type=ApplicationMBean,Location=AdminServer,Name=unsecure,User=weblogic')
activeAttr=Attribute('Active', Boolean('false'))
mbs.setAttribute(myApp, activeAttr)
descAttr=Attribute('Description', 'Disabled this app')
mbs.setAttribute(myApp, descAttr)
 
# Create test package
packageObjs = jarray.array(['test-package'], java.lang.Object)
packageStrs = jarray.array(['java.lang.String'], java.lang.String)
myPackage = mbs.invoke(myLock, 'createPackage', packageObjs, packageStrs)
 
# Commit configuration
commitObjs = jarray.array([myLock], java.lang.Object)
commitStrs = jarray.array(['javax.management.ObjectName'], java.lang.String)
mbs.invoke(admin, 'commit', commitObjs, commitStrs)

Setting Logging Levels

The WebRTC Session Controller is subject to the common configuration settings defined for WebLogic servers. To modify the logging settings for a WebRTC Session Controller in the Administration Console, access the logging configuration settings page as follows:

1. Expand the Environment node in the Domain Structure tree.

2. Click Servers.

3. Click the name of the server you want to configure logging for in the Configuration tab.

4. In the right pane, click the Logging tab.

5. Modify the default logging settings and then click Save to commit your changes.

Alternatively, use the logging.xml WebLogic file to manually configure logging properties for the servers.

WebRTC Session Controller supports additional logging features that provide for SIP message logging. SIP message logging should be enabled in development environments only. It is not intended for production environments.

To configure SIP message logging:

1. Expand the SipServer node in the Domain Structure tree.

2. In the Configuration tab, click the Message Debug subtab.

3. Select the Enable Debug check box.

4. Configure other message logging settings as needed. Other settings include the logging verbosity level, the log entry pattern, and the target log file name. See the on-screen field description for more information.

5. Click Save to commit your changes.

6. Restart the WebLogic server.

See "Logging SIP Requests and Responses and EDRs" for information about creating custom log listeners and more information about logging settings.

Startup Sequence for a WebRTC Session Controller Domain

WebRTC Session Controller start scripts use default values for many JVM parameters that affect performance. For example, JVM garbage collection and heap size parameters may be omitted, or may use values that are acceptable only for evaluation or development purposes.

In a production system, you must rigorously profile your applications with different heap size and garbage collection settings to realize adequate performance. See "Modifying JVM Parameters in Server Start Scripts" in the chapter for suggestions about maximizing JVM performance in a production domain.

Caution:

When you configure a domain with multiple Signaling Engine servers, you must accurately synchronize all system clocks to a common time source (to within one or two milliseconds) in order for the SIP protocol stack to function properly. See "Configuring NTP for Accurate SIP Timers" for more information.

Because a typical WebRTC Session Controller domain contains numerous Signaling Engine and SIP call-state storage servers, with dependencies between the different server types, you should generally follow this sequence when starting up a domain:

1. Start the Administration Server for the domain.

   Start the Administration Server to provide the initial configuration to engine servers in the domain. The Administration Server can also be used to monitor the startup/shutdown status of each Managed Server.

   You generally start the Administration Server by using the startWebLogic.sh or startWebLogic.cmd script (depending on your operating system) installed with the Configuration Wizard, or a custom startup script.

2. Start SIP Coherence servers in each partition.

   The engine server cannot function until SIP Coherence servers are available to manage call state data. Although all replicas in each partition need not be available to begin processing requests, at least one replica in each configured partition must be available to manage the concurrent call state. All replicas should be started and available before opening the system to production network traffic.

   You generally start each SIP Coherence server by using either the startManagedWebLogic.cmd script installed with the Configuration Wizard, or a custom startup script. The startManagedWebLogic.cmd script requires that you specify the name of the server to start up and the URL of the Administration Server for the domain. For example:

   startManagedWebLogic.cmd datanode0-0 t3://adminhost:7001
   

3. Start engine servers.

   Start Signaling Engine servers and begin processing client requests. Signaling engine servers are generally started using the startManagedWebLogic.cmd script or a custom startup script.

Following the above startup sequence ensures that all Managed Servers use the latest SIP Servlet container and SIP Coherence configuration. This sequence also avoids engine error messages that are generated when SIP call-state storage is unavailable.

Startup Command Options

Table 3-6 lists startup options available to WebRTC Session Controller. For more information about these and other options, see "WebLogic Server Command-Line Reference" in the Command Reference for Oracle Weblogic Server documentation.

Table 3-6 Startup Command Options

Application	Startup Option	For More Information
WebRTC Session Controller	-Dwlss.udp.listen.on.ephemeral	See information about single network adapter card configurations with TCP and UDP channels in Oracle WebLogic Server SIP Container Administrator's Guide.
WebRTC Session Controller	-Dwlss.udp.lb.masquerade	See information about single network adapter card configurations with TCP and UDP channels in Oracle WebLogic Server SIP Container Administrator's Guide.
WebRTC Session Controller	-Dweblogic.management.discover	See "Restarting an Administration Server on the Same System" for more information.
WebRTC Session Controller	-Dweblogic.RootDirectory	See "Restarting an Administration Server on Another System" for more information.
Installer	-Djava.io.tmpdir	See the discussion on temporary disk space requirements in Installation Guide for Oracle WebLogic Server in the WebLogic Server documentation.

Reverting to the Original Boot Configuration

When you start the Administration Server for a WebRTC Session Controller 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 in the config/custom subdirectory of the domain directory. This backup copy of the initial configuration is preserved until you next start 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 restart the server to apply the new configuration.