A SIP Servlet Container Configuration Reference

The following sections provide a complete reference to the engine tier configuration file, sipserver.xml:

Section A.1, "Overview of sipserver.xml"
Section A.2, "Editing sipserver.xml"
Section A.3, "XML Schema"
Section A.4, "Example sipserver.xml File"
Section A.5, "XML Element Description"

A.1 Overview of sipserver.xml

The sipserver.xml file is an XML document that configures the SIP container features provided by an Oracle WebLogic Server SIP Container instance in the engine tier of a server installation. sipserver.xml is stored in the DOMAIN_DIR/config/custom subdirectory where DOMAIN_DIR is the root directory of the Oracle WebLogic Server SIP Container domain.

A.2 Editing sipserver.xml

You should never move, modify, or delete the sipserver.xml file during normal operations.

Oracle recommends using the Administration Console to modify sipserver.xml indirectly, rather than editing the file by hand. Using the Administration Console ensures that the sipserver.xml document always contains valid XML. See also Configuring Container Properties Using WLST (JMX) in the Configuration Guide.

You may need to manually view or edit sipserver.xml to troubleshoot problem configurations, repair corrupted files, or to roll out custom configurations to a large number of machines when installing or upgrading Oracle WebLogic Server SIP Container. When you manually edit sipserver.xml, you must reboot Oracle WebLogic Server SIP Container instances to apply your changes.

Caution:

Always use the SipServer node in the Administration Console or the WLST utility to make changes to a running Oracle WebLogic Server SIP Container deployment.

A.2.1 Steps for Editing sipserver.xml

If you need to modify sipserver.xml on a production system, follow these steps:

Use a text editor to open the DOMAIN_DIR/config/custom/sipserver.xml file, where DOMAIN_DIR is the root directory of the Oracle WebLogic Server SIP Container domain.
Modify the sipserver.xml file as necessary. See Section A.3, "XML Schema" for a full description of the XML elements.
Save your changes and exit the text editor.
Reboot or start servers to have your changes take effect:

Caution:
Always use the SipServer node in the Administration Console or the WLST utility to make changes to a running Oracle WebLogic Server SIP Container deployment.
Test the updated system to validate the configuration.

A.3 XML Schema

The schema file for sipserver.xml, wcp-sipserver.xsd, is installed inside the wlss-descriptor-binding.jar library, located in the WLSS_HOME/server/lib/wlss directory.

A.4 Example sipserver.xml File

The following shows a simple example of a sipserver.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<sip-server xmlns="http://www.bea.com/ns/wlcp/wlss/300">
  <overload>
    <threshold-policy>queue-length</threshold-policy>
    <threshold-value>200</threshold-value>
    <release-value>150</release-value>
  </overload>
</sip-server>

A.5 XML Element Description

The following sections describe each element used in the sipserver.xml configuration file. Each section describes an XML element that is contained within the main sip-server element shown in Figure A-0.

A.5.1 enable-timer-affinity

The enable-timer-affinity element determines the way in which engine tier servers process expired timers. By default (when enable-timer-affinity is omitted from sipserver.xml, or is set to "false"), an engine tier server that polls the SIP data tier for expired timers processes all available expired timers. When enable-timer-affinity is set to "true," engine tier servers polling the SIP data tier process only those expired timers that are associated with call states that the engine last modified (or expired timers for call states that have no owner).

A.5.2 overload

The overload element enables you to throttle incoming SIP requests according to a configured overload condition. When an overload condition occurs, Oracle WebLogic Server SIP Container destroys new SIP requests by responding with "503 Service Unavailable" until the configured release value is observed, or until the size of the server's capacity constraints is reduced (see Section A.5.2.3, "Overload Control Based on Capacity Constraints").

User-configured overload controls are applied only to initial SIP requests; SIP dialogues that are already active when an overload condition occurs may generate additional SIP requests that are not throttled.

To configure an overload control, you define the three elements described in Table A-1.

Table A-1 Nested overload Elements

Element Description

Element	Description
threshold-policy	A String value that identifies the type of measurement used to monitor overload conditions: `session-rate` measures the rate at which new SIP requests are generated. Oracle WebLogic Server SIP Container determines the session rate by calculating the number of new SIP application connections that were created in the last 5 seconds of operation. See Section A.5.2.2, "Overload Control Based on Session Generation Rate". `queue-length` measures the sum of the sizes of the capacity constraint work manager components that processes SIP requests and SIP timers. See Section A.5.2.3, "Overload Control Based on Capacity Constraints". Note: Execute queues are deprecated and no longer used in `Oracle WebLogic Server SIP Container. Capacity constraints are used in place of execute queues. The policy name "queue-length`" was kept for backward compatibility. You must use only one of the above policies to define an overload control. See Section A.5.2.1, "Selecting an Appropriate Overload Policy" for more information.
threshold-value	Specifies the measured value that causes Oracle WebLogic Server SIP Container to recognize an overload condition and start throttling new SIP requests: When using the `session-rate` threshold policy, `threshold-value` specifies the number of new SIP requests per second that trigger an overload condition. See Section A.5.2.2, "Overload Control Based on Session Generation Rate". When using the `queue-length` threshold policy, `threshold-value` specifies the size of the combined number of requests in the SIP transport and SIP timer capacity constraint components that triggers an overload condition. See Section A.5.2.3, "Overload Control Based on Capacity Constraints". After the `threshold-value` is observed, Oracle WebLogic Server SIP Container recognizes an overload condition for a minimum of 512 milliseconds during which time new SIP requests are throttled. If multiple overloads occur over a short period of time, the minimum overload of 512 ms is dynamically increased to avoid repeated overloads. After the minimum overload recognition period expires, the overload condition is terminated only after the configured `release-value` is observed.
release-value	Specifies the measured value that causes Oracle WebLogic Server SIP Container to end an overload condition and stop throttling new SIP requests: When using the `session-rate` threshold policy, `release-value` specifies the number of new SIP requests per second that terminates session throttling. See Section A.5.2.2, "Overload Control Based on Session Generation Rate". When using the `queue-length` threshold policy, `release-value` specifies the combined number of requests in the capacity constraints that terminates session throttling. See Section A.5.2.3, "Overload Control Based on Capacity Constraints".

threshold-policy

A String value that identifies the type of measurement used to monitor overload conditions:

session-rate measures the rate at which new SIP requests are generated. Oracle WebLogic Server SIP Container determines the session rate by calculating the number of new SIP application connections that were created in the last 5 seconds of operation. See Section A.5.2.2, "Overload Control Based on Session Generation Rate".
queue-length measures the sum of the sizes of the capacity constraint work manager components that processes SIP requests and SIP timers. See Section A.5.2.3, "Overload Control Based on Capacity Constraints".
Note: Execute queues are deprecated and no longer used in Oracle WebLogic Server SIP Container. Capacity constraints are used in place of execute queues. The policy name "queue-length" was kept for backward compatibility.

You must use only one of the above policies to define an overload control. See Section A.5.2.1, "Selecting an Appropriate Overload Policy" for more information.

threshold-value

Specifies the measured value that causes Oracle WebLogic Server SIP Container to recognize an overload condition and start throttling new SIP requests:

When using the session-rate threshold policy, threshold-value specifies the number of new SIP requests per second that trigger an overload condition. See Section A.5.2.2, "Overload Control Based on Session Generation Rate".
When using the queue-length threshold policy, threshold-value specifies the size of the combined number of requests in the SIP transport and SIP timer capacity constraint components that triggers an overload condition. See Section A.5.2.3, "Overload Control Based on Capacity Constraints".
After the threshold-value is observed, Oracle WebLogic Server SIP Container recognizes an overload condition for a minimum of 512 milliseconds during which time new SIP requests are throttled. If multiple overloads occur over a short period of time, the minimum overload of 512 ms is dynamically increased to avoid repeated overloads.
After the minimum overload recognition period expires, the overload condition is terminated only after the configured release-value is observed.

release-value

Specifies the measured value that causes Oracle WebLogic Server SIP Container to end an overload condition and stop throttling new SIP requests:

When using the session-rate threshold policy, release-value specifies the number of new SIP requests per second that terminates session throttling. See Section A.5.2.2, "Overload Control Based on Session Generation Rate".
When using the queue-length threshold policy, release-value specifies the combined number of requests in the capacity constraints that terminates session throttling. See Section A.5.2.3, "Overload Control Based on Capacity Constraints".

A.5.2.1 Selecting an Appropriate Overload Policy

Oracle WebLogic Server SIP Container provides two different policies for throttling SIP requests:

The session-rate policy throttles sessions when the volume new SIP sessions reaches a configured rate (a specified number of sessions per second).
The queue-length policy throttles requests after the sum of the requests in the wlss.connect work manager and wlss.timer.capacity capacity constraint components reaches a configured size.

Note that you must select only one of the available overload policies. You cannot use both policies simultaneously.

The session-rate policy is generally used when a back-end resource having a known maximum throughput (for example, an RDBMS) is used to set up SIP calls. In this case, the session-rate policy enables you to tie the Oracle WebLogic Server SIP Container overload policy to the known throughput capabilities of the back-end resource.

With the queue-length policy, Oracle WebLogic Server SIP Container monitors both CPU and I/O bottlenecks to diagnose an overload condition. The queue-length policy is generally used with CPU-intensive SIP applications in systems that have no predictable upper bound associated with the call rate.

The following sections describe each policy in detail.

A.5.2.2 Overload Control Based on Session Generation Rate

Oracle WebLogic Server SIP Container calculates the session generation rate (sessions per second) by monitoring the number of application sessions created in the last 5 seconds. When the session generation rate exceeds the rate specified in the threshold-value element, Oracle WebLogic Server SIP Container throttles initial SIP requests until the session generation rate becomes smaller than the configured release-value.

The following example configures Oracle WebLogic Server SIP Container to begin throttling SIP requests when the new sessions are created at a rate higher than 50 sessions per second. Throttling is discontinued when the session rate drops to 40 sessions per second:

<overload>
  <threshold-policy>session-rate</threshold-policy>
  <threshold-value>50</threshold-value>
  <release-value>40</release-value>
</overload>

A.5.2.3 Overload Control Based on Capacity Constraints

By default, SIP messages are handled by a work manager named wlss.connect and SIP timers are processed by a work manager named wlss.timer.Each work manager has an associated capacity constraint component that sets the number of requests allotted for SIP message handling and timer processing. Work managers are configured in the config.xml file for your Oracle WebLogic Server SIP Container. You can also allocate additional threads to the server at boot time using the startup option -Dweblogic.threadpool.MinPoolSize=number_of_threads.

Oracle WebLogic Server SIP Container performs queue-length overload control by monitoring the combined lengths of the configured capacity constraints. When the sum of the requests in the two constraints exceeds the length specified in the threshold-value element, Oracle WebLogic Server SIP Container throttles initial SIP requests until the total requests are reduced to the configured release-value.

Example A-1 shows a sample overload configuration from sipserver.xml. Here, Oracle WebLogic Server SIP Container begins throttling SIP requests when the combined size of the constraints exceeds 200 requests. Throttling is discontinued when the combined length returns to 200 or fewer simultaneous requests.

Example A-1 Sample overload Definition

<overload>
  <threshold-policy>queue-length</threshold-policy>
  <threshold-value>200</threshold-value>
  <release-value>150</release-value>
</overload>

A.5.2.4 Two Levels of Overload Protection

User-configured overload controls (defined in sipserver.xml) represent the first level of overload protection provided by Oracle WebLogic Server SIP Container. They mark the onset of an overload condition and initiate simple measures to avoid dropped calls (generating 503 responses for new requests).

If the condition that caused the overload persists or worsens, then the work manager component used to perform work in the SIP Servlet container may itself become overloaded. At this point, the server no longer utilizes threads to generate 503 responses, but instead begins to drop messages. In this way, the configured size of the SIP container's work manager components represent the second and final level of overload protection employed by the server.

Always configure overload controls in sipserver.xml conservatively, and resolve the circumstances that caused the overload in a timely fashion.

A.5.3 message-debug

The message-debug element is used to enable and configure access logging with log rotation for Oracle WebLogic Server SIP Container. This element should be used only in a development environment, because access logging logs all SIP requests and responses.

A.5.4 proxy—Setting Up an Outbound Proxy Server

RFC 3261 defines an outbound proxy as "A proxy that receives requests from a client, even though it may not be the server resolved by the Request-URI. Typically, a UA is manually configured with an outbound proxy, or can learn about one through auto-configuration protocols."

In Oracle WebLogic Server SIP Container an outbound proxy server is specified using the proxy element in sipserver.xml. The proxy element defines one or more proxy server URIs. You can change the behavior of the proxy process by setting a proxy policy with the proxy-policy tag. Example A-0 describes the possible values for the proxy elements.

The default behavior is as if proxy policy is in effect. The proxy policy means that the request is sent out to the configured outbound proxy and the route headers in the request preserve any routing decision taken by Oracle WebLogic Server SIP Container. This enables the outbound proxy to send the request over to the intended recipient after it has performed its actions on the request. The proxy policy comes into effect only for the initial requests. As for the subsequent request the Route Set takes precedence over any policy in a dialog. (If the outbound proxy wants to be in the Route Set it can turn record routing on).

Also if a proxy application written on Oracle WebLogic Server SIP Container wishes to override the configured behavior of outbound proxy traversal, then it can add a special header with name "X-BEA-Proxy-Policy" and value "domain". This header is stripped from the request while sending, but the effect is to ignore the configured outbound proxy. The X-BEA-Proxy-Policy custom header can be used by applications to override the configured policy on a request-by-request basis. The value of the header can be "domain" or "proxy". Note, however, that if the policy is overridden to "proxy," the configuration must still have the outbound proxy URIs in order to route to the outbound proxy.

Table A-2 Nested proxy Elements

Element Description

Element	Description
routing-policy	An optional element that configures the behavior of the proxy. Valid values are: domain - Proxies messages using the routing rule defined by RFC 3261, ignoring any outbound proxy that is specified. proxy - Sends the message to the downstream proxy specified in the default proxy URI. If there are multiple proxy specifications they are tried in the order in which they are specified. However, if the transport tries a UDP proxy, the settings for subsequent proxies are ignored.
uri	The TCP or UDP URI of the proxy server. You must specify at least one URI for a `proxy` element. Place multiple URIs in multiple `uri` elements within the `proxy` element.

routing-policy

An optional element that configures the behavior of the proxy. Valid values are:

domain - Proxies messages using the routing rule defined by RFC 3261, ignoring any outbound proxy that is specified.
proxy - Sends the message to the downstream proxy specified in the default proxy URI. If there are multiple proxy specifications they are tried in the order in which they are specified. However, if the transport tries a UDP proxy, the settings for subsequent proxies are ignored.

uri

The TCP or UDP URI of the proxy server. You must specify at least one URI for a proxy element. Place multiple URIs in multiple uri elements within the proxy element.

Example A-2 shows the default proxy configuration for Oracle WebLogic Server SIP Container domains. The request in this case is created in accordance with the SIP routing rules, and finally the request is sent to the outbound proxy "sipoutbound.oracle.com".

Example A-2 Sample proxy Definition

<proxy>
     <routing-policy>proxy</routing-policy>
     <uri>sip:sipoutbound.oracle.com:5060</uri>
     <!-- Other proxy uri tags can be added. - > 
</proxy>

A.5.5 t1-timeout-interval

This element sets the value of the SIP protocol T1 timer, in milliseconds. Timer T1 also specifies the initial values of Timers A, E, and G, which control the retransmit interval for INVITE requests and responses over UDP.

Timer T1 also affects the values of timers F, H, and J, which control retransmit intervals for INVITE responses and requests; these timers are set to a value of 64*T1 milliseconds. See the SIP: Session Initiation Protocol for more information about SIP timers.

If t1-timeout-interval is not configured, Oracle WebLogic Server SIP Container uses the SIP protocol default value of 500 milliseconds.

A.5.6 t2-timeout-interval

This elements sets the value of the SIP protocol T2 timer, in milliseconds. Timer T2 defines the retransmit interval for INVITE responses and non-INVITE requests. See the SIP: Session Initiation Protocol for more information about SIP timers.

If t2-timeout-interval is not configured, Oracle WebLogic Server SIP Container uses the SIP protocol default value of 4 seconds.

A.5.7 t4-timeout-interval

This elements sets the value of the SIP protocol T4 timer, in milliseconds. Timer T4 specifies the maximum length of time that a message remains in the network. Timer T4 also specifies the initial values of Timers I and K, which control the wait times for retransmitting ACKs and responses over UDP.

If t4-timeout-interval is not configured, Oracle WebLogic Server SIP Container uses the SIP protocol default value of 5 seconds.

A.5.8 timer-b-timeout-interval

This elements sets the value of the SIP protocol Timer B, in milliseconds. Timer B specifies the length of time a client transaction attempts to retry sending a request.

If timer-b-timeout-interval is not configured, the Timer B value is derived from timer T1 (64*T1, or 32000 milliseconds by default).

A.5.9 timer-f-timeout-interval

This elements sets the value of the SIP protocol Timer F, in milliseconds. Timer F specifies the timeout interval for retransmitting non-INVITE requests.

If timer-f-timeout-interval is not configured, the Timer F value is derived from timer T1 (64*T1, or 32000 milliseconds by default).

A.5.10 max-application-session-lifetime

This element sets the maximum amount of time, in minutes, that a SIP application session can exist before Oracle WebLogic Server SIP Container invalidates the session. max-application-session-lifetime acts as an upper bound for any timeout value specified using the session-timeout element in a sip.xml file, or using the setExpires API.

A value of -1 (the default) specifies that there is no upper bound to application-configured timeout values.

A.5.11 enable-local-dispatch

enable-local-dispatch is a server optimization that helps avoid unnecessary network traffic when sending and forwarding messages. You enable the optimization by setting this element "true." When enable-local-dispatch enabled, if a server instance needs to send or forward a message and the message destination is the engine tier's cluster address or the local server address, then the message is routed internally to the local server instead of being sent via the network. Using this optimization can dramatically improve performance when chained applications process the same request.

You may want to disable this optimization if you feel that routing internal messages could skew the load on servers in the engine tier, and you prefer to route all requests via a configured load balancer.

By default enable-local-dispatch is set to "false."

A.5.12 cluster-loadbalancer-map

The cluster-loadbalancer-map element is used only when upgrading Oracle WebLogic Server SIP Container software, or when upgrading a production SIP Servlet to a new version. It is not required or used during normal server operations.

During a software upgrade, multiple engine tier clusters are defined to host the older and newer software versions. A cluster-loadbalancer-map defines the virtual IP address (defined on your load balancer) that correspond to an engine tier cluster configured for an upgrade. Oracle WebLogic Server SIP Container uses this mapping to ensure that engine tier requests for timers and call state data are received from the correct "version" of the cluster. If a request comes from an incorrect version of the software, the cluster-loadbalancer-map entries are used to forward the request to the correct cluster.

Each cluster-loadbalancer-map entry contains the two elements described in Table A-1.

Table A-3 Nested cluster-loadbalancer-map Elements

Element	Description
cluster-name	The configured name of an engine tier cluster.
sip-uri	The internal SIP URI that maps to the engine tier cluster. This corresponds to a virtual IP address that you have configured in your load balancer. The internal URI is used to forward requests to the correct cluster version during an upgrade.

Example A-3 shows a sample cluster-loadbalancer-map entry used during an upgrade.

Example A-3 Sample cluster-loadbalancer-map Entry

<cluster-loadbalancer-map>
   <cluster-name>EngineCluster</cluster-name>
   <sip-uri>sip:172.17.0.1:5060</sip-uri>
</cluster-loadbalancer-map>
<cluster-loadbalancer-map>
   <cluster-name>EngineCluster2</cluster-name>
   <sip-uri>sip:172.17.0.2:5060</sip-uri>
</cluster-loadbalancer-map>

See Upgrading Software in the Operations Guide for more information.

A.5.13 default-behavior

This element defines the default behavior of the Oracle WebLogic Server SIP Container instance if the server cannot match an incoming SIP request to a deployed SIP Servlet (or if the matching application has been invalidated or timed out). Valid values are:

proxy—Act as a proxy server.
ua—Act as a User Agent.

proxy is used as the default if you do not specify a value.

When acting as a User Agent (UA), Oracle WebLogic Server SIP Container acts in the following way in response to SIP requests:

ACK requests are discarded without notice.
CANCEL or BYE requests receive response code 481 - Transaction does not exist.
All other requests receive response code 500 - Internal server error.

When acting as a proxy requests are automatically forwarded to an outbound proxy (see Section A.5.4, "proxy—Setting Up an Outbound Proxy Server") if one is configured. If no proxy is defined, Oracle WebLogic Server SIP Container proxies to a specified Request URI only if the Request URI does not match the IP and port number of a known local address for a SIP Servlet container, or a load balancer address configured for the server. This ensures that the request does not constantly loop to the same servers. When the Request URI matches a local container address or load balancer address, Oracle WebLogic Server SIP Container instead acts as a UA.

A.5.14 default-servlet-name

This element specifies the name of a default SIP Servlet to call if an incoming initial request cannot be matched to a deployed Servlet (using standard servlet-mapping definitions in sip.xml). The name specified in the default-servlet-name element must match the servlet-name value of a deployed SIP Servlet. For example:

<default-servlet-name>myServlet</default-servlet-name>

If the name defined in default-servlet-name does not match a deployed Servlet, or no value is supplied (the default configuration), Oracle WebLogic Server SIP Container registers the name com.bea.wcp.sip.engine.BlankServlet as the default Servlet. The BlankServlet name is also used if a deployed Servlet registered as the default-servlet-name is undeployed from the container.

BlankServlet's behavior is configured with the default-behavior element. By default the Servlet proxies all unmatched requests. However, if the default-behavior element is set to "ua" mode, BlankServlet is responsible for returning 481 responses for CANCEL and BYE requests, and 500/416 responses in all other cases. BlankServlet does not respond to ACK, and it always invalidates the application session.

A.5.15 retry-after-value

Specifies the number of seconds used in the Retry-After header for 5xx responses. This value can also include a parameter or a reason code, such as "Retry-After: 18000;duration=3600" or "Retry-After: 120 (I'm in a meeting)."

If the this value is not configured, Oracle WebLogic Server SIP Container uses the default value of 180 seconds.

A.5.16 sip-security

Oracle WebLogic Server SIP Container enables you to configure one or more trusted hosts for which authentication is not performed. When Oracle WebLogic Server SIP Container receives a SIP message, it calls getRemoteAddress() on the SIP Servlet message. If this address matches an address defined in the server's trusted host list, no further authentication is performed for the message.

The sip-security element defines one or more trusted hosts, for which authentication is not performed. The sip-security element contains one or more trusted-authentication-host or trusted-charging-host elements, each of which contains a trusted host definition. A trusted host definition can consist of an IP address (with or without wildcard placeholders) or a DNS name. Example A-4 shows a sample sip-security configuration.

Example A-4 Sample Trusted Host Configuration

<sip-security>
   <trusted-authentication-host>myhost1.mycompany.com</trusted-authentication-host>
   <trusted-authentication-host>172.*</trusted-authentication-host>
</sip-security>

A.5.17 route-header

3GPP TS 24.229 Version 7.0.0 (http://www.3gpp.org/ftp/Specs/archive/24_series/24.229/24229-700.zip) requires that IMS Application Servers generating new requests (for example, as a B2BUA) include the S-CSCF route header. In Oracle WebLogic Server SIP Container, the S-CSCF route header must be statically defined as the value of the route-header element in sipserver.xml. For example:

<route-header>
   <uri>Route: sip:wlss1.bea.com</uri>
</route-header>

A.5.18 engine-call-state-cache-enabled

Oracle WebLogic Server SIP Container provides the option for engine tier servers to cache a portion of the call state data locally, as well as in the SIP data tier, to improve performance with SIP-aware load balancers. When a local cache is used, an engine tier server first checks its local cache for existing call state data. If the cache contains the required data, and the local copy of the data is up-to-date (compared to the SIP data tier copy), the engine locks the call state in the SIP data tier but reads directly from its cache.

By default the engine tier cache is enabled. To disable caching, set engine-call-state-cache-enabled to false:

<engine-call-state-cache-enabled>false</engine-call-state-cache-enabled>

A.5.19 server-header

Oracle WebLogic Server SIP Container enables you to control when a Server header is inserted into SIP messages. You can use this functionality to limit or eliminate Server headers to reduce the message size for wireless networks, or to increase security.

By default, Oracle WebLogic Server SIP Container inserts no Server header into SIP messages. Set the server-header to one of the following string values to configure this behavior:

none (the default) inserts no Server header.
request inserts the Server header only for SIP requests generated by the server.
response inserts the Server header only for SIP responses generated by the server.
all inserts the Server header for all SIP requests and responses.

For example, the following element configures Oracle WebLogic Server SIP Container to insert a Server header for all generated SIP messages:

<server-header>all</server-header>

A.5.20 server-header-value

Oracle WebLogic Server SIP Container enables you to control the text that is inserted into the Server header of generated messages. This provides additional control over the size of SIP messages and also enables you to mask the server entity for security purposes. By default, Oracle WebLogic Server SIP Container does not insert a Server header into generated SIP messages (see Section A.5.19, "server-header"). If Server header insertion is enabled but no server-header-value is specified, Oracle WebLogic Server SIP Container inserts the value "WebLogic SIP Server." To configure the header contents, enter a string value. For example:

<server-header-value>MyCompany Application Server</server-header-value>

A.5.21 persistence

The persistence element defines enables or disables writing call state data to an RDBMS and/or to a remote, geographically-redundant Oracle WebLogic Server SIP Container installation. For sites that utilize geographically-redundant replication features, the persistence element also defines the site ID and the URL at which to persist call state data.

The persistence element contains the sub-elements described in Table A-1.

Table A-4 Nested persistence Elements

Element	Description
default-handling	Determines whether or not Oracle WebLogic Server SIP Container observes persistence hints for RDBMS persistence and/or geographical-redundancy. This element can have one of the following values: all—Specifies that call state data may be persisted to both an RDBMS store and to a geographically-redundant Oracle WebLogic Server SIP Container installation. This is the default behavior. Note that actual replication to either destination also requires that the available resources (JDBC datasource and remote JMS queue) are available. db—Specifies that long-lived call state data is replicated to an RDBMS if the required JDBC datasource and schema are available. geo—Specifies that call state data is persisted to a remote, geographically-redundant site if the configured site URL contains the necessary JMS resources. none—Specifies that only in-memory replication is performed to other replicas in the SIP data tier cluster. Call state data is not persisted in an RDBMS or to an external site.
geo-site-id	Specifies the site ID of this installation. All installations that participate in geographically-redundant replication require a unique site ID.
geo-remote-t3-url	Specifies the remote Oracle WebLogic Server SIP Container installation to which this site replicates call state data. You can specify a single URL corresponding to the engine tier cluster of the remote installation. You can also specify a comma-separated list of addresses corresponding to each engine tier server. The URLs must specify the t3 protocol.

Element

Description

default-handling

Determines whether or not Oracle WebLogic Server SIP Container observes persistence hints for RDBMS persistence and/or geographical-redundancy. This element can have one of the following values:

all—Specifies that call state data may be persisted to both an RDBMS store and to a geographically-redundant Oracle WebLogic Server SIP Container installation. This is the default behavior. Note that actual replication to either destination also requires that the available resources (JDBC datasource and remote JMS queue) are available.
db—Specifies that long-lived call state data is replicated to an RDBMS if the required JDBC datasource and schema are available.
geo—Specifies that call state data is persisted to a remote, geographically-redundant site if the configured site URL contains the necessary JMS resources.
none—Specifies that only in-memory replication is performed to other replicas in the SIP data tier cluster. Call state data is not persisted in an RDBMS or to an external site.

geo-site-id

Specifies the site ID of this installation. All installations that participate in geographically-redundant replication require a unique site ID.

geo-remote-t3-url

Specifies the remote Oracle WebLogic Server SIP Container installation to which this site replicates call state data. You can specify a single URL corresponding to the engine tier cluster of the remote installation. You can also specify a comma-separated list of addresses corresponding to each engine tier server. The URLs must specify the t3 protocol.

Example A-5 shows a sample configuration that uses RDBMS storage for long-lived call state as well as geographically-redundant replication. Call states are replicated to two engine tier servers in a remote location.

Example A-5 Sample persistence Configuration

<persistence>
  <default-handling>all</default-handling>
  <geo-site-id>1</geo-site-id>
  <geo-remote-t3-url>t3://remoteEngine1:7050,t3://remoteEngine2:7051</geo-remote-t3-url>
</persistence>

A.5.22 use-header-form

This element configures the server-wide, default behavior for using or preserving compact headers in SIP messages. You can set this element to one of the following values:

compact—Oracle WebLogic Server SIP Container uses the compact form for all system-generated headers. However, any headers that are copied from an originating message (rather than generated) use their original form.
force compact—Oracle WebLogic Server SIP Container uses the compact form for all headers, converting long headers in existing messages into compact headers as necessary.
long—Oracle WebLogic Server SIP Container uses the long form for all system-generated headers. However, any headers that are copied from an originating message (rather than generated) use their original form.
force long—Oracle WebLogic Server SIP Container uses the long form for all headers, converting compact headers in existing messages into long headers as necessary.

A.5.23 enable-dns-srv-lookup

This element enables or disables Oracle WebLogic Server SIP Container DNS lookup capabilities. If you set the element to "true," then the server can use DNS to:

Discover a proxy server's transport, IP address, and port number when a request is sent to a SIP URI.
Resolve an IP address and/or port number during response routing, depending on the contents of the Sent-by field.

For proxy discovery, Oracle WebLogic Server SIP Container uses DNS resolution only once per SIP transaction to determine transport, IP, and port number information. All retransmissions, ACKs, or CANCEL requests are delivered to the same address and port using the same transport. For details about how DNS resolution takes place, see RFC 3263: Session Initiation Protocol (SIP): Locating SIP Servers (http://www.ietf.org/rfc/rfc3263.txt).

When a proxy needs to send a response message, Oracle WebLogic Server SIP Container uses DNS lookup to determine the IP address and/or port number of the destination, depending on the information provided in the sent-by field and via header.

By default, DNS resolution is not used ("false").

Note:

Because DNS resolution is performed within the context of SIP message processing, any DNS performance problems result in increased latency performance. Oracle recommends using a caching DNS server in a production environment to minimize potential performance problems.

A.5.24 connection-reuse-pool

Oracle WebLogic Server SIP Container includes a connection pooling mechanism that can be used to minimize communication overhead with a Session Border Control (SBC) function or Serving Call Session Control Function (S-CSCF). You can configure multiple, fixed pools of connections to different addresses.

Oracle WebLogic Server SIP Container opens new connections from the connection pool on demand as the server makes requests to a configured address. The server then multiplexes new SIP requests to the address using the already-opened connections, rather than repeatedly terminating and recreating new connections. Opened connections are re-used in a round-robin fashion. Opened connections remain open until they are explicitly closed by the remote address.

Note that connection re-use pools are not used for incoming requests from a configured address.

To configure a connection re-use pool, you define the four nested elements described in Table A-1.

Table A-5 Nested connection-reuse-pool Elements

Element	Description
pool-name	A String value that identifies the name of this pool. All configured `pool-name` elements must be unique to the domain.
destination	Specifies the IP address or host name of the destination SBC or S-CSCF. Oracle WebLogic Server SIP Container opens or re-uses connection in this pool only when making requests to the configured address.
destination-port	Specifies the port number of the destination SBC or S-CSCF.
maximum-connections	Specifies the maximum number of opened connections to maintain in this pool.

Example A-6 shows a sample connection-reuse-pool configuration having two pools.

Example A-6 Sample connection-reuse-pool Configuration

<connection-reuse-pool>
   <pool-name>SBCPool</pool-name>
   <destination>MySBC</destination>
   <destination-port>7070</destination-port>
   <maximum-connections>10</maximum-connections>
</connection-reuse-pool>
<connection-reuse-pool>
   <pool-name>SCSFPool</pool-name>
   <destination>192.168.1.6</destination>
   <destination-port>7071</destination-port>
   <maximum-connections>10</maximum-connections>
</connection-reuse-pool>

A.5.25 globally-routable-uri

This element enables you to specify a Globally-Routable User Agent URI (GRUU) that Oracle WebLogic Server SIP Container automatically inserts into Contact and Route-Set headers when communicating with network elements. The URI specified in this element should be the GRUU for the entire Oracle WebLogic Server SIP Container cluster. (In a single-server domain, use a GRUU for the server itself.)

Note that User Agents (UAs) deployed on Oracle WebLogic Server SIP Container typically obtain GRUUs via a registration request. In this case, the application code is responsible both for requesting and subsequently handling the GRUU. To request a GRUU the UA would include the "+sip.instance" Contact header field parameter in each Contact for which GRUU is required. Upon receiving a GRUU, the UA would use the GRUU as the URI for the contact header field when generating new requests.

A.5.26 domain-alias-name

This element defines one or more domains for which Oracle WebLogic Server SIP Container is responsible. If a message has a destination domain that matches a domain specified with a domain-alias-name element, Oracle WebLogic Server SIP Container processes the message locally, rather than forwarding it.

The sipserver.xml configuration file can have multiple main-alias-name elements. Each element can specify either:

an individual, fully-qualified domain name, such as myserver.mycompany.com, or
a domain name starting with an initial wildcard character, such as *.mycompany.com, used to represent all matching domains. Note that only a single wildcard character is supported, and it must be used as the first element of the domain name.

Note:
You can also identify these domain names using the Domain Aliases field in the Configuration > General tab of the SipServer Administration Console extension.

A.5.27 enable-rport

This element determines whether or not Oracle WebLogic Server SIP Container automatically adds an rport parameter to Via headers when acting as a UAC. By default, the server does not add the rport parameter; set the element to "true" to automatically add rport to requests generated by the server.

Note:

You can also set this parameter to "true" by selecting the Symmetric Response Routing option on the Configuration > General tab of the SipServer Administration console extension.

The rport parameter is used for symmetric response routing as described in RFC 3581 (http://www.ietf.org/rfc/rfc3581.txt). When a message is received by an RFC 3581-compliant server, such as Oracle WebLogic Server SIP Container, the server responds using the remote UDP port number from which the message was received, rather than the port number specified in the Via header. This behavior is frequently used when servers reside behind gateway devices that perform Network Address Translation (NAT). The NAT devices maintain a binding between the internal and external port numbers, and all communication must be initiated via the gateway port.

Note that Oracle WebLogic Server SIP Container is compliant with RFC 3581, and will honor the rport parameter even if you set the enable-rport element to "false." The enable-rport element only specifies whether the server automatically adds rport to the requests it generates when acting as a UAC. To disable rport handling completely (disable RFC 3581 support), you must start the server with the command-line option, -Dwlss.udp.uas.rport=false.

Note:

rport support as described in RFC 3581 requires that SIP responses include the source port of the original SIP request. Because source port information is frequently treated as sensitive data, Oracle recommends using the TLS transport.

A.5.28 image-dump-level

This element specifies the level of detail to record in Oracle WebLogic Server SIP Container diagnostic image files. You can set this element to one of two values:

basic—Records all diagnostic data except for call state data.
full—Records all diagnostic data including call state data.

Note:
Recording call state data in the image file can be time consuming. By default, image dump files are recorded using the basic option.
You can also set this parameter using the Configuration > General tab of the SipServer Administration console extension.

A.5.29 stale-session-handling

Oracle WebLogic Server SIP Container uses encoded URIs to identify the call states and application sessions associated with a message. When an application is undeployed or upgraded to a new version, incoming requests may have encoded URIs that specify "stale" or nonexistent call or session IDs. The stale-session-handling element enables you to configure the action that Oracle WebLogic Server SIP Container takes when it encounters stale session data in a request. The following actions are possible:

drop—Drops the message without logging an error. This setting is desirable for systems that frequently upgrade applications using Oracle WebLogic Server SIP Container's in-place upgrade feature. Using the drop action ensures that messages intended for older, incompatible versions of a deployed application are dropped.
error—Responds with an error, so that a UAC might correct the problem. This is the default action. Messages having a To: tag cause a 481 Call/Transaction Does Not Exist error, while those without the tag cause a 404 Not Found error.
continue—Ignores the stale session data and continues processing the request.

Note:
When it encounters stale session data, Oracle WebLogic Server SIP Container applies the action specified by stale-session-handling before considering the value of the default-behavior element. This means that the default-behavior is performed only when you have configured stale-session-handling to perform the continue action.

A.5.30 enable-contact-provisional-response

By default Oracle WebLogic Server SIP Container does not place a Contact header in non-reliable provisional (1xx) responses that have a To header. If you deploy applications that expect the Contact header to be present in such 1xx responses, set this element to true:

<enable-contact-provisional-response>true</enable-contact-provisional-response>

Note that setting this element to true does not affect 100 Trying responses.

A.5.31 app-router

The app-router stanza contains several elements that configure SIP Servlet v1.1 application router behavior. See Section A.5.32, "use-custom-app-router", Section A.5.33, "app-router-config-data", Section A.5.34, "custom-app-router-jar-file-name", and Section A.5.35, "default-application-name".

A.5.32 use-custom-app-router

The use-custom-app-router element determines whether Oracle WebLogic Server SIP Container uses the default, built-in Application AR (AR), or a custom AR that you specify with the custom-app-router-jar-file-name element. The default value, "false," configures the server to use the default AR.

A.5.33 app-router-config-data

The app-router-config-data element defines properties to pass to the default or custom Application Router (AR) in the init method. All configuration properties must conform to the Java Properties format, and each individual property must be entered on a separate, single line without line breaks or spaces. DAR properties must conform to the detailed property format described in Appendix C of http://jcp.org/en/jsr/detail?id=289. Example A-7 shows an example configuration.

Example A-7 Sample app-router-config-data element

<?xml version='1.0' encoding='UTF-8'?>
<sip-server xmlns="http://www.bea.com/ns/wlcp/wlss/300" xmlns:sec="http://www.bea.com/ns/weblogic/90/security" xmlns:wls="http://www.bea.com/ns/weblogic/90/security/wls" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <app-router>
    <use-custom-app-router>false</use-custom-app-router>
    <app-router-config-data>INVITE:("OriginatingCallWaiting","DAR:From","ORIGINATING","","NO_ROUTE","0"),("CallForwarding","DAR:To","TERMINATING","","NO_ROUTE","1")
SUBSCRIBE:("CallForwarding","DAR:To","TERMINATING","","NO_ROUTE","1")</app-router-config-data>
    <custom-app-router-jar-file-name></custom-app-router-jar-file-name>
    <default-application-name></default-application-name>
  </app-router>
</sip-server>

You can optionally specify AR initialization properties when starting the Oracle WebLogic Server SIP Container instance by including the -Djavax.servlet.sip.ar.dar.configuration Java option. (To specify a property file, rather than a URI, include the prefix file:///) If you specify the Java startup option, the container ignores any configuration properties defined in app-router-config-data. You can modify the properties in at any time, but the properties are not passed to the AR until the server is restarted with the -Djavax.servlet.sip.ar.dar.configuration option omitted.

A.5.34 custom-app-router-jar-file-name

The custom-app-router-jar-file-name element specifies the filename of the custom Application Router (AR), packaged as a JAR file, to use. The custom AR implementation must reside in the $DOMAIN_HOME/approuter subdirectory.

A.5.35 default-application-name

The default-application-name element specifies the name of a default application that the container should call when the custom Application Router (AR) cannot find an application to process an initial request. If no default application is specified, the container returns a 500 error if the AR cannot select an application.

Note:

You must first deploy an application before specifying its name as the value of Default application name.