<?xml version="1.0"?>
<!DOCTYPE entities [
<!ENTITY %  entities SYSTEM  "commonEntities.xml">
%entities;
]>
<!--

 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.

-->

<chapter id="Java-Broker-Getting-Started">
  <title>Getting Started</title>
  <para>This section describes how to start the Java Broker for the first time.</para>
  <section role="h2" id="Java-Broker-Getting-Started-Starting">
    <title>Starting/Stopping the Broker</title>
    <para>To start the Broker, use the <command>qpid-server</command> script (UNIX) or <command>qpid-server.bat</command> (Windows)
      provided within distribution.</para>
  </section>
  <section role="h2" id="Java-Broker-Getting-Started-Starting-Stopping-Windows">
    <title>Starting/Stopping on Windows</title>
    <para>Firstly change to the installation directory used during the <link linkend="Java-Broker-Installation-InstallationWindows">installation</link>
      and ensure that the <link linkend="Java-Broker-Installation-InstallationWindows-SettingQPIDWORK">QPID_WORK environment variable is set</link>.</para>
    <para>Now use the <command>qpid-server.bat</command> to start the server</para>
    <programlisting><![CDATA[bin\qpid-server.bat]]></programlisting>
    <para>Output similar to the following will be seen:</para>
    <screen>[Broker] BRK-1006 : Using configuration : C:\qpid\qpid-broker-&qpidCurrentRelease;\etc\config.xml
[Broker] BRK-1007 : Using logging configuration : C:\qpid\qpid-broker-&qpidCurrentRelease;\etc\log4j.xml
[Broker] BRK-1001 : Startup : Version: &qpidCurrentRelease; Build: 1411386
[Broker] BRK-1010 : Platform : JVM : Sun Microsystems Inc. version: 1.6.0_24-b07 OS : Windows 7 version: 6.1 arch: amd64
[Broker] BRK-1011 : Maximum Memory : 1,069,416,448 bytes
[Broker] MNG-1001 : Web Management Startup
[Broker] MNG-1002 : Starting : HTTP : Listening on port 8080
[Broker] MNG-1004 : Web Management Ready
[Broker] MNG-1001 : JMX Management Startup
[Broker] MNG-1002 : Starting : RMI Registry : Listening on port 8999
[Broker] MNG-1002 : Starting : JMX RMIConnectorServer : Listening on port 9099
[Broker] MNG-1004 : JMX Management Ready
[Broker] BRK-1002 : Starting : Listening on TCP port 5672
[Broker] BRK-1004 : Qpid Broker Ready</screen>
    <para>The BRK-1004 message confirms that the Broker is ready for work.  The MNG-1002 and BRK-1002 confirm the ports to
      which the Broker is listening (for HTTP/JMX management and AMQP respectively).</para>
    <para>To stop the Broker, use Control-C or use the Shutdown MBean made from the <xref
        linkend="Java-Broker-Configuring-And-Managing-JMX"/></para>
  </section>
  <section role="h2" id="Java-Broker-Getting-Started-Starting-Stopping-Unix">
    <title>Starting/Stopping on Unix</title>
    <para>Firstly change to the installation directory used during the <link linkend="Java-Broker-Installation-InstallationUnix">installation</link>
      and ensure that the <link linkend="Java-Broker-Installation-InstallationUnix-SettingQPIDWORK">QPID_WORK environment variable is set</link>.</para>
    <para>Now use the <command>qpid-server</command> script to start the server:</para>
    <programlisting><![CDATA[bin\qpid-server]]></programlisting>
    <para>Output similar to the following will be seen:</para>
    <screen>[Broker] BRK-1006 : Using configuration : /usr/local/qpid/qpid-broker-&qpidCurrentRelease;/etc/config.xml
[Broker] BRK-1007 : Using logging configuration : /usr/local/qpid/qpid-broker-&qpidCurrentRelease;/etc/log4j.xml
[Broker] BRK-1001 : Startup : Version: &qpidCurrentRelease; Build: 1411386
[Broker] BRK-1010 : Platform : JVM : Apple Inc. version: 1.6.0_35-b10-428-11M3811 OS : Mac OS X version: 10.8.2 arch: x86_64
[Broker] BRK-1011 : Maximum Memory : 1,070,399,488 bytes
[Broker] MNG-1001 : Web Management Startup
[Broker] MNG-1002 : Starting : HTTP : Listening on port 8080
[Broker] MNG-1004 : Web Management Ready
[Broker] MNG-1001 : JMX Management Startup
[Broker] MNG-1002 : Starting : RMI Registry : Listening on port 8999
[Broker] MNG-1002 : Starting : JMX RMIConnectorServer : Listening on port 9099
[Broker] MNG-1004 : JMX Management Ready
[Broker] BRK-1002 : Starting : Listening on TCP port 5672
[Broker] BRK-1004 : Qpid Broker Ready</screen>
    <para>The BRK-1004 message confirms that the Broker is ready for work.  The MNG-1002 and BRK-1002 confirm the ports to
    which the Broker is listening (for HTTP/JMX management and AMQP respectively).</para>
    <para>To stop the Broker, use Control-C from the controlling shell, use the
        <command>bin/qpid.stop</command> script, use <command>kill -TERM &lt;pid&gt;</command>, or
      the Shutdown MBean from <xref linkend="Java-Broker-Configuring-And-Managing-JMX"/></para>
  </section>
  <section role="h2" id="Java-Broker-Getting-Started-LogFile">
    <title>Log file</title>
    <para>The Java Broker writes a log file to record both details of its normal operation and any exceptional
      conditions.  By default the log file is written within the log subdirectory beneath the work directory
      - <computeroutput>$QPID_WORK/log/qpid.log</computeroutput> (UNIX) and
      <computeroutput>%QPID_WORK%\log\qpid.log</computeroutput> (Windows).</para>
    <para>For details of how to control the logging, see <xref linkend="Java-Broker-Runtime-Log-Files"/></para>
  </section>
  <section role="h2" id="Java-Broker-Getting-Started-CommandLine">
    <title>Using the command line</title>
    <para>The Java Broker understands a number of command line options which may be used to override the configuration.</para>
    <para>To see usage information for all command line options, use the option <option>--help</option></para>
    <programlisting><![CDATA[bin/qpid-server --help]]></programlisting>
    <screen><![CDATA[usage: Qpid [-cic <path>] [-h] [-icp <path>] [-l <file>] [-mm] [-mmhttp <port>]
            [-mmjmx <port>] [-mmpass <password>] [-mmqv] [-mmrmi <port>] [-os]
            [-sp <path>] [-st <type>] [-v] [-w <period>]
 -cic <path>                                    create a copy of the initial config
 --create-initial-config <path>                 file, either to an optionally specified
                                                file path, or as initial-config.json
                                                in the current directory

 -h,                                            print this message
 --help

 -icp  <path>                                   set the location of initial JSON config
 --initial-config-path <path>                   to use when creating/overwriting a
                                                broker configuration store

 -l <file>                                      use the specified log4j xml configuration
 --logconfig <file>                             file. By default looks for a file named
                                                etc/log4j.xml in the same directory as
                                                the configuration file

 -mm                                            start broker in management mode,
                                                disabling the AMQP ports

 -mmhttp <port>                                 override http management port in
 --management-mode-http-port <port>             management mode

 -mmjmx                                         override jmx connector port in
 --management-mode-jmx-connector-port <port>    management mode

 -mmpass  <password>                            Set the password for the management
 --management-mode-password <password>          mode user mm_admin

 -mmqv                                          make virtualhosts stay in the quiesced
 --management-mode-quiesce-virtualhosts         state during management mode.

 -mmrmi <port>                                  override jmx rmi registry port in
 --management-mode-rmi-registry-port <port>     management mode

 -os                                            overwrite the broker configuration store
 --overwrite-store                              with the current initial configuration

 -sp <path>                                     use given configuration store location
 --store-path <path>

 -st <type>                                     use given broker configuration store type
 --store-type <type>

 -v                                             print the version information and exit
 --version

 -w <period>                                    monitor the log file configuration file
 --logwatch <period>                            for changes. Units are seconds. Zero
                                                means do not check for changes.
]]></screen>
  </section>

</chapter>
