<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5CR2//EN"
"http://www.docbook.org/xml/4.5CR2/docbookx.dtd" >

<book xmlns:ci="http://apache.org/cocoon/include/1.0">
	<bookinfo>
		<graphic fileref="logo.jpg"/>
		<productname>Open Source Native XML Database</productname>
        <title>Cluster configuration</title>
		<author>
			<firstname>Piranha</firstname>
			<surname>Group</surname>
		</author>
	</bookinfo>
	<ci:include src="sidebar.xml"/>
	<chapter>
		<title>Cluster Configuration Environment</title>
		<section>
			<title>Overview</title>
			<para>The central configuration file for <application>eXist</application>
            is called <filename>conf.xml</filename>.</para>
			<para>The cluster configuration is performed throught the cluster element</para>
		</section>
		<section>
			<title> cluster </title>
			<para>This section configures the cluster parameters used by eXist during the replica phase.
				An example of configuration for the cluster environment is shown below:</para>
			<example>
				<title>&lt;cluster&gt; entry</title>
				<programlisting format="linespecific"><![CDATA[
                <cluster
	                protocol="UDP(mcast_addr=228.1.2.3;mcast_port=7890;ip_ttl=8;ip_mcast=true;
                      mcast_send_buf_size=800000;mcast_recv_buf_size=150000;
                      ucast_send_buf_size=800000;ucast_recv_buf_size=150000;
                      loopback=false):
                      PING(timeout=2000;num_initial_members=3;up_thread=true;
                      down_thread=true):
		              MERGE2(min_interval=10000;max_interval=20000):
		              FD(shun=true;up_thread=true;down_thread=true;timeout=2500;
                      max_tries=5):
		              VERIFY_SUSPECT(timeout=3000;num_msgs=3;up_thread=true;
                      down_thread=true):
		              pbcast.NAKACK(gc_lag=50;retransmit_timeout=300,600,1200,2400,4800;
		              max_xmit_size=8192;up_thread=true;down_thread=true):
		              UNICAST(timeout=300,600,1200,2400,4800;window_size=100;
                      min_threshold=10;down_thread=true):
		              pbcast.STABLE(desired_avg_gossip=20000;up_thread=true;
                      down_thread=true):
		              FRAG(frag_size=8192;down_thread=true;up_thread=true):
		              pbcast.GMS(join_timeout=5000;join_retry_timeout=2000;shun=true;
                      print_local_addr=true)"
		            dbaUser="admin" dbaPassword="" exclude="/db/system/temp"
                    journalDir="/app/exist/journal_1"/>
                ]]></programlisting>
			</example>
			<section>
				<title>protocol</title>
				<para>The <option>protocol</option> attribute rappresents the protocol layers used by JGROUP. For a deep description of the parameters used in this attributes see the <ulink url="http://www.jgroups.org/javagroupsnew/docs/index.html">jgroup documentation</ulink></para>
                <para>Interesting parameter are :</para>

                <itemizedlist>
                    <listitem><para>UDP/mcast_addr : multicast address</para></listitem>
                    <listitem><para>UDP/bind_addr : binding address (to be configured if node has multiple address )</para></listitem>
                    <listitem><para>UDP/mcast_port : multicast port</para></listitem>
                </itemizedlist>

			</section>
			<section>
				<title>User account</title>
				<para>The <option>dbaUser</option> and <option>dbaPassword</option> attributes are the account info used by the cluster layer during the replica behaviour. Each actions replicated on cluster environment are performed with this account information.</para>
			</section>
			<section>
				<title>exclude</title>
				<para>Some collections should be signed as no-replicated collections i.e. during the replica phase eXist cluster environment doesn't send events based on these collections, <option>colon</option> is the separator char when more than one collection is added.</para>
			</section>
			<section>
				<title>journalDir</title>
				<para>Specifies the folder where the eXist cluster node saves its journal file.</para>
                <para>Directory is automatically created if it doesn't exist</para>
                <para>If no journaldir is specifyed, journal is disabled.</para>
                <para>For more information on the cluster journal behaviour see <ulink url="journal.xml">Journal cluster behaviour</ulink>.</para>
			</section>
			<section>
				<title>journal configuration</title>
				<para>Some optional parameters can be added in order to customize the journal behaviour.</para>
                <section>
                    <title>journalMaxItem</title>
                    <para>
                    Max items that the index file can hold (default =
                    65000). This value is the maximum number of event
                    that a node can retrieve from master, if the node is
                    disaligned more than this event, a manual realigment
                    must be executed.
                    </para>
                </section>
                <section>
                 <title>journalIndexShift</title>
                 	<para>
                    Each time the JGroup cluster creates a new coordinator, the new cordinator realign its journal index adding journalIndexShift element to it.
                	</para>
                </section>
			</section>
		</section>
		<section>
			<title>Cluster console</title>
			<para>It's created a link to cluster console on sidebar (<ulink url="cluster">Cluster status</ulink>)</para>
		</section>
	</chapter>
</book>