Note: This release deprecates the use of sipserver.xml to configure the behavior of the SIP Servlet container. sipserver.xml may not be provided in future releases of WebLogic SIP Server.
This document describes how to configure the SIP servlet container capabilities provided by WebLogic SIP Server 2.0.2. The configuration information of the SIP servlet container is stored in the configuration file sipserver.xml. This file is located in the WebLogic SIP Server domain directory (for example, $BEA_HOME/user_projects/domains/mydomain).
Note: If you edit settings in sipserver.xml, you must restart WebLogic SIP Server to realize the changes. If you edit SIP Servlet container settings using the Administration console, restarting the server is not required in all instances.
Configuration properties are referenced by WebLogic SIP Server at run time, and are specified with the <container-param> tag. The <container-param> tag has two children: the <param-name> and <param-value> tags. Each tag specifies the property name and its value, respectively.
The following values can be set for the <param-name> tag:
SessionSwapoutDuration - Set the period (by ms) from the last accessed time of the application session to the time when it is swapped out. However, the timing of swap-out would be every 1/10 seconds of this value (For example, if the period until swap-out is set as 10 minutes, it would happen every 1 minute. If a value shorter than 30 seconds is specified, it would be every 30 seconds). Accordingly, swap-out may not always occur immediately after the specified period of time has passed. If a negative value is set, the swapping function is disabled. A value less than 60000 cannot be specified. If you have not specified SessionSwapoutDuration, the value is set to 600000 (10 minutes).
listenAddressCacheDuration - Specify the period to cache the address information retrieved by network channel function. The specification is made by msec and the shortest period that can be specified is 500 (msec). In addition, the default is 30 seconds (30,000) and this default period is also used when a negative value is specified.
Note: This release of WebLogic SIP Server deprecates creating general-purpose SIP filters by extending a base filter class.
A filter is a component for filtering received SIP messages before they are processed by SIP Servlet container. The filtering process uses the pipeline structure. SIP messages are processed with filters in the order which the filters are configured in the sipserver.xml. A filter is specified with the <filter> tag which has the following attribute:
classname - Specifies the class name which implements the filter.
AccessLogFilter is a filter to record access to WebLogic SIP Server. In AccessLogFilter, you can set the following <param-name> values:
| param-name | Description |
| format | Set the format of access log. The format is defined by an integer not less than 0, bracketed by "{" and "}". |
| Number not less than 0 | Set a token to record to the number defined in "format". |
The following tokens can be specified:
| Token | Description | Example |
|---|---|---|
| %date | The date when the message was received. ("yyyy/MM/dd" format) | 2004/05/16 |
| %time | The time when the message was received. ("HH:mm:ss" format) | 18:05:27 |
| %mtype | The type of receiving. | SIPREQ |
| %method | The name of the SIP method. It records the method name to invoke when forwarding. | INVITE |
| %call_id | The Call-ID header. It is blank when forwarding. | 43543543 |
| %cseq | The CSeq header. It is blank when forwarding. | INVITE 1 |
| %req_uri | The request URI. This token is only available for the SIP request. | sip:foo@bea.com |
| %from | The From header (all). It is blank when forwarding. | sip:foo@bea.com;tag=438943 |
| %from_uri | The SIP URI part of the From header. It is blank when forwarding. | sip:foo@bea.com |
| %from_tag | The tag parameter of the From header. It is blank when forwarding. | 12345 |
| %to | The To header (all). It is blank when forwarding. | sip:foo@bea.com;tag=438943 |
| %to_uri | The SIP URI part of the To header. It is blank when forwarding. | sip:foo@bea.com |
| %to_tag | The tag parameter of the To header. It is blank when forwarding. | 12345 |
| %exception | The class name of the exception occurred when calling the AP. Detailed information is recorded to the run-time log. | NullPointerException |
The access log is stored to the file specified in the log4j.properties in the directory where WebLogic Server runs. The default setting is (the directory where WLS runs)/logs/sip/access.log.
The following shows the settings configured during installation.
<filter classname="com.bea.wcp.sip.engine.server.AccessLogFilter">
<filter-param>
<param-name>format</param-name>
<param-value>{0} {1}, {2}, {3}, {4}, {5}</param-value>
</filter-param>
<filter-param>
<param-name>0</param-name>
<param-value>%date</param-value>
</filter-param>
<filter-param>
<param-name>1</param-name>
<param-value>%time</param-value>
</filter-param>
<filter-param>
<param-name>2</param-name>
<param-value>%mtype</param-value>
</filter-param>
<filter-param>
<param-name>3</param-name>
<param-value>%method</param-value>
</filter-param>
<filter-param>
<param-name>4</param-name>
<param-value>%from_uri</param-value>
</filter-param>
<filter-param>
<param-name>5</param-name>
<param-value>%to_uri</param-value>
</filter-param>
</filter>
A proxy server is specified with the <default-proxy> tag. You can configure multiple proxy servers. The TCP messages are sent to the proxy servers in the order which the proxy servers are configured. The UDP messages are sent only to the first proxy server. The <default-proxy> tag has the following three attributes. These attributes are required.
host - The host name or IP address of the proxy server.
port - The connection port number for the proxy server.
transport - The transport name used by the proxy server. The possible values are "tcp" and "udp."
You can change the behavior of proxy process by setting a policy. A policy is specified with the <proxy-policy> tag. The possible values are as follows:
domain - Sends messages as per the routing rule defined by RFC 3261.
proxy - Sends the message to the downstream proxy specified in the "default-proxy". If there are multiple specifications for "default-proxy," they are tried in the order in which they are specified. However, if the transport tries the UDP proxy, the settings for the subsequent proxies are ignored.
domain,proxy - If the destination domain can be resolved, behaves like when domain is specified. If it cannot be resolved, behaves like when proxy is specified.
The following shows the default proxy configuration for new WebLogic SIP Server domains. If the destination is determined in accordance with the routing rule of RFC 3261, the message is sent to that destination. If not, the message is sent to the host "siplb.bea.com" (which would need to be configured appropriately).
<proxy>
<proxy-policy>domain,proxy</proxy-policy>
<default-proxy host="siplb.bea.com" port="5060" transport="udp"/>
<!-- Other proxy tags can be added. -->
</proxy>
To enable incoming-call regulation, set <income-call> (For details on incoming-call regulation, see Blockage Function). The <income-call> tag has the following three tags. Settings for these tags are required at all times.
threshold-policy - Sets the policy for incoming-call regulation. Specify "session-rate" for regulation by session generation rate, and "queue-length" for regulation by queue length.
threshold-value - Sets the threshold to exercise incoming-call regulation. For regulation by session generation rate, specify the number of sessions generated per second, and for regulation by queue length, specify the length of the message resident in the execution queue.
release-value - Sets the threshold to terminate the incoming-call regulation. The value to be set is the same as the one set for "threshold-value".
The "session generation rate" and "queue length" cannot be monitored at the same time.
Here is an example setting in the sipserver.xml. It is configured to trigger the regulation at 50 sessions/sec and terminate the regulation at 40 sessions/sec.
<income-call>
<threshold-policy>session-rate</threshold-policy>
<threshold-value>50</threshold-value>
<release-value>40</release-value>
</income-call>
If the SSE is to be operated with a load balancer, configure the <loadbalancer> tag. The <loadbalancer> tag has the following two attributes.
host - Sets the host or IP address on which load balancer runs.
enable - the flag to indicate whether the setting is valid. If true is specified, the setting of the load balancer is valid.
The port of the load balancer is set by <port-info> tag. The <port-info> tag has the following two attributes.
port - Sets the connection port number for the load balancer.
transport - Sets the transport name used by the load balancer. The possible values are "tcp" and "udp."
The following is a configuration when the load balancer runs on the host having an address of 192.168.0.1 and UDP port number of 6080.
<loadbalancer host="192.168.0.1" enable="true">
<port-info port="6080" transport="udp"/>
</loadbalancer>
Note: WebLogic SIP Server 2.0.2 deprecates the use of the connector element for configuring port numbers for SIP TCP or UDP. The method for specifying port numbers may change in the future.
The connector element converts a SIP message received using TCP or UDP into a format recognizable to the SIP Servlet Container. On multihomed server hardware, connector definitions are also used for populating SIP message system headers (Via, Contact, and Record-Route) with correct IP address to use for routing subsequent messages.
The connector element uses the following attributes:
host - Specifies the IP address of a connector. The host attribute is required when configuring multiple connectors for a multi-homed server machine. WebLogic SIP Server uses the host IP address when determining the address to embed in SIP message system headers. See Example Configuration for a Multihomed Server below.
Servers that use a single NIC can omit the host attribute; the connector automatically uses the IP address configured for WebLogic SIP Server.
port - Specifies the port number the connector uses to receive the SIP messages. This attribute is required.
transport - Specifies the transport type the connector uses to receive the SIP messages. The possible values are "tcp" and "udp." This attribute is required.
classname - Specifies the class name that implements the connector. You must specify com.bea.wcp.sip.engine.connector.WLSConnector in WebLogic SIP Server 2.0.2.
Connectors are defined within the transport element, which also defines the execute queue (thread-pool-name) used for handling SIP messages received by a connector. The transport element also includes connection-timeout that specifies the time in seconds that a TCP connector maintains a connection. The connection-timeout default is 60 seconds.
The following code listing shows the default connector configured for the example WebLogic SIP Server domain. The connector uses both TCP and UDP is configured to receive all SIP traffic over port 5060. The connector's IP address is derived from the WebLogic SIP Server host.
<transport>
<connector port="5060"
transport="udp"
classname="com.bea.wcp.sip.connector.WLSConnector"/>
<connector port="5060"
transport="tcp"
classname="com.bea.wcp.sip.connector.WLSConnector"/>
<thread-pool-name>sip.transport.Default</thread-pool-name>
<connection-timeout>60</connection-timeout>
</transport>
When configuring connectors for a server that has multiple network interfaces (a "multihomed" server), you must configure a separate connector for each IP address. You must also define a host attribute for each connector that specifies the IP address used. WebLogic SIP Server uses the host attribute when embedding routing information into SIP message system headers.
Note: If you do not configure a connector for a particular IP address on a multihomed machine, that IP address cannot be used when populating Via, Contact, and Record-Route headers.
The following code listing shows a sample connector configuration for a multihomed WebLogic SIP Server having two IP addresses. Each connector accepts UDP and TCP messages over port 5060, but each connector serves a different network.
<transport>
<connector
host=10.0.1.5
port="5060"
transport="udp"
classname="com.bea.wcp.sip.connector.WLSConnector"/>
<connector host=10.0.1.5
port="5060"
transport="tcp"
classname="com.bea.wcp.sip.connector.WLSConnector"/>
<connector
host=192.168.1.6
port="5060"
transport="udp"
classname="com.bea.wcp.sip.connector.WLSConnector"/>
<connector host=192.168.1.6
port="5060"
transport="tcp"
classname="com.bea.wcp.sip.connector.WLSConnector"/>
<thread-pool-name>sip.transport.Default</thread-pool-name>
<connection-timeout>60</connection-timeout>
</transport>
In WebLogic SIP Server 2.0.2 you can use the container-param element to configure values for the SIP T1, T2, and T4 timers. The container-param element requires two elements to define the parameter name and parameter value as shown in this example:
<container-param> <param-name>parametername</param-name> <param-value>parametervalue</param-value> </container-param>
The valid param-name values are T1TimeoutInterval, T2TimeoutInterval, T4TimeoutInterval, TimerBTimeoutInterval, and TimerFTimeoutInterval and are described in the following sections.
This parameter 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 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 specification for more information about SIP timers.
Timer T1 sets the values of Timers B and F (at 64*T1) only if you do not explicitly set values for those timers using the TimerBTimeoutInterval and TimerFTimeoutInterval parameters.
If T1TimeoutInterval is not configured, WebLogic SIP Server uses the SIP protocol default param-value of 500 milliseconds. For example:
<container-param> <param-name>T1TimeoutInterval</param-name> <param-value>500</param-value> </container-param>
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 specification for more information about SIP timers.
If T2TimeoutInterval is not configured, WebLogic SIP Server uses the SIP protocol default value of 4000 milliseconds. For example:
<container-param> <param-name>T2TimeoutInterval</param-name> <param-value>4000</param-value> </container-param>
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. See the SIP: Session Initiation Protocol specification for more information about SIP timers. Timer T4 also specifies the initial values of Timers I and K, which control the wait times for re-transmitting ACKs and responses over UDP.
If T4TimeoutInterval is not configured, WebLogic SIP Server uses the SIP protocol default value of 5000 milliseconds. For example:
<container-param> <param-name>T4TimeoutInterval</param-name> <param-value>5000</param-value> </container-param>
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 SIP: Session Initiation Protocol specification for more information about SIP timers.
If TimerBTimeoutInterval is not configured, the Timer B value is derived from timer T1 (64*T1, or 32000 milliseconds by default). For example:
<container-param> <param-name>TimerBTimeoutInterval</param-name> <param-value>32000</param-value> </container-param>
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 SIP: Session Initiation Protocol specification for more information about SIP timers.
If TimerFTimeoutInterval is not configured, the Timer F value is derived from timer T1 (64*T1, or 32000 milliseconds by default). For example:
<container-param> <param-name>TimerFTimeoutInterval</param-name> <param-value>32000</param-value> </container-param>