<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:lang="en"
  xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:svg="http://www.w3.org/2000/svg"
  xmlns:mml="http://www.w3.org/1998/Math/MathML"
  xmlns:html="http://www.w3.org/1999/xhtml"
  xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>WEB clustering with Apache/Tomcat</title>
  </info>

  <section xml:id="config.web.jk">
    <info>
      <title>Configuring a WEB farm with mod_jk</title>
    </info>

    <section>
      <info>
        <title>mod_jk configuration</title>
      </info>

      <para>
        As with other Apache modules, mod_jk should be first
        installed on the modules directory of the Apache Web
        Server and the
        <filename>httpd.conf</filename>
        file has to be updated. Moreover, mod_jk requires
        <filename>workers.properties</filename>
        file that describes the host(s) and port(s) used by the
        workers.
      </para>

      <section>
        <info>
          <title>workers.properties file</title>
        </info>

        <para>
          Here we provide an example of
          <filename>workers.properties</filename>
          file to connect the Apache frontal with two
          workers. The file defines a
          <emphasis>load-balancing</emphasis>
          worker named
          <literal>myloadbalancer</literal>
          , and the two
          <emphasis>balanced</emphasis>
          workers,
          <literal>worker1</literal>
          and
          <literal>worker2</literal>
          . Each cluster member will be configured to play the
          role of one of the balanced workers. Additionally, a
          status worker jkstatus is defined for controlling
          and monitoring the load-balancing.
        </para>
		<example>
            <title>Configuring mod_jk workers</title>
        <screen>
#-----------------------
# List the workers name
#-----------------------
worker.list=myloadbalancer,jkstatus

#-----------------------
# worker1
#-----------------------
worker.worker1.port=9010
worker.worker1.host=localhost
worker.worker1.type=ajp13 # Load balance factor
worker.worker1.lbfactor=1 # Define preferred failover node for worker1
#worker.worker1.redirect=worker2 # Disable worker1 for all requests except failover
#worker.worker1.disabled=True
#-----------------------
# worker2
#-----------------------
worker.worker2.port=9011
worker.worker2.host=localhost
worker.worker2.type=ajp13 # Load balance factor
worker.worker2.lbfactor=1 # Define preferred failover node for worker2
#worker.worker2.redirect=worker2 # Disable worker2 for all requests except failover
#worker.worker2.disabled=True
#-----------------------
# Load Balancer worker
#-----------------------
worker.myloadbalancer.type=lb
worker.myloadbalancer.balance_workers=worker1,worker2
worker.myloadbalancer.sticky_session=false
#-----------------------
# jkstatus worker
#-----------------------
worker.jkstatus.type=status
        </screen>
        </example>

        <para>
          For a complete documentation about
          <filename>workers.properties</filename>
          see the Apache Tomcat Connector
          <link
            xlink:href="http://tomcat.apache.org/connectors-doc/reference/workers.html">
            guide
          </link>
          .
        </para>
      </section>

      <section>
        <info>
          <title>Apache configuration</title>
        </info>

        <para>
          The Apache configuration must be enhanced for loading the mod_jk plugin with its setting. The following lines
          have to be added to the <filename>httpd.conf</filename> file directly or included from another file:
        </para>
		<example>
            <title>Configuring mod_jk mount points</title>
        <screen>
# Load mod_jk module
# Update this path to match your modules location
LoadModule jk_module modules/mod_jk.so
# Location of the workers.properties file
# Update this path to match your conf directory location JkWorkersFile
# (put workers.properties next to httpd.conf)
/etc/httpd/conf/workers.properties
# Location of the log file JkLogFile /var/log/mod_jk.log
# Log level : debug, info, error or emerg
JkLogLevel info
# Select the timestamp log format
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
# Shared Memory Filename ( Only for Unix platform ) required by loadbalancer
JkShmFile /var/log/jk.shm
# Assign specific URL to the workers
JkMount /sampleCluster2 myloadbalancer
JkMount /sampleCluster2/* myloadbalancer
JkMount /sampleCluster3 myloadbalancer
JkMount /sampleCluster3/* myloadbalancer
# A mount point to the status worker
JkMount /jkmanager jkstatus
JkMount /jkmanager/* jkstatus

# Copy mount points into all virtual hosts
JkMountCopy All

# Enable the Jk manager access only from localhost
&lt;Location /jkmanager/&gt;
   JkMount jkstatus
   Order deny,allow
   Deny from all
   Allow from 127.0.0.1
&lt;/Location&gt;
        </screen>
        </example>

        <para>
        The location of the <filename>workers.properties</filename> file has to be adapted to your environment.
        The <literal>JkMount</literal> directives specify the routes that are managed by mod_jk. The examples of
        context urls pattern have to be replaced with your application ones.

          For a complete documentation see Apache
          <link
            xlink:href="http://tomcat.apache.org/connectors-doc/webserver_howto/apache.html">
            HowTo
          </link>
          .
        </para>
      </section>
    </section>

    <section>
      <info>
        <title>Cluster members configuration</title>
      </info>

      <para>
        Each cluster member needs an AJP/1.3 connector listening on the
        port defined in the workers.properties file. Moreover,
        the worker name (here in the example, worker1/worker2) must be used as
        value for the Engine's
        <literal>jvmRoute</literal>
        attribute.
      </para>

      <para>
        Here is a chunk of <filename>tomcat6-server.xml</filename> configurations file for
        the member worker1:
      </para>

		<example>
            <title>Configuring an AJP connector in Tomcat</title>
      <screen>
&lt;Server&gt;
  &lt;!-- Define the Tomcat Stand-Alone Service --&gt;
  &lt;Service name="Tomcat-JOnAS"&gt;
    &lt;!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 9000 --&gt;
    &lt;Connector port="9000" protocol="HTTP/1.1" connectionTimeout="20000"
        redirectPort="9043" /&gt;
    &lt;!-- AJP 1.3 Connector on port 9010 for worker.worker1.port in workers.properties file --&gt;
    &lt;Connector port="9010" redirectPort="9043" protocol="AJP/1.3"/&gt;

    &lt;!-- An Engine represents the entry point You should set jvmRoute to support load-balancing via AJP ie : --&gt;
    &lt;Engine name="jonas" defaultHost="localhost" jvmRoute="worker1"&gt;
    &lt;/Engine&gt;
  &lt;/Service&gt;
&lt;Server&gt;
      </screen>
      </example>
    </section>

  </section>

 <section xml:id="config.web.mod_proxy_balancer">
    <info>
      <title>Configuring a WEB farm with mod_proxy_balancer</title>
    </info>

    <section>
      <info>
        <title>mod_proxy_balancer configuration</title>
      </info>

      <para>
        <note>
          <literal>mod_proxy-balancer</literal> is available in Apache 2.2 and later.
        </note>

        See the Apache documentation
          <link
            xlink:href="http://httpd.apache.org/docs/2.2/mod/mod_proxy_balancer.html">
            here
          </link>.
      </para>

    </section>

    <section>
      <info>
        <title>Cluster members configuration</title>
      </info>

      <para>
        Contrary to <literal>mod_jk</literal>, <literal>mod_proxy_balancer</literal> supports HTTP and AJP protocols. Thus the cluster member can
        specify either an AJP/1.3 connector or a HTTP connector. In both case, the connector port number must be the same than the port number
        defined in the Apache's configuration file.
        Moreover, the BalancerMember <literal>route</literal> parameter must be used as value for the Engine's
        <literal>jvmRoute</literal>
        attribute.
      </para>
    </section>
 </section>


  <section>
    <info>
      <title>Configuring a WEB cluster</title>
    </info>

    <para>The load-balancing is configured as a WEB farm, see <xref linkend="config.web.jk" /> and <xref linkend="config.web.mod_proxy_balancer" />.</para>

    <section>
      <info>
        <title>TomcatCluster configuration</title>
      </info>

      <para>
        Additionally to HTTP requests load balancing provided by
        mod_jk, transparent failover for Web applications can
        be reached by using HTTP session replication provided by
        the Tomcat clustering solution.
      </para>

      <para>
        Web cluster
        members are JOnAS instances having the <emphasis>web container</emphasis>
        service activated, using the Tomcat implementation, and having a
        specific configuration which allows them to be members
        of a Tomcat cluster.
      </para>

      <para>
        The concerned configuration file is the
        <filename>tomcat6-server.xml</filename>
        file. Every member of the cluster must have a <literal>Cluster</literal>
        element defined in the default virtual host definition.
        The cluster name is defined by the <literal>clusterName</literal>
        attribute, which should be the same for all the cluster
        members. Another common element for the cluster members
        is the <literal>Membership</literal> definition.
      </para>

      <para>
        The example below defines a configuration of the <literal>Cluster</literal> element for an all-to-all session replication with the DeltaManager.
        This works great for small cluster. For larger cluster, BackupManager enables to replicate the session data to one backup node,
        and only to nodes that have the application deployed. See the <link
            xlink:href="http://tomcat.apache.org/tomcat-6.0-doc/cluster-howto.html">
            documentation
          </link> for more informations.
      </para>

		<example>
            <title>Configuring the HTTP session replication in Tomcat</title>
      <screen>
      &lt;!-- Define a Cluster element --&gt;
      &lt;Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
                 channelSendOptions="8" clustername="mycluster" &gt;
          &lt;Manager className="org.apache.catalina.ha.session.DeltaManager"
                   expireSessionsOnShutdown="false"
                   notifyListenersOnReplication="true"/&gt;
          &lt;Channel className="org.apache.catalina.tribes.group.GroupChannel"&gt;
            &lt;Membership className="org.apache.catalina.tribes.membership.McastService"
                        address="228.0.0.4"
                        port="45564"
                        frequency="500"
                        dropTime="3000"/&gt;
            &lt;Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
                      address="auto"
                      port="4000"
                      autoBind="100"
                      selectorTimeout="5000"
                      maxThreads="6"/&gt;
            &lt;Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter"&gt;
              &lt;Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/&gt;
            &lt;/Sender&gt;
            &lt;Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/&gt;
            &lt;Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/&gt;
          &lt;/Channel&gt;
          &lt;Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
                 filter=""/&gt;
          &lt;Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve"/&gt;
          &lt;ClusterListener className="org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener"/&gt;
          &lt;ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/&gt;
        &lt;/Cluster&gt;
      </screen>
      </example>

      <para>
        <note>
          <para>
            the
            <property>clusterName</property>
            attribute is mandatory for administration purpose (and not set by default
            in
            <filename>tomcat6-server.xml</filename>
            file).
          </para>
        </note>
      </para>
    </section>
  </section>
</section>
