<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="commands.jonas" 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">
  <title>jonas command</title>

  <para>This command provides the capability to start, stop, or administrate
  <xi:include href="../variables.xml" xpointer="appserver" /> servers.</para>

  <para>The following two scripts can be reviewed and possibly modified for
  assistance with problems or for obtaining additional information:</para>

  <itemizedlist>
    <listitem>
      <para><emphasis role="bold">jonas</emphasis> for UNIX systems</para>
    </listitem>

    <listitem>
      <para><emphasis role="bold">jonas.bat </emphasis>for WINDOWS
      systems</para>
    </listitem>
  </itemizedlist>

  <para>There are five different sub-commands, that depend on the first
  mandatory argument: start, stop, admin, version, check</para>

  <section>
    <title>jonas start</title>

    <para>Command allowing to start a <xi:include href="../variables.xml"
    xpointer="appserver" /> server.</para>

    <section>
      <title>Options</title>

      <cmdsynopsis>
        <command xml:id="jonas.start">jonas start</command>

        <arg>-standby</arg>

        <arg>-fg</arg>

        <arg>-bg</arg>

        <arg>-win</arg>

        <arg>-tui</arg>

        <arg>-gui</arg>

        <arg>-dev</arg>

        <arg>-clean</arg>

        <arg>-n name</arg>

        <arg>-target server</arg>

        <arg>-Ddomain.name=domain</arg>
      </cmdsynopsis>

      <variablelist>
        <varlistentry>
          <term>-standby</term>

          <listitem>
            <para>Start a minimal <xi:include href="../variables.xml"
            xpointer="appserver" /> server with only mandatory services :
            <emphasis>registry</emphasis>, <emphasis>jmx</emphasis>. If the
            <emphasis>discovery</emphasis> service is configured in the JOnAS
            service list, it will bo started too.</para>

            <para>When the server startup is done, <xi:include
            href="../variables.xml" xpointer="appserver" /> should be in the
            STANDBY state. In this state, the server can either be stopped
            (see <emphasis>jonas stop</emphasis> command) or be fully started
            by executing the <emphasis>jonas start</emphasis> command to reach
            the RUNNING state.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-bg</term>

          <listitem>
            <para>Start the server in background mode</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-win</term>

          <listitem>
            <para>Start the server in a new window</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-tui</term>

          <listitem>
            <para>Start the Apache Felix TUI (force foreground mode)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-gui</term>

          <listitem>
            <para>Start the Apache Felix GUI</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-dev</term>

          <listitem>
            <para>This option allows to start a <xi:include
            href="../variables.xml" xpointer="appserver" /> server by using
            bundles present in the default maven repository instead of bundles
            under <emphasis>$JONAS_ROOT/lib/bundles</emphasis>. A specific
            maven repository location can be given by setting the
            <emphasis>m2.repository</emphasis> property</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-clean</term>

          <listitem>
            <para>Clean the Apache Felix cache before starting a <xi:include
            href="../variables.xml" xpointer="appserver" /> server</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-n name</term>

          <listitem>
            <para>Set the server name. It must be unique in the domain. By
            default, the server name is <emphasis>jonas</emphasis></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-target server</term>

          <listitem>
            <para>This option allows to start another server or cluster (group
            of servers) in the domain.</para>

            <para>This action is to be executed in the environment of a
            running master server who's name is given by the -n option. In
            order to start a target server or cluster, the following
            conditions have to be met:</para>

            <itemizedlist>
              <listitem>
                <para>the target must belong to the domain (has to be defined
                in the domain's map)</para>
              </listitem>

              <listitem>
                <para>a cluster daemon has to be running on the target's host
                and it has to be aware of the target (see cluster daemon
                configuration)</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-Ddomain.name=domain</term>

          <listitem>
            <para>Set the name of the management domain to which the server
            belongs</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section>
      <title>Description</title>

      <para>Start a <xi:include href="../variables.xml"
      xpointer="appserver" /> server.</para>

      <para>The process can be run in the foreground, in the background, or in
      a new window. If the background option is chosen (default option),
      control is given back to the caller only when the server is
      ready.</para>

      <para>The gui and tui options allow to interact with the OSGi
      framework.</para>

      <para>The name of the management domain to which the server belongs is
      given by the <emphasis>domain.name</emphasis> propery, or by the server
      name if this property is not defined.</para>
    </section>
  </section>

  <section>
    <title>jonas stop</title>

    <para>Command allowing to stop a <xi:include href="../variables.xml"
    xpointer="appserver" /> server.</para>

    <section>
      <title>Options</title>

      <cmdsynopsis>
        <command xml:id="jonas.stop">jonas stop</command>

        <arg>-standby</arg>

        <arg>-n name</arg>

        <arg>-target server</arg>

        <arg>-Ddomain.name=domain</arg>
      </cmdsynopsis>

      <variablelist>
        <varlistentry>
          <term>-standby</term>

          <listitem>
            <para>Allows to stop all services except the mandatory ones
            (<emphasis>registry</emphasis> and <emphasis>jmx</emphasis>). When
            the server stop is done, <xi:include href="../variables.xml"
            xpointer="appserver" /> should be in the STANDBY state and the JVM
            is still running. In this state, the server can either be started
            (see <emphasis>jonas start </emphasis>command) or be fully stopped
            by executing the <emphasis>jonas stop</emphasis> command to stop
            all services and the JVM.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-n name</term>

          <listitem>
            <para>Set the name of the server to stop. By default, the server
            name is <emphasis>jonas</emphasis></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-target server</term>

          <listitem>
            <para>This option allows to stop another server or cluster (group
            of servers) in the domain.</para>

            <para>This action is to be executed in the environment of a
            running master server who's name is given by the -n option. In
            order to start a target server or cluster, the following
            conditions have to be met:</para>

            <itemizedlist>
              <listitem>
                <para>the target must belong to the domain (has to be defined
                in the domain's map)</para>
              </listitem>

              <listitem>
                <para>a cluster daemon has to be running on the target's host
                and it has to be aware of the target (see cluster daemon
                configuration)</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>-Ddomain.name=domain</term>

          <listitem>
            <para>Set the name of the management domain to which the server
            belongs</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section>
      <title>Description</title>

      <para>Stop a running or a standby <xi:include href="../variables.xml"
      xpointer="appserver" /> server by stopping in a first time all services
      and then the JVM.</para>

      <para>The name of the management domain to which the server belongs is
      given by the <emphasis>domain.name</emphasis> propery, or by the server
      name if this property is not defined.</para>
    </section>
  </section>

  <section xml:id="commands.jonas.jonasadmin">
    <title>jonas admin</title>

    <para>Command allowing to administer a <xi:include href="../variables.xml"
    xpointer="appserver" /> server.</para>

    <section>
      <title>Synopsis</title>

      <cmdsynopsis>
        <command>jonas admin</command>

        <arg>-win</arg>

        <arg>-n name</arg>

        <arg>-registry</arg>

        <arg>-protocol</arg>

        <arg>-username</arg>

        <arg>-password</arg>

        <arg rep="repeat">admin options</arg>
      </cmdsynopsis>
    </section>

    <section>
      <title>Description</title>

      <para>Administer a <xi:include href="../variables.xml"
      xpointer="appserver" /> server.</para>

      <para>The connection to the server is established through JMX. The
      default JMX service URL is build from the information contained in the
      local <emphasis>$JONAS_BASE/conf/carol.properties</emphasis> file. You
      can customize the JMX service URL by specifying the server name, the
      registry URL and the protocol name.</para>

      <para>Set the username and the password if the connection to the remote
      <xi:include href="../variables.xml" xpointer="appserver" /> server
      requires an authentication.</para>

      <para>Used without any administration option, this command will prompt
      the user for an administration command (interactive mode). Each
      administration command exists in a non-interactive mode, to be used in
      shell or bat scripts for example.</para>
    </section>

    <section>
      <title>Options</title>

      <para>Options can be divided in two categories, the connection options
      and the administration options.</para>

      <section>
        <title>Connection options</title>

        <variablelist>
          <varlistentry>
            <term>-win</term>

            <listitem>
              <para>Administer the server in a new window</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-n name</term>

            <listitem>
              <para>Set the name of the server to administer. By default, the
              server name is <emphasis>jonas</emphasis></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-username</term>

            <listitem>
              <para>Set the username when authentication is required</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-password</term>

            <listitem>
              <para>Set the password when authentication is required</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-registry</term>

            <listitem>
              <para>Set the registry URL</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-protocol</term>

            <listitem>
              <para>Set the protocol name (jrmp, iiop or irmi)</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </section>

      <section>
        <title>Administration options</title>

        <variablelist>
          <varlistentry>
            <term>-?</term>

            <listitem>
              <para>Prints the help message</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-a filepath</term>

            <listitem>
              <para>Deploy an application from a given filepath on the current
              server, or on another target in the domain if the current server
              is a master. Note that the filepath must be an absolute
              path</para>

              <para>The application can be one of the following :</para>

              <para><itemizedlist>
                  <listitem>
                    <para>a standard <emphasis role="bold">.jar</emphasis>
                    file. This will lead to the creation of a new EJB
                    container.</para>
                  </listitem>

                  <listitem>
                    <para>a standard <emphasis role="bold">.war</emphasis>
                    file containing a WEB module.</para>
                  </listitem>

                  <listitem>
                    <para>a standard <emphasis role="bold">.ear</emphasis>
                    file containing a complete J2EE application.</para>
                  </listitem>

                  <listitem>
                    <para>a standard <emphasis role="bold">.rar</emphasis>
                    file containing a RAR module.</para>
                  </listitem>
                </itemizedlist></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-r filepath</term>

            <listitem>
              <para>Undeploy a previously deployed application from the
              current server or from the specified target if the current
              server is a master</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-gc</term>

            <listitem>
              <para>Run the garbage collector on the current <xi:include
              href="../variables.xml" xpointer="appserver" /> server</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-passivate</term>

            <listitem>
              <para>Passivate all entity bean instances. This affects only
              instances outside transaction</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-e</term>

            <listitem>
              <para>List the properties of the current <xi:include
              href="../variables.xml" xpointer="appserver" /> server</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-j</term>

            <listitem>
              <para>List the registered JNDI names, as seen by the current
              <xi:include href="../variables.xml" xpointer="appserver" />
              server</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-l</term>

            <listitem>
              <para>List the beans currently loaded by the current <xi:include
              href="../variables.xml" xpointer="appserver" /> server</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-synch</term>

            <listitem>
              <para>Synchronize the entity bean instances on the current
              <xi:include href="../variables.xml" xpointer="appserver" />
              server. Note that this affects only the instances that are not
              involved in a transaction</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-debug topic</term>

            <listitem>
              <para>Set the logging level for the given topic to DEBUG</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-tt timeout</term>

            <listitem>
              <para>Change the default timeout for transactions. Timeout is in
              seconds</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>-ping [-timeout seconds]</term>

            <listitem>
              <para>Wait until the <xi:include href="../variables.xml"
              xpointer="appserver" /> server is available</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>Each jonas admin option has its equivalent in the interactive
        mode. To enter interactive mode and access the following list of
        subcommands, type jonas admin with only connection options (without
        administration options). To exit from interactive mode, use the exit
        command.</para>

        <informaltable>
          <tgroup cols="2">
            <thead>
              <row>
                <entry align="center">interactive command</entry>

                <entry align="center">options</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry><emphasis role="bold">a</emphasis>ddbeans</entry>

                <entry><emphasis role="bold">-a filepath</emphasis></entry>
              </row>

              <row>
                <entry><emphasis role="bold">e</emphasis>nv</entry>

                <entry><emphasis role="bold">-e</emphasis></entry>
              </row>

              <row>
                <entry><emphasis role="bold">g</emphasis>c</entry>

                <entry><emphasis role="bold">-gc</emphasis></entry>
              </row>

              <row>
                <entry><emphasis role="bold">h</emphasis>elp</entry>

                <entry><emphasis role="bold">-?</emphasis></entry>
              </row>

              <row>
                <entry><emphasis role="bold">j</emphasis>ndinames</entry>

                <entry><emphasis role="bold">-j</emphasis></entry>
              </row>

              <row>
                <entry><emphasis role="bold">l</emphasis>istbeans</entry>

                <entry><emphasis role="bold">-l</emphasis></entry>
              </row>

              <row>
                <entry><emphasis role="bold">r</emphasis>emovebeans</entry>

                <entry><emphasis role="bold">-r filepath</emphasis></entry>
              </row>

              <row>
                <entry><emphasis role="bold">sync</emphasis></entry>

                <entry><emphasis role="bold">-sync</emphasis></entry>
              </row>

              <row>
                <entry><emphasis role="bold">tr</emphasis>ace</entry>

                <entry><emphasis role="bold">-debug topic</emphasis></entry>
              </row>

              <row>
                <entry><emphasis role="bold">tt</emphasis>imeout</entry>

                <entry><emphasis role="bold">-tt timeout</emphasis></entry>
              </row>

              <row>
                <entry><emphasis role="bold">quit</emphasis></entry>

                <entry>exit interactive mode</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </section>
    </section>
  </section>

  <section>
    <title>jonas version</title>

    <para>Command allowing to know the version of the <xi:include
    href="../variables.xml" xpointer="appserver" /> server.</para>

    <section>
      <title>Synopsis</title>

      <cmdsynopsis>
        <command>jonas version</command>
      </cmdsynopsis>
    </section>

    <section>
      <title>Description</title>

      <para>Print the current version of the <xi:include
      href="../variables.xml" xpointer="appserver" /> server.</para>
    </section>
  </section>

  <section xml:id="commands.jonas.jonascheck">
    <title>jonas check</title>

    <para>Command allowing to check that the <xi:include
    href="../variables.xml" xpointer="appserver" /> environment is correctly
    set .</para>

    <section>
      <title>Synopsis</title>

      <cmdsynopsis>
        <command>jonas check</command>

        <arg>-help</arg>
      </cmdsynopsis>
    </section>

    <section>
      <title>Description</title>

      <para>Check that the <xi:include href="../variables.xml"
      xpointer="appserver" /> server is well installed. Below the result of
      the jonas check command :</para>

      <programlisting>Checking jonas.properties file...
- jonas.services : registry,jmx,jtm,db,security,resource,ejb2,ejb3,jaxws,web,ear,depmonitor

Checking JORAM configuration...

Checking port availability...

The JOnAS environment seems correct.</programlisting>
    </section>
  </section>
  
  
  <section xml:id="commands.jonas.jcl">
    <title>jcl</title>

    <para>Command allowing to start or stop a cluster of <xi:include
    href="../variables.xml" xpointer="appserver" /> instances on the local machine.</para>

    <section>
      <title>Synopsis</title>

      <cmdsynopsis>
        <command>jcl</command>

        <arg>status|start|stop|kill</arg>

      </cmdsynopsis>
    </section>

    <section>
      <title>Description</title>

      <para>The command is a wrapper of the <filename>jonas</filename> command enabling to control a local cluster previously
      built with the <link
     linkend="commands.newjc"> <filename>newjc</filename></link> command.</para>
     
      <para>The names and paths of the cluster instances are built from a set of variables (JCL_NUMBER_OF_NODES, JCL_BASE_PREFIX, JCL_NODE_NAME_PREFIX, ...). 
      The list of variable in an example is given below.</para>
 
      <programlisting>JCL_NUMBER_OF_NODES=2

JCL_CLUSTER_DAEMON_DIR=/home/jonas/njc51/cd
JCL_BASE_PREFIX=/home/jonas/njc51/jb

JCL_NODE_NAME_PREFIX=node
JCL_DOMAIN_NAME=sampleCluster2Domain

JCL_DB_DIR=/home/jonas/njc51/db
JCL_DB_NAME=db

JCL_MASTER_DIR=/home/jonas/njc51/master
JCL_MASTER_NAME=master

export JCL_MASTER_NAME JCL_MASTER_DIR JCL_DB_NAME JCL_DB_DIR JCL_DOMAIN_NAME JCL_NODE_NAME_PREFIX
export JCL_NUMBER_OF_NODES JCL_CLUSTER_DAEMON_DIR JCL_BASE_PREFIX

</programlisting>

     <para>The control commands (status/start/stop/...) are applied for all the instances by default. A particular instance or a subset of instances 
      can be specified with the <filename>-n</filename> argument.</para>
      
      <para> Example for starting node1 and node2:</para>
 
      <programlisting>$JONAS_ROOT/bin/jcl.sh -n 1,2 start</programlisting>
     
      <para> Example for getting the status for node1, node2, node3 and node4:</para>
      
      <programlisting>$JONAS_ROOT/bin/jcl.sh -n 1-4 status</programlisting>
      
    </section>
  </section>
    
</chapter>
