Configuring SIP – CBA Live Assist Help Center

The Fusion Application Server contains a SIP subsystem, which you can configure.

The attributes described in this section have not all been validated with FAS; it is therefore recommended that you consult CBA Support before making any changes to them.

Configuring the SIP Servlet Subsystem

The SIP Servlet subsystem exposes many different attributes for configuration. All of the attributes have default settings, so configuration of them is optional. These attributes can be configured using the Management Console or the CLI.

Configuring the SIP Servlet Subsystem using the Management Console

Launch the Management Console - see the Starting the Management Console section in the Management Interfaces article.
From the top right menu, select Profiles.
From the top left menu, select the ha profile.
From the menu on the left, expand Sip and select Sip Servlet.
Select the Configuration navigation tab:

The basic SIP Servlet attributes are displayed at the top of the main content pane. These are the attributes that you are most likely to need to change; for example External Address Mode, as discussed in the Changing the External Address Modes section in the Managing Cluster Components article, and Cluster Address, as discussed in the Changing Addresses section in the same article.

To view other attributes, which are less likely to require a configuration change, click on the expand icon () by the Advanced heading.

Note: To see a description of all the attributes, click the Need Help? link on the right.

To edit an attribute, click Edit.

Note: If the advanced attributes were displayed when you clicked Edit, all of the attributes are available to edit. If they were not displayed, only the basic attributes are available to edit.

Edit the attribute values as required and click Save.

The pane reverts back to view mode, displaying the updated values.

Restart the ASs to pick up the new configuration.

Configuring the SIP Servlet Subsystem using the CLI

Start the CLI (see the Starting the CLI section in the Management Interfaces article).
To return a list of the SIP subsystem attributes that can be configured, use:

/profile=ha/subsystem=sip/:read-resource

The list includes all of the SIP attributes, including the SIP connectors, which are described in the Configuring SIP Connectors section in this article, and the SIP stack properties, which are described in the Configuring the SIP Stack section in this article.

Edit an attribute with:

/profile=ha/subsystem=sip/:write-attribute(name=<attribute name>, value=<attribute value>)

where <attribute name> is the name of the attribute, and <attribute value> is the new value.

Restart the AS nodes to pick up the new configuration.

Configuring SIP Connectors

You can also configure the SIP connectors (for example, to allow the static address of LBs to be set, or if you change external ports or IP addresses). All of the attributes have default settings, so configuration of them is optional.

Configuring SIP Connectors using the Management Console

Launch the Management Console - see the Starting the Management Console section in the Management Interfaces article.
From the top right menu, select Profiles.
From the top left menu, select the ha profile.
From the menu on the left, expand Sip and select Sip Servlet.
Select the Connectors navigation tab:

In the Available Sip Connectors section, select the connector that you want to edit.

The attributes of the connector will show in the Selection section. To see a description of the attributes, click the Need Help? link on the right.

Click Edit.
Edit the attribute values, and click Save.

You will see the updated values in the Available Sip Connectors section.

Restart the AS to pick up the new configuration.

Configuring the SIP Connectors using the CLI

Start the CLI (see the Starting the CLI section in the Management Interfaces article).
To list the current value for a connector, use:

/profile=ha/subsystem=sip/connector=<connector>:read-resource()

where <connector> is the SIP connector name ( sip-udp, sip-tcp, sip-tls, or sip-ws).

Edit a value with:

/profile=ha/subsystem=sip/connector=<connector name>:write-attribute(name=<attribute name>, value=<attribute value>)

where <connector> is the SIP connector name, <attribute name> is the name of the attribute, and <attribute value> is the new value.

The changes will be pushed to each host in the cluster. Restart all the hosts to pick up the new configuration.

Configuring the SIP Stack

FAS uses the NIST SIP stack (that is, the reference implementation of the JAIN SIP API). The NIST SIP stack has a number of optional configuration properties (the names of which begin with gov.nist.javax.sip), which can be configured using the Management Console or the CLI. Using the Management Console, you can also remove an existing property or add a new one.

The following table lists some of the properties that could be edited to tune your FAS cluster. The default values listed below reflect the values in a FAS installation, so some might differ from the default values of the native NIST stack; not all are set, so if you wish to set them, they may need to be added. For a full description of options, refer to the NIST SIP stack documentation.

Option	Default	Description
gov.nist.javax.sip.LOG_ MESSAGE_CONTENT	true	Set to false if you do not want to capture message content in the log.
gov.nist.javax.sip. AUTOMATIC_DIALOG_ ERROR_HANDLING	false	Set to true to enable merged requests loop detection: ● If the request has no tag in the To header field, the UAS core must check the request against ongoing transactions. ● If the From tag, Call-ID, and CSeq exactly match those associated with an ongoing transaction, but the request does not match that transaction, the UAS core generates a 482 (Loop Detected) response and passes it to the server transaction.
gov.nist.javax.sip. MAX_MESSAGE_SIZE	10000	Maximum size of content that a UDP connection can read. This is to prevent DoS attacks launched by writing to a UDP connection until the server can’t handle any more data.
gov.nist.javax.sip. MAX_TCP_ MESSAGE_SIZE	2000000	Maximum size of content that a TCP connection can read. This is to prevent DoS attacks launched by writing to a TCP connection until the server can’t handle any more data.
gov.nist.javax.sip. MTU_SIZE		This value defines the size in bytes that the AS uses as the MTU (UDP Maximum Transmission Unit). The AS follows the rules outlined in RFC 3261 regarding using the MTU to determine whether a UDP request could become fragmented, and whether to avoid this by upgrading the protocol used from UDP to TCP. If it upgrades the message, but cannot set up the new TCP channel (for example if the next hop doesn't support TCP), the AS falls back to using UDP; however, fragmentation (particularly over WANs) might cause problems (for example, if parts of a message are dropped, or delivered in the wrong order). If this property is not set, it will default to 1500, which means that messages larger than 1300 bytes (that is, 1500 – 200 buffer) will be upgraded. Set this value to a value larger than the value of gov.nist.javax.sip.MAX_ MESSAGE_SIZE to disable upgrade; the AS will then drop, rather than upgrade, a UDP message greater than the MAX_MESSAGE_SIZE.
gov.nist.javax.sip. CACHE_SERVER_ CONNECTIONS	true	Set to false to close the server socket after a server transaction goes to the TERMINATED state. This allows a server to protect against TCP-based DoS attacks launched by clients. When set to true, the stack will keep the socket open to maximize performance, at the expense of thread and memory resources, but leaving itself open to DoS attacks.
gov.nist.javax.sip. CACHE_CLIENT_ CONNECTIONS	true	Set to false to close the server socket after a client transaction goes to the TERMINATED state. This allows a client to release any buffers, threads, and socket connections associated with a client transaction after the transaction has terminated, at the expense of performance.
gov.nist.javax.sip. CACHE_CLIENT_ CONNECTIONS	64	Concurrency control for the number of simultaneous active threads. If not specified, each event delivered to the listener is run in the context of a new thread. If specified, the stack will run the listener using a thread from the thread pool. This allows you to manage the level of concurrency to a fixed maximum. Threads are pre-allocated when the stack is instantiated.
gov.nist.javax.sip.MAX_ CONNECTIONS		Maximum number of simultaneous TCP connections handled by the stack.
gov.nist.javax.sip.MAX_ SERVER_ TRANSACTIONS	5000	Maximum size of the server transaction table. Requests are selectively dropped if the table size goes over 80% of this size.
gov.nist.javax.sip.MAX_ CLIENT_ TRANSACTIONS	unlimited	Maximum number of active client transactions before the caller blocks and waits for the number to drop below a threshold.
gov.nist.javax.sip.MAX_ LISTENER_RESPONSE_ TIME	120	Maximum time in seconds before sending a response to a server transaction. If a response is not sent within this time period, the stack will delete the transaction.
gov.nist.javax.sip.MAX_ TX_LIFETIME_INVITE	-1 (infinite)	A typical value is dependent on early dialog timeout; for example, 180 seconds could be a good default maximum time that an INVITE transaction is supposed to live in the stack. This is to avoid any leaks in whatever state the transaction can be in, even if the application misbehaves. When the maximum time is reached, a timeout event is sent to the application listener, so that the application can take action, and the transaction is removed from the stack after a typical lingering period of 8s.
gov.nist.javax.sip.MAX_ TX_LIFETIME_ NON_INVITE	-1 (infinite)	A typical value is dependent on T1; for example, 2 * T1 could be a good default maximum time (in seconds) that a non-INVITE transaction is supposed to live in the stack. This is to avoid any leaks in whatever state the transaction can be in, even if the application misbehaves. When the maximum time is reached, a timeout event is sent to the application listener, so that the application can take action, and the transaction is removed from the stack after a typical lingering period of 8s. There is a specific property for non-INVITE transactions because a non-INVITE transaction is short-lived as compared to INVITE, and so can be collected more eagerly to save on memory usage.
gov.nist.javax.sip. READ_TIMEOUT	-1 (off)	This option is relevant for incoming TCP connections to prevent starvation at the server. This defines the timeout in milliseconds between successive reads after the first byte of a SIP message is read by the stack. All the SIP headers must be delivered in this interval, and each successive buffer must be of the content delivered in this interval. By default, the stack is open to starvation attacks and the client can be as slow as it wants to be.
gov.nist.javax.sip. CANCEL_CLIENT_ TRANSACTION_ CHECKED	false	This flag is added in support of Load Balancers or failover managers, where you might want to cancel ongoing transactions from a different stack than the original stack. When set to false, the CANCEL client transaction is not checked for the existence or state of the INVITE when you send the CANCEL request, allowing you to CANCEL an INVITE from a different stack. You can also create a CANCEL client transaction late and send it out after the INVITE server transaction has been terminated. This will, however, result in protocol errors. Setting the flag to true enables you to avoid common protocol errors.
gov.nist.javax.sip. RECEIVE_UDP_ BUFFER_SIZE	65536	This property controls the size of the UDP buffer used for receiving SIP messages. If the buffer capacity overflows under load, the messages are dropped, causing retransmissions, further increasing the load, and causing even more retransmissions.
gov.nist.javax.sip.SEND_ UDP_BUFFER_SIZE	65536	This property controls the size of the UDP buffer used for sending SIP messages. If the buffer capacity overflows under load, the messages are dropped, causing retransmissions, further increasing the load, and causing even more retransmissions.
gov.nist.javax.sip. CONGESTION_ CONTROL_TIMEOUT	8000	How much time in milliseconds messages are allowed to wait in the queue before being dropped due to the stack being too slow to respond.
gov.nist.javax.sip.TCP_ POST_PARSING_ THREAD_POOL_SIZE		When using TCP, your phones or clients usually connect independently, creating their own TCP sockets. Sometimes, however, SIP devices are allowed to tunnel multiple calls over a single socket. In the stack, each TCP socket has its own thread. When all calls are using the same socket, they all use a single thread, which leads to severe performance penalty. This option instructs the SIP stack to use a thread pool and split the CPU load between the number of threads specified. The processing is split immediately after the parsing of the message. It cannot be split before the parsing because in TCP the SIP message size is in the Content-Length header of the message, and the access to the TCP network stream has to be synchronized. Additionally, in TCP the message size can be larger. This causes most of the parsing for all calls to occur in a single thread, which might have an impact on the performance in trivial applications using a single socket for all calls. In most applications, it doesn't have any performance impact. If the phones or clients use separate TCP sockets for each call, this option doesn't have much impact, except the slightly increased memory footprint caused by the thread pool. It is recommended that you disable this option, either by setting it to 0 or leaving it blank. Disabling this option avoids closing the TCP socket when something fails because we must keep processing other messages for other calls. Note: This option relies on accurate Content-Length headers in the SIP messages. It cannot recover once a malformed message is processed, because the stream iterator will not be aligned anymore. Eventually, the connection will be closed.
gov.nist.javax.sip.MAX_ FORK_TIME_SECONDS		Maximum time that the original transaction for which a forked response is received is tracked. This property is only relevant to dialog stateful applications (User Agents or B2BUA). When a forked response is received in this time interval from when the original INVITE client transaction was sent, the stack will place the original INVITE client transaction in the response and deliver that to the application. The event handler can get the original transaction from this event.
gov.nist.javax.sip. EARLY_DIALOG_ TIMEOUT_ SECONDS	180	Maximum time that a dialog can remain in the early state (before it receives a final response). Note: In order to avoid a memory leak associated with certain downstream parallel forking scenarios, a dialog in the early state will be torn down if it receives no responses for 180 seconds. This may cause problems in similar sequential forking scenarios, where the container attempts to create a derived session from the original forked session, which no longer exists.
gov.nist.javax.sip. THREAD_PRIORITY		Controls the priority of the threads started by the stack
gov.nist.javax.sip. AGGRESSIVE_CLEANUP	true	A property that will clean up Dialog and Transaction structures aggressively to improve memory usage and performance (up to 50% gain).
gov.nist.javax.sip.MIN_ KEEPALIVE_ TIME_SECONDS	-1 (do not respond)	Minimum time between keep-alive pings (CRLF CRLF) from clients. If pings arrive with less than this frequency a CRLF CRLF reply will be sent; if they arrive with greater frequency they will be rejected.
gov.nist.javax.sip. DIALOG_ TIMEOUT_FACTOR	64	The number of ticks before a dialog that does not receive an ACK receives a Timeout notification.
gov.nist.javax.sip.TLS_ CLIENT_PROTOCOLS	SSLv3, SSLv2Hello, TLSv1	Comma-separated list of protocols to use when creating outgoing TLS connections. Some servers do not support SSLv2Hello, so override to SSLv3, TLSv1 if necessary.
gov.nist.javax.sip.TLS_ CLIENT_AUTH_TYPE	Enabled	Valid values are Enabled, Want, or Disabled. Set to Enabled if you want the SSL stack to require a valid certificate chain from the client before accepting a connection. Set to Want if you want the SSL stack to request a client Certificate, but not fail if one isn't presented. A value of Disabled does not require a certificate chain.
gov.nist.javax.sip. RELIABLE_ CONNECTION_ KEEP_ALIVE_TIMEOUT		Value in seconds that is used as the default keep-alive timeout. (See also http://tools.ietf.org/html/rfc5626#section-4.4.1.)
gov.nist.javax.sip.SSL_ HANDSHAKE_TIMEOUT		Value in seconds that is used as the default timeout for performing the SSL Handshake. This prevents bad clients which connect without sending any data from blocking the server.

Configuring the SIP Stack using the Mangement Console

Launch the Management Console - see the Starting the Management Console section in the Management Interfaces article.
From the top right menu, select Profiles.
From the top left menu, select the ha profile.
From the menu on the left, expand Sip and select Sip Servlet.
Select the Properties navigation tab:

Click on a cell in the Value column to edit it.

The new value is saved automatically when you press <span class="smallcaps">Enter</span> or click outside the cell.

Restart the AS to pick up the new configuration.

Configuring the SIP Stack using the CLI

Start the CLI (see the Starting the CLI section in the Management Interfaces article).
Edit an attribute using the command:

/profile=ha/subsystem=sip/property=<property name>/:write-attribute(name=value, value=<property value>)

where <property name> is the name of a property, and <property value> is the new value.

Restart the AS nodes to pick up the new configuration.