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:
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 An IP address range may also be used, using address/mask notation; for example, |
a hostname, |
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, The RA treats incoming messages routed to these addresses as if they were local. For example,
If this property is set, and the By default this property is empty, meaning the SIP RA will use the node’s IP address (as determined by the |
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 |
|
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 |
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 |
|
false |
PortOffset |
Required when running multiple cluster nodes on the same host. If |
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. |
|
false |
SCTP:additional_addresses |
By default, SCTP listen sockets will bind to the configured Like If |
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 |
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. |
|
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, |
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, |
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 |
integer, |
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 |
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 |
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 |
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 blacklisted 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. |
blacklist time in milliseconds |
300000 |
RFC3263:fallback_to_blacklist_address |
Specifies whether to fallback to sending to a blacklisted 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 blacklisted, 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 blacklist 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 |
|
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 |
Null or a profile table name. |
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" |
ResponseConfigurationPollTime |
The interval (ms) between scans of the response configuration profile tables. |
300,000 (5 minutes) |
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 |
|
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. |
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 |
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 2.7.0 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 |
4 |
BigGroup.max-pool-size |
The maximum number of threads in the Big Group thread pool. |
integer, |
50 |
BigGroup.queue-size |
The maximum number of waiting threads in the Big Group thread pool. |
integer, |
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, |
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 |
|
|
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, |
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. |
|
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) |