The Open Source SLEE and SIP Server

Mobicents Sip Servlets

Mobicents SIP Load Balancer

This page is obsolete : More detailed and better looking installation instructions are available from the Mobicents Sip Servlets User Guide


The Mobicents SIP Load Balancer is used to load balance SIP related services, in order to achieve performance scalability and high availability of the services.

The Mobicents SIP Load Balancer is a very simple proxy that is useful in SIP-based VoIP installations where there are multiple ingress proxy servers.

The Mobicents SIP Load Balancer permits pooling these servers, thereby eliminating the need to balance user demands for connectivity through a complicated provisioning algorithm.

All users can send their SIP request to the same SIP URI using the Load Balancer as outbound proxy and the Load Balancer will assign application server node to each call. In this way, the traffic load is balanced over a pool of application server nodes based on the real-time demand for services.

The Mobicents SIP Load Balancer will distribute requests across the healthy and available instances in cluster to increase throughput of the overall system. It can also fail-over mid-call requests from unhealthy/inaccessible instances to healthy and available instances.

The Load Balancer accepts instructions from application servers how and where to stick calls. For example, when The Load Balancer must work together with mod_jk, the routes are updated after every failover to the newly selected node.

More information can also be found in the Mobicents SIP High Availability and Clustering document .

We will now cover the Mobicents SIP Load Balancer implementation, configuration and an example below.


The Mobicents SIP Load Balancer receives SIP requests from endpoints on a port that is specified in a configuration file.

It then select nodes to serve the SIP requests through a round-robin algorithm for load-balancing picking up nodes from a list of Mobicents Sip Servlets nodes that is created at runtime. The different nodes are responsible for contacting the load balancer and sending to it heartbeats and health status.

It then forwards the SIP requests through a different port to the selected node.
It maintains stickiness of requests in a session to a single node as long as the serving node is healthy and available.

The Mobicents SIP Load Balancer adds itself to the Via header of requests to enable responses to return to the Mobicents SIP Balancer before being sent to orginating endpoint.
It also adds itself to the path of subsequent requests by adding record route headers. Thus it can handle mid call failover by forwarding subsequent requests to a different node in the cluster if the node that originally handled the initial request when down.

As said above, the different nodes are responsible for contacting the Mobicents Sip Load Balancer and sending to it liveness heartbeats and status health.

This has the following advantages compared to standard implementations where the Load Balancer is reponsible for pinging the cluster nodes :

  • Dynamic configuration of the nodes : Traditional SIP-based load balancers require explicit configuration of the nodes available. This has the downside ofnot being able to add new nodes on the fly to the cluster to respond to peaks of calls without updating manually the SIP Load Balancer. In Mobicents SIP Load Balancer, the bulk of the configuration resides on the application server nodes. The set of SIP load balancers to which an application server will communicate is determined by a static list. The application server relays lifecycle events (e.g. server startup/shutdown) to the load balancers allowing them to effectively auto-configure themselves. They also send keep alives to the Load Balancers so that if the application server crashes, the load balancer autmatically remove the node after receiving no keep alives from the node.
  • Server-side load balance factor calculation : In traditional SIP-based load balancers, the compputation of the load is done by the load balancer but the SIP Load Balancer only knows about the request that went through it. Thus if many SIP Load Balancers are used for the same cluster, the calculation will not be accurate at all. Also it doesn't take into account some other factors that can happen on the node itself such as CPU or Memory Consumption. The Mobicents SIP load Balance uses load balance factors calculated and provided by the application server nodes, rather than computing these in the load balancer. Consequently, it offers a more robust and accurate set of load metrics than is available from the load balancer.

To configure Mobicents Sip Servlets cluster node to contact the SIP Load Baalncer, this is done in extending the SipStandardService class which already extends the Tomcat StandardService class implementing the Tomcat Service interface.
In Tomcat's Architecture, a Service is an intermediate component which lives inside a Server and ties one or more Connectors to exactly one Engine.

So when the service is started the new SipStandardBalancerNodeService looks up its configuration and gather the address(es) of the Sip Balancer(s) and sends a heartbeat and health status to it(them) to make it(them)selves known as an available node of the cluster.

The different parameters of the node are configurable through its MBean interface, see Section below for more information on configuration.

Installation & Configuration

  • To be able to start a tomcat instance as a client node of the sip balancer(s), you need to follow first the instructions on how to setup your converged server (if that is not already done) and then modify your container's server.xml so that the Service tag attribute className is equals to org.mobicents.servlet.sip.startup.failover.SipStandardBalancerNodeService instead of org.mobicents.servlet.sip.startup.SipStandardService and add an attribute called balancers with the ip address(es) of the sip balancer you want to send heartbeats to.
  • As seen above, each node has a JMX interface to be easily configurable. It is available under serviceName=jboss.web,type=Service in the jmx-console and provides the following configurable properties :
    • balancers : the sip balancer(s) host names with the corresponding addBalancerAddress and removeBalancerAddress methods.
    • heartBeatInterval : the interval at which each heartbeat is sent to the sip balancer(s)
  • For configuring the complete converged Load Balancing architecture see read below "Converged Load-Balancing".

Step-By-Step Example

  • Take the balancer from the sip-balancer directory in the root of your Mobicents Sip Servlets distribuition (JBoss AS distros only)
  • Get the default load balancer configuration properties files
    • The first property in the file is the local IP Address (interface) where the Sip Balancer will listen for incoming requests
    • The second property in the file is the port where the Sip Balancer will listen for incoming requests from UA sip clients. (external port)
    • The third property in the file is the port from where the Sip Balancer will forward incoming requests to different nodes of the cluster. (local port)
    • the rest of the properties are jain sip stack properties that you can tune (refer to jain sip javadoc for SipStack and SipStackImpl classes to get more information on jain sip stack properties)
  • Fire up the sip balancer with following command java -jar sip-balancer-1.0-BETA4-jar-with-dependencies.jar (if you need to stop it just do Ctrl+C) :
  • Start 2 nodes either tomcat or jboss (or even a mix of them both but beware Tomcat nodes won't benefit from clustering since this advanced feature is available for JBoss only) with the above server.xml modified configuration. You can find an example for tomcat here and one for jboss here ; only the Service tag has been modified as compared to a standard version of Mobicents Sip Servlets. (make sure they don't listen on same port for http or sip connectors)
  • Deploy the same application, let's say location service on both nodes (you need to deploy the application manually on both nodes, when deployed on one node it won't deploy automatically in the whole cluster for now and don't forget to setup the dar file in the server.xml on both nodes neither)
  • Start a sip client with following sip address sip:sender@sip-servlets-com on port 5055, with outbound proxy the sip-balancer
  • Start a second sip client with following sip address on port 5090
  • From first sip client, start a call to Tear down the call when you're done
  • Redo it another, from first sip client, start a call to Tear down the call when you're done. The request should have been handled by the other node

Converged Load-Balancing

When you need to cluster your converged applications with HTTP and SIP, you can configure mod_jk and our SIP Balancer with your Mobicents distribution. Your HTTP and SIP session that belog to the same application session will be stuck to the same node. The SIP LB will follow the HTTP LB whenever there is a change. In order to configure the converged Load Balancer, all you need to do is to configure the apache mod_jk load-balancer with JBoss. To do this follow these instructions . To understand better, how it works you can see this diagram .


  • Currently, the HTTP, SIP and the Sip Application sessions are replicated and you can put references from one session to another safely, however the Servlet Contexts are not replicated, you should use a database of some other clustered storage (like JBoss Cache or memchache) if you need replication of servlet context - scoped data. Note that replication of the servlet context is against the HTTP servlet specifications and it is not certain when and how it will be implemented. We could replicate only a subset of the attributes.

Mobicents Sip Servlets