SIP Resource Adaptor Guide

Other documentation for the SIP Resource Adaptor including the changelog and links to the API JavaDoc and downloads, can be found on the SIP Resource Adaptor product page.

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.

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

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

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.

When a SIP RA entity is created in a Rhino cluster, each cluster node creates an instance of a SIP RA object. Each SIP RA instance will bind to the local IP interfaces on its node.

Each node has its own unique IP address. Rhino does not provide any form of IP address failover or load balancing. An external load balancer must be used if it is necessary to present a single virtual IP address for the cluster.

Activities, such as transactions and dialogs, created by the SIP RA instances on each node are local to each node. If a node fails, all SIP activities on the node will be lost, but the SIP RAs and services on other nodes can continue running, providing high availability of services.

It is possible to use replicated dialog activities. These are disabled by default. If enabled, replicated dialog activities, and service instances that are attached to them, can continue on other nodes after a failure, providing some level of fault tolerance.

In the default configuration, the SIP RA cannot be deployed in a cluster where multiple nodes are running on the same host. This is because each RA instance will try to bind to the same SIP port, and the OS will not allow this if they are on the same host.

This can be resolved by specifying two additional configuration properties when deploying the RA: OffsetPorts=true and PortOffset=<LowestNodeID>.

These properties tell the RA to add an offset to the SIP port used on each node, so that each node will use a unique port number. For example, if the RA is configured with Port=5060, and the cluster has nodes with node IDs 101, 102, and 103, and PortOffset=101, the SIP ports used by the three nodes will be 5060, 5061, and 5062 respectively.

If the SIP RA is deployed in a cluster behind an IP load balancer, the load balancer typically provides a virtual IP address (VIP) that external hosts use to connect to the cluster. The SIP RA has an optional VirtualAddresses configuration property, which specifies a list of hostnames or VIPs that the cluster is known by. This allows the SIP RA to detect when a SIP URI or hostname should be treated as a local address, if it matches a virtual address for the cluster. See network address properties.

SBB programming considerations include location independence and helper methods.

The SIP RA’s forking support follows this basic model, and only applies if the application is using dialog activities.

When sending an initial dialog-creating request, the UAC SBB should attach to the original dialog activity. If a forked response arrives that creates a new dialog, the SIP RA will fire an event on the original dialog activity, so that the SBB can know that there is a new dialog activity. The event object is a DialogForkedEvent.

The SBB can get a reference to the new dialog activity by calling DialogForkedEvent.getNewDialog(). The SBB can attach to the new activity and send requests on it.

If a 2xx response arrives on any early dialog, the RA will fire the normal response event. If a 2xx response arrives with a different To-tag to any early dialog, the RA will fire another DialogForkedEvent. All other early dialogs will be ended.

Any late 2xx responses with different To-tags will be dropped. In this case the SIP RA will send an ACK then a BYE to tear down this forked dialog at the server. Late 2xx responses are not passed up to the SBB.

UAS applications typically do not fork; however if the application is a back-to-back user agent (B2BUA), then it may need to create multiple server dialogs to correspond to the client dialogs created in the UAC procedures above. This is essential if the application needs to receive mid-dialog requests while the dialogs are in the Early state.

The JAIN SIP resource adaptor type defines the method SleeSipProvider.forwardForkedResponse(). This method should be called when the UAS forwards a dialog-creating response with a different To-tag to the original dialog. This method will forward the response upstream, and return a new dialog activity. The application can attach to the forked dialog activity in order to receive any mid-dialog requests on the dialog.

The dialog activity contains a reference to the original server transaction. When a final response is sent on the transaction, or by passing a 2xx response to SleeSipProvider.forwardForkedResponse(), all other early dialog activities will end automatically.

The B2BUA example application handles forking events and the multiple client and server dialogs that may be created.

Critical headers such as Call-ID, CSeq, and Via will always be parsed by the RA, as these are essential to correct operation of the protocol. However most other headers need not be parsed at all until accessed by an application. This is a performance benefit, and can also aid interoperability with user agents that may not strictly follow SIP syntax.

If an application calls Message.getHeader(), and the RA is unable to parse the header, a LazyParsingException will be thrown. This is an unchecked exception. In this case, an application might want to get the unparsed header value so that it can parse the header itself. This might be required when communicating with a user agent that is known to have bugs in SIP syntax.

An application can retrieve the unparsed value of a header by casting the Message object to a LazyParsedMessage, and calling getUnparsedHeaderValue(). This returns the string value of the header, which the application can parse itself. If the header is a multi-value header, the getUnparsedHeaderValues() method should be used, which returns an array of strings.

The SIP RA has been enhanced to support this draft RFC. This page describe the procedures that must be used on the client and server sides to setup and maintain persistent connections through a firewall.

The SIP RA implements the JAIN SIP 1.2 API. The JAIN SIP API does not have any notion of "connections", so applications cannot manipulate a connection object. The support for the draft RFC has been implemented so that applications still use the JAIN SIP API, and connections are setup and torn down using specially-formed REGISTER requests, as described below.

Below is a summary of persistent outbound connection procedures at the client.

Below is a summary of persistent outbound connection procedures at the server.

The following JVM system properties may be set to alter the default persistent outbound connection behaviour.

When a SIP client sends a request, it must select either the first Route header’s URI, if present, or the Request-URI. This URI determines where the request is sent to (the next-hop address). This URI might only contain a domain name, such as sip:bob@example.com. RFC 3263 DNS procedures are required to convert the URI into the address, port, and transport protocol of an actual SIP server (or servers).

At a high level there are three parts to the RFC 3263 DNS process. Some of these may be skipped depending on what information is already given in the URI, such as transport, IP address, or port numbers. Here is a simplified description of the process that applies to any SIP client using RFC 3263.

At the end of this process the SIP client has a list of (address, port, transport) tuples to try. If the list is empty then the request cannot be routed and will fail. Otherwise, the client picks the first address in the list and starts a client transaction. The next backup address will be tried if the transaction fails for any of these reasons:

When such a failure occurs, the client selects the next address and tries again with a new client transaction. If all addresses failed, then the client must fail the request.

The SIP RA closely follows the RFC 3263 procedures but with some adaptations, described below.

At the client, this feature performs these procedures:

At the server, this feature performs these procedures:

The following SIP properties (sip.properties) must be set to alter the default persistent outbound connection behaviour.

The following JVM system properties must be set to alter the behaviour between RFC 5626 and draft-ietf-sip-outbound-03.

When a dialog activity is created, the dialog activity state is initially local to the calling node. When the dialog transitions to the "confirmed" state (that is, a 2xx response is sent or received on the initial transaction), the SIP RA replicates the dialog state to all nodes, using Rhino’s built-in memory database. From this point on, the dialog activity state is available to all nodes.

If a node fails, any dialogs that it created can continue on other nodes. If another node receives a request for a dialog it has not seen before, it will check the replicated state and continue processing the request as an in-dialog request. Any SBB entities that were attached to the dialog activity context will be able to receive the request. This assumes that the SIP client is able to detect the node failure and send future requests to a different node. This can be achieved using a load balancer or DNS SRV records, for example.

The performance of FT dialogs will be slower due to the replication and transaction cost. Updates to replicated dialog activity state are performed transactionally, and require a distributed lock to be acquired by the node updating dialog state. For this reason the latency will be larger than when using non-replicated dialogs.

The example B2BUA service supports the use of replicated dialogs. To deploy a fully replicated B2BUA, ensure that the RA is deployed with the ReplicatedDialogSupport=true property (see Configuration), and also set the B2BUA_REPLICATED property in sip.properties to True. The latter ensures that Rhino deploys the B2BUA service as a replicated service, so that SBB CMP state is replicated as well.

Stream Control Transmission Protocol (SCTP)) is a transport protocol designed for call-control signaling . Like TCP, it provides reliable, ordered, end-to-end delivery of messages, but has many features that make it better than TCP for some applications. The main benefits of using SCTP for SIP are:

The SIP RA follows RFC 4168 when sending and receiving messages:

The SIP RA’s SCTP implementation requires Java Standard Edition 7, running on Linux 2.6 or Solaris 10 (or later versions of the same).

In addition, on Linux the lksctp-tools package must be installed.

The SIP RA’s SCTP support uses the Java SCTP API, via the Netty library.

Below are instructions to configure the SIP RA, and send requests, and responses over SCTP.

Session timers are disabled by default. An application that wants to use session timers must request them when creating dialog activities.

The session timer for a new dialog is configured using a SessionTimerOptions value. This value contains the mandatory session interval parameter, which is the time in seconds after which the dialog (session) is considered to have expired, if there were no session refresh requests sent or received in that time. RFC 4028 defines how the two parties on a dialog can negotiate the session interval, but it must always be at least 90 seconds.

A session refresh request is any re-INVITE or UPDATE sent on the dialog. If a session refresh request is successful, this means that both parties on the dialog are still alive, so the session timer is reset and the dialog can continue. If a session refresh request times out, or fails with 481 (dialog does not exist), then the application should terminate the dialog.

During dialog setup, one party on the dialog is selected to be the refresher, who must send a session refresh request periodically. An application can indicate its preferred refresher in its SessionTimerOptions, but this may not be applied, for example if the other party does not support session timers.

If a dialog activity in the SIP RA was selected to be the refresher, then periodically the SIP RA will fire a SessionRefreshRequiredEvent on the dialog, which tells the application that it should initiate a session refresh request. If this request fails with a timeout or 481 response then the application should terminate the dialog with a BYE.

Regardless of who is selected to be the refresher, any successful re-INVITE or UPDATE on the dialog is implicitly a session refresh request, and resets the session timer automatically so the dialog may continue.

If there were no successful session refreshes within the session interval, then the SIP RA considers the dialog to be expired, and fires a SessionExpiredEvent. The application must then terminate the dialog by sending a BYE request.

To request the use of a session timer for a dialog, the application must pass in a SessionTimerOptions value when creating the dialog, before sending or responding to the initial request.

The dialog must be created using a dialog builder from OCSleeSipProvider.newDialogBuilder(). This lets you specify SessionTimerOptions in addition to other dialog options. For example:

The session timer is activated when a successful response to the initial INVITE is sent or received. If the initial INVITE is not successful, then the dialog is not created and no session timer is started.

The session timer state of a dialog activity can be queried using SessionTimerDialog.getSessionTimer(). SessionTimerDialog is a subclass of Dialog, and any dialog activity object may be safely type cast to this type.

The SessionTimer interface shows whether the timer is active or expired, and also shows the dialog’s currently applied SessionTimerOptions.

Once the dialog has been setup successfully, a session expiry timer is started using the session interval negotiated by the initial INVITE transaction. Session refresh requests must now be sent periodically to reset the expiry timer and keep the session alive. The party selected to be the refresher will do this at regular intervals if there has been no other activity, but either party may send a session refresh request at any time.

If there were no successful session refresh requests sent or received within the session interval, the dialog’s session expiry timer will fire, causing a SessionExpiredEvent to be fired on the dialog activity.

The application processing the SessionExpiredEvent should terminate the dialog by sending a BYE. Again this is not done automatically by the RA, so that the application can control how it cleans up its resources.

If no SBB processed the SessionExpiredEvent, the RA will automatically send a BYE. This avoids dialogs leaking if no service was active or able to process the event.

Applications that need to forward messages between dialogs, such as B2BUAs, might just want to pass all messages through without directly taking part in session timer negotiation and refreshing. But it would still be useful if the application could be notified when a session expired, if the endpoints were using session timers.

This is what proxy mode is used for. In proxy mode, a dialog does not need to configure any session timer options. Instead it observes the session interval negotiated by the endpoints on the dialog, and starts a session expiry timer.

The dialog does not initiate any session refresh requests on its own. It observes all session refresh requests that pass through, and resets the expiry timer when a refresh succeeds.

If neither endpoint sends a successful session refresh within the session interval, a SessionExpiredEvent is fired so the application can clean up the expired dialog.

When SIP dialog replication is enabled (using the ReplicatedDialogSupport=true config property), session timers are replicated as well so they can recover from a node failure.

In a Rhino cluster, session timer refresh and expiry events will be fired on the same node that created the dialog activity.

If a node fails, its dialogs are automatically taken over by surviving nodes in the cluster. When a dialog is recovered on a surviving node, any session timers for that dialog are recovered as well, and will now fire on the surviving node at the expected time.

Subsequent session timer refresh and expiry events for the dialog activity will now fire on the node that took over that dialog.

The SIP RA’s session timer support adds one new configuration property: SessionTimer:default_refresher.

This is only required when a UAS has to select the refresher for a dialog, because the UAC did not specify one, and the UAS application did not set a refresher in its SessionTimerOptions for the dialog. In this case the SessionTimer:default_refresher property is used so the UAS can decide.

All other session timer parameters are configured by the application for each dialog, using the appropriate SessionTimerOptions values.

To use session timers, an application must:

In the previous resource adaptor type, the SBB RA interface was OCSipResourceAdaptorSbbInterface. This interface has been replaced by SleeSipProvider in the standard JAIN SIP 1.2 resource adaptor types.

This extends axref:jain-sip-api/javax.sip.SipProvider, and provides methods for accessing the JAIN SIP factory objects.

To access OpenCloud-specific features and headers, the OCSIP resource adaptor types can be used. This provides the OCSleeSipProvider interface, which extends SleeSipProvider.

Applications written using the previous resource adaptor type must replace all references to OCSipResourceAdaptorSbbInterface with SleeSipProvider or OCSleeSipProvider.

All event type IDs have been changed in the new resource adaptor type. All events in the JAIN SIP resource adaptor types have the vendor net.java.slee (denoting the JAIN SLEE community) and version 1.2.

Consult the table in the JAIN SIP 1.2 RA Type API to see the complete list of events.

Users of OpenCloud-specific events should also check the event table in the OCSIP 2.5 RA Type API.