Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
<?xml version='1.0' encoding='UTF-8'?>
<!-- This document was created with Syntext Serna Free. -->
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "SIP_Balancer_User_Guide.ent">
%BOOK_ENTITIES;
]>
<!-- chapter id nickname: sslb -->
<chapter id="sslb-MSS_Load_Balancer">
<title>Load Balancer</title>
<!--Removed star network image because it's also in the introductory section,
and jdocbook can't shrink it or align the caption -->
<figure>
<title>Star Cluster Topology.</title>
<mediaobject id="sslb-mss-MSSSIPLoadBalancer-dia-StarNetworkTopology">
<imageobject>
<imagedata width="440"
fileref="images/mss-MSSSIPLoadBalancer-dia-StarNetworkTopology.jpg"
format="JPG" />
</imageobject>
</mediaobject>
</figure>
<para>The
SIP Load Balancer is used to balance the load of SIP service requests
and responses between nodes in a SIP Server cluster, such as &PLATFORM_NAME;
JAIN SLEE or SIP Servlets. Both &SHORT_PLATFORM_NAME;
servers can be used in conjunction with the SIP Load Balancer to
increase the performance and availability of SIP services and
applications.
</para>
<para>In terms of functionality, the 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 Server nodes, which are almost always located
on a Local Area Network (LAN). All SIP requests and responses pass
through the SIP Load Balancer.</para>
<para>
Starting with the 7.0.0.GA release, SIP Load Balancer can handle
WebSocket requests supporting up to version 13 of the wire protocol -
RFC 6455 (version 17 of the draft hybi specification -
<ulink
url="http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-17">http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-17</ulink>
).
SIP Load Balancer will accept HTTP requests and if the request contains
header Sec-WebSocket-Protocol it will upgrade the connection and
dispatch the reuqest to
a node capable to handle WebSocket requests (a node that has a
WebSocket connector).
</para>
<para>One major advantage of having WebSocket support for SIP Load
Balancer is to allow tunneling over HTTP port for SIP traffic and thus
bypass
proxy and firewall servers that might be blocking SIP traffic.</para>
<section
id="sslb-binary-SIP_Load_Balancer-Installing_Configuring_and_Running">
<title>SIP Load Balancer: Installing, Configuring and Running</title>
<para>
</para>
<section
id="sslb-binary-SIP_Load_Balancer-PreInstall_Requirements_and_Prerequisites">
<title>Pre-Install Requirements and Prerequisites</title>
<para>
</para>
<variablelist id="sslb-binary-SIP_Load_Balancer-Software_Prerequisites">
<title>Software Prerequisites</title>
<!--Issue #822 Editor Comment - if I understand correctly, clustering
won't work on Tomcat Servlet Containers. If that is the case, it's probably
easier to say: 1. Load balancing requires at least two Sip Servlet Servers.
2. Only SIP Servlet JBoss AS containers supported. Tomcat Servlet Containers
cannot be clustered. Or something similar to that. Do you agree? -->
<varlistentry>
<term>A
JAIN SIP HA-enabled application server such as &PLATFORM_NAME;
JAIN SLEE or &PLATFORM_NAME;
SIP Servlets is required.
</term>
<listitem>
<para>Running
the SIP Load Balancer requires at least two instances of the
application server as cluster nodes nodes. Therefore, before
configuring the SIP Load Balancer, we should make sure we've
installed a the SIP application server first. The &PLATFORM_NAME;
SIP load balancer will work with a SIP Servlets-enabled JBoss
Application Server
<emphasis>or</emphasis>
a JAIN SLEE application server with SIP RA.
</para>
<para>SIP Servlets containers based on Tomcat are also supported
but the session replication is not available there, thus mid-call
failover will not work.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="sslb-binary-SIP_Load_Balancer-Downloading">
<title>Downloading</title>
<para>
The load balancer is located in the
<filename>sip-balancer</filename>
top-level directory of the &SHORT_PLATFORM_NAME;
distribution. You will find the following files in the directory:
</para>
<variablelist>
<varlistentry>
<term>SIP load balancer executable JAR file</term>
<listitem>
<para>This is the binary file with all dependencies</para>
</listitem>
</varlistentry>
<varlistentry
id="sslb-binary-SIP_Load_Balancer-Configuration_Properties_File">
<term>SIP load balancer Configuration Properties file</term>
<listitem>
<para>This is the properties files with various settings</para>
</listitem>
</varlistentry>
<!-- Unnecessary, because the binary distribution has exact copies of
these files <varlistentry> <term>Modified <filename>server.xml</filename>
Configuration Files</term> <listitem> <para>You can use these sample modified
<filename>server.xml</filename> configuration files to start either (or both)
your SIP Servlet-customized <ulink url="http://code.google.com/p/mobicents/source/browse/trunk/servers/sip-servlets/sip-servlets-impl/docs/fialover-server-jboss.xml">JBoss</ulink>
or <ulink url="http://code.google.com/p/mobicents/source/browse/trunk/servers/sip-servlets/sip-servlets-impl/docs/failover-server-tomcat-6.xml">Tomcat</ulink>
container instances.</para> </listitem> </varlistentry> -->
</variablelist>
</section>
<section id="sslb-binary-SIP_Load_Balancer-Installing">
<title>Installing</title>
<para>The SIP load balancer executable JAR file can be extracted
anywhere in the file system. It is recommended that the file is
placed in the directory containing other JAR executables, so it can
be easily located in the future.</para>
</section>
<section id="sslb-binary-SIP_Load_Balancer-Configuring">
<title>Configuring</title>
<para>
Configuring the SIP load balancer and the two SIP Servlets-enabled
Server nodes is described in
<xref
linkend="sslb-Configuring_the_SIP_Load_Balancer_and_Servlet_Server_Nodes" />
.
</para>
<procedure
id="sslb-Configuring_the_SIP_Load_Balancer_and_Servlet_Server_Nodes">
<title>Configuring
the &PLATFORM_NAME;
SIP Load Balancer and SIP Server Nodes
</title>
<step>
<title>Configure lb.properties Configuration Properties File</title>
<para>
Configure the SIP Load Balancer's Configuration Properties file by
substituting valid values for your personal setup.
<xref linkend="sslb-Complete_Sample_lb.properties_File" />
shows a sample
<filename>lb.properties</filename>
file, with key element descriptions provided after the example.
The lines beginning with the pound sign are comments.
</para>
<example id="sslb-Complete_Sample_lb.properties_File">
<title>Complete Sample lb.properties File</title>
<programlisting linenumbering="unnumbered"><![CDATA[
# 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 port to be used used for the Remote Object
rmiRemoteObjectPort=2001
# 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
]]>
</programlisting>
</example>
<variablelist>
<varlistentry>
<term>host</term>
<listitem>
<para>Local IP address, or interface, on which the SIP load
balancer will listen for incoming requests.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>externalPort</term>
<listitem>
<para>Port on which the SIP load balancer listens for incoming
requests from SIP User Agents.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>internalPort</term>
<listitem>
<para>Port on which the SIP load balancer forwards incoming
requests to available, and healthy, SIP Server cluster nodes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>rmiRegistryPort</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>rmiRemoteObjectPort</term>
<listitem>
<para>Port on which the SIP load balancer will use to export the RMI Remote Object.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>httpPort</term>
<listitem>
<para>Port on which the SIP load balancer will accept HTTP
requests to be distributed across the nodes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>internalTransport</term>
<listitem>
<para>
Transport protocol for the internal SIP connections associated
with the internal SIP port of the load balancer. Possible
choices are
<literal>UDP</literal>
,
<literal>TCP</literal>
and
<literal>TLS</literal>
.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>externalTransport</term>
<listitem>
<para>
Transport protocol for the external SIP connections associated
with the external SIP port of the load balancer. Possible
choices are
<literal>UDP</literal>
,
<literal>TCP</literal>
and
<literal>TLS</literal>
. It must match the transport of the internal port.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>externalIpLoadBalancerAddress</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>externalIpLoadBalancerPort</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>internalIpLoadBalancerAddresst</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>internalIpLoadBalancerPort</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>extraServerNodes</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>algorithmClass</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>nodeTimeout</term>
<listitem>
<para>In milliseonds. Default value is 5100. If a server node
doesnt check in within this time (in ms), it is considered
dead.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>heartbeatInterval</term>
<listitem>
<para>
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 -
<literal>org.mobicents.ha.javax.sip.HEARTBEAT_INTERVAL</literal>
</para>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>
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
<ulink
url="http://snad.ncsl.nist.gov/proj/iptel/jain-sip-1.2/javadoc/javax/sip/SipStack.html">Interface SIP Stack page on nist.gov</ulink>
. For a comprehensive list of properties associated with the SIP
Stack implementation, refer to
<ulink
url="http://snad.ncsl.nist.gov/proj/iptel/jain-sip-1.2/javadoc/gov/nist/javax/sip/SipStackImpl.html">Class SipStackImpl page on nist.gov</ulink>
.
</para>
</note>
<note>
<para>
If SIP load balancer is behind firewall you will need to open all the required ports.
The default ports are:
TCP: 2000, 2001, 2080, 5060, 5065, 8000
UDP: 5060, 5065
</para>
</note>
</step>
<step>
<title>Configure logging</title>
<para>
The SIP load balancer uses
<ulink url="http://logging.apache.org/log4j">Log4J</ulink>
as a logging mechanism. You can configure it through the typical
log4j xml configuration
file and specify the path as follows
<literal>-DlogConfigFile=./log4j.xml</literal>
.
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
<literal>-DlogLevel=DEBUG</literal>
will allow you to switch all loggig categories to the specified
log level.
</para>
</step>
<!-- Is needed on JB5 Version only --><!--step> <title>Configure the <filename>mss-sip-stack.properties</filename>
configuration file</title> <itemizedlist> <listitem> <para>The <literal>org.mobicents.ha.javax.sip.cache.MobicentsSipCache.cacheName</literal>
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 <literal>standard-session-cache</literal></para>
</listitem> <listitem> <para>The <literal>org.mobicents.ha.javax.sip.BALANCERS</literal>
property must be configured with the list of load balancer IP address and
internal ports. As an example, suppose a single &THIS.PLATFORM; SIP Load
Balancer is running with IP <literal>192.168.0.1</literal> and internal port
<literal>5065</literal>, the property would be set with value <literal>192.168.0.1:5065</literal>.
To specify multiple balancers use <literal>;</literal> 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.</para> </listitem> <listitem> <para>The
<literal>org.mobicents.ha.javax.sip.LoadBalancerHeartBeatingServiceClassName</literal>
property is optional, it defines the class name of the HeartBeating service
implementation, currently the only one available is <literal>org.mobicents.ha.javax.sip.LoadBalancerHeartBeatingServiceImpl</literal></para>
</listitem> <listitem> <para>The <literal>org.mobicents.ha.javax.sip.LoadBalancerElector</literal>
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, <literal>org.mobicents.ha.javax.sip.RoundRobinLoadBalancerElector</literal>,
which, as the class name says, uses round robin algorythm to select the balancer.</para>
</listitem> </itemizedlist> </step -->
</procedure>
<section>
<title>Converged Load Balancing</title>
<section>
<title>Apache HTTP Load Balancer</title>
<para>The &SHORT_PLATFORM_NAME;
SIP Load Balancer can work in concert with HTTP load balancers
such as
<literal>mod_jk</literal>
. Whenever an HTTP session is bound to a particular node, an
instruction is sent to the SIP Load Balancer to direct the SIP
calls from the same application session to the same node.
</para>
<para>
It is sufficient to configure
<literal>mod_jk</literal>
to work for HTTP in JBoss in order to enable cooperative load
balancing. &SHORT_PLATFORM_NAME;
will read the configuration and will use it without any extra
configuration. You can read more about configuring
<literal>mod_jk</literal>
with JBoss in your JBoss Application Server documentation.
</para>
</section>
<section>
<title>Integrated HTTP Load Balancer</title>
<para>
To use the integrated HTTP Load Balancer, no extra configuration
is needed. If a unique
<literal>jvmRoute</literal>
is specified and enabled in each application server, it will
behave exactly as the apache balancer. If
<literal>jvmRoute</literal>
is not present, it will use the session ID as a hash value and
attempt to create a sticky session. The integrated balancer can be
used together with the apache balancer at the same time.
</para>
<para>
In addition to the apache behavior, there is a consistent hash
balancer algorithm that can be enabled for both HTTP and SIP
messages. For both HTTP and SIP messages, there is a configurable
affinity key, which is evaluated and hashed against each
unassigned request. All requests with the same hash value will
always be routed to the same application server node. For example,
the SIP affinity key could be the callee user name and the HTTP
affinity key could the
<quote>appsession</quote>
HTTP GET parameter of the request. If the desired behaviour group
these requests, we can just make sure the affinity values (user
name and GET parameter) are the same.
</para>
<figure>
<title>Ensuring SIP and HTTP requests are being grouped by common
affinity value.</title>
<mediaobject
id="sslb-mss-MSSSIPLoadBalancer-dia-StarNetworkTopology_1">
<imageobject>
<imagedata width="440" fileref="images/converged-integrated-lb.png"
format="JPG" />
</imageobject>
</mediaobject>
</figure>
</section>
</section>
</section>
<section id="sslb-binary-SIP_Load_Balancer-Running">
<title>Running</title>
<procedure
id="sslb-Running_the_SIP_Load_Balancer_and_Servlet_Server_Nodes">
<title>Running the SIP Load Balancer and SIP Server Nodes</title>
<step>
<title>Start the SIP Load Balancer</title>
<para>
Start the SIP load balancer, ensuring the Configuration Properties
file (
<filename>lb.properties</filename>
in this example) is specified. In the Linux terminal, or using the
Windows Command Prompt, the SIP Load Balancer is started by
issuing a command similar to this one:
</para>
<screen>java -jar sip-balancer-jar-with-dependencies.jar
lb-configuration.properties</screen>
<para>Executing the SIP load balancer produces output similar to
the following example:</para>
<screen>home]$ java -jar sip-balancer-jar-with-dependencies.jar
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</screen>
<para>The output shows the IP address on which the SIP Load
Balancer is listening, as well as the external and internal
listener ports.</para>
</step>
<step>
<title>Configure SIP Server Nodes</title>
<para>The information about configuring your SIP Server, SIP
Servlets or JAIN SLEE, is in the respective server User Guide.</para>
</step>
<step>
<title>Start Load Balancer Client Nodes</title>
<para>Start all SIP load balancer client nodes.</para>
<!--Issue #822 Editor Comment - What command would you execute to start
all the client nodes? -->
</step>
</procedure>
</section>
<!--<section id="sslb-binary-SIP_Load_Balancer-Using"> <title>Using</title>
<para> </para> </section -->
<section id="sslb-binary-SIP_Load_Balancer-Testing">
<title>Testing</title>
<para>To test load balancing, the same application must be deployed
manually on each node, and two SIP Softphones must be installed.</para>
<procedure>
<title>Testing Load Balancing with Sip Servlets</title>
<step>
<title>Deploy an Application</title>
<para>
Ensure that for each node, the DAR file location is specified in
the
<filename>server.xml</filename>
file.
</para>
<para>Deploy the Location service manually on both nodes.</para>
</step>
<step>
<title>Start the "Sender" SIP softphone</title>
<para>
Start a SIP softphone client with the SIP address of
<userinput>sip:sender@sip-servlets-com</userinput>
, listening on port 5055. The outbound proxy must be specified as
the sip-balancer (http://127.0.0.1:5060)
</para>
</step>
<step>
<title>Start the "Receiver" SIP softphone</title>
<para>
Start a SIP softphone client with the SIP address of
<userinput>sip:receiver-failover@sip-servlets-com</userinput>
, listening on port 5090.
</para>
</step>
<step>
<title>Initiate two calls from "Sender" SIP softphone</title>
<para>
Initiate one call from
<userinput>sip:sender@sip-servlets-com</userinput>
to
<userinput>sip:receiver-failover@sip-servlets-com</userinput>
. Tear down the call once completed.
</para>
<para>Initiate a second call using the same SIP address, and tear
down the call once completed. Notice that the call is handled by
the second node.</para>
</step>
</procedure>
<procedure>
<title>Testing Load Balancing with JAIN SLEE and SIP RA</title>
<step>
<para>Deploy SIP RA</para>
</step>
<step>
<para>Configure the JAIN SIP HA properties for load balancing
according to the JAIN SLEE User Guide</para>
</step>
<step>
<para>Deploy a sample application</para>
</step>
<step>
<para>Run the sample scenario for the application using the SIP
Load Balancer</para>
</step>
</procedure>
</section>
<section id="sslb-binary-SIP_Load_Balancer-Stopping">
<title>Stopping</title>
<para>
Assuming that you started the JBoss Application Server as a
foreground process in the Linux terminal, the easiest way to stop it
is by pressing the
<keycombo action="simul">
<keycap>Ctrl</keycap>
<keycap>C</keycap>
</keycombo>
key combination in the same terminal in which you started it.
</para>
<para>This should produce similar output to the following:</para>
<screen>^COct 21, 2008 1:11:57 AM
org.mobicents.tools.sip.balancer.SipBalancerShutdownHook run
INFO: Stopping the sip forwarder</screen>
</section>
<section id="sslb-binary-SIP_Load_Balancer-Uninstalling">
<title>Uninstalling</title>
<para>To uninstall the SIP load balancer, delete the JAR file you
installed.</para>
</section>
</section>
<!--<note> <title/> <para>Before reading further, you should ensure that
you are familiar with the terminology employed across all sections of the
selected SIP Server from &PLATFORM_NAME; Platform (SIP Servlets or JAIN SLEE
with SIP RA).</para> </note> -->
<section id="sslb-SIP_Load_Balancing_Basics">
<title>SIP Load Balancing Basics</title>
<para>
All User Agents send SIP messages, such as
<literal>INVITE</literal>
and
<literal>MESSAGE</literal>
, 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.
</para>
<para>The SIP Server 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.
</para>
<para>By
using the Load Balancer, SIP traffic is balanced across a pool of
available SIP Servers, increasing the overall throughput of the SIP
service or application running on either individual nodes of the
cluster. In the case of a &SHORT_PLATFORM_NAME;
server with
<literal></distributed></literal>
capabilities, load balancing advantages are applied across the entire
cluster.
</para>
<para>The SIP Load Balancer is also able to failover 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.
</para>
</section>
<section>
<title>HTTP Load Balancing Basics</title>
<para>In addition to the SIP load balancing, there are several options
for coordinated or cooperative load balancing with other protocols
such as HTTP.
</para>
<para>Typically, a JBoss Application Server will use apache HTTP
server with mod_jk, mod_proxy, mod_cluster or similar extension
installed as an HTTP load balancer. This apache-based load balancer
will parse incoming HTTP requests and will look for the session ID of
those requests in order to ensure all requests from the same session
arrive at the same application server.
</para>
<para>
By default, this is done by examining the
<literal>jsessionid</literal>
HTTP cookie or GET parameter and looking for the
<literal>jvmRoute</literal>
assigned to the session. The typical
<literal>jsessionid</literal>
value is of the form
<literal><sessionId>.<jvmRoute></literal>
. The very first request for each new HTTP session does not have a
session ID assigned; the apache routes the request to a random
application server node.
</para>
<para>
When the node responds it assigns a session ID and
<literal>jvmRoute</literal>
to the response of the request in a HTTP cookie. This response goes
back to the client through apache, which keeps track of which node
owns each
<literal>jvmRoute</literal>
. Once the very first request is served this way, the subsequent
requests from this session will carry the assigned cookie, and the
apache load balancer will always route the requests to the node,
which advertised itself as the
<literal>jvmRoute</literal>
owner.
</para>
<para>Instead of using apache, an integrated HTTP Load Balancer is
also available. The SIP Load Balancer has a HTTP port where you can
direct all incoming HTTP requests. The integrated HTTP load balancer
behaves exactly like apache by default, but this behavior is
extensible and can be overridden completely with the pluggable
balancer algorithms. The integrated HTTP load balancer is much easier
to configure and generally requires no effort, because it reuses most
SIP settings and assumes reasonable default values.
</para>
<para>Unlike the native apache, the integrated HTTP Load Balancer is
written completely in Java, thus a performance penalty should be
expected when using it. However, the integrated HTTP Balancer has an
advantage when related SIP and HTTP requests must stick to the same
node.
</para>
</section>
<section>
<title>Pluggable balancer algorithms</title>
<para>
The SIP/HTTP Load Balancer exposes an interface to allow users to
customize the routing decision making for special purposes. By
default there are three built-in algorithms. Only one algorithm is
active at any time and it is specified with the
<literal>algorithmClass</literal>
property in the configuration file.
</para>
<para>It is 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 and HTTP
request and other significant events to make more informed decisions.
</para>
<note>
<para>Users must be aware that by default requests explicitly
addressed to a live server node passing through the load balancer
will be forwarded directly to the server node. This allows for
pre-specified routing use-cases, where the target node is known by
the SIP client through other means. If the target node is dead, then
the node selection algorithm is used to route the request to an
available node.
</para>
</note>
<para>The following is a list of the built-in algorithms:</para>
<para>
<variablelist>
<varlistentry>
<term>org.mobicents.tools.sip.balancer.CallIDAffinityBalancerAlgorithm </term>
<listitem>
<para>
This algorithm is not distributable. It selects nodes randomly to
serve a give Call-ID extracted from the requests and responses.
It keeps a map with
<literal>Call-ID -> nodeId</literal>
associations and this map is not shared with other load balancers
which will cause them to make different decisions. For HTTP it
behaves like apache.
</para>
</listitem>
</varlistentry>
<varlistentry
id="sslb-binary-SIP_Load_Balancer-Configuration_Properties_File_1">
<term>org.mobicents.tools.sip.balancer.HeaderConsistentHashBalancerAlgorithm </term>
<listitem>
<para>This algorithm is distributable and can be used in
distributed load balancer configurations. It extracts the hash
value of specific headers from SIP and HTTP 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.</para>
</listitem>
</varlistentry>
<varlistentry
id="sslb-binary-SIP_Load_Balancer-Configuration_Properties_File_2">
<term>org.mobicents.tools.sip.balancer.PersistentConsistentHashBalancerAlgorithm </term>
<listitem>
<para>This algorithm is distributable and 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.</para>
</listitem>
</varlistentry>
<varlistentry
id="sslb-binary-SIP_Load_Balancer-Configuration_Properties_File_3">
<term>org.mobicents.tools.sip.balancer.ClusterSubdomainAffinityAlgorithm </term>
<listitem>
<para>
This algorithm is not distributable, but supports grouping server
nodes to act
as a subcluster. Any call of a node that belongs to a cluster group
will be preferentially
failed over to a node from the same group. To configure a group you can
just add the
<literal>subclusterMap</literal>
property in the load balancer properties and listing
the IP addresses of the nodes. The groups are enclosed in
parentheses and the IP
addresses are separate by commas as follows:
</para>
<screen>subclusterMap=( 192.168.1.1, 192.168.1.2 ) ( 10.10.10.10,
20.20.20.20, 30.30.30.30)</screen>
<para>The nodes specified in a group do not have to alive and
nodes that are not specified are still allowed to join the
cluster. Otherwise the algorthim behaves exactly as the default
Call-ID affinity algorthim.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<section>
<title>Distributed load balancing</title>
<para>
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/HTTP load balancers based
on some IP rules or round-robin. With consistent hash and
<literal>jvmRoute</literal>
-based balancer algorithms it doesn't matter which SIP/HTTP 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/HTTP balancers.
</para>
<figure>
<title>Example deployment: IP load balancers serving both directions
for incoming/outgoing requests in a cluster</title>
<mediaobject id="sslb-mss-MSSSIPLoadBalancer-dia-StarNetworkTopology_2">
<imageobject>
<imagedata width="440"
fileref="images/bidirectional-distributed-sip-lb.gif" format="JPG" />
</imageobject>
</mediaobject>
</figure>
</section>
<section id="sslb-SIP_Load_Balancer-Implementation">
<title>Implementation
of the &PLATFORM_NAME;
Load Balancer
</title>
<para>Each
individual &PLATFORM_NAME;
SIP Server in the cluster is responsible for contacting the SIP load
balancer and relaying its health status and regular
"heartbeats". <!--Issue #822 Editor Comment - would it be worthwhile
describing heartbeats in more detail here? Can you link to another area in
the guide which discusses heartbeats in more detail (to avoid duplicating
information)? -->
</para>
<para>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.
</para>
<para>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.
</para>
<para>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.
</para>
</section>
<section>
<title>SIP Message Flow</title>
<para>
The SIP Load Balancer appends itself to the
<literal>Via</literal>
header of each request, so that returned responses are sent to the
SIP Balancer before they are sent to the originating endpoint.
</para>
<para>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 an unhealthy status, or irregular heartbeats from a node.
</para>
<para>Additionally, SIP Load Balancer will add two custom header
containing the initial remote address and port of the sip client for
every REGISTER request or requests with content.
</para>
<itemizedlist>
<listitem>
<para>X-Sip-Balancer-InitialRemoteAddr</para>
</listitem>
<listitem>
<para>X-Sip-Balancer-InitialRemotePort</para>
</listitem>
</itemizedlist>
<para>Application can use these two headers to have the correct
location of the sip client that sent the REGISTER request.</para>
<para>
In advanced configurations, it is possible to run more than one SIP
Load Balancer. Simply edit the balancers connection string in your
SIP Server - the list is separated with semi-colon. <!--Issue #822 Editor
Comment - is there more information regarding how to enable this? -->
</para>
<para>
<xref linkend="figure-mss-Basic_IP_and_Port_Cluster_Configuration" />
describes a basic IP and Port Cluster Configuration. In the diagram,
the SIP Load balancer is the server with the IP address of
<literal>192.168.1.1</literal>
.
</para>
<figure id="figure-mss-Basic_IP_and_Port_Cluster_Configuration">
<title>Basic IP and Port Cluster Configuration</title>
<mediaobject id="sslb-mss-MSSSIPLoadBalancer-dia-ClusterIPsAndPorts">
<imageobject>
<imagedata width="532" align="center"
fileref="images/mss-MSSSIPLoadBalancer-dia-ClusterIPsAndPorts.jpg"
format="JPG" />
</imageobject>
</mediaobject>
</figure>
</section>
<section>
<title>Using the Load Balancer with Third-Party SIP Servers</title>
<para>The load balancer only forwards requests to servers that send
heartbeat signals. A third party server can send metadata using a SIP
OPTIONS or SIP INFO message towards the internal port of the SIP load
balancer. For security reasons heartbeat messages arriving at the
external entry-point will be ignored and using a single internal and
external entry-point is not allowed. The third party SIP server must
advertise it's metadata in the SIP message contents.</para>
<para>For example, this request will advertise a SIP server listening
on 127.0.0.1:5070, both TCP and UDP .</para>
<programlisting linenumbering="unnumbered"><![CDATA[
OPTIONS sip:[email protected]:5065;lr SIP/2.0
Call-ID: [email protected]
CSeq: 1 OPTIONS
From: <sip:[email protected]>;tag=4481411
To: <sip:[email protected]>
Via: SIP/2.0/UDP 127.0.0.1:5070;branch=z9hG4bK-373335-ec2c7452cfd0130bd409ba4f8ea5f54e
Max-Forwards: 70
Contact: <sip:[email protected]:4060;transport=udp;lr>
Route: <sip:[email protected]:5065;node_host=127.0.0.1;node_port=5070;lr>
Content-Type: text/plain;charset=UTF-8
Mobicents-Heartbeat: 1
Content-Length: 54
tcpPort=5070
udpPort=5070
hostname=sipHeartbeat
ip=127.0.0.1
]]></programlisting>
<para>
The important headers to be filled in this request are
<literal>Mobicents-Heartbeat</literal>
, the Route header with
<literal>;node_host=127.0.0.1;node_port=5070</literal>
and the message contents. The message contents are interpreted as
properties of the
<literal>SIPNode</literal>
object representing the node in the load balancer and can be further
interpreted by load balancing algorithms for load balancing purposes.
The value of the
<literal>Mobicents-Heartbeat</literal>
header is arbitrary and reserved for future use, the presence of the
header is sufficient to instruct the load balancer how to process the
request.
</para>
<para>
All requests initiated by the SIP Server must have the following hint
in their Route header
<literal>;node_host=127.0.0.1;node_port=5070</literal>
. This hint instructs the SIP load balancer that the dialog initated
by the application server must stay on the node advertised in the
hint. This function is cruicial when the direction of the requests
withing the dialog is reversed.
</para>
<para>Since this SIP request represents a heartbeat signal, it must be
sent regularly at least once every 5 seconds (by default). Sending
this request is responsibility of the third party server. The load
balancer will respond to every heartbeat request with 200 OK
immediately. The third party server must expect the OK response. If
no response if received within a threshhold time then the third party
SIP server must assume the SIP load balancer is not available and use
another (backup) load balancer.</para>
<para>The regular SIP load balancer setting are still in effect for
third party servers and you can expect the same behavior as the
Mobicents-specific RMI heartbeat configuration.</para>
<para>
If you are desgning a pluggable algorithm using the SIP metadata, you
can access the properties passed in the SIP message contents using
<literal>SIPNode.getProperties()</literal>
</para>
</section>
</chapter>
