1)DESCRIPTION
Q-Man is a Management bridge that exposes one (or several) Qpid broker domain model as MBeans that are accessible through the Java Management Extensions (JMX).
The following README content could be read also in http://cwiki.apache.org/confluence/display/qpid/Qman+Tool

2)HOW TO RUN Q-Man

2.1)PREREQUISITES
QMan is a standalone application that is packaged as qpid-management-client-<version>.jar. To run QMan you need to add the following jars in your CLASSPATH:

log4j-1.2.12.jar
slf4j-api-1.4.0.jar
slf4j-log4j12-1.4.0.jar
commons-pool-1.4.jar
commons-codec-1.3.jar
commons-lang-2.2.jar
commons-collections-3.2.jar
commons-configuration-1.2.jar
qpid-client-<version>.jar (were <version> is the current qpid version)
qpid-common-<version>.jar (were <version> is the current qpid version)

alternatively you can run the following script (that add all the qpid jars to the CLASSPATH):

> CLASSPATH=`find <lib-root> -name '*.jar' | tr '\n' ":"`

Where <lib-root> is the directory containing the qpid jars (when qpid is built from source <lib-root> is equal to qpid/java/build/lib)

You should have in your classpath a log4j.xml configuration file too with a category defined as this :

<category name="org.apache.qpid.management">
<priority value="INFO"/>
</category>

2.2) CONFIGURATION
QMan can be connected at run time against any broker. However if you wish to automatically connect to one or several brokers you can do so by providing a configuration file as follows:

<configuration>
  <brokers>
	<broker>
	  <host>localhost</host>
	  <port>5672</port>
	  <virtual-host>test</virtual-host>
	  <user>guest</user>
	  <password>guest</password>
	  <max-pool-capacity>4</max-pool-capacity>
	  <initial-pool-capacity>0</initial-pool-capacity>
	  <max-wait-timeout>-1</max-wait-timeout>
	</broker>
        <broker>
	  <host>myhost</host>
	  <port>5672</port>
	  <virtual-host>test</virtual-host>
	  <user>guest</user>
	  <password>guest</password>
	  <max-pool-capacity>4</max-pool-capacity>
	  <initial-pool-capacity>0</initial-pool-capacity>
	  <max-wait-timeout>-1</max-wait-timeout>
	</broker>
  </brokers>
</configuration>
The configuration above specifies that QMan should connect to two brokers, one on localhos and one on myhost, both listening on port 5672.

The configuration file to use is specified through the JVM parameter "qman-config" that must point onto a valid configuration file.

2.3)RUNNING Q-Man

To run QMan in a console run the following command:

> java -Dcom.sun.management.jmxremote org.apache.qpid.management.domain.services.QMan

Messages similar to those should be displayed:

... [org.apache.qpid.management.domain.services.QMan] <QMAN-000001> : Starting Q-Man...
...
Type "q" to quit.

if you wish to use a configuration file <home>/myconfiguration.xml so QMan establishes a connection with one or several brokers, run the following command:

java -Dqman-config="<home>/myconfiguration.xml" org.apache.qpid.management.domain.services.QMan 


2.4) STOPPING Q-Man
Type "q" In the console from which QMan has been started.

3) Browsing Manageable Beans using JConsole
The jconsole tool (JMX-compliant graphical tool for monitoring a Java virtual machine) can be used for monitoring and QMan Mbeans. for more information see http://java.sun.com/javase/6/docs/technotes/guides/management/jconsole.html

The jconsole executable can be found in JDK_HOME/bin, where JDK_HOME is the directory in which the JDK software is installed. If this directory is in your system path, you can start JConsole by simply typing jconsole in a console. Otherwise, you have to type the full path to the executable file.

As jconsole needs to perform operations invocation you will need to add the QMan jar in jconsole classpath. In a console type:

jconsole -J-Djava.class.path=$CLASSPATH:$JAVA_HOME/lib/jconsole.jar:$JAVA_HOME/lib/tools.jar
Where CLASSPATH contains the QMan jars and JAVA_HOME point on your JDK home.

NOte that in order to see QMan JVM on JConsole you need to add the following command line option to QMan launcher : -Dcom.sun.management.jmxremote

4) Deploying Q-Man on JBoss 
QMan comes with a servlet that can be deployed in any application server. In the following we show how to deploy the qman servlet within JBoss application server.

4.1) PREREQUISITES 
You mus install JBoss:

- Download the latest stable version from: http://www.jboss.org/jbossas/downloads/
- Unzip the download archive in <jboss-home>

4.2) Deploying 
First you need to copy the provided qman.war in <jboss-home>/server/default/deploy/ (note that you can use another server configuration like for example minimal)

Then run JBoss:

Add the following option-Djboss.platform.mbeanserver to JAVA_OPTS (for example: export JAVA_OPTS=-Djboss.platform.mbeanserver)
Execute <jboss-home>/binrun.sh (or run.bat on a windows platform)
Notes:

If you wish to configure QMan via a configuration file so QMan establishes a connection with one or several broker at starting time then add the options -Dqman-config=myconfigFile.xml to JAVA_OPTS.
When Qpid is built form source, the war archive qman.war is located in qpid/java/build/management/client/servlet

Enjoy!