This chapter describes the Oracle Communications Converged Application Server engine server configuration file, sipserver.xml.
The sipserver.xml file is an XML document that configures the SIP container features provided by a Converged Application Server instance in a server installation. The sipserver.xml file is stored in the domain_home/config/custom subdirectory where domain_home is the root directory of the Converged Application Server domain.
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 manually with a text editor. Using the Administration Console ensures that the sipserver.xml document always contains valid XML.
You may need to manually view or edit sipserver.xml to troubleshoot problem configurations, repair corrupted files, or to roll out custom configurations to many systems when installing or upgrading Converged Application Server. When you manually edit sipserver.xml, you must restart Converged Application Server 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 Converged Application Server deployment. See Chapter 3, "Configuring Converged Application Server Container Properties".If you need to modify sipserver.xml on a production system, follow these steps:
Use a text editor to open the domain_home/config/custom/sipserver.xml file, where domain_home is the root directory of the Converged Application Server domain.
Modify the sipserver.xml file as necessary. See "XML Schema" for a full description of the XML elements.
Save your changes and exit the text editor.
Restart 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 Converged Application Server deployment. See Chapter 3, "Configuring Converged Application Server Container Properties" for more information.Test the updated system to validate the configuration.
The schema file for sipserver.xml (wcp-sipserver.xsd) is installed inside the wlss-descriptor-binding.jar library, located in WL_home/wlserver/sip/server/lib, where WL_home is the path to the directory where WebLogic Server is installed.
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>
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.
The enable-timer-affinity element determines the way in which engine servers process expired timers. By default (when enable-timer-affinity is omitted from sipserver.xml, or is set to false), an engine server that polls the SIP call-state store for expired timers might process all available expired timers. When enable-timer-affinity is set to true, engine servers polling the SIP call-state store 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).
See "Configuring Timer Processing" for more information.
The message-debug element enables and configures access logging with log rotation for Converged Application Server. Use this element only in a development environment, because access logging logs all SIP requests and responses.
To perform more selective logging in a production environment, see Chapter 21, "Logging SIP Requests and Responses".
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 Converged Application Server 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. Table 22-1, "Nested proxy Elements" 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 preserving any routing decision taken by Converged Application Server. This configuration 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 Converged Application Server wishes to override the configured behavior of outbound proxy traversal, then it can add a special header with name X-BEA-Proxy-Policy with the value domain. This header is stripped from the request while sending, but the effect is to ignore the configured outbound proxy. Applications use the X-BEA-Proxy-Policy custom header 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 to route to the outbound proxy.
Table 22-1 Nested proxy Elements
| Element | Description |
|---|---|
|
routing-policy |
An optional element that configures the behavior of the proxy. Valid values are:
|
|
uri |
The TCP or UDP URI of the proxy server. You must specify at least one URI for a |
Example 22-1 shows the default proxy configuration for Converged Application Server 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.
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 Session Initiation Protocol for more information about SIP timers. See also "Configuring NTP for Accurate SIP Timers" for more information.
If t1-timeout-interval is not configured, Converged Application Server uses the SIP protocol default value of 500 milliseconds.
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 Session Initiation Protocol for more information about SIP timers. See also "Configuring NTP for Accurate SIP Timers" for more information.
If t2-timeout-interval is not configured, Converged Application Server uses the SIP protocol default value of 4 seconds.
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. See the Session Initiation Protocol for more information about SIP timers. See also "Configuring NTP for Accurate SIP Timers" for more information.
If t4-timeout-interval is not configured, Converged Application Server uses the SIP protocol default value of 5 seconds.
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. See the Session Initiation Protocol for more information about SIP timers. See also "Configuring NTP for Accurate SIP Timers" for more information.
If timer-b-timeout-interval is not configured, the Timer B value is derived from timer T1 (64*T1, or 32000 milliseconds by default).
This elements sets the value of the SIP protocol Timer F, in milliseconds. Timer F specifies the timeout interval for retransmitting non-INVITE requests. See the Session Initiation Protocol for more information about SIP timers. See also "Configuring NTP for Accurate SIP Timers" for more information.
If timer-f-timeout-interval is not configured, the Timer F value is derived from timer T1 (64*T1, or 32000 milliseconds by default).
This element sets the maximum amount of time, in minutes, that a SIP application session can exist before Converged Application Server 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.
Note:
The value of max-application-session-lifetime must be equal or greater than the default session length of every deployed application.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's cluster address or the local server address, then the message is routed internally to the local server instead of being sent through the network.
You may want to disable this optimization if you feel that routing internal messages could skew the load on engine servers, and you prefer to route all requests through a configured load balancer.
By default enable-local-dispatch is set to false.
The cluster-loadbalancer-map element is used only when upgrading Converged Application Server 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 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 cluster configured for an upgrade. Converged Application Server uses this mapping to ensure that engine 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, Converged Application Server uses the cluster-loadbalancer-map to forward the request to the correct cluster.
Each cluster-loadbalancer-map entry contains the two elements described in Table 22-2.
Table 22-2 Nested cluster-loadbalancer-map Elements
| Element | Description |
|---|---|
|
cluster-name |
The configured name of an engine cluster. |
|
sip-uri |
The internal SIP URI that maps to the engine cluster. This corresponds to a virtual IP address that you have configured in your load balancer. The internal URI forwards requests to the correct cluster version during an upgrade. |
Example 22-2 shows a sample cluster-loadbalancer-map entry used during an upgrade.
Example 22-2 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 the section on upgrading production Converged Application Server software in the Converged Application Server Installation Guide for more information.
This element defines the default behavior of the Converged Application Server 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), Converged Application Server 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 "proxy—Setting Up an Outbound Proxy Server") if one is configured. If no proxy is defined, Converged Application Server 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, Converged Application Server instead acts as a UA.
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), Converged Application Server 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.
Specifies the number of seconds used in the Retry-After header for 5xx response codes. 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, Converged Application Server uses the default value of 180 seconds.
Converged Application Server enables you to configure one or more trusted hosts for which authentication is not performed. When Converged Application Server 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 22-3 shows a sample sip-security configuration.
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 Converged Application Server, 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>
Converged Application Server provides the option for engine servers to cache a portion of the call-state data locally, to improve performance with SIP-aware load balancers. When a local cache is used, an engine 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 call-state store), the engine locks the call state in the SIP call-state store but reads directly from its cache.
By default the engine 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>
See Chapter 5, "Using the Engine Cache" for more information.
Converged Application Server 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, Converged Application Server 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 Converged Application Server to insert a Server header for all generated SIP messages:
<server-header>all</server-header>
See also "server-header-value".
Converged Application Server 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, Converged Application Server does not insert a Server header into generated SIP messages (see "server-header"). If Server header insertion is enabled but no server-header-value is specified, Converged Application Server 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>
The persistence element enables or disables writing call state data to an RDBMS, or to a remote, geographically-redundant Converged Application Server installation. For sites that use 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 22-3.
Table 22-3 Nested persistence Elements
| Element | Description |
|---|---|
|
default-handling |
Determines whether Converged Application Server observes persistence hints for RDBMS persistence or geographical-redundancy. This element can have one of the following values:
|
|
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 Converged Application Server installation to which this site replicates call state data. You can specify a single URL corresponding to the engine cluster of the remote installation. You can also specify a comma-delimited list of addresses corresponding to each engine server. The URLs must specify the t3 protocol. |
Example 22-4 shows a sample configuration that uses RDBMS storage for long-lived call state and geographically-redundant replication. Call states are replicated to two engine servers in a remote location.
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: Converged Application Server 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: Converged Application Server uses the compact form for all headers, converting long headers in existing messages into compact headers as necessary.
long: Converged Application Server 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: Converged Application Server uses the long form for all headers, converting compact headers in existing messages into long headers as necessary.
This element enables or disables Converged Application Server 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 port number during response routing, depending on the contents of the Sent-by field.
For proxy discovery, Converged Application Server 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, Converged Application Server uses DNS lookup to determine the IP address and 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.Converged Application Server includes a connection pooling mechanism that minimizes 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.
Converged Application Server 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 re-creating new connections. Opened connections are reused in a round-robin fashion. Opened connections remain open until they are explicitly closed by the remote address.
Connection reuse pools are not used for incoming requests from a configured address.
To configure a connection reuse pool, you define the four nested elements described in Table 22-4.
Table 22-4 Nested connection-reuse-pool Elements
| Element | Description |
|---|---|
|
pool-name |
A String value that identifies the name of this pool. All configured |
|
destination |
Specifies the IP address or host name of the destination SBC or S-CSCF. Converged Application Server opens or reuses 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 22-5 shows a sample connection-reuse-pool configuration having two pools.
Example 22-5 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>
This element enables you to specify a Globally-Routable User Agent URI (GRUU) that Converged Application Server 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 Converged Application Server cluster. (In a single-server domain, use a GRUU for the server itself.)
User Agents (UAs) deployed on Converged Application Server typically obtain GRUUs through 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 includes the +sip.instance field parameter in the Contact header in each Contact for which GRUU is required. Upon receiving a GRUU, the UA uses the GRUU as the URI for the Contact header field when generating new requests.
This element defines one or more domains for which Converged Application Server is responsible. If a message has a destination domain that matches a domain specified with a domain-alias-name element, Converged Application Server 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. 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.This element determines whether Converged Application Server 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 in the Administration Console. In the Administration Console, select Configuration, then select the 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 Converged Application Server, 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 through the gateway port.
Converged Application Server 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.This element specifies the level of detail to record in Converged Application Server 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 thebasic option.
You can also set this parameter using the Configuration > General tab of the SipServer Administration Console extension.
Converged Application Server 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 Converged Application Server 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 Converged Application Server'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, Converged Application Server applies the action specified by stale-session-handling before considering the value of the default-behavior element. The default-behavior is performed only when you have configured stale-session-handling to perform the continue action.By default Converged Application Server 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>
Setting this element to true does not affect 100 Trying responses.