Configuration

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

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)

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

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 that will be used for unencrypted SIP transports (UDP, TCP, SCTP).

an integer port number

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

an integer port number

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

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

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)

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

true, false

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)

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

true, false

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

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

a comma-separated list of SIP method names

(none)

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

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

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

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

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

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

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

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

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

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

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

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. If this property is zero or less, then no blocking of failed addresses will occur.

duration in milliseconds

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

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

true or false

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

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"

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"

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

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

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

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

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

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

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

a file name

The name of a truststore file containing trusted CA certificates.

a file name

Password to unlock the keystore.

a string

(none)

Password to unlock the truststore.

a string

(none)

The type of keystore implementation.

a keystore type name

The type of truststore implementation.

a truststore type name

The location of a certificate revocation list.

a URL

(none)

The certificate revocation list refresh timeout.

a duration in seconds

The certificate revocation list load failure timeout.

a duration in seconds

The certificate revocation list load failure retry timeout.

a duration in seconds

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

NEED, WANT, or NONE

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

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

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

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

integer, 0 or more

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.

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

timeout in milliseconds

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

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

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

Not used. F5 BIG-IP notify support has been removed.

true, false

Not used. F5 BIG-IP notify support has been removed.

an IP address or hostname

(none)

Not used. F5 BIG-IP notify support has been removed.

an integer port number

Not used. F5 BIG-IP notify support has been removed.

a string

(none)

Not used. F5 BIG-IP notify support has been removed.

a string

(none)

Not used. F5 BIG-IP notify support has been removed.

a string

(none)