Skip Headers

Oracle® Communication and Mobility Server Administrator's Guide 10g Release 3 (10.1.3) Part Number E12656-01 |
Home | Contents | Index | Contact Us

Previous | Next
| View PDF

# 3 Configuring the SIP Server MBeans

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

- "Overview of SIP Server Management"

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

- "Managing OCMS MBeans"

- "Setting and Viewing the SIP Port"

## Overview of SIP Server Management

The OCMS SIP Server is an OC4J container that you manage using the Oracle 10g Enterprise Manager Application Server Control console (Figure 3-1).

Figure 3-1 The Oracle 10g Enterprise Manager Application Server Control

Description of "Figure 3-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 Server Control enables you to stop and restart the OCMS SIP Server. Like other OC4J containers, the OCMS SIP Server can be stopped and restarted using the Stop and Restart buttons on the Home page (Figure 3-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.

If you have installed OCMS in standalone mode, you can invoke the start and stop scripts available under ORACLE_HOME/sdp/bin from the command line:

    startocms

or

    stopocms

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 3-2) control the running status for selected SIP servlet applications.

Figure 3-2 The Applications Page of the Application Server Control

Description of "Figure 3-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 persist when updated.

## Managing OCMS MBeans

The Application Server Control Console's MBeans browser (Figure 3-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 3-3 Viewing MBeans

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

You access the MBeans related to the JSR 116-compliant OCMS SIP Servlet Container through the System MBean Browser. For more information, see "Managing OCMS MBeans".

To display the available System MBeans, the MBean Browser accesses the MBean Server that runs in OC4J.

Figure 3-4 Viewing System MBeans

Description of "Figure 3-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 3-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 3-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 view. 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 3-5 The JMX Section of the Task List

   Description of "Figure 3-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 view displays the MBeans registered to the application. Selecting an MBean in this tree control lets you view its attributes, operations, statistics, and notifications.

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 3-1):

Table 3-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 proxy that receives client requests. Setting the default applications for incoming requests. | SIP Servlet Container
Setting the log levels for the logger components (CUSTOMER, BADMSG, TRAFFIC, CONFIG, TIMER, STATISTICS, FORMAT, and APPLICATION). For more information, see Chapter 12, "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
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 3-2). For more information on setting the values for these attributes during installation, refer to Oracle Communication and Mobility Server Installation Guide.

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

- Via

Table 3-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 | A comma-separated list with the DNS that the container shall try to resolve against. Enter as a SipURI, that is, sip:host:port;transport=tcp, where host is the only required part. For example, '127.0.0.1:53;transport=udp'. Port and transport defaults to 53 and UDP. An empty string enables the synchronous OS based resolver (no NAPTR or SRV support) which considers the local hosts file. This mode is intended for demonstration or development systems. For details about how DNS resolution takes place, see "RFC 3263: Session Initiation Protocol (SIP): Locating SIP Servers". Because DNS resolution is performed within the context of SIP message processing, any DNS performance problems result in increased latency. It is recommended to use a caching DNS server in a production environment to minimize potential performance problems. You must specify a DNS in production environments.
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.
NeedClientAuth | Setting this attribute to true enables mutual TLS, where the SIP servlet container not only provides a server certificate during the TLS handshake, but also requires a client certificate. The default value, false, enables the SIP servlet container to act as a TLS server by providing a server certificate during the TLS handshake with the client. This function is only available if useTLS is set to true. Setting this parameter to true will not work with most SIP clients, as they cannot provide a client certificate. Although most SIP client applications cannot provide certificates, other clients, such as proxy servers can.
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.
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.
TlsKeyStore | The file path to a keystore of Sun's JKS type.
TlsKeyStorePassword | A password or a password indirection. For example, '->jazn.com/oc4jadmin' which means that the password for the JAZN user 'oc4jadmin' in the realm 'jazn.com' is used to unlock the store. A JAZN user is created by invoking the jazn.jar in OC4J.
TlsTrustStore | A file path to a truststore of Sun's JKS type.
TlsTrustStorePassword | A password or a password indirection. For example, '->jazn.com/oc4jadmin' which means that the password for the JAZN user 'oc4jadmin' in the realm 'jazn.com' is used to unlock the store. A JAZN user is created by invoking the jazn.jar in OC4J.
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.
UseTLS | Select true to enable the SIP servlet container to provide server certificates during a TLS handshake with a client. If set to true, the SIP Servlet container listens to the TLS port. You must also configure the TlsKeystore, TlsKeyStorePassword, TlsTrustStore, and TlsTrustStorePassword attributes.
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 13, "Deploying Applications", The SIP application is usually built as an Enterprise Archive (EAR) that is deployed to OC4J. Once the SIP application has been deployed, the application server parses the `sip.xml` and instantiates the servlets and listeners. The application server also creates a name for the deployed application by piecing together the components of the EAR file. Because this generated name can be lengthy, you can create an alias for the application. You can use this shorter, more intuitive application name when you configure the default application. This short name can be used in the URI parameter of the route header or the request-URI.

For example, the name of a presence application deployed to the server might appear as presenceapplicationear-4.0.0-dev/eventnotificationssr-4.0.0-dev. Using the ApplicationAliases attribute, you can set a short name for this application by entering key-value pair such as presence=presenceapplicationear-4.0.0-dev/eventnotificationssr-4.0.0-dev. The key is the alias (presence) and the value is the real name of the application. This alias can be used for the real name of the application.

Note:

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

##### Using TLS

The useTLS attribute, when set to true, enables the SIP servlet container to act as a TLS server by providing a server certificate during the TLS handshake. You must also configure the TlsKeystore, TlsKeyStorePassword, TlsTrustStore, and TlsTrustStorePassword attributes. In addition to providing the server certificate, the needClientAuth attribute enables the SIP servlet container to perform mutual TLS by requiring a client certificate during the TLS handshake.

#### Setting the Keystore

A keystore is a database of public and private keys that can be grouped into two categories: key entries and trusted certificate entries. The SIP Servlet container works with keystores of Sun's JKS type (PKCS12 is not supported). A keystore of the JKS type may contain both key entries and trusted certificate entries. Using two different files instead of one single keystore file provides for a cleaner separation between the SIP Servlet container's certificates and certificates from other entities (which is also supported by the SIP Servlet container).

Note:

Multiple private key entries in the keystore are not supported; the SIP Servlet container supports one certificate for each domain. There is no mechanism to feed the container with a password for a keystore entry.

#### Enabling TLS

To enable TLS, you must set the following java system properties: `useTLS`, and, optionally, `needClientAuth`. You must also configure the TlsKeystore, TlsKeyStorePassword, TlsTrustStore, and TlsTrustStorePassword attributes.

Setting the `useTLS` attribute means that the container will listen to the configured TLS port and provide the server certificate during the TLS handshake.

If you set the `needClientAuth` attribute, the server will as usual provide it's server certificate but will also require a certificate from the client. This is a setting that will not work with Oracle Communicator (and other SIP clients) as SIP clients typically cannot provide a client certificate. In an environment where the client is a proxy server this setting can be used.

#### SIP Servlet Container Logging

For information on the logging system and configuring log levels, see Chapter 12, "Configuring the Logging System".

#### 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 3-4) 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 3-4 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.

### Configuring SIP Applications

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

- Subscriber Data Services

- Presence (See "Configuring Presence and Presence Web Services")

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

  Table 3-5 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 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 3-6 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 Oracle 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 3-6). These commands match those retrieved by entering `help account` at the Sash prompt. For more information, see "Viewing Subcommands" in Chapter 11, "Provisioning Users with Sash".

   Figure 3-6 Viewing Help for a Command

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

To view a list of all of the available commands (Figure 3-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 3-7 Viewing Available Commands

Description of "Figure 3-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 3-7 describes the attributes of the Proxy Registrar.

Table 3-7 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 MaxExpires, 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 3-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 3-8 Setting the Application Routing for an INVITE Request

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

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

Table 3-8 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. You must configure the following Application Router attributes for the incremental mode: RecordRoute RouteLoaderUri SIPUriList 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. You must configure the following Application Router attributes for the standard mode: RecordRoute RouteLoaderUri SipUriList
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. In general, you set the value as the URI of the Proxy Registrar because the SIP servlet container recognizes the URI of the Proxy Registrar as its own.
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 Deploying SIP Applications]] For more information on the `appID` parameter, refer to Oracle Communication and Mobility Server Developer's Guide.

### Setting and Viewing the SIP Port

The SIP port is set in the opmn.xml file rather than through Enterprise Manager. You should specify a specific port number, such as 5060, rather than a range of ports.

You can view what SIP port you have set in the opmn.xml from the "Server Properties" page in Enterprise Manager. Do not change the SIP port through this page. If you attempt to change it the "protocol" part in the opmn.xml file will be modified from "sip" to "ajp" and the SIP container will start on the default port, 5060.