<commit_before><?xml version="1.0"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-howto.html">

    &project;

    <properties>
        <author email="<EMAIL>"><NAME></author>
        <author email="<EMAIL>"><NAME></author>
        <title>Clustering/Session Replication HOW-TO</title>
    </properties>

<body>

<section name="Important Note">
<p><b>You can also check the <a href="config/cluster.html">configuration reference documentation.</a></b>
</p>
</section>

<section name="Table of Contents">
<toc/>
</section>

<section name="For the impatient">
  <p>
    Simply add <source>&lt;Cluster className=&quot;org.apache.catalina.ha.tcp.SimpleTcpCluster&quot;/&gt;</source>
    to your <code>&lt;Engine&gt;</code> or your <code>&lt;Host&gt;</code> element to enable clustering.
  </p>
  <p>
    Using the above configuration will enable all-to-all session replication
    using the <code>DeltaManager</code> to replicate session deltas. By all-to-all we mean that the session gets replicated to all the other 
    nodes in the cluster. This works great for smaller cluster but we don't recommend it for larger clusters(a lot of tomcat nodes).
    Also when using the delta manager it will replicate to all nodes, even nodes that don't have the application deployed.<br/>
    To get around this problem, you'll want to use the BackupManager. This manager only replicates the session data to one backup
    node, and only to nodes that have the application deployed. Downside of the BackupManager: not quite as battle tested as the delta manager.
    <br/>
    Here are some of the important default values:<br/>
    1. Multicast address is 172.16.58.3<br/>
    2. Multicast port is 45564 (the port and the address together determine cluster membership.<br/>
    3. The IP broadcasted is <code>java.net.InetAddress.getLocalHost().getHostAddress()</code> (make sure you don't broadcast 127.0.0.1, this is a common error)<br/>
    4. The TCP port listening for replication messages is the first available server socket in range <code>4000-4100</code><br/>
    5. Two listeners are configured <code>ClusterSessionListener</code> and <code>JvmRouteSessionIDBinderListener</code><br/>
    6. Two interceptors are configured <code>TcpFailureDetector</code> and <code>MessageDispatch15Interceptor</code><br/>
    The following is the default cluster configuration:<br/>
    <source>
        &lt;Cluster className=&quot;org.apache.catalina.ha.tcp.SimpleTcpCluster&quot;
                 channelSendOptions=&quot;8&quot;&gt;

          &lt;Manager className=&quot;org.apache.catalina.ha.session.DeltaManager&quot;
                   expireSessionsOnShutdown=&quot;false&quot;
                   notifyListenersOnReplication=&quot;true&quot;/&gt;

          &lt;Channel className=&quot;org.apache.catalina.tribes.group.GroupChannel&quot;&gt;
            &lt;Membership className=&quot;org.apache.catalina.tribes.membership.McastService&quot;
                        address=&quot;172.16.58.3&quot;
                        port=&quot;45564&quot;
                        frequency=&quot;500&quot;
                        dropTime=&quot;3000&quot;/&gt;
            &lt;Receiver className=&quot;org.apache.catalina.tribes.transport.nio.NioReceiver&quot;
                      address=&quot;auto&quot;
                      port=&quot;4000&quot;
                      autoBind=&quot;100&quot;
                      selectorTimeout=&quot;5000&quot;
                      maxThreads=&quot;6&quot;/&gt;

            &lt;Sender className=&quot;org.apache.catalina.tribes.transport.ReplicationTransmitter&quot;&gt;
              &lt;Transport className=&quot;org.apache.catalina.tribes.transport.nio.PooledParallelSender&quot;/&gt;
            &lt;/Sender&gt;
            &lt;Interceptor className=&quot;org.apache.catalina.tribes.group.interceptors.TcpFailureDetector&quot;/&gt;
            &lt;Interceptor className=&quot;org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor&quot;/&gt;
          &lt;/Channel&gt;

          &lt;Valve className=&quot;org.apache.catalina.ha.tcp.ReplicationValve&quot;
                 filter=&quot;&quot;/&gt;
          &lt;Valve className=&quot;org.apache.catalina.ha.session.JvmRouteBinderValve&quot;/&gt;

          &lt;Deployer className=&quot;org.apache.catalina.ha.deploy.FarmWarDeployer&quot;
                    tempDir=&quot;/tmp/war-temp/&quot;
                    deployDir=&quot;/tmp/war-deploy/&quot;
                    watchDir=&quot;/tmp/war-listen/&quot;
                    watchEnabled=&quot;false&quot;/&gt;

          &lt;ClusterListener className=&quot;org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener&quot;/&gt;
          &lt;ClusterListener className=&quot;org.apache.catalina.ha.session.ClusterSessionListener&quot;/&gt;
        &lt;/Cluster&gt;    
    </source>
  </p>
  <p>Will cover this section in more detail later in this document.</p>
</section>

<section name="Cluster Basics">

<p>To run session replication in your Tomcat 7.0 container, the following steps
should be completed:</p>
<ul>
  <li>All your session attributes must implement <code>java.io.Serializable</code></li>
  <li>Uncomment the <code>Cluster</code> element in server.xml</li>
  <li>If you have defined custom cluster valves, make sure you have the <code>ReplicationValve</code>  defined as well under the Cluster element in server.xml</li>
  <li>If your Tomcat instances are running on the same machine, make sure the <code>tcpListenPort</code>
      attribute is unique for each instance, in most cases Tomcat is smart enough to resolve this on it's own by autodetecting available ports in the range 4000-4100</li>
  <li>Make sure your <code>web.xml</code> has the <code>&lt;distributable/&gt;</code> element 
      or set at your <code>&lt;Context distributable="true" /&gt;</code></li>
  <li>If you are using mod_jk, make sure that jvmRoute attribute is set at your Engine <code>&lt;Engine name="Catalina" jvmRoute="node01" &gt;</code>
      and that the jvmRoute attribute value matches your worker name in workers.properties</li>
  <li>Make sure that all nodes have the same time and sync with NTP service!</li>
  <li>Make sure that your loadbalancer is configured for sticky session mode.</li>
</ul>
<p>Load balancing can be achieved through many techniques, as seen in the
<a href="balancer-howto.html">Load Balancing</a> chapter.</p>
<p>Note: Remember that your session state is tracked by a cookie, so your URL must look the same from the out
   side otherwise, a new session will be created.</p>
<p>Note: Clustering support currently requires the JDK version 1.5 or later.</p>
<p>The Cluster module uses the Tomcat JULI logging framework, so you can configure logging 
   through the regular logging.properties file. To track messages, you can enable logging on the key:<code>org.apache.catalina.tribes.MESSAGES</code></p>
</section>


<section name="Overview">

<p>To enable session replication in Tomcat, three different paths can be followed to achieve the exact same thing:</p>
<ol>
  <li>Using session persistence, and saving the session to a shared file system (PersistenceManager + FileStore)</li>
  <li>Using session persistence, and saving the session to a shared database (PersistenceManager + JDBCStore)</li>
  <li>Using in-memory-replication, using the SimpleTcpCluster that ships with Tomcat (lib/catalina-tribes.jar + lib/catalina-ha.jar)</li>
</ol>

<p>In this release of session replication, Tomcat can perform an all-to-all replication of session state using the <code>DeltaManager</code> or 
   perform backup replication to only one node using the <code>BackupManager</code>.
   The all-to-all replication is an algorithm that is only efficient when the clusters are small. For larger clusters,  to use 
   a primary-secondary session replication where the session will only be stored at one backup server simply setup the BackupManager. <br/>
   Currently you can use the domain worker attribute (mod_jk &gt; 1.2.8) to build cluster partitions
   with the potential of having a more scaleable cluster solution with the DeltaManager(you'll need to configure the domain interceptor for this).<commit_msg>Remove setting distributable on the Context from the docs. It gets lost on webapp reload() e.g. when triggered from the manager app.<commit_after><?xml version="1.0"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-howto.html">

    &project;

    <properties>
        <author email="<EMAIL>"><NAME></author>
        <author email="<EMAIL>"><NAME></author>
        <title>Clustering/Session Replication HOW-TO</title>
    </properties>

<body>

<section name="Important Note">
<p><b>You can also check the <a href="config/cluster.html">configuration reference documentation.</a></b>
</p>
</section>

<section name="Table of Contents">
<toc/>
</section>

<section name="For the impatient">
  <p>
    Simply add <source>&lt;Cluster className=&quot;org.apache.catalina.ha.tcp.SimpleTcpCluster&quot;/&gt;</source>
    to your <code>&lt;Engine&gt;</code> or your <code>&lt;Host&gt;</code> element to enable clustering.
  </p>
  <p>
    Using the above configuration will enable all-to-all session replication
    using the <code>DeltaManager</code> to replicate session deltas. By all-to-all we mean that the session gets replicated to all the other 
    nodes in the cluster. This works great for smaller cluster but we don't recommend it for larger clusters(a lot of tomcat nodes).
    Also when using the delta manager it will replicate to all nodes, even nodes that don't have the application deployed.<br/>
    To get around this problem, you'll want to use the BackupManager. This manager only replicates the session data to one backup
    node, and only to nodes that have the application deployed. Downside of the BackupManager: not quite as battle tested as the delta manager.
    <br/>
    Here are some of the important default values:<br/>
    1. Multicast address is 172.16.58.3<br/>
    2. Multicast port is 45564 (the port and the address together determine cluster membership.<br/>
    3. The IP broadcasted is <code>java.net.InetAddress.getLocalHost().getHostAddress()</code> (make sure you don't broadcast 127.0.0.1, this is a common error)<br/>
    4. The TCP port listening for replication messages is the first available server socket in range <code>4000-4100</code><br/>
    5. Two listeners are configured <code>ClusterSessionListener</code> and <code>JvmRouteSessionIDBinderListener</code><br/>
    6. Two interceptors are configured <code>TcpFailureDetector</code> and <code>MessageDispatch15Interceptor</code><br/>
    The following is the default cluster configuration:<br/>
    <source>
        &lt;Cluster className=&quot;org.apache.catalina.ha.tcp.SimpleTcpCluster&quot;
                 channelSendOptions=&quot;8&quot;&gt;

          &lt;Manager className=&quot;org.apache.catalina.ha.session.DeltaManager&quot;
                   expireSessionsOnShutdown=&quot;false&quot;
                   notifyListenersOnReplication=&quot;true&quot;/&gt;

          &lt;Channel className=&quot;org.apache.catalina.tribes.group.GroupChannel&quot;&gt;
            &lt;Membership className=&quot;org.apache.catalina.tribes.membership.McastService&quot;
                        address=&quot;172.16.58.3&quot;
                        port=&quot;45564&quot;
                        frequency=&quot;500&quot;
                        dropTime=&quot;3000&quot;/&gt;
            &lt;Receiver className=&quot;org.apache.catalina.tribes.transport.nio.NioReceiver&quot;
                      address=&quot;auto&quot;
                      port=&quot;4000&quot;
                      autoBind=&quot;100&quot;
                      selectorTimeout=&quot;5000&quot;
                      maxThreads=&quot;6&quot;/&gt;

            &lt;Sender className=&quot;org.apache.catalina.tribes.transport.ReplicationTransmitter&quot;&gt;
              &lt;Transport className=&quot;org.apache.catalina.tribes.transport.nio.PooledParallelSender&quot;/&gt;
            &lt;/Sender&gt;
            &lt;Interceptor className=&quot;org.apache.catalina.tribes.group.interceptors.TcpFailureDetector&quot;/&gt;
            &lt;Interceptor className=&quot;org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor&quot;/&gt;
          &lt;/Channel&gt;

          &lt;Valve className=&quot;org.apache.catalina.ha.tcp.ReplicationValve&quot;
                 filter=&quot;&quot;/&gt;
          &lt;Valve className=&quot;org.apache.catalina.ha.session.JvmRouteBinderValve&quot;/&gt;

          &lt;Deployer className=&quot;org.apache.catalina.ha.deploy.FarmWarDeployer&quot;
                    tempDir=&quot;/tmp/war-temp/&quot;
                    deployDir=&quot;/tmp/war-deploy/&quot;
                    watchDir=&quot;/tmp/war-listen/&quot;
                    watchEnabled=&quot;false&quot;/&gt;

          &lt;ClusterListener className=&quot;org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener&quot;/&gt;
          &lt;ClusterListener className=&quot;org.apache.catalina.ha.session.ClusterSessionListener&quot;/&gt;
        &lt;/Cluster&gt;    
    </source>
  </p>
  <p>Will cover this section in more detail later in this document.</p>
</section>

<section name="Cluster Basics">

<p>To run session replication in your Tomcat 7.0 container, the following steps
should be completed:</p>
<ul>
  <li>All your session attributes must implement <code>java.io.Serializable</code></li>
  <li>Uncomment the <code>Cluster</code> element in server.xml</li>
  <li>If you have defined custom cluster valves, make sure you have the <code>ReplicationValve</code>  defined as well under the Cluster element in server.xml</li>
  <li>If your Tomcat instances are running on the same machine, make sure the <code>tcpListenPort</code>
      attribute is unique for each instance, in most cases Tomcat is smart enough to resolve this on it's own by autodetecting available ports in the range 4000-4100</li>
  <li>Make sure your <code>web.xml</code> has the
      <code>&lt;distributable/&gt;</code> element</li>
  <li>If you are using mod_jk, make sure that jvmRoute attribute is set at your Engine <code>&lt;Engine name="Catalina" jvmRoute="node01" &gt;</code>
      and that the jvmRoute attribute value matches your worker name in workers.properties</li>
  <li>Make sure that all nodes have the same time and sync with NTP service!</li>
  <li>Make sure that your loadbalancer is configured for sticky session mode.</li>
</ul>
<p>Load balancing can be achieved through many techniques, as seen in the
<a href="balancer-howto.html">Load Balancing</a> chapter.</p>
<p>Note: Remember that your session state is tracked by a cookie, so your URL must look the same from the out
   side otherwise, a new session will be created.</p>
<p>Note: Clustering support currently requires the JDK version 1.5 or later.</p>
<p>The Cluster module uses the Tomcat JULI logging framework, so you can configure logging 
   through the regular logging.properties file. To track messages, you can enable logging on the key:<code>org.apache.catalina.tribes.MESSAGES</code></p>
</section>


<section name="Overview">

<p>To enable session replication in Tomcat, three different paths can be followed to achieve the exact same thing:</p>
<ol>
  <li>Using session persistence, and saving the session to a shared file system (PersistenceManager + FileStore)</li>
  <li>Using session persistence, and saving the session to a shared database (PersistenceManager + JDBCStore)</li>
  <li>Using in-memory-replication, using the SimpleTcpCluster that ships with Tomcat (lib/catalina-tribes.jar + lib/catalina-ha.jar)</li>
</ol>

<p>In this release of session replication, Tomcat can perform an all-to-all replication of session state using the <code>DeltaManager</code> or 
   perform backup replication to only one node using the <code>BackupManager</code>.
   The all-to-all replication is an algorithm that is only efficient when the clusters are small. For larger clusters,  to use 
   a primary-secondary session replication where the session will only be stored at one backup server simply setup the BackupManager. <br/>
   Currently you can use the domain worker attribute (mod_jk &gt; 1.2.8) to build cluster partitions
   with the potential of having a more scaleable cluster solution with the DeltaManager(you'll need to configure the domain interceptor for this).
{'fraction_non_alphanumeric': 0.10246060270942771, 'fraction_numerical': 0.010284766380978711, 'mean_word_length': 3.68064182194617, 'pattern_counts': {'":': 0, '<': 273, '<?xml version=': 2, '>': 273, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 10}, 'pii_count': 6, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7367216', 'n_tokens_mistral': 5310, 'n_tokens_neox': 4912, 'n_words': 1723}