2 Getting Started

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

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.

Note:
The default administration console port for Converged Application Server is 7001.
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, report support, diagnostic image format, stale session handling, Max-BreadthCheck Support, SIP outbound support, and automatic responses to a non-INVITE request.
Configuration	Application Router	Configure a custom Application Router (AR) type, use a JavaScript Object Notation (JSON) configuration file, and pass properties to an AR. 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	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 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 including general runtime information, SIP performance information, individual SIP application information and call state storage information.

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 "Using the WebLogic Server Administration Console" in Understanding Oracle WebLogic Server.

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, see "Using the WebLogic Scripting Tool" in Understanding the WebLogic Scripting Tool.

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

Configuration MBeans for the SIP Servlet Container

ConfigManagerRuntimeMBean manages access to and persists the configuration MBean attributes described in the com.bea.wcp.sip.management.descriptor.beans package of the Converged Application Server Java API Reference. 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.

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('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 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 Java API Reference.

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

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 Oracle Converged Application Server Java API Reference 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:

If your domain is running in Production mode, click Lock & Edit.
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.
If your domain is running in Production mode, click Activate Changes.
Restart the WebLogic Server.

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 "Monitoring, Tuning, and Troubleshooting the JVM" for suggestions about maximizing JVM performance in a production domain.

Caution:

When you configure a domain with multiple 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 Server Container Properties" for more information.

Because a typical Converged Application Server domain contains numerous engines, 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 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 the engine servers.

You generally start each SIP Coherence server by using either the startManagedWebLogic.sh script installed with the Configuration Wizard, or a custom startup script. The startManagedWebLogic.sh 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 engine0-0 t3://adminhost:7001
```

Following the above startup sequence ensures that all Managed Servers use the latest SIP Servlet container and Coherence cache configuration.

Startup Command Options

Table 2-2 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 "WLST Command and Variable Reference" in WLST Command Reference for WebLogic Server.

Table 2-2 Startup Command Options

Application	Startup Option	For More Information
Installer	-Djava.io.tmpdir	See the discussion about "Temporary Disk Space Requirements" in Fusion Middleware System Requirements and Specifications.
SIP Servlet Application Router	-Djavax.servlet.sip.ar.spi.SipApplicationRouterProvider	See "Configuring a Custom Application Router" in Converged Application Server Developer's Guide.
SIP Servlet Application Router	-Djavax.servlet.sip.dar.configuration	See "Using the Default Application Router" in Converged Application Server Developer's Guide.
Converged Application Server	-Dweblogic.management.discover	See "Restarting an Administration Server on the Same System".
Converged Application Server	-Dweblogic.RootDirectory	See "Restarting an Administration Server on Another System".
Converged Application Server	–Dwlss.dialog.index.enabled	See "Join and Replaces Header Support" in Converged Application Server Developer's Guide.
Converged Application Server	-Dwlss.local.serialization	See "Optimizing Memory Utilization and Performance with Serialization" in Converged Application Server Developer's Guide.
Converged Application Server	-Dwlss.sip.session.count.log_interval	See "Configuring the License Tracking as Startup Command Options".
Converged Application Server	-Dwlss.sip.session.count.start_time	See "Configuring the License Tracking as Startup Command Options".
Converged Application Server	-Dwlss.send100ForNonInviteTransaction	See the description about "Sending Provisional Responses to Non-Invite Requests" in Converged Application Server Developer's Guide.
Converged Application Server	-Dwlss.udp.lb.masquerade	See information about "Network Address Translation Options" in Converged Application Server Concepts.
Converged Application Server	-Dwlss.udp.listen.on.ephemeral	See information about "Single-NIC Configurations with TCP and UDP Channels" in Converged Application Server Concepts.

Reverting to the Original Boot Configuration

When you boot the Administration Server for a Converged Application Server domain, the server parses the current container configuration in sipserver.xml. It generates a copy of the initial configuration in a file named sipserver.xml.booted in the Domain_home/config/custom directory, where Domain_home is the directory in which the Converged Application Server domain resides. This backup 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.