Skip Headers

Oracle® Communication and Mobility Server Administrator's Guide Release 10.1.3 Part Number E10292-02 |
Home | Contents | Index | Contact Us

Previous | Next
| View PDF

# 9 Managing the SIP Server

This chapter, through the following sections, describes how to manage the OCMS SIP Server through Oracle 10g Enterprise Application Server Control.

- "Overview of SIP Server Management"

- "Starting, Stopping and Restarting the OCMS SIP Server"

- "Managing OCMS MBeans"

- "Deploying SIP Server Applications"

- "Viewing Log Files"

- "Managing OCMS through JBoss Application Server"

## Overview of SIP Server Management

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

Description of "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.

## Starting, Stopping and Restarting the OCMS SIP Server

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.

### Starting an Application and Stopping a SIP Servlet Application

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

Description of "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.

## Managing OCMS MBeans

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.

Figure 9-3 Viewing MBeans

Description of "Figure 9-3 Viewing MBeans"

See Oracle Containers for J2EE Configuration and Administration Guide for information on managing MBeans.

### Accessing 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 OCMS MBeans".

Figure 9-4 Viewing System MBeans

Description of "Figure 9-4 Viewing System 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.

#### Accessing SIP Servlet Container MBeans

The System MBean Browser enables you to browse the SIP Servlet Container MBeans (Figure 9-3). To access the System MBean Browser:

1. Navigate to the OC4J Home page for the SIP Server instance.

2. Click Administration. The Administration page appears, displaying the available tasks.

3. If needed, expand the JMX section of the task list to display System MBean Browser.

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

   Description of "Figure 9-5 The JMX Section of the Task List"

Tip:

Use the Search function to locate an MBean

#### Accessing the MBeans for a Selected SIP Application

To view the MBeans for a selected application:

1. Click Applications on the SIP Server OC4J home page. A list of applications appears.

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

3. Click Apply to commit any changes to the MBean's attributes.

### Configuring the SIP Servlet Container MBeans

This section describes the configuration parameters for the following System MBeans (listed in Table 9-1):

Table 9-1 SIP Servlet Container MBeans

Tasks | MBean Name
--- | ---
Tasks include: Setting or changing the IP address of the SIP Container. Setting or changing the DNS IP address. Setting or changing the domains and realms. Setting or changing the traffic port. Setting or changing the proxy that receives client requests. Setting the default applications for incoming requests. | SIP Servlet Container
Setting the log levels for the logger components (badmsg, config, eventlogger, statistics, system, and traffic). For more information, see Chapter 10, "Configuring the Logging System". | SIP Servlet Container Logging
Setting bindings that enable clients to traverse NAT (Network Address Translating) entities. | STUN Service
View the current statues of the system queues. | SIP Servlet Container Monitor
Set overload actions when the capacity thresholds for memory usage, Application Queue usage, Network Queue usage, or SIP Session Table usage are reached. | Overload Policy
Set the default timeouts for OC4J clusters. | SIP Cluster

#### SIP Servlet Container

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 (SipServletContainer) 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

Value | SIP Servlet Container Attribute(s)
--- | ---
The IP address of the SIP Container. | IPAddress
The traffic port used by the SIP Container. | SIPPort
The proxy for receiving client requests. | EdgeProxy
The domain (or hostname) of the SIP Server and the SIP realm used for authentication. | DomainsandRealms

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 | The host, port, and transport used in the Contact header that is embedded in SIP requests by applications acting as User Agent Clients (UACs). Enter this value as a SIP URI. 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 | The host, port, and transport placed in the Contact header for distributable applications acting as User Agent Clients (UACs) in a high-availability environment.
DistributableRecordRoute | The host, port, and transport placed in the RecordRoute header for distributable applications in a high-availability environment. Enter this value as a SIP URI in the following format: `sip:host:port;transport=tcp`. You need only enter the hostname (`sip:my.host:5060;transport=tcp`). For high availability configurations, configure this parameter in the following format: `sip:<SIP container IP address>:<port>`. Remove the transport method to enable the use of any type of transport between the Edge Proxy and OCMS. For more information, see "Configuring the OCMS SIP Containers for High Availability".
DistributableVia | The host, port, and transport used in the Via header for distributable applications in a high-availability environment. Enter this value as a SIP URI in the following format: `sip:host:port;transport=tcp`. You need only enter the hostname (`sip:my.host:5060;transport=tcp`).
DnsIpAddress | The IP address for the DNS against which the SIP servlet containers resolve addresses. Enter the IP address in the format of `<IP>:<port>/<transport>`. For example, enter 127.0.0.1:53/UDP. You can only enter an IP address as the value; you cannot enter a domain name.
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 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 used by the load balancer in front of the Edge Proxies. Set this value using the following format: `sip:<EdgeProxy or Load Balancer IP address>:<port>;lr` For more information, see "Configuring the OCMS SIP Containers for High Availability".
RecordRoute | The host, port and transport used in the RecordRoute header of non-distributable applications. Enter this value as a SIP URI in the following format: `sip:host:port;transport=tcp`. You need only enter the hostname (`sip:my.host:5060;transport=tcp`). For high availability configurations, configure this parameter in the following format: `sip:<SIP Container IP address>:<port>`. Remove 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 `org.aopalliance.intercept.MethodInterceptor`. If the class has a `public` constructor with `javax.servlet.ServletConfig` it will be used to instantiate the interceptor. To enable P-Asserted-Identity support (RFC 3325) for authentication when using OCMS UserService and SecurityService, replace `oracle.sdp.sipservletengine.SecurityInterceptor` with `oracle.sdp.extinterceptors.PaiSecurityInterceptor`.
SipServletOc4jInterceptors | A comma-separated list of SipServlet interceptor classes specific to OC4J. The interceptors must implement `org.aopalliance.intercept.MethodInterceptor`. If the class has a `public` constructor with `javax.servlet.ServletConfig` it will be used to instantiate the interceptor. This list will be prepended to the list of interceptors entered for the SipServletCommonInterceptors attribute.
StatisticsPeriodicity | The interval, in minutes, at which the SIP servlet container logs statistics that display in the SIP Servlet Container Monitor. Setting this attribute to 0 suspends logging operation. See also the statistics attribute of the SIP Servlet Container Logging MBean.
TimerListenerOc4jInterceptors | A comma-separated list of OC4J-specific `TimerListener` interceptor classes. The interceptors must implement `org.aopalliance.intercept.MethodInterceptor`.
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.
UdptoTcpTriggerSize | The maximum number of bytes contained in a request message sent by the SIP servlet container. When a request message reaches this size, the SIP servlet container uses TCP rather than UDP to transport the request. The default value for a request is 1300 bytes.
UseStun | Select true to use STUNbis keepalive traffic.
UseTCP | Select true for the SIP servlet 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 servlet container to listen for UDP traffic.
Via | The host, port, and transport used in the VIA header of non-distributable applications. Enter this value as a SIP URI.

##### Setting an Alias for an Application

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 or the JBoss Application Server. 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. On the JBoss Application Server, for example, the name of the deployed application is the name of the EAR file followed by the name of the ssr 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.

Note:

The value for set for ApplicationAliases attribute must also match the `appId` parameter of the the Application Router's SIPURIList attribute to ensure that the OCMS SIP servlet container invokes the applications that are appropriate to incoming requests. The `appId` parameter is case-sensitive.

#### SIP Servlet Container Logging

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, and also SIP servlet container's internal system logs:

- OFF – The OFF level turns off all logging. This is the highest log level.

- ERROR – The ERROR level designates error events which may allow the application to continue running. ERROR messages indicate a serious problem that requires immediate attention. ERROR messages are not caused by bugs in OCMS.

- 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. These messages indicate a major life-cycle event, such as the activation or de-activation of a primary sub-component. This is the default log level set for all loggers except for badmsg and traffic.

- DEBUG – The DEBUG Level designates detailed informational events which are useful in debugging an application. These messages indicate trace or debug information for events that are meaningful to end users of the product, such as public API entry or exit points.

- ALL – The ALL level turns on all logging. This is the lowest log level.

Note:

Some of the component loggers do not use all of these logging levels.

By default, all of the component loggers except for traffic and badmsg are set to INFO. The traffic and badmsg logs are set to OFF. As a consequence, a system using these default settings will not write any messages to the traffic or badsmg logs.

Table 9-4 Attributes of the SipServletContainerLogging MBean

Attribute | Description
--- | ---
badmsg | Sets the log level for the bad messages log. This is a debug log.
config | Sets the log level for the configuration log. This is a debug log.
eventlogger | Sets the log level for the event log. You can use the event logs for charging.
statistics | Sets the log level for the statistics log, a debug log that reports SIP Servlet Container Monitor- related statistics at regular intervals. See also the SIP Servlet Container's StatisticsPeriodicityattribute.
system | Sets the log level for all SDP-related events.
traffic | Sets the log level for SIP traffic. This is a debug log.

For information on configuring the log4j logging system, see "Configuring the Logging System". For information on viewing the log files, see "Viewing Log Files".

#### STUN Service

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 on which to listen for incoming Binding Requests. The default value is 127.0.0.1.
PrimaryPort | The primary STUN port on which to listen for incoming Binding Requests. The value is UDP port 3478, the default STUN Port as described in RFC 3489.
SecondaryAddress | The secondary STUN address on which to listen for incoming Binding Requests. This cannot be the same value as PrimaryAddress.
SecondaryPort | The secondary STUN port to which to listen for incoming Binding Requests. The default value is UDP port 3479.

#### SIP Servlet Container Monitor

The SIP Servlet Container Monitor MBean (SipServletContainerMonitor) displays read-only values for system queues and SIP transactions that enable you to assess the performance of the SIP servlet container when it enters an abnormal state. These values can also serve as a reference for system tuning.

The following sections describe SIP Servlet Container Monitor's attributes:

- "Viewing System Status"

- "Viewing Transactions"

- "Using the Current, Peak, and Total Usage Statistics to Tune the System"

##### Viewing System Status

Table 9-6 lists the attributes that display the current status of the SIP servlet container.

Table 9-6

SIP Servlet Container Status | Attribute
--- | ---
The time that the SIP container was last started. | SipServiceStartTime
The time that the SIP container entered its current state. | SipServiceLastChanged
The number of events dropped by OCMS. | SipMessagesDropped

##### Viewing Transactions

The SipServletContainerMonitor MBean's SipSummaryTotalTransactions attribute displays the total number of transactions (both current and completed) as a read-only value. The MBean further delineates transactions by displaying the total number of requests received by the SIP servlet container as well as the total number of subsequent responses that it receives and sends.

Total Requests and Responses

The SipSummaryInRequests attribute displays the total number of requests received by the SIP servlet container. In addition to this attribute, the SipServletContainerMonitor provides read-only values for the responses that comprise each transaction, both in terms of the total of SIP response messages received and sent by the SIP servlet container (the SipSummaryInResponses and SipSummaryOutResponses attributes, respectively) and also in terms of the total number of messages from provisional responses (Status Code 1xx) to the final responses (Status Codes 200 - 600). The SipServletContainerMonitor displays the total of SIP responses for each message category supported by OCMS (Table 9-7). See RFC 3261 and RFC 3265 for more information on response codes.

Table 9-7 SIP Response Messages Supported by OCMS

Status Code | Reason Phrase | Related Attributes
--- | --- | ---
1xx | Provisional Response Messages | 1xx-related attributes: SipStatsInfoClassIns SipStatsInfoClassOuts
2xx | Success Messages | 2xx-related attributes: SipStatsSuccessClassOuts SipStatsSuccessClassIns
3xx | Redirection Response Messages | 3xx-related attributes: SipStatesRedirClassIns SipStatsRedirClassOuts
4xx | Client Error Responses | 4xx-related attributes: SipStatsReqFailClassIns SipStatsReqFailClassOuts
5xx | Server Failure Responses | 5xx-related attributes: SipStatsServerFailClassIns SipStatsServerFailClassOuts 503ResponseSent
6xx | Global Failure Messages | 6xx-related attributes: SipStatsGlobalFailClassIns SipStatsGlobalFailClassOuts
NA | Non-SIP Response Codes | Non-SIP response-related attributes: SipStatsOtherClassesIns SipStatsOtherClassesOuts

Provisional Response Messages

As described in RFC 3261, the 1xx SIP response messages indicate informational or provisional responses and are sent when servers expects that obtaining a final response will exceed 200 milliseconds. The SipStatsInfoClassIns indicates the total number of 1xx responses received by the SIP servlet container, including transmission. The SipStatsInfoClassOuts attribute represents the number of messages sent, relayed, or re-transmitted by the SIP servlet container.

Success Messages

The SipStatsSuccessClassOuts and SipStatsSuccessClassIns represent the total number of 200 (OK) or 202 (Accepted) response messages sent and received by the SIP servlet container, respectively.

Redirection Response Messages

The 3xx responses provide information about the user's new location, or about alternative services that might be able to satisfy the call. The SipStatesRedirClassIns attribute represents the total number of 3xx responses received by (and re-transmitted to) the SIP servlet container. The SipStatsRedirClassOuts attribute represents the total number of 3xx responses sent (or re-transmitted) by the SIP servlet container.

Client Error Responses

The 4xx response messages are failure responses issued from server. When a client receives a 4xx response message, it should not attempt to send the request again without modifying it. The SipStatsReqFailClassIns attribute represents the total number of client error received by (or re-transmitted to) the SIP Servlet Container. The SipStatsReqFailClassOuts attribute represents the total number of client error messages sent (or retransmitted) by the SIP servlet container.

Server Failure Responses

The SIP Servlet Container sends the following error messages:

- 500 Server Internal Error

- 501 Not Implemented

- 502 Bad Gateway

- 503 Service Unavailable

- 504 Server Time-out

- 505 Version Not Supported

- 513 Message Too Large

The SipStatsServerFailClassIns attribute represents the total number of 5xx response messages received by (or re-transmitted to) the SIP servlet container. The SipStatsServerFailClassOuts attribute represents the total number of 5xx response messages sent (or re-transmitted) by the SIP servlet container.

While the SipStatsServerFailClassOuts attribute represents all of the 5xx response messages sent by the SIP servlet container, the 503ResponseSent attribute represents the total number of 503 (Service Unavailable) responses sent by the SIP servlet container.

Global Failure Messages

The 6xx responses provide information specific to a user (as opposed to information specific to the instance indicated in the Request-URI). The SipStatsGlobalFailClassIns represents the total number of 6xx response messages received by (or re-transmitted) to the SIP servlet container. The SipStatsGlobalFailClassOuts attribute represents the total number of 6xx responses sent (or relayed) by the SIP servlet container.

Non-SIP Response Codes

The SipStatsOtherClassesIns and SipStatsOtherClassesOuts represent non-SIP response messages (that is, response codes other than the 1xx, 2xx, 3xx, 4xx, 5xx, and 6xx that OCMS supports). The SipStatsOtherClassesIns attribute represents the total number of non-SIP responses messages received by (or re-transmitted to) the SIP servlet container. The SipStatsClassesOuts attribute represents the total number of non-SIP response messages sent (or relayed) by the SIP servlet container.

##### Using the Current, Peak, and Total Usage Statistics to Tune the System

This SipServletContainerMontior's attributes enable you to view the current, peak and total usage for the application and network queues as well as the current and total number of SIP sessions. These read-only values 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. See also "Deactivating the Overload Protection for System Tuning".

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.

#### Overload Policy

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 in Table 9-8). 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-8 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.

##### Overview of Overload Policy Architecture

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

Collectors notify policies when states change. The Overload Policy subscribes to state changes for the following collectors:

- Memory Usage

- Application Queue

- Network Queue

- SIP Session Table Usage

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

High and low levels keep overload actions from starting and stopping repeatedly for small changes in memory usage. In addition to the threshold level that sets the start of the 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 are 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 executes.

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-9 lists the attributes that you configure to set the values for the high and low warning thresholds for memory usage.

Table 9-9 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-10 lists the attributes that you configure to set the high and low alarm thresholds for memory usage.

Table 9-10 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-11 lists the attributes that you configure to set the high and low critical thresholds for memory usage.

Table 9-11 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 after 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 that 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-12), Alarm (Table 9-13), and Critical (Table 9-14) thresholds of the Application Queue.

Table 9-12 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-12 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-13 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-13 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-14 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-14 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-15), Alarm (Table 9-16), and Critical (Table 9-17) thresholds of the Network Queue.

Table 9-15 lists the attributes that you configure to set the high and low threshold values that trigger Warning actions.

Table 9-15 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-16 lists the attributes that you configure to set the high and low threshold values that trigger Alarm actions.

Table 9-16 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-17 lists the attributes that you configure to set the high and low values that trigger Critical actions.

Table 9-17 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 SIP servlet engine'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-18), Alarm (Table 9-19), and Critical (Table 9-20) thresholds that trigger overload actions.

Table 9-18 lists the attributes that you configure to set the warning thresholds.

Table 9-18 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-19 lists the attributes that you configure to set the alarm level thresholds.

Table 9-19 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-20 lists the attributes that you configure to set the critical thresholds.

Table 9-20 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.

##### Deactivating the Overload Protection for System Tuning

Technically, overload protection is always activated. When you tune the system, you can prevent overload actions from executing by doing either of the following:

- Disabling all of the rules by setting all of the trigger values to zero (0).

- Setting the AppQueueMaxSize, StackQueueMaxSize, and SipSessionTableMaxSize attributes to high numbers.

#### Memory Monitor

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-21 lists the attributes of the Memory Monitor MBean.

Table 9-21 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.

##### Starting and Stopping the Memory Monitor

The start and stop operations enable you to manually start and stop the Memory Monitor.

#### SIP Cluster

The SIP Cluster MBean (SipCluster) enables you to override the default timeouts set for OC4J clusters. High Availability for OCMS is based on OC4J clusters. Because this framework is based on HTTP, the intervals set for replication are inappropriate for SIP, as they are on the order of seconds rather than milliseconds.

Caution:

Because the values set for these timers can significantly impact high availability for OCMS, contact Oracle Support (http://www.oracle.com/) support before you change the values for this MBean. For most systems, the seeded values will suffice.

The SIPCluster MBean enables you to configure the following timers for state replication between peer nodes:

- RestoreTimeout -- If a node cannot recognize the session ID of an incoming request, it requests a state replica from a peer. The interval set by the attribute reflects the time that the node waits for the requested state replica from another peer.

  Note:

  The default value for the restore timeout for OC4J clusters is 0, meaning that the peer would wait indefinitely for the state replica. Without the override provided by this attribute, the peer might block all of its active threads under some circumstances.

- OwnedByTimeout -- The time needed to pass ownership of the replicated data from one peer to another. This value sets the interval in which the node owning the state replica drops ownership and the requesting node confirms ownership. Once the requesting peer attains the data, its session replica is promoted to a "live" state.

  Note:

  The default value to pass ownership for OC4J clusters is -1, which instructs the peer not to wait for the replicated data. Because there is no interval between ownership, two peers can concurrently host "live" session replicas for a short period of time.

### Configuring SIP Applications

This section describes the configuration enabled by the MBeans registered to the following SIP applications:

- Subscriber Data Services

- Presence (See "Overview of Presence")

- Proxy Registrar

- Application Router

- Aggregation Proxy

#### Subscriber Data Services

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-22 describes the attributes of the AA Service MBean.

  Table 9-22 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 `Linear`, `Exponential` and `Constant`, are packaged as ModelMBeans. The default value is hotisp.math:service=MathFunction,name=Linear.
  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.

  Table 9-23 Subscriber Data Services MBeans

  MBean | Tasks
  --- | ---
  ModelMBeanDeployer | The helper MBean used by the Subscriber Data Services application to deploy its Model MBeans.

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

##### CommandService

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:

1. Click the Operations tab. A list of `get` commands appears.

2. Click help for a returning a help String for a partial command. The parameters for the `help` operation appear.

3. Enter account in the Value field.

   Tip:

   Click Use Multiline Editor to expand the Value field to accommodate long command names.

4. 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".

   Figure 9-6 Viewing Help for a Command

   Description of "Figure 9-6 Viewing Help for a Command"

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

Figure 9-7 Viewing Available Commands

Description of "Figure 9-7 Viewing Available Commands"

The Command Service MBean is deployed within the presence application to enable user provisioning to the XDMS (XML Document Management Server). See Command Service (XDMS Provisioning).

#### Proxy Registrar

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-24 describes the attributes of the Proxy Registrar.

Table 9-24 Attributes of the Proxy Registrar

Attributes | Description
--- | ---
CurrentRegDevices | A read-only attribute that displays the number of currently 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 (the default value), then third-party registrations are rejected (the requestor receives a 403 Forbidden status code). This is a read-only attribute that is always set to false.
SipRegMaxUsers | A read-only attribute that specifies the maximum number of users supported by the Proxy Registrar.

#### Application Router

When the OCMS SIP servlet container receives incoming requests that do not contain the application ID (`appId`) parameter, the container invokes the Application Router which inserts routing information that includes this parameter into the request's ROUTE. As a result, the container can respond to incoming `INVITE`, `MESSAGE`, `PUBLISH`, `REGISTER`, and `SUBSCRIBE` requests by invoking the appropriate applications in the correct order. As described in Oracle Communication and Mobility Server Developer's Guide, the `appId` parameter is an OCMS extension to JSR-116 used to route requests to applications.

Because requests generated by SIP clients other than Oracle Communicator typically do not contain the `appId` parameter in either their ROUTE or REQUEST URI headers, the presence of the `appId` parameter in an incoming request's ROUTE header ensures that the OCMS SIP servlet container correctly handles requests. The Application Router MBean (ocmsrouteloaderear, illustrated in Figure 9-8) enables you to configure the destinations for incoming `INVITE`, `MESSAGE`, `PUBLISH`, `REGISTER`, and `SUBSCRIBE` requests by defining the application routing sequence and other route-related criteria.

Figure 9-8 Setting the Application Routing for an INVITE Request

Description of "Figure 9-8 Setting the Application Routing for an INVITE Request "

Table 9-25 describes the attributes that you configure for the routing of `INVITE`, `MESSAGE`, `PUBLISH`, `REGISTER`, and, `SUBSCRIBE` requests.

Table 9-25 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. Select true to set the incremental execution mode for the Application Router. For the incremental mode, the Application Router inserts the first (or top-most) URI configured in the SIPURIList attribute as well as the URI of the return route to the Application Router itself, which is defined as the value to the RouteLoaderUri attribute. When the request returns to the Application Router, the Application Router then checks if the Request URI has changed. If so, it proxies the request to this new URI. If the Request URI remains unchanged, then the Application router inserts the next URI defined in the SIPURIList into the request's ROUTE header and repeats the cycle. Select false to set the standard mode for the Application Router. In the standard mode, the Application Router inserts all of the routes defined in the SipUriList attribute in the request's ROUTE header. The request then follows the routes in the sequence that they are defined in the SipUriList attribute.
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 servlet container.
SipUriList | A comma-separated list of URIs, transport methods, and `appId`s of applications that the Application Router inserts in the ROUTE header of an incoming request. The default list, which routes requests to the Proxy Registrar, is defined as
    sip:<SIP Container IP Address>:<SIP port>;transport=TCP;lr;appId=proxyregistrar
For example: `sip:144.25.174.189:5060;transport=TCP;lr;appId=proxyregistrar` Request routing is set according to the order of the applications listed in this attribute. For example, to call an application called dialin as the first destination for an `INVITE` request, insert the information for dialin as the first item on the list as follows:
    sip:144.25.174.189:5060;transport=TCP;lr;appId=dialin,sip:144.25.174.189:5060;      transport=TCP;lr;appId=proxyregistrar
To ensure that request-related applications that you deploy to the OCMS SIP servlet container are invoked in response to incoming requests, you must add any application that you deploy to this list. The name of the application defined for the `appId` parameter (which is case-sensitive) can either be the full name of the deployed application, or an alias for the application. If the latter, the name must match the application alias set for the ApplicationAliases parameter of the SIP Servlet Container MBean. The Proxy Registrar must always be the last item listed in the SIPUriList attribute. See also "Deploying SIP Server Applications". For more information on the `appID` parameter, refer to Oracle Communication and Mobility Server Developer's Guide.

### Overview of Presence

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 as 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

- Presence Status Subscriptions

- Watcher-Info Support

- Presence XDMS Authorization of Subscriptions

- Privacy Filtering

- Presence Hard State

- Composition of Multiple Presence Sources

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 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 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 as dictated by a composition policy. 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 Presence

Configuring the following MBeans enables Presence:

- Bus

- PackageManager

- Presence

- PresenceApplicationDeployer

- PresenceEventPackage

- PresenceWInfoEventPackage

- UA-ProfileEventPackage

- UserAgentFactoryService

##### Configuring XDMS

The following MBeans enables you to configure the XDMS (XML Document Management Server):

- XCapConfig

- Command Service (XDMS Provisioning)

Note:

If you change any attributes of the following MBeans, you must restart OCMS for these changes to take effect.

- Presence

- PresenceEventPackage

- PresenceWInfoEventPackage

- UAProfileEventPackage

- XCAPConfig

#### Bus

The Bus MBean supports presence by setting the thread pool, the high and low watermarks for the job queues, and the duration that a job remains in the queue before notifications are dispatched. Table 9-26 describes the attributes of the Bus MBean.

Table 9-26 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.

#### PackageManager

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-27 describes the attributes of the PackageManger MBean.

Table 9-27 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 (`waitingsubscleanupinterval`) to decide if a waiting subscription is old enough to be removed from the subscribed resource.

#### Presence

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-28) include those for setting the composition policy for creating a unified document when a user publishes presence documents from two or more clients, as well as setting the blocking, filtering, and presence hard state.

Table 9-28 Attributes of the Presence MBean

Attribute | Description/Value
--- | ---
CompositionPolicyFilename | The filename of the composition policy document. Values include `compose.xslt`, for the OCMS composition policy, and `compose_OMA.xslt`, for the OMA composition policy.
DefaultSubHandling | The default subscription authorization decision that the server makes when no presence rule is found for an authenticated user. The defined values are: block confirm polite-block 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 (`http://www.ietf.org/internet-drafts/draft-ietf-simple-presence-rules-04.txt`).
DocumentStorageFactory | The name of the `DocumentStorage` Factory Class. The default value is `oracle.sdp.presenceeventpackage.document.XMLDocumentStorageFactoryImpl`.
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: file memory The default value is memory.
HttpAssertedIdentityHeader | The type of asserted identity header used in all HTTP requests from the Presence Server to the XDMS. Set the value of this attribute to one expected by the XDMS. Valid values: X_3GPP_ASSERTED_IDENTITY X_3GPP_INTENDED_IDENTITY X_XCAP_ASSERTED_IDENTITY (The default value.)
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 the XDMS 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 the XDMS 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 `TrasformerFactory` class. The default value is `net.sf.saxon.TransformerFactoryImpl`.

#### PresenceEventPackage

Table 9-29 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-29 Attributes of the PresenceEventPackage

Attribute | Value/Description
--- | ---
Description | A description of the PresenceEventPackage. For example: The event package that enables presence.
DocumentFactory | The `DocumentFactory` class name. The default value is `oracle.sdp.presenceeventpackage.document.PresenceDocumentFactoryImpl`.
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 `EventStateCompositor`. The default value is `oracle.sdp.presenceeventpackage.PublishControl`.
Name | The name of this event package. The default value is Presence.
Notifier | The name of the `Notifier` class. The default value is `oracle.sdp.presenceeventpackage.PresenceSubscriptionControl`.
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 `oracle.sdp.presenceeventpackage.PresentityManagerImpl`.

#### PresenceWInfoEventPackage

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-30) sets the subscription state information for the Watcher Information Event Package.

Table 9-30 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 `DocumentFactory` class. The default is `oracle.sdp.eventnotificationservice.DocumentFactoryImpl`.
Name | The name of the event package. The default value is presence.winfo.
Notifier | The `Notifier` class name. The default value is `oracle.sdp.presenceeventpackage.PresenceSubscriptionControl`.
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 Response (Service Unavailable). The default value is 100.
NotifierMinExpires | The minimum time, in seconds, for a SUBSCRIBE to expire.
ResourceManagerClassName | The name of the `ResourceManager` class. The default is `oracle.sdp.winfoeventpackage.WatcherinfoResourceManager`.

#### UA-ProfileEventPackage

Table 9-31 describes the attributes of the UA-ProfileEventPackage MBean.

Table 9-31 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 `Document Factory` class name. The default value is: `oracle.sdp.eventnotificationservice.DocumentFactoryImpl`
Name | The name of the event package. The default value is ua-profile.
Notifier | The name of the `Notifier` class. The default value is: `oracle.sdp.presenceeventpackage.PresenceSubscriptionControl`
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 Response (Service Unavailable). 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: `oracle.sdp.winfoeventpackage.WatcherinfoResourceManager`

#### UserAgentFactoryService

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 for presence.

Table 9-32 Attributes of the UserAgentFactoryService MBean

Attribute Name | Description/Value
--- | ---
DNSNames | A comma-separated list of DNS (Domain Name System) IP addresses used by the user agent.
IpAddress | The IP address for the user agent client; use the empty string (the default setting) for the default network interface on the current system.
PreferredTransport | The preferred transport protocol that enables communication between the Presence Server and the XDMS. The default value is TCP. Valid values are TCP and UDP.
Port | The IP port for the user agent client. The default value is 5070.

#### Command Service (XDMS Provisioning)

The Command Service MBean enables user provisioning to the XDMS. For more information see "CommandService".

#### XCapConfig

The XCapConfig MBean controls the configuration of the XDMS, 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 is external to OCMS.

Table 9-33 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 and then the document will be stored. The default value is true.
MaxContentLength | The maximum size, in bytes, for an XDMS document. Although Oracle recommends a default maximum size per XDMS document of 1 MB (1000 contacts at about 1 KB each), you can increase or decrease the size of the document. If you increase the document size, then you must be sure to that there is sufficient disk space to accommodate the XDMS document * the number of users * the number of applications. If you set a smaller per-document size, then this calculation is reduced to the sum of (`max_doc_size_n` * number of users) where each `max_doc_size_n` is specific to application `n`. The default size for the resource-lists document is also 1 MB.
PersistenceRootUrl | 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.
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.
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 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). The XDMS 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 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"
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.

### Configuring Presence Web Services

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 an 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:

- Bus

- PackageManager

  - PresenceEventPackage

  - PresenceWInfoEventPackage

  - UA-ProfileEventPackage

- Presence

- UserAgentFactoryService

- XCapConfig

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.

#### PresenceWebServiceDeployer

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

#### PresenceSupplierWebService

The PresenceSupplierWebService MBean (described in Table 9-35) enables you to manage the presence data published to watchers.

Table 9-35 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 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.

#### PresenceConsumerWebService

The PresenceConsumerWebService MBean (described in Table 9-36) enables you to set the duration of watcher subscriptions.

Table 9-36 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.

#### Aggregation Proxy

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.

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.

Note:

The Aggregation Proxy uses the OCMS Logging modules.

The attributes of the Aggregation Proxy MBean (Table 9-37) enable you to set the type of identity assertion that is appropriate to the XDMS. In addition, you set the host and port of the Web Server and XDMS that receive the proxied traffic from the Aggregation Proxy.

Table 9-37 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: X_3GPP_ASSERTED_IDENTITY (the default) X_3GPP_INTENDED_IDENTITY X_XCAP_ASSERTED_IDENTITY
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 `name` for the JAAS (Java Authentication and Authorization Service) `javax.security.auth.login.LoginContext`.
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 with 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 to which the Aggregation Proxy proxies requests.
XCAPPort | The port of the XDMS to which the Aggregation Proxy proxies requests.
XCAPRoot | The root URL of the XDMS.

#### Securing the XDMS with the Aggregation Proxy

Secure the XDMS by deploying it behind the Aggregation Proxy. Access to the XDMS should be restricted only to the Aggregation Proxy and the Presence Server. In addition, securing the XDMS 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-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 -- 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 by HTTPS.

## Viewing Log Files

Log files are named after the component loggers. For example, the log for the traffic component is called the traffic.log. OCMS writes logs for the traffic, system, statistics, config and badsmg components to the log files located at the `ORACLE_HOME/j2ee/home/log/sdp` directory in OC4J installations and at `$JBOSS_HOME/server/$jboss_server_name/default/log/sdp` directory in JBOSS Application Server installations in standalone OC4J deployments. OCMS writes these logs to `ORACLE_HOME/J2EE/ocms/log/sdp` in enterprise deployments.

Note:

Debug messages are written to the system directory, which is also located in the sdp directory.

You can view these log files using any text editor. See also "Configuring the Logging System" and "SIP Servlet Container Logging".

## Deploying SIP Server Applications

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 topics:

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

### Deploying, Undeploying, and Redeploying SIP Servlet Applications with Application Server Control

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

#### Deploying an Application using the Deployment Wizard

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-9) is the first page of the wizard. To complete this page, point OC4J to 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-9 Deploying an Application: Entering the Archive Location

  Description of "Figure 9-9 Deploying an Application: Entering the Archive Location"

  - Clicking Next invokes the Application Attributes page (Figure 9-10). 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-10 Deploying an Application: Entering the Application Name and Parent Application

  Description of "Figure 9-10 Deploying an Application: Entering the Application Name and Parent Application"

- The Deployment Settings page (Figure 9-11) provides a tasks that enable you to edit the deployment plan.

  Figure 9-11 Deploying an Application: Configuring the Deployment Settings

  Description of "Figure 9-11 Deploying an Application: Configuring the Deployment Settings"

  Complete deployment tasks as needed and then click Deploy. The confirmation page appears (Figure 9-12).

  Figure 9-12 Confirming the Deployment

  Description of "Figure 9-12 Confirming the Deployment"

Note:

To ensure that the OMCS SIP servlet container responds appropriately to incoming requests, you must add any deployed application that processes requests to the Application Router's SIPUriList attribute. Configuring this attribute ensures that applications are added to the ROUTE header of incoming `INVITE`, `MESSAGE`, `PUBLISH`, `REGISTER`, or `SUBSCRIBE` requests from non-OCMS (that is, non-OCMS Communicator) SIP clients. The Proxy Registrar must always be the last item listed in the SIPUriList attribute.

#### Undeploying an Application Using the Deployment Wizard

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.

#### Redeploying an Application Using the Deployment Wizard

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.

### Deploying, Undeploying, and Redeploying an Application Using the admin_client.jar Utility

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.

#### Deploying an Application Using admin_client.jar

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]

#### Undeploying an Application Using admin_client.jar

To undeploy an application:

    java -jar admin_client.jar uri adminId adminPassword -undeploy appName

#### Redploying an Application Using admin_client.jar

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.

## Managing OCMS through JBoss Application Server

You can install OCMS on top of JBoss Application Server (Version 4.0.5) by Red Hat Inc.

Note:

Oracle High Availability is not supported when OCMS is installed on top the JBoss Application Server.

### Starting and Stopping OCMS through JBoss Application Server

This section describes how to start and stop OCMS on both Windows and Linux operating systems.

#### Starting and Stopping OCMS on Windows

To start OCMS on Windows:

From Programs, select Oracle Communication and Mobility Server and then select Start OCMS.

To stop OCMS:

From Programs, select Oracle Communication and Mobility Server and then select Stop OCMS.

#### Starting and Stopping OCMS on Linux

To start OCMS on Linux systems:

Enter `JBOSS_HOME/sdp/bin/startocms`

To stop OCMS:

Enter `JBOSS_HOME/sdp/bin/stopocms`

### Managing OCMS MBeans through JBoss Application Server

Using The JMX Console, you can configure the OCMS MBeans and invoke the MBean operations. The MBean attributes exposed through this console are the same as those exposed through OC4J.

Once OCMS starts and initializes JBoss Application Server, you can access OCMS MBeans and applications as follows:

1. In a browser, enter host and port for the JBoss Application Server. For example, enter http://localhost:8080/. The default page appears (Figure 9-13).

   Figure 9-13 The Default Page of the JBoss Application Server

   Description of "Figure 9-13 The Default Page of the JBoss Application Server"

2. Access the JMX Agent View by clicking either JMX Console or JBoss Web Console. If you select the later, expand System in the navigation tree and then select JMX MBeans (Figure 9-14).

   Tip:

   Use the ObjectName Filter (illustrated in Figure 9-14) to locate specific MBeans. For example, to locate the SIP Servlet Container-related Mbeans described in "Managing OCMS MBeans", enter *:type=SipContainer,* and then click ApplyFilter.

   Figure 9-14 OCMS MBeans Accessed through the JMX Console

   Description of "Figure 9-14 OCMS MBeans Accessed through the JMX Console"

3. Click the link of an MBean or application to access the attributes. For example, to access the attributes and operations of the "SIP Servlet Container" MBean, click the name=SipServletContainer,service=SipServletContainer,type=SipContainer link. The JMX Bean View page appears (Figure 9-15), displaying the attributes and operations.

   Figure 9-15 Viewing Attributes and Operations

   Description of "Figure 9-15 Viewing Attributes and Operations"