Procedure 5.1. Configuring the Mobicents SIP Load Balancer and SIP Server Nodes

1. Configure lb.properties Configuration Properties File

   Configure the SIP Load Balancer’s Configuration Properties file by substituting valid values for your personal setup.Example 5.1, “Complete Sample lb.properties File” shows a sample lb.properties file, with key element descriptions provided after the example. The lines beginning with the pound sign are comments.

   Example 5.1. Complete Sample lb.properties File

   # Mobicents Load Balancer Settings
   # For an overview of the Mobicents  Load Balancer visit 
   # http://docs.google.com/present/view?id=dc5jp5vx_89cxdvtxcm
   # The Load balancer will listen for both TCP and UDP connections
   
   
   
   # The binding address of the load balancer. This also specifies the 
   # default value for both internalHost and externalHost if not specified separately.
   host=127.0.0.1
   
   # The binding address of the load balancer where clients should connect (if the host property is not specified)
   #externalHost=127.0.0.1
   
   # The SIP port from where servers will receive messages
   # delete if you want to use only one port for both inbound and outbound)
   internalPort=5065
   
   # The SIP port used where clients should connect
   externalPort=5060
   
   # The binding address of the load balancer where SIP application servers should connect (if the host property is not specified)
   #internalHost=127.0.0.1
   
   # The RMI port used for heartbeat signals
   rmiRegistryPort=2000
   
   # The HTTP port for HTTP forwarding
   # if you like to activate the integrated HTTP load balancer, this is the entry point
   httpPort=2080
   #If no nodes are active the LB can redirect the traffic to the unavailableHost specified in this property,
   #otherwise, it will return 503 Service Unavailable
   #unavailableHost=google.com
   
   # 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
   
   # The addresses in the SIP LB Via headers can be either the real addresses or those specified in the external and internal IP LB addresses
   useIpLoadBalancerAddressInViaHeaders=false
   
   # 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
   #The following attribute specified the policy after failover. If set to true all calls from the failed node
   #will go to a new healthy node (all calls to the same node). If set to false the calls will go to random new nodes.
   #callIdAffinityGroupFailover=false
   
   # 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
   
   
   #If a node doesnt check in within that time (in ms), it is considered dead
   nodeTimeout=5100
   #The consistency of the above condition is checked every heartbeatInterval milliseconds
   heartbeatInterval=150
   
   
   #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 = 0
   
   // Specify if message contents should be logged.
   gov.nist.javax.sip.LOG_MESSAGE_CONTENT=false
   
   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

    

   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 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.

   httpPort

   Port on which the SIP load balancer will accept HTTP requests to be distributed across the 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 here 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.

   nodeTimeout

   In milliseonds. Default value is 5100. If a server node doesnt check in within this time (in ms), it is considered dead.

   heartbeatInterval

   In milliseconds. Default value is 150 milliseonds. The hearbeat interval must be much smaller than the interval specified in the JAIN SIP property on the server machines – org.mobicents.ha.javax.sip.HEARTBEAT_INTERVAL

   Note

   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.

2. Configure logging

   The SIP load balancer uses Log4J as a logging mechanism. You can configure it through the typical log4j xml configuration file and specify the path as follows -DlogConfigFile=./log4j.xml. Please refer to Log4J documentation for more information on how to configure the logging. A shortcut exists if you want to switch between INFO/DEBUG/WARN logging levels. The JVM option -DlogLevel=DEBUG will allow you to switch all loggig categories to the specified log level.

3. Configure the container configuration file

   Ensure the following attributes are configured for the <service> element in server.xml for Tomcat or in the mobicents subsystem element for JBoss AS7.

   • The sipPathName attribute must contain the following value org.mobicents.ha.balancing.only to indicate that the server will be using the Mobicents JAIN SIP HA SIP Stack which is an extension of the JAIN SIP Stack offering integration with the Mobicents Load Balancer and transparent replication.

4. Configure the mss-sip-stack.properties configuration file

   • The org.mobicents.ha.javax.sip.cache.MobicentsSipCache.cacheName property must contain the name of the cache that will be responsible for holding the replicated data of the SIP Stack layer (namely the established SIP dialog data). The value has to be one of the cache name present in the jboss-cache-manager-jboss-beans.xml file of the jboss-cache-manager JBoss Service of the container. The default value is standard-session-cache
   • The org.mobicents.ha.javax.sip.BALANCERS property must be configured with the list of load balancer IP address and internal ports. As an example, suppose a single 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. If this property is used the balancers attribute located in server.xml should not be used as it is a replacement for it.
   • The org.mobicents.ha.javax.sip.LoadBalancerHeartBeatingServiceClassName property is optional, it defines the class name of the HeartBeating service implementation, currently the only one available isorg.mobicents.ha.javax.sip.LoadBalancerHeartBeatingServiceImpl
   • The org.mobicents.ha.javax.sip.LoadBalancerElector property is optional, it 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.