<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" 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" xml:lang="en"><info><title>Cluster Daemon</title></info>

  <section><info><title>Introduction</title></info>

    <para>
      The goal of the cluster daemon is to enable the remote control of the JOnAS clustered instances through a JMX interface.
    </para>
    <para>
      In a cluster configuration, the cluster daemon is the bootstrap of the JOnAS instances.
    </para>
    <para>
      There is at least one cluster daemon instance per machine.
    </para>
    <para>
      <mediaobject>
        <imageobject>
            <imagedata align="center"
                       fileref="../../../../resources/images/clustering/clusterd.png"
                       width="60%" scalefit="1">
            </imagedata>
        </imageobject>
      </mediaobject>
    </para>
  </section>
  <section><info><title>Configuration</title></info>

    <para>
      In the same manner as a classic JOnAS instance, the cluster daemon reads its configuration in a directory pointed to by a JONAS_BASE variable (or JONAS_ROOT if JONAS_BASE is not set). All the default JONAS_BASE subdirectories and files are not required; the mandatory ones are:
    </para>
    <informaltable>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>
              element
            </entry>
            <entry>
              description
            </entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>
              $JONAS_BASE/conf
            </entry>
            <entry>
              Configuration directory
            </entry>
          </row>
          <row>
            <entry>
              $JONAS_BASE/logs
            </entry>
            <entry>
              Log directory
            </entry>
          </row>
          <row>
            <entry>
              $JONAS_BASE/conf/carol.properties
            </entry>
            <entry>
              Carol configuration file describing the protocol and its parameters (used for the JMX interface)
            </entry>
          </row>
          <row>
            <entry>
              $JONAS_BASE/conf/trace.properties
            </entry>
            <entry>
              Trace/Error log configuration file
            </entry>
          </row>
          <row>
            <entry>
              $JONAS_BASE/conf/jonas.properties
            </entry>
            <entry>
              This file must be present for enabling the cluster daemon starting but           its content is not read, the file can be empty
            </entry>
          </row>
          <row>
            <entry>
              $JONAS_BASE/conf/clusterd.xml
            </entry>
            <entry>
              Cluster daemon configuration file, lists the local JOnAS instances and describes           their environment (see below)
            </entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>
  <section><info><title>clusterd.xml</title></info>

    <para>
      The JOnAS instances controlled by a cluster daemon are configured in the
      <code>
        clusterd.xml
      </code>
       file.
    </para>
    <screen>
&lt;?xml version="1.0"?&gt;
&lt;cluster-daemon xmlns="http://www.ow2.org/jonas/ns"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.objectweb.org/jonas/ns
    http://www.ow2.org/jonas/ns/jonas-clusterd_4_8.xsd"&gt;

   &lt;name&gt;cd1&lt;/name&gt;
   &lt;domain-name&gt;domainSample&lt;/domain-name&gt;
   &lt;jonas-interaction-mode&gt;loosely-coupled&lt;/jonas-interaction-mode&gt;

   &lt;server&gt;
      &lt;name&gt;node1&lt;/name&gt;
      &lt;description&gt;Web instance&lt;/description&gt;
      &lt;java-home&gt;/usr/java/jdk-ia32/sun/j2sdk1.4.2_10&lt;/java-home&gt;
      &lt;jonas-root&gt;/home/pelletib/pkg/jonas_root_sb48&lt;/jonas-root&gt;
      &lt;jonas-base&gt;/home/pelletib/tmp/newjc48/jb1&lt;/jonas-base&gt;
      &lt;xprm&gt;&lt;/xprm&gt;
      &lt;auto-boot&gt;false&lt;/auto-boot&gt;
      &lt;jonas-cmd&gt;&lt;/jonas-cmd&gt;
   &lt;/server&gt;

...

&lt;/cluster-daemon&gt;

    </screen>
    <informaltable>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>
              Element
            </entry>
            <entry>
              Description
            </entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>
              name
            </entry>
            <entry>
              Cluster daemon instance name. Used for building the connector url.
            </entry>
          </row>
          <row>
            <entry>
              domain-name
            </entry>
            <entry>
              Domain name to use for launching the JOnAS instance when it is not specified in the start command
            </entry>
          </row>
          <row>
            <entry>
              jonas-interaction-mode
            </entry>
            <entry>
              Starting mode of the JOnAS instances:
              <code>
                loosely-coupled
              </code>
               corresponds to background and
              <code>
                tighly-coupled
              </code>
                     corresponds to foreground.  Typically, when launching in tighly coupled mode a cluster daemon stopping will cause the stopping
                     of the managed JOnAS instance.
            </entry>
          </row>
          <row>
            <entry>
              server/name
            </entry>
            <entry>
              Name of the JOnAS instance
            </entry>
          </row>
          <row>
            <entry>
              server/description
            </entry>
            <entry>
              Description of the JOnAS instance
            </entry>
          </row>
          <row>
            <entry>
              server/java-home
            </entry>
            <entry>
              JDK home directory to be used for launching the JOnAS instance
            </entry>
          </row>
          <row>
            <entry>
              server/jonas-root
            </entry>
            <entry>
              JOnAS binaries directory to be used for launching the JOnAS instance
            </entry>
          </row>
          <row>
            <entry>
              server/jonas-base
            </entry>
            <entry>
              JOnAS configuration directory to use for launching the JOnAS instance
            </entry>
          </row>
          <row>
            <entry>
              server/xprms
            </entry>
            <entry>
              JVM parameters to set when launching the JOnAS instance
            </entry>
          </row>
          <row>
            <entry>
              server/auto-boot
            </entry>
            <entry>
              If true, start the JOnAS instance when launching the cluster daemon
            </entry>
          </row>
          <row>
            <entry>
              server/jonas-cmd
            </entry>
            <entry>
              Optional parameter. If set, specifies the script to use for starting/stopping the JOnAS instance. 
              This user script can set the required environment and perform some pre or post processing. By default, the
              jonas
               command is used.
            </entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>
  <section><info><title>domain.xml</title></info>

    <para>
      The cluster daemons must be specified and associated to the JOnAS instances in the
      <code>
        domain.xml
      </code>
       file for permitting the remote control of the cluster.
    </para>
    <screen>

...
&lt;cluster-daemon&gt;
   &lt;name&gt;cd1&lt;/name&gt;
   &lt;description&gt;cluster daemon 1&lt;/description&gt;
   &lt;location&gt;
      &lt;url&gt;service:jmx:rmi://host/jndi/rmi://host:port/jrmpconnector_cd&lt;/url&gt;
   &lt;/location&gt;
&lt;/cluster-daemon&gt;
...
&lt;server&gt;
  &lt;name&gt;node1&lt;/name&gt;
  &lt;cluster-daemon&gt;cd1&lt;/cluster-daemon&gt;
  ...
&lt;/server&gt;
...
    </screen>
    <para>
      The JMX remote url of the cluster daemon respects the following syntax:
    </para>
    <para>
      service:jmx:rmi://
      <code>
host
      </code>
/jndi/rmi://
      <code>
host
      </code>
:
      <code>
port
      </code>
/
      <code>
protocol
      </code>
connector_
      <code>
name
      </code>
       with the following meanings:
    </para>
    <variablelist>
      <varlistentry>
        <term>
          host
        </term>
      <listitem><para>
        ip alias or ip address of the machine that hosts the cluster daemon   (by default localhost, can be overridden through the carol.properties file)
      </para></listitem>
      </varlistentry>
      <varlistentry>
        <term>
          port
        </term>
      <listitem><para>
        tcp listen port of the registry embedded in the cluster daemon   (by default 1806, can be overridden through the carol.properties file)
      </para></listitem>
      </varlistentry>
      <varlistentry>
        <term>
          protocol
        </term>
      <listitem><para>
        protocol used for accessing the JMX interface (by default irmi, can be overridden   through the carol.properties file)
      </para></listitem>
      </varlistentry>
      <varlistentry>
        <term>
          name
        </term>
      <listitem><para>
        cluster daemon instance name (defined in the clusterd.xml file)
      </para></listitem>
      </varlistentry>
    </variablelist>
  </section>
  <section><info><title>Running the Cluster Daemon</title></info>

    <para>
      The cluster daemon is started using the command
      <code>
        jclusterd
      </code>
      . The possible options are:
    </para>
    <informaltable>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>
              option
            </entry>
            <entry>
              description
            </entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>
              start
            </entry>
            <entry>
              Start the cluster daemon.
            </entry>
          </row>
          <row>
            <entry>
              stop
            </entry>
            <entry>
              Stop the cluster daemon.
            </entry>
          </row>
          <row>
            <entry>
              -DdomainName
            </entry>
            <entry>
              Domain name to be used for starting the JOnAS instance. This value is used when it is defined both here and in the clusterd.xml file.
            </entry>
          </row>
          <row>
            <entry>
              -carolFile &lt;my-carol.properties&gt;
            </entry>
            <entry>
              Path to the carol.properties file to be used. If not specified, the file is loaded from $JONAS_BASE/conf.         If the file is not found, the default values (localhost, 1806, irmi) are used.
            </entry>
          </row>
          <row>
            <entry>
              -confFile &lt;my-clusterd.xml&gt;
            </entry>
            <entry>
              Path to the clusterd.xml file to load. If not specified, the file is loaded from $JONAS_BASE/conf.
            </entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>
  <section><info><title>JMX Interface</title></info>

    <para>
      The cluster daemon provides a JMX interface that enables control of the JOnAS instances. The following operations are available:
    </para>
    <informaltable>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>
              Operation
            </entry>
            <entry>
              Description
            </entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>
              String getServersList()
            </entry>
            <entry>
              Return the list of JOnAS instances
            </entry>
          </row>
          <row>
            <entry>
              int pingJOnAS(String name)
            </entry>
            <entry>
              Ping a JOnAS instance identified by its name
            </entry>
          </row>
          <row>
            <entry>
              void startJOnAS(String name, String domainName, String prm)
            </entry>
            <entry>
              Start a JOnAS instance identified by its name. The parameter
              <code>
                domainName
              </code>
               (optional) provides the capability to specify the domain name. The parameter
              <code>
                prm
              </code>
               (optional) provides the capability to set some JVM parameters.
            </entry>
          </row>
          <row>
            <entry>
              String startAllJOnAS(String domainName, String prm)
            </entry>
            <entry>
              Start all the JOnAS instances known in the cluster daemon configuration. The parameter
              <code>
                domainName
              </code>
               (optional) provides the capability to specify the domain name. The parameter
              <code>
                prm
              </code>
               (optional) provides the capability to set some JVM parameters.
            </entry>
          </row>
          <row>
            <entry>
              void stopJOnAS(String name)
            </entry>
            <entry>
              Stop a JOnAS instance identified by its name
            </entry>
          </row>
          <row>
            <entry>
              String stopAllJOnAS()
            </entry>
            <entry>
              Stop all the JOnAS instances known in the cluster daemon configuration
            </entry>
          </row>
          <row>
            <entry>
              String getJavaHome4Server(String name)
            </entry>
            <entry>
              Get the JAVA_HOME defined for a JOnAS server
            </entry>
          </row>
          <row>
            <entry>
              String getJonasRoot4Server(String name)
            </entry>
            <entry>
              Get the JONAS_ROOT defined for a JOnAS server
            </entry>
          </row>
          <row>
            <entry>
              String getJonasBase4Server(String name)
            </entry>
            <entry>
              Get the JONAS_BASE defined for a JOnAS server
            </entry>
          </row>
          <row>
            <entry>
              void reloadConfiguration()
            </entry>
            <entry>
              Reload the configuration file of the cluster daemon
            </entry>
          </row>
          <row>
            <entry>
              void addServer(String name, String description, String javaHome, String jonasRoot, String jonasBase)
            </entry>
            <entry>
              Add a definition of a JOnAS instance to the cluster daemon configuration. The change is saved in the       configuration file.
            </entry>
          </row>
          <row>
            <entry>
              void removeServer(String name)
            </entry>
            <entry>
              Remove a definition of a JOnAS instance in the cluster daemon configuration. The change is saved in the       configuration file.
            </entry>
          </row>
          <row>
            <entry>
              void modifyServer(String name, String description, String javaHome, String jonasRoot, String jonasBase)
            </entry>
            <entry>
              Modify the definition of a JOnAS instance in the cluster daemon configuration. The change is saved in the       configuration file.
            </entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>
</section>
