diff options
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 <path to configuration></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> +<broker> +... +<management> + <emphasis><enabled>true</enabled></emphasis> <co id="java-broker-example-jmx-management-0"/> + <jmxport> + <emphasis><registryServer>7999</registryServer></emphasis> <co id="java-broker-example-jmx-management-1"/> + <emphasis><connectorServer>7998</connectorServer></emphasis> <co id="java-broker-example-jmx-management-2"/> + </jmxport> +<management> +... +</broker></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> +<broker> +... +<management> +... + <ssl> + <enabled>true</enabled> <co id="java-broker-example-management-keystore-0"/> + <keyStorePath>${conf}/qpid.keystore</keyStorePath> <co id="java-broker-example-management-keystore-1"/> + <keyStorePassword>password</keyStorePassword> <co id="java-broker-example-management-keystore-2"/> + </ssl> +... +<management> +... +</broker></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> +<broker> +... +<management> +... + <http> + <enabled>true</enabled> <co id="java-broker-example-management-web-0"/> + <port>9090</keyStorePath> <co id="java-broker-example-management-web-1"/> + <basic-auth>false</basic-auth> <co id="java-broker-example-management-web-2"/> + <sasl-auth>true</sasl-auth> <co id="java-broker-example-management-web-3"/> + <session-timeout>600</session-timeout> <co id="java-broker-example-management-web-4"/> + </http> + + <https> + <enabled>true</enabled> <co id="java-broker-example-management-web-5"/> + <port>9443</keyStorePath> <co id="java-broker-example-management-web-6"/> + <sasl-auth>true</sasl-auth> <co id="java-broker-example-management-web-7"/> + <basic-auth>true</basic-auth> <co id="java-broker-example-management-web-8"/> + </https> +... +<management> +... +</broker></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/<authentication provider name></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/<authentication provider name>/<user name></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/<group provider name></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/<group provider name>/<group name></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/<group provider name >/<group name>/<user name></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/<port name></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/<port name></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/<virtual host name>/>queue name></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/<virtual host name>/<exchange name></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/<virtual host name>/<exchange name>/<queue name>/<binding name></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/<virtual host name>/<connection name></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/<virtual host name>/<connection name>/<session name></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/<vhost>/<exchange>/<queue>/<binding> + replacing of <emphasis><exchange></emphasis> with "asterisks" (http://localhost:8080/rest/binding/<vhost>/*/<queue>/<binding>) + 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><binding></emphasis> and <emphasis><queue></emphasis> are omitted in binding REST URL + (http://localhost:8080/rest/binding/<vhostname>/<exchangename>) 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)://<hostname>:<port>/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 Binary files differnew file mode 100644 index 0000000000..c752adec3b --- /dev/null +++ b/qpid/doc/book/src/java-broker/images/Management-Web-Console.png |