JBoss.orgCommunity Documentation
The SIP Stack used by the RA supports ESTABLISHED SIP DIALOG
failover. This means that an application must be in charge of properly adapting its state machine, to recover SIP transaction or early dialogs failures, once message retransmissions are received.
The RA can be used with Mobicents SIP Load Balancer. The recommended version is 1.0.BETA12.
There are three properties which define how the RA connects to Mobicents SIP Load Balancer:
the property must be configured with the list of load balancer IP address and internal ports. As an example, suppose a single Mobicents SIP Load Balancer is running with IP 192.168.0.1
and internal port 5065
, the property would be set with value 192.168.0.1:5065
. To specify multiple balancers use ;
as separator.
this property is optional, defines the class name of the HeartBeating service implementation, currently the only one available is org.mobicents.ha.javax.sip.LoadBalancerHeartBeatingServiceImpl
this property is optional, defines the class of the load balancer elector from JAIN SIP HA Stack. The elector is used to define which load balancer will receive outgoing requests, which are out of dialog or in dialog with null state. Currently only one elector implementation is available, org.mobicents.ha.javax.sip.RoundRobinLoadBalancerElector
, which, as the class name says, uses round robin algorythm to select the balancer.
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.
All User Agents send SIP messages, such as INVITE
and MESSAGE
, to the same SIP URI (the IP address and port number of the SIP load balancer on the WAN). The load balancer then parses, alters, and forwards those messages to an available node in the cluster. If the message was sent as a part of an existing SIP session, it will be forwarded to the cluster node which processed that User Agent's original transaction request.
The SIP RA that receives the message acts upon it and sends a response back to the SIP load balancer. The SIP load balancer reparses, alters and forwards the message back to the original User Agent. This entire proxying and provisioning process is carried out independent of the User Agent, which is only concerned with the SIP service or application it is using.
By using the load balancer, SIP traffic is balanced across a pool of available SIP RAs, increasing the overall throughput of the SIP service or application running on either individual nodes of the cluster.
The SIP load balancer is also able to fail over requests mid-call from unavailable nodes to available ones, thus increasing the reliability of the SIP service or application. The load balancer increases throughput and reliability by dynamically provisioning SIP service requests and responses across responsive nodes in a cluster. This enables SIP applications to meet the real-time demand for SIP services.
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 following is a list of the built-in algorithms:
This algorithm does not support distributed use case. It selects nodes randomly to serve a give Call-ID extracted from the requests and responses. It keeps a map with Call-ID -> nodeId
associations and this map is not shared with other load balancers which will cause them to make different decisions.
This algorithm can be used in distributed load balancer configurations. It extracts the hash value of specific headers from SIP messages to decide which application server node will handle the request. Information about the options in this algorithms is available in the balancer configuration file comments.
This algorithm can be used in distributed load balancer configurations. It is similar to the previous algorithm, but it attempts to keep session affinity even when the cluster nodes are removed or added, which would normally cause hash values to point to different nodes.
When the capacity of a single load balancer is exceeded, multiple load balancers can be used. With the help of an IP load balancer the traffic can be distributed between all SIP load balancers based on some IP rules or round-robin. With consistent hash and jvmRoute
-based balancer algorithms it doesn't matter which SIP load balancer will process the request, because they would all make the same decisions based on information in the requests (headers, parameters or cookies) and the list of available nodes. With consistent hash algorithms there is no state to be preserved in the SIP balancers.
Each individual Mobicents JAIN SLEE SIP RA in the cluster is responsible for contacting the SIP load balancer and relaying its health status and regular "heartbeats".
From these health status reports and heartbeats, the SIP load balancer creates and maintains a list of all available and healthy nodes in the cluster. The load balancer forwards SIP requests between these cluster nodes, providing that the provisioning algorithm reports that each node is healthy and is still sending heartbeats.
If an abnormality is detected, the SIP load balancer removes the unhealthy or unresponsive node from the list of available nodes. In addition, mid-session and mid-call messages are failed over to a healthy node.
The SIP load balancer first receives SIP requests from endpoints on a port that is specified in its Configuration Properties configuration file. The SIP load balancer, using a round-robin algorithm, then selects a node to which it forwards the SIP requests. The load balancer forwards all same-session requests to the first node selected to initiate the session, providing that the node is healthy and available.
The Mobicents SIP load balancer appends itself to the Via
header of each request, so that returned responses are sent to the SIP Balancer before they are sent to the originating endpoint.
The load balancer also adds itself to the path of subsequent requests by adding Record-Route headers. It can subsequently handle mid-call failover by forwarding requests to a different node in the cluster if the node that originally handled the request fails or becomes unavailable. The SIP load balancer immediately fails over if it receives and unhealthy status, or irregular heartbeats from a node.
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:
Local IP address, or interface, on which the SIP load balancer will listen for incoming requests.
Port on which the SIP load balancer listens for incoming requests from SIP User Agents.
Port on which the SIP load balancer forwards incoming requests to available, and healthy, SIP Servlets Server cluster nodes.
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.
Transport protocol for the internal SIP connections associated with the internal SIP port of the load balancer. Possible choices are UDP
, TCP
and TLS
.
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.
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.
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.
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.
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.
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.
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.
The remaining keys and properties in the configuration properties file can be used to tune the JAIN SIP stack, but are not specifically required for load balancing. To assist with tuning, a comprehensive list of implementing classes for the SIP Stack is available from the Interface SIP Stack page on nist.gov. For a comprehensive list of properties associated with the SIP Stack implementation, refer to Class SipStackImpl page on nist.gov.
Start the SIP load balancer, ensuring the Configuration Properties file (lb.properties
in this example) is specified. In the Unix terminal, or using the Windows Command Prompt, the SIP Load Balancer is started by issuing a command similar to this one:
java -jar sip-balancer-1.0.BETA12-jar-with-dependencies.jar -mobicents-balancer-config=lb-configuration.properties
Executing the SIP load balancer produces output similar to the following example:
[user]$ java -jar sip-balancer-1.0.BETA12-jar-with-dependencies.jar -mobicents-balancer-config=lb-configuration.properties Oct 21, 2008 1:10:58 AM org.mobicents.tools.sip.balancer.SIPBalancerForwarder start INFO: Sip Balancer started on address 127.0.0.1, external port : 5060, port : 5065 Oct 21, 2008 1:10:59 AM org.mobicents.tools.sip.balancer.NodeRegisterImpl startServer INFO: Node registry starting... Oct 21, 2008 1:10:59 AM org.mobicents.tools.sip.balancer.NodeRegisterImpl startServer INFO: Node expiration task created Oct 21, 2008 1:10:59 AM org.mobicents.tools.sip.balancer.NodeRegisterImpl startServer INFO: Node registry started
The output shows the IP address on which the SIP load balancer is listening, as well as the external and internal listener ports.
Assuming that you started the load balancer as a foreground process in the OS terminal, the easiest way to stop it is by pressing the Ctrl+C key combination in the same terminal in which you started it.
This should produce similar output to the following:
^COct 21, 2008 1:11:57 AM org.mobicents.tools.sip.balancer.SipBalancerShutdownHook run INFO: Stopping the sip forwarder