QPID-4584: Add documentation about java broker management REST interfaces0.20

    
merged from trunk r1446258 



git-svn-id: https://svn.apache.org/repos/asf/qpid/branches/0.20@1471035 13f79535-47bb-0310-9956-ffa450edef68

4 files changed, 400 insertions, 2 deletions

diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Config-Files.xml b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Config-Files.xml
index f2d93641b4..1a01df5f8f 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Config-Files.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Config-Files.xml
@@ -23,4 +23,156 @@
 <section id="Java-Broker-Configuring-And-Managing-Config-Files">
 <title>Config Files</title>
 
+    <para>
+        This section shows how to configure and manage broker.
+    </para>
+
+    <section role="h2" id="Java-Broker-Configuring-And-Managing-Config-Files-Configuration">
+        <title>Configuration file</title>
+        <para>Broker can be configured using XML configuration files. By default, broker is looking for configuration file at ${QPID_HOME}/etc/config.xml. The default configuration location can be overridden by specifying command line option <emphasis>-c &lt;path to configuration&gt;</emphasis> on broker start up.</para>
+    </section>
+
+    <section role="h2" id="Java-Broker-Configuring-And-Managing-Config-Files-Management">
+        <title>Management Configuration</title>
+        <para>
+        Management interfaces can be configured in <emphasis>management</emphasis> section of broker configuration file. The example of the management section is provided below.
+        </para>
+         <example>
+    <title>Management configuration</title>
+    <programlisting><![CDATA[
+    <broker>
+    ...
+        <management>
+            <enabled>true</enabled>
+            <jmxport>
+                <registryServer>8999</registryServer>
+            </jmxport>
+            <ssl>
+                <enabled>false</enabled>
+                <keyStorePath>${conf}/qpid.keystore</keyStorePath>
+                <keyStorePassword>password</keyStorePassword>
+            </ssl>
+            <http>
+                <enabled>true</enabled>
+            </http>
+            <https>
+                <enabled>false</enabled>
+            </https>
+        </management>
+    ...
+    </broker>]]></programlisting>
+  </example>
+    </section>
+    <section role="h2" id="Java-Broker-Configuring-And-Managing-Config-Files-JMX-Management">
+        <title>JMX Management Configuration</title>
+        <para>
+        JMX management can be configured in <emphasis>management</emphasis> section of broker configuration file.
+        </para>
+        <para>An <emphasis>enabled</emphasis> element in the <emphasis>management</emphasis> section is used to enable or disable the JMX interfaces. Setting it to <emphasis>true</emphasis> causes the broker to start the management plugin if such is available on the broker classpath.</para>
+        <para>JMX management requires two ports which can be configured in <emphasis>jmxport</emphasis> sub-section of <emphasis>management</emphasis>:
+        <itemizedlist>
+            <listitem><para>RMI port (8999 by default) can be configured in an element <emphasis>jmxport/registryServer</emphasis></para></listitem>
+            <listitem><para>Connector port can be configured in an element <emphasis>jmxport/connectorServer</emphasis>. If configuration element <emphasis>connectorServer</emphasis> is not provided than the connector port defaults to <emphasis>100 + registryServer port</emphasis>.</para></listitem>
+        </itemizedlist>
+        </para>
+        <example>
+            <title>Enabling JMX Management and configuring JMX ports</title>
+            <programlisting>
+&lt;broker&gt;
+...
+&lt;management&gt;
+    <emphasis>&lt;enabled>true&lt;/enabled&gt;</emphasis>                     <co id="java-broker-example-jmx-management-0"/>
+    &lt;jmxport&gt;
+        <emphasis>&lt;registryServer>7999&lt;/registryServer&gt;</emphasis>   <co id="java-broker-example-jmx-management-1"/>
+        <emphasis>&lt;connectorServer>7998&lt;/connectorServer&gt;</emphasis> <co id="java-broker-example-jmx-management-2"/>
+    &lt;/jmxport&gt;
+&lt;management&gt;
+...
+&lt;/broker&gt;</programlisting>
+        </example>
+        <para>In the snippet above the following is configured:</para>
+        <calloutlist>
+            <callout arearefs="java-broker-example-jmx-management-0"><para>Enable JMX management</para></callout>
+            <callout arearefs="java-broker-example-jmx-management-1"><para>Set RMI port to 7999</para></callout>
+            <callout arearefs="java-broker-example-jmx-management-2"><para>Set connector port to 7998</para></callout>
+        </calloutlist>
+        <para>SSL can be configured to use on the connector port in the sub-section <emphasis>ssl</emphasis> of the <emphasis>management</emphasis> section. See <xref linkend="Java-Broker-Configuring-And-Managing-Config-Files-SSL-keystore-configuration"/> for details.</para>
+        <para>In order to use SSL with JMX management an element <emphasis>ssl/enabled</emphasis> needs to be set to <emphasis>true</emphasis>.</para>
+    </section>
+    <section role="h2" id="Java-Broker-Configuring-And-Managing-Config-Files-SSL-keystore-configuration">
+        <title>Management SSL key store configuration</title>
+        <para>
+            This section describes how to configure the key store to use in SSL connections in both JMX and Web management interfaces.
+        </para>
+        <para>The following examples demonstrates how to configure keystore for management</para>
+        <example>
+            <title>Management key store configuration</title>
+            <programlisting>
+&lt;broker&gt;
+...
+&lt;management&gt;
+...
+    &lt;ssl&gt;
+        &lt;enabled&gt;true&lt;/enabled&gt;                            <co id="java-broker-example-management-keystore-0"/>
+        &lt;keyStorePath&gt;${conf}/qpid.keystore&lt;/keyStorePath&gt; <co id="java-broker-example-management-keystore-1"/>
+        &lt;keyStorePassword&gt;password&lt;/keyStorePassword&gt;      <co id="java-broker-example-management-keystore-2"/>
+    &lt;/ssl&gt;
+...
+&lt;management&gt;
+...
+&lt;/broker&gt;</programlisting>
+        </example>
+        <calloutlist>
+            <callout arearefs="java-broker-example-management-keystore-0"><para>Enable SSL on JMX connector port only. This setting does not effect the web management interfaces.</para></callout>
+            <callout arearefs="java-broker-example-management-keystore-1"><para>Set path to the key store file</para></callout>
+            <callout arearefs="java-broker-example-management-keystore-2"><para>Set keystore password</para></callout>
+        </calloutlist>
+     </section>
+     <section role="h2" id="Java-Broker-Configuring-And-Managing-Config-Files-Web-Management">
+        <title>Web Management Configuration</title>
+        <para>
+        Web management can be configured in <emphasis>management</emphasis> section of broker configuration file.
+        </para>
+        <para>Sub-section <emphasis>http</emphasis> is used to enable web management on http port.</para>
+        <para>Sub-section <emphasis>https</emphasis> is used to enable web management on https port.</para>
+        <para>The following example shows how to configure http and https ports</para>
+        <example>
+            <title>Enabling web management</title>
+            <programlisting>
+&lt;broker&gt;
+...
+&lt;management&gt;
+...
+    &lt;http&gt;
+        &lt;enabled&gt;true&lt;/enabled&gt;                       <co id="java-broker-example-management-web-0"/>
+        &lt;port&gt;9090&lt;/keyStorePath&gt;                     <co id="java-broker-example-management-web-1"/>
+        &lt;basic-auth&gt;false&lt;/basic-auth&gt;                <co id="java-broker-example-management-web-2"/>
+        &lt;sasl-auth&gt;true&lt;/sasl-auth&gt;                   <co id="java-broker-example-management-web-3"/>
+        &lt;session-timeout&gt;600&lt;/session-timeout&gt;        <co id="java-broker-example-management-web-4"/>
+    &lt;/http&gt;
+
+    &lt;https&gt;
+        &lt;enabled&gt;true&lt;/enabled&gt;                       <co id="java-broker-example-management-web-5"/>
+        &lt;port&gt;9443&lt;/keyStorePath&gt;                     <co id="java-broker-example-management-web-6"/>
+        &lt;sasl-auth&gt;true&lt;/sasl-auth&gt;                   <co id="java-broker-example-management-web-7"/>
+        &lt;basic-auth&gt;true&lt;/basic-auth&gt;                 <co id="java-broker-example-management-web-8"/>
+    &lt;/https&gt;
+...
+&lt;management&gt;
+...
+&lt;/broker&gt;</programlisting>
+        </example>
+        <calloutlist>
+            <callout arearefs="java-broker-example-management-web-0"><para>Enable web management on http port. Default is true.</para></callout>
+            <callout arearefs="java-broker-example-management-web-1"><para>Set web management http port to 9090. Default is 8080.</para></callout>
+            <callout arearefs="java-broker-example-management-web-2"><para>Disable basic authentication on http port for REST services only. Default is false.</para></callout>
+            <callout arearefs="java-broker-example-management-web-3"><para>Enable SASL authentication on http port for REST services and web console. Default is true.</para></callout>
+            <callout arearefs="java-broker-example-management-web-4"><para>Set session timeout in seconds. Default is 15 minutes.</para></callout>
+            <callout arearefs="java-broker-example-management-web-5"><para>Enable web management on https port. Default is false.</para></callout>
+            <callout arearefs="java-broker-example-management-web-6"><para>Set web management https port to 9443. Default is 8443.</para></callout>
+            <callout arearefs="java-broker-example-management-web-7"><para>Enable SASL authentication on https port for REST services and web console. Default is true.</para></callout>
+            <callout arearefs="java-broker-example-management-web-8"><para>Enable basic authentication on https port for REST services only. Default is true.</para></callout>
+        </calloutlist>
+        <note><para>Please configure the keystore to use with the https web management port. See <xref linkend="Java-Broker-Configuring-And-Managing-Config-Files-SSL-keystore-configuration"/> for details.</para></note>
+     </section>
 </section>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-REST-API.xml b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-REST-API.xml
index fcca6b69b4..8bd63ade7a 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-REST-API.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-REST-API.xml
@@ -22,5 +22,242 @@
 
 <section id="Java-Broker-Configuring-And-Managing-REST-API">
 <title>REST API</title>
+    <section id="Java-Broker-Configuring-And-Managing-REST-API-Overview">
+        <title>REST API Overview</title>
+        <para>This section provides an overview of REST management API.</para>
+        <para>If web management is enabled (see <xref linkend="Java-Broker-Configuring-And-Managing-Config-Files-Web-Management"/>) 
+            the REST API can be used to monitor and manage the broker instance.</para>
+        <para>The Qpid broker REST services support traditional REST model which uses the GET method requests to retrieve 
+            the information about broker configured objects, DELETE method requests to delete the configured object,
+            PUT to create the configured object and POST to update the configured objects.</para>
+        <para>The table below lists the available REST services with brief description how they can be used.</para>
 
+       <table>
+          <title>Rest services</title>
+          <tgroup cols="6">
+          <thead>
+            <row>
+              <entry>Rest service URL</entry>
+              <entry>Description</entry>
+              <entry>GET</entry>
+              <entry>PUT</entry>
+              <entry>POST</entry>
+              <entry>DELETE</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry><para>/rest/broker</para></entry>
+              <entry><para>Rest service to manage broker instance</para></entry>
+              <entry><para>Retrieves the details of broker configuration</para></entry>
+              <entry><para>Not implemented yet</para></entry>
+              <entry><para>Not implemented yet</para></entry>
+              <entry><para>Not implemented yet</para></entry>
+            </row>
+            <row>
+              <entry><para>/rest/authenticationprovider</para>
+                  <para>/rest/authenticationprovider/&lt;authentication provider name&gt;</para>
+              </entry>
+              <entry>Rest service to manage authentication providers on the broker</entry>
+              <entry>Retrieves the details about authentication providers</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+            </row>
+            <row>
+              <entry><para>/rest/user</para>
+                  <para>/rest/user/&lt;authentication provider name&gt;/&lt;user name&gt;</para>
+              </entry>
+              <entry>Rest service to manage user account</entry>
+              <entry>Retrieves the details about user account</entry>
+              <entry>Creates user account</entry>
+              <entry>Updates user password</entry>
+              <entry>Deletes user account</entry>
+            </row>
+            <row>
+              <entry><para>/rest/groupprovider</para>
+                  <para>/rest/groupprovider/&lt;group provider name&gt;</para>
+              </entry>
+              <entry>Rest service to manage group providers</entry>
+              <entry>Retrieves the details about group provider(s)</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+            </row>
+            <row>
+              <entry><para>/rest/group</para>
+                  <para>/rest/group/&lt;group provider name&gt;/&lt;group name&gt;</para>
+              </entry>
+              <entry>Rest service to manage user group</entry>
+              <entry>Retrieves the details about user group</entry>
+              <entry>Creates group</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Deletes group</entry>
+            </row>
+            <row>
+              <entry><para>/rest/groupmember</para>
+                  <para>/rest/groupmember/&lt;group provider name &gt;/&lt;group name&gt;/&lt;user name&gt;</para>
+              </entry>
+              <entry>Rest service to manage group member(s)</entry>
+              <entry>Retrieves the details about group member(s)</entry>
+              <entry>Add user to group</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Deletes user from group</entry>
+            </row>
+            <row>
+              <entry>
+                    <para>/rest/port</para>
+                    <para>/rest/port/&lt;port name&gt;</para>
+              </entry>
+              <entry>Rest service to manage broker ports(s)</entry>
+              <entry>Retrieves the details about the broker port(s)</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+            </row>
+            <row>
+              <entry>
+                    <para>/rest/port</para>
+                    <para>/rest/port/&lt;port name&gt;</para>
+              </entry>
+              <entry>Rest service to manage broker ports(s)</entry>
+              <entry>Retrieves the details about the broker port(s)</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+            </row>
+            <row>
+              <entry>
+                    <para>/rest/queue</para>
+                    <para>/rest/queue/&lt;virtual host name&gt;/&gt;queue name&gt;</para>
+              </entry>
+              <entry>Rest service to manage queue(s)</entry>
+              <entry>Retrieves the details about the queue(s)</entry>
+              <entry>Creates queue</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Deletes queue</entry>
+            </row>
+            <row>
+              <entry>
+                    <para>/rest/exchange</para>
+                    <para>/rest/exchange/&lt;virtual host name&gt;/&lt;exchange name&gt;</para>
+              </entry>
+              <entry>Rest service to manage exchange(s)</entry>
+              <entry>Retrieves the details about the exchange(s)</entry>
+              <entry>Creates exchange</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Deletes exchange</entry>
+            </row>
+            <row>
+              <entry>
+                    <para>/rest/binding</para>
+                    <para>/rest/binding/&lt;virtual host name&gt;/&lt;exchange name&gt;/&lt;queue name&gt;/&lt;binding name&gt;</para>
+              </entry>
+              <entry>Rest service to manage binding(s)</entry>
+              <entry>Retrieves the details about the binding(s)</entry>
+              <entry>Binds a queue to an exchange</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Deletes binding</entry>
+            </row>
+            <row>
+              <entry>
+                    <para>/rest/connection</para>
+                    <para>/rest/connection/&lt;virtual host name&gt;/&lt;connection name&gt;</para>
+              </entry>
+              <entry>Rest service to manage connection(s)</entry>
+              <entry>Retrieves the details about the connection(s)</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+            </row>
+            <row>
+              <entry>
+                    <para>/rest/session</para>
+                    <para>/rest/session/&lt;virtual host name&gt;/&lt;connection name&gt;/&lt;session name&gt;</para>
+              </entry>
+              <entry>Rest service to manage session(s)</entry>
+              <entry>Retrieves the details about the session(s)</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+            </row>
+            <row>
+              <entry>
+                    <para>/rest/message/*</para>
+              </entry>
+              <entry>Rest service to manage messages(s)</entry>
+              <entry>Retrieves the details about the messages(s)</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Copies, moves messages</entry>
+              <entry>Deletes messages</entry>
+            </row>
+            <row>
+              <entry>
+                    <para>/rest/message-content/*</para>
+              </entry>
+              <entry>Rest service to retrieve message content</entry>
+              <entry>Retrieves the message content</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+            </row>
+            <row>
+              <entry>
+                    <para>/rest/logrecords</para>
+              </entry>
+              <entry>Rest service to retrieve broker logs</entry>
+              <entry>Retrieves the broker logs</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+            </row>
+            <row>
+              <entry>
+                    <para>/rest/sasl</para>
+              </entry>
+              <entry>Sasl authentication</entry>
+              <entry>Retrieves user current authentication status and broker supported SASL mechanisms</entry>
+              <entry>Authenticates user using supported SASL mechanisms</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+            </row>
+            <row>
+              <entry>
+                    <para>/rest/logout</para>
+              </entry>
+              <entry>Log outs</entry>
+              <entry>Log outs user</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+              <entry>Not implemented yet</entry>
+            </row>
+          </tbody>
+          </tgroup>
+        </table>
+        <para>Rest URL are hierarchical. It is permitted to replace rest URL elements with an "asterisks" in GET requests to denote
+        all object of a particular type. Additionally, trailing object type in the URL hierarchy can be omitted.
+        In this case GET request will return all of the object underneath of the current object.</para>
+        <para>For example, for binding URL http://localhost:8080/rest/binding/&lt;vhost&gt;/&lt;exchange&gt;/&lt;queue&gt;/&lt;binding&gt;
+        replacing of <emphasis>&lt;exchange&gt;</emphasis> with "asterisks" (http://localhost:8080/rest/binding/&lt;vhost&gt;/*/&lt;queue&gt;/&lt;binding&gt;)
+        will result in the GET response containing the list of bindings for all of the exchanges in the virtual host having the given name and given queue.
+        If <emphasis>&lt;binding&gt;</emphasis> and <emphasis>&lt;queue&gt;</emphasis> are omitted in binding REST URL
+        (http://localhost:8080/rest/binding/&lt;vhostname&gt;/&lt;exchangename&gt;) the GET request will result in returning 
+        all bindings for all queues for the given exchange in the virtual host.
+        </para> 
+        <example>
+        <title>Examples of queue creation using curl:</title>
+            <programlisting><![CDATA[
+#create a durable queue
+curl -X PUT  -d '{"durable":true}' http://localhost:8080/rest/queue/<vhostname>/<queuename>
+#create a durable priority queue
+curl -X PUT  -d '{"durable":true,"type":"priority"}' http://localhost:8080/rest/queue/<vhostname>/<queuename>
+            ]]></programlisting>
+        </example><example>
+        <title>Example of binding a queue to an exchange using curl</title>
+            <programlisting><![CDATA[
+curl  -X PUT  -d '{}' http://localhost:8080/rest/binding/<vhostname>/<exchangename>/<queue-name>/<binding-name>
+            ]]></programlisting>
+        </example>
+        <para>Qpid broker web management console calls rest interfaces internally to manage the broker.</para>
+    </section>
 </section>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Console.xml b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Console.xml
index 9fa8d3c03f..406f2fbe08 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Console.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Console.xml
@@ -21,6 +21,15 @@
 -->
 
 <section id="Java-Broker-Configuring-And-Managing-Web-Console">
-<title>Web Console</title>
-
+    <title>Web Console</title>
+    <para>If web management is enabled (see <xref linkend="Java-Broker-Configuring-And-Managing-Config-Files-Web-Management"/>) the web management console can be accessed from web browser using URL http(s)://&lt;hostname&gt;:&lt;port&gt;/management, where</para>
+    <itemizedlist>
+        <listitem><para><emphasis>hostname</emphasis> is the broker host</para></listitem>
+        <listitem><para><emphasis>port</emphasis> is the broker port(either http or https)</para></listitem>
+    </itemizedlist>
+    <para>The page like following is displayed on navigation to the management URL.</para>
+    <figure>
+      <title>Web management Console</title>
+      <graphic fileref="images/Management-Web-Console.png"/>
+    </figure>
 </section>
diff --git a/qpid/doc/book/src/java-broker/images/Management-Web-Console.png b/qpid/doc/book/src/java-broker/images/Management-Web-Console.png
new file mode 100644
index 0000000000..c752adec3b
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/images/Management-Web-Console.png