<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="clustering.configDomain" 
                       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>domain configuration</title></info>
  <section><info><title>What is a domain</title></info>


    <para>A domain represents an administration perimeter which is under the
    control of an administration authority. It provides at least one common
    administration point for the elements in the domain.</para>

    <para>A JOnAS domain may contain:</para>

    <itemizedlist>
      <listitem>
        <para>JOnAS instances or servers</para>
      </listitem>

      <listitem>
        <para>groups of instances called clusters</para>
      </listitem>

      <listitem>
        <para>cluster daemons, elements used for the remote control of
        instances and clusters</para>
      </listitem>
    </itemizedlist>

    <para>A common administration point is represented by a JOnAS instance
    having a particular configuration and playing the role of <emphasis role="bold">master</emphasis>. A master has the knowledge of the domain
    topology and allows executing administration operations on the rest of the
    servers and on the clusters. It also allows the monitoring of the domain
    elements.</para>

    <para>The administered elements are identified by their names, that have
    to be unique within the domain, and the domain name.</para>

  <section><info><title>Naming policy</title></info>


      <para>Names can be defined in a static way, through the
      <filename>domain.xml</filename> configuration file, or dynamically, by
      starting new elements in the domain. For example, when starting a JOnAS
      instance, the administrator can specify the <emphasis>server
      name</emphasis> using the -n option and the <emphasis>domain
      name</emphasis> by setting the <emphasis role="bold"><property>domain.name</property></emphasis> environment
      property. The uniqueness of the starting server's name is enforced by
      the discovery service.</para>
    </section>
  </section>

  <section><info><title>What is a domain configuration</title></info>


    <para>A domain configuration consists in the domain topology - the
    description of the elements composing the domain (servers, clusters, cluster daemons), and the state of the
    elements in the domain, as viewed from the common administration
    point.</para>

    <para>The domain configuration dynamically evolves by starting or stopping
    servers and by creating or removing clusters in the domain.</para>
  </section>

  <section xml:id="clustering.configDomain.howto"><info><title>How to configure a domain</title></info>


    <section><info><title>Choose the domain name and configure the master</title></info>


      <para>The first step is to choose a name for the domain and to choose a server to represent the
      common administration point. This server must be configured as a master by setting to <property>true</property> the
      <property>jonas.master</property> property. Also, to allow dynamic domain management, add the discovery
      service in the JOnAS services list (<property>jonas.services</property>
      property) in <literal>jonas.properties</literal> file.</para>

      <para>The domain name is not a configuration property for the master
      (neither for any server in the domain), but it has to be specified when
      starting the master.</para>

      <para>Before starting the master, the administrator can define the
      domain's initial topology by editing the <filename class="libraryfile">domain.xml</filename> configuration file.</para>
    </section>

    <section><info><title>Define the domain initial topology</title></info>


      <para>This step is optional. It consists in defining the domain elements
      using the <filename>domain.xml</filename> configuration file located in
      the master's configuration directory. If the administrator has no specific
      configuration needs, it should at least check the name element,
      and set its value to the chosen name. That file
      can also be used to define a default user name and password (that may be encoded) to use when
      connecting to servers and cluster daemons. Moreover, the administrator
      can choose to remove the <filename>domain.xml</filename> file.</para>

      <para>The elements that can be defined in domain.xml are:</para>

      <itemizedlist>
        <listitem>
          <para>server elements: allow to define a server in the domain, or a
          server in a cluster. A server has a name, a description, a location
          and optionally a user name and password as well as an associated
          cluster daemon. The location can be represented by a list of JMX
          remote connector server URLs.</para>
        </listitem>

        <listitem>
          <para>cluster elements: allows to group servers in a logical
          cluster.</para>
        </listitem>

        <listitem>
          <para>cluster daemon elements: allows to define a cluster daemon in
          the domain. A cluster daemon element has a name, a description, a
          location and optionally a user name and password. The location can be
          represented by a list of JMX remote connector server URLs.</para>
        </listitem>
      </itemizedlist>
      <example>
       <title>domain.xml</title>
       <screen>
       
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;domain xmlns="http://www.objectweb.org/jonas/ns" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.objectweb.org/jonas/ns    http://www.objectweb.org/jonas/ns/jonas-domain_4_9.xsd"&gt;
  &lt;name&gt;sampleCluster2Domain&lt;/name&gt;
  &lt;description&gt;A domain for sampleCluster2 servers management&lt;/description&gt;

	&lt;cluster-daemon&gt;
		&lt;name&gt;cd&lt;/name&gt;
		&lt;description&gt;&lt;/description&gt;
		&lt;location&gt;
		   &lt;url&gt;service:jmx:rmi://localhost/jndi/rmi://localhost:1806/jrmpconnector_cd&lt;/url&gt;
		&lt;/location&gt;
	&lt;/cluster-daemon&gt;
	&lt;cluster&gt;
	   &lt;name&gt;mycluster&lt;/name&gt;
	  &lt;description&gt;A cluster for sampleCluster2&lt;/description&gt;
		&lt;server&gt;
		   &lt;name&gt;node1&lt;/name&gt;
		   &lt;location&gt;
			&lt;url&gt;service:jmx:rmi://localhost/jndi/rmi://localhost:2002/jrmpconnector_node1&lt;/url&gt;
		   &lt;/location&gt;
		   &lt;cluster-daemon&gt;cd&lt;/cluster-daemon&gt;
		&lt;/server&gt;
		&lt;server&gt;
		   &lt;name&gt;node2&lt;/name&gt;
		   &lt;location&gt;
			&lt;url&gt;service:jmx:rmi://localhost/jndi/rmi://localhost:2022/jrmpconnector_node2&lt;/url&gt;
		   &lt;/location&gt;
		   &lt;cluster-daemon&gt;cd&lt;/cluster-daemon&gt;
		&lt;/server&gt;
		&lt;server&gt;
		   &lt;name&gt;node3&lt;/name&gt;
		   &lt;location&gt;
			&lt;url&gt;service:jmx:rmi://localhost/jndi/rmi://localhost:2032/jrmpconnector_node3&lt;/url&gt;
		   &lt;/location&gt;
		   &lt;cluster-daemon&gt;cd&lt;/cluster-daemon&gt;
		&lt;/server&gt;
		&lt;server&gt;
		   &lt;name&gt;node4&lt;/name&gt;
		   &lt;location&gt;
			&lt;url&gt;service:jmx:rmi://localhost/jndi/rmi://localhost:2043/jrmpconnector_node4&lt;/url&gt;
		   &lt;/location&gt;
		   &lt;cluster-daemon&gt;cd&lt;/cluster-daemon&gt;
		&lt;/server&gt;
	&lt;/cluster&gt;

&lt;/domain&gt;       
       </screen>
      </example>
    </section>

    <section><info><title>Domain configuration at master start-up</title></info>


      <para>Start the master in the domain:</para>

      <screen>jonas start -n masterName -Ddomain.name=domainName</screen>

      <para>Note that the domain name is specified by setting a
      <envar>domain.name</envar> environment property.</para>

      <para>Once started, the administrator can manage and monitor the
      following elements in the domain through JonasAdmin, or another JMX
      based administration application (such as jconsole), running on the master:</para>

      <itemizedlist>
        <listitem>
          <para>servers declared in the domain.xml file.</para>
        </listitem>

        <listitem>
          <para>other servers already started in the domain having the
          discovery service enabled.</para>
        </listitem>

        <listitem>
          <para>clusters declared in the domain.xml file.</para>
        </listitem>

        <listitem>
          <para>clusters detected by the administration framework</para>
        </listitem>

        <listitem>
          <para>cluster daemons declared in the domain.xml file.</para>
        </listitem>
      </itemizedlist>
    </section>
  </section>
</section>
