2 Getting Started

This chapter describes how to start and stop servers in an Oracle Communications Converged Application Server domain:

Accessing the Administration Console
Using WLST (JMX) to Configure Converged Application Server
Setting Logging Levels
Startup Sequence for a Converged Application Server Domain
Startup Command Options
Reverting to the Original Boot Configuration

Accessing the Administration Console

The Administration Console enables you to configure and monitor core WebLogic Server functionality as well as the SIP Servlet container functionality provided with Converged Application Server. To configure or monitor SIP Servlet features using the Administration Console:

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 Converged Application Server. Table 2-1 summarizes the available pages and provides links to additional information about configuring SIP container properties.

Table 2-1 Converged Application Server Configuration and Monitoring Pages

Tab	SubTab	Function
Configuration	General	Configure SIP timer values, session timeout duration, default Converged Application Server 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. See "Composing SIP Applications" in Converged Application Server Developer's Guide.
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 Performance	View runtime performance information on SIP traffic throughput and number of successful and failed transactions.
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.

Locking and Persisting the Configuration

The Administration Console Change Center provides a way to lock a domain configuration so you can make 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 new development domain. See "Enable and disable the domain configuration lock" in the Administration Console Online Help for more information.

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.

For more information on using Oracle WebLogic Server Administration Console, see Administrator's Guide in the Oracle WebLogic Server 11g documentation.

To make changes:

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. This enables you to make changes using the Administration Console.
Make the changes you desire 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 desired 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 original boot configuration file. See "Reverting to the Original Boot Configuration" for more information.

Using WLST (JMX) to Configure Converged Application Server

The WebLogic Scripting Tool (WLST) is a utility that you can use to observe or modify JMX MBeans available on a WebLogic Server or Converged Application Server instance. To learn how to use WLST, refer to the Oracle WebLogic Scripting Tool documentation.

Before using WLST to configure a Converged Application Server domain, set your environment to add required Converged Application Server 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. The default WebLogic Server home directory is named wlserver_10.3.

Managing Configuration Locks

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

Table 2-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 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.
`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 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.
Call save() to persist all changes to a temporary configuration file named sipserver.xml.saved, or
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.

Note:
When you boot the Administration Server for a Converged Application 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 2-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 2-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 "Define the Cluster-to-Load Balancer Mapping" in Chapter 10, "Upgrading Production Converged Application Server Software."
OverloadProtection	RegulationPolicy, ThresholdValue, ReleaseValue	Manages overload settings for throttling incoming SIP requests. See also "overload" in Chapter 21, "Engine Tier Configuration Reference (sipserver.xml)."
Proxy	ProxyURIs, RoutingPolicy	Manages the URIs routing policies for proxy servers. See also "proxy—Setting Up an Outbound Proxy Server" in Chapter 21, "Engine Tier Configuration Reference (sipserver.xml)."
SipSecurity	TrustedAuthenticationHosts	Defines trusted hosts for which authentication is not performed. See also "sip-security" in Chapter 21, "Engine Tier Configuration Reference (sipserver.xml)."
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 Converged Application 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:

CustomResources/sipserver/Resource/sipserver

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

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

Runtime MBeans, such as ConfigManagerRuntime, 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 "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 Converged Application Server, you must ensure that all Converged Application Server JAR files are included in your classpath. Follow these steps:

Set your Converged Application Server 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 Converged Application Server 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 the configuration and/or applying changes—JMX applications that manage container attributes generally have a similar structure. Example 2-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 Converged Application Server domains. You can use this listing as a basic template, modifying commands to access and modify the configuration MBeans as necessary.

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

Example 2-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 Example 2-3, "Invoking Helper Methods for Setting URI Attributes" for a listing of other helper methods in SipServer, or refer to the Converged Application Server JavaDocs.

Example 2-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. Oracle provides a helper class, com.bea.wcp.sip.util.URIHelper, to help you easily generate URI objects from an array of Strings. Example 2-3 modifies the sample shown in Example 2-2 to add a new URI attribute to the LoadBalancer MBean. See also the Converged Application Server JavaDocs for a full reference to the URIHelper class.

Example 2-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()

Setting Logging Levels

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

Expand the Environment node in the Domain Structure tree.
Click Servers.
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.

Converged Application Server 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.

Configure SIP message logging as follows:

Expand the SipServer node in the Domain Structure tree.
In the Configuration tab, click the Message Debug subtab.
Select the Enable Debug checkbox.
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 onscreen field description for more information.
Click Save to commit your changes.

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

Startup Sequence for a Converged Application Server Domain

Converged Application Server 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 in order to realize adequate performance. See "Modifying JVM Parameters in Server Start Scripts" in the chapter "Tuning JVM Garbage Collection for Production Deployments" for suggestions about maximizing JVM performance in a production domain.

Caution:

When you configure a domain with multiple engine and SIP data tier 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" in Chapter 3, "Configuring Converged Application Container Properties" for more information.

Because a typical Converged Application Server domain contains numerous engine and SIP data tier 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 in order to provide the initial configuration to engine and SIP data tier 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 OS) installed with the Configuration Wizard, or a custom startup script.
Start SIP data tier servers in each partition. The engine tier cannot function until servers in the SIP data tier 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 in order 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 data tier server by using either the startManagedWebLogic.cmd script installed with the Configuration Wizard, or a custom startup script. startManagedWebLogic.cmd requires that you specify the name of the server to startup, as well as the URL of the Administration Server for the domain, as in:
```
startManagedWebLogic.cmd datanode0-0 t3://adminhost:7001
```
Start engine tier servers. After the SIP data tier servers have started, you can start servers in the engine tier and begin processing client requests. As with SIP data tier servers, engine tier 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 data tier configuration. This sequence also avoids engine tier error messages that are generated when servers in the SIP data tier are unavailable.

Startup Command Options

Table 2-4 lists startup options available to Oracle Communications Converged Application Server and other Converged Application Server utilities. For more information about these and other options, see Command Reference for Oracle WebLogic Server in the Oracle WebLogic Server 11g documentation.

Table 2-4 Startup Command Options

Application	Startup Option	For More Information
SIP Servlet Application Router	-Djavax.servlet.sip.dar.configuration	See "Using the Default Application Router" in "Composing SIP Applications" in Converged Application Server Developer's Guide.
SIP Servlet Application Router	-Djavax.servlet.sip.ar.spi.SipApplicationRouterProvider	See "Configuring a Custom Application Router" in "Composing SIP Applications" in Oracle Communications Converged Application Server Developer's Guide.
Converged Application Server	–Dwlss.dialog.index.enabled	See "Join and Replaces Header Support" in Oracle Communications Converged Application Server Developer's Guide.
Converged Application Server	-Dwlss.local.serialization	See "Optimizing Memory Utilization and Performance with Serialization" in Oracle Communications Converged Application Server Developer's Guide.
Converged Application Server	-Dwlss.udp.listen.on.ephemeral	See information about single-NIC configurations with TCP and UDP channels in Oracle Communications Converged Application Server Concepts.
Converged Application Server	-Dwlss.udp.lb.masquerade	See information about network address translation (NAT) options in Oracle Communications Converged Application Server Concepts.
Converged Application Server	-Dweblogic.management.discover	See "Restarting an Administration Server on the Same Machine" in Chapter 18, "Avoiding and Recovering From Server Failures."
Converged Application Server	-Dweblogic.RootDirectory	See "Restarting an Administration Server on Another Machine" in Chapter 18, "Avoiding and Recovering From Server Failures."
Installer	-Djava.io.tmpdir	See the discussion on temporary disk space requirements in Installation Guide for Oracle WebLogic Server in the WebLogic Server 11g documentation.
WlssEchoServer	-Dwlss.ha.echoserver.port	See "Starting WlssEchoServer on SIP Data Tier Server Machines" in Chapter 6, "Configuring Server Failure Detection."
WlssEchoServer	-Dwlss.ha.echoserver.logfile	See "Starting WlssEchoServer on SIP Data Tier Server Machines" in Chapter 6, "Configuring Server Failure Detection."
WlssEchoServer	-Dreplica.host.monitor.enabled	See "Enabling and Configuring the Heartbeat Mechanism on Servers" in Chapter 6, "Configuring Server Failure Detection."
WlssEchoServer	-Dwlss.ha.heartbeat.interval	See "Enabling and Configuring the Heartbeat Mechanism on Servers" in Chapter 6, "Configuring Server Failure Detection."
WlssEchoServer	-Dwlss.ha.heartbeat.count	See "Enabling and Configuring the Heartbeat Mechanism on Servers" in Chapter 6, "Configuring Server Failure Detection."
WlssEchoServer	-Dwlss.ha.heartbeat.SoTimeout	See "Enabling and Configuring the Heartbeat Mechanism on Servers" in Chapter 6, "Configuring Server Failure Detection."

Reverting to the Original Boot Configuration

When you boot the Administration Server for a Converged Application 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 in the config/custom subdirectory of the domain directory. 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.