<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="services.discovery.config" 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>discovery service configuration</title>
  </info>

  <para>The role of the <emphasis role="bold">discovery</emphasis> service is
  to enable dynamic <emphasis role="bold">domain management</emphasis>. Recall
  that domain management means management of all the servers running in the
  domain, from the common administration point represented by a master
  server.</para>

  <para>The discovery service allows a master to detect servers starting and
  stopping in the domain. Moreover, a master can discover servers there were
  already running in the domain when it started.</para>

  <para>The discovery service implements a <emphasis>greeting</emphasis>
  mechanism to enforce servers' name unicity in the domain. This mechanism
  prevents starting a new server in the domain, if a server having the same
  name is already running in the domain.</para>

  <para>There are two available implementations for the discovery service: one
  based on IP multicast, the other based on JGroups. The former, introduced in
  JOnAS 4, is deprecated. The latter, has the advantage to allow for cluster
  daemons detection.</para>

  <para>All servers and in the domain must choose the same implementation. The
  choice is made upon the implementation class name:</para>

  <screen>###################### JOnAS Discovery service
#
#  Set the name of the implementation class and initialization parameters
# JGropus implementation 
jonas.service.discovery.class=org.ow2.jonas.discovery.jgroups.JgroupsDiscoveryServiceImpl
# Uncomment this to set Multicast implementation
#jonas.service.discovery.class=org.ow2.jonas.discovery.internal.MulticastDiscoveryServiceImpl</screen>

  <section>
    <info>
      <title>Configuration for IP multicast based implementation</title>
    </info>

    <para>You have to provide initialization parameters in jonas.properties
    file for:</para>

    <itemizedlist>
      <listitem>
        <para>Multicast address and port. These must be identical for all
        servers in the domain. Use properties:</para>

        <itemizedlist>
          <listitem>
            <para><property>jonas.service.discovery.multicast.address</property></para>
          </listitem>

          <listitem>
            <para><property>jonas.service.discovery.multicast.port</property></para>
          </listitem>
        </itemizedlist>

        <para>beware that multicast adresses must be consequently allocated
        through the network.</para>
      </listitem>

      <listitem>
        <para>The time-to-live for packets: use property:</para>

        <itemizedlist>
          <listitem>
            <para><property>jonas.service.discovery.ttl</property></para>
          </listitem>
        </itemizedlist>

        <para>this parameter indicates the number of gateway hops for
        packets.</para>

        <itemizedlist>
          <listitem>
            <para>if ttl = 0 the discovery scope is the host (multicast packet
            aren't routed to network interfaces).</para>
          </listitem>

          <listitem>
            <para>if ttl =1 the discovery scope is limited to the subnetworks
            the host is attached to (multicast packets cross the network
            interfaces but will be discarded by the next gateway).</para>
          </listitem>

          <listitem>
            <para>if ttl =N&gt;1 the discovery packets may cross N-1 gateways
            (provided that these gateways are configured to propagate
            multicast packets).</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para>In the case of a master server, the
        <property>jonas.service.discovery.source.port</property> property must
        be set with an available port number.</para>
      </listitem>

      <listitem>
        <para>The greeting mechanism. Use properties:</para>

        <itemizedlist>
          <listitem>
            <para><property>jonas.service.discovery.greeting.port</property></para>
          </listitem>

          <listitem>
            <para><property>jonas.service.discovery.greeting.timeout</property></para>
          </listitem>
        </itemizedlist>

        <para>Note that two servers on the same host must have different
        values in <property>greeting.port</property> property.</para>
      </listitem>
    </itemizedlist>

    <para>Example:</para>

    <screen>jonas.service.discovery.multicast.address=224.224.224.224
jonas.service.discovery.multicast.port=9080
jonas.service.discovery.ttl=1
#  For a master server, configure the client source port with this property
jonas.service.discovery.source.port=9888

#  A multicast greeting message is sent out when discovery service is started.
#  The starting server listens at the port jonas.service.discovery.greeting.port
#  (default 9899) for a response for jonas.service.discovery.greeting.timeout miliseconds
#  (default 1000 ms). If a pre-existing server has the same server name as this one,
#  this server's discovery service will be terminated.
jonas.service.discovery.greeting.port=9899
jonas.service.discovery.greeting.timeout=1000</screen>
  </section>

  <section>
    <info>
      <title>Configuration for JGroups based implementation</title>
    </info>

    <para>JGropups configuration being more complex, a specific configuration
    file have to be used. The name of this file is given by the
    <property>jonas.service.discovery.jgroups.conf </property>property. Two
    other properties have to be initialized:</para>

    <itemizedlist>
      <listitem>
        <para>The name of the JGroups group used by the the discovery service
        to exchange messages.</para>

        <itemizedlist>
          <listitem>
            <para><property>jonas.service.discovery.group.name</property></para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para>The reconnection timeout for the JGroups channel.</para>

        <itemizedlist>
          <listitem>
            <para><property>jonas.service.discovery.group.reconnection.timeout</property></para>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>

    <para>Example:</para>

    <screen>jonas.service.discovery.jgroups.conf=jgroups-discovery.xml
jonas.service.discovery.group.name=JGroupsDiscovery
jonas.service.discovery.group.reconnection.timeout=5000</screen>

    <para>You can find in JOnAS distribution, under<filename>
    JONAS_ROOT/conf</filename>, a <filename>jgroups-discovery.xml</filename>
    file. This file containes a JGroups stack configuration for the UDP
    protocol.</para>

    <para><note>
        <para>Refer to <link
        xlink:href="clustering_guide.html#faq.jgroups">the clustering
        guide</link> for issues related to JGroups.</para>
      </note></para>
  </section>

  <section>
    <info>
      <title>Cluster deamon configuration for discovery</title>
    </info>

    <para>In order to be detected by a master server, a cluster daemon has to
    be properly configured. This is achieved by using a
    <token>discovery</token> entry in the <filename>clusterd.xml</filename>
    configuration file. The configuration properies are:</para>

    <itemizedlist>
      <listitem>
        <para>The JGroups group name</para>
      </listitem>

      <listitem>
        <para>The JGroups stack configuration file name</para>
      </listitem>

      <listitem>
        <para>A <literal>boolean</literal> allowing to activate (if
        <literal>true</literal>) the discovery.</para>
      </listitem>
    </itemizedlist>

    <para>Example:</para>

    <screen>  &lt;discovery&gt;
    &lt;group-name&gt;JGroupsDiscovery&lt;/group-name&gt;
    &lt;stack-file&gt;jgroups-discovery.xml&lt;/stack-file&gt;
    &lt;start-up&gt;true&lt;/start-up&gt;
  &lt;/discovery&gt;</screen>
  </section>
</section>
