You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ro...@apache.org on 2012/08/12 21:19:53 UTC

svn commit: r1372183 [11/19] - in /qpid/site/docs/books/trunk_new: ./ AMQP-Messaging-Broker-CPP-Book/ AMQP-Messaging-Broker-CPP-Book/html/ AMQP-Messaging-Broker-CPP-Book/html/css/ AMQP-Messaging-Broker-CPP-Book/html/images/ AMQP-Messaging-Broker-CPP-Bo...

Added: qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/Qpid-JMX-Management-Console.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/Qpid-JMX-Management-Console.html?rev=1372183&view=auto
==============================================================================
--- qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/Qpid-JMX-Management-Console.html (added)
+++ qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/Qpid-JMX-Management-Console.html Sun Aug 12 19:19:49 2012
@@ -0,0 +1,1132 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 3.  Qpid JMX Management Console</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="up" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="prev" href="Java-Broker-Slow-Consumer-Disconnect.html" title="2.11. Slow Consumer Disconnect - User Guide"><link rel="next" href="QpidJavaBroker-ManagementTools.html" title="Chapter 4. Management Tools"></head><body><div class="container" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><DIV class="header"><DIV class="logo"><H1>Apache Qpid™</H1><H2>Open Source AMQP Messaging</H2></DIV></DIV><DIV class="menu_box"><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Apache Qpid</H3><UL><
 LI><A href="http://qpid.apache.org/index.html">Home</A></LI><LI><A href="http://qpid.apache.org/download.html">Download</A></LI><LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI><LI><A href="http://www.apache.org/licenses/">License</A></LI><LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Documentation</H3><UL><LI><A href="http://qpid.apache.org/documentation.html#doc-release">0.14 Release</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Community</H3><UL><LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI><LI><A href="http://qpid.apache.org/source_repository.ht
 ml">Source Repository</A></LI><LI><A href="http://qpid.apache.org/mailing_lists.html">Mailing Lists</A></LI><LI><A href="https://cwiki.apache.org/qpid/">Wiki</A></LI><LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI><LI><A href="http://qpid.apache.org/people.html">People</A></LI><LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Developers</H3><UL><LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI><LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About AMQP</H3><UL><LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_b
 ody"><H3>About Apache</H3><UL><LI><A href="http://www.apache.org">Home</A></LI><LI><A href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</A></LI><LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI><LI><A href="http://www.apache.org/security/">Security</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV></DIV><div class="main_text_area"><div class="main_text_area_top"></div><div class="main_text_area_body"><DIV class="breadcrumbs"><span class="breadcrumb-link"><a href="index.html">AMQP Messaging Broker (Implemented in Java)</a></span> &gt; <span class="breadcrumb-node">
+    Qpid JMX Management Console
+  </span></DIV><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Qpid-JMX-Management-Console"></a>Chapter 3. 
+    Qpid JMX Management Console
+  </h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="Qpid-JMX-Management-Console.html#QpidJMXManagementConsole-QpidJMXManagementConsole">3.1.  Qpid JMX Management Console </a></span></dt><dd><dl><dt><span class="section"><a href="Qpid-JMX-Management-Console.html#QpidJMXManagementConsole-Overview">3.1.1. 
+	Overview
+      </a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="QpidJMXManagementConsole-QpidJMXManagementConsole"></a>3.1.  Qpid JMX Management Console </h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="QpidJMXManagementConsole-Overview"></a>3.1.1. 
+	Overview
+      </h3></div></div></div><p>
+	The Qpid JMX Management Console is a standalone Eclipse
+	RCP application that communicates with the broker using
+	JMX.
+      </p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2533151"></a>3.1.1.1. 
+      Configuring Management Users
+    </h4></div></div></div><p>
+            The Qpid Java broker has a single source of users for the system.
+            So a user can connect to the broker to send messages and via the
+            JMX console to check the state of the broker.
+          </p><p>
+            
+          </p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ConfiguringManagementUsers-Addinganewmanagementuser"></a>
+            Adding
+            a new management user
+          </h5></div></div></div><p>
+            The broker does have some minimal configuration available to
+            limit which users can connect to the JMX console and what they
+            can do when they are there.
+          </p><p>
+            There are two steps required to add a new user with rights for
+            the JMX console.
+          </p><div class="orderedlist"><ol type="1"><li><p>Create a new user login, see HowTo:<a class="xref" href="">???</a>
+            </p></li><li><p>Grant the new user permission to the JMX Console
+            </p></li></ol></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ConfiguringManagementUsers-GrantingJMXConsolePermissions"></a>
+            Granting
+            JMX Console Permissions
+          </h6></div></div></div><p>
+            By default new users do not have access to the JMX console. The
+            access to the console is controlled via the file
+            <span class="emphasis"><em>jmxremote.access</em></span>.
+          </p><p>
+            This file contains a mapping from user to privilege.
+          </p><p>
+            There are three privileges available:
+          </p><div class="orderedlist"><ol type="1"><li><p>readonly - The user is able to log in and view queues but not
+            make any changes.
+            </p></li><li><p>readwrite - Grants user ability to read and write queue
+            attributes such as alerting values.
+            </p></li><li><p>admin - Grants the user full access including ability to edit
+            Users and JMX Permissions in addition to readwrite access.
+            </p></li></ol></div><p>
+            This file is read at start up and can forcibly be reloaded by an
+            admin user through the management console.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ConfiguringManagementUsers-AccessFileFormat"></a>
+            Access
+            File Format
+          </h6></div></div></div><p>
+            The file is a standard Java properties file and has the following
+            format
+          </p><pre class="programlisting">
+&lt;username&gt;=&lt;privilege&gt;
+</pre><p>
+            If the username value is not a valid user (list in the specified
+            PrincipalDatabase) then the broker will print a warning when it
+            reads the file as that entry will have no meaning.
+          </p><p>
+            Only when the the username exists in both the access file and the
+            PrincipalDatabase password file will the user be able to login
+            via the JMX Console.
+          </p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ConfiguringManagementUsers-ExampleFile"></a>
+            Example File
+          </h6></div></div></div><p>
+            The file will be timestamped by the management console if edited
+            through the console.
+          </p><pre class="programlisting">
+#Generated by JMX Console : Last edited by user:admin
+#Tue Jun 12 16:46:39 BST 2007
+admin=admin
+guest=readonly
+user=readwrite
+</pre></div></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2525100"></a>3.1.1.2. 
+      Configuring Qpid JMX Management Console
+    </h4></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ConfiguringQpidJMXManagementConsole-ConfiguringQpidJMXManagementConsole"></a>
+            Configuring Qpid JMX Management Console
+          </h5></div></div></div><p>
+            Qpid has a JMX management interface that exposes a number of
+            components of the running broker.
+            You can find out more about the features exposed by the JMX
+            interfaces <a class="xref" href="">???</a>.
+          </p><p>
+            
+          </p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ConfiguringQpidJMXManagementConsole-InstallingtheQpidJMXManagementConsole"></a>
+            Installing the Qpid JMX Management Console
+          </h6></div></div></div><div class="orderedlist"><ol type="1"><li><p>Unzip the archive to a suitable location.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">SSL encrypted connections</h3><p>
+                        Recent versions of the broker can make use of SSL to
+                        encrypt their RMI based JMX connections. If a broker
+                        being connected to is making use of this ability then
+                        additional console configuration may be required,
+                        particularly when using self-signed certificates. See
+                        <a class="xref" href="">???</a> for details.
+                      </p></div></li></ol></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">JMXMP based connections</h3><p>
+	      In previous releases of Qpid (M4 and below) the broker
+	      JMX connections could make use of the JMXMPConnector for
+	      additional security over its default RMI based JMX
+	      configuration. This is no longer the case, with SSL
+	      encrypted RMI being the favored approach going forward.
+	      However, if you wish to connect to an older broker using
+	      JMXMP the console will support this so long as the
+	      <span class="emphasis"><em>jmxremote_optional.jar</em></span> file is provided to it.
+	      For details see <a class="xref" href="">???</a>.
+	    </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ConfiguringQpidJMXManagementConsole-RunningtheQpidJMXManagementConsole"></a>
+            Running the Qpid JMX Management Console
+          </h6></div></div></div><p>
+            The console can be started in the following way, depending on
+            platform:
+          </p><div class="itemizedlist"><ul><li><p>Windows: by running the 'qpidmc.exe' executable file.
+            </p></li></ul></div><div class="itemizedlist"><ul><li><p>Linux: by running the 'qpidmc' executable.
+            </p></li></ul></div><div class="itemizedlist"><ul><li><p>Mac OS X: by launching the consoles application bundle (.app
+            file).
+            </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ConfiguringQpidJMXManagementConsole-UsingtheQpidJMXManagementConsole"></a>
+            Using the Qpid JMX Management Console
+          </h6></div></div></div><p>
+            Please see <a class="xref" href="Qpid-JMX-Management-Console.html#Qpid-JMX-Management-Console-User-Guide" title="3.1.1.5.  Qpid JMX Management Console User Guide">Section 3.1.1.5, “
+      Qpid JMX Management Console User Guide
+    ”</a> for details on using this Eclipse RCP
+            application.
+          </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ConfiguringQpidJMXManagementConsole-UsingJConsole"></a>
+            Using
+            JConsole
+          </h5></div></div></div><p>
+            See <a class="xref" href="">???</a>
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ConfiguringQpidJMXManagementConsole-UsingHermesJMS"></a>
+            Using
+            HermesJMS
+          </h5></div></div></div><p>
+            HermesJMS also offers integration with the Qpid management
+            interfaces. You can get instructions and more information from
+	    <a class="ulink" href="http://cwiki.apache.org/confluence/display/qpid/HermesJMS" target="_top">HermesJMS</a>.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ConfiguringQpidJMXManagementConsole-UsingMC4J"></a>
+            Using
+            MC4J
+          </h5></div></div></div><p>
+            <a class="ulink" href="qpid_www.mc4j.org" target="_top">MC4J</a> is an alternative
+            management tool. It provide a richer "dashboard" that can
+            customise the raw MBeans.
+          </p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ConfiguringQpidJMXManagementConsole-Installation"></a>
+            Installation
+          </h6></div></div></div><div class="itemizedlist"><ul><li><p>First download and install MC4J for your platform. Version
+            1.2 beta 9 is the latest version that has been tested.
+            </p></li><li><p>Copy the directory blaze/java/management/mc4j into
+            the directory &lt;MC4J-Installation&gt;/dashboards
+            </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ConfiguringQpidJMXManagementConsole-Configuration"></a>
+            Configuration
+          </h6></div></div></div><p>
+            You should create a connection the JVM to be managed. Using the
+            Management-&gt;Create Server Connection menu option. The
+            connection URL should be of the form:
+            service:jmx:rmi:///jndi/rmi://localhost:8999/jmxrmi
+            making the appropriate host and post changes.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ConfiguringQpidJMXManagementConsole-Operation"></a>
+            Operation
+          </h6></div></div></div><p>
+            You can view tabular summaries of the queues, exchanges and
+            connections using the Global Dashboards-&gt;QPID tree view. To
+            drill down on individual beans you can right click on the bean.
+            This will show any available graphs too.
+          </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2536172"></a>3.1.1.3. 
+      Management Console Security
+    </h4></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ManagementConsoleSecurity-ManagementConsoleSecurity"></a>
+            Management
+            Console Security
+          </h5></div></div></div><div class="itemizedlist"><ul><li><p>
+                <a class="xref" href="Qpid-JMX-Management-Console.html#ManagementConsoleSecurity-SSLencryptedRMI-280.5andabove-29" title="SSL encrypted RMI (0.5 and above)">the section called “
+            SSL
+            encrypted RMI (0.5 and above)
+          ”</a>
+              </p></li><li><p>
+                <a class="xref" href="Qpid-JMX-Management-Console.html#ManagementConsoleSecurity-JMXMP-28M4andprevious-29" title="JMXMP (M4 and previous)">the section called “
+            JMXMP
+            (M4 and previous)
+          ”</a>
+              </p></li><li><p>
+                <a class="xref" href="Qpid-JMX-Management-Console.html#ManagementConsoleSecurity-UserAccounts-26AccessRights" title="User Accounts &amp; Access Rights">the section called “
+            User
+            Accounts &amp; Access Rights
+          ”</a>
+              </p></li></ul></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ManagementConsoleSecurity-SSLencryptedRMI-280.5andabove-29"></a>
+            SSL
+            encrypted RMI (0.5 and above)
+          </h6></div></div></div><p>
+            Current versions of the broker make use of SSL encryption to
+            secure their RMI based JMX ConnectorServer for security purposes.
+            This ships enabled by default, although the test SSL keystore
+            used during development is not provided for security reasons
+            (using this would provide no security as anyone could have access
+            to it).
+          </p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ManagementConsoleSecurity-BrokerConfiguration"></a>
+            Broker
+            Configuration
+          </h6></div></div></div><p>
+            The broker configuration must be updated before the broker will
+            start. This can be done either by disabling the SSL support,
+            utilizing a purchased SSL certificate to create a keystore of
+            your own, or generating a self-signed keystore.
+          </p><p>
+            The broker must be configured with a keystore containing the
+            private and public keys associated with its SSL certificate. This
+            is accomplished by setting the Java environment properties
+            <span class="emphasis"><em>javax.net.ssl.keyStore</em></span> and
+            <span class="emphasis"><em>javax.net.ssl.keyStorePassword</em></span> respectively with the
+            location and password of an appropriate SSL keystore. Entries for
+            these properties exist in the brokers main configuration file
+            alongside the other management settings (see below), although the
+            command line options will still work and take precedence over the
+            configuration file.
+          </p><pre class="programlisting">
+&lt;management&gt;
+    &lt;ssl&gt;
+        &lt;enabled&gt;true&lt;/enabled&gt;
+        &lt;!-- Update below path to your keystore location, eg ${conf}/qpid.keystore  --&gt;
+        &lt;keyStorePath&gt;${conf}/qpid.keystore&lt;/keyStorePath&gt;
+        &lt;keyStorePassword&gt;password&lt;/keyStorePassword&gt;
+    &lt;/ssl&gt;
+&lt;/management&gt;
+</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ManagementConsoleSecurity-JMXManagementConsoleConfiguration"></a>
+            JMX
+            Management Console Configuration
+          </h6></div></div></div><p>
+            If the broker makes use of an SSL certificate signed by a known
+            signing CA (Certification Authority), the management console
+            needs no extra configuration, and will make use of Java's
+            built-in CA
+            truststore for certificate verification (you may however have to
+            update the system-wide default truststore if your CA is not
+            already present in it).
+          </p><p>
+            If however you wish to use a self-signed SSL certificate, then
+            the management console must be provided with an SSL truststore
+            containing a record for the SSL certificate so that it is able to
+            validate it when presented by the broker. This is performed by
+            setting the <span class="emphasis"><em>javax.net.ssl.trustStore</em></span> and
+            <span class="emphasis"><em>javax.net.ssl.trustStorePassword</em></span> environment variables
+            when starting the console. This can be done at the command line,
+            or alternatively an example configuration has been made within
+            the console's qpidmc.ini launcher configuration file that may
+            pre-configured in advance for repeated usage. See the <a class="xref" href="Qpid-JMX-Management-Console.html#Qpid-JMX-Management-Console-User-Guide" title="3.1.1.5.  Qpid JMX Management Console User Guide">Section 3.1.1.5, “
+      Qpid JMX Management Console User Guide
+    ”</a> for more
+            information on this configuration process.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ManagementConsoleSecurity-JConsoleConfiguration"></a>
+            JConsole
+            Configuration
+          </h6></div></div></div><p>
+            As with the JMX Management Console above, if the broker is using
+            a self-signed SSL certificate then in order to connect remotely
+            using JConsole, an appropriate trust store must be provided at
+            startup. See <a class="xref" href="">???</a> for further details on configuration.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ManagementConsoleSecurity-AdditionalInformation"></a>
+            Additional
+            Information
+          </h6></div></div></div><p>
+            More information on Java's handling of SSL certificate
+            verification and customizing the keystores can be found in the
+	    <a class="ulink" href="http://java.sun.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#CustomizingStores" target="_top">http://java.sun.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#CustomizingStores</a>.
+          </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ManagementConsoleSecurity-JMXMP-28M4andprevious-29"></a>
+            JMXMP
+            (M4 and previous)
+          </h6></div></div></div><p>
+            In previous releases of Qpid (M4 and below) the broker, can make
+            use of Sun's Java Management Extensions Messaging Protocol
+            (JMXMP) to provide encryption of the JMX connection, offering
+            increased security over the default unencrypted RMI based JMX
+            connection.
+          </p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ManagementConsoleSecurity-DownloadandInstall"></a>
+            Download and
+            Install
+          </h6></div></div></div><p>
+            This is possible by adding the jmxremote_optional.jar as provided
+            by Sun. This jar is covered by the Sun Binary Code License and is
+            not compatible with the Apache License which is why this
+            component is not bundled with Qpid.
+          </p><p>
+            Download the JMX Remote API 1.0.1_04 Reference Implementation
+            from <a class="xref" href="">???</a>. The included
+            'jmxremote-1_0_1-bin\lib\jmxremote_optional.jar' file must be
+            added to the broker classpath:
+          </p><p>
+            First set your classpath to something like this:
+          </p><pre class="programlisting">
+CLASSPATH=jmxremote_optional.jar
+</pre><p>
+            Then, run qpid-server passing the following additional flag:
+          </p><pre class="programlisting">
+qpid-server -run:external-classpath=first
+</pre><p>
+            Following this the configuration option can be updated to enabled
+            use of the JMXMP based JMXConnectorServer.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ManagementConsoleSecurity-BrokerConfiguration2"></a>
+            Broker
+            Configuration
+          </h6></div></div></div><p>
+            To enabled this security option change the
+            <span class="emphasis"><em>security-enabled</em></span> value in your broker configuration
+            file.
+          </p><pre class="programlisting">
+    &lt;management&gt;
+        &lt;security-enabled&gt;true&lt;/security-enabled&gt;
+    &lt;/management&gt;
+</pre><p>
+            You may also (for M2 and earlier) need to set the following
+            system properties using the environment variable QPID_OPTS:
+          </p><p>
+            QPID_OPTS="-Dcom.sun.management.jmxremote
+            -Dcom.sun.management.jmxremote.port=8999
+            -Dcom.sun.management.jmxremote.authenticate=false
+            -Dcom.sun.management.jmxremote.ssl=false"
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ManagementConsoleSecurity-JMXManagementConsoleConfiguration-2"></a>
+            JMX
+            Management Console Configuration
+          </h6></div></div></div><p>
+            If you wish to connect to a broker configured to use JMXMP then
+            the console also requires provision of the Optional sections of
+            the JMX Remote API that are not included within the JavaSE
+            platform.
+          </p><p>
+            In order to make it available to the console, place the
+            'jmxremote_optional.jar' (rename the file if any additional
+            information is present in the file name) jar file within the
+            'plugins/jmxremote.sasl_1.0.1/' folder of the console release (on
+            Mac OS X you will need to select 'Show package contents' from the
+            context menu whilst selecting the management console bundle in
+            order to reveal the inner file tree).
+          </p><p>
+            Following the the console will automatically load the JMX Remote
+            Optional classes and attempt the JMXMP connection when connecting
+            to a JMXMP enabled broker.
+          </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="ManagementConsoleSecurity-UserAccounts-26AccessRights"></a>
+            User
+            Accounts &amp; Access Rights
+          </h6></div></div></div><p>
+            In order to access the management operations via JMX, users must
+            have an account and have been assigned appropriate access rights.
+            See <a class="xref" href="">???</a>
+          </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2541508"></a>3.1.1.4. 
+      Qpid JMX Management Console FAQ
+    </h4></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleFAQ-Errors"></a>
+            Errors
+          </h5></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="QpidJMXManagementConsoleFAQ-HowdoIconnectthemanagementconsoletomybrokerusingsecurity-3F"></a>
+             How do I connect the management console to
+            my broker using security ?
+          </h6></div></div></div><p>
+            The <a class="xref" href="">???</a> page will give you the instructions that you should
+            use to set this up.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="QpidJMXManagementConsoleFAQ-IamunabletoconnectQpidJMXMC-2FJConsoletoaremotebrokerrunningonLinux-2Cbutconnectingtolocalhostonthatmachineworks-3F"></a>
+             I am unable to connect Qpid JMX MC/JConsole
+            to a remote broker running on Linux, but connecting to localhost
+            on that machine works ?
+          </h6></div></div></div><p>
+            The RMI
+            based JMX ConnectorServer used by the broker requries two ports
+            to operate. The console connects to an RMI Registry running on
+            the primary (default 8999) port and retrieves the information
+            actually needed to connect to the JMX Server. This information
+            embeds the hostname of the remote machine, and if this is
+            incorrect or unreachable by the connecting client the connection
+            will fail.
+          </p><p>
+            This
+            situation arises due to the hostname configuration on Linux and
+            is generally encountered when the remote machine does not have a
+            DNS hostname entry on the local network, causing the hostname
+            command to return a loopback IP instead of a fully qualified
+            domain name or IP address accessible by remote client machines.
+            It is described in further detail at: <a class="xref" href="">???</a>
+          </p><p>
+            To
+            remedy this issue you can set the
+            <span class="emphasis"><em>java.rmi.server.hostname</em></span> system property to control the
+            hostname/ip reported to the RMI runtime when advertising the JMX
+            ConnectorServer. This can also be used to dictate the address
+            returned on a computer with multiple network interfaces to
+            control reachability. To do so, add the value
+            <span class="emphasis"><em>-Djava.rmi.server.hostname=&lt;desired hostname/ip&gt;</em></span>
+            to the QPID_OPTS environment variable before starting the
+            <span class="emphasis"><em>qpid-server</em></span> script.
+          </p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Qpid-JMX-Management-Console-User-Guide"></a>3.1.1.5. 
+      Qpid JMX Management Console User Guide
+    </h4></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleUserGuide-QpidJMXManagementConsoleUserGuide"></a>
+            Qpid JMX Management Console User Guide
+          </h5></div></div></div><p>
+            
+            The Qpid JMX Management Console is a standalone Eclipse RCP
+            application for managing and monitoring the Qpid Java server
+            utilising its JMX management interfaces.
+          </p><p>
+            This guide will give an overview of configuring the console, the
+            features supported by it, and how to make use of the console in
+            managing the various JMX Management Beans (MBeans) offered by the
+            Qpid Java server.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleUserGuide-Startup-26Configuration"></a>
+            
+            Startup &amp; Configuration
+          </h5></div></div></div><p>
+            
+          </p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="QpidJMXManagementConsoleUserGuide-Startup"></a>
+            Startup
+          </h6></div></div></div><p>
+            
+            The console can be started in the following way, depending on
+            platform:
+          </p><div class="itemizedlist"><ul><li><p>
+              <span class="emphasis"><em>Windows:</em></span> by running the <span class="emphasis"><em>qpidmc.exe</em></span> executable
+              file.
+            </p></li><li><p>
+              <span class="emphasis"><em>Linux:</em></span> by running the <span class="emphasis"><em>qpidmc</em></span> executable.
+            </p></li><li><p>
+              <span class="emphasis"><em>Mac OS X:</em></span> by launching the <span class="emphasis"><em>Qpid Management
+              Console.app</em></span> application bundle.
+            </p></li></ul></div><p>
+            
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="QpidJMXManagementConsoleUserGuide-SSLconfiguration"></a>
+            SSL
+            configuration
+          </h6></div></div></div><p>
+            
+            Newer Qpid Java servers can protect their JMX connections with
+            SSL, and this is enabled by default. When attempting to connect
+            to a server with this enabled, the console must be able to verify
+            the SSL certificate presented to it by the server or the
+            connection will fail.
+          </p><p>
+            If the server makes use of an SSL certificate signed by a known
+            Signing CA (Certification Authority) then the console needs no
+            extra configuration, and will make use of Java's default
+            system-wide CA TrustStore for certificate verification (you may
+            however have to update the system-wide default CA TrustStore if
+            your certified is signed by a less common CA that is not already
+            present in it).
+          </p><p>
+            If however the server is equipped with a self-signed SSL
+            certificate, then the management console must be provided with an
+            appropriate SSL TrustStore containing the public key for the SSL
+            certificate, so that it is able to validate it when presented by
+            the server. The server ships with a script to create an example
+            self-signed SSL certificate, and store the relevant entries in a
+            KeyStore and matching TrustStore. This script can serve as a
+            guide on how to use the Java Keytool security utility to
+            manipulate your own stores, and more information can be found in
+            the JSSE Reference Guide: 
+	    <a class="ulink" href="http://java.sun.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#CustomizingStores" target="_top">http://java.sun.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#CustomizingStores</a>.
+          </p><p>
+            Supplying the necessary details to the console is performed by
+            setting the <span class="emphasis"><em>javax.net.ssl.trustStore</em></span> and
+            <span class="emphasis"><em>javax.net.ssl.trustStorePassword</em></span> environment variables
+            when starting it. This can be done at the command line, but the
+            preferred option is to set the configuration within the
+            <span class="emphasis"><em>qpidmc.ini</em></span> launcher configuration file for repeated
+            usage. This file is equipped with a template to ease
+            configuration, this should be uncommented and edited to suit your
+            needs. It can be found in the root of the console releases for
+            Windows, and Linux. For Mac OS X the file is located within the
+            consoles <span class="emphasis"><em>.app</em></span> application bundle, and to locate and edit
+            it you must select <span class="emphasis"><em>'Show Package Contents'</em></span> when
+            accessing the context menu of the application, then browse to the
+            <span class="emphasis"><em>Contents/MacOS</em></span> sub folder to locate the file.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="QpidJMXManagementConsoleUserGuide-JMXMPconfiguration"></a>
+            JMXMP
+            configuration
+          </h6></div></div></div><p>
+            
+            Older releases of the Qpid Java server can make use of the Java
+            Management Extensions Messaging Protocol (JMXMP) to provide
+            protection for their JMX connections. This occurs when the server
+            has its main configuration set with the management
+            <span class="emphasis"><em>'security-enabled'</em></span> property set to true.
+          </p><p>
+            In order to connect to this configuration of server, the console
+            needs an additional library that is not included within the Java
+            SE platform and cannot be distributed with the console due to
+            licensing restrictions.
+          </p><p>
+            You can download the JMX Remote API 1.0.1_04 Reference
+            Implementation from the Sun website <a class="xref" href="">???</a>. The included
+            <span class="emphasis"><em>jmxremote-1_0_1-bin/lib/jmxremote_optional.jar</em></span> file must
+            be added to the <span class="emphasis"><em>plugins/jmxremote.sasl_1.0.1</em></span> folder of
+            the console release (again, in Mac OS X you will need to select
+            <span class="emphasis"><em>'Show package contents'</em></span> from the context menu whilst
+            selecting the management console bundle in order to reveal the
+            inner file tree).
+          </p><p>
+            Following this the console will automatically load the JMX Remote
+            Optional classes and negotiate the SASL authentication profile
+            type when encountering a JMXMP enabled Qpid Java server.
+          </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleUserGuide-ManagingServerConnections"></a>
+            
+            Managing Server Connections
+          </h5></div></div></div><p>
+            
+          </p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="QpidJMXManagementConsoleUserGuide-MainToolbar"></a>
+            Main Toolbar
+          </h6></div></div></div><p>
+            
+            The main toolbar of the console can be seen in the image below.
+            The left most buttons respectively allow for adding a new server
+            connection, reconnecting to an existing server selected in the
+            connection tree, disconnecting the selected server connection,
+            and removing the server from the connection tree.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113098.png"><div class="caption"><p></p></div></div><p>
+            
+            
+            Beside these buttons is a combo for selecting the refresh
+            interval; that is, how often the console requests updated
+            information to display for the currently open area in the main
+            view. Finally, the right-most button enables an immediate update.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="QpidJMXManagementConsoleUserGuide-Connectingtoanewserver"></a>
+            Connecting
+            to a new server
+          </h6></div></div></div><p>
+            
+            To connect to a new server, press the <span class="emphasis"><em>Add New Server</em></span>
+            toolbar button, or select the <span class="emphasis"><em>Qpid Manager -&gt; Add New
+            Connection</em></span> menu item. At this point a dialog box will be
+            displayed requesting the server details, namely the server
+            hostname, management port, and a username and password. An
+            example is shown below:
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113099.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            
+            Once all the required details are entered, pressing Connect will
+            initiate a connection attempt to the server. It the attempt fails
+            a reason will be shown and the server will not be added to the
+            connection tree. If the attempt is successful the server will be
+            added to the connections list and the entry expanded to show the
+            initial administration MBeans the user has access to and any
+            VirtualHosts present on the server, as can be seen in the figure
+            below.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113100.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            
+            If the server supports a newer management API than the console in
+            use, once connected this initial screen will contain a message on
+            the right, indicating an upgraded console should be sought by the
+            user to ensure all management functionality supported by the
+            server is being utilised.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="QpidJMXManagementConsoleUserGuide-Reconnectingtoaserver"></a>
+            Reconnecting
+            to a server
+          </h6></div></div></div><p>
+            
+            If a server has been connected to previously, it will be saved as
+            an entry in the connection tree for further use. On subsequent
+            connections the server can simply be selected from the tree and
+            using the <span class="emphasis"><em>Reconnect</em></span> toolbar button or <span class="emphasis"><em>Qpid Manager
+            -&gt; Reconnect</em></span> menu item. At this stage the console will
+            prompt simply for the username and password with which the user
+            wishes to connect, and following a successful connection the
+            screen will appear as shown previously above.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="QpidJMXManagementConsoleUserGuide-Disconnectingfromaserver"></a>
+            Disconnecting
+            from a server
+          </h6></div></div></div><p>
+            
+            To disconnect from a server, select the connection tree node for
+            the server and press the <span class="emphasis"><em>Disconnect</em></span> toolbar button, or
+            use the <span class="emphasis"><em>Qpid Manager -&gt; Disconnect</em></span> menu option.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="QpidJMXManagementConsoleUserGuide-Removingaserver"></a>
+            Removing a
+            server
+          </h6></div></div></div><p>
+            
+            To remove a server from the connection list, select the
+            connection tree node for the server and press the <span class="emphasis"><em>Remove</em></span>
+            toolbar button, or use the <span class="emphasis"><em>Qpid Manager -&gt; Remove
+            Connection</em></span> menu option.
+          </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleUserGuide-Navigatingaconnectedserver"></a>
+            Navigating a connected server
+          </h5></div></div></div><p>
+            
+            Once connected to a server, the various areas available for
+            administration are accessed using the Qpid Connections tree at
+            the left side of the application. To open a particular MBean from
+            the tree for viewing, simply select it in the tree and it will be
+            opened in the main view.
+            </p><div class="mediaobject"><img src="images/3113101.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            As there may be vast numbers of Queues, Connections, and
+            Exchanges on the server these MBeans are not automatically added
+            to the tree along with the general administration MBeans.
+            Instead, dedicated selection areas are provided to allow users to
+            select which Queue/Connection/Exchange they wish to view or add
+            to the tree. These areas can be found by clicking on the
+            Connections, Exchanges, and Queues nodes in the tree under each
+            VirtualHost, as shown in the figure above. One or more MBeans may
+            be selected and added to the tree as Favourites using the button
+            provided. These settings are saved for future use, and each time
+            the console connects to the server it will check for the presence
+            of the MBean previously in the tree and add them if they are
+            still present. Queue/Connection/Exchange MBeans can be removed
+            from the tree by right clicking on them to expose a context menu
+            allowing deletion.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113102.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            As an alternative way to open a particular MBean for viewing,
+            without first adding it to the tree, you can simply double click
+            an entry in the table within the Queue/Connection/Exchange
+            selection areas to open it immediately. It is also possible to
+            open some MBeans like this whilst viewing certain other MBeans.
+            When opening an MBean in either of these ways, a Back button is
+            enabled in the top right corner of the main view. Using this
+            button will return you to the selection area or MBean you were
+            previously viewing. The history resets each time the tree is used
+            to open a new area or MBean.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleUserGuide-ConfigurationManagementMBean"></a>
+            
+            ConfigurationManagement MBean
+          </h5></div></div></div><p>
+            
+            The ConfigurationManagement MBean is available on newer servers,
+            to users with admin level management rights. It offers the
+            ability to perform a live reload of the <span class="emphasis"><em>Security</em></span>
+            sections defined in the main server configuration file (e.g.
+            defaults to: <span class="emphasis"><em>etc/config.xml</em></span>). This is mainly to allow
+            updating the server Firewall configuration to new settings
+            without a restart, and can be performed by clicking the Execute
+            button and confirming the prompt which follows.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113103.png"><div class="caption"><p></p></div></div><p>
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleUserGuide-LoggingManagementMBean"></a>
+            
+            LoggingManagement MBean
+          </h5></div></div></div><p>
+            
+            The LoggingManagement MBean is available on newer servers, and
+            accessible by admin level users. It allows live alteration of the
+            logging behaviour, both at a Runtime-only level and at the
+            configuration file level. The latter can optionally affect the
+            Runtime configuration, either through use of the servers
+            automated LogWatch ability which detects changes to the
+            configuration file and reloads it, or by manually requesting a
+            reload. This functionality is split across two management tabs,
+            Runtime Options and ConfigurationFile Options.
+          </p><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="QpidJMXManagementConsoleUserGuide-RuntimeOptions"></a>
+            Runtime
+            Options
+          </h6></div></div></div><p>
+            
+            </p><div class="mediaobject"><img src="images/3113104.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            The Runtime Options tab allows manipulation of the logging
+            settings without affecting the configuration files (this means
+            the changes will be lost when the server restarts), and gives
+            individual access to every Logger active within the server.
+          </p><p>
+            As shown in the figure above, the table in this tab presents the
+            Effective Level of each Logger. This is because the Loggers form
+            a hierarchy in which those without an explicitly defined (in the
+            logging configuration file) Level will inherit the Level of their
+            immediate parent; that is, the Logger whose full name is a prefix
+            of their own, or if none satisfy that condition then the
+            RootLogger is their parent. As example, take the
+            <span class="emphasis"><em>org.apache.qpid</em></span> Logger. It is parent to all those below
+            it which begin with <span class="emphasis"><em>org.apache.qpid</em></span> and unless they have
+            a specific Level of their own, they will inherit its Level. This
+            can be seen in the figure, whereby all the children Loggers
+            visible have a level of WARN just like their parent, but the
+            RootLogger Level is INFO; the children have inherited the WARN
+            level from <span class="emphasis"><em>org.apache.qpid</em></span> rather than INFO from the
+            RootLogger.
+          </p><p>
+            To aid with this distinction, the Logger Levels that are
+            currently defined in the configuration file are highlighted in
+            the List. Changing these levels at runtime will also change the
+            Level of all their children which haven't been set their own
+            Level using the runtime options. In the latest versions of the
+            LoggingManagement MBean, it is possible to restore a child logger
+            that has had an explicit level se, to inheriting that of its
+            parent by setting it to an INHERITED level that removes any
+            previously set Level of its own.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113105.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            In order to set one of more Loggers to a new Level, they should
+            be selected in the table (or double click an individual Logger to
+            modify it) and the <span class="emphasis"><em>Edit Selected Logger(s)</em></span> button
+            pressed to load the dialog shown above. At this point, any of the
+            available Levels supported by the server can be applied to the
+            Loggers selected and they will immediately update, as will any
+            child Loggers without their own specific Level.
+          </p><p>
+            The RootLogger can be similarly edited using the button at the
+            bottom left of the window.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h6 class="title"><a name="QpidJMXManagementConsoleUserGuide-ConfigurationFileOptions"></a>
+            ConfigurationFile
+            Options
+          </h6></div></div></div><p>
+            
+            The ConfigurationFile Options tab allows alteration of the Level
+            settings for the Loggers defined in the configuration file,
+            allowing changes to persist following a restart of the server.
+            Changes made to the configuration file are only applied
+            automatically while the sever is running if it was configured to
+            enable the LogWatch capability, meaning it will monitor the
+            configuration file for changes and apply the new configuration
+            when the change is detected. If this was not enabled, the changes
+            will be picked up when the server is restarted. The status of the
+            LogWatch feature is shown at the bottom of the tab.
+            Alternatively, in the latest versions of the LoggingManagement
+            MBean it is possible to reload the logging configuration file on
+            demand.
+          </p><p>
+            Manipulating the Levels is as on the Runtime Options tab, either
+            double-click an individual Logger entry or select multiple
+            Loggers and use the button to load the dialog to set the new
+            Level.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113106.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            One issue to note of when reloading the configuration file
+            settings, either automatically using LogWatch or manually, is
+            that any Logger set to a specific Level using the Runtime Options
+            tab that is not defined in the configuration file will maintain
+            that Level when the configuration file is reloaded. In other
+            words, if a Logger is defined in the configuration file, then the
+            configuration file will take precedence at reload, otherwise the
+            Runtime options take precedence.
+          </p><p>
+            This situation will be immediately obvious by examining the
+            Runtime Options tab to see the effective Level of each Logger
+            – unless it has been altered with the RuntimeOptions or
+            specifically set in the configuration file, a Logger Level should
+            match that of its parent. In the latest versions of the
+            LoggingManagement MBean, it is possible to use the RuntimeOptions
+            to restore a child logger to inheriting from its parent by
+            setting it with an INHERITED level that removes any previously
+            set Level of its own.
+            
+          </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleUserGuide-ServerInformationMBean"></a>            
+            ServerInformation MBean
+          </h5></div></div></div><p>
+            
+            </p><div class="mediaobject"><img src="images/3113107.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            The ServerInformation MBean currently only conveys various pieces
+            of version information to allow precise identification of the
+            server version and its management capabilities. In future it is
+            likely to convey additional server-wide details and/or
+            functionality.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleUserGuide-UserManagementMBean"></a>
+            
+            UserManagement MBean
+          </h5></div></div></div><p>
+            
+            The UserManagement MBean is accessible by admin level users, and
+            allows manipulation of existing user accounts and creation of new
+            user accounts.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113108.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            
+            To add a new user, press the <span class="emphasis"><em>Add New User</em></span> button, which
+            will load the dialog shown below.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113109.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            Here you may enter the new users Username, Password, and select
+            their JMX Management Rights. This controls whether or not they
+            have access to the management interface, and if so what
+            capabilities are accessible. <span class="emphasis"><em>Read Only</em></span> access allows
+            undertaking any operations that do not alter the server state,
+            such as viewing messages. <span class="emphasis"><em>Read + Write</em></span> access allows use
+            of all operations which are not deemed admin-only (such as those
+            in the UserManagement MBean itself). <span class="emphasis"><em>Admin</em></span> access allows
+            a user to utilize any operation, and view the admin-only MBeans
+            (currently these are ConfigurationManagement, LoggingManagement,
+            and UserManagement).
+          </p><p>
+            One or more users at a time may be deleted by selecting them in
+            the table and clicking the <span class="emphasis"><em>Delete User(s)</em></span> button. The
+            console will then prompt for confirmation before undertaking the
+            removals. Similarly, the access rights for one or more users may
+            be updated by selecting them in the table and clicking the
+            <span class="emphasis"><em>Set Rights</em></span> button. The console will then display a
+            dialog enabling selection of the new access level and
+            confirmation to undertake the update.
+          </p><p>
+            An individual user password may be updated by selecting the user
+            in the table in and clicking the <span class="emphasis"><em>Set Password</em></span> button.
+            The console will then display a dialog enabling input of the new
+            password and confirmation to undertake the update.
+          </p><p>
+            
+            The server caches the user details in memory to aid performance.
+            If may sometimes be necessary to externally modify the password
+            and access right files on disk. In order for these changes to be
+            known to the server without a restart, it must be instructed to
+            reload the file contents. This can be done using the provided
+            <span class="emphasis"><em>Reload User Details</em></span> button (on older servers, only the
+            management rights file is reloaded, on newer servers both files
+            are. The description on screen will indicate the behaviour).
+            After pressing this button the console will seek confirmation
+            before proceeding.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleUserGuide-VirtualHostManagerMBean"></a>
+            
+            VirtualHostManager MBean
+          </h5></div></div></div><p>
+            
+            Each VirtualHost in the server has an associated
+            VirtualHostManager MBean. This allows viewing, creation, and
+            deletion of Queues and Exchanges within the VirtualHost.
+          </p><p>
+            Clicking the <span class="emphasis"><em>Create</em></span> button in the Queue section will
+            open a dialog allowing specification of the Name, Owner
+            (optional), and durability properties of the new Queue, and
+            confirmation of the operation.
+          </p><p>
+            One or more Queues may be deleted by selecting them in the table
+            and clicking the <span class="emphasis"><em>Delete</em></span> button. This will unregister the
+            Queue bindings, remove the subscriptions and delete the Queue(s).
+            The console will prompt for confirmation before undertaking the
+            operation.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113110.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            Clicking the <span class="emphasis"><em>Create</em></span> button in the Exchange section will
+            open a dialog allowing specification of the Name, Type, and
+            Durable attributes of the new Exchange, and confirmation of the
+            operation.
+          </p><p>
+            One or more Exchanges may be deleted by selecting them in the
+            table and clicking the <span class="emphasis"><em>Delete</em></span> button. This will
+            unregister all the related channels and Queue bindings then
+            delete the Exchange(s). The console will prompt for confirmation
+            before undertaking the operation.
+          </p><p>
+            
+            Double-clicking on a particular Queue or Exchange name in the
+            tables will open the MBean representing it.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleUserGuide-Notifications"></a>
+            
+            Notifications
+          </h5></div></div></div><p>
+            
+            MBeans on the server can potentially send Notifications that
+            users may subscribe to. When managing an individual MBean that
+            offers Notifications types for subscription, the console supplies
+            a Notifications tab to allow (un)subscription to the
+            Notifications if desired and viewing any that are received
+            following subscription.
+          </p><p>
+            In order to provide quicker access to/awareness of any received
+            Notifications, each VirtualHost area in the connection tree has a
+            Notifications area that aggregates all received Notifications for
+            MBeans in that VirtualHost. An example of this can be seen in the
+            figure below.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113111.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            All received Notifications will be displayed until such time as
+            the user removes them, either in this aggregated view, or in the
+            Notifications area of the individual MBean that generated the
+            Notification.
+          </p><p>
+            They may be cleared selectively or all at once. To clear
+            particular Notifications, they should be selected in the table
+            before pressing the <span class="emphasis"><em>Clear</em></span> button. To clear all
+            Notifications, simply press the <span class="emphasis"><em>Clear</em></span> button without
+            anything selected in the table, at which point the console will
+            request confirmation of this clear-all action.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleUserGuide-ManagingQueues"></a>
+             Managing
+            Queues
+          </h5></div></div></div><p>
+            
+            As mentioned in earlier discussion of Navigation, Queue MBeans
+            can be opened either by double clicking an entry in the Queues
+            selection area, or adding a queue to the tree as a favourite and
+            clicking on its tree node. Unique to the Queue selection screen
+            is the ability to view additional attributes beyond just that of
+            the Queue Name. This is helpful for determining which Queues
+            satisfy a particular condition, e.g. having &lt;X&gt; messages on
+            the queue. The example below shows the selection view with
+            additional attributes <span class="emphasis"><em>Consumer Count, Durable, MessageCount,
+            and QueueDepth</em></span> (selected using the <span class="emphasis"><em>Select
+            Attributes</em></span> button at the bottom right corner of the
+            table)<span class="emphasis"><em>.</em></span>
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113112.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            Upon opening a Queue MBean, the Attributes tab is displayed, as
+            shown below. This allows viewing the value all attributes,
+            editing those which are writable values (highlighted in blue) if
+            the users management permissions allow, viewing descriptions of
+            their purpose, and graphing certain numerical attribute values as
+            they change over time.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113113.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            The next tab contains the operations that can be performed on the
+            queue. The main table serves as a means of viewing the messages
+            on the queue, and later for selecting specific messages to
+            operate upon. It is possible to view any desired range of
+            messages on the queue by specifying the visible range using the
+            fields at the top and pressing the <span class="emphasis"><em>Set</em></span> button. Next to
+            this there are helper buttons to enable faster browsing through
+            the messages on the queue; these allow moving forward and back by
+            whatever number of messages is made visible by the viewing range
+            set. The Queue Position column indicates the position of each
+            message on the queue, but is only present when connected to newer
+            servers as older versions cannot provide the necessary
+            information to show this (unless only a single message position
+            is requested).
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113114.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            Upon selecting a message in the table, its header properties and
+            redelivery status are updated in the area below the table. Double
+            clicking a message in the table (or using the <span class="emphasis"><em>View Message
+            Content</em></span> button to its right) will open a dialog window
+            displaying the contents of the message.
+          </p><p>
+            One or more messages can be selected in the table and moved to
+            another queue in the VirtualHost by using the <span class="emphasis"><em>Move
+            Message(s)</em></span> button, which opens a dialog to enable selection
+            of the destination and confirmation of the operation. Newer
+            servers support the ability to similarly copy the selected
+            messages to another queue in a similar fashion, or delete the
+            selected messages from the queue after prompting for
+            confirmation.
+          </p><p>
+            Finally, all messages (that have not been acquired by consumers)
+            on the queue can be deleted using the <span class="emphasis"><em>Clear Queue</em></span>
+            button, which will generate a prompt for confirmation. On newer
+            servers, the status bar at the lower left of the application will
+            report the number of messages actually removed.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleUserGuide-ManagingExchanges"></a>
+            
+            Managing Exchanges
+          </h5></div></div></div><p>
+            Exchange MBeans are opened for management operations in similar
+            fashion as described for Queues, again showing an Attributes tab
+            initially, with the Operations tab next:
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113115.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            Of the four default Exchange Types <span class="emphasis"><em>(direct, fanout, headers,
+            and topic)</em></span> all but <span class="emphasis"><em>headers</em></span> have their bindings
+            presented in the format shown above. The left table provides the
+            binding/routing keys present in the exchange. Selecting one of
+            these entries in the table prompts the right table to display all
+            the queues associated with this key. Pressing the <span class="emphasis"><em>Create</em></span>
+            button opens a dialog allowing association of an existing queue
+            with the entered Binding.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113116.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            The <span class="emphasis"><em>headers</em></span> Exchange type (default instantiation
+            <span class="emphasis"><em>amq.match or amq.headers</em></span>) is presented as below:
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113117.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            In the previous figure, the left table indicates the binding
+            number, and the Queue associated with the binding. Selecting one
+            of these entries in the table prompts the right table to display
+            the header values that control when the binding matches an
+            incoming message.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113118.png"><div class="caption"><p></p></div></div><p>
+          </p><p>
+            Pressing the <span class="emphasis"><em>Create</em></span> button when managing a
+            <span class="emphasis"><em>headers</em></span> Exchange opens a dialog allowing creation of a
+            new binding, associating an existing Queue with a particular set
+            of header keys and values. The <span class="emphasis"><em>x-match</em></span> key is required,
+            and instructs the server whether to match the binding with
+            incoming messages based on ANY or ALL of the further key-value
+            pairs entered. If it is desired to enter more than 4 pairs, you
+            may press the <span class="emphasis"><em>Add additional field</em></span> button to create a
+            new row as many times as is required.
+            
+            When managing a <span class="emphasis"><em>headers</em></span> Exchange, double clicking an
+            entry in the left-hand table will open the MBean for the Queue
+            specified in the binding properties.
+          </p><p>
+            When managing another Exchange Type, double clicking the Queue
+            Name in the right-hand table will open the MBean of the Queue
+            specified.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="QpidJMXManagementConsoleUserGuide-ManagingConnections"></a>
+            
+            Managing Connections
+          </h5></div></div></div><p>
+            
+            Exchange MBeans are opened for management operations in similar
+            fashion as described for Queues, again showing an Attributes tab
+            initially, with the Operations tab next, and finally a
+            Notifications tab allowing subscription and viewing of
+            Notifications. The Operations tab can be seen in the figure
+            below.
+          </p><p>
+            </p><div class="mediaobject"><img src="images/3113119.png"><div class="caption"><p></p></div></div><p>
+            The main table shows the properties of all the Channels that are
+            present on the Connection, including whether they are
+            <span class="emphasis"><em>Transactional</em></span>, the <span class="emphasis"><em>Number of Unacked Messages</em></span>
+            on them, and the <span class="emphasis"><em>Default Queue</em></span> if there is one (or
+            <span class="emphasis"><em>null</em></span> if there is not).
+          </p><p>
+            The main operations supported on a connection are Commiting and
+            Rolling Back of Transactions on a particular Channel, if the
+            Channel is Transactional. This can be done by selecting a
+            particular Channel in the table and pressing the <span class="emphasis"><em>Commit
+            Transactions</em></span> or <span class="emphasis"><em>Rollback Transactions</em></span> buttons at
+            the lower right corner of the table, at which point the console
+            will prompt for confirmation of the action. These buttons are
+            only active when the selected Channel in the table is
+            Transactional.
+          </p><p>
+            The final operation supported is closing the Connection. After
+            pressing the <span class="emphasis"><em>Close Connection</em></span> button, the console will
+            prompt for confirmation of the action. If this is carried out,
+            the MBean for the Connection being managed will be removed from
+            the server. The console will be notified of this by the server
+            and display an information dialog to that effect, as it would if
+            any other MBean were to be unregistered whilst being viewed.
+          </p><p>
+            Double clicking a row in the table will open the MBean of the
+            associated <span class="emphasis"><em>Default Queue</em></span> if there is one.
+          </p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2547592"></a>3.1.1.6. 
+      Qpid Management Features
+    </h4></div></div></div><p>
+            <span class="emphasis"><em>Management tool:</em></span> See our <a class="xref" href="">???</a> for
+            details of how to use various console options with the Qpid
+            management features.
+          </p><p>
+            The management of QPID is categorised into following types-
+          </p><div class="orderedlist"><ol type="1"><li><p>Exchange
+            </p></li><li><p>Queue
+            </p></li><li><p>Connection
+            </p></li><li><p>Broker
+            </p></li></ol></div><p>
+             <span class="emphasis"><em>1) Managing and Monitoring Exchanges</em></span>: Following is
+            the list of features, which we can have available for managing
+            and monitoring an Exchange running on a Qpid Server Domain-
+          </p><div class="orderedlist"><ol type="1"><li><p>Displaying the following information for monitoring purpose-
+              </p><div class="orderedlist"><ol type="a"><li><p>The list of queues bound to the exchange along with the
+                routing keys.
+                </p></li><li><p>
+                  General Exchange properties(like name,
+                  durable etc).
+                </p></li></ol></div><p>
+            </p></li><li><p>
+              Binding an existing queue with the
+              exchange.
+            </p></li></ol></div><p>
+            <span class="emphasis"><em>2) Managing and Monitoring
+            Queues</em></span>:  Following are the
+            features, which we can have for a Queue on a Qpid Server
+            Domain-
+          </p><div class="orderedlist"><ol type="1"><li><p>
+              Displaying the following information about
+              the queue for monitoring purpose-
+              </p><div class="orderedlist"><ol type="a"><li><p>
+                  General Queue properties(like name,
+                  durable, etc.)
+                </p></li><li><p>
+                  The maximum size of a message that can
+                  be accepted from the message producer.
+                </p></li><li><p>
+                  The number of the active consumers
+                  accessing the Queue.
+                </p></li><li><p>
+                  The total number of
+                  consumers (Active and Suspended).
+                </p></li><li><p>
+                  The number of undelivered messages
+                  in the Queue.
+                </p></li><li><p>
+                  The total number of messages received
+                  on the Queue since startup.
+                </p></li><li><p>
+                  The maximum number of bytes for
+                  the Queue that can be stored on the Server.
+                </p></li><li><p>The maximum number of messages for the Queue that can be
+                stored on the Server.
+                </p></li></ol></div><p>
+            </p></li><li><p>
+              Viewing the messages on the Queue.
+            </p></li><li><p>
+              Deleting message from top of the
+              Queue.
+            </p></li><li><p>
+              Clearing the Queue.
+            </p></li><li><p>
+              Browsing the DeadMessageQueue - Messages
+              which are expired or undelivered because of some reason are
+              routed to the DeadMessageQueue.  This queue can not be
+              deleted.  [Note: The is open because it depends on how
+              these kind of messages will be handeled?]
+            </p></li></ol></div><p>
+            <span class="emphasis"><em>3) Managing and Monitoring
+            Connections</em></span>: Following are the
+            features, which we can have for a connection on a QPID
+            Server Domain-
+          </p><div class="orderedlist"><ol type="1"><li><p>
+              Displaying general connection
+              properties(like remote address, etc.).
+            </p></li><li><p>Setting maximum number of channels allowed for a
+            connection.
+            </p></li><li><p>View all related channels and channel properties.
+            </p></li><li><p>Closing a channel.
+            </p></li><li><p>Commit or Rollback transactions of a channel, if the channel
+            is transactional.
+            </p></li><li><p>Notification for exceeding the maximum number of
+            channels.
+            </p></li><li><p>Dropping a connection.
+            </p></li><li><p>The work for <a class="xref" href="">???</a> implies that
+            there are potentially some additional requirements
+              </p><div class="orderedlist"><ol type="a"><li><p>Alert when tcp flow control kicks in
+                </p></li><li><p>Information available about current memory usage
+                available through JMX interface
+                </p></li><li><p>Dynamic removal of buffer bounds? (fundamentally not
+                possible with TransportIO)
+                </p></li><li><p>Management functionality added to JMX interface - UI
+                changes?
+                </p></li></ol></div><p>
+            </p></li></ol></div><p>
+            <span class="emphasis"><em>4) Managing the Broker</em></span>: Features for the Broker-
+          </p><div class="orderedlist"><ol type="1"><li><p>Creating an Exchange.
+            </p></li><li><p>Unregistering an Exchange.
+            </p></li><li><p>Creating a Queue.
+            </p></li><li><p>Deleting a Queue.
+            </p></li></ol></div></div></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Java-Broker-Slow-Consumer-Disconnect.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="QpidJavaBroker-ManagementTools.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.11. Slow Consumer Disconnect - User Guide </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. Management Tools</td></tr></table></div><div class="main_text_area_bottom"></div></div></div></body></html>

Added: qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/Qpid-Java-Broker-Config-File.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/Qpid-Java-Broker-Config-File.html?rev=1372183&view=auto
==============================================================================
--- qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/Qpid-Java-Broker-Config-File.html (added)
+++ qpid/site/docs/books/trunk_new/AMQP-Messaging-Broker-Java-Book/html/Qpid-Java-Broker-Config-File.html Sun Aug 12 19:19:49 2012
@@ -0,0 +1,36 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>2.5.  Configure the Broker via config.xml</title><link rel="stylesheet" href="css/style.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="AMQP Messaging Broker (Implemented in Java)"><link rel="up" href="Qpid-Java-Broker-HowTos.html" title="Chapter 2. How Tos"><link rel="prev" href="Qpid-Java-Log4j.html" title="2.4.  Configure Log4j CompositeRolling Appender"><link rel="next" href="Qpid-Java-Broker-Virtualhosts-Config.html" title="2.6.  Configure the Virtual Hosts via virtualhosts.xml"></head><body><div class="container" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><DIV class="header"><DIV class="logo"><H1>Apache Qpid™</H1><H2>Open Source AMQP Messaging</H2></DIV></DIV><DIV class="menu_box"><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Apache Qpi
 d</H3><UL><LI><A href="http://qpid.apache.org/index.html">Home</A></LI><LI><A href="http://qpid.apache.org/download.html">Download</A></LI><LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI><LI><A href="http://www.apache.org/licenses/">License</A></LI><LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Documentation</H3><UL><LI><A href="http://qpid.apache.org/documentation.html#doc-release">0.14 Release</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Community</H3><UL><LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI><LI><A href="http://qpid.apache.org/source_re
 pository.html">Source Repository</A></LI><LI><A href="http://qpid.apache.org/mailing_lists.html">Mailing Lists</A></LI><LI><A href="https://cwiki.apache.org/qpid/">Wiki</A></LI><LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI><LI><A href="http://qpid.apache.org/people.html">People</A></LI><LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Developers</H3><UL><LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI><LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About AMQP</H3><UL><LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class=
 "menu_box_body"><H3>About Apache</H3><UL><LI><A href="http://www.apache.org">Home</A></LI><LI><A href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</A></LI><LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI><LI><A href="http://www.apache.org/security/">Security</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV></DIV><div class="main_text_area"><div class="main_text_area_top"></div><div class="main_text_area_body"><DIV class="breadcrumbs"><span class="breadcrumb-link"><a href="index.html">AMQP Messaging Broker (Implemented in Java)</a></span> &gt; <span class="breadcrumb-link"><a href="Qpid-Java-Broker-HowTos.html">How Tos</a></span> &gt; <span class="breadcrumb-node">
+      Configure the Broker via config.xml
+    </span></DIV><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="Qpid-Java-Broker-Config-File"></a>2.5. 
+      Configure the Broker via config.xml
+    </h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ConfiguretheBrokerviaconfig.xml-Brokerconfig.xmlOverview"></a>2.5.1. 
+            Broker config.xml Overview
+          </h3></div></div></div><p>
+            The broker config.xml file which is shipped in the etc directory
+            of any Qpid binary distribution details various options and
+            configuration for the Java Qpid broker implementation.
+          </p><p>
+            In tandem with the virtualhosts.xml file, the config.xml file
+            allows you to control much of the deployment detail for your Qpid
+            broker in a flexible fashion.
+          </p><p>
+            Note that you can pass the config.xml you wish to use for your
+            broker instance to the broker using the -c command line option.
+            In turn, you can specify the paths for the broker password file
+            and virtualhosts.xml files in your config.xml for simplicity.
+          </p><p>
+            For more information about command line configuration options
+            please see <a class="xref" href="">???</a>.
+          </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="ConfiguretheBrokerviaconfig.xml-QpidVersion"></a>2.5.2. 
+            Qpid
+            Version
+          </h3></div></div></div><p>
+            The config format has changed between versions here you can find
+            the configuration details on a per version basis.
+          </p><p>
+            <a class="xref" href="">???</a>
+            <a class="xref" href="">???</a>
+          </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="Qpid-Java-Log4j.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Qpid-Java-Broker-HowTos.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Qpid-Java-Broker-Virtualhosts-Config.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.4. 
+      Configure Log4j CompositeRolling Appender
+     </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.6. 
+      Configure the Virtual Hosts via virtualhosts.xml
+    </td></tr></table></div><div class="main_text_area_bottom"></div></div></div></body></html>



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org