| Oracle® Communication and Mobility Server Administrator Guide Release 10.1.3 Part Number B31497-01 |
|
|
View PDF |
| Oracle® Communication and Mobility Server Administrator Guide Release 10.1.3 Part Number B31497-01 |
|
|
View PDF |
This chapter, through the following sections, describes how to manage the OCMS SIP Server through Oracle 10g Enterprise Application Server Control.
The Oracle Sip Server is an OC4J container that you manage using the Oracle 10g Enterprise Manager Application Server Control console (Figure 9-1).
Figure 9-1 The Oracle 10g Enterprise Manager Application Server Control
In addition to the standard Application Server Control functions that enable starting, stopping, restarting, deploying, undeploying, and redeploying applications, the Application Server Control MBean browser enables you to configure and manage the OCMS components. Configuring the attributes of the OCMS MBeans (Managed Beans) enables you to execute administrative tasks and set the basic configuration (port, IP, and host address) of the OCMS SIP Server itself. In addition, the OCMS MBeans enables you to configure and manage presence.
Application Sever Control enables you to stop and restart The Oracle SIP Server. Like other OC4J containers, the OCMS SIP Servlet can be stopped and restarted using the Stop and Restart buttons on the Home page (Figure 9-1). These buttons control the entire OC4J instance; stopping or restarting OC4J also stops or restarts the OCMS SIP Servlet Container and the applications deployed to it. See also "Starting the SIP Servlet Container".
From the command line, you can invoke the start and stop scripts available under ORACLE_HOME/sdp/bin.
You can also stop or restart OC4J using the opmnctl or the admin_client.jar command-line utility to stop, start, or restart OC4J or its applications.
To stop all OPMN-managed processes including OC4J on a local Oracle Application Server instance using opmnctl:
opmnctl stopall
To stop the OC4J instance of OCMS on a local Oracle Application Server instance using opmnctl:
opmnctl stopproc process-type=ocms
To start all OPMN-managed processes, including OC4J, on a local Oracle Application Server instance using opmnctl:
cd ORACLE_HOME/opmn/bin opmnctl startall
To restart the OC4J instance of OCMS on a local Oracle Application Server instance using opmnctl:
cd ORACLE_HOME/opmn/bin opmnctl restartproc process-type=ocms
Use the following syntax when using admin_client.jar to start, stop or restart an application and its child applications on a specific OC4J instance or across an entire cluster.
java -jar admin_client.jar uri adminId adminPassword -start|-stop appName
For more information, see Oracle Application Server Administrator's Guide.
The Stop, Start and Restart buttons on the Applications page (Figure 9-2) control the running status for selected SIP Servlet applications.
Figure 9-2 The Applications Page of the Application Server Control
Note:
Changes made to the SIP Container applications persist when you restart OC4J; changes made to the logging do not persist.The Application Server Control Console's MBeans browser (Figure 9-3) enables you to view and configure MBeans. An MBean (managed bean) is a Java object that represents a JMX-manageable resource in a distributed environment, such as an application, a service, a component, or a device. MBeans expose a management interface, including a set of attributes and operations. This interface does not change during the lifetime of an MBean instance. MBeans can also send notifications when defined events occur.
The MBean attributes enable you to configure the OCMS SIP Server.
See Oracle Containers for J2EE Configuration and Administration Guide for information on managing MBeans.
The Application Server Control Console's MBean browser enable you to view, configure and deploy both system MBeans and application-defined MBeans.
To display the available System MBeans, the MBean Browser accesses the MBean Server that runs in OC4J. The available System MBeans display in the System MBean Browser.
In general, you access the MBeans related to the JSR 116-compliant OCMS SIP Servlet Container, a runtime environment for SIP applications that includes security, concurrency, life-cycle management, transaction, and other services through the System MBean Browser. For more information, see "Managing SIP Servlet Container MBeans".
The SIP Application-based MBeans do not display in the System MBean Browser; instead, they appear in the context of the application that registered them. For example, Figure 9-3 illustrates the MBeans registered by the Subscriber Data Services application.
Note:
MBeans are packaged with the application that they manage.The System MBean Browser enables you to browse the SIP Servlet Container MBeans (Figure 9-3). To access the System MBean Browser:
Navigate to the OC4J Home page for the SIP Server instance.
Click Administration. The Administration page appears, displaying the available tasks.
If needed, expand the JMX section of the task list to display System MBean Browser.
Click the Go to Task icon in the System Bean Browser row of the table. The System MBean Browser appears, displaying the available MBeans in the tree control. Selecting an MBean in the tree control enables you to view and edit its attributes, invoke its operations, and manage notification subscriptions. Click Apply to commit any changes to the MBean's parameters.
Figure 9-5 The JMX Section of the Task List
Tip:
Use the Search function to locate an MBeanTo view the MBeans for a selected application:
Click Applications on the SIP Server OC4J home page. A list of applications appears.
Click the Application Defined MBean icon for the selected application. The Application MBeans page appears. The tree control lists the MBeans registered to the application. Selecting an MBean in this tree control enables you to view its attributes, operations, statistics, and notifications.
Note:
The MBean attributes represent the getter and setter methods of the MBean operations.Click Apply to commit any changes to the MBean's attributes.
This section describes the configuration parameters for the following System MBeans:
Table 9-1 Sip Servlet Container-Related MBeans
| Tasks | MBean Name |
|---|---|
|
Tasks include:
|
|
|
Setting the log levels for the SDP callflow and the SDP core components (system, traffic, and JMX). For more information, see Chapter 10, "Configuring the Logging System". |
|
|
Setting bindings that enable clients to traverse NAT (Network Address Translating) entities. |
|
|
View the current statues of the system queues. |
|
|
Set overload actions when the capacity thresholds for memory usage, Application Queue usage, Network Queue usage, or SIP Session Table usage are reached. |
|
The SIP servlet container is a standalone Java process that provides the execution environment for the SIP applications. The attributes exposed by the SIP Servlet Container MBean enable you to change values that are set during the installation of OCMS (listed in Table 9-2). For more information on setting the values for these attributes during installation, refer to Oracle Communication and Mobility Server Installation Guide.
Table 9-2 Values Populated by Installation of OCMS
Table 9-3 describes the SIP Servlet Container MBean's attributes. While the format for entering values is sip:host:port;transport=tcp|udp for the following attributes, you generally need only enter the host value, as other values are pre-seeded.
Contact
DistributableContact
DistributableRecordRoute
DistributableVia
DnsIpAddress
DnsIpAddress
Via
Table 9-3 Attributes of the SIP Servlet Container
| Attribute | Value |
|---|---|
|
ApplicationAliases |
A short name for the application. For more information, see "Setting an Alias for an Application". |
|
Contact |
A comma-separated list of hostnames, ports, and transports used in the Contact header for non-distributable embeded in SIP requests by applications acting as User Agent Clients (UACs). For example, enter my.host, 5060, tcp. This contact information provides an address that enables the SIP Server to respond. |
|
DefaultApplications |
A comma-separated list of applications that are invoked if no application matches a request. By default, the Application Router is set as the default application. If many applications have been deployed to the SIP Container, you should also deploy an application dispatcher as the default application. The application dispatcher (or Application Router in OCMS) routes incoming requests to other applications by addressing them directly. For more information, see "Application Router" in " An Overview of Oracle Communication and Mobility Server". If no default application is set, then the container designates all of the SIP applications that it locates as the default application. For more information on default application and how the SIP container invokes servlets, see Servlet Mapping in Oracle Communication and Mobility Server Developer's Guide. |
|
DeployedApplications |
A read-only list of deployed applications. |
|
DistributableContact |
A comma-separated list of hosts, ports, and transports (such as my.cluster, 5060, tcp) placed in the Contact header for distributable applications acting as User Agent Clients (UACs) in a high-availability environment. |
|
DistributableRecordRoute |
A comma-separated list of hosts, ports, and transports (such as my.cluster, 5060, tcp) placed in the RecordRoute header for distributable applications in a high-availability environment. Enter this value as a SIP URL in the following format:
You need only enter the hostname ( For high availability configurations, configure this parameter in the following format:
Remove any transport methods to enable any type of transport to be used between the Edge Proxy and OCMS. For more information, see "Configuring the OCMS SIP Containers for High Availability". |
|
DistributableVia |
A comma-separated list of hosts, ports, and transports (such as my.cluster, 5060, tcp) used in the Via header for distributable applications in a high-availability environment. Enter this value as a SIP URL in the following format:
You need only enter the hostname ( |
|
DnsIpAddress |
The IP address for the DNS against which the SIP servlet containers resolve addresses. Enter the IP address in the format of |
|
DomainsAndRealms |
This attribute defines a mapping of SIP domains to Java-authenticated realms. This mapping is used to dynamically challenge a SIP request with the appropriate authentication realm during SIP authentication. For example, a domain/realm mapping of voip.com/voip would require a user with the SIP URI of user@voip.com to authenticate against the voip realm in response to the challenge by the SIP servlet container. Enter a comma-separated list of the configured hosted domains and their corresponding realms used for authentication. Applications -- rather than the SIP container itself -- use such a hosted domain to send a 404 (Not Found) message. |
|
DomainLoopDetection |
If set to true (the default setting), The SIP container checks whenever a request is about to be sent from the server to a destination that has a resolvable host name. If the host name resolves to one of the server's own listening ports (meaning that the server will send the request back to itself) the server checks the resolved host name against configurations set for the DomainsandRealms and RecordRoute header attributes. If there is no match for the hostname, then the request is blocked and the server responds with a 482 (Loop Detected) message. This protects the server from fake DNS names that point to the server's IP address and then send a request with the fake hostname in the top-most route header. Because the SIP container cannot recognize the hostname, it will never pop the Route header and the request will loop. |
|
IPAddress |
The IP address on which the SIP servlet container listens. The default value of 0.0.0.0 designates all IP addresses. For a production environment, change this value to an actual IP address. |
|
NetworkThreadCount |
The number of network threads spawned by the SIP container to handle network traffic. The value must be an integer. |
|
Edge Proxy |
The proxy that receives client requests. This proxy is adds a pre-loaded route. For example: sip:my.host:5060;transport=tcp. This setting is required for clients to maintain a reusable TCP connection to the server. To ensure this connection, clients may implement a keep-alive algorithm, such as sending periodic CRLFs (carriage-return line feeds). In clustered environments, you must configure an Edge Proxy for each OCMS instance to support communication with the Edge Proxy or other proxy applications. For high availability installations, this attribute must be set to the address of the Edge Proxy or to the virtual hostname and port service by the load balancer in front of the Edge Proxies. Set this value using the following format:
For more information, see "Configuring the OCMS SIP Containers for High Availability". |
|
RecordRoute |
A comma-separated list of hosts, ports and transports used in the RecordRoute header of non-distributable applications. Enter this value as a SIP URL in the following format:
You need only enter the hostname ( For high availability configurations, configure this parameter in the following format:
Remove any transports methods to enable any type of transport to be used between the Edge Proxy and OCMS. For more information, see "Configuring the OCMS SIP Containers for High Availability". |
|
SIPPort |
The port through which the SIP Servlet Container accepts traffic. The default value is 5060. |
|
SipServletCommanInterceptors |
A comma-separated list of SipServlet interceptor classes. The interceptors must implement |
|
SipServletOc4jInterceptors |
A comma-separated list of SipServlet interceptor classes specific for OC4J. The interceptors must implement |
|
TimerListenerOc4jInterceptors |
A comma-separated list of OC4J-specific |
|
TimerT1 |
The estimate, in seconds, for a round trip. This value must be an integer. |
|
TimerT2 |
The maximum interval, in seconds, for non-INVITE requests and INVITE responses. This value must be an integer. |
|
TimerT4 |
The maximum interval, in seconds, that a message can remain in the network. This value must be an integer. |
|
Trusted Hosts |
A comma-separated list IP of addresses representing trusted hosts as described in RFC 3325. For example, enter 192.168.0.10, 192.168.0.11. Leaving the value field blank means that there are no trusted hosts; entering an asterisk (*), means that all IP addresses can be trusted. Regular expressions are not supported. |
|
UseStun |
Select true to use STUNbis keepalive traffic. |
|
UseTCP |
Select true for the SIP Container to listen for TCP traffic. Oracle recommends setting TCP as the transport protocol because of network fragmentation issues. Add NAPTR and SRV records to the DNS to indicate that TCP is the preferred protocol. Ensure that clients connecting to OCMS fully support NAPTR and SRV records. |
|
UseUDP |
Select true for the SIP Container to listen for UDP traffic. |
|
Via |
A comma-separated list of hosts, port, and transports used in the VIA header of non-distributable applications. For example, enter my.host,5060, tcp. |
A SIP application in the OCMS SIP servlet container is basically the parsed sip.xml file. Hence, the SIP application contains all of the parsed servlet-definitions as well as the servlet-mappings (that is, the rules) and other sip.xml components as listeners.
As illustrated in Chapter 7, "Packaging and Deploying Applications", The SIP application is usually built as an Enterprise ARchive (EAR) that is deployed to OC4J. Once the SIP application has been deployed, the application server parses the sip.xml and instantiates the servlets and listeners. The application server also creates a name for the deployed application by piecing together the components of the EAR file. Because this generated name can be lengthy, you can create an alias for the application. You can use this shorter, more intuitive application name when you configure the default application. This short name can be used in the URI parameter of the route header or the request-URI.
For example, the name of a presence application deployed to the server might appear as presenceapplicationear-4.0.0-dev/eventnotificationssr-4.0.0-dev. Using the ApplicationAliases attribute, you can set a short name for this application by entering key-value pair such as presence=presenceapplicationear-4.0.0-dev/eventnotificationssr-4.0.0-dev. The key is the alias (presence) and the value is the real name of the application. This alias can be used for the real name of the application.
The SIP Servlet Container Logging (SipServletContainerLogging) MBean's attributes (described in Table 9-4) expose the log level interfaces of Apache log4j (that is, the level class that extends org.apache.log4j.priority). These attributes enable you to set the following logging levels for SIP traffic and events, JMX (Java Management Extensions) and SIP servlet container internal system logs:
OFF – The OFF level turns off all logging. This is the highest log level.
FATAL – The FATAL level designates severe error events which may cause the application to abort.
ERROR – The ERROR level designates error events which may allow the application to continue running.
WARN – The WARN level designates potentially harmful situations.
INFO – The INFO level designates informational messages that highlight the progress of the application at a general level.
DEBUG – The DEBUG Level designates detailed informational events which are useful in debugging an application.
TRACE – The TRACE Level designates finer-grained informational events than those designated by the DEBUG log level.
ALL – The ALL level turns on all logging. This is the lowest log level.
Table 9-4 Attributes of the SipServletContainerLogging MBean
| Attribute | Description |
|---|---|
|
eventlogger |
Sets the log level for application-defined MBeans. |
|
jmx |
Sets the log level for JMX related events. |
|
system |
Sets the log level for all SDP-related events. |
|
traffic |
Sets the log level for SIP traffic. |
For information on configuring the log4j logging system, see "Configuring the Logging System". For information on viewing the log files, see "Viewing Log Files".
The OCMS STUN Service implements STUN -- Simple Traversal of User Datagram Protocol (UDP) Through Network Address Translators (NATs). As described in RFC 3489, STUN enables STUN clients behind a NAT (that is, clients behind a router) to discover the presence of a NAT, the type of NAT, and then to learn the address bindings (including IP addresses) allocated by the NAT.
STUN is a client-server protocol in which a STUN client sends a request (a Binding Request) to a server, which in turn sends a response. OCMS supports the receipt of Binding Requests from a client, which are sent over UDP and are used to both discover the presence of a NAT and discover the public IP address and the port mappings that it generates. When a STUN client sends a Binding Request to the STUN server, the STUN Server examines the request's source IP address and port and copies them into a response that it sends back to the client. When the STUN client receives the Binding Response, it compares the IP address and port in the packet with the local IP address and port to which it bound itself when it sent the Binding Request to the STUN Server.
The attributes of the STUN Service MBean (described in Table 9-5) enable you to set the STUN Server's primary and secondary IP addresses and ports that form the four RFC 3489-dictated address-port combinations used by the STUN server to receive client Binding Requests. Per RFC 3489, the combinations are as follows:
A1, P1 -- The Primary Address and Primary Port
A2, P1 -- The Secondary Address and the Primary Port
A1, P2 -- The Primary Address and the Secondary Port
A2, P2 -- The Secondary Address and the Secondary Port
Typically, the STUN server's Primary Port (P1) is set to UDP port 3478. The Stun server uses the Secondary Address and Secondary Port values (A2, P2) in the CHANGED-ADDRESS attribute included in its Binding Response.
Table 9-5 Attributes of the STUNService MBean
| Attribute | Value |
|---|---|
|
Autostart |
Set to true for the Stun Server to start automatically when OCMS starts. |
|
PrimaryAddress |
The primary STUN address to which to bind for listening for incoming Binding Requests. The default value is 127.0.0.1. |
|
PrimaryPort |
The primary STUN port to which to bind for listening for incoming Binding Requests. The value is UDP port 3478, the default STUN Port as described in RFC 3489. |
|
SecondaryAddress |
The secondary STUN address to which to bind for listening for incoming Binding Requests. This cannot be the same value as PrimaryAddress. |
|
SecondaryPort |
The secondary STUN port to which to bind for listening for incoming Binding Requests. The default value is UDP port 3479. |
The SIP Servlet Container Monitor MBean (SipServletContainerMonitor) enables you to view the current status of the system queues. Clicking this MBean's attributes enables you to view the current, peak and total usage for the application and network queues. In addition, you can also view both the current and total number of SIP sessions as well as the number of responses sent when the system issues a 503 (Service Unavailable) message.
The values displayed through this MBean can serve as a reference when you tune overload protection using the Overload Policy MBean. In particular, you can use the numbers for ApplicationPeakQueue, NetworkPeakQueue, and Sessions to gauge the values for the Overload Policy's AppQueueMaxSize, StackQueueMaxSize, and SipSessionTableMaxSize attributes.
In general, overload protection is not invoked for normal load situations. Use this Mbean to find out the numbers for a normal load by monitoring the system's responses to various test scenarios without executing the overload protection. You can then set the overload protection to start above these figures.
Note:
The number of 503 responses sent and messages dropped (indicated by the 503ResponseSent and MessagesDropped attributes, respectively) indicate how often overload protection should execute to reduce incoming traffic.The Overload Policy enables OCMS to execute overload protection when capacity reaches high threshold levels. To configure this MBean, you first set the maximum value for number of SIP Sessions (SipSessionTableMaxSize) and the maximum size for the Application (AppQueueMaxSize) and Network queues (StackQueueMaxSize) as described inTable 9-6). You then set the threshold values for each of these, as described in Configuring High and Low Thresholds.
In addition to the maximum values settings, the AllowedTrafficDuring503 attribute enables you to set the percentage of traffic allowed to pass through the system when it becomes overloaded and issues the 503 (Service Unavailable) error response to clients. The system does not process any new incoming requests if you set this attribute to zero (0), the default value.
Note:
Refer to the load figures displayed for the ApplicationPeakQueue, NetworkPeakQueue, Sessions, 503ResponseSent and MessagesDropped attributes of the SIP Servlet Container Monitor when setting these values.Table 9-6 Default Values for SIP Sessions, Application and Network Queues
| Attribute | Default Value |
|---|---|
|
AppQueueMaxSize |
200 |
|
StackQueueMaxSize |
100 |
|
SipSessionTableMaxSize |
70000 |
Note:
Because of the internal use of the queues by OCMS, the actual peak values for the queues in an overload situation may exceed the maximum values configured in the Overload Policy.The Overload Policy receives collectors and actions from the Policy Manager (the lookup service for collectors, actions and policies). The Policy Manager sends notifications to all observers when available collectors, actions, or policies have changed.
Collectors notify policies when states change. The Overload Policy subscribes to state changes for the following collectors:
Overview of Overload Policy
The Overload Policy implements the following default actions, for which it enacts an overload action when high threshold values are reached and then reverts this action when usage sinks to the low threshold value:
Do not accept new connections: This overload action occurs when a high warning threshold value has been met.
Send 503 (Service Unavailable) response on initial requests: This overload action occurs when a high alarm threshold value has been met.
Stop reading from all connections: This overload action occurs when a high critical threshold has been met.
Configuring High and Low Thresholds
The Overload Policy MBean enables you to configure the high and low values for the Warning, Alarm and Critical levels for Memory Usage, Application Queue, Network Queue, and SIP Session Table Usage. At each level, there may be one or even several actions to execute if usage exceeds the specified threshold. When the high value set for a threshold is met, the Overload Policy calls overload actions. This value is the threshold at which these actions start. If usage drops to the low value set for a threshold, then the Overload Policy stops the overload action. For example, if a high level is set to 90 and low level is set to 80, overload actions that start when usage reaches 90% and are then stopped when usage drops back to 80%.
Starting and Stopping the Overload Policy
The start and stop operations for the Overload Policy MBean enable you manually start and stop the Overload Policy. To automatically start the Overload Policy at the startup of OCMS, set the Autostart attribute to true.
Memory Usage
The Memory Monitor reports memory usage to the Overload Policy. The usage is reported as percent of total memory. For example, if the Memory Monitor reports a value of 85, it means that 85% of total memory is currently in use and that 15% of it is free.
Using the Overload Policy MBean, you configure the Warning, Alarm and Critical threshold levels for the Overload Policy's memory usage. At each level, there may be one or several actions to execute if memory usage exceeds the specified threshold. The MBean enables you to set high and low threshold values for each of these levels. The high value is the threshold at which to start executing overload actions. The low level is marks the threshold at which to stop executing the action. For example, if high level is set to 90 and low level is set to 80, the actions start when memory usage reaches 90% and then stop when memory usage drops to 80% again.
Delaying a Memory Overload Action
The high and low levels avoid starting and stopping overload actions repeatedly for small changes in memory usage. In addition to the threshold level set to begin executing actions, you can also configure a delay time (in seconds) for memory overload actions using the MemoryActionDelay attribute. When the high threshold is exceeded, a scheduled timer fires after the specified delay time (in seconds). Memory overload actions will not be executed before the delay time has passed, and if memory usage drops below high threshold during the delay time, the timer is canceled and no actions will be executed. Configure the MemoryActionDelay attribute by entering the delay (in seconds) from the instance when the memory threshold value has been exceeded to the instant the actions are executed. The execution stops if the memory drops below the threshold during the delay. The value set for the delay must be greater than 0. The default value is 60 seconds.
Table 9-7 lists the attributes that you configure to set the values for the high and low warning thresholds for memory usage.
Table 9-7 Warning High and Low Thresholds for Memory Usage
| Attribute | Description |
|---|---|
|
MemoryWarningHigh |
The high value for a warning threshold that triggers an overload action to decline new connections. This is the default overload action. The range of values is 0-100. 0 disables the action. The default value is 95. |
|
MemoryWarningLow |
The low value for a warning threshold that triggers an end to the overload action. The range of values is 0-100. The default value is 90. |
|
MemoryWarningActions |
A comma-separated list of actions performed when a memory warning level has been reached. The default value is oracle.sdp.networlayer.NetworkServiceImpl$StopAcceptAction. |
Table 9-8 lists the attributes that you configure to set the high and low alarm thresholds for memory usage.
Table 9-8 The Alarm HIgh and Low Thresholds for Memory Usage
| Attribute | Description |
|---|---|
|
MemoryAlarmHigh |
The high value for an alarm threshold for memory usage that triggers an action to send a 503 response (Service Unavailable) on initial requests. This is the default overload action. The range of values is 0-100. 0 disables the action. The default value is 95. |
|
MemoryAlarmLow |
The low value for the alarm threshold for memory usage that triggers an end to the overload action. The range of values is 0-100. The default value is 90. |
|
MemoryAlarmActions |
A comma-separated list of actions performed when a memory alarm threshold level has been reached. The default value is com.hotsip.jainsipimpl.javax.sip.context.SipContextImpl$Send503Action. |
Table 9-9 lists the attributes that you configure to set the high and low critical thresholds for memory usage.
Table 9-9 Critical High and Low Thresholds for Memory Usage
| Attribute | Description |
|---|---|
|
MemoryCriticalHigh |
The high value for a critical threshold for memory usage that triggers an overload action to stop reading connections. This is the default overload action. The range of values is 0-100; 0 disables the action. The default value is 98. |
|
MemoryCriticalLow |
The value that triggers an end to the overload action when the low threshold for memory usage has been reached. The range of values is 0-100. The default value is 90. |
|
MemoryCriticalActions |
A comma-separated list of action performed when the critical threshold of memory usage has been reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopReadAction. |
Application Queue
The Application Queue is the communication link between the network layer and the applications. An event is added to the Application Queue when network packages are framed and ready for application consumption and when a session timer fires or other network related events occur. The network layer's EventNotifier reports Application Queue usage to the Overload Policy. This usage is reported as a percent of the total queue capacity. For example, if the EventNotifier reports a value of 85, it means that 85% of total queue capacity is currently used and 15% of the queue is empty. The AppQueMaxSize attribute sets the capacity of the Application Queue. The default value is 200. This value must always be greater than zero.
The EventNotifier does not report every change in Application Queue usage to the Overload Policy: below 95%, every 5% change is reported (that is 0, 5, 10, 15 and so on). From 95% and above, every 1% change is reported (that is, 95, 96, 97 and so on). The Overload Policy MBean enables you to configure the Warning (Table 9-10), Alarm (Table 9-11), and Critical (Table 9-12) thresholds of the Application Queue.
Table 9-10 lists the attributes of the Overload Policy that enable you to set the high and low warning thresholds for the Application Queue usage.
Table 9-10 Warning High and Low Threshold and Actions for the Application Queue
| Attribute | Value |
|---|---|
|
AppQueueWarningHigh |
The high threshold warning value for Application Queue usage that triggers an action to decline new connections. This is the default overload action. The range of values is 0-100. Selecting 0 disables the action. The default value is 70. |
|
AppQueueWarningLow |
The low threshold warning value for Application Queue usage that triggers an end to the overload action. The range of values is 0-100. The default value is 50. |
|
AppQueueWarningActions |
A comma-separated list of actions performed when a warning threshold for Application Queue usage has been reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopAcceptAction. |
Table 9-11 lists the attributes of the Overload Policy that enable you to set the high and low alarm thresholds for the Application Queue usage.
Table 9-11 Alarm High and Low Threshold Actions for the Application Queue
| Attribute | Description |
|---|---|
|
AppQueueAlarmHigh |
The high alarm threshold value for the Application Queue usage that triggers an overload action to send a 503 response (Service Unavailable) to initial requests. (This is the default overload action.) The range of values is 0-100. 0 disables the action. The default value is 80. |
|
AppQueueAlarmLow |
The low alarm threshold value for Application Queue usage that triggers an end to the overload action. The range of values is 0-100. The default value is 60. |
|
AppQueueAlarmActions |
A comma-separated list of action performed when an alarm threshold is reached. The default value is com.hotsip.jainsipimpl.javax.sip.context.SipContextImpl$Send503Action. |
Table 9-12 lists the attributes of the Overload Policy MBean that enable you to set the high and low critical thresholds for the Application Queue usage.
Table 9-12 Critical High and Low Threshold Actions for the Application Queue
| Attribute | Description |
|---|---|
|
AppQueueCriticalHigh |
The high threshold value for Application Queue usage that triggers an overload action to stop reading connections. This is the default overload action. The range of values is 0-100; 0 disables the action. The default value is 90. |
|
AppQueueCriticalLow |
The low threshold value for Application Queue usage that triggers an end to the overload action. The range of values is 0-100. The default value is 70. |
|
AppQueueCriticalActions |
A comma-separated list of actions performed when a critical level is reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopReadAction. |
Network Queue
The network layer deposits the incoming unframed data from the network into the Network Queue. The network layer's EventQueue reports the Network Queue usage to the Overload Policy. The usage is reported as a percent of the total queue capacity. For example, if the EventQueue reports a value of 85, it means that 85% of total queue capacity is currently in use and 15% of the queue is empty. The StackQueueMaxSize attribute sets the Network Queue capacity. The default value for this attribute is 100. The value must always be greater than zero.
The EventQueue does not report every change in queue usage to the Overload Policy. Below 95%, every 5% change is reported (that is, 0, 5, 10, 15 and so on). From 95% and above, every 1% change is reported (that is, 95, 96, 97 and so on). The Overload Policy MBean enables you to configure the Warning (Table 9-13), Alarm (Table 9-14), and Critical (Table 9-15) thresholds of the Network Queue.
Table 9-13 lists the attributes that you configure to set the high and low threshold values that trigger Warning actions.
Table 9-13 Warning High and Low Threshold Actions for the Network Queue
| Attribute | Description |
|---|---|
|
StackQueueWarningHigh |
The high warning threshold value for Network Queue usage that triggers the overload action to decline new connections. This is the default overload action. The range of values is 0-100; 0 disables the action. The default value is 70. |
|
StackQueueWarningLow |
The low warning threshold value that trigger end to the overload action. The range of values is 0-100. The default value is 50. |
|
StackQueueWarningActions |
A comma-separated list of actions performed when a warning threshold is reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopAcceptAction. |
Table 9-14 lists the attributes that you configure to set the high and low threshold values that trigger Alarm actions.
Table 9-14 Alarm High and Low Threshold Actions for the Network Queue
| Attribute | Description |
|---|---|
|
StackQueueAlarmHigh |
The high alarm threshold for Network Queue usage that triggers an overload action to send a 503 (Service Unavailable) response to initial requests. This is the default action. The range of values is 0-100; 0 disables the action. The default value is 80. |
|
StackQueueAlarmLow |
The low alarm threshold for Network Queue usage that triggers an end to the overload action. The range of values is 0-100. The default value is 60. |
|
StackAlarmQueueActions |
A comma-separated list of actions performed when a threshold is reached. The default value is com.hotsip.jainsipimpl.javax.sip.context.SipContexImpl$Send503Action. |
Table 9-15 lists the attributes that you configure to set the high and low values that trigger Critical actions.
Table 9-15 Critical High and Low Threshold Actions for the Network Queue
| Attribute | Description |
|---|---|
|
StackQueueCriticalHigh |
The high critical threshold value for Network Queue usage that triggers an overload action to stop reading all connections. (This is the default overload action.) The range of values is 0-100. 0 disables the action. The default value is 90. |
|
StackQueueCriticalLow |
The low critical threshold value that triggers an end to the overload action. The range of values is 0-100. The default value is 70. |
|
StackQueueCriticalActions |
A comma-separated list of actions performed when a critical level is reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopReadAction. |
SIP Session Table Usage
The sipservletengine's Application Manager reports SIP session table usage to the Overload Policy. The usage is reported as a percent of total table capacity. For example, if the Application Manager reports a value of 85, it means that 85% of total table capacity is currently in use and 15% of it is free. The SessionTableMaxSizeSip attribute sets the SIP session table capacity. The default value of this attribute is 70000. The value must be greater than zero.
Not every change in table usage is reported back to overload policy. Below 95%, every 5% change is reported (that is, 0, 5, 10, 15 an so on). From 95% and above, every 1% change is reported (that is, 95, 96, 97 and so on). The Overload Policy MBean enables you to configure the Warning (Table 9-16), Alarm (Table 9-17), and Critical (Table 9-18) thresholds that trigger overload actions.
Table 9-16 lists the attributes that you configure to set the warning thresholds.
Table 9-16 Warning High and Low Threshold Actions for SIP Session Table Usage
| Attribute | Description |
|---|---|
|
SipSessionWarningHigh |
The high warning threshold value for SIP session table usage that triggers an overload action to decline new connections. This is the default overload action. The range of values is 0-100; 0 disables the action. The default value is 90. |
|
SipSessionWarningLow |
The low warning threshold that triggers an end to the overload action. The range of values is 0-100. The default value is 85. |
|
SipSessionWarningActions |
A comma-separated list of actions performed when a critical level is reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopAcceptAction. |
Table 9-17 lists the attributes that you configure to set the alarm level thresholds.
Table 9-17 Alarm High and Low Threshold Actions for SIP Session Table Usage
| Attribute | Description |
|---|---|
|
SipSessionAlarmHigh |
The high alarm threshold of SIP session table usage that triggers an overload action to send a 503 Response (Service Unavailable) to initial requests. This is the default overload action. The range of values is 0-100; 0 disables the action. The default value is 98. |
|
SipSessionAlarmLow |
The low alarm threshold of SIP session table usage that triggers an end to the overload action. The range of values is 0-100. The default value is 97. |
|
SipSessionAlarmActions |
A comma-separated list of actions performed when an alarm threshold is reached. The default value is com.hotsip.jainsipimpl.javax.sip.context.SipContextImpl$Send503Action. |
Table 9-18 lists the attributes that you configure to set the critical thresholds.
Table 9-18 Critical Threshold Actions for SIP Session Table Usage
| Attribute | Description |
|---|---|
|
SipSessionCriticalHigh |
The high critical threshold value for SIP session table usage that triggers an overload action to stop reading all connections. This is the default overload action. The range of values is 0-100; 0 disables the action. The default value is 100. |
|
SipSessionCriticalLow |
The low critical threshold for SIP session table usage that triggers an end to the overload action. The range of values is 0-100. The default value is 99. |
|
SipSessionCriticalActions |
A comma-separated list of actions performed when a critical level is reached. The default value is oracle.sdp.networklayer.NetworkServiceImpl$StopReadAction. |
The Memory Monitor reports memory usage to the Overload Policy. The Memory Monitor polls the memory status from the runtime environment at either specified or random polling intervals. The Memory Monitor MBean includes attributes that enable you to select the type of polling interval and also the duration of the polling interval. Table 9-19 lists the attributes of the Memory Monitor MBean.
Table 9-19 Attributes of the Memory Monitor MBean
| Attribute | Description |
|---|---|
|
AutoStart |
Select true to activate the Memory Monitor on startup of the SIP container. |
|
PollingInterval |
Enter the time, in seconds, between each interval that the Memory Monitor polls the memory status of the runtime environment. This attribute sets a fixed interval between polls. This value must be greater than five (5) seconds. The default value is 5. |
|
RandomInterval |
Select true to set the Memory Monitor to poll at a random intervals. The average length of these intervals will be the same as the value set for the PollingInterval attribute, but individual polls may differ by 50% from the fixed interval. For example, if the polling interval is set to 20 seconds, then a random interval may be pending between 10 and 30 seconds. The default setting is false. |
|
MemoryMonitorStatus |
The current status of the Memory Monitor. This value is read-only. |
|
MemoryUsage |
The current memory usage. This value is read-only. |
This section describes the configuration enabled by the MBeans registered to the following SIP applications:
Presence (See "Overview of Presence")
Subscriber Data Services (subscriberdataservices) is the parent application to all SIP applications that require authentication and security against the OCMS user repository. For example, the Application Router, Aggregation Proxy, and Proxy Registrar require Subscriber Data Services. In the case of the latter, the Location Service and the registrar component of the Proxy Registrar are dependent upon Subscriber Data Services. Subscriber Data Services also provides access to the TimesTen In-Memory database or Oracle Internet Directory (OID). For more information, see "Overview of Security". See also "Configuring Oracle Internet Directory as the User Repository" for information on using Oracle Internet Directory (OID), the LDAP data store used by Oracle WebCenter Suite, as the user provisioning repository for an OCMS deployment.
Account Security
Subscriber Data Services provides account security through the Account Lockout Service and Login Failure service MBean groups.
The Account Lockout group includes the following MBeans:
AA Service
The AA Service MBean is used by the Login Failure Service to lock accounts. This MBean depends on the MathFunction Model MBeans, which enable the AA Service MBean to calculate the next lock duration for an account based on the current number of failed login attempts.
Note:
Account locking persists when you restart OC4J.Table 9-20 describes the attributes of the AA Service MBean.
Table 9-20 Attributes of the AA Service MBean
| Attribute | Value |
|---|---|
|
MathFunction |
The type of math function used to calculate the next lock duration for an account based on the number of current failed login attempts. The math functions, which include |
|
DefaultLockDuration |
The lock duration, in seconds, to use if no math functions are available. The default value is 600. |
|
JNDIName |
The JNDI Name of the AA Service. This value is read-only |
|
SecurityServiceName |
The JNDI Name bound to the service object that is used to unlock user accounts. This value is read-only. |
Constant (read-only)
The constant function used by the MathFunction MBean to calculate the next lock duration for an account based on the number of current failed login attempts.
Exponential
The exponential math function used by the MathFunction MBean to calculate the next lock duration for an account based on the number of current failed login attempts.
Linear
The linear math function used by the MathFunction MBean to calculate the next lock duration for an account based on the number of current failed login attempts.
Of the Subscriber Data Services MBeans, only AA Service and Command Service can be configured.
The operations of the CommandService MBean enable you to execute the equivalent of Sapphire Shell (Sash) commands which are used to provision OCMS users to the TimesTen In-Memory database. For example, to view a list of commands for account management:
Click the Operations tab. A list of get commands appears.
Click help for a returning a help String for a partial command. The parameters for the help operation appear.
Enter account in the Value field.
Tip:
Click Use Multiline Editor to expand the Value field to accommodate long command names.Click Invoke Operation. The commands pertaining to account management appear (Figure 9-6). These commands match those retrieved by entering help account at the Sash prompt. For more information, see "Viewing Subcommands" in Chapter 5, "Provisioning Users and Applications".
To view a list of all of the available commands (Figure 9-7), select listAllCommands from the Operations tab and then click Invoke Operation from the listAllCommands page that appears. For a description of Sash commands, see "Viewing Available Commands". For more information on user management through Sash, see "Creating a User".
The Command Service MBean is deployed within the presence application to enable user provisioning to the XDMS server. See Command Service (XDMS Server Provisioning).
The Proxy Registrar is a user agent server (UAS) that implements the proxy and registrar functions described in RFC 3261. This SIP entity is a router of messages. The Proxy Registrar's registrar function processes the REGISTER requests from User Agent clients and uses a Location Service to store a binding (that is, an association) between a user's address of record (AOR) and the user's SIP or SIPS URIs that are located in a CONTACT field. Upon receiving requests to the AOR, the proxy function locates the mapped URIs through a Location Service lookup and then proxies the request using the location information retrieved by this lookup. Table 9-22 describes the attributes of the Proxy Registrar.
Table 9-22 Attributes of the Proxy Registrar
| Attributes | Description |
|---|---|
|
CurrentRegDevices |
A list of registered devices. |
|
DefaultExpires |
Sets the expiration value for the REGISTER request if the client has not indicated a preferred value itself. The default value for this attribute is 3600 seconds. |
|
MaxExpires |
Sets the maximum expiration value for the REGISTER request accepted by the server. Although a client can request any expiration value in the REGISTER request, the server can set a maximum amount of time that it accepts for expiration. If the client requests a time greater than the value set for MaxEpires, then the server sets the expiration time for that particular REGISTER request to the value set for MaxExpires. The default value for this attribute is 7200 seconds. |
|
MinExpires |
Specifies the minimum expiration value for a REGISTER request accepted by server. While clients can request any expiration time, they can also specify a very low value for the expiration of the REGISTER request. Such low values require clients to update registration information frequently, which creates traffic on the network. If a client requests a value that is below this minimum expiration time, then the server does not accept the REGISTER request and responds with a 423 (Interval Too Brief) error response per RFC 3261. This response message specifies the lowest expiration time allowed, which is set by the MinExpires attribute. The server is allowed to shorten an expiration time, but can never lengthen one. The default value for this attribute is 60 seconds. |
|
SipRegAllowThirdParty |
Specifies whether the Proxy Registrar allows third-party registrations. In a third-party registration, the entity issuing the request (in the From header) is different from the entity being registered (in the To header) to whom the provided Contact information applies. If set to true, the Proxy Registrar allows third party registrations. If set to false, then third-party registrations are rejected (the requestor receives a 403 Forbidden status code). |
|
SipRegMaxUsers |
Specifies the maximum number of users supported by the Proxy Registrar. |
Incoming messages are dispatched to applications through the Application Router. This component first inserts the routing information into a message and then proxies it onto the next application. The Application Router MBean (ocmsrouteloaderear) enables you to configure the destination for incoming messages. Table 9-23 describes the attributes that you configure for the routing of INVITE, MESSAGE, PUBLISH, REGISTER, and SUBSCRIBE messages.
Table 9-23 Attributes of the Application Router
| Attribute | Description |
|---|---|
|
IncrementalMode |
This boolean enables you to select the Application Router's execution mode: true for incremental, false for standard.
|
|
RecordRoute |
Set to true to enable record routing. |
|
RouteLoaderUri |
The URI of the return route to the Application Router. This value must be the same URI as the SIP container. |
|
SipUriList |
A comma-separated list of URIs, transport methods, and application IDS (appIds) of applications that the Application Router inserts in the ROUTE header of an incoming request. Enter an application as follows:
The Proxy Registrar is listed by default. The order in which you list these applications determines the routing of SIP messages to these applications. |
Presence represents the end-user's willingness and ability to receive calls. Client presence is often represented as a buddy list, which displays user availability with icons. These icons, which not only represent a user's availability, but also a user's location, means of contact, or current activity, enable efficient communications between users.
The Presence application enables a service provider to extend presence service to end users. The application also enables service providers to base other services on presence information. The MBeans registered to the Presence application enable you to configure the presence service, which accepts, stores, and distributes presence information. See also "Presence Server" in Chapter 1, " An Overview of Oracle Communication and Mobility Server".
The Presence application MBeans enable you to manage the following:
Presence Status Publication
A presentity can publish a PIDF (Presence Information Data Format) document containing presence state to the Presence Server.
Presence Status Subscriptions
The Presence server supports subscriptions to a user's status. The Presence Server notifies the user when the watcher (subscriber) is authorized to view the user's status. The Presence server also notifies all of the active, authorized watchers of the publication of a new presence document.
Watcher-Info Support
The Presence Server enables the user who is publishing presence information to subscribe to watcher-info events to receive information on all watchers currently subscribing to the user's presence information. The Presence Server also notifies users of changes in the watcher subscriptions, such as new or terminated subscriptions.
Presence XDMS Authorization of Subscriptions
Whenever a watcher subscribes to a user's presence, the Presence Server checks the authorization policy that the publisher has set to see if the subscriber has the required authorization.
If no matching rule can be found, the subscriber is put in a pending state and a watcher info notification is sent to the publisher. Usually, the publisher's client (User Agent) presents a pop-up box asking whether to accept or reject a new pending subscriber. The answer is added to the publisher's authorization policy document in the form of a rule for this subscriber. The document is then updated by the client on the XDMS Server using HTTP. When the document is updated, the Presence Server reads the new policy document and acts on the new rule, changing the subscription state accordingly.
Privacy Filtering
A user can create privacy filtering rules that can be applied to a group or to the individual watcher, enabling different presence documents to be generated for different watchers. For example, a user can create rules which present a limited presence document for co-workers while friends receive the entire document.
Presence Hard State
The hard state feature enables a user to leave a document in the XDMS Server that notifies watchers when there are no other documents. In general, this feature is used for leaving an off-line note, such as "On Vacation".
Composition of Multiple Presence Sources
If a user has two or more clients (such as a PC and a mobile phone) both publishing presence documents, the Presence Server combines two or more documents into a unified document according to a policy that can be configured. The Presence server supports two different composition policies: a default policy and a policy that performs composition according to the OMA (Open Mobile Alliance) Presence enabler.
The default composition policy is a simple but robust algorithm. It adds <dm:timestamp> elements to the <dm:person> and <dm:device> elements if they are missing, and <pidf:timestamp> elements to the <pidf:tuple> elements if they are missing.
When the Presence Server creates the candidate document, it includes all <pidf:tuple> and <dm:device> elements from the source documents. It includes only one <dm:person> element in the candidate document, and uses the latest published element based on the <dm:timestamp> element. All other <dm:person> elements are ignored.
Configuring the following MBeans enables Presence:
PresenceApplicationDeployer
The Bus MBean supports presence by setting the thread pool, the high and low watermarks for the job queues, and the duration that job to remain in the queue before notifications are dispatched. Table 9-24 describes the attributes of the Bus MBean.
Table 9-24 Attributes of the Bus MBean
| Attribute | Value Type | Description |
|---|---|---|
|
HighWatermark |
int |
The number of pending jobs reached before the bus's exhausted threshold level is reached. The default value is 20. |
|
KeepAlive |
long |
The number of seconds to keep an idle thread alive before dropping it (if the current number of threads exceeds the value specified for MinThreads). The default value is 60. |
|
LogDuration |
long |
The duration, in seconds, that an event remains in the queue. A warning is logged to the system log for events that remain in the queue for a period exceeding the specified duration before they are broadcast to the bus. This warning indicates that server is about to be overloaded, since an old job has been sent to the bus. The default value is 60. |
|
LowWatermark |
int |
Specifies the low threshold level for the number of pending jobs. When this threshold is reached from below, the Bus logs a warning that it is about to be choked. At this point, no more warnings are logged until the high watermark level is reached. The default value is 15. |
|
MinThreads |
int |
The minimum number of threads held in the thread pool. If no threads are used, then the specified number of threads remains in an idle state, ready for upcoming jobs. The default value is 15. |
|
MaxThreads |
int |
The maximum number of threads held in the thread pool. When the specified number of threads are occupied with jobs, subsequent jobs are placed in a queue and are dealt with as the threads become available. The default value is 10. |
The PresenceEventPackage, PresenceWInfoEventPackage, and UA-ProfileEventPackage MBeans enable you to configure the event packages, which define the state information to be reported by a notifier to a watcher (subscriber). These packages form the core of the Presence Server, as most requests flow through them.
A notifier is a User Agent (UA) that generates NOTIFY requests that alert subscribers to the state of a resource (the entity about which watchers request state information). Notifiers typically accept SUBSCRIBE requests to create subscriptions. A watcher is another type of UA, one that receives the NOTIFY requests issued by a notifier. Such requests contain information about the state of a resource of interest to the watcher. Watchers typically also generate SUBSCRIBE requests and send them to notifiers to create subscriptions.
The PackageManager MBean sets the configuration for the PresenceEventPackage, WatcherinfoPackage, and UA-ProfileEventPackage Means. Table 9-25 describes the attributes of the PackageManger MBean.
Table 9-25 Attributes of the EventPackages MBean
| Attribute | Description |
|---|---|
|
CaseSensitiveUserPart |
Setting this attribute to true enables case-sensitive handling of the user part of the SIP URI. If this parameter is set to false, then the user part of the URI is not a case-sensitive match. For example, foo is considered the same as FoO. The domain part of the URI is always case-insensitive. |
|
EventPackageNames |
A comma-separated list of event package names. For example: presence,presence.winfo,ua-profile. |
|
WaitingSubsCleanupInterval |
The interval, in seconds, in which the subscription cleanup check runs. The thread sleeps for this period and then awakens to check for any waiting subscriptions with a timestamp older than the MaxWaitingSubsTimeHours parameter. All old subscriptions are then removed from the subscribed resource. |
|
Max WaitingSubsTimeHours |
The maximum time, in hours, that a subscription can be in a waiting state before the server removes it. This parameter is used by the subscription cleanup check thread ( |
The Presence MBean controls how the Presence Server interacts with presentities, Publish User Agents (PUAs) that provide presence information to presence services. The attributes (described in Table 9-26) include those for setting the composition policy for creating a unified document when a user publishes presence documents from two or more clients, set blocking, filtering, and the presence hard state.
Table 9-26 Attributes of the Presence MBean
| Attribute | Description/Value |
|---|---|
|
CompositionPolicyFilename |
The filename of the composition policy document. Values include |
|
DefaultSubHandling |
The default subscription authorization decision that the server makes when no presence rule is found for an authenticated user. The defined values are:
Unauthenticated users will always be blocked if no rule is found. For more information about this, see Chapter 3.2.1: Subscription Handling in the IETF SIMPLE draft for presence rules ( |
|
DocumentStorageFactory |
The name of the |
|
DocumentStorageRootUrl |
The system identifier for the document storage. In the file storage case, this is the root file URL path where documents are stored. The content of this directory should be deleted when the server is restarted. The default value is file:/tmp/presencestorage/. |
|
DocumentStorageType |
The type of storage to be used for presence documents. If the number of users is large, Oracle recommends that you store the presence documents on file. Valid values:
The default value is memory. |
|
HttpAssertedIdentityHeader |
The type of asserted identity header used in all HTTP requests from the Presence Server to the XDMS Servers. Set the value of this attribute to one expected by the XDMS Server. Valid values:
|
|
PidfManipulationAuid |
The ID of the application usage for PIDF (Presence Information Data Format) manipulation. The default value is pidf-manipulation. |
|
PidfManipulationDocumentName |
The document name for pidf manipulation application usage. For example: hardstate. Unauthenticated users are blocked when no rule is found. If the URI contains a domain name instead of an IP address, then you must configure the DNS Server. The default value is hardstate. |
|
PidfManipulationEnabled |
Set to true (the default value) to enable PIDF manipulation. |
|
PidfManipulationXcapUri |
The SIP URI of XDMS Server for the pidf manipulation application usage. The default value is: sip:127.0.0.1;transport=TCP;lr. The loose route (lr) parameter must be included in the SIP URI for the server to function properly. |
|
PoliteBlockPendingSubscription |
Set to true if pending subscriptions should be polite-blocked. This feature is used to hide the presentity from the presence watcher with a pending subscription and instead send them fake presence documents. If set to false the subscriptions will remain as pending. |
|
PresRulesAuid |
The ID of the application usage for presrules. The default is pres-rules. |
|
PresRulesDocumentName |
The document name for presrules application usage. The default value is presrules. |
|
PresRulesXcapUri |
The SIP URI of XDMS Server for the presence rules application usage. The default value is: sip:127.0.0.1; transport=TCP;lr. The loose route (lr) parameter must be included in the SIP URI for the server to function properly. |
|
PrivacyFilteringEnabled |
Set to true to enable privacy filtering. Set to false to disable filtering. If privacy filtering is disabled, then all subscriptions that are allowed to see a user's presence will always see everything that has been published for the presentity. |
|
TransformerFactory |
The name of the |
Table 9-27 describes the attributes of the PresenceEventPackage MBean. The presence event package has two subgroups: publish and subscribe. Each subgroup has a minexpires and a maxexpires parameter to set the interval of the expiry of a publication or a subscription that is accepted by the Presence Server. A client states when its publication or subscription expires. If a client sends an expiry time that is lower than the configured minexpires time, the server returns a 423 (Subscription Too Brief) response. If a client sends an expires time that is higher than the configured maxexpires time, the server returns the maxexpires time in the response. To keep a publication or subscription alive, the client sends republish or resubscribe to the server within the expiry time. The client must perform this task repeatedly through the lifetime of the publication or subscription.
Table 9-27 Attributes of the PresenceEventPackage
| Attribute | Value/Description |
|---|---|
|
Description |
A description of the PresenceEventPackage. For example: The event package that enables presence. |
|
DocumentFactory |
The |
|
EscMaxDocumentSize |
The maximum size, in bytes, for the contents of a publication. If a client attempts to publish a document that is larger than the specified size, the server sends the 413 response, Request entity too long. The default value is 10000. |
|
ESCMaxExpires |
The maximum time, in seconds, for a publication to expire. The default value is 3600. |
|
ESCMaxPubPerRes |
The maximum number of publications allowed per resource. If the maximum number has been reached for a resource when a new publish is received, the server sends the 503 response, Service Unavailable. |
|
ESCMinExpires |
The minimum time, in seconds, for a publication to expire. The default is 60. |
|
EventStateCompositor |
The class name of the |
|
Name |
The name of this event package. The default value is Presence. |
|
Notifier |
The name of the |
|
NotifierMaxDocumentSize |
The maximum size for a SUBSCRIBE. |
|
NotifierMaxExpires |
The maximum time, in seconds, for a SUBSCRIBE to expire. The default is 3600. |
|
NotifierMaxNoOfSubsPerRes |
The maximum number of subscriptions allowed per resource. If the maximum number has been reached for a resource, then a new presence subscribe is received and the server sends the 503 response (Service Unavailable). |
|
NotifierMinExpires |
The minimum time, in seconds, for a SUBSCRIBE to expire. |
|
ResourceManagerClassName |
The name of the ResourceManager class. The default is |
As described in RFC 3857, a Watcher Information Event Package monitors the resources in another event package to ascertain the state of all of the subscriptions to that resource. This information is then sent to the subscriptions of the Watcher Information Event Package. As a result, the subscriber learns of changes in the monitored resources subscriptions.
The PresenceWInfoEventPackage MBean (described in Table 9-28) sets the subscription state information for the Watcher Information Event Package.
Table 9-28 Attributes of the WatcherinfoEventPackage
| Attribute | Description/Value |
|---|---|
|
Description |
A description of the PresenceWInfoEventPackage. For example: The event package that enables watcherinfo. |
|
DocumentFactory |
The name of the |
|
Name |
The name of the event package. The default value is presence.winfo. |
|
Notifier |
The |
|
NotifierMaxDocumentSize |
The maximum document size for SUBSCRIBE. |
|
NotifierMaxExpires |
The maximum time, in seconds, for a SUBSCRIBE to expire. The default is 3600. |
|
NotifierMaxNoSubsPerRes |
The maximum number of subscriptions allowed per resource. If the maximum number has been reached for a resource when a new presence subscribe is received, the server will send a 503 (Service Unavailable) response. The default value is 100. |
|
NotifierMinExpires |
The minimum time, in seconds, for a SUBSCRIBE to expire. |
|
ResourceManagerClassName |
The name of the |
Table 9-29 describes the attributes of the UA-ProfileEventPackage MBean.
Table 9-29 Attributes of the UA-Profile Event Package
| Attributes | Description/Value |
|---|---|
|
Description |
A description of the UA-ProfileEventPackage. The default value is The event package that enables the ua-profile. |
|
Document Factory |
The
|
|
Name |
The name of the event package. The default value is ua-profile. |
|
Notifier |
The name of the
|
|
NotifierMaxDocumentSize |
The maximum document size for a SUBSCRIBE. |
|
NotifierMaxExpires |
The maximum time, in seconds, for a SUBSCRIBE to expire. The default is 6000. |
|
NotifierMaxNoOfSubsPerRes |
The maximum number of subscriptions allowed per resource. If the maximum number has been reached for a resource when a new presence subscribe is received, the server will send a 503 (Service Unavailable) response. The default value is 100. |
|
NotifierMinExpires |
The minimum time, in seconds, for a SUBSCRIBE to expire. The default value is 60. |
|
ResourceManager |
The name of the Resource Manager class. The default value is:
|
The UserAgentFactoryService MBean sets the commands for user agent factory service. The Presence Server uses the user agent factory to subscribe to changes in XML documents stored in the XDMS Server for presence.
Table 9-30 Attributes of the UserAgentFactoryService MBean
| Attribute Name | Read/Write | Description/Value |
|---|---|---|
|
DNSNames |
Both |
A comma-separated list of DNS (Domain Name System) IP addresses used by the user agent. |
|
IpAddress |
Both |
The IP address for the user agent client; use the empty string (the default setting) for the default network interface on the current system. |
|
Port |
Both |
The IP port for the user agent client. The default value is 5070. |
The Command Service MBean enables user provisioning to the XDMS Server. For more information see "CommandService".
The XCapConfig MBean controls the configuration of the XDMS Server (an XDMS, XML Document Management Server), the repository of the XCAP (Extensible Markup Language Configuration Access Protocol) documents containing user presence rules (pres-rules) and hard state information. The XCapConfig MBean settings can be ignored if the XDMS Server is external to OCMS.
Table 9-31 Attributes of the XCapConfig MBean
| Attribute Name | Description/Value |
|---|---|
|
CreateNonExistingUserstore |
Set to true to create a user store if one does not exist when storing a document; otherwise, set to false. If the parameter is set to false and a client tries to store a document for a user that does not exist, then the store fails. If the parameter is set to true, then the user will first be created in the XDMS Server and then the document will be stored. The default value is true. |
|
PersistanceRootUrl |
The file URL of the XCAP document files storage root. For example: file:/var/tmp/xcaproot/ |
|
PidfManipulationAuid |
The ID of the application usage for PIDF (Presence Information Data Format) manipulation. The default value is pidf-manipulation. |
|
PidfManipulationDocumentName |
The document name for pidf manipulation application usage. For example: hardstate. Unauthenticated users are blocked when no rule is found. If the URI contains a domain name instead of an IP address, then you must configure the DNS Server. The default value is hardstate. |
|
PresRulesAU |
The name of the pres-rules application usage. The default value is pres-rules. |
|
PresRulesDocName |
The name of the pres-rules document. The default value is presrules. |
|
PublicContentServerRootUrl |
The URL to the public content server root. The URL must be set to the public URL of the content server (that is, the URL of the authentication HTTP proxy server). |
|
PublicXCAPRootUrl |
The URL to the public XDMS server root, entered as http://<your.xdms.domain.com>/services/. For example, enter http://127.0.0.1:8080/services. The URL defined in this parameter gives clients the location of the content server (which can be on a separate server from the XDMS Server). The XDMS Server places this URL in the Content-Type header of its outgoing NOTIFY messages. For example, the Content-Type header in the following NOTIFY message from the XDMS Server to the Presence Server notes that the body of the pres-rules document is stored externally and also includes instructions within the URL for retrieving the document. CSeq: 1 NOTIFY From: <sip:bob_0@144.22.3.45>;tag=66910936-0e31-41b2-abac-10d7616d04ef To: <sip:bob_0@144.22.3.45>;tag=ffa3e97bd77f91e6ca727fbf48a5678b Content-Type: message/external-body;URL="http://127.0.0.1:8888/contentserver/pres-rules/users/bob_0@144.22.3.45/presrules";access-type="URL" ... Event: ua-profile;document="pres-rules/users/sip:bob_0@144.22.3.45/presrules";profile -type=application;auid="pres-rules" |
|
XCAPMaxDocSize |
Sets the maximum size for a pres-rules document. |
|
RequireAssertedIdentity |
Set to true if all HTTP/XDMS requests require an asserted identity header; otherwise, set this parameter to false. Setting this attribute to true requires all XCAP traffic to be authenticated by the Aggregation Proxy. If this attribute is set to true, then any incoming XCAP request that lacks an asserted identity is denied access. |
OCMS enables Web Service clients to access presence services through its support of the Parlay X Presence Web Service as defined in Open Service Access, Parlay X Web Services, Part 14, Presence ETSI ES 202 391-14. A Parlay X Web Service enables a HTTP Web Service client to access such presence services as publishing and subscribing to presence information. The Parlay X Presence Web Service does not require developers to be familiar with the SIP protocol to build such a Web-based client; instead, Parlay X enables Web developers can build this client using their knowledge of Web Services.
The Presence Web Services application, which is deployed as a child application of the Presence application, contains the following MBeans that enable you to configure a Web Services deployment server:
The Presence Web Services application also includes the PresenceSupplierWebService and PresenceConsumerWebService MBeans, which contain attributes for managing presence publication and watcher subscriptions enabled through the OCMS implementation of Presence Consumer and Presence Supplier interfaces. For more information on the OCMS implementation of Parlay X Web Service and support of these interfaces, refer to Oracle Communication and Mobility Server Developer's Guide.
Starts the JMX framework for the Presence Web Services application and deploys all of its Model MBeans.The operations of the PresenceWebServiceDeployer MBean enable you to retrieve information of the objects exposed by the Presence Web Service to this MBean.
Table 9-32 Operations of the PresenceWebServiceDeployer MBean
| Operation | Description |
|---|---|
|
getManagedObjectNames |
Returns a String array containing the object names of the deployed application. |
|
getMBeanInfo |
Returns the meta-data for the deployed MBean. |
|
getMBeanInfo (locale) |
Returns the localized meta-data for the deployed Mbean. |
The PresenceSupplierWebService MBean (described in Table 9-33) enables you to manage the presence data published to watchers.
Table 9-33 Attributes of the PresenceSupplierWebService MBean
| Attributes | Description |
|---|---|
|
Expires |
The default expiry time, in seconds, for the PUBLISH of a presence status. The value entered for this attribute should be optimized to match that entered for the SessionTimeout attribute. |
|
PIDFManipulationAU |
The name of the application usage for PIDF ((Presence Information Data Format) manipulation. The default value is pidf-manipulation. |
|
PidfManipulationDocname |
The document name for pidf manipulation application usage. For example: hardstate. Unauthenticated users are blocked when no rule is found. If the URI contains a domain name instead of an IP address, then you must configure the DNS Server. The default value is hardstate. |
|
PresRulesAU |
The name of the pres-rules application usage. The default value is pres-rules. |
|
PresRulesDocname |
The name of the pres-rules document. The default value is presrules. |
|
PublicXCAPRootUrl |
The URL to the public XDMS server root, entered as http://<your.xdms:domain.com>/services/. For example, enter http://127.0.0.1:8080/services. |
|
SessionTimeout |
The timeout of the HTTP session, in seconds. The value entered for this attribute should be optimized to match the value entered for the Expires attribute. This timeout takes effect for new sessions only. |
|
SIPOutboundProxy |
The IP address of the outbound proxy server where all requests are sent on the first hop. Enter this address in the following format: sip:<IP address>;lr;transport=UDP You can also enter the default port (5060) in this address. For example, enter sip:127.0.0.1:5060;lr;transport=UDP. The shortest format for entering this address is sip:127.0.0.1;lr. If you do not define this attribute, then no outbound proxy will be used. |
The PresenceConsumerWebService MBean (described in Table 9-34) enables you to set the duration of watcher subscriptions.
Table 9-34 Attributes of the PresenceConsumerWebService MBean
| Attribute | Value |
|---|---|
|
Expires |
The default expiry time, in seconds, for watcher subscriptions. The value entered for this attribute should be optimized to match the value entered for the SessionTimeout attribute. |
|
SessionTimeout |
The timeout of the HTTP session, in seconds. The value entered for this attribute should be optimized to match the value entered for the Expires attribute. This timeout takes effect for new sessions only. |
|
SIPOutboundProxy |
The IP address of the outbound proxy server where all requests are sent on the first hop. Enter this address in the following format: sip:<IP address>;lr;transport=UDP You can also enter the default port (5060) in this address. For example, enter sip:127.0.0.1:5060;lr;transport=UDP. The shortest format for entering this address is sip:127.0.0.1;lr. If you do not define this attribute, then no outbound proxy will be used. |
The Aggregation Proxy is a server-side entry point for OMA clients that authenticates any XCAP traffic and Web Service calls (which are conducted through HTTP, not SIP) by providing identity assertion. This component acts as the gatekeeper for the trusted domain that houses the Presence Server and the XDMS Server.
Note:
The Aggregation Proxy uses the OCMS Logging modules.The Parlay X Web Service operates within a trusted domain where the Aggregation Proxy authorizes the user of the Web Service. It authenticates XCAP traffic and Web Service calls emanating from a Parlay X client by inserting identity headers that identify the user of the Web Services. The Aggregation Proxy then proxies this traffic (which is sent over HTTP) to the Parlay X Web Service and XDMS Server.
The attributes of the Aggregation Proxy MBean (Table 9-35) enable you to set the type of identity assertion that is appropriate to the XDMS Server. In addition, you set the host and port of the Web Server and XDMS server that receive the proxied traffic from the Aggregation Proxy.
Table 9-35 Attributes of the Aggregation Proxy
| Attribute | Description |
|---|---|
|
AssertedIdentityType |
Enter the number corresponding to the identity header inserted into proxied HTTP requests that is appropriate to the XDMS Server:
|
|
ContentHost |
Hostname of the Content Server where the Aggregation Proxy sends proxied requests. |
|
ContentPort |
The port number of the Content Server where the Aggregation Proxy sends proxied requests. |
|
ContentRoot |
The root URL of the Content Server. |
|
IgnoreUserpartCase |
Set to true if case-sensitive handling of the user name is not required. |
|
JAASLogingContext |
The |
|
JAASRoles |
A comma-separated list of JAAS roles for authentication. |
|
PresenceConsumerEndpoint |
The path to the endpoint of the Presence Consumer Web Service. The methods of the Presence Consumer interface enable watchers to obtain presence data. For more information, refer to Oracle Communication and Mobility Server Developer's Guide. |
|
PresenceSupplierEndpoint |
The path to the endpoint of the PresenceSupplier Web Service. The methods of the Presence Supplier Interface enable presentities to provide presence manage the data accessed by watchers. For more information, refer to Oracle Communication and Mobility Server Developer's Guide. |
|
TrustedHosts |
A comma-separated list of IP addresses of trusted hosts. Asserted identity headers are removed from requests that addresses that are not included in this list. |
|
WebServiceHost |
The host name of the Web Services deployment server to which the Aggregation proxies requests. |
|
WebServicePort |
The port of the Web Services deployment server to which the Aggregation proxies requests. |
|
XCAPHost |
The host name of the XDMS Server to which the Aggregation Proxy proxies requests. |
|
XCAPPort |
The port of the XDMS Server to which the Aggregation Proxy proxies requests. |
|
XCAPRoot |
The root URL of the XDMS Server. |
Secure the XDMS Server by deploying it behind the Aggregation Proxy. Access to the XDMS Server should be restricted only to the Aggregation Proxy and the Presence Server. In addition, securing the XDMS Server requires that you configure the Presence Sever application's XCapConfig MBean, the Aggregation Proxy and the Oracle Communicator as follows:
Deny access to any incoming XCAP request that lacks an asserted identity header by setting the value of the RequiredAssertedIdentity attribute of Presence Server's XCAPConfig MBean to true. Setting this attribute to true requires authentication of all XCAP by the Aggregation Proxy.
Set the appropriate XDMS Server-related values for the XCAPHost, XCAPPort, XCAPRoot, ContentHost, ContentPort and ContentRoot attributes of the Aggregation Proxy MBean.
Configure the Oracle Communicator's XDMS settings in customize.xml to point to the Aggregation Proxy -- not to the XDMS Server -- by defining the <RootContext> element as aggregationproxy, the context root of the Aggregation Proxy and by setting the <host> and <port> elements to the host of the Aggregation Proxy and the HTTPS port on that host, such as 443. See also "Enabling Presence" in " Configuring Oracle Communicator".
The Aggregation Proxy must be deployed as a child application of Subscriber Data Services. You can bind to the default-web-site for HTTP. To enable HTTP over SSL, you must configure the OC4J Container on which the Aggregation Proxy executes to provide HTTPS. Refer to Oracle Containers for J2EE Security Guide for instructions on configuring HTTPS. To enable access to the Aggregation Proxy over HTTPS, bind the Aggregation Proxy with the secure-web-site. Ensure that the Presence Server binds with the default-web-site if it resides on the same server with the Aggregation Proxy. Because the Presence Server resides in the presence.ear file, all of the HTTP servlets in that EAR file must bind to default-web-site.
Note:
Oracle Communication and Mobility Server Version 10.1.3.2 does not support direct access to the XDMS Server by HTTPS.OCMS writes logs for the traffic, system, and JMX components to the traffic.log, system.log, and jmx.log files located at the ORACLE_HOME/j2ee/home/log/sdp directory in standalone OC4J deployments and at ORACLE_HOME/J2EE/ocms/log/sdp in enterprise deployments. You can view these log files using any text editor. See also "Configuring the Logging System" and "SIP Servlet Container Logging".
You can deploy, undeploy and redeploy SIP applications to OC4J using either the wizard provided in Application Server Control Console or the admin_client.jar command-line tool. This section gives a brief overview of both of these options through the following:
"Deploying, Undeploying, and Redeploying SIP Servlet Applications with Application Server Control"
"Deploying, Undeploying, and Redeploying an Application Using the admin_client.jar Utility"
For more information, refer to Oracle Containers for J2EE Deployment Guide.
Note:
SIP applications can only be deployed to OC4J if they are packaged into a J2EE-compliant EAR file. For more information, see "Packaging and Deploying Applications".The Application Sever Control Console provides a wizard that steps you through deploying, undeploying, and redploying SIP applications.
Tip:
Use a firewall to block all incoming SIP traffic until all of the applications have been fully deployed and the server started.You can filter SIP traffic using a shell script, such as the following Linux script, blockport.sh, which uses the iptables tool.
#!/bin/bash if [ $# != 1 ] then echo "blockport.sh <port>" exit fi iptables -A INPUT -p tcp -m tcp --dport $1 -j DROP iptables -A INPUT -p udp -m udp --dport $1 -j DROP service iptables save echo "Port "$1" blocked."
Likewise, you can use a shell script to enable the flow SIP traffic once the server is running and all applications have been fully deployed. The following Linux script, unblockport.sh, is an example of script that enables SIP traffic:
#!/bin/bash if [ $# != 1 ] then echo "unblockport.sh <port>" exit fi iptables -D INPUT -p tcp -m tcp --dport $1 -j DROP iptables -D INPUT -p udp -m udp --dport $1 -j DROP service iptables save echo "Port "$1" unblocked."
For more information, see Deploying with Application Server Control Console in Oracle Containers for J2EE Deployment Guide.
The Deploy button on the Applications page invokes the deployment wizard, which guides you through the deployment process through the following pages:
The Select Archive page (Figure 9-8) is the first page of the wizard. To complete this page, point OC4J to the enter the location of the EAR (Enterprise Archive) file containing the SIP application. This page also enables you to select the option to create or apply a deployment plan, a client-side aggregation of all of the configuration data needed to deploy an archive into OC4J. If you use an existing deployment plan, you enter its location. If you opt for new deployment plan, select the Automatically Create a New Deployment Plan option. Refer to "Packaging and Deploying Applications" for information on EAR file structure and how to package a SIP Application for deployment.
Tip:
The wizard automatically creates a new deployment plan if you do not enter the location of an existing plan.Figure 9-8 Deploying an Application: Entering the Archive Location
Clicking Next invokes the Application Attributes page (Figure 9-9). This page enables you to enter the application name and select the parent application. The application name cannot contain spaces.
Select Subscriber Data Services as the parent application for OCMS applications requiring authentication.
Note:
The SIP application becomes a child of the default application if you do not specify a parent application.The Application Attributes page also enables you to set the binding of a Web application to a Web site by specifying the name portion of the name-web-site.xml configuration file that defines the Web site. A Web application deployed as part of a J2EE application must be bound to the Web site through which it is accessed.
The Web module context root, which will be appended to the URL used to access the application through a Web browser, is also set as part of the process to enable Web access. This value is typically read from the application.xml deployment descriptor packaged with the application.
Figure 9-9 Deploying an Application: Entering the Application Name and Parent Application
The Deployment Settings page (Figure 9-10) provides a tasks that enable you to edit the deployment plan.
Figure 9-10 Deploying an Application: Configuring the Deployment Settings
Complete deployment tasks as needed and then click Deploy. The confirmation page appears (Figure 9-11).
You can remove (undeploy) an application by first selecting it and then by clicking the Undeploy button. When you undeploy an application, you likewise undeploy the MBeans registered to the application.
Likewise, if you undeploy a parent application, its the child applications are also undeployed. As a result, the parent application and all related applications must be redeployed. See Oracle Containers for J2EE Deployment Guide for information on when to restart OC4J when undeploying an application.
The Redeploy button enables you undeploy an application without restarting OC4J. Redeploying a SIP application packaged within an EAR file prompts OC4J to undeploy the previous instance; you do not have to first select the application and then click Undeploy.
Like deploying an application, the wizard prompts you through a three-step process for redeploying an application in which you point OC4J to the EAR file, select or create a deployment plan, select the parent application and Web bindings, and complete deployment descriptor configuration tasks.
The admin_client.jar command-line utility used to perform deployment-related operations on active OC4J instances in an Oracle Application Server clustered environment as well as on standalone OC4J servers.
The admin_client.jar utility is installed by default in ORACLE_HOME/j2ee/home in an OC4J instance. OC4J must be started before this utility can be used.
To deploy an EAR, use the -deploy command with the EAR-specific context as follows:
java -jar admin_client.jar uri adminId adminPassword -deploy -file path/filename -deploymentName appName [-bindAllWebApps [webSiteName]] [-targetPath path] [-parent appName] [-deploymentDirectory path] -enableIIOP [-iiopClientJar path/filename]
To undeploy an application:
java -jar admin_client.jar uri adminId adminPassword -undeploy appName
To redeploy a previously deployed archive, use the -redeploy command and with the following syntax:
java -jar admin_client.jar uri adminId adminPassword -redeploy -file path/filename -deploymentName appName [-keepSettings] [-sequential]
Refer to Deploying with the admin_client.jar Utility in Oracle Containers for J2EE Deployment Guide for more information on the -redeploy command subswitches.
