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> > <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">
+<username>=<privilege>
+</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 <MC4J-Installation>/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->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->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 & Access Rights">the section called â
+ User
+ Accounts & 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">
+<management>
+ <ssl>
+ <enabled>true</enabled>
+ <!-- Update below path to your keystore location, eg ${conf}/qpid.keystore -->
+ <keyStorePath>${conf}/qpid.keystore</keyStorePath>
+ <keyStorePassword>password</keyStorePassword>
+ </ssl>
+</management>
+</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">
+ <management>
+ <security-enabled>true</security-enabled>
+ </management>
+</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 & 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=<desired hostname/ip></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 & 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 -> 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
+ -> 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 -> 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 -> 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 <X> 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> > <span class="breadcrumb-link"><a href="Qpid-Java-Broker-HowTos.html">How Tos</a></span> > <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