This chapter describes managing Oracle Communications WebRTC Session Controller domain services using the Administration Console and WebLogic Scripting Tool (WLST).
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:
Ensure that your WebLogic Administration Server is running.
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.
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 | Sub Tab | 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. |
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:
Locate the Change Center in the upper left corner of the Administration Console.
Click Lock & Edit to lock the editable configuration hierarchy for the domain.
Make the changes you want on the relevant page of the console and click Save on each page where you make a change.
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.
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:
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.
This section provides information on configuring the WebRTC Session Controller SIP container using WLST.
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 |
---|---|
|
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. |
|
Navigate the hierarchy of configuration or run-time beans. |
|
Connect WLST to a WebLogic Server instance. |
|
Starts an 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 If you attempt to call |
|
Set the specified attribute value for the current configuration bean. |
|
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:
Call startEdit() to obtain a lock on the active configuration.
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.
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".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 |
---|---|---|
|
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: |
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.
This section provides information on configuring the WebRTC Session Controller application using WLST.
Table 3-4 summarizes the WebRTC Session Controller methods included in ConfigAdminMBean.
Table 3-4 WebRTC Session Controller ConfigAdminMBean Method Summary
Method Name | Description |
---|---|
|
Commits a configuration update transaction. |
|
Exports the whole wsc configuration, to a specified path. |
|
Gets current lock if one exist. The request fails if the lock is owned by another user. |
|
Imports the whole wsc configuration from the specified path. |
|
Checks if the configuration is locked (by any user). |
|
Begins the configuration update transaction. |
|
Reverts a configuration update transaction. |
|
Validates the transaction. |
|
Validates all the scripts. |
|
Validates all the Media Engines and checks to see if they are reachable from the Signaling Engine. |
|
Validates a particular script. |
|
Validates the script libraries. |
Table 3-5 lists the configuration MBeans for WebRTC Session Controller.
Table 3-5 WebRTC Session Controller Configuration MBeans
MBean | Description |
---|---|
|
WebRTC Session Controller application configuration MBean. This MBean allows you to do the following for an application profile: add a library, add or clone a package, add package methods; get and set parameters in the application profile, such as the name, description, request URI. |
|
Media Engine configuration MBean. This MBean provides access to the address, port, and state of the Media Engine. |
|
Media Engine configuration MBean. This MBean provides access to the media agent notifications, user name, password. |
|
Client applications MBean. This MBean is used to create an application, delete an application given its appId, and retrieve an array of applications. |
|
Client application settings configuration MBean This MBean is used to access to the parameters displayed for a specific application. |
|
WebRTC Session Controller configuration administration MBean. This MBean is used to access to the general administration configuration parameters. |
|
Notification Service Configuration MBean This MBean is used to get and set the proxy IP address and proxy port of the notification service entry. |
|
WebRTC Session Controller package configuration MBean. This MBean is used to create and remove a script configuration, retrieve package name, and all scripts. |
|
Cloud Messaging provider Certificate Configuration MBean This MBean is used to create a provider certificate, delete a provider certificate given its name, and retrieve an array of provider certificates. |
|
Cloud Messaging provider Certificate MBean This MBean is used to set or retrieve the content, name and pass phrase of a provider certificate. |
|
WebRTC Session Controller resource limits configuration MBean. This MBean is used to set or retrieve the resource limits for the resource parameters of a resource limit entry. |
|
WebRTC Session Controller script library configuration MBean. This MBean is used to set or retrieve the script library macros and retrieve the type of a script library. |
|
WebRTC Session Controller script configuration MBean. This MBean is used to get the name, content, criteria, type, and method name of a script; and set the script content and criteria. |
|
WebRTC Session Controller application configuration MBean. This MBean is used to retrieve the runtime session statistics and watermarks. |
|
WebRTC Session Controller application configuration MBean. This MBean is used get and set the system integration parameters and media engine configurations |
|
WebRTC Session Controller application configuration MBean. This MBean is used get and set the parameters of a tenant profile. |
|
WebRTC Session Controller WebSocket configuration MBean. This MBean is used get and set the maximum allowed connections and the idle time out (in seconds). |
|
WebRTC Session Controller main configuration MBean. This MBean is used create and delete the main configuration settings in WebRTC Session Controller. |
See the oracle.wsc.core.configuration.admin.mbean package in 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.
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:
Connect to the WebLogic instance using WLST.
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
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
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.
Manage the tenant profile using WebLogic Scripting Tool:
WscConfigMbean
Use the following methods:
To create a tenant profile, use the createTenantProfile method. This method returns an ObjectName. A JMX client can access the TenantProfileMBean with this name entry.
To remove the tenant profile, use the removeTenantProfile method
ApplicationMbean:
Use the following methods:
To assign one or more tenant profiles to an application profile, call the setTenantProfile method.
To get a list of the tenant profiles assigned to the application profile, use the getTenantProfile method.
To assign one or more tenant profiles to an application profile, call the setTenantProfile method. The getTenantProfile method of the ApplicationMbean MBean returns the tenant profile.
To administer a tenant profile, access the TenantProfileMBean. You can get and set its elements such as the name, key, resource limits and the groovy properties associated with the tenant profile.
To generate the statistics for monitoring at system, application profile, and tenant profile levels, use the methods in the StatisticsRuntimeMBean.
For more information on accessing these MBeans, see WebRTC Session Controller Configuration API Reference.
The following sections provide example WLST scripts and commands for configuring SIP Servlet container properties.
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:
Set your WebRTC Session Controller environment:
cd ~/domain_home/bin
./setDomainEnv.sh
where domain_home is the path to the domain's home directory.
Start WLST:
java weblogic.WLST
Connect to the Administration Server for your WebRTC Session Controller domain:
connect('system','weblogic','t3://myadminserver:port_number')
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()
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 WebRTC Session Controller JavaScript API Reference for more information.
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)
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:
Expand the Environment node in the Domain Structure tree.
Click Servers.
Click the name of the server you want to configure logging for in the Configuration tab.
In the right pane, click the Logging tab.
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:
Expand the SipServer node in the Domain Structure tree.
In the Configuration tab, click the Message Debug subtab.
Select the Enable Debug check box.
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.
Click Save to commit your changes.
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.
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:
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.
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
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.
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. |
WebRTC Session Controller |
-DallowSessionTransfer |
See "Supporting Session Rehydration for Device Handover Scenarios" for more information. |
WebRTC Session Controller |
-Doracle.wsc.stats=false |
See "Monitoring Statistics and Resource Limits" for more information. |
WebRTC Session Controller |
-Doracle.wsc.se-me-http=true |
See "Disabling the HTTPS Setting in WebLogic Server" 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. |
Your customer who is logged in to your application on one device (a cellphone) may move to another device (a laptop softphone) to continue the same activity in the same application. The shift of the application session from one device to another occurs due to the customer's actions in the personal, local, or wide area network.
The application Session (along with its subsessions) currently active in your application on one device belonging to your customer becomes active on your application on another device belonging to the same customer. In order to allow the same user or tenant to connect with the WSC server using the same WebSocket session Id, set the startup option allowSessionTransfer to true:
./startWeblogic.sh -DallowSessionTransfer=true
By default, this option is set to false and prevents the WSC server from rehydrating your application on the target device with the active session transferred from the original device.
For information about how the application session state information is transferred to another device, see "Handling Session Rehydration When the User Moves to Another Device" in WebRTC Session Controller Application Developer's Guide.
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.