JBoss.orgCommunity Documentation

Mobicents JAIN SLEE SIP11 Resource Adaptor User Guide

by Bartosz Baranowski and Eduardo Martins

Abstract

Mobicents JAIN SLEE SIP11 Resource Adaptor (RA) is the JAIN SLEE 1.1 RA for the SIP Protocol, used in Mobicents JAIN SLEE platform.

The RA implements the Resource Adaptor Type defined by Appendix D of the JAIN SLEE 1.1 Specification, and provides high performance and fail over support.


This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:

The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.

Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:

The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.

Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main menu bar' approach.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in the the Issue Tracker, against the product Mobicents JAIN SLEE SIP11 Resource Adaptor, or contact the authors.

When submitting a bug report, be sure to mention the manual's identifier: JAIN_SLEE_SIP11_RA_User_Guide

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

The RA implementation uses the Mobicents JAIN SIP HA stack, an extension of the JAIN SIP Reference Implementation which provides high availability and fault tolerance. The stack is the result of the work done by Mobicents JAIN SLEE and SIP Servlets development teams, and source code is provided in all releases.

There is a single Resource Adaptor Entity created when deploying the Resource Adaptor, named SipRA. The SipRA entity uses the default Resource Adaptor configuration, specified in Section 3.1, “Configuration”.

The SipRA entity is also bound to Resource Adaptor Link Name SipRA, to use it in an Sbb add the following XML to its descriptor:



    
    <resource-adaptor-type-binding>
        
        <resource-adaptor-type-ref>
            <resource-adaptor-type-name>
                JAIN SIP
            </resource-adaptor-type-name>
            <resource-adaptor-type-vendor>
                javax.sip
            </resource-adaptor-type-vendor>
            <resource-adaptor-type-version>
                1.2
            </resource-adaptor-type-version>
        </resource-adaptor-type-ref>
        
        <activity-context-interface-factory-name>
            slee/resources/jainsip/1.2/acifactory
        </activity-context-interface-factory-name>
        
        <resource-adaptor-entity-binding>
            <resource-adaptor-object-name>
                slee/resources/jainsip/1.2/provider
            </resource-adaptor-object-name>
            <resource-adaptor-entity-link>
                SipRA
            </resource-adaptor-entity-link>
        </resource-adaptor-entity-binding>
        
    </resource-adaptor-type-binding>
    
    
    

  1. Downloading the source code

    Use SVN to checkout a specific release source, the base URL is http://mobicents.googlecode.com/svn/tags/servers/jain-slee/2.x.y/resources/sip11, then add the specific release version, lets consider 2.0.0.CR1.

    [usr]$ svn co http://mobicents.googlecode.com/svn/tags/servers/jain-slee/2.x.y/resources/sip11/2.0.0.CR1 slee-ra-sip11-2.0.0.CR1
  2. Building the source code

    Important

    Maven 2.0.9 (or higher) is used to build the release. Instructions for using Maven2, including install, can be found at http://maven.apache.org

    Use Ant to build the binary.

    [usr]$ cd slee-ra-sip11-2.0.0.CR1
    [usr]$ mvn install
    				    

    Once the process finishes you should have the deployable-unit jar file in the target directory, if Mobicents JAIN SLEE is installed and environment variable JBOSS_HOME is pointing to its underlying JBoss Application Server directory, then the deployable unit jar will also be deployed in the container.

Similar process as for Section 4.2.1, “Release Source Code Building”, the only change is the SVN source code URL, which is http://mobicents.googlecode.com/svn/trunk/servers/jain-slee/resources/sip11.

The RA can be used with Mobicents SIP Load Balancer. The recommended version is 1.0.BETA12.

The Mobicents SIP load balancer is used to balance the load of SIP service requests and responses between nodes in a JAIN SLEE cluster, increasing the performance and availability of SIP services and applications.

In terms of functionality, the Mobicents SIP Load Balancer is a simple stateless proxy server that intelligently forwards SIP session requests and responses between User Agents (UAs) on a Wide Area Network (WAN), and SIP RA nodes, which are almost always located on a Local Area Network (LAN). All SIP requests and responses pass through the SIP load balancer.

The SIP load balancer exposes an interface to allow users to customize the routing decision algorithm. Only one algorithm is active at any time and it is specified with the algorithmClass property in the configuration file.

It is completely up to the algorithm how and whether to support distributed architecture or how to store the information needed for session affinity. The algorithms will be called for every SIP request and other significant events to make proper routing decisions.

The load balancer can be downloaded from http://repository.jboss.org/maven2/org/mobicents/tools/sip-balancer/1.0.BETA12. There you will find the balancer's executable jar with dependencies ( sip-balancer-1.0.BETA12-jar-with-dependencies.jar ) , along with javadocs and sources jars.

Configuration is done through a properties file which path is then passed as argument. Below is a configuration properties file example:

# The binding address of the load balancer
host=127.0.0.1

# The RMI port used for heartbeat signals
rmiRegistryPort=2000

# The SIP port used where client should connect
externalPort=5060
 
# The SIP port from where servers will receive messages
# delete if you want to use only one port for both inbound and outbound)
# if you like to activate the integrated HTTP load balancer, this is the entry point
internalPort=5065
 
# The HTTP port for HTTP forwarding
httpPort=2080

#Specify UDP or TCP (for now both must be the same)
internalTransport=UDP
externalTransport=UDP

# If you are using IP load balancer, put the IP address and port here
#externalIpLoadBalancerAddress=127.0.0.1
#externalIpLoadBalancerPort=111
 
# Requests initited from the App Servers can route to this address (if you are using 2 IP load balancers for bidirectional SIP LB)
#internalIpLoadBalancerAddress=127.0.0.1
#internalIpLoadBalancerPort=111

# Designate extra IP addresses as serer nodes
#extraServerNodes=222.221.21.12:21,45.6.6.7:9003,33.5.6.7,33.9.9.2

# Call-ID affinity algortihm settings. This algorithm is the default. No need to uncomment it.
#algorithmClass=org.mobicents.tools.sip.balancer.CallIDAffinityBalancerAlgorithm
# This property specifies how much time to keep an association before being evitcted.
# It is needed to avoid memory leaks on dead calls. The time is in seconds.
#callIdAffinityMaxTimeInCache=500

# Uncomment to enable the consistent hash based on Call-ID algorithm.
#algorithmClass=org.mobicents.tools.sip.balancer.HeaderConsistentHashBalancerAlgorithm
# This property is not required, it defaults to Call-ID if not set, cna be "from.user" or "to.user" when you want the SIP URI username
#sipHeaderAffinityKey=Call-ID
#specify the GET HTTP parameter to be used as hash key
#httpAffinityKey=appsession
 
# Uncomment to enable the persistent consistent hash based on Call-ID algorithm.
#algorithmClass=org.mobicents.tools.sip.balancer.PersistentConsistentHashBalancerAlgorithm
# This property is not required, it defaults to Call-ID if not set
#sipHeaderAffinityKey=Call-ID
#specify the GET HTTP parameter to be used as hash key
#httpAffinityKey=appsession
 
#This is the JBoss Cache 3.1 configuration file (with jgroups), if not specified it will use default
#persistentConsistentHashCacheConfiguration=/home/config.xml
 
# Call-ID affinity algortihm settings. This algorithm is the default. No need to uncomment it.
#algorithmClass=org.mobicents.tools.sip.balancer.CallIDAffinityBalancerAlgorithm
# This property specifies how much time to keep an association before being evitcted.
# It is needed to avoid memory leaks on dead calls. The time is in seconds.
#callIdAffinityMaxTimeInCache=500

# Uncomment to enable the consistent hash based on Call-ID algorithm.
#algorithmClass=org.mobicents.tools.sip.balancer.HeaderConsistentHashBalancerAlgorithm
# This property is not required, it defaults to Call-ID if not set, cna be "from.user" or "to.user" when you want the SIP URI username
#sipHeaderAffinityKey=Call-ID
#specify the GET HTTP parameter to be used as hash key
#httpAffinityKey=appsession

# Uncomment to enable the persistent consistent hash based on Call-ID algorithm.
#algorithmClass=org.mobicents.tools.sip.balancer.PersistentConsistentHashBalancerAlgorithm
# This property is not required, it defaults to Call-ID if not set
#sipHeaderAffinityKey=Call-ID
#specify the GET HTTP parameter to be used as hash key
#httpAffinityKey=appsession
 
#This is the JBoss Cache 3.1 configuration file (with jgroups), if not specified it will use default
#persistentConsistentHashCacheConfiguration=/home/config.xml

#JSIP stack configuration.....
javax.sip.STACK_NAME = SipBalancerForwarder
javax.sip.AUTOMATIC_DIALOG_SUPPORT = off
// You need 16 for logging traces. 32 for debug + traces.
// Your code will limp at 32 but it is best for debugging.
gov.nist.javax.sip.TRACE_LEVEL = 32
gov.nist.javax.sip.DEBUG_LOG = logs/sipbalancerforwarderdebug.txt
gov.nist.javax.sip.SERVER_LOG = logs/sipbalancerforwarder.xml
gov.nist.javax.sip.THREAD_POOL_SIZE = 64
gov.nist.javax.sip.REENTRANT_LISTENER = true

            		

An overview of most important properties:

host

Local IP address, or interface, on which the SIP load balancer will listen for incoming requests.

externalPort

Port on which the SIP load balancer listens for incoming requests from SIP User Agents.

internalPort

Port on which the SIP load balancer forwards incoming requests to available, and healthy, SIP Servlets Server cluster nodes.

rmiRegistryPort

Port on which the SIP load balancer will establish the RMI heartbeat connection to the application servers. When this connection fails or a disconnection instruction is received, an application server node is removed and handling of requests continues without it by redirecting the load to the lie nodes.

internalTransport

Transport protocol for the internal SIP connections associated with the internal SIP port of the load balancer. Possible choices are UDP, TCP and TLS.

externalTransport

Transport protocol for the external SIP connections associated with the external SIP port of the load balancer. Possible choices are UDP, TCP and TLS. It must match the transport of the internal port.

externalIpLoadBalancerAddress

Address of the IP load balancer (if any) used for incoming requests to be distributed in the direction of the application server nodes. This address may be used by the SIP load balancer to be put in SIP headers where the external address of the SIP load balancer is needed.

externalIpLoadBalancerPort

The port of the external IP load balancer. Any messages arriving at this port should be distributed across the external SIP ports of a set of SIP load balancers.

internalIpLoadBalancerAddresst

Address of the IP load balancer (if any) used for outgoing requests (requests initiated from the servers) to be distributed in the direction of the clients. This address may be used by the SIP load balancer to be put in SIP headers where the internal address of the SIP load balancer is needed.

internalIpLoadBalancerPort

The port of the internal IP load balancer. Any messages arriving at this port should be distributed across the internal SIP ports of a set of SIP load balancers.

extraServerNodes

Comma-separated list of hosts that are server nodes. You can put here alternative names of the application servers and they will be recognized. Names are important, because they might be used for direction-analysis. Requests coming from these server will go in the direction of the clients and will not be routed back to the cluster.

algorithmClass

The fully-qualified Java class name of the balancing algorithm to be used. There are three algorithms to choose from and you can write your own to implement more complex routing behaviour. Refer to the sample configuration file for details about the available options for each algorithm. Each algorithm can have algorithm-specific properties for fine-grained configuration.

Revision History
Revision 1.0Tue Dec 30 2009Eduardo Martins
Creation of the Mobicents JAIN SLEE SIP11 RA User Guide.