diff options
| author | Alex Rudyy <orudyy@apache.org> | 2013-05-09 15:17:33 +0000 |
|---|---|---|
| committer | Alex Rudyy <orudyy@apache.org> | 2013-05-09 15:17:33 +0000 |
| commit | fce6730e7b70bc3ca220db412b25f9027a4e54de (patch) | |
| tree | d19287e7591ce35733d9a08f6af55114dd5fd0a4 | |
| parent | 3970c2521d5ecc1c449de4c685efc1b186d36332 (diff) | |
| download | qpid-python-fce6730e7b70bc3ca220db412b25f9027a4e54de.tar.gz | |
QPID-4685: Update documentation to reflect changes to configuration
merged from trunk r1480672
git-svn-id: https://svn.apache.org/repos/asf/qpid/branches/0.22@1480684 13f79535-47bb-0310-9956-ffa450edef68
41 files changed, 1674 insertions, 929 deletions
diff --git a/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml b/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml index b2dbd969bc..9f5872926c 100644 --- a/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml +++ b/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml @@ -27,11 +27,12 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Installation.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Getting-Started.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Configuring-And-Managing.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Ports.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Virtual-Hosts.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Exchanges.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Queues.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Stores.xml"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Configuring-And-Managing.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-High-Availability.xml"/> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Authentication-Providers.xml index 3a2825826b..706df1f4a7 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Authentication-Providers.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Authentication-Providers.xml @@ -22,5 +22,31 @@ <section id="Java-Broker-Concepts-Authentication-Providers"> <title>Authentication Providers</title> - +<para><emphasis>Authentication Providers</emphasis> authenticate AMQP and non-AMQP connections on Broker <emphasis>Ports</emphasis>. +Multiple <emphasis>Authentication Providers</emphasis> can be configured on the Broker at the same time, +however, only one can be assigned to the concrete Port.</para> +<para> + The following authentication providers are implemented and supported: + <itemizedlist> + <listitem><para><link linkend= "Java-Broker-Security-Anonymous-Provider">Anonymous</link> + allows anonymous connections to the broker</para></listitem> + <listitem><para><link linkend= "Java-Broker-Security-External-Provider">External</link> + delegates authentication to the external authentication mechanisms like Client Certificate Authentication etc</para></listitem> + <listitem><para><link linkend= "Java-Broker-Security-Kerberos-Provider">Kerberos</link> + uses GSS-API SASL mechanism to authenticate connections</para></listitem> + <listitem><para><link linkend= "Java-Broker-Security-LDAP-Provider">SimpleLDAP</link> + authenticate users against LDAP server.</para></listitem> + <listitem><para><link linkend= "Java-Broker-Security-PlainPasswordFile-Provider">PlainPasswordFile</link> + authenticate users against credentials stored in local file.</para></listitem> + <listitem><para><link linkend= "Java-Broker-Security-Base64MD5PasswordFile-Provider">Base64MD5PasswordFile</link> + similar to the above but the password credentials are encoded and different SASL mechanisms are used for authentication.</para></listitem> + </itemizedlist> +</para> +<para><emphasis>Authentication Providers</emphasis> can be split into two categories: + <itemizedlist> + <listitem><para><emphasis>User managing providers</emphasis> allowing to add/delete credentials using Broker management interfaces.</para></listitem> + <listitem><para><emphasis>User non-managing providers</emphasis> using externally stored credentials for authentication.</para></listitem> + </itemizedlist> +</para> +<para>The configuration details for Authentication Providers are covered in <xref linkend= "Java-Broker-Security-Authentication-Providers"/>.</para> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml index af14b46a69..47c7b72b4d 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml @@ -22,5 +22,27 @@ <section id="Java-Broker-Concepts-Exchanges"> <title>Exchanges</title> - +<para><emphasis>Exchange</emphasis> is the named entity within the <emphasis>Virtual Host</emphasis> which receives messages from producer applications and +optionally routes them to message queues within the <emphasis>Virtual Host</emphasis>. The message routing occurs based on exchange routing algorithm +and queue <emphasis>Bindings</emphasis>.</para> +<para> +The following <emphasis>Exchanges</emphasis> are implemented and supported by the <emphasis>Broker</emphasis>: + <itemizedlist> + <listitem><para><emphasis>Direct Exchange</emphasis> provides routing of messages to zero or more queues based on an exact match between +the routing key of the message, and the binding key used to bind the queue to the exchange + </para></listitem> + <listitem><para><emphasis>Topic Exchange</emphasis> provides routing to bound queues based on a pattern match between the binding key and the +routing key of the message. This exchange type is used to support the classic publish/subscribe paradigm using a topic namespace as the +addressing model to select and deliver messages across multiple consumers based on a partial or full match on a topic pattern. + </para></listitem> + <listitem><para><emphasis>Fanout Exchange</emphasis> provides routing of messages to all bound queues regardless of the message's routing key. + </para></listitem> + <listitem><para><emphasis>Headers Exchange</emphasis> provides routing based on header properties within the AMQP message. + The message is passed to the queue if the headers property matches the arguments with which the queue was bound. + </para></listitem> + </itemizedlist> +</para> +<para>Also, Broker supports the concept of a Default Exchange to which all queues are bound using their name as a binding key.</para> +<para>Any number of exchanges of any type can be created on <emphasis>Virtual Host</emphasis>.</para> +<para>Exchange configuration is covered in <xref linkend="Java-Broker-Exchanges"/>.</para> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Other-Services.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Other-Services.xml index bb694d81da..df1600273b 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Other-Services.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Other-Services.xml @@ -22,5 +22,34 @@ <section id="Java-Broker-Concepts-Other-Services"> <title>Other Services</title> +<para>The Broker can also contain Access Control Providers, Group Providers, Keystore, Trustores and Management Plugins.</para> + + <section id="Java-Broker-Concepts-Access-Control-Providers"> + <title>Access Control Providers</title> + <para><emphasis>Access Control Providers</emphasis> are used to authorize the access to the various Broker objects.</para> + <para>The ACL configuration and management details are covered in <xref linkend="Java-Broker-Security-ACLs"/>.</para> + </section> + + <section id="Java-Broker-Concepts-Group-Providers"> + <title>Group Providers</title> + <para><emphasis>Group Providers</emphasis> are used to aggregate Broker authenticated principals into groups + which can be used to define ACL rules applicable to the whole group.</para> + <para>The Group Provider configuration and management is covered in <xref linkend="Java-Broker-Security-Group-Providers"/>.</para> + </section> + + <section id="Java-Broker-Keystore-Providers"> + <title>Keystores</title> + <para><emphasis>Keystore</emphasis> are used to configure keystores holding SSL keys and certificates + for the SSL transports on Ports.</para> + <para>The Keystore configuration and management is covered in <xref linkend="Java-Broker-SSL-Keystore"/>.</para> + </section> + + <section id="Java-Broker-Truststore-Providers"> + <title>Truststores</title> + <para><emphasis>Truststore </emphasis> are used to configure keystores holding SSL certificates + for Client Certificate Authentication on SSL ports. + </para> + <para>The Truststore configuration and management is covered in <xref linkend="SSL-Truststore-ClientCertificate"/>.</para> + </section> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Ports.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Ports.xml index afbb612bc4..d3ef268f52 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Ports.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Ports.xml @@ -22,5 +22,29 @@ <section id="Java-Broker-Concepts-Ports"> <title>Ports</title> +<para><emphasis>Port</emphasis> is a named broker entity serving as a communications end-point +and providing the AMQP transport layer over the given TCP port. The particular AMQP protocols can be configured on the Port. +As result, different <emphasis>Ports</emphasis> can support different protocols. Any number of <emphasis>Ports</emphasis> +can be configured on the Broker.</para> +<para> + The following AMQP protocols are currently supported by the Broker: + <itemizedlist> + <listitem><para><emphasis>AMQP 0.8</emphasis></para></listitem> + <listitem><para><emphasis>AMQP 0.9</emphasis></para></listitem> + <listitem><para><emphasis>AMQP 0.9.1</emphasis></para></listitem> + <listitem><para><emphasis>AMQP 0.10</emphasis></para></listitem> + <listitem><para><emphasis>AMQP 1.0</emphasis></para></listitem> + </itemizedlist> +</para> +<para>Ports are also responsible for the authentication of all incoming connections +by mean of <emphasis>Authentication Provider</emphasis> configured on the Port. +Each Port can have its own <emphasis>Authentication Provider</emphasis>.</para> +<para>Both TCP and SSL transports are supported and can be configured on the <emphasis>Ports</emphasis>. +AMQP ports also support Client Certificate Authentication.</para> + +<para>Besides AMQP ports HTTP and JMX ports can be configured for use by management plugins. +They can be configured by specifying HTTP and RMI/JMX_RMI protocols respectively.</para> + +<para>Configuration details for the Ports are covered in <xref linkend="Java-Broker-Ports"/>.</para> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Protocols.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Protocols.xml deleted file mode 100644 index 45a62ce5ab..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Protocols.xml +++ /dev/null @@ -1,26 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- - - 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. - ---> - -<section id="Java-Broker-Concepts-Protocols"> -<title>Protocols</title> - -</section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Queues.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Queues.xml index a4b0995a7e..ae6ea04269 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Queues.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Queues.xml @@ -22,5 +22,18 @@ <section id="Java-Broker-Concepts-Queues"> <title>Queues</title> - +<para>Message queues are named entities that store messages in memory or on the disk and deliver them in sequence +to connected consumer applications.</para> +<para>The queues are hosted by the <link linkend="Java-Broker-Concepts-Virtual-Hosts">Virtual Hosts</link>. +Any number of queues can be created on <emphasis>Virtual Host</emphasis>.</para> +<para>The following types of Queues are currently supported: + <itemizedlist> + <listitem><para><link linkend="Java-Broker-Queues">Simple</link> is a simple FIFO queue</para></listitem> + <listitem><para><link linkend="Java-Broker-Queues-OtherTypes-Priority">Priority</link> where messages delivery order depends from the message priority</para></listitem> + <listitem><para><link linkend="Java-Broker-Queues-OtherTypes-Sorted">Sorted</link> where messages delivery order depends from the message sorting key value</para></listitem> + <listitem><para><link linkend="Java-Broker-Queues-OtherTypes-LVQ">Last Value Queue</link> automatically discards older message when + a newer message arrives with the same key value</para></listitem> + </itemizedlist> +</para> +<para>Queue configuration details are covered in <xref linkend="Java-Broker-Queues"/>.</para> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Virtual-Hosts.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Virtual-Hosts.xml index c12a543140..bf9367bf15 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Virtual-Hosts.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Virtual-Hosts.xml @@ -22,5 +22,36 @@ <section id="Java-Broker-Concepts-Virtual-Hosts"> <title>Virtual Hosts</title> - +<para>Broker comprises from one or many <emphasis>Virtual Hosts</emphasis>. +<emphasis>Virtual Host</emphasis> can be defined as a collection of exchanges, message queues and associated objects and +is an independent server domain that share a common authentication, encryption and transport environment. +</para> +<para> + The following diagram depicts the Virtual Host model: + <figure> + <title>Virtual Host Model</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/VirtualHost-Model.png" format="PNG" scalefit="1"/> + </imageobject> + <textobject> + <phrase>Virtual Host Model</phrase> + </textobject> + </mediaobject> + </figure> +</para> +<para>Each <emphasis>Virtual Host</emphasis> has its own <emphasis>Message Store</emphasis> +which is used to store the persistent messages from all <link linkend="Java-Broker-Concepts-Queues">Queues</link> +declared on the <emphasis>Virtual Host</emphasis>.</para> +<para> + The following message stores are currently supported: + <itemizedlist> + <listitem><para><link linkend="Java-Broker-Stores-SQL-Store">JDBC Message Store</link></para></listitem> + <listitem><para><link linkend="Java-Broker-Stores-Derby-Store">Derby Message Store</link></para></listitem> + <listitem><para><link linkend="Java-Broker-Stores-BDB-Store">Berkeley DB Message Store</link></para></listitem> + <listitem><para><link linkend="Java-Broker-Stores-HA-BDB-Store">Berkeley DB HA Message Store</link></para></listitem> + <listitem><para><link linkend="Java-Broker-Stores-Memory-Store">Memory Message Store</link></para></listitem> + </itemizedlist> +</para> +<para>Virtual Hosts configuration is covered in <xref linkend="Java-Broker-Virtual-Hosts"/>.</para> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts.xml index 013308fb8f..0ebf6124a0 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts.xml @@ -22,11 +22,37 @@ <chapter id="Java-Broker-Concepts"> <title>Concepts</title> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Virtual-Hosts.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Exchanges.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Queues.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Ports.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Protocols.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Authentication-Providers.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Other-Services.xml"/> + + <section id="Java-Broker-Concepts-Broker"> + <title>Broker</title> + <para>The Qpid Broker can be defined as a collection of <emphasis>Virtual Hosts</emphasis> (independent containers of <emphasis>Queues</emphasis>, + <emphasis>Exchanges</emphasis>, etc) sharing the same authentication model provided by the broker <emphasis>Authentication Providers</emphasis> + and the transport model defined as <emphasis>Port</emphasis> configured objects. The authorization model is either provided by the broker + <emphasis>Access Control Providers</emphasis> or <emphasis>Access Control List</emphasis> defined on the <emphasis>Virtual Hosts</emphasis>. + The Broker also provides the management plugins to manage and configure Broker's and Virtual Hosts' configured objects. + Additionally, <emphasis>Keystores</emphasis> and <emphasis>Truststores</emphasis> can be defined on the broker level to configure Port SSL transports. + The <emphasis>Group Providers</emphasis> can be configured to use groups with <emphasis>ACL Providers</emphasis>. + </para> + <para> + The following diagram depicts the Broker model: + <figure> + <title>Broker Model</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Broker-Model.png" format="PNG" scalefit="1"/> + </imageobject> + <textobject> + <phrase>Broker Model</phrase> + </textobject> + </mediaobject> + </figure> + </para> + </section> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Virtual-Hosts.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Exchanges.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Queues.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Ports.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Authentication-Providers.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Other-Services.xml"/> </chapter> 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 66d471fb37..a184fea671 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 @@ -21,158 +21,156 @@ --> <section id="Java-Broker-Configuring-And-Managing-Config-Files"> -<title>Config Files</title> +<title>Broker Configuration</title> - <para> - This section shows how to configure and manage broker. - </para> + <para>This section provides the details about broker configuration store.</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. + <section id="Java-Broker-Configuring-And-Managing-Configuration-Store-Introduction"> + <title>Configuration store</title> + <para>The Broker has a configuration store and provides management interfaces to manage the broker components. + The configuration for each broker component is stored in the store as a configuration entry. + The following configuration entries can be stored there: + <itemizedlist> + <listitem><para>Broker</para></listitem> + <listitem><para>Port</para></listitem> + <listitem><para>Authentication Provider</para></listitem> + <listitem><para>Virtual Host</para></listitem> + <listitem><para>Access Control Provider</para></listitem> + <listitem><para>Group Provider</para></listitem> + <listitem><para>Key store</para></listitem> + <listitem><para>Trust store</para></listitem> + <listitem><para>Plugin</para></listitem> + </itemizedlist> </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>When broker is started for a first time a configuration store is created automatically from + the internal initial configuration. The created broker configuration is placed into broker working folder + if the broker configuration store location is not specified.</para> + <para>The predefined initial configuration can be overridden using command line argument <emphasis>-icp</emphasis> + with path to the initial configuration as in the example below:</para> + <screen> +$ ./qpid-server -icp ./my-initial-configuration.json + </screen> + <para>In this example the initial configuration from file "./my-initial-configuration.json" is used + to create the broker configuration store on the broker startup.</para> + <para>If broker configuration store already exists the command line argument <emphasis>-icp</emphasis> with the path + to a custom initial configuration is ignored. The command line argument <emphasis>-os</emphasis> can be used + to force the (re)creation of broker configuration store from initial store even when broker configuration store exists. + The example below demonstrates this:</para> + <screen> +$ ./qpid-server -os -icp ./my-initial-configuration.json + </screen> <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>: + The default initial configuration can be retrieved from the broker and stored into a file + using a command line argument <emphasis>-cic <path to file ></emphasis>, for example:</para> + <screen> +$ ./qpid-server -cic ./initial-config.json + </screen> + <para>In the example above the broker default initial configuration saved at "./initial-config.json". + A custom initial configuration can be created from the default one by using this command line argument.</para> + <para>The default initial configuration declares four ports: <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> + <listitem><para><emphasis>AMQP</emphasis>, the default port number is 5672. The port number + can be overridden using configuration parameter <emphasis>qpid.amqp_port</emphasis>.</para></listitem> + <listitem><para><emphasis>HTTP</emphasis>, the default port number is 8080. The port number + can be overridden using configuration parameter <emphasis>qpid.HTTP_port</emphasis>.</para></listitem> + <listitem><para><emphasis>RMI</emphasis>, the default port number is 8999. The port number + can be overridden using configuration parameter <emphasis>qpid.rmi_port</emphasis>.</para></listitem> + <listitem><para><emphasis>JMX</emphasis>, the default port number is 9099. The port number + can be overridden using configuration parameter <emphasis>qpid.jmx_port</emphasis>.</para></listitem> </itemizedlist> + It is also possible to override the port numbers in a default initial configuration using a command line + argument <emphasis>-prop</emphasis> like in an example below: </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. + <screen> +$ ./qpid-server -prop qpid.amqp_port=10000 -prop qpid.http_port=10001 -prop qpid.jmx_port=10002 -prop qpid.rmi_port=10003 + </screen> + <para>In the example above, port number 10000 is specified for AMQP port, port number 10001 is specified for HTTP port, + port number 10002 is specified for JMX port and port number 1003 is specified for RMI port. When specified, + these port numbers will be used to create the broker configuration store from initial configuration on first broker start-up. + If configuration store already exists the settings will not have any effect. The command line argument <emphasis>-os</emphasis> + can be used to force (re)creation of broker configuration store from initial store. </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> + <para>The command line argument <emphasis>-sp</emphasis> is used to specify a relative or absolute path to a broker + configuration store to start broker with. If the store at specified location does not exist it will be created from + the initial configuration. It is not required to provide the path to configuration store on broker on start-up.</para> + <screen> +$ ./qpid-server -sp ./my-broker-configuration.json + </screen> + <para>In the example above the broker is started with configuration store at "./my-broker-configuration.json".</para> </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> + + <section id="Java-Broker-Configuring-And-Managing-Configuration-Store-Example"> + <title>Example of JSON configuration store</title> + <para>The JSON configuration store is used as a default configuration store. + An example of the JSON store is provided below:</para> <example> - <title>Enabling web management</title> - <programlisting> -<broker> -... -<management> -... - <http> - <enabled>true</enabled> <co id="java-broker-example-management-web-0"/> - <port>9090</port> <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> + <title>JSON configuration store</title> + <programlisting><![CDATA[ +{ + "name" : "Broker", + "defaultVirtualHost" : "default", + "modelVersion" : "1.0", + "storeVersion" : 1, + "authenticationproviders" : [ { + "name" : "passwordFile", + "path" : "${qpid.work_dir}/etc/passwd", + "type" : "PlainPasswordFile" + } ], + "ports" : [ { + "authenticationProvider" : "passwordFile", + "name" : "HTTP", + "port" : "8080", + "protocols" : [ "HTTP" ] + }, { + "authenticationProvider" : "passwordFile", + "name" : "JMX_CONNECTOR", + "port" : "9099", + "protocols" : [ "JMX_RMI" ] + }, { + "name" : "RMI_REGISTRY", + "port" : "8999", + "protocols" : [ "RMI" ] + }, { + "name" : "AMQP", + "port" : "5672" + } ], + "virtualhosts" : [ { + "name" : "default", + "storePath" : "${qpid.work_dir}/derbystore/default", + "storeType" : "DERBY" + } ], + "plugins" : [ { + "name" : "jmxManagement", + "pluginType" : "MANAGEMENT-JMX" + }, { + "name" : "httpManagement", + "pluginType" : "MANAGEMENT-HTTP" + } ] +} +]]></programlisting> + <para>In the configuration above the following entries are stored: + <itemizedlist> + <listitem><para>Authentication Provider of type <emphasis>PlainPasswordFile</emphasis> with name "passwordFile"</para></listitem> + <listitem><para>Four Port entries: "AMQP", "HTTP", "RMI_REGISTRY", "JMX_CONNECTOR"</para></listitem> + <listitem><para>Virtual Host with name "default" and DERBY message store type at location "${qpid.work_dir}/derbystore/default".</para></listitem> + <listitem><para>Two management plugins: "jmxManagement" of type "MANAGEMENT-JMX" and "httpManagement" of type "MANAGEMENT-HTTP".</para></listitem> + <listitem><para>Broker attributes are stored as a root entry.</para></listitem> + </itemizedlist> + </para> + </example> + </section> - <https> - <enabled>true</enabled> <co id="java-broker-example-management-web-5"/> - <port>9443</port> <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> + <section id="Java-Broker-Attributes-Configuring"> + <title>Configuring Broker Attributes</title> + + <para>The Broker Attributes can be configured using + <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> + and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>.</para> + + <para>The Broker attributes can be changed from Web Management Console by clicking on "Edit" button + on "Broker Attributes" panel from Broker tab. + </para> + + </section> + +</section>
\ No newline at end of file diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml index 122da6d267..498494d81a 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml @@ -21,6 +21,16 @@ --> <section id="Java-Broker-Configuring-And-Managing-JMX"> -<title>JMX</title> + <title>JMX Plugin</title> + + <para>JMX Management Plugin exposes JMX management interfaces to manage the Broker. + It is included into initial configuration by default and starts the RMI registry and JMX connector on pre-configured RMI and JMX ports. + If any or both JMX Ports are missed but JMX Management Plugin entry is present in the Broker configuration the Broker fails to start. + Only one JMX Management Plugin can be configured on the Broker. + </para> + + <para>JMX Management Plugin can start its own MBean server or can use a platform MBean server. + By default, the platform MBean server is used. This is controlled by the value of the plugin attribute "Use Platform MBean Server". + The value of this attribute can be changed through REST management interface but takes effect only on next Broker restart.</para> </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 8bd63ade7a..66dc737354 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 @@ -24,12 +24,12 @@ <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 + <para>This section provides an overview of REST management interfaces.</para> + <para>If web management plugin is configured + the REST interfaces can be used to monitor and manage the Broker instance.</para> + <para>The Qpid broker REST interfaces 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> + PUT to create or update the configured object and POST to perform the configured objects updates not available with the PUT requests.</para> <para>The table below lists the available REST services with brief description how they can be used.</para> <table> @@ -50,7 +50,7 @@ <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>Updates broker attributes</para></entry> <entry><para>Not implemented yet</para></entry> <entry><para>Not implemented yet</para></entry> </row> @@ -60,9 +60,9 @@ </entry> <entry>Rest service to manage authentication providers on the broker</entry> <entry>Retrieves the details about authentication providers</entry> + <entry>Creates or updates authentication providers</entry> <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> + <entry>Deletes authentication providers</entry> </row> <row> <entry><para>/rest/user</para> @@ -70,8 +70,8 @@ </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>Creates user account, updates user password</entry> + <entry>Not implemented yet</entry> <entry>Deletes user account</entry> </row> <row> @@ -80,9 +80,9 @@ </entry> <entry>Rest service to manage group providers</entry> <entry>Retrieves the details about group provider(s)</entry> + <entry>Creates group provider</entry> <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> + <entry>Deletes groups providers</entry> </row> <row> <entry><para>/rest/group</para> @@ -111,20 +111,9 @@ </entry> <entry>Rest service to manage broker ports(s)</entry> <entry>Retrieves the details about the broker port(s)</entry> + <entry>Creates or updates port</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> + <entry>Deletes ports</entry> </row> <row> <entry> @@ -231,10 +220,50 @@ <entry>Not implemented yet</entry> <entry>Not implemented yet</entry> </row> + <row> + <entry> + <para>/rest/accesscontrolprovider</para> + </entry> + <entry>Rest service to manage access control providers</entry> + <entry>Retrieves the details about access control providers</entry> + <entry>Creates access control provider</entry> + <entry>Not implemented yet</entry> + <entry>Deletes access control provider(s)</entry> + </row> + <row> + <entry> + <para>/rest/keystore</para> + </entry> + <entry>Rest service to manage KeyStores</entry> + <entry>Retrieves the details about KeyStore</entry> + <entry>Creates or updates KeyStore</entry> + <entry>Not implemented yet</entry> + <entry>Deletes KeyStore(s)</entry> + </row> + <row> + <entry> + <para>/rest/truststore</para> + </entry> + <entry>Rest service to manage TrustStore</entry> + <entry>Retrieves the details about TrustStore</entry> + <entry>Creates or updates TrustStore</entry> + <entry>Not implemented yet</entry> + <entry>Deletes TrustStore(s)</entry> + </row> + <row> + <entry> + <para>/rest/plugin</para> + </entry> + <entry>Rest service to manage plugins</entry> + <entry>Retrieves the details about plugins</entry> + <entry>Updates plugin attributes</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 + <para>Rest URLs 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> @@ -258,6 +287,6 @@ curl -X PUT -d '{"durable":true,"type":"priority"}' http://localhost:8080/rest/ 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> + <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 406f2fbe08..6e3b44dab8 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 @@ -22,14 +22,14 @@ <section id="Java-Broker-Configuring-And-Managing-Web-Console"> <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> + <para>If web management is configured the Web Mnagement 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> + <listitem><para><emphasis>port</emphasis> is the HTTP(s) port number</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> + <para>For authenticated and authorized user the page like below should be displayed on navigation to the management URL:</para> + <ulink url="images/Management-Web-Console.png"> + <graphic fileref="images/Management-Web-Console.png" width="600px"/> + </ulink> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Management.xml b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Management.xml new file mode 100644 index 0000000000..1c6a7c4d20 --- /dev/null +++ b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Management.xml @@ -0,0 +1,53 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + 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. + +--> + +<section id="Java-Broker-Configuring-And-Managing-Web-Management"> + <title>Web Management</title> + + <para>Web Management Plugin exposes REST management interfaces and provides the Web Management Console to configure the Broker. + It is included into initial configuration by default and starts the servlet container on pre-configured HTTP ports. + If no HTTP Port is configured but Web Management Plugin entry is present in the Broker configuration the Broker fails to start. + Only one Web Management Plugin can be configured on the Broker. + </para> + + <para>Web Management itself can be configured through REST management interfaces and Web Management Console. + The following attributes can be set on Web Management Plugin: + <itemizedlist> + <listitem><para><emphasis>Basic Authentication for HTTP</emphasis> is flag to enable/disable + Basic Authentication on HTTP ports. It is set to false by default.</para></listitem> + <listitem><para><emphasis>Basic Authentication for HTTPS</emphasis> is flag to enable/disable + Basic Authentication on HTTPS ports. It is set to true by default.</para></listitem> + <listitem><para><emphasis>SASL Authentication for HTTP</emphasis> is flag to enable/disable + SASL Authentication on HTTP ports. It is set to true by default.</para></listitem> + <listitem><para><emphasis>SASL Authentication for HTTPS</emphasis> is flag to enable/disable + SASL Authentication on HTTPS ports. It is set to true by default.</para></listitem> + <listitem><para><emphasis>Session timeout</emphasis> is the timeout in seconds to close the HTTP session. + It is set to 10 minutes by default.</para></listitem> + </itemizedlist> + On clicking on Web Management Plugin name in Broker object tree the tab for Web Management Plugin is displayed with current plugin settings. + The plugin attributes can be changed by clicking on "Edit" button in Plugin tab. The changes will take effect only after Broker is restarted. + </para> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Configuring-And-Managing-Web-Console.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Configuring-And-Managing-REST-API.xml"/> + +</section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing.xml b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing.xml index d0858a80c0..9a07c37861 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing.xml @@ -23,8 +23,7 @@ <chapter id="Java-Broker-Configuring-And-Managing"> <title>Configuring And Managing</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Configuring-And-Managing-Config-Files.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Configuring-And-Managing-Web-Console.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Configuring-And-Managing-REST-API.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Configuring-And-Managing-Web-Management.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Configuring-And-Managing-JMX.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Configuring-And-Managing-Other-Tooling.xml"/> </chapter> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Exchanges.xml b/qpid/doc/book/src/java-broker/Java-Broker-Exchanges.xml index f6272fb0f3..7fe0df1410 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Exchanges.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Exchanges.xml @@ -23,4 +23,29 @@ <chapter id="Java-Broker-Exchanges"> <title>Exchanges</title> + <section id="Java-Broker-Exchanges-Configuring"> + <title>Configuring Virtual Host Exchanges</title> + + <para>The Virtual Host Exchanges can be configured using + <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link>, + <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link> and Virtual Host configuration file.</para> + + <para>The following Exchange managing operations are available from Web Management Console: + <itemizedlist> + <listitem><para>A new Exchange can be added by clicking on "Add Exchange" on the Virtual Host tab.</para></listitem> + <listitem><para>An existing Exchange details can be viewed the Exchange tab. + Exchange tab is shown after clicking on Exchange name in Broker object tree or by clicking on Exchange row in Exchanges grid on Virtual Host tab.</para></listitem> + <listitem><para>An existing Exchange can be deleted by clicking on "Delete Exchange" button + on Virtual Host tab or "Delete Exchange" button on the Exchange tab.</para></listitem> + <listitem><para>An existing Queue can be bound to the Exchange by clicking on "Add Binding" button + on the Exchange tab.</para></listitem> + <listitem><para>An existing Queue binding can be deleted from Exchange by clicking on "Delete Binding" button + on the Exchange tab.</para></listitem> + </itemizedlist> + </para> + + <para>An example of configuring Exchanges in Virtual Host configuration file is provided + in <xref linkend="Java-Broker-Virtual-Host-Configuration-Exchange"/>.</para> + </section> + </chapter> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Getting-Started.xml b/qpid/doc/book/src/java-broker/Java-Broker-Getting-Started.xml index 061d574362..e90dadd126 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Getting-Started.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Getting-Started.xml @@ -26,7 +26,11 @@ <chapter id="Java-Broker-Getting-Started"> <title>Getting Started</title> - <para>This section describes how to start the Java Broker for the first time.</para> + <para> + This section describes how to start the Java Broker for the first time. + The Broker configuration details and configuration command line arguments are described in <xref linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Introduction"/>. + </para> + <section role="h2" id="Java-Broker-Getting-Started-Starting"> <title>Starting/Stopping the Broker</title> <para>To start the Broker, use the <command>qpid-server</command> script (UNIX) or <command>qpid-server.bat</command> (Windows) @@ -39,19 +43,19 @@ <para>Now use the <command>qpid-server.bat</command> to start the server</para> <programlisting><![CDATA[bin\qpid-server.bat]]></programlisting> <para>Output similar to the following will be seen:</para> - <screen>[Broker] BRK-1006 : Using configuration : C:\qpid\qpid-broker-&qpidCurrentRelease;\etc\config.xml + <screen>[Broker] BRK-1006 : Using configuration : C:\qpidwork\config.json [Broker] BRK-1007 : Using logging configuration : C:\qpid\qpid-broker-&qpidCurrentRelease;\etc\log4j.xml -[Broker] BRK-1001 : Startup : Version: &qpidCurrentRelease; Build: 1411386 -[Broker] BRK-1010 : Platform : JVM : Sun Microsystems Inc. version: 1.6.0_24-b07 OS : Windows 7 version: 6.1 arch: amd64 -[Broker] BRK-1011 : Maximum Memory : 1,069,416,448 bytes -[Broker] MNG-1001 : Web Management Startup -[Broker] MNG-1002 : Starting : HTTP : Listening on port 8080 -[Broker] MNG-1004 : Web Management Ready +[Broker] BRK-1001 : Startup : Version: &qpidCurrentRelease; Build: 1478262 +[Broker] BRK-1010 : Platform : JVM : Oracle Corporation version: 1.7.0_21-b11 OS : Windows 7 version: 6.1 arch: x86 +[Broker] BRK-1011 : Maximum Memory : 1,060,372,480 bytes +[Broker] BRK-1002 : Starting : Listening on TCP port 5672 [Broker] MNG-1001 : JMX Management Startup [Broker] MNG-1002 : Starting : RMI Registry : Listening on port 8999 [Broker] MNG-1002 : Starting : JMX RMIConnectorServer : Listening on port 9099 [Broker] MNG-1004 : JMX Management Ready -[Broker] BRK-1002 : Starting : Listening on TCP port 5672 +[Broker] MNG-1001 : Web Management Startup +[Broker] MNG-1002 : Starting : HTTP : Listening on port 8080 +[Broker] MNG-1004 : Web Management Ready [Broker] BRK-1004 : Qpid Broker Ready</screen> <para>The BRK-1004 message confirms that the Broker is ready for work. The MNG-1002 and BRK-1002 confirm the ports to which the Broker is listening (for HTTP/JMX management and AMQP respectively).</para> @@ -65,11 +69,12 @@ <para>Now use the <command>qpid-server</command> script to start the server:</para> <programlisting><![CDATA[bin\qpid-server]]></programlisting> <para>Output similar to the following will be seen:</para> - <screen>[Broker] BRK-1006 : Using configuration : /usr/local/qpid/qpid-broker-&qpidCurrentRelease;/etc/config.xml + <screen>[Broker] BRK-1006 : Using configuration : /var/qpidwork/config.json [Broker] BRK-1007 : Using logging configuration : /usr/local/qpid/qpid-broker-&qpidCurrentRelease;/etc/log4j.xml -[Broker] BRK-1001 : Startup : Version: &qpidCurrentRelease; Build: 1411386 -[Broker] BRK-1010 : Platform : JVM : Apple Inc. version: 1.6.0_35-b10-428-11M3811 OS : Mac OS X version: 10.8.2 arch: x86_64 -[Broker] BRK-1011 : Maximum Memory : 1,070,399,488 bytes +[Broker] BRK-1001 : Startup : Version: &qpidCurrentRelease; Build: exported +[Broker] BRK-1010 : Platform : JVM : Sun Microsystems Inc. version: 1.6.0_32-b05 OS : Linux version: 3.6.10-2.fc16.x86_64 arch: amd64 +[Broker] BRK-1011 : Maximum Memory : 1,065,025,536 bytes +[Broker] BRK-1002 : Starting : Listening on TCP port 5672 [Broker] MNG-1001 : Web Management Startup [Broker] MNG-1002 : Starting : HTTP : Listening on port 8080 [Broker] MNG-1004 : Web Management Ready @@ -77,7 +82,6 @@ [Broker] MNG-1002 : Starting : RMI Registry : Listening on port 8999 [Broker] MNG-1002 : Starting : JMX RMIConnectorServer : Listening on port 9099 [Broker] MNG-1004 : JMX Management Ready -[Broker] BRK-1002 : Starting : Listening on TCP port 5672 [Broker] BRK-1004 : Qpid Broker Ready</screen> <para>The BRK-1004 message confirms that the Broker is ready for work. The MNG-1002 and BRK-1002 confirm the ports to which the Broker is listening (for HTTP/JMX management and AMQP respectively).</para> @@ -139,6 +143,11 @@ -os overwrite the broker configuration store --overwrite-store with the current initial configuration + -prop,--config-property <name=value> set a configuration property to use when + resolving variables in the broker + configuration store, with format + 'name=value' + -sp <path> use given configuration store location --store-path <path> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml b/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml new file mode 100644 index 0000000000..e4661d6b7e --- /dev/null +++ b/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml @@ -0,0 +1,95 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + 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. + +--> + +<chapter id="Java-Broker-Ports"> + <title>Broker Ports</title> + <para>This section guides through the process of configuring of Broker AMQP and non-AMQP ports.</para> + + <section id="Java-Broker-Ports-Configuring"> + <title>Configuring Broker Ports</title> + <para>The Broker Ports can be configured using + <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> + and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>.</para> + + <para>The following Port managing operations are available from Web Management Console: + <itemizedlist> + <listitem><para>A new Port can be created by clicking "Add Port" button on the Broker tab.</para></listitem> + <listitem><para>An existing Port details are displayed on the Port tab after clicking + on Port name in the Broker object tree or after clicking on a Port row in the Ports grid on the Broker tab.</para></listitem> + <listitem><para>An existing Port can be edited by clicking on "Edit" button on the Port tab.</para></listitem> + <listitem><para>An existing Port can be deleted by clicking on "Delete Port" button + on Broker tab or "Delete" button on the Port tab.</para></listitem> + </itemizedlist> + </para> + + <para>Three different types of ports can be created: + <itemizedlist> + <listitem><para>AMQP ports accepting connections for supported AMQP protocols.</para></listitem> + <listitem><para>HTTP ports accepting connections for HTTP and HTTPS protocols and used by web management plugin.</para></listitem> + <listitem><para>RMI ports supporting RMI and JMX_RMI protocols and used by JMX management plugin.</para></listitem> + </itemizedlist> + </para> + + <para>On creation or editing of AMQP port the port protocols can be specified from the list of supported AMQP protocols. + Any number of AMQP ports with any combination of supported protocols can be configured on the Broker.</para> + + <para>It is possible to create any number of HTTP/HTTPS ports. However, only two JMX ports are recommended + to configure on the Broker: one with RMI protocol and another with JMX_RMI protocol. + The creation of more JMX protocols might result in unexpected behavior. When more then two JMX ports are configured + the JMX plugin will pick up only two of them (having different RMI protocols) in indeterministic order.</para> + + <para>Both TCP and SSL transports are supported by AMQP and HTTP ports. + The Keystore is required to configure on Port for SSL transport support. + The details of Keystore configuration are covered in <xref linkend="Java-Broker-SSL-Keystore"/>. + SSL transport is also supported by the JMX connector port (having protocol set to "JMX_RMI") + but JMX RMI port (having protocol set to "RMI") does not support SSL transport.</para> + + <para>Client Certificate Authentication can be configured with AMQP ports only. This requires configuring + of one or more Trustores on the Port and setting of needClientAuthentication and wantClientAuthentication attributes. + They allow control of whether the client must present an SSL certificate. Only one of these elements is needed but both + may be used at the same time. A socket's client authentication setting is one of three states: + required (needClientAuth = true), requested (wantClientAuth = true), or none desired (both false, the default). + If both elements are set to true, needClientAuth takes precedence. When using Client Certificate Authentication + it may be desirable to use the External Authentication Provider, for details see <xref linkend="Java-Broker-Security-External-Provider"/>. + The details how to configure Trustores are covered in <xref linkend="SSL-Truststore-ClientCertificate"/>.</para> + + <para>An Authentication Provider is required to configure on AMQP, HTTP and JMX connector(having protocol set to "JMX_RMI") ports. + JMX RMI port (having protocol set to "RMI") does not require setting of Authentication Provider. + For Authentication Provider configuration details see <xref linkend="Java-Broker-Security-Authentication-Providers"/></para> + + <important> + Neither Port type no name can be changed for existing Port as editing of name and type is unsupported at the moment. + </important> + + <important> + The changes of port attributes will take effect only after broker restart. + </important> + + <important> + On deletion of active Port all opened connections remain opened until they are closed by the clients or Broker is shutdown + or connection Virtual Hosts are deleted or stopped. When Port is deleted with active connections, the creation of another Port + having the same port number as deleted one fails. + </important> + + </section> + +</chapter> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Queues-Messaging-Groups.xml b/qpid/doc/book/src/java-broker/Java-Broker-Queues-Messaging-Groups.xml deleted file mode 100644 index 60413282a0..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Queues-Messaging-Groups.xml +++ /dev/null @@ -1,26 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- - - 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. - ---> - -<section id="Queues-Messaging-Groups"> -<title>Messaging Groups</title> - -</section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml b/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml index 55f477e338..f24b1fd06d 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml @@ -25,22 +25,23 @@ --> <section id="Java-Broker-Queues-OtherTypes"> - <title>Other Queue Types</title> + <title>Queue Types</title> <section role="h2" id="Java-Broker-Queues-OtherTypes-Introduction"> <title>Introduction</title> <para> In addition to the standard queue type where messages are delivered in the same order - that they were sent, the Java Broker supports four additional queue types which allows for + that they were sent, the Java Broker supports three additional queue types which allows for alternative delivery behaviours. These are <link linkend="Java-Broker-Queues-OtherTypes-Priority">priority-queues</link>, <link linkend="Java-Broker-Queues-OtherTypes-Sorted">sorted-queues</link>-, - <link linkend="Java-Broker-Queues-OtherTypes-LVQ">last-value-queues</link> (LVQs), and - <link linkend="Java-Broker-Queues-OtherTypes-Message-Grouping">grouped queues</link>. + <link linkend="Java-Broker-Queues-OtherTypes-LVQ">last-value-queues</link> (LVQs). + Additionally, Java Broker supports <link linkend="Java-Broker-Queues-OtherTypes-Message-Grouping">message grouping</link>. </para> <para> In the following sections, the semantics of each queue type is described, followed by a description of how instances of these queue can be created via <link - linkend="Java-Broker-Queues-OtherTypes-CreateUsingConfig">configuration</link> or <link - linkend="Java-Broker-Queues-OtherTypes-CreateUsingJmsOrJmx">programmatically</link>. </para> + linkend="Java-Broker-Queues-OtherTypes-CreateUsingConfig">configuration</link>, <link + linkend="Java-Broker-Queues-OtherTypes-CreateUsingJmsOrJmx">programmatically</link> or + <link linkend="Java-Broker-Queues-OtherTypes-CreateUsingManagement">Web Management Console</link>.</para> <para>The final section discusses the importance of using a <link linkend="Java-Broker-Queues-OtherTypes-SetLowPrefetch">low client pre-fetch</link> with these queued. </para> @@ -85,95 +86,28 @@ <section role="h2" id="Java-Broker-Queues-OtherTypes-Create"> <title>Creating a Priority, Sorted or LVQ Queue</title> <para>To create a priority, sorted or LVQ queue, it can be defined in the virtualhost - configuration file, or the queue can be created programmtically from a client via AMQP (using - an extension to JMS), or using JMX. These methods are described below. </para> + configuration file, can be created programmtically from a client via AMQP (using + an extension to JMS), using JMX, using REST interfaces or created in Web Management Console. + These methods are described below. </para> <para>Once a queue is created you cannot change its type (without deleting it and re-creating). Also note you cannot currently mix the natures of these queue types, for instance, you cannot define a queue which it both an LVQ and a priority-queue.</para> + <section role="h2" id="Java-Broker-Queues-OtherTypes-CreateUsingManagement"> + <title>Using Web Management Console</title> + <para>On clicking on "Add Queue" button on Virtual Host tab the pop-up dialog to create a queue is displayed.</para> + <para>For a Simple queue a Queue Type "Standard" should be selected</para> + <para>For a Priority queue a Queue Type "Priority" and the priority value (10 by default) should be selected.</para> + <para>For a Sorted queue a Queue Type "Sorted" and Sort Message Property should be specified.</para> + <para>For a LVQ queue a Queue Type "LVQ" and LVQ Message Property should be specified.</para> + <para>Additionally, for each type of the queue Flow Control Thresholds and Alert Thresholds can be specified in optional fields.</para> + <para>Also, a Dead Letter Queue can be configured for the Queue by checking "Create DLQ" check box. + The maximum number of delivery retries before message is sent to the DLQ can be specified in "Maximum Delivery Retries" field. + However, configuring of maximum delivery retries on a queue without DLQ(AlternateExchange) will result in messages + being discarded after the limit is reached.</para> + </section> <section role="h2" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig"> - <title>Using configuration</title> - <para>To create a priority, sorted or LVQ queue within configuration, add the appropriate xml - to the virtualhost.xml configuration file within the <varname>queues</varname> - element.</para> - <section role="h3" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig-Priority"> - <title>Priority</title> - <para> To defining a priority queue, add a <priority>true</priority> element. By - default the queue will have 10 distinct priorities. </para> - <example> - <title>Configuring a priority queue</title> - <programlisting><![CDATA[<queue> - <name>myqueue</name> - <myqueue> - <exchange>amq.direct</exchange> - <priority>true</priority> - </myqueue> -</queue>]]></programlisting> - </example> - <para> If you require fewer priorities, it is possible to specify a - <varname>priorities</varname> element (whose value is a integer value between 2 and 10 - inclusive) which will give the queue that number of distinct priorities. When messages are - sent to that queue, their effective priority will be calculated by partitioning the - priority space. If the number of effective priorities is 2, then messages with priority - 0-4 are treated the same as "lower priority" and messages with priority 5-9 are treated - equivalently as "higher priority". </para> - <example> - <title>Configuring a priority queue with fewer priorities</title> - <programlisting><![CDATA[<queue> - <name>myqueue</name> - <myqueue> - <exchange>amq.direct</exchange> - <priority>true</priority> - <priorities>4</priorities> - </myqueue> -</queue>]]></programlisting> - </example> - </section> - <section role="h3" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig-Sorted"> - <title>Sorted</title> - <para> To define a sorted queue, add a <varname>sortKey</varname> element. The value of the - <varname>sortKey</varname> element defines the message property to use the value of when - sorting the messages put onto the queue. </para> - <example> - <title>Configuring a sorted queue</title> - <programlisting><![CDATA[<queue> - <name>myqueue</name> - <myqueue> - <exchange>amq.direct</exchange> - <sortKey>message-property-to-sort-by</sortKey> - </myqueue> -</queue>]]></programlisting> - </example> - </section> - <section role="h3" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig-LVQ"> - <title>LVQ</title> - <para> To define a LVQ, add a <varname>lvq</varname> element with the value - <constant>true</constant>. Without any further configuration this will define an LVQ - which uses the JMS message property <constant>qpid.LVQ_key</constant> as the key for - replacement. </para> - <example> - <title>Configuring a LVQ queue</title> - <programlisting><![CDATA[<queue> - <name>myqueue</name> - <myqueue> - <exchange>amq.direct</exchange> - <lvq>true</lvq> - </myqueue> -</queue>]]></programlisting> - </example> - <para> If you wish to define your own property then you can do so using the - <varname>lvqKey</varname> element.</para> - <example> - <title>Configuring a LVQ queue with custom message property name</title> - <programlisting><![CDATA[<queue> - <name>myqueue</name> - <myqueue> - <exchange>amq.direct</exchange> - <lvq>true</lvq> - <lvqKey>ISIN</lvqKey> - </myqueue> -</queue>]]></programlisting> - </example> - </section> + <title>Using configuration</title> + <para>How to declare queues in the Virtual Host configuration file is described in <xref linkend="Java-Broker-Virtual-Host-Declare-Queues"/>.</para> </section> <section role="h2" id="Java-Broker-Queues-OtherTypes-CreateUsingJmsOrJmx"> <title>Using JMX or AMQP</title> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Queues.xml b/qpid/doc/book/src/java-broker/Java-Broker-Queues.xml index 050d4cdbce..9338ab8462 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Queues.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Queues.xml @@ -22,6 +22,5 @@ <chapter id="Java-Broker-Queues"> <title>Queues</title> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Queues-Messaging-Groups.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Queues-OtherTypes.xml"/> </chapter> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control.xml index 8db014a6b7..cf7660aed7 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control.xml @@ -43,47 +43,17 @@ as overfull when the size (in bytes) of the messages on the queue exceeds the "capacity" of the Queue. A Queue becomes "underfull" when its size becomes less than the "flowResumeCapacity". - - - <example> - <title>Configuring a queue depth limit</title> - <programlisting> - <![CDATA[ -<queue> - <name>test</name> - <test> - <exchange>amq.direct</exchange> - <capacity>10485760</capacity> <!-- set the queue capacity to 10Mb --> - <flowResumeCapacity>8388608</flowResumeCapacity> <!-- set the resume capacity to 8Mb --> - </test> -</queue> - ]]> - </programlisting> - </example> - - The default for all queues on a virtual host can also be set - - <example> - <title>Configuring a default queue depth limit on a virtualhost</title> - <programlisting> - <![CDATA[ -<virtualhosts> - <virtualhost> - <name>localhost</name> - <localhost> - <capacity>10485760</capacity> <!-- set the queue capacity to 10Mb --> - <flowResumeCapacity>8388608</flowResumeCapacity> <!-- set the resume capacity to 8Mb --> - </localhost> - </virtualhost> -</virtualhosts> - ]]> - </programlisting> - </example> - + </para> + <para> + Examples how to configure flow control in virtual host configuration are provided in + <xref linkend="Java-Broker-Virtual-Host-Configure-Flow-Control"/>. + </para> + <para> Where no flowResumeCapacity is set, the flowResumeCapacity is set to be equal to the capacity. Where no capacity is set, capacity is defaulted to 0 meaning there is no capacity limit. </para> + <important>Flow control can be configured globally for all virtual hosts by specifying threshold values for Broker flow control attributes.</important> <section role="h4"> <title>Broker Log Messages</title> <para> @@ -131,23 +101,12 @@ MESSAGE [con:2(guest@anonymous(713889609)/test)/ch:1] [con:2(guest@anonymous(713 <para> underfull limit - when the space on disk drops below this limit, producers are allowed to resume publishing. </para> + <para> - An example of quota configuration for the BDB message store is provided below. + An example how to configure disk quota-based flow control in virtual host configuration is provided in + <xref linkend="Java-Broker-Virtual-Host-Configure-Disk-Quotas"/>. </para> - <example> - <title>Configuring a limit on a store</title> - <programlisting> - <![CDATA[ -<store> - <class>org.apache.qpid.server.store.berkeleydb.BDBMessageStore</class> - <environment-path>${work}/bdbstore/test</environment-path> - <overfull-size>50000000</overfull-size> - <underfull-size>45000000</underfull-size> -</store> - ]]> - </programlisting> - </example> <para> The disk quota functionality is based on "best effort" principle. This means the broker cannot guarantee that the disk space limit will not be exceeded. If several concurrent diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml index 40c0e44629..29c42267e4 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml @@ -102,67 +102,12 @@ <section role="h2" id="Java-Broker-Runtime-Handling-Undeliverable-Messages-Configuration"> <title>Configuration</title> - <para>In the below configuration it can be seen that DLQs/Maximum Delivery Count are enabled at - the broker level with maximum delivery count set to 5, disabled at the virtualhost level for the - 'dev-only' virtualhost, and enabled specifically for the 'dev-only-main-queue' with maximum - delivery count overridden to 5. </para> - <para>As 'dev-only-main-queue' has its own configuration specified, this value overrides all - others and causes the features to be enabled for this queue. In contrast to this, - 'dev-only-other-queue' does not specify its own value and picks up the false value specified for - its parent virtualhost, causing the DLQ/Maximum Delivery Count features to be disabled for this - queue. Any such queue in the 'dev-only' virtualhost which does not specify its own configuration - value will have the DLQ/Maximum Delivery Count feature disabled.</para> - <para>The queue 'localhost-queue' has the DLQ/Maximum Delivery Count features enabled, as neither - the queue itself or the 'localhost' virtualhost specifies a configuration value and so the broker - level value of true is used. Any such queue in the 'localhost' virtualhost which does not specify - its own configuration value will have the features enabled.</para> - <example> - <title>Enabling DLQs and maximum delivery count at broker level within config.xml</title> - <programlisting><![CDATA[<broker> - ... - <deadLetterQueues>true</deadLetterQueues> - <maximumDeliveryCount>5</maximumDeliveryCount> - ... -</broker>]]></programlisting> - </example> - <example> - <title>Enabling DLQs and maximum delivery count at virtualhost and queue level within - virtualhosts.xml</title> - <programlisting><![CDATA[<virtualhosts> - ... - <virtualhost> - <name>dev-only</name> - <dev-only> - <queues> - <deadLetterQueues>false</deadLetterQueues> - <maximumDeliveryCount>0</maximumDeliveryCount> - <queue> - <name>dev-only-main-queue</name> - <dev-only-main-queue> - <deadLetterQueues>true</deadLetterQueues> - <maximumDeliveryCount>3</maximumDeliveryCount> - </dev-only-main-queue> - </queue> - <queue> - <name>dev-only-other-queue</name> - </queue> - </queues> - </dev-only> - </virtualhost> - <virtualhost> - <name>localhost</name> - <localhost> - <queues> - <queue> - <name>localhost-queue</name> - </queue> - </queues> - </localhost> - </virtualhost> - ... -</virtualhosts>]]> - </programlisting> - </example> + <important>DLQs/Maximum Delivery can be configured globally for all Virtual Hosts by + specifying non-zero value for global Broker attribute + "queue.maximumDeliveryAttempts" and setting of Broker attribute "queue.deadLetterQueueEnabled" to true.</important> + + <para>An examples of configuring DLQs/Maximum Delivery Count using Virtual Hosts configuration file + are described in <xref linkend="Java-Broker-Virtual-Host-Configuring-DLQ"/>.</para> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml index 04212d94ed..8ef8528ee1 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml @@ -113,7 +113,8 @@ CHN-1003 : Close]]> <title>Configuration</title> <section role="h3" id="Java-Broker-Runtime-Producer-Transaction-Timeout-Configuration-Overview"> <title>Configuration</title> - <para>Transaction timeouts are configurable separately on each defined virtual host, using the + <important>Transaction timeouts can be configured globally for all virtual hosts by setting corresponding Broker transaction timeout attributes.</important> + <para>Transaction timeouts can be configured separately on each defined virtual host, using the virtualhosts.xml file.</para> <para>We would recommend that only warnings are configured at first, which should allow broker administrators to obtain an idea of the distribution of transaction lengths on their systems, @@ -135,47 +136,9 @@ CHN-1003 : Close]]> </section> <section role="h3" id="Java-Broker-Runtime-Producer-Transaction-Timeout-Configuration-Virtualhosts"> - <title>Virtualhosts.xml</title> - <para> The JMS transaction timeouts are configured on each virtual host defined in the XML - configuration files.</para> - <para> The default values for each of the parameters is 0, indicating that the particular check - is disabled.</para> - <para> Any or all of the parameters can be set, using the desired value in milliseconds, and will - be checked each time the housekeeping process runs, usually set to run every 30 seconds in - standard configuration. The meaning of each property is as follows:</para> - <para> - <itemizedlist> - <listitem> - <para>openWarn - the time a transaction can be open for (with activity occurring on it) after - which a warning alert will be issued.</para> - </listitem> - <listitem> - <para>openClose - the time a transaction can be open for before the connection it is on is - closed.</para> - </listitem> - <listitem> - <para>idleWarn - the time a transaction can be idle for (with no activity occurring on it) - after which a warning alert will be issued.</para> - </listitem> - <listitem> - <para>idleClose - the time a transaction can be idle for before the connection it is on is - closed.</para> - </listitem> - </itemizedlist> - </para> - <para> The virtualhosts configuration is shown below, and must occur inside the - //virtualhosts/virtualhost/name/ elements: </para> - <example> -<title>Configuring producer transaction timeout</title> - <programlisting><![CDATA[ -<transactionTimeout> - <openWarn>10000</openWarn> - <openClose>20000</openClose> - <idleWarn>5000</idleWarn> - <idleClose>15000</idleClose> -</transactionTimeout> - ]]></programlisting> - </example> + <title>Virtualhost configuration</title> + <para>The details how to configure Transaction Timeouts in Virtual Host configuration file + are provided in <xref linkend="Java-Broker-Virtual-Host-Transaction-Timeout-Configuring"/></para> </section> </section> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml index 21e1052183..03537115a4 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml @@ -25,53 +25,45 @@ <title>Access Control Lists</title> <para> In Qpid, Access Control Lists (ACLs) specify which actions can be performed by each authenticated user. - To enable, the <acl/> element is used within the <security/> element of the configuration XML. - In the Java Broker, the ACL may be imposed broker wide or applied to individual virtual - hosts. The <acl/> configuration references a text file containing the ACL rules. + To enable, an <emphasis>Access Control Provider</emphasis> needs to be configured on the <emphasis>Broker</emphasis> + level or/and ACL configuration should be provided on a <emphasis>Virtual Host</emphasis> level. + The first imposes the ACL broker wide, and the second is applied to individual virtual hosts. + The <emphasis>Access Control Provider</emphasis> of type "AclFile" uses local file to specify the ACL rules. By convention, this file should have a .acl extension. </para> + <para> + A Group Provider can be configured with ACL to define the user groups which can be used in ACL + to determine the ACL rules applicable to the entire group. The configuration details for the Group Providers are described in + <xref linkend="Java-Broker-Security-Group-Providers"/>. On creation of ACL Provider with group rules, + the Group Provider should be added first. Otherwise, if the individual ACL rules are not defined for the logged principal + the following invocation of management operations could be denied due to absence of the required groups.</para> - <section role="h3" id="Java-Broker-Security-ACLs-EnablingACL"> - <title> - Enabling ACLs - </title> - - <para> - To apply an ACL broker-wide, add the following to the config.xml (assuming that <replaceable>conf</replaceable> has been set to a suitable - location such as ${QPID_HOME}/etc): - </para> - - <programlisting> - <broker> - ... - <security> - ... - <acl><replaceable>${conf}/broker.acl</replaceable></acl> - </security> - </broker> - </programlisting> - - <para> - </para> + <para>Only one <emphasis>Access Control Provider</emphasis> can be used by the Broker. + If several <emphasis>Access Control Providers</emphasis> are configured on Broker level + only one of them will be used (the latest one). <xref linkend="Java-Broker-Virtual-Hosts-Configuration-File-ACL"/> + shows how to configure ACL on <emphasis>Virtual Host</emphasis> using virtual host configuration xml. + If both Broker <emphasis>Access Control Provider</emphasis> and <emphasis>Virtual Host</emphasis> ACL are configured, + the <emphasis>Virtual Host</emphasis> ACL is used for authorization of operations on <emphasis>Virtual Host</emphasis> and + Virtual Host objects and Broker level ACL is used to authorization of operations on Broker and Broker children + (excluding Virtual Hosts having ACL configured). + </para> - <para> - To apply an ACL on a single virtualhost named <replaceable>test</replaceable>, add the following to the config.xml: - </para> + <para> + The ACL Providers can be configured using <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> + and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>. + </para> - <programlisting> - <virtualhost> - ... - <name>test</name> - <test> - ... - <security> - <acl><replaceable>${conf}/vhost_test.acl</replaceable></acl> - </security> - </test> - </virtualhost> - </programlisting> - </section> + <para>The following ACL Provider managing operations are available from Web Management Console: + <itemizedlist> + <listitem><para>A new ACL Provider can be added by clicking onto "Add Access Control Provider" on the Broker tab.</para></listitem> + <listitem><para>An ACL Provider details can be viewed on the Access Control Provider tab. + The tab is shown after clicking onto ACL Provider name in the Broker object tree or after clicking + onto ACL Provider row in ACL Providers grid on the Broker tab.</para></listitem> + <listitem><para>An existing ACL Provider can be deleted by clicking onto buttons "Delete Access Control Provider" + on the Broker tab or Access Control Provider tab.</para></listitem> + </itemizedlist> + </para> <section role="h3" id="Java-Broker-Security-ACLs-WriteACL"> <title> @@ -209,6 +201,10 @@ <entry> <command>UPDATE</command> </entry> <entry> <para> Applied when an object is updated </para> </entry> </row> + <row> + <entry> <command>CONFIGURE</command> </entry> + <entry> <para> Applied when an object is configured via REST management interfaces(Java Broker only).</para> </entry> + </row> </tbody> </tgroup> </table> @@ -250,7 +246,7 @@ </row> <row> <entry> <command>BROKER</command> </entry> - <entry> <para>The broker (not currently used in Java Broker)</para> </entry> + <entry> <para>The broker</para> </entry> </row> </tbody> </tgroup> @@ -532,5 +528,51 @@ ACL DENY-LOG messaging-users ACCESS VIRTUALHOST \ ACL DENY-LOG all all </programlisting> </section> + <section role="h4" id="Java-Broker-Security-ACLs-WorkedExample5"> + <title> + Worked example 5 - REST management ACL example + </title> + <para> + This example illustrates how to set up an ACL that restricts usage of REST management interfaces. + </para> + <programlisting> +# allow to the users from webadmins group to change broker model +# this rule allows adding/removing/editing of Broker level objects: +# Broker, Virtual Host, Group Provider, Authentication Provider, Port, Access Control Provider etc +ACL ALLOW-LOG webadmins CONFIGURE BROKER + +# allow to the users from webadmins group to perform +# create/update/delete on Virtual Host children +ACL ALLOW-LOG webadmins CREATE QUEUE +ACL ALLOW-LOG webadmins UPDATE QUEUE +ACL ALLOW-LOG webadmins DELETE QUEUE +ACL ALLOW-LOG webadmins PURGE QUEUE +ACL ALLOW-LOG webadmins CREATE EXCHANGE +ACL ALLOW-LOG webadmins DELETE EXCHANGE +ACL ALLOW-LOG webadmins BIND EXCHANGE +ACL ALLOW-LOG webadmins UNBIND EXCHANGE + +# allow to the users from webadmins group to create/update/delete groups on Group Providers +ACL ALLOW-LOG webadmins CREATE GROUP +ACL ALLOW-LOG webadmins DELETE GROUP +ACL ALLOW-LOG webadmins UPDATE GROUP + +# allow to the users from webadmins group to create/update/delete users for Authentication Providers +ACL ALLOW-LOG webadmins CREATE USER +ACL ALLOW-LOG webadmins DELETE USER +ACL ALLOW-LOG webadmins UPDATE USER + +# allow to the users from webadmins group to move, copy and delete messagaes +# using REST management interfaces +ACL ALLOW-LOG webadmins UPDATE METHOD + +# at the moment only the following UPDATE METHOD rules are supported by web management console +#ACL ALLOW-LOG webadmins UPDATE METHOD component="VirtualHost.Queue" name="moveMessages" +#ACL ALLOW-LOG webadmins UPDATE METHOD component="VirtualHost.Queue" name="copyMessages" +#ACL ALLOW-LOG webadmins UPDATE METHOD component="VirtualHost.Queue" name="deleteMessages" + +ACL DENY-LOG all all + </programlisting> + </section> </section> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml index 0974441ae5..8b91a6f33d 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml @@ -26,135 +26,102 @@ <para> In order to successfully establish a connection to the Java Broker, the connection must be authenticated. The Java Broker supports a number of different authentication schemes, each - with its own "authentication manager". Each of these are outlined below, along with details - of <link linkend="MultipleAuthProviders"> using more than one at a time</link>. + with its own "authentication provider". Any number of Authentication Providers can be configured + on the Broker at the same time. </para> - <section> - <title>Password File</title> - <para> - TODO - </para> + <para> + The Authentication Providers can be configured using <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> + and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>. + </para> - </section> + <para>The following Authentication Provider managing operations are available from Web Management Console: + <itemizedlist> + <listitem><para>A new Authentication Provider can be added by clicking onto "Add Provider" on the Broker tab.</para></listitem> + <listitem><para>An Authentication Provider details can be viewed on the Authentication Provider tab. + The tab is displayed after clicking onto Authentication Provider name in the Broker object tree or after clicking + onto Authentication Provider row in Authentication Providers grid on the Broker tab.</para></listitem> + <listitem><para>Editing of Authentication Provider can be performed by clicking on "Edit" button + on Authentication Provider tab.</para></listitem> + <listitem><para>An existing Authentication Provider can be deleted by clicking on "Delete Provider" button + on Broker tab or "Delete" button on the Authentication Provider tab.</para></listitem> + </itemizedlist> + The Authentication Provider type and name cannot be changed for existing providers as editing of name and type + is unsupported at the moment. Only provider specific attributes can be modified in the editing dialog + and stored in the broker configuration store. + </para> - <section id="LDAPAuthManager"> - <title>LDAP</title> + <important> + Only unused Authentication Provider can be deleted. For delete requests attempting to delete Authentication Provider + associated with the Ports, the errors will be returned and delete operations will be aborted. It is possible to change + the Authentication Provider on Port at runtime. However, the Broker restart is required for changes on Port to take effect. + </important> + + <section id="Java-Broker-Security-LDAP-Provider"> + <title>Simple LDAP Authentication Provider</title> <para> - LDAP authentication can be configured using the <simple-ldap-auth-manager> element - within the <security> section. An example of how to configure this is shown below. - Please note this example also configures an unused <pd-auth-manager> to use an empty - password file, this is a workaround for an issue relating to registration of security providers. + SimpleLDAPAuthenticationProvider authenticate the connections by searching for a user unique distinguished name + in the pre-configured LDAP search directory and performing LDAP bind using the found DN and password after that. + On creation of SimpleLDAPAuthenticationProvider the following mandatory fields are required to specify: + <itemizedlist> + <listitem><para><emphasis>LDAP server URL</emphasis> is an URL of LDAP server, for example, ldaps://example.com:636</para></listitem> + <listitem><para><emphasis>Search context</emphasis> is a LDAP directory name to search for users entries, for example, "dc=users,dc=example,dc=com"</para></listitem> + <listitem><para><emphasis>Search filter</emphasis> is a DN template to find an LDAP user entry by provided user name, for example, (uid={0})</para></listitem> + </itemizedlist> + Additionally, the following optional fields can be specified: + <itemizedlist> + <listitem><para><emphasis>LDAP context factory</emphasis> is fully qualified class name for the JNDI LDAP context factory.</para></listitem> + <listitem><para><emphasis>LDAP authentication URL</emphasis>is an URL of LDAP server for performing "ldap bind" + if a different LDAP URL is required for performing an authentication.</para></listitem> + </itemizedlist> </para> <para> <emphasis>NOTE: When using LDAP authentication, you must also use SSL on the brokers AMQP messaging and JMX/HTTP management ports in order to protect passwords during transmission to the broker.</emphasis> </para> - <example> - <title>Configuring LDAP authentication</title> - <programlisting><![CDATA[ -<security> - <default-auth-manager>SimpleLDAPAuthenticationManager</default-auth-manager> - <simple-ldap-auth-manager> - <provider-url>ldaps://example.com:636/</provider-url> - <search-context>dc=example\,dc=com</search-context> - <search-filter>(uid={0})</search-filter> - </simple-ldap-auth-manager> - - <!-- Unused pd-auth-manager, a workaround to register the necessary security providers --> - <pd-auth-manager> - <principal-database> - <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class> - <attributes> - <attribute> - <name>passwordFile</name> - <value>${conf}/emptyPasswdFile</value> - </attribute> - </attributes> - </principal-database> - <pd-auth-manager> - ... -</security>]]></programlisting> - </example> <para> - The authentication manager first connects to the ldap server anonymously and searches for the + The Authentication Provider first connects to the ldap server anonymously and searches for the ldap entity which is identified by the username provided over SASL. Essentially the - authentication manager calls - DirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) - with the values of search-context and search-filter as the first two arguments, and the username - as the only element in the array which is the third argument. + authentication manager calls DirContext.search(Name name, String filterExpr, Object[] filterArgs, SearchControls cons) + with the values of <emphasis>Search context</emphasis> and <emphasis>Search filter</emphasis> as the first two arguments, + and the username as the only element in the array which is the third argument. </para> <para> - If the search returns a name from the LDAP server, the AuthenticationManager then attempts to - login to the ldap server with the given name and the password. + If the search returns a name from the LDAP server, the Authentication Provider then attempts to + login to the LDAP server with the given name and the password. </para> <para> If the URL to open for authentication is different to that for the search, then the - authentication url can be overridden using <provider-auth-url> in addition to providing a - <provider-url>. Note that the URL used for authentication should use ldaps:// since + authentication url can be overridden using <LDAP authentication URL> in addition to providing a + <LDAP server URL>. Note that the URL used for authentication should use ldaps:// since passwords will be being sent over it. </para> <para> By default com.sun.jndi.ldap.LdapCtxFactory is used to create the context, however this can be - overridden by specifying <ldap-context-factory> in the configuration. + overridden by specifying <LDAP context factory> in the configuration. </para> </section> - <section> + <section id="Java-Broker-Security-Kerberos-Provider"> <title>Kerberos</title> <para> - Kereberos Authentication is configured using the <kerberos-auth-manager> element within - the <security> section. When referencing from the default-auth-manager or port-mapping - sections, its name is KerberosAuthenticationManager. + Kereberos Authentication Provider uses java GSS-API SASL mechanism to authenticate the connections. </para> <para> - Since Kerberos support only works where SASL authentication is available (e.g. not for JMX - authentication) you may wish to also include an alternative Authentication Manager - configuration, and use this for other ports: - </para> - - <example> - <title>Configuring Kerberos authentication</title> - <programlisting><![CDATA[ -<security> - <pd-auth-manager> - <principal-database> - <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class> - <attributes> - <attribute> - <name>passwordFile</name> - <value>${conf}/passwd</value> - </attribute> - </attributes> - </principal-database> - </pd-auth-manager> - <kerberos-auth-manager/> - <default-auth-manager>PrincipalDatabaseAuthenticationManager</default-auth-manager> - <port-mappings> - <port-mapping> - <port>5672</port> - <auth-manager>KerberosAuthenticationManager</auth-manager> - </port-mapping> - </port-mappings> - ... -</security>]]></programlisting> - </example> - - <para> Configuration of kerberos is done through system properties (there doesn't seem to be a way around this unfortunately). </para> <programlisting> - export QPID_OPTS=-Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf + export JAVA_OPTS=-Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf ${QPID_HOME}/bin/qpid-server </programlisting> @@ -183,138 +150,99 @@ com.sun.security.jgss.accept { Note: You may need to install the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" appropriate for your JDK in order to get Kerberos support working. </para> + + <para> + Since Kerberos support only works where SASL authentication is available (e.g. not for JMX + authentication) you may wish to also include an alternative Authentication Provider + configuration, and use this for JMX and HTTP ports. + </para> + </section> - <section id="ExternalAuthManager"> + <section id="Java-Broker-Security-External-Provider"> <title>External (SSL Client Certificates)</title> <para> When <link linkend="SSL-Truststore-ClientCertificate"> requiring SSL Client Certificates</link> be - presented the ExternalAuthenticationManager can be used, such that the user is authenticated based on + presented the External Authentication Provider can be used, such that the user is authenticated based on trust of their certificate alone, and the X500Principal from the SSL session is then used as the username for the connection, instead of also requiring the user to present a valid username and password. </para> <para> - The ExternalAuthenticationManager may be enabled by adding an empty <external-auth-manager> element to - the <security> section, as shown below. When referencing it from the default-auth-manager or port-mapping - sections, its name is ExternalAuthenticationManager. - </para> - - <para> - <emphasis role="bold">Note:</emphasis> The ExternalAuthenticationManager should typically only be used on the + <emphasis role="bold">Note:</emphasis> The External Authentication Provider should typically only be used on the AMQP ports, in conjunction with <link linkend="SSL-Truststore-ClientCertificate">SSL client certificate authentication</link>. It is not intended for other uses such as the JMX management port and will treat any - non-sasl authentication processes on these ports as successfull with the given username. As such you should - <link linkend="MultipleAuthProviders">include another Authentication Manager for use on non-AMQP ports</link>, - as is done in the example below. Perhaps the only exception to this would be where the broker is embedded in a - container that is itself externally protecting the HTTP interface and then providing the remote users name. + non-sasl authentication processes on these ports as successful with the given username. As such you should + configure another Authentication Provider for use on non-AMQP ports. Perhaps the only exception to this + would be where the broker is embedded in a container that is itself externally protecting the HTTP interface + and then providing the remote users name. </para> - <example> - <title>Configuring external authentication (SSL client auth)</title> - <programlisting><![CDATA[ -<security> - <pd-auth-manager> - <principal-database> - <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class> - <attributes> - <attribute> - <name>passwordFile</name> - <value>${conf}/passwd</value> - </attribute> - </attributes> - </principal-database> - </pd-auth-manager> - <external-auth-manager/> - <default-auth-manager>PrincipalDatabaseAuthenticationManager</default-auth-manager> - <port-mappings> - <port-mapping> - <port>5672</port> - <auth-manager>ExternalAuthenticationManager</auth-manager> - </port-mapping> - </port-mappings> - ... -</security>]]></programlisting> - </example> - + <para>On creation of External Provider the use of full DN or username CN as a principal name can be configured. + If field "Use the full DN as the Username" is set to "true" the full DN is used as an authenticated principal name. + If field "Use the full DN as the Username" is set to "false" the user name CN part is used as the authenticated principal name. + Setting the field to "false" is particular useful when <link linkend="Java-Broker-Security-ACLs">ACL</link> is required, + as at the moment, ACL does not support commas in the user name. + </para> </section> - <section id="AnonymousAuthManager"> + <section id="Java-Broker-Security-Anonymous-Provider"> <title>Anonymous</title> <para> - The AnonymousAuthenticationManager will allow users to connect with or without credentials and result - in their identification on the broker as the user ANONYMOUS. It may be enabled by adding an empty - anonymous-auth-manager element to the security configuration section, as shown below. + The Anonymous Authentication Provider will allow users to connect with or without credentials and result + in their identification on the broker as the user ANONYMOUS. This Provider does not require specification + of any additional fields on creation. </para> - <example> - <title>Configuring anonymous authentication</title> - - <programlisting><![CDATA[ -<security> - <anonymous-auth-manager/> - ... -</security>]]></programlisting> - </example> + </section> + <section id="Java-Broker-Security-PlainPasswordFile-Provider"> + <title>Plain Password File</title> + <para> + The PlainPasswordFile Provider uses local file to store and manage user credentials. + When creating an authentication provider the path to the file needs to be specified. + If specified file does not exist an empty file is created automatically on Authentication Provider creation. + On Provider deletion the password file is deleted as well. For this Provider + user credentials can be added, removed or changed using REST management interfaces and web management console. + </para> <para> - When referencing it from the default-auth-manager or port-mapping sections, its name is - AnonymousAuthenticationManager. + On navigating to the Plain Password File Provider tab (by clicking onto provider name from Broker tree or provider + row in providers grid on Broker tab) the list of existing credentials is displayed on the tab with the buttons "Add User" + and "Delete Users" to add new user credentials and delete the existing user credentials respectively. + On clicking into user name on Users grid the pop-up dialog to change the password is displayed. </para> + + <section> + <title>Plain Password File Format</title> + <para> + The user credentials are stored on the single file line as user name and user password pairs separated by colon character. + </para> + <programlisting> +# password file format +# <user name>: <user password> +guest:guest + </programlisting> + </section> </section> - <section id="MultipleAuthProviders"> - <title>Configuring multiple Authentication Providers</title> + <section id="Java-Broker-Security-Base64MD5PasswordFile-Provider"> + <title>Base64MD5 Password File</title> <para> - Different managers may be used on different ports. Each manager has its own configuration element, - the presence of which within the <security> section denotes the use of that authentication - provider. Where only one such manager is configured, it will be used on all ports (including JMX - and HTTP). Where more than one authentication manager is configured the configuration must define - which is the "default", and (if required) the mapping of non-default authentication managers to - other ports. + Base64MD5PasswordFile Provider uses local file to store and manage user credentials similar to Similar to PlainPasswordFile + but instead of storing a password the MD5 password digest encoded with Base64 encoding is stored in the file. + When creating an authentication provider the path to the file needs to be specified. + If specified file does not exist an empty file is created automatically on Authentication Provider creation. + On Base64MD5PasswordFile Provider deletion the password file is deleted as well. For this Provider + user credentials can be added, removed or changed using REST management interfaces and web management console. </para> <para> - The following configuration sets up three authentication managers, using a password file as the - default (e.g. for the JMX and HTTP ports), Kerberos on port 5672 (the regular AMQP port) and Anonymous - on port 5673 (e.g a second AMQP port the broker could have been configured with). + On navigating to the Base64MD5PasswordFile Provider tab (by clicking onto provider name from Broker tree or provider + row in providers grid on Broker tab) the list of existing credentials is displayed on the tab with the buttons "Add User" + and "Delete Users" to add new user credentials and delete the existing user credentials respectively. + On clicking into user name on Users grid the pop-up dialog to change the password is displayed. </para> - - <example> - <title>Configuring multiple (per-port) authentication schemes</title> - <programlisting><![CDATA[ -<security> - <pd-auth-manager> - <principal-database> - <class>org.apache.qpid.server.security.auth.database.PlainPasswordFilePrincipalDatabase</class> - <attributes> - <attribute> - <name>passwordFile</name> - <value>${conf}/passwd</value> - </attribute> - </attributes> - </principal-database> - </pd-auth-manager> - <kerberos-auth-manager> - <auth-name>sib</auth-name> - </kerberos-auth-manager> - <anonymous-auth-manager/> - <default-auth-manager>PrincipalDatabaseAuthenticationManager</default-auth-manager> - <port-mappings> - <port-mapping> - <port>5672</port> - <auth-manager>KerberosAuthenticationManager</auth-manager> - </port-mapping> - <port-mapping> - <port>5673</port> - <auth-manager>AnonymousAuthenticationManager</auth-manager> - </port-mapping> - </port-mappings> - ... -</security>]]></programlisting> - </example> </section> - </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml index eaecd85770..34ea443ef7 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml @@ -22,39 +22,45 @@ --> <section id="Java-Broker-Security-Group-Providers"> - <title>Configuring Group Providers</title> + <title>Group Providers</title> <para> - The Java broker utilises GroupProviders to allow assigning users to groups for use in <link linkend="Java-Broker-Security-ACLs">ACLs</link>. Following authentication by a given <link linkend="Java-Broker-Security-Authentication-Providers">Authentication Provider</link>, the configured Group Providers are consulted to allowing assignment of GroupPrincipals for a given authenticated user. + The Java broker utilises GroupProviders to allow assigning users to groups for use in <link linkend="Java-Broker-Security-ACLs">ACLs</link>. + Following authentication by a given <link linkend="Java-Broker-Security-Authentication-Providers">Authentication Provider</link>, + the configured Group Providers are consulted allowing the assignment of GroupPrincipals for a given authenticated user. Any number of + Group Providers can be added into the Broker. All of them will be checked for the presence of the groups for a given authenticated user. </para> - + <para>The <emphasis>Group Provider</emphasis> can be configured using <link linkend="Java-Broker-Configuring-And-Managing-REST-API"> + REST Management interfaces</link> and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>.</para> + <para>The following <emphasis>Group Provider</emphasis> managing operations are available from Web Management Console: + <itemizedlist> + <listitem><para>A new Group Provider can be added by clicking onto "Add Group Provider" button on a Broker tab.</para></listitem> + <listitem><para>An existing providers can be removed by pressing "Delete Group Provider" button + on Broker tab or Group Provider tab.</para></listitem> + <listitem><para>On clicking onto provider name in the Group Providers grid or Broker object tree, + the tab for the Group Provider is displayed.</para></listitem> + <listitem><para>A new group can be added into the Group Provider by clicking onto "Add Group" button on provider tab.</para></listitem> + <listitem><para>An existing group can be deleted from the Group Provider by clicking onto "Delete Group" button on provider tab.</para></listitem> + <listitem><para>On clicking onto group name in the groups grid, the tab with the list of existing + group members is displayed for the Group.</para></listitem> + <listitem><para>From the Group tab a new member can be added into a group or existing members can be deleted + from a group by clicking on "Add Group Member" or "Remove Group Members" accordingly.</para></listitem> + </itemizedlist> + </para> <section role="h3" id="File-Group-Manager"> - <title>FileGroupManager</title> - <para> - The FileGroupManager allows specifying group membership in a flat file on disk, and is also exposed for inspection and update through the brokers HTTP management interface. - </para> + <title>GroupFile Provider</title> <para> - To enable the FileGroupManager, add the following configuration to the config.xml, adjusting the groupFile attribute value to match your desired groups file location. + The <emphasis>GroupFile</emphasis> Provider allows specifying group membership in a flat file on disk. + On adding a new GroupFile Provider the path to the groups file is required to be specified. + If file does not exist an empty file is created automatically. On deletion of GroupFile Provider + the groups file is deleted as well. Only one instance of "GroupFile" Provider per groups file location can be created. + On attempt to create another GroupFile Provider pointing to the same location the error will be displayed and + the creation will be aborted. </para> - <programlisting><![CDATA[ - ... - <security> - <file-group-manager> - <attributes> - <attribute> - <name>groupFile</name> - <value>${conf}/groups</value> - </attribute> - </attributes> - </file-group-manager> - </security>]]> - ... -</programlisting> - - <section role="h4" id="File-Group-Manager-FileFormat"> + <section role="h4" id="File-Group-Manager-FileFormat"> <title>File Format</title> - <para> + <para> The groups file has the following format: </para> <programlisting> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml index e415065a84..0a5ec0ec97 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml @@ -25,45 +25,42 @@ --> <section id="Java-Broker-Security-SSL"> - <title>SSL</title> +<title>SSL</title> <para> - This section will show how to use SSL to enable secure - connections between an AMQP message client and the broker. + This section guides through the details of configuration of Keystores and Trsustores + required for enabling of SSL transport and Client Certificate Authentication on Broker ports. + The details how to configure SSL on Broker ports are provided in <xref linkend="Java-Broker-Ports"/>. </para> - <section role="h2" id="SSL-Keystore"> + + <section role="h2" id="Java-Broker-SSL-Keystore"> <title>Keystore Configuration</title> <para> - The broker configuration file (config.xml) needs to be updated to include the required SSL keystore - configuration, an example of which can be found below. + A Keystore can be added/deleted/edited using <link linkend="Java-Broker-Configuring-And-Managing-REST-API"> + REST Management interfaces</link> and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console"> + Web Management Console</link>. Any number of Keystores can be configured on the Broker. + SSL ports can be configured with different Keystores. </para> - <example> - <title>Configuring an SSL Keystore</title> - <programlisting><![CDATA[ -<connector> - ... - <ssl> - <enabled>true</enabled> - <port>5671</port> - <sslOnly>false</sslOnly> - <keyStorePath>/path/to/keystore.ks</keyStorePath> - <keyStorePassword>keystorepass</keyStorePassword> - <certAlias>alias<certAlias> - </ssl> - ... -<connector>]]></programlisting> - </example> - - <para> - The certAlias element is an optional way of specifying which certificate the broker should use - if the keystore contains multiple entries. + <para>The following Keystore managing operations are available from + <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>: + <itemizedlist> + <listitem><para>A new Keystore can be added by clicking on "Add Key Store" button on the Broker tab.</para></listitem> + <listitem><para>Keystore details can be viewed on the Keystore tab which is displayed after clicking + on Keystore name in the Broker object tree or after clicking on Keystore row in Keystores grid on the Broker tab.</para></listitem> + <listitem><para>Editing of Keystore can be performed by clicking on "Edit" button on the Keystore tab. + Changing of Keystore name is unsupported at the moment. If changed Keystore is used by the Port + the changes on Port object will take effect after Broker restart.</para></listitem> + <listitem><para>An existing Keystore can be deleted by clicking on "Delete Key Store" button on Broker tab + or hitting "Delete" button on the Keystore tab. Only unused Keystores can be deleted. + The deletion of the Keystore configured on any Broker Port is not allowed.</para></listitem> + </itemizedlist> </para> <para> - The sslOnly element controls whether the broker will <emphasis role="bold">only</emphasis> bind - the configured SSL port(s) or will also bind the non-SSL port(s). Setting sslOnly to true will - disable the non-SSL ports. + The "Keystore certificate alias" field is an optional way of specifying which certificate the broker should use + if the keystore contains multiple entries. Optionally "Key manager factory algorithm" and "Key store type" can + be specified on Keystore creation. </para> <important> @@ -80,39 +77,35 @@ <section role="h2" id="SSL-Truststore-ClientCertificate"> <title>Truststore / Client Certificate Authentication</title> <para> - The SSL trustore and related Client Certificate Authentication behaviour can be configured with - additional configuration as shown in the example below, in which the broker requires client - certificate authentication. + The SSL trustore and related Client Certificate Authentication behaviour can be configured + by adding a Trustore configured object and associating it with the SSL port. + A Truststore can be added/deleted/edited using <link linkend="Java-Broker-Configuring-And-Managing-REST-API"> + REST Management interfaces</link> and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console"> + Web Management Console</link>. Any number of Trustores can be configured on the Broker. + Multiple Trustores can be configured on Broker SSL Ports. </para> - <example> - <title>Configuring an SSL Truststore and client auth</title> - <programlisting><![CDATA[ -<connector> - ... - <ssl> - ... - <trustStorePath>/path/to/truststore.ks</trustStorePath> - <trustStorePassword>truststorepass</trustStorePassword> - <needClientAuth>true</needClientAuth> - <wantClientAuth>false</wantClientAuth> - ... - </ssl> - ... -<connector>]]></programlisting> - </example> + <para>The following Truststore managing operations are available from + <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>: + <itemizedlist> + <listitem><para>A new Truststore can be added by clicking on "Add Trust Store" button on the Broker tab.</para></listitem> + <listitem><para>Truststore details can be viewed on the Truststore tab which is displayed after clicking + onto Truststore name in the Broker object tree or after clicking onto Truststore row in Truststores grid on the Broker tab.</para></listitem> + <listitem><para>Trustore can be edited by clicking onto "Edit" button on the Trustore tab. + Changing of Trustore name is unsupported at the moment.</para></listitem> + <listitem><para>An existing Trustore can be deleted by clicking onto "Delete Trust Store" button + on Broker tab or "Delete" button on the Truststore tab. Only unused Truststores can be deleted. + The deletion of the Truststore configured on any Broker Port is not allowed.</para></listitem> + </itemizedlist> + </para> - <para> - The needClientAuth and wantClientAuth elements allow control of whether the client must present an - SSL certificate. Only one of these elements is needed but both may be used at the same time. - A socket's client authentication setting is one of three states: required (needClientAuth = true), - requested (wantClientAuth = true), or none desired (both false, the default). If both elements are - set to true, needClientAuth takes precedence. + <para>When "Peers Only" option is selected for the Truststore it will allow logging in for the clients + with the certificate exactly matching the certificate loaded in the Truststore database, + thus, authenticating the connections with self signed certificates not nessesary signed by CA. </para> - <para> - When using Client Certificate Authentication it may be desirable to use the External Authentication - Manager, for details see <xref linkend="ExternalAuthManager"></xref> + <para>"Trust manager factory algorithm" and "Trust store type" can + be optionally specified for the Trustore. </para> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-Users-And-Groups.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-Users-And-Groups.xml deleted file mode 100644 index 2125f3a3df..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Security-Users-And-Groups.xml +++ /dev/null @@ -1,26 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!-- - - 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. - ---> - -<section id="Java-Broker-Security-Users-And-Groups"> -<title>Users And Groups</title> - -</section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security.xml index 3db672100e..858a27abb0 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Security.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Security.xml @@ -22,9 +22,8 @@ <chapter id="Java-Broker-Security"> <title>Security</title> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-Users-And-Groups.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-Group-Providers.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-Authentication-Providers.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-Group-Providers.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-ACLs.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security-SSL.xml"/> </chapter> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml index c16d9aa227..d6c779f2f3 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml @@ -25,13 +25,25 @@ --> <section id="Java-Broker-Stores-BDB-Store"> - <title>BDB Store</title> + <title>BDB Message Store</title> <para> The Java broker has an <emphasis>optional</emphasis> message store implementation backed by Oracle BDB JE. This section will detail where to download the optional dependency from, how to add it to the broker installation, and provide an example configuration for using the BDBMessageStore. </para> + <para> + The BDBMessageStore can be selected on Virtual Host creation + via <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> + and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>. + For details, see <xref linkend="Java-Broker-Virtual-Hosts"/>. + </para> + + <para> + Alternatively, the BDBMessageStore can configured in Virtual Host configuration xml. + For details, see <xref linkend="Java-Broker-Stores-BDB-Store-Configuration"/>. + </para> + <section role="h3" id="Java-Broker-Stores-BDB-Store-BDBJE-Download"> <title>Oracle BDB JE download</title> <para> @@ -63,32 +75,4 @@ cp je-&oracleBdbProductVersion;.jar qpid-broker-&qpidCurrentRelease;/lib/opt</pr copy je-&oracleBdbProductVersion;.jar qpid-broker-&qpidCurrentRelease;\lib\opt</programlisting> </section> - - - <section role="h3" id="Java-Broker-Stores-BDB-Store-Configuration"> - <title>Configuration</title> - <para> - In order to use the BDBMessageStore, you must configure it for each VirtualHost desired by updating the store element - to specify the associated store class and provide a directory location for the data to be written, as shown below. - </para> - - <example> - <title>Configuring a VirtualHost to use the BDBMessageStore</title> - <programlisting><![CDATA[ -<virtualhosts> - <virtualhost> - <name>vhostname</name> - <vhostname> - <store> - <class>org.apache.qpid.server.store.berkeleydb.BDBMessageStore</class> - <environment-path>${QPID_WORK}/bdbstore/vhostname</environment-path> - </store> - ... - </vhostname> - </virtualhost> -</virtualhosts> -]]></programlisting> - </example> - </section> - </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml index 042b2324de..b8cd7a17d5 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml @@ -21,36 +21,22 @@ --> <section id="Java-Broker-Stores-Derby-Store"> -<title>Derby Store</title> +<title>Derby Message Store</title> <para> The Java broker has a message store implementation backed by Apache Derby. This section will detail configuration for using the DerbyMessageStore. </para> - <section role="h3" id="Java-Broker-Stores-Derby-Store-Configuration"> - <title>Configuration</title> - <para> - In order to use the DerbyMessageStore, you must configure it for each VirtualHost desired by updating the store element - to specify the associated store class and provide a directory location for the data to be written, as shown below. - </para> - - <example> - <title>Configuring a VirtualHost to use the DerbyMessageStore</title> - <programlisting><![CDATA[ -<virtualhosts> - <virtualhost> - <name>vhostname</name> - <vhostname> - <store> - <class>org.apache.qpid.server.store.DerbyMessageStore</class> - <environment-path>${QPID_WORK}/derbystore/vhostname</environment-path> - </store> - ... - </vhostname> - </virtualhost> -</virtualhosts> -]]></programlisting> - </example> - </section> + <para> + The DerbyMessageStore can be selected on Virtual Host creation + via <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> + and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>. + For details, see <xref linkend="Java-Broker-Virtual-Hosts"/>. + </para> + + <para> + Alternatively, the DerbyMessageStore can configured in Virtual Host configuration xml. + For details, see <xref linkend="Java-Broker-Stores-Derby-Store-Configuration"/>. + </para> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml index e8a13c52dc..880814a0be 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml @@ -21,7 +21,7 @@ --> <section id="Java-Broker-Stores-HA-BDB-Store"> - <title>High Availability BDB Store</title> + <title>High Availability BDB Message Store</title> <para> The Java broker has an <emphasis>optional</emphasis> High Availability message store implementation backed by Oracle BDB JE HA. This section references information on where to download the optional dependency from, how to add it to the broker diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml index b8694f3315..cb04929e0c 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml @@ -21,7 +21,7 @@ --> <section id="Java-Broker-Stores-Memory-Store"> - <title>Memory Store</title> + <title>Memory Message Store</title> <para> The Java broker has an in-memory message store implementation. This section will detail configuration for using the MemoryMessageStore. @@ -32,30 +32,16 @@ ability to store new messages will be entirely constrained by the JVM heap size. </para> - <section role="h3" id="Java-Broker-Stores-Memory-Store-Configuration"> - <title>Configuration</title> - <para> - In order to use the MemoryMessageStore, you must configure it for each VirtualHost desired by updating the store element - to specify the associated store class, as shown below. - </para> - - <example> - <title>Configuring a VirtualHost to use the MemoryMessageStore</title> - <programlisting><![CDATA[ -<virtualhosts> - <virtualhost> - <name>vhostname</name> - <vhostname> - <store> - <class>org.apache.qpid.server.store.MemoryMessageStore</class - </store> - ... - </vhostname> - </virtualhost> -</virtualhosts> -]]></programlisting> - </example> - </section> + <para> + The MemoryMessageStore can be selected on Virtual Host creation + via <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> + and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>. + For details, see <xref linkend="Java-Broker-Virtual-Hosts"/>. + </para> + <para> + Alternatively, the MemoryMessageStore can configured in Virtual Host configuration xml. + For details, see <xref linkend="Java-Broker-Stores-Memory-Store-Configuration"/>. + </para> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-SQL-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-SQL-Store.xml index b6776c81e6..f41b8af0e6 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-SQL-Store.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Stores-SQL-Store.xml @@ -21,6 +21,31 @@ --> <section id="Java-Broker-Stores-SQL-Store"> -<title>SQL Store</title> +<title>SQL Message Store</title> +<para> + The Java broker has a message store implementation backed by JDBC API. + This section will detail configuration for using the JDBCMessageStore. + </para> + + <para> + The JDBCMessageStore can be selected on Virtual Host creation + via <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> + and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>. + For details, see <xref linkend="Java-Broker-Virtual-Hosts"/>. + </para> + + <para> + Alternatively, the JDBCMessageStore can configured in Virtual Host configuration xml. + For details, see <xref linkend="Java-Broker-Stores-JDBC-Store-Configuration"/>. + </para> + + <section role="h3" id="Java-Broker-Stores-JDBC-Store-Driver"> + <title>JDBC driver</title> + <para> + Only JDBC 4.0 compatible drivers can be used with JDBCMessageStore as it does not register a driver class explicitly. + In order to use a JDBCMessageStore a driver library is required to be present in the Broker classpath. + For the standard Broker distribution a driver library can be put into ${QPID_HOME}/lib/opt folder. + </para> + </section> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores.xml index aee3cdebdb..2524c9855c 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Stores.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Stores.xml @@ -21,7 +21,7 @@ --> <chapter id="Java-Broker-Stores"> - <title>Stores</title> + <title>Virtual Host Message Stores</title> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Stores-Memory-Store.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Stores-Derby-Store.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Stores-SQL-Store.xml"/> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml b/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml new file mode 100644 index 0000000000..97a6558ba3 --- /dev/null +++ b/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml @@ -0,0 +1,643 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + 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. + +--> + + <section id="Java-Broker-Virtual-Hosts-Configuration-File"> + <title>Configuring Virtual Host using configuration file</title> + <para>This section describes how to configure Virtual Host using configuration XML.</para> + <para>Virtual Host configuration XML can hold configuration for a single Virtual Host or multiple Virtual Hosts. + When multiple Virtual Hosts are configured a section for the each virtual host needs to be added. It should contain a tag + having the same name as virtual host. + </para> +<programlisting> +<virtualhosts> + ... + <virtualhost> <co id="Java-Broker-Virtual-Hosts-Configuration-Multiple-1"/> + <name>test</name> + <test> + ... + </test> + </virtualhost> + + <virtualhost> <co id="Java-Broker-Virtual-Hosts-Configuration-Multiple-2"/> + <name>development</name> + <development> + ... + </development> + </virtualhost> + ... +</virtualhosts> + </programlisting> + <calloutlist> + <callout arearefs="Java-Broker-Virtual-Hosts-Configuration-Multiple-1"><para>A configuration section for a virtual host "test"</para></callout> + <callout arearefs="Java-Broker-Virtual-Hosts-Configuration-Multiple-2"><para>A configuration section for a virtual host "development"</para></callout> + </calloutlist> + + <section id="Java-Broker-Virtual-Hosts-Configuration-File-ACL"> + <title>Configuring ACL</title> + <para><xref linkend="Java-Broker-Security-ACLs"/> provides the details of ACL, rules, formats, etc.</para> + <para> + To apply an ACL on a single virtualhost named <replaceable>test</replaceable>, add the following to the config.xml: + </para> + + <programlisting> +<virtualhost> +... + <name>test</name> + <test> + ... + <security> <co id="Java-Broker-Virtual-Hosts-Configuration-Security-ACL-1"/> + ... + <acl><replaceable>${conf}/vhost_test.acl</replaceable></acl> <co id="Java-Broker-Virtual-Hosts-Configuration-Security-ACL-2"/> + ... + </security> + ... + </test> +</virtualhost> + </programlisting> + <calloutlist> + <callout arearefs="Java-Broker-Virtual-Hosts-Configuration-Security-ACL-1"><para>A security section of configuration is used to declare the ACL</para></callout> + <callout arearefs="Java-Broker-Virtual-Hosts-Configuration-Security-ACL-2"><para>A path to an ACL file is configured (assuming that <replaceable>conf</replaceable> has been set to a suitable + location such as ${QPID_HOME}/etc)</para></callout> + </calloutlist> + </section> + + <section role="h3" id="Java-Broker-Stores-Memory-Store-Configuration"> + <title>Configuring MemoryMessageStore</title> + <para> + An example of MemoryMessageStore configuration for a virtual host is shown below: + </para> + + <example> + <title>Configuring a VirtualHost to use the MemoryMessageStore</title> + <programlisting><![CDATA[ +<virtualhosts> + <virtualhost> + <name>vhostname</name> + <vhostname> + <store> + <class>org.apache.qpid.server.store.MemoryMessageStore</class + </store> + ... + </vhostname> + </virtualhost> +</virtualhosts> + ]]></programlisting> + </example> + </section> + + <section role="h3" id="Java-Broker-Stores-BDB-Store-Configuration"> + <title>Configuring BDBMessageStore</title> + <para> + In order to use the BDBMessageStore, you must configure it for each VirtualHost desired by updating the store element + to specify the associated store class and provide a directory location for the data to be written, as shown below. + </para> + + <example> + <title>Configuring a VirtualHost to use the BDBMessageStore</title> + <programlisting><![CDATA[ +<virtualhosts> + <virtualhost> + <name>vhostname</name> + <vhostname> + <store> + <class>org.apache.qpid.server.store.berkeleydb.BDBMessageStore</class> + <environment-path>${QPID_WORK}/bdbstore/vhostname</environment-path> + </store> + ... + </vhostname> + </virtualhost> +</virtualhosts> + ]]></programlisting> + </example> + </section> + + <section role="h3" id="Java-Broker-Stores-Derby-Store-Configuration"> + <title>Configuring DerbyMessageStore</title> + <para> + In order to use the DerbyMessageStore, you must configure it for each VirtualHost desired by updating the store element + to specify the associated store class and provide a directory location for the data to be written, as shown below. + </para> + + <example> + <title>Configuring a VirtualHost to use the DerbyMessageStore</title> + <programlisting><![CDATA[ +<virtualhosts> + <virtualhost> + <name>vhostname</name> + <vhostname> + <store> + <class>org.apache.qpid.server.store.DerbyMessageStore</class> + <environment-path>${QPID_WORK}/derbystore/vhostname</environment-path> + </store> + ... + </vhostname> + </virtualhost> +</virtualhosts> + ]]></programlisting> + </example> + </section> + + <section role="h3" id="Java-Broker-Stores-JDBC-Store-Configuration"> + <title>Configuring JDBCMessageStore</title> + <para> + JDBCMessageStore can be configured on VirtualHost as in example shown below: + </para> + + <example> + <title>Configuring a VirtualHost to use the JDBCMessageStore</title> + <programlisting><![CDATA[ +<virtualhosts> + <virtualhost> + <name>vhostname</name> + <vhostname> + <store> + <class>org.apache.qpid.server.store.jdbc.JDBCMessageStore</class> + <connectionUrl>jdbc:oracle:thin:guest@guest//localhost:1521/orcl</connectionUrl> + </store> + ... + </vhostname> + </virtualhost> +</virtualhosts> +]]></programlisting> + </example> + </section> + + + <section role="h3" id="Java-Broker-Virtual-Host-Configuration-Exchange"> + <title>Configuring Exchanges</title> + <para> + To declare Exchanges within Virtual Host configuration, add the appropriate xml + to the virtualhost.xml configuration file within the <varname>exchanges</varname> element. + An example of such declaration is shown below: + </para> + + <example> + <title>Configuring Exchanges on VirtualHost</title> + <programlisting><![CDATA[ +<virtualhosts> + <virtualhost> + <name>vhostname</name> + ... + <exchanges> + <exchange> + <type>direct</type> + <name>test.direct</name> + <durable>true</durable> + </exchange> + <exchange> + <type>topic</type> + <name>test.topic</name> + </exchange> + </exchanges> + ... + </vhostname> + </virtualhost> +</virtualhosts> +]]></programlisting> + </example> + </section> + + <section role="h2" id="Java-Broker-Virtual-Host-Declare-Queues"> + <title>Configuring Queues</title> + <para>To create a priority, sorted or LVQ queue within configuration, add the appropriate xml + to the virtualhost.xml configuration file within the <varname>queues</varname> + element.</para> + <section role="h3" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig-Simple"> + <title>Simple</title> + <para>For declaration of a simple queue define a queue entry in the virtual host configuration as in example below</para> + <example> + <title>Configuring a simple queue</title> + <programlisting><![CDATA[<queue> + <name>my-simple-queue</name> + <my-simple-queue> + <exchange>amq.direct</exchange> + <durable>true</durable> + </my-simple-queue> +</queue>]]></programlisting> + </example> + </section> + <section role="h3" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig-Priority"> + <title>Priority</title> + <para> To defining a priority queue, add a <priority>true</priority> element. By + default the queue will have 10 distinct priorities. </para> + <example> + <title>Configuring a priority queue</title> + <programlisting><![CDATA[<queue> + <name>myqueue</name> + <myqueue> + <exchange>amq.direct</exchange> + <priority>true</priority> + </myqueue> +</queue>]]></programlisting> + </example> + <para> If you require fewer priorities, it is possible to specify a + <varname>priorities</varname> element (whose value is a integer value between 2 and 10 + inclusive) which will give the queue that number of distinct priorities. When messages are + sent to that queue, their effective priority will be calculated by partitioning the + priority space. If the number of effective priorities is 2, then messages with priority + 0-4 are treated the same as "lower priority" and messages with priority 5-9 are treated + equivalently as "higher priority". </para> + <example> + <title>Configuring a priority queue with fewer priorities</title> + <programlisting><![CDATA[<queue> + <name>myqueue</name> + <myqueue> + <exchange>amq.direct</exchange> + <priority>true</priority> + <priorities>4</priorities> + </myqueue> +</queue>]]></programlisting> + </example> + </section> + <section role="h3" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig-Sorted"> + <title>Sorted</title> + <para> To define a sorted queue, add a <varname>sortKey</varname> element. The value of the + <varname>sortKey</varname> element defines the message property to use the value of when + sorting the messages put onto the queue. </para> + <example> + <title>Configuring a sorted queue</title> + <programlisting><![CDATA[<queue> + <name>myqueue</name> + <myqueue> + <exchange>amq.direct</exchange> + <sortKey>message-property-to-sort-by</sortKey> + </myqueue> +</queue>]]></programlisting> + </example> + </section> + <section role="h3" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig-LVQ"> + <title>LVQ</title> + <para> To define a LVQ, add a <varname>lvq</varname> element with the value + <constant>true</constant>. Without any further configuration this will define an LVQ + which uses the JMS message property <constant>qpid.LVQ_key</constant> as the key for + replacement. </para> + <example> + <title>Configuring a LVQ queue</title> + <programlisting><![CDATA[<queue> + <name>myqueue</name> + <myqueue> + <exchange>amq.direct</exchange> + <lvq>true</lvq> + </myqueue> +</queue>]]></programlisting> + </example> + <para> If you wish to define your own property then you can do so using the + <varname>lvqKey</varname> element.</para> + <example> + <title>Configuring a LVQ queue with custom message property name</title> + <programlisting><![CDATA[<queue> + <name>myqueue</name> + <myqueue> + <exchange>amq.direct</exchange> + <lvq>true</lvq> + <lvqKey>ISIN</lvqKey> + </myqueue> +</queue>]]></programlisting> + </example> + </section> + </section> + + <section role="h2" id="Java-Broker-Virtual-Host-Configure-Flow-Control"> + <title>Configuring of Producer Flow Control</title> + <para>Flow control capacity and flow resume capacity are required to set on a queue or virtual host to enable Producer flow control.</para> + + <example> + <title>Configuring a queue depth limit</title> + <programlisting> + <![CDATA[ +<queue> + <name>test</name> + <test> + <exchange>amq.direct</exchange> + + <!-- set the queue capacity to 10Mb --> + <capacity>10485760</capacity> + + <!-- set the resume capacity to 8Mb --> + <flowResumeCapacity>8388608</flowResumeCapacity> + </test> +</queue> + ]]> + </programlisting> + </example> + + The default for all queues on a virtual host can also be set + + <example> + <title>Configuring of default queue depth limit on virtualhost</title> + <programlisting> + <![CDATA[ +<virtualhosts> + <virtualhost> + <name>localhost</name> + <localhost> + + <!-- set the queue capacity to 10Mb --> + <capacity>10485760</capacity> + + <!-- set the resume capacity to 8Mb --> + <flowResumeCapacity>8388608</flowResumeCapacity> + </localhost> + </virtualhost> +</virtualhosts> + ]]> + </programlisting> + </example> + </section> + + <section role="h2" id="Java-Broker-Virtual-Host-Configure-Disk-Quotas"> + <title>Configuring of Disk Quota-based Flow Control</title> + <para> + An example of quota configuration for the BDB message store is provided below. + </para> + + <example> + <title>Configuring a limit on a store</title> + <programlisting> + <![CDATA[ +<store> + <class>org.apache.qpid.server.store.berkeleydb.BDBMessageStore</class> + <environment-path>${work}/bdbstore/test</environment-path> + <overfull-size>50000000</overfull-size> + <underfull-size>45000000</underfull-size> +</store> + ]]> + </programlisting> + </example> + </section> + + +<section role="h3" + id="Java-Broker-Virtual-Host-Transaction-Timeout-Configuring"> + <title>Configuring Transaction Timeouts</title> + <para> The JMS transaction timeouts are configured on each virtual host defined in the XML + configuration files.</para> + <para> The default values for each of the parameters is 0, indicating that the particular check + is disabled.</para> + <para> Any or all of the parameters can be set, using the desired value in milliseconds, and will + be checked each time the housekeeping process runs, usually set to run every 30 seconds in + standard configuration. The meaning of each property is as follows:</para> + <para> + <itemizedlist> + <listitem> + <para>openWarn - the time a transaction can be open for (with activity occurring on it) after + which a warning alert will be issued.</para> + </listitem> + <listitem> + <para>openClose - the time a transaction can be open for before the connection it is on is + closed.</para> + </listitem> + <listitem> + <para>idleWarn - the time a transaction can be idle for (with no activity occurring on it) + after which a warning alert will be issued.</para> + </listitem> + <listitem> + <para>idleClose - the time a transaction can be idle for before the connection it is on is + closed.</para> + </listitem> + </itemizedlist> + </para> + <para> The virtualhosts configuration is shown below, and must occur inside the + //virtualhosts/virtualhost/name/ elements: </para> + <example> +<title>Configuring producer transaction timeout</title> + <programlisting><![CDATA[ +<transactionTimeout> + <openWarn>10000</openWarn> + <openClose>20000</openClose> + <idleWarn>5000</idleWarn> + <idleClose>15000</idleClose> +</transactionTimeout> + ]]></programlisting> + </example> + </section> + + <section role="h2" id="Java-Broker-Virtual-Host-Configuring-DLQ"> + <title>Configuring DLQs/Maximum Delivery Count</title> + <para>In the below configuration it can be seen that DLQs/Maximum Delivery Count are enabled at + the virtual host "localhost" with maximum delivery count set to 5 and disable for virtual host "dev-only".</para> + <para>As 'dev-only-main-queue' has its own configuration specified, this value overrides all + others and causes the features to be enabled for this queue. In contrast to this, + 'dev-only-other-queue' does not specify its own value and picks up the false value specified for + its parent virtualhost, causing the DLQ/Maximum Delivery Count features to be disabled for this + queue. Any such queue in the 'dev-only' virtualhost which does not specify its own configuration + value will have the DLQ/Maximum Delivery Count feature disabled.</para> + <para>The queue 'localhost-queue' has the DLQ/Maximum Delivery Count features disabled. + Any other queue in the 'localhost' virtualhost which does not specify + its own configuration value will have the features enabled (inherited from parent virtual host).</para> + + <example> + <title>Enabling DLQs and maximum delivery count at virtualhost and queue level within + virtualhosts.xml</title> + <programlisting><![CDATA[<virtualhosts> + ... + <virtualhost> + <name>dev-only</name> + <dev-only> + <queues> + <deadLetterQueues>false</deadLetterQueues> + <maximumDeliveryCount>0</maximumDeliveryCount> + <queue> + <name>dev-only-main-queue</name> + <dev-only-main-queue> + <deadLetterQueues>true</deadLetterQueues> + <maximumDeliveryCount>3</maximumDeliveryCount> + </dev-only-main-queue> + </queue> + <queue> + <name>dev-only-other-queue</name> + </queue> + </queues> + </dev-only> + </virtualhost> + <virtualhost> + <name>localhost</name> + <localhost> + <queues> + <deadLetterQueues>true</deadLetterQueues> + <maximumDeliveryCount>5</maximumDeliveryCount> + <queue> + <name>localhost-queue</name> + <deadLetterQueues>false</deadLetterQueues> + </queue> + </queues> + </localhost> + </virtualhost> + ... +</virtualhosts>]]> + </programlisting> + </example> + </section> + + + <section role="h2" id="Java-Broker-Virtual-Host-Configuration-Example"> + <title>An example of virtual host configuration file</title> + <example> + <title>An example of virtual host configuration file</title> + <programlisting><![CDATA[ +<?xml version="1.0" encoding="ISO-8859-1"?> +<virtualhosts> + <virtualhost> + <name>localhost</name> + <localhost> + <store> + <class>org.apache.qpid.server.store.MemoryMessageStore</class> + <!--<class>org.apache.qpid.server.store.derby.DerbyMessageStore</class> + <environment-path>${QPID_WORK}/derbystore</environment-path>--> + </store> + + <housekeeping> + <threadCount>2</threadCount> + <checkPeriod>20000</checkPeriod> + </housekeeping> + + <exchanges> + <exchange> + <type>direct</type> + <name>test.direct</name> + <durable>true</durable> + </exchange> + <exchange> + <type>topic</type> + <name>test.topic</name> + </exchange> + </exchanges> + <queues> + <exchange>amq.direct</exchange> + <maximumQueueDepth>4235264</maximumQueueDepth> + <!-- 4Mb --> + <maximumMessageSize>2117632</maximumMessageSize> + <!-- 2Mb --> + <maximumMessageAge>600000</maximumMessageAge> + <!-- 10 mins --> + <maximumMessageCount>50</maximumMessageCount> + <!-- 50 messages --> + + <queue> + <name>queue</name> + </queue> + <queue> + <name>ping</name> + </queue> + <queue> + <name>test-queue</name> + <test-queue> + <exchange>test.direct</exchange> + <durable>true</durable> + </test-queue> + </queue> + <queue> + <name>test-ping</name> + <test-ping> + <exchange>test.direct</exchange> + </test-ping> + </queue> + + </queues> + </localhost> + </virtualhost> + + <virtualhost> + <name>development</name> + <development> + <store> + <class>org.apache.qpid.server.store.MemoryMessageStore</class> + <!--<class>org.apache.qpid.server.store.derby.DerbyMessageStore</class> + <environment-path>${QPID_WORK}/derbystore</environment-path>--> + </store> + + <queues> + <minimumAlertRepeatGap>30000</minimumAlertRepeatGap> + <maximumMessageCount>50</maximumMessageCount> + <queue> + <name>queue</name> + <queue> + <exchange>amq.direct</exchange> + <maximumQueueDepth>4235264</maximumQueueDepth> + <!-- 4Mb --> + <maximumMessageSize>2117632</maximumMessageSize> + <!-- 2Mb --> + <maximumMessageAge>600000</maximumMessageAge> + <!-- 10 mins --> + </queue> + </queue> + <queue> + <name>ping</name> + <ping> + <exchange>amq.direct</exchange> + <maximumQueueDepth>4235264</maximumQueueDepth> + <!-- 4Mb --> + <maximumMessageSize>2117632</maximumMessageSize> + <!-- 2Mb --> + <maximumMessageAge>600000</maximumMessageAge> + <!-- 10 mins --> + </ping> + </queue> + </queues> + </development> + </virtualhost> + + <virtualhost> + <name>test</name> + <test> + <store> + <!--<class>org.apache.qpid.server.store.MemoryMessageStore</class>--> + <class>org.apache.qpid.server.store.derby.DerbyMessageStore</class> + <environment-path>${QPID_WORK}/derbystore</environment-path> + </store> + + <queues> + <minimumAlertRepeatGap>30000</minimumAlertRepeatGap> + <maximumMessageCount>50</maximumMessageCount> + <queue> + <name>queue</name> + <queue> + <exchange>amq.direct</exchange> + <maximumQueueDepth>4235264</maximumQueueDepth> + <!-- 4Mb --> + <maximumMessageSize>2117632</maximumMessageSize> + <!-- 2Mb --> + <maximumMessageAge>600000</maximumMessageAge> + <!-- 10 mins --> + </queue> + </queue> + <queue> + <name>ping</name> + <ping> + <exchange>amq.direct</exchange> + <maximumQueueDepth>4235264</maximumQueueDepth> + <!-- 4Mb --> + <maximumMessageSize>2117632</maximumMessageSize> + <!-- 2Mb --> + <maximumMessageAge>600000</maximumMessageAge> + <!-- 10 mins --> + </ping> + </queue> + </queues> + </test> + </virtualhost> +</virtualhosts> + ]]></programlisting> + </example> + </section> + +</section>
\ No newline at end of file diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts.xml b/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts.xml index fc1a8b1dc5..0a8f754aa0 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts.xml @@ -22,4 +22,45 @@ <chapter id="Java-Broker-Virtual-Hosts"> <title>Virtual Hosts</title> + + <section id="Java-Broker-Virtual-Hosts-Configuring-Managing"> + <title>Configuring And Managing</title> + <para>One or more Virtual Hosts can be configured on the Broker. The + <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> + and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link> + can be used to add and delete Virtual Hosts.</para> + + <para>A new Virtual Host can be created in two ways by specifying either: + <itemizedlist> + <listitem><para>A <link linkend="Java-Broker-Stores">store type</link> and a store path</para></listitem> + <listitem><para>A path to Virtual Host XML configuration file</para></listitem> + </itemizedlist> + In first case the virtual host attributes are derived from Broker global attributes. + In the second case, the Virtual Host specific configuration can be set in the configuration XML, + for example, alert thresholds, message store, queues, exchanges, ACL etc. The first way of Virtual Host creation + is more preferable as it will reduce the burden of configuration changes when migrating to a newer version, + especially, when the support of Virtual Host configuration XML will be removed. However, the second way + is the only way at the moment to configure <link linkend="Java-Broker-Stores-HA-BDB-Store">HA Message Store</link>, + Virtual Host <link linkend="Java-Broker-Security-ACLs">ACL</link> and virtual host specific attributes. + </para> + + <para>The following Virtual Host Managing operations are available from + <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>: + <itemizedlist> + <listitem><para>A new Virtual Host can be added into Broker by pressing "Add Virtual Host" button + on the Broker tab.</para></listitem> + <listitem><para>The existing Virtual Host(s) can be removed by pressing "Remove Virtual Host" button on the Broker tab.</para></listitem> + <listitem><para>The Virtual Host details can be viewed on the Virtual Host tab. + This tab can be displayed after clicking onto Virtual Host Name in the Broker object tree + or onto the Virtual Host row in the Virtual Hosts grid on the Broker tab.</para></listitem> + <listitem><para>Queues can be configured (added/removed) from Virtual Host tab</para></listitem> + <listitem><para>Exchange can be configured (added/removed) from Virtual Host tab</para></listitem> + <listitem><para>Existing Exchange/Queue tabs can be navigated from Virtual Host tab</para></listitem> + </itemizedlist> + </para> + + </section> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Virtual-Hosts-Configuration.xml"/> + </chapter> diff --git a/qpid/doc/book/src/java-broker/images/Broker-Model.png b/qpid/doc/book/src/java-broker/images/Broker-Model.png Binary files differnew file mode 100644 index 0000000000..e74f608bf1 --- /dev/null +++ b/qpid/doc/book/src/java-broker/images/Broker-Model.png 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 differindex c752adec3b..de7344a08c 100644 --- a/qpid/doc/book/src/java-broker/images/Management-Web-Console.png +++ b/qpid/doc/book/src/java-broker/images/Management-Web-Console.png diff --git a/qpid/doc/book/src/java-broker/images/VirtualHost-Model.png b/qpid/doc/book/src/java-broker/images/VirtualHost-Model.png Binary files differnew file mode 100644 index 0000000000..011026bcfb --- /dev/null +++ b/qpid/doc/book/src/java-broker/images/VirtualHost-Model.png |
