# Cluster Daemon

## Introduction

The intent of the cluster daemon is to enable the remote control of the JOnAS clustered instances through a JMX interface.

In a cluster configuration, the cluster daemon is the bootstrap of the JOnAS instances.

There is at least one cluster daemon instance per machine.

## Configuration

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:

element | description
--- | ---
$JONAS_BASE/conf | Configuration directory
$JONAS_BASE/logs | Log directory
$JONAS_BASE/conf/carol.properties | Carol configuration file describing the protocol and its parameters (used for the JMX interface)
$JONAS_BASE/conf/trace.properties | Trace/Error log configuration file
$JONAS_BASE/conf/jonas.properties | This file must be present for enabling the cluster daemon starting but its content is not read, the file can be empty
$JONAS_BASE/conf/clusterd.xml | Cluster daemon configuration file, lists the local JOnAS instances and describes their environment (see below)

## clusterd.xml

The JOnAS instances controlled by a cluster daemon are configured in the `clusterd.xml` file.

    <?xml version="1.0"?>
    <cluster-daemon 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-clusterd_4_8.xsd">

       <name>cd1</name>
       <domain-name>domainSample</domain-name>
       <jonas-interaction-mode>loosely-coupled</jonas-interaction-mode>

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

    ...

    </cluster-daemon>

element | description
--- | ---
name | Cluster daemon instance name. Used for building the connector url.
domain-name | Domain name to use for launching the JOnAS instance when it is not specified in the start command
jonas-interaction-mode | Starting mode of the JOnAS instances: `loosely-coupled` corresponds to background and `tighly-coupled` corresponds to foreground
server/name | Name of the JOnAS instance
server/description | Description of the JOnAS instance
server/java-home | JDK home directory to use for launching the JOnAS instance
server/jonas-root | JOnAS binaries directory to use for launching the JOnAS instance
server/jonas-base | JOnAS configuration directory to use for launching the JOnAS instance
server/xprms | JVM parameters to set when launching the JOnAS instance
server/auto-boot | If true, start the JOnAS instance when launching the cluster daemon
server/jonas-cmd | Optional parameter. If set, specifies the script to use for starting/stopping the JOnAS instance. This user script can set the required environnement and perform some pre or post processing. By default, the jonas command is used.

## domain.xml

The cluster daemons must be specified and associated to the JOnAS instances in the `domain.xml` file for permitting the remote control of the cluster.

    ...
    <cluster-daemon>
       <name>cd1</name>
       <description>cluster daemon 1</description>
       <location>
          <url>service:jmx:rmi://host/jndi/rmi://host:port/jrmpconnector_cd</url>
       </location>
    </cluster-daemon>
    ...
    <server>
      <name>node1</name>
      <cluster-daemon>cd1</cluster-daemon>
      ...
    </server>
    ...

The JMX remote url of the cluster daemon adheres to the following syntax:

service:jmx:rmi://`host`/jndi/rmi://`host`:`port`/`protocol`connector_`name` with the following meanings:

- `host`: ip alias or ip address of the machine that hosts the cluster daemon (by default localhost, can be overridden through the carol.properties file)
- `port`: tcp listen port of the registry embedded in the cluster daemon (by default 1806, can be overridden through the carol.properties file)
- `protocol`: protocol used for accessing the JMX interface (by default irmi, can be overridden through the carol.properties file)
- `name`: cluster daemon instance name (defined in the clusterd.xml file)

## Running the Cluster Daemon

The cluster daemon is started using the command `jclusterd`. The possible options are:

option | description
--- | ---
start | Start the cluster daemon.
stop | Stop the cluster daemon.
-DdomainName | Domain name to use for starting the JOnAS instance. This value is used when it is defined both here and in the clusterd.xml file.
-carolFile | Path to the carol.properties file to use. 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.
-confFile | Path to the clusterd.xml file to load. If not specified, the file is loaded from $JONAS_BASE/conf.

## JMX Interface

The cluster daemon provides a JMX interface that enables control of the JOnAS instances. The following operations are available:

Operation | Description
--- | ---
String getServersList() | Return the list of JOnAS instances
int pingJOnAS(String name) | Ping a JOnAS instance identified by its name
void startJOnAS(String name) | Start a JOnAS instance identified by its name
String startAllJOnAS(String domainName, String prm) | Start all the JOnAS instances known in the cluster daemon configuration. The parameter `domainName` (optional) enables the ability to specifiy the domain name. The parameter `prm` (optional) enables the ability to set some JVM parameters.
void stopJOnAS(String name) | Stop a JOnAS instance identified by its name
String stopAllJOnAS() | Stop all the JOnAS instances known in the cluster daemon configuration
String getJavaHome4Server(String name) | Get the JAVA_HOME defined for a JOnAS server
String getJonasRoot4Server(String name) | Get the JONAS_ROOT defined for a JOnAS server
String getJonasBase4Server(String name) | Get the JONAS_BASE defined for a JOnAS server
void reloadConfiguration() | Reload the configuration file of the cluster daemon
void addServer(String name, String description, String javaHome, String jonasRoot, String jonasBase) | Add a definition of a JOnAS instance to the cluster daemon configuration. The change is saved in the configuration file.
void removeServer(String name) | Remove a definition of a JOnAS instance in the cluster daemon configuration. The change is saved in the configuration file.
void modifyServer(String name, String description, String javaHome, String jonasRoot, String jonasBase) | Modify the definition of a JOnAS instance in the cluster daemon configuration. The change is saved in the configuration file.