The SIP RA is configured using SLEE configuration properties. These properties may be specified at deploy time or updated later using management commands.

The file build.properties contains the default set of configuration properties that will be used when deploying the RA with the provided Ant build.xml script:

build.properties
sip.ra.properties=IPAddress=AUTO,Transports="udp,tcp",Port=5060,SecurePort=5061

Network address properties

These properties define the IP address, ports and transports that the SIP RA entity will be using. The default configuration is to listen on all interfaces, using UDP and TCP, on port 5060.

Property name Description Values Default
 IPAddress

The IP address the SIP RA will listen on. The value AUTO means the RA will listen on all interfaces and use the host’s primary IP address in outgoing headers.

An IP address range may also be used, using address/mask notation; for example, 192.168.0.0/24. This will select the matching IP address on the node, if one exists. This may be useful in a cluster where nodes have IP addresses on the same subnet.

a hostname,
IP address,
IP address range,
or AUTO

 AUTO
 VirtualAddresses

A list of hostnames and/or IP addresses that are local to the cluster. Required when a load balancer is providing a virtual IP address (VIP) for the Rhino cluster. Addresses may also include a port number (for example, host:5090 in case the load balancer is using a different port.

The RA treats incoming messages routed to these addresses as if they were local. For example, isLocalSipURI() will return true if the URI’s host field matches one of these virtual addresses.

If this property is set, and the UseVirtualAddressInURIs property is set to true, the first name in the list will be used in SIP URIs generated by the RA, so that requests are routed back to the VIP, and not a specific node. The first name should be the fully-qualified hostname corresponding to the VIP.

By default this property is empty, meaning the SIP RA will use the node’s IP address (as determined by the IPAddress property) in SIP URIs.

list of hostnames or IP addresses

(none)

 UseVirtualAddressInURIs

Specifies whether to use the configured virtual address in SIP URIs generated by the SIP RA.

If true (the default), the first address in the VirtualAddresses property will be used for the host part in SIP URIs. Otherwise, the node’s IP address (as determined by the IPAddress property) will be used.

true, false

 true
 ViaSentByAddress

Specifies an address (IP address or hostname) that will be used in the "sent-by" field of Via headers added by the SIP RA.

By default this property is empty, and the SIP RA will use the local IP address of the node. In some scenarios it may be necessary to override the default and use a virtual server address.

a hostname or IP address

(none)

 Port

Port that will be used for unencrypted SIP transports (UDP, TCP, SCTP).

an integer port number

 5060
 SecurePort

Port that will be used for encrypted SIP transports (TLS).

an integer port number

 5061
 Transports

Supported SIP transports. The RA will open listen sockets for these transports.

a comma-separated list containing one or more of UDP, TCP, SCTP or TLS

 UDP,TCP
 OffsetPorts

Required when running multiple cluster nodes on the same host. If true, the RA will automatically add an offset to the SIP port number so that each SIP RA instance gets a different port number.

See PortOffset below.

true, false

 false
 PortOffset

Required when running multiple cluster nodes on the same host. If OffsetPorts is enabled, the SIP RA’s port will be calculated as Port + (NodeID - PortOffset). Typically the PortOffset value used is the lowest NodeID in the cluster. So if Port is 5060, and the lowest NodeID is 101, and the cluster has nodes 101, 102 and 103, the SIP ports used will be 5060, 5061 and 5062 respectively.

an integer NodeID, usually the value of the lowest NodeID in the cluster

(none)

 AllowLoopbackSend

Determines whether the RA is allowed to send SIP messages to itself. Disabled by default to prevent accidental loops.

true, false

 false
 SCTP:additional_addresses

By default, SCTP listen sockets will bind to the configured IPAddress value. Additional IP addresses may be specified here; they will be advertised to peers during SCTP association setup. This property accepts a comma- or whitespace-delimited list of hostnames or addresses.

Like IPAddress, each address may be an address range, such as 192.168.0.0/24. The RA selects the matching interface on the host.

If IPAddress is AUTO or a wildcard address, then these additional addresses are ignored. Additional addresses that are wildcards are also ignored.

list of hostnames or IP addresses

(none)

SIP RA Features

Property Name Description Values Default
 Automatic100TryingSupport

If enabled, the RA will automatically generate 100 Trying responses for INVITEs.

true, false

 true
 ReplicatedDialogSupport

Enables support for replicating SIP dialog state, so that dialog activities can continue on other cluster nodes after a node failure. Requires a clustered production Rhino installation.

true, false

 false
 ExtensionMethods

SIP methods that can initiate dialogs, in addition to the standard INVITE and SUBSCRIBE methods.

a comma-separated list of SIP method names

(none)

 WorkerPoolSize

Number of worker threads the SIP RA will use to process incoming messages. If zero, the RA will receive and process messages in the same I/O thread. Otherwise, the pool will be used so that incoming messages can be processed concurrently.

integer, 0 or more

 4
 WorkerQueueSize

Queue size for the worker thread pool. If the queue fills then the RA will drop packets (UDP) or temporarily suspend reads (TCP, TLS, SCTP).

integer, 1 or more

 50
 IOThreads

Number of threads for handling network I/O. SIP sockets are divided between the I/O threads. A value of zero or less will create 2N threads, where N is the number of CPU cores.

integer, 0 or more

 1
 ListenBacklog

Size of the listen backlog queue for server sockets. Increase this to allow the server to accept more concurrent connection requests. A value of zero or less means use the Java platform’s default.

integer

 0
 UDPMaxRequestSize

The maximum size (in bytes) of SIP requests that may be sent sent using UDP. Requests larger than this will automatically be sent using TCP instead, as per RFC3261 §18.1.1. Values of zero or less disable this feature; the RA will try to send with UDP anyway. This is not recommended as fragmentation and packet loss are more likely with large UDP datagrams.

integer

 1300
 UDPInputBufferSize

Size of UDP input buffer, in bytes. UDP messages larger than this will be rejected. Clients should send large messages using TCP, as per RFC3261 §18.1.1; this option is provided to handle exceptional cases. Values must be at least 2048 bytes to ensure the stack can handle typical cases. Relying on large UDP datagrams is not recommended as fragmentation and packet loss are more likely.

integer, 2048 or more

 2048
 AutomaticOptionsResponses

If enabled, OPTIONS requests that are routed directly to this RA’s address (no Route header and the Request-URI has the RA’s address) will be answered immediately by the RA. Otherwise, the RA passes all OPTIONS requests up to SLEE applications to be processed. This is enabled by default so that OPTIONS health checks from load balancers or gateways are handled efficiently.

true, false

 true
 InviteTransactionLifetime

The maximum time (in ms) that INVITE transaction activities may be active for. Activities older than this value will be removed on Rhino’s next query liveness call. The default value of 0 means that activities will be removed on their first query liveness call, which is usually after 5 minutes with Rhino’s query liveness configuration.

long value in milliseconds, 0 or more

 0
 RetryAfterInterval

When the RA rejects a request due to overload, it will send a "503 Service Unavailable" response with this Retry-After interval (in seconds This instructs the client to back off so the server can recover. An interval of 0 or less means the RA will not automatically insert the Retry-After header.

integer value in seconds

 5
 RFC3263:failover_enabled

Specifies whether to use RFC 3236: Failover and Load Balancing. By default this is disabled, to match existing behaviour. If enabled, the RA uses RFC 3263 DNS procedures to find possible servers and automatically fails over to backup servers where available. If multiple servers are found in DNS they are sorted and tried according to their SRV priority and weight as per RFC 2782. If disabled, the DNS procedures are still used to find server addresses, but only the first address is used.

true or false

 false
 RFC3263:failover_timer

Specifies the duration of the failover timer. If RFC 3263 failover is enabled and this timer expires before any responses were received, the RA treats this as a transport error and tries sending the request to the next available server. This timer should be set to a value smaller than the default Timer B and Timer F timers (32s) so that failures can be detected promptly. A value of zero or less disables this timer.

failover time in milliseconds

 10000
 RFC3263:blacklist_timer

The duration for which a server will be blocked after a failure is detected. This avoids the RA trying to use the server immediately after a failure, when it is most likely just going to fail again. After this time has passed the failed server may be tried again on subsequent client transactions. If a server specifies a Retry-After duration in a 503 response, that value will be used instead.

duration in milliseconds

 300000
 RFC3263:fallback_to_blacklist_address

Specifies whether to fallback to sending to a blocked address, when there are no more alternatives. If false, a SipException will be thrown if no addresses are available for the request. If true (default), the last address found for the target will be tried, even if it is blocked, in case the address is now back up. If the address was not available then the request may timeout or generate a 503 response.

true or false

 true
 RFC3263:blacklist_on_transaction_timeout

Specifies whether to block addresses on SIP transaction timeout (Timer F).

true or false

 true
 SessionTimer:default_refresher

The default refresher value that will be inserted when a UAS responds to an initial session refresh request that did not specify a refresher. Must be uac or uas (case-insensitive).

uac or uas

 uas
 ErrorResponseProfileTable

The profile table containing per-request-method configuration of RA generated error responses. Profiles named to match request methods contain a response code and, optionally, a Reason header value to send instead of the default RA generated error. This configuration only overrides 5xx responses from the RA. Profiles are named for the request method they define responses to, for example INVITE, OPTIONS.

Null or a profile table name.
An example configuration is ErrorResponse
ProfileTable
="sip-ra1-error-responses" referring to a profile table called "sip-ra1-error-responses" containing a profile named "INVITE" with attributes ErrorResponseCode=500 and ReasonHeader="Q.850; cause=16; text=System down"

 _(none)_
RefusedResponseProfileTable

The profile table containing per-request-method configuration of RA generated request-refused responses. Profiles named to match request methods contain a response code and, optionally, a Reason header value to send instead of the default RA generated error. Overrides ErrorResponseProfileTable if configured. This configuration overrides 5xx responses from the RA when the SLEE rejects creation of an activity (new dialog or non-dialog) e.g. due to rate-limiting. Profiles are named for the request method they define responses to, for example "INVITE", "OPTIONS".

Null or a profile table name. An example configuration is RefusedResponseProfileTable="sip-ra1-refused-responses" referring to a profile table called "sip-ra1-refused-responses" containing a profile named "INVITE" with attributes ErrorResponseCode=603 and ReasonHeader="Q.850; cause=21; text=Rate limited"

 _(none)_
 ResponseConfigurationPollTime

The interval (ms) between scans of the response configuration profile tables.

 300,000 (_5 minutes_)
 NonInvite:TryingTimer

The time (ms) at which an automatic 100 Trying response must be sent for all non-INVITE server transactions, regardless of transport protocol, as per RFC 4320.

Should almost always be left at the default of 3500ms, unless it is known that the network uses T1 and T2 values that differ from SIP defaults.

Non-INVITE server transactions on unreliable transports (UDP) always use this timer value.

A value of zero means the 100 Trying response is sent immediately.

Negative values disable this behaviour, so no automatic 100 Trying responses are sent.

duration in milliseconds

 3500
 NonInvite:TryingTimerTCP

The time (ms) at which an automatic 100 Trying response is sent for non-INVITE server transactions on TCP and other reliable transports, as per RFC 4320.

A negative value means inherit the configured NonInvite:TryingTimer value (default 3500), this is the default setting. Otherwise a value between zero and NonInvite:TryingTimer may be configured.

A value of zero means the 100 Trying response is sent immediately.

If NonInvite:TryingTimer is disabled, this setting is ignored and no automatic 100 Trying responses are sent.

duration in milliseconds

 -1
 Invite:TimerC

Configures automatic "Timer C" behaviour for INVITE transactions.

Timer C (from RFC 3261) cleans up INVITE transactions that have not had a final response, and have not seen any provisional responses for at least 3 minutes.

Timer C resets on each 101-199 response. If Timer C fires before a 101-199 or final response arrives, then the transaction is terminated. Timer C is enabled for INVITE server transactions only if ServerTransactionTimeoutEnabled is true.

INVITE server transactions that time out will send a 408 (Request Timeout) response and fire a transaction timeout event. INVITE client transactions will first send a CANCEL request. If the CANCEL request does not trigger a final response for the INVITE, then a transaction timeout event is fired, and the INVITE client transaction is terminated.

A value of 0 or less disables Timer C. Otherwise it must be set to at least 180000ms (3 minutes).

duration in milliseconds

 0
 ServerTransactionTimeoutEnabled

Specifies whether server transactions should automatically timeout if the service sent no final response.

If enabled, INVITE and non-INVITE server transactions will automatically be removed after 64*T1 (32) seconds, and a transaction timeout event will be fired.

INVITE server transactions will send a 408 (Request Timeout) response if a 100 Trying was sent. If no 100 Trying was sent, no 408 response is needed as the client transaction will be ended by its Timer B.

Non-INVITE server transactions send no response (as per RFC 4320), since the client transaction will have already been ended by its Timer F.

If the INVITE server transaction sends a 101-199 response then the timer is cancelled, and Timer C behaviour (if enabled) takes over. If the transaction is part of a Dialog activity then that activity will be removed as well, as the service is in an unusable state.

true or false

 false
 SAS:redact_dtmf

Whether to redact DTMF signals in SIP message bodies reported to SAS. Applies to INFO requests with "application/dtmf-relay" bodies. If true, the message body reported to SAS will have the DTMF signal character replaced with "-". The original message is unmodified. This is to prevent potentially sensitive information transmitted in DTMF signals from leaking to SAS.

true or false

 false

SSL/TLS Properties

These properties must be specified when the Transports property contains "TLS".

Property Name Description Values Default
 Keystore

The name of a keystore file used to store private key material.

a file name

 sip-ra-ssl.keystore
 Truststore

The name of a truststore file containing trusted CA certificates.

a file name

 sip-ra-ssl.truststore
 KeystorePassword

Password to unlock the keystore.

a string

(none)

 TruststorePassword

Password to unlock the truststore.

a string

(none)

 KeystoreType

The type of keystore implementation.

a keystore type name

 jks
 TruststoreType

The type of truststore implementation.

a truststore type name

 jks
 CRLURL

The location of a certificate revocation list.

a URL

(none)

 CRLRefreshTimeout

The certificate revocation list refresh timeout.

a duration in seconds

 86400
 CRLLoadFailureRetryTimeout

The certificate revocation list load failure timeout.

a duration in seconds

 900
 CRLNoCRLLoadFailureRetryTimeout

The certificate revocation list load failure retry timeout.

a duration in seconds

 60
 ClientAuthentication

Indicate whether clients need to be authenticated against certificates in the truststore.

NEED, WANT, or NONE

 NEED
 EnabledCipherSuites

Specifies the cipher suites to enable on all TLS sockets. If empty, The JVM’s default cipher suites will be used. For the list of available cipher suites, see SunJSSE Provider.

a comma-separated list of cipher suite names

 empty

BigGroup Properties

These properties apply when using the BigGroup 3.1 RA Type API.

Property Name Description Values Default
 BigGroup.core-pool-size

The core number of threads in the Big Group thread pool.

integer, between 0 and BigGroup.max-pool-size

 4
 BigGroup.max-pool-size

The maximum number of threads in the Big Group thread pool.

integer, 0 or more

 50
 BigGroup.queue-size

The maximum number of waiting threads in the Big Group thread pool.

integer, 0 or more. 0 indicates no queuing, tasks are scheduled immediately if the pool has capacity.

 0
 BigGroup.fork-timeout

The default maximum time to wait for a success response for a Big Group Fork Activity.

timeout in milliseconds

 10000
 BigGroup.fork-batch-size

Specify the maximum number in a batch for a big group fork thread to process. Tune the batch size by observing the SIP RA’s big group stats in "rhino-stats".

integer, 1 or more

 250
 BigGroup.fork-keep-callid

Specifies whether to keep the Call-ID from the original request when forking the request to its targets. Set to False when using a sipp UAS or other simulator.

true, false

 `false`
 BigGroup.notify-batch-size

Specify the maximum number in a batch for a big group notify thread to process. Tune the batch size by observing the SIP RA’s big group stats in "rhino-stats".

integer, 1 or more

 250

F5 BIG-IP Properties

The SIP RA can optionally use the F5 iControl API to dynamically update a SIP load balancer pool on the BIG-IP platform. These properties specify how the RA connects to BIG-IP.

Property Name Description Values Default
 BigIP.enable-notify

Enable or disable F5 BIG-IP notify. On RA activation, if enabled F5 BIG-IP will be notified to enable the node’s pool member and start sending SIP Messages to Node. On RA deactivation, if enabled F5 BIG-IP will be notified to disable the node’s pool member and stop sending SIP Messages to Node. If disabled, F5 BIGIP will be not be notified on activation or deactivation of RA.

true, false

 false
 BigIP.ipaddress

BIG-IP load balancer’s address

an IP address or hostname

(none)

 BigIP.port

BIG-IP load balancer’s iControl API port

an integer port number

 443
 BigIP.username

The user name to authenticate with the BIG-IP load balancer.

a string

(none)

 BigIP.password

The password to authenticate with the BIG-IP load balancer.

a string

(none)

 BigIP.poolname

The BIG-IP Pool that the SIP RA nodes are members of.

a string

(none)

Previous page Next page