1 files changed, 117 insertions, 0 deletions
diff --git a/qpid/tools/src/java/qpid-broker-plugins-management-qmf2/README.txt b/qpid/tools/src/java/qpid-broker-plugins-management-qmf2/README.txt
new file mode 100644
index 0000000000..d6f46a895f
--- /dev/null
+++ b/qpid/tools/src/java/qpid-broker-plugins-management-qmf2/README.txt
@@ -0,0 +1,117 @@
+/*
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+
+The Qpid Java Broker by default uses either JMX or an HTTP Management GUI & REST API, however by building
+a QMF2 Agent as a Java Broker plugin it's possible to provide better synergy between the C++ and Java Brokers
+and allow the Java Broker to be controlled by the Qpid Command Line tools and also via the QMF2 REST API
+and GUI thus providing a unified view across a mixture of C++ and Java Brokers.
+
+
+************************************************ Building**************************************************
+
+To build the Java Broker QMF2 plugin from source, do:
+
+mvn clean package
+
+This will build the main plugin jar, and additionally a tar.gz release assembly which contains all the necessary
+dependencies to install the plugin in a broker installation.
+
+To aid during development, you can optionally use the 'copy-broker' profile to extract the broker release archive
+into the target/qpid-broker directory and copy the qmf2 broker plugin and dependencies into its lib dir:
+
+mvn clean package -Pcopy-broker
+
+You can then configure the extracted broker as described below.
+
+*********************************************** Installing *************************************************
+
+To install a release of the plugin, extract the release assembly and copy all of the files from the contained
+lib/ directory into the corresponding lib/ directory of your extracted broker installation.
+
+You can then configure the broker as described below.
+
+********************************************** Configuring **************************************************
+
+The Java Broker stores its main configuration in a JSON file (default: $QPID_WORK/config.json), which is typically
+managed file via the Web Management GUI. It is IMPORTANT to ensure that the following:
+
+{
+    "name" : "qmf2Management",
+    "type" : "MANAGEMENT-QMF2",
+    "connectionURL" : "amqp://guest:guest@/?brokerlist='tcp://0.0.0.0:5672'"
+  }
+
+is added to the "plugins" list of $QPID_WORK/config.json or the Plugin will not be used. Each entry in the file
+has an "id" property, but it is not necessary to specify one here as it will get automatically initialised the first
+time the broker starts with the updated configuration.
+
+The "connectionURL" property is particularly important. The Plugin connects to AMQP via the JMS Client so
+"connectionURL" represents a valid Java ConnectionURL to the Broker so the username/password and any other
+ConnectionURL configuration needs to be valid as for any other AMQP Connection to the Broker.
+
+
+If the QMF GUI is to be used then either the -p option of QpidRestAPI.sh should be used to set the REST Server's
+HTTP port to something other than 8080, or the brokers list of "ports" in $QPID_WORK/config.json should be modified from e.g.
+{
+    "id" :   <UUID>,
+    "name" : "HTTP",
+    "port" : "${qpid.http_port}"
+    "protocols" : [ "HTTP" ]
+  }
+
+to
+
+{
+    "id" :   <UUID>,
+    "name" : "HTTP",
+    "port" : 9090,
+    "protocols" : [ "HTTP" ]
+  }
+
+So that the HTTP ports don't conflict.
+
+
+******************************************** Troubleshooting **********************************************
+
+If all has gone well you should see
+
+[Broker] MNG-1001 : QMF2 Management Startup
+[Broker] MNG-1004 : QMF2 Management Ready
+
+in the Broker log messages when you run qpid-server, if you don't see these then there is likely to be a problem.
+
+1. Check your broker/plugin installation directory (e.g. $QPID_HOME/lib or $QPID_HOME/lib/plugins) now contains
+at least the following additional jars:
+qpid-qmf2-<version>.jar
+qpid-broker-plugins-management-qmf2-<version>.jar
+qpid-client-<version>.jar
+geronimo-jms_1.1_spec-1.0.jar
+
+2. If the jars mentioned above are present and correct in the plugins directory the most likely cause of failure
+is incorrect configuration.
+
+Ensure the steps outlined in the Config section have been taken to add the plugin configuration.
+
+Additionally, in the top-level Broker config the "defaultVirtualHost" *MUST* be set to the name of the
+default Virtual Host. If this property is not set or is set to a name that doesn't match the name of one of
+the Virtual Hosts then the Plugin will not start correctly.
+
+