| Oracle® Communications Converged Application Server Administration Guide Release 5.0 Part Number E17647-03 |
|
|
View PDF |
| Oracle® Communications Converged Application Server Administration Guide Release 5.0 Part Number E17647-03 |
|
|
View PDF |
This chapter describes how to configure SIP Container features in the engine tier of an Oracle Communications Converged Application Server deployment:
You can configure SIP Container properties either by using a JMX utility such as the Administration Console or WebLogic Scripting Tool (WLST), or by programming a custom JMX application. "Using the Administration Console to Configure Container Properties" describes how to configure container properties using the Administration Console graphical user interface.
"Configuring Container Properties Using WLST (JMX)" describes how to directly access JMX MBeans to modify the container configuration. All examples use WLST to illustrate JMX access to the configuration MBeans.
The Administration Console included with Converged Application Server 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 8-1 summarizes the available pages and provides links to additional information about configuring SIP container properties.
Table 8-1 Converged Application Server Configuration and Monitoring Pages
| Page | SubPage | 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 SIP Application Development 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. |
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.
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.
Table 8-2 summarizes the WLST methods used to lock a configuration and apply changes.
Table 8-2 ConfigManagerRuntimeMBean Method Summary
| Method | Description |
|---|---|
|
|
Writes the current configuration MBean attributes (the current SIP Servlet container configuration) to the |
|
|
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 runtime 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 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".ConfigManagerRuntimeMBean manages access to and persists the configuration MBean attributes described in Table 8-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 8-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. See also "Define the Cluster-to-Load Balancer Mapping" in Chapter 20, "Upgrading Converged Application Server Software." |
OverloadProtection |
RegulationPolicy, ThresholdValue, ReleaseValue |
Manages overload settings for throttling incoming SIP requests. See also "overload" in Chapter 30, "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 30, "Engine Tier Configuration Reference (sipserver.xml)." |
SipSecurity |
TrustedAuthenticationHosts |
Defines trusted hosts for which authentication is not performed. See also "sip-security" in Chapter 30, "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 |
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".
The following sections provide example WLST scripts and commands for configuring SIP Servlet container properties.
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')
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 8-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 8-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()
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 8-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 8-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 8-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()
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 8-3 modifies the sample shown in Example 8-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 8-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()
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.
The Administration Console exposes the Proxy Registrar MBean attributes that are used to set Proxy and Registrar parameters. Only those parameters and attributes that you typically need to set are exposed in the Administration Console. To modify advanced parameters and attributes, you can modify MBean attributes by using WebLogic Scripting Tool (WLST).
For information about the Proxy and Registrar MBeans, see the Converged Application Server Java API Reference.
Some Proxy Registrar configurations, such as security settings, require that you edit the sip.xml deployment descriptor. If you modify sip.xml, you must redeploy the Proxy Registrar for the changes to take effect.
Authentication for the Proxy and Registrar is defined in a security-constraint element in the sip.xml deployment descriptor. Proxy and Registrar authentication is enabled by default. You can disable authentication for the Proxy, Registrar, or both by removing their respective section from the security-constraint element:
To disable Registrar authentication, remove the registrar servlet section.
To disable Proxy authentication, remove the VoipProxy Servlet section.
The type of authentication for SIP requests is defined in the auth-method subelement of the login-config element in sip.xml. Converged Application Server supports DIGEST, BASIC and CLIENT-CERT authentications. DIGEST authentication is the default. For more information, see "Authentication for SIP Servlets" in Chapter 25, "Overview of Security Features."
You can also set the following authentication policy:
Trusted hosts:
You can bypass authentication for certain hosts by adding trusted-host definitions in the sip-security element. For more information, see "sip-security" in Chapter 30, "Engine Tier Configuration Reference (sipserver.xml)."
Note:
You can also configure trusted hosts by using the Administration Console. See "Using the Administration Console to Configure Trusted Hosts" for instructions.Identity assertion mode:
You can set the identity-assertion element in sip.xml to specify either P-Asserted-Identity or Identity.
For more information, see "Overview of SIP Servlet Identity Assertion Mechanisms" in Chapter 28, "Configuring Identity Assertion for SIP Servlets."
Security provider:
You configure security providers by using the Administration Console:
If you set the identity assertion mode to P-Asserted-Identity, then configure a P-Asserted-Identity Assertion Provider. Be sure to set its Trusted Hosts parameter.
If you set the identity assertion mode to Identity, then configure an Identity Header Assertion Provider.
For more information, see Chapter 28, "Configuring Identity Assertion for SIP Servlets."
You can specify to bypass authentication for certain hosts by adding trusted-host definitions through the Administration Console.
To add trusted hosts:
Log in to the Administration Console.
In the Domain Structure panel, click SipServer. The SIP Server configuration options are displayed in the main window.
Click the Configuration tab and then the SIP Security tab.
Enter any trusted hosts and click Save.
Stop and restart all servers in the domain. See Chapter 14, "Starting and Stopping Servers."
To configure the Proxy:
Log in to the Administration Console.
For information on using the Administration Console, see the WebLogic Server documentation.
In the Domain Structure panel, click ProxyRegistrar. The Proxy Registrar configuration options are displayed in the main window.
Click the Proxy tab.
Configure the following Proxy parameters:
Note:
Parameter that are preceded by an exclamation mark (!) indicate that you must restart the servers for the new value to take effect. Be sure to restart all servers in the domain to ensure that the new values are propagated to all servers. Chapter 14, "Starting and Stopping Servers."!Enable ENUM Lookup: Select this option to enable ENUM lookup. If ENUM lookup is disabled and the request URI is a Tel URL, then the request will be rejected with a 404 response.
!ENUM DNS Server: Specify the address of the DNS server.
!ENUM Zone: This is the DNS Zone used by ENUM. The default domain "e164.arpa" provides the infrastructure in the DNS for storage of E.164 numbers.
!ENUM SIP Service Field: Specify which service field of the DNS NAPTR record to retrieve. The default, E2U+sip, is the common value for SIP applications.
!ENUM Preset DNS Response: Specify a comma-separated list of predefined DNS responses. If you set this value, the Proxy does not consult the DNS server for ENUM lookup. Instead, the Proxy uses the ENUM Preset DNS Response value as the response from the DNS server.
Force Record Route: Select this option if you want all subsequent requests to go through the Proxy. The default is True.
Parallel Forking: Indicates whether a call that has more than one destination is routed to those destinations in parallel or sequentially. The default is parallel.
TimeOut Length: Specify the period in seconds that the Proxy waits for a final response to a request. The default is 180 seconds.
If Parallel Forking is set to sequential, the time-out period is the time the container waits for a final response from a branch before it CANCELs the branch and proxies the next destination in the target set.
If Parallel Forking is set to Parallel, the time-out period is time the container waits for final responses from the entire proxy (that is, all of the parallel branches) before it CANCELs the branches. With parallel forking, the container sends the best final response upstream.
!Hosted Domains: Only set this value if you set Use Domain Service to false. Specify a comma-separated list of the domain names for the domains hosted by this server. To specify any domain name, use an asterisk: *
!Use Domain Service: Select this option to use the Domain Service to determine which domains are hosted by the server. If set to false (not selected), then specify the domains in the Hosted Domains parameter to specify the domains.
Offline Code: Specify the status code that is returned when a SIP client is offline.
If needed, configure advanced parameters. You typically do not need to do this and can accept the default values.
At the bottom of the Proxy window, click Advanced to display the advanced parameters.
If needed, set the following parameters:
!Options: This specifies any option tags supported by the Proxy. When receiving a request that has a “Proxy-Require” header, all option tags listed in the “Proxy-Require” header must be specified in the Options field. If not specified, the proxy will reject the request with a 420 response. The value is a comma-separated list of options. For example, “privacy, sec-agree”.
!Location Service: Specify the location service class name.
Click Save.
If you changed the value of any parameter that requires restarting the server, stop and restart all servers in the domain. See Chapter 14, "Starting and Stopping Servers."
To configure the Registrar:
Log in to the Administration Console.
In the Domain Structure panel, click ProxyRegistrar. The Proxy Registrar configuration options are displayed in the main window.
Click the Registrar tab.
Configure the following Registrar parameters:
Note:
Parameter that are preceded by an exclamation mark (!) indicate that you must restart the servers for the new value to take effect. Be sure to restart all servers in the domain. See Chapter 14, "Starting and Stopping Servers."Max Contacts: Specifies the maximum allowed number of Contact headers in a REGISTER request and the maximum number of contacts that will be stored as a result of multiple REGISTER requests. The default is 5.
Max Expires: Specifies in seconds, the maximum allowed expiration time for registrations. If a request is made that exceeds this maximum, a response is sent that the time is too long. The default is 7200 seconds. Max Expires must be greater than the value of Min Expires.
Min Expires: Specifies in seconds, the minimum allowed expiration time for registrations. If a request is made that is shorter than this minimum, a response is sent that the time is too brief. The default is 60 seconds. Min Expires must be less than the value of Max Expires.
Default Expires: Specifies in seconds, the default expiration time for registrations. If an expiration time is not requested, the default is used. The default value is 3600 seconds. Default Expires must be greater than the value of Min Expires and less than the value of Max Expires.
Important:
The Administration Console does not validate that the expiration times are logically set. For example, if you set Default Expires to 3600 seconds and set Max Expires to 2700 seconds, the Administration Console will accept the configuration, but registrations may be denied.If needed, configure advanced parameters. You typically do not need to do this and can accept the default values.
At the bottom of the Registrar window, click Advanced to display the advanced parameters.
Set the following parameters:
Supported Methods: Specify the supported methods to insert into the Contact header of REGISTER request responses when the REGISTER request itself does not include supported methods in the Allow header or the Contact header.
The format of this value is the same as the methods parameter in the contact header.
Enable Associated ID: Indicates whether to add the P-Associated-URI header when the Registrar sends a response.
!Location Service House Keeper Period: The house keeper removes expired registrations. Specify in seconds, the period between house-keeper runs. A negative value means to run the house keeper only once, when the Proxy Registrar application is started. The default is 300 seconds.
!Location Service House Keeper Delay: Specify in seconds, the time to wait after the Proxy Registrar application is started, before the house keeper is started. A negative value turns off the house keeper. The default is 120 seconds.
!Location Service: Specify the location service class name.
Click Save.
If you changed the value of any parameter that requires restarting the server, stop and restart all servers in the domain. See Chapter 14, "Starting and Stopping Servers."
As engine tier servers add new call state data to the SIP data tier, SIP data tier instances queue and maintain the complete list of SIP protocol timers and application timers associated with each call. Engine tier servers periodically poll partitions in the SIP data tier to determine which timers have expired, given the current time. By default, multiple engine tier polls to the SIP data tier are staggered to avoid contention on the timer tables. Engine tier servers then process all expired timers using threads allocated in the sip.timer.Default execute queue.
With the default timer processing mechanism, a given engine tier server processes all timers that are currently due to fire, regardless of whether or not that engine was involved in processing the calls associated with those timers. However, some deployment scenarios require that a timer is processed on the same engine server that last modified the call associated with that timer. One example of this scenario is a hot standby system that maintains a secondary engine that should not process any call data until another engine fails. Converged Application Server enables you to configure timer affinity in such scenarios.
When you enable timer affinity, replicas request that each engine tier server periodically poll the SIP data tier for processed timers. When polling the SIP data tier, an engine processes only those timers associated with calls that were last modified by that engine, or timers for calls that have no owner.
Note:
When an engine tier server fails, any call states that were last modified by that engine no longer have an owner. Expired timers that have no owner are processed by the next engine server that polls the SIP data tier.To enable timer affinity:
Access the Administration Console for your domain.
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.
Select the Configuration > General tab in the right pane.
Select Enable Timer Affinity.
Click Save to save your configuration changes.
Click Activate Changes to apply your changes to the engine tier servers.
The Enable Timer Affinity setting is persisted in sipserver.xml in the enable-timer-affinity element.
In order for the SIP protocol stack to function properly, all engine and SIP data tier servers must accurately synchronize their system clocks to a common time source, to within one or two milliseconds. Large differences in system clocks cause a number of severe problems such as:
SIP timers firing prematurely on servers with fast clock settings.
Poor distribution of timer processing in the engine tier. For example, one engine tier server may process all expired timers, whereas other engine tier servers process no timers.
Oracle recommends using a Network Time Protocol (NTP) client or daemon on each Converged Application Server instance and synchronizing to a common NTP server.
Caution:
You must accurately synchronize server system clocks to a common time source (to within one or two milliseconds) in order for the SIP protocol stack to function properly. Because the initial T1 timer value of 500 milliseconds controls the retransmission interval for INVITE request and responses, and also sets the initial values of other timers, even small differences in system clock settings can cause improper SIP protocol behavior. For example, an engine tier server with a system clock 250 milliseconds faster than other servers will process more expired timers than other engine tier servers, will cause retransmits to begin in half the allotted time, and may force messages to timeout prematurely.Converged Application Server allows you to control third-party media servers using a Media Server Control API based on JSR 309, a standard Java interface. The JSR 309 specification defines a protocol agnostic API for controlling media servers. JSR 309 provides a portable interface to create media rich applications with interactive voice response (IVR), conferencing, speech recognition, and similar features. Vendors of IP media servers provide JSR 309 based driver implementations that work with their IP media servers.
See “Media Server Control” in the Converged Application Server Technical Product Description for more information about the Media Server Control feature. For information about JSR 309, see the JSR 309 specification at:
http://jcp.org/en/jsr/detail?id=309
To enable your converged SipServlet-Java EE applications deployed on the Converged Application Server to communicate with the media server using the Media Server Control API, you must configure Converged Application Server to recognize the custom, JSR 309 resource; install the Media Server Control driver; and configure the driver using the Administration Console.
For a standalone deployment of Converged Application Server, you must to install the Media Server Control driver on the Administration Server. For a replicated deployment, you must to install the Media Server Control driver on each engine in the Engine tier cluster.
Follow these steps to install the Media Server Control driver:
Shutdown all servers in the domain.
Copy the Media Server Control JAR file(s) to share into a lib subdirectory of the domain directory. For example:
CAS_home\user_projects\domains\domain_name\lib\
where CAS_home is the root directory where you installed Converged Application Server.
Note:
The Administration Server does not automatically distribute Media Server Control drivers to Managed Servers on remote machines. If you have Managed Servers that do not share the same physical domain directory as the Administration Server, you must manually install Media Server Control drivers to the CLASSPATH of each Managed Server.Alternatively, you can add the JAR file to the system or Converged Application Server classpath.
See the discussion on adding JARs to the system classpath in Developing Applications with WebLogic Server for more information about adding JAR files to the system or Converged Application Server classpath.
Start the Administration Server and all Managed Servers in the domain. Converged Application Server appends JAR files found in the lib directory to the system classpath.
When the Converged Application Server starts, you can configure the installed driver(s) using the Converged Application Server Administration Console. See "Configure the Media Server Control Factory" for more information.
The Media Server Control driver is not configured with a JSR 309 resource during the initial installation of the software. You must manually configure a custom JSR 309 resource for all servers in your Converged Application Server domain that will use the Media Server Control driver.
To configure the JSR 309 resource for deployments using Proxy Registrar domains:
Shutdown all servers in the domain.
Add the custom resource shown in the example below to the domain's config.xml file on the Administration Server. This example uses AdminServer as the target for the JSR309 resource. Specify the target parameters applicable to your Converged Application Server deployment.
<custom-resource>
<name>jsr309driveroam</name>
<target>AdminServer</target>
<descriptor-file-name>custom/jsr309driver.xml</descriptor-file-name>
<resource-class>
oracle.sdp.jsr309.configuration.resources.Jsr309Resource
</resource-class>
<descriptor-bean-class>
oracle.sdp.jsr309.configuration.beans.Jsr309ConfigurationBean
</descriptor-bean-class>
</custom-resource>
Start the Administration Server, and all instances of Managed Servers on which you will install a Media Server Control driver.
When the Converged Application Server starts, you can configure the installed driver(s) using the Converged Application Server Administration Console. See "Configure the Media Server Control Factory" for more information.
The mscontrol.jar and jsr309-descriptor-binding.jar JAR files are not added to the WebLogic CLASSPATH during installation. For this reason, you must manually add these JAR files to the CLASSPATH for your deployment. If you do not add these files to the CLASSPATH, the following exception is thrown during server start-up:
<Error> <netuix> <BEA-423168> <An exception or error occurred in the backing file [oracle.sdp.jsr309.console.util.JSR309NavTreeBac kingFile] while executing its init method. It was java.lang.NoClassDefFoundError : oracle/sdp/jsr309/configuration/resources/Jsr309Resource
To add the mscontrol.jar and jsr309-descriptor-binding.jar JAR files to the WebLogic CLASSPATH:
Shutdown all servers in the domain.
Modify the CLASSPATH variable of the startWebLogic script as follows:
For Windows-based operating systems:
Modify the startWebLogic.cmd script located at CAS_home\user_projects\domains\domain_name\bin as follows:
set CLASSPATH=%SAVE_CLASSPATH%; %ORCL_HOME%\server\modules\mscontrol.jar;% %ORCL_HOME%\server\lib\jsr309-descriptor-binding.jar
For UNIX-based operating systems:
Modify the startWebLogic.sh script located at CAS_home/user_projects/domains/domain_name/bin as follows:
CLASSPATH="${SAVE_CLASSPATH}:
${ORCL_HOME}/server/modules/mscontrol.jar:
${ORCL_HOME}/server/lib/jsr309-descriptor-binding.jar"
Add the custom resource shown in the example below to the domain's config.xml file on the Administration Server. This example uses AdminServer as the target for the JSR309 custom resource. Specify the target parameters applicable to your Converged Application Server deployment.
<custom-resource>
<name>jsr309driveroam</name>
<target>AdminServer</target>
<descriptor-file-name>custom/jsr309driver.xml</descriptor-file-name>
<resource-class>
oracle.sdp.jsr309.configuration.resources.Jsr309Resource
</resource-class>
<descriptor-bean-class>
oracle.sdp.jsr309.configuration.beans.Jsr309ConfigurationBean
</descriptor-bean-class>
</custom-resource>
Create an XML file called jsr309driver.xml with the following contents:
<?xml version='1.0' encoding='UTF-8'?> <jsr309-configuration xmlns="http://www.oracle.com/ns/occas/sdp/jsr309/100" xmlns:sec="http://xmlns.oracle.com/weblogic/security" xmlns:wls="http://xmlns.oracle.com/weblogic/security/wls" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> </jsr309-configuration>
Save the jsr309driver.xml file to the directory CAS_home/user_projects/domains/domain_name/config/custom (UNIX) or CAS_home\user_projects\domains\domain_name\config\custom (Windows) on your domain's Administration Server.
Start the Administration Server, and all instances of Managed Servers on which you will install a Media Server Control driver.
When the Converged Application Server starts, you can configure the installed driver(s) using the Converged Application Server Administration Console. See "Configure the Media Server Control Factory" for more information.
Follow these steps to configure the Media Server Control factory:
Access the WebLogic Server 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 Media Server Control in the Domain Structure navigation tree.
The Media Server Control Factory page displays any previously configured Media Server Control drivers.
Click New to create a new Media Server Control Factory.
Fill in the fields of the Create a Media Server Control Factory page as follows:
Factory name: The name to assign to the Media Server Control factory.
JNDI name: The JNDI name under which to create the Media Server Control factory. The JNDI name uniquely identifies this instance of the driver.
Observe the conventions of the Java Naming and Directory Interface (JNDI) service when you create JNDI factory names. The following naming conventions are supported for the JNDI name:
Only a-z, A-Z, 0-9,'_', '@' and '/' are valid characters for the JNDI name.
All other characters are treated as invalid, and will cause the configuration to fail.
'/' is treated as a subcontext character. For example, the name test1/test2/factory will be treated as a JNDI hierarchy.
When registering a JNDI name for the Media Server Control factory, Converged Application Server prepends the term mscontrol to the name. For example: mscontrol/mediasrv1
Driver name: Select a Media Server Control driver from the Driver list.
Click Next.
The properties of the Media Server Control configuration are displayed in an editable text field. You can edit this field to add new properties, or you can modify or delete an existing property.
The only property specified by the Media Server Control API is MEDIA_SERVER_URI, which defines the Uniform Resource Identifier (URI) of the media server. The URI is a string of characters used to identify a resource on the Internet. You can edit the MEDIA_SERVER_URI property with the URI of the media server to use in conjunction with Converged Application Server. While the MEDIA_SERVER_URI is an optional property, and may not be required by all media server vendors, Oracle recommends specifying a URI value whenever possible.
Note:
Certain properties defined by theMsControlFactory class are required to create a Media Server Control factory. If you delete a required property, the creation of the factory will fail.Click Finish.
A new Media Server Control factory instance that can be injected or looked up from inside your converged applications to communicate with the media server is created.
|
 Copyright © 2005, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|