Revision: 15600
Author: rhatdocs
Date: Wed Dec 1 17:55:07 2010
Log: Committing patch attached to
http://code.google.com/p/mobicents/issues/detail?id=2176. Integrating Load
Balancer documentation changes from product repository
http://code.google.com/p/mobicents/source/detail?r=15600
Modified:
/trunk/tools/sip-balancer/docs/sources/src/main/resources/en-US/concept-section-SS_Load_Balancer.xml
=======================================
---
/trunk/tools/sip-balancer/docs/sources/src/main/resources/en-US/concept-section-SS_Load_Balancer.xml
Thu Oct 14 09:58:07 2010
+++
/trunk/tools/sip-balancer/docs/sources/src/main/resources/en-US/concept-section-SS_Load_Balancer.xml
Wed Dec 1 17:55:07 2010
@@ -14,87 +14,8 @@
</imageobject>
</mediaobject>
</figure>
- <para>The &PLATFORM_NAME; SIP Load Balancer is used to balance the load
of SIP service requests and responses between nodes in a &PLATFORM_NAME;
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 &PLATFORM_NAME; 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>
-<!--<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 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.</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. 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 it 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. 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> (e.g.
<literal>mysessionid323424.node1</literal> where <literal>node1</literal>
is the <literal>jvmRoute</literal> component). The very first request for
each new HTTP session do not have any session ID assigned, thus apache
routes the request to a random application server node. When the node
responds it assigns a session ID and <literal>jvmRoute</literal> to the
response of the request in a HTTP cookie and this response goes back to the
client through apache, which keeps track of which node owns which
<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 balancing is
also available. The SIP load balancer has an HTTP port where you could
direct all incoming HTTP requests. The integrated HTTP load balancer
behaves exactly like apache by default, but this behaviour 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 ans
assumes reasonable default values.</para>
- <para>Unlike the native apache, the integrated HTTP load balancer is
written completely in Java and does not support AJP, 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 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 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>
- </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 scenario with IP load balancers serving
both directions for incoming and 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 &PLATFORM_NAME; 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
and unhealthy status, or irregular heartbeats from a node.</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>
+ <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>
<section
id="sslb-binary-SIP_Load_Balancer-Installing_Configuring_and_Running">
<title>SIP Load Balancer: Installing, Configuring and Running</title>
<para> </para>
@@ -111,7 +32,7 @@
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>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>
@@ -145,7 +66,7 @@
</section>
<section id="sslb-binary-SIP_Load_Balancer-Installing">
<title>Installing</title>
- <para>The SIP load balancer executable JAR file can be placed
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>
+ <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>
@@ -153,7 +74,7 @@
<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>
+ <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[
@@ -309,13 +230,13 @@
</listitem>
</varlistentry>
<varlistentry>
- <term> internalTransport</term>
+ <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>
+ <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>
@@ -370,12 +291,12 @@
</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>
+ <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>
</step>
<step>
<title>Configure logging</title>
- <para>The SIP load balancer uses <ulink
url="http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html">Java
Logging as a logging mechanism</ulink>. As such you can configure it
through a property file and specify the property file to be used by using
the following command
<literal>-Djava.util.logging.config.file=./lb-logging.properties</literal>.
Please refer to JDK logging for more informationon how to configure the
Java logging.</para>
+ <para>The SIP load balancer uses <ulink
url="http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html">Java
Logging</ulink> as a logging mechanism. You can configure it through a
property file and specify the property file to be used by using the
following command
<literal>-Djava.util.logging.config.file=./lb-logging.properties</literal>.
Please refer to JDK logging for more informationon how to configure the
Java logging.</para>
</step>
<!-- Is needed on JB5 Version only --><!--step>
<title>Configure the
<filename>mss-sip-stack.properties</filename> configuration file</title>
@@ -397,14 +318,16 @@
<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>
+ <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 session ID as a hash value and attempt to create sticky session.
The integrated balancer can be used together with the apache balancer at
the same time.</para>
- <para>In addition to the apache behaviour, 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>
+ <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">
@@ -434,7 +357,7 @@
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>
+ <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>
@@ -452,7 +375,7 @@
<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. Two SIP Softphones must be installed.</para>
+ <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>
@@ -462,7 +385,7 @@
</step>
<step>
<title>Start the "Sender" SIP softphone</title>
- <para>Start a SIP softphone client with the SIP address of
<userinput>sip:sen...@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>
+ <para>Start a SIP softphone client with the SIP address of
<userinput>sip:sen...@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>
@@ -494,7 +417,107 @@
</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>
+ <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>
+ </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>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>
</chapter>