qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From oru...@apache.org
Subject svn commit: r1480672 [2/3] - in /qpid/trunk/qpid/doc/book/src/java-broker: ./ images/
Date Thu, 09 May 2013 15:05:00 GMT
Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml?rev=1480672&r1=1480671&r2=1480672&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml Thu May  9 15:04:59 2013
@@ -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>
 
 

Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml?rev=1480672&r1=1480671&r2=1480672&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml Thu May  9 15:04:59 2013
@@ -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>

Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml?rev=1480672&r1=1480671&r2=1480672&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml Thu May  9 15:04:59 2013
@@ -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 &lt;acl/&gt; element is used within the &lt;security/&gt; element of the configuration XML.
-    In the Java Broker, the ACL may be imposed broker wide or applied to individual virtual
-    hosts.  The  &lt;acl/&gt; 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>
+
+  <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>
 
-  <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>
-      &lt;broker&gt;
-        ...
-        &lt;security&gt;
-          ...
-          &lt;acl&gt;<replaceable>${conf}/broker.acl</replaceable>&lt;/acl&gt;
-        &lt;/security&gt;
-      &lt;/broker&gt;
-    </programlisting>
-
-    <para>
-    </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>
-      &lt;virtualhost&gt;
-        ...
-        &lt;name&gt;test&lt;/name&gt;
-        &lt;test&gt;
-          ...
-          &lt;security&gt;
-            &lt;acl&gt;<replaceable>${conf}/vhost_test.acl</replaceable>&lt;/acl&gt;
-          &lt;/security&gt;
-        &lt;/test&gt;
-      &lt;/virtualhost&gt;
-    </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 VIRT
 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>

Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml?rev=1480672&r1=1480671&r2=1480672&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml Thu May  9 15:04:59 2013
@@ -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>
-
-  </section>
-
-  <section id="LDAPAuthManager">
-  <title>LDAP</title>
-
   <para>
-    LDAP authentication can be configured using the &lt;simple-ldap-auth-manager&gt; element
-    within the &lt;security&gt; section. An example of how to configure this is shown below.
-    Please note this example also configures an unused &lt;pd-auth-manager&gt; to use an empty
-    password file, this is a workaround for an issue relating to registration of security providers.
+    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>
+
+  <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>
+
+  <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>
+    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 &lt;provider-auth-url&gt; in addition to providing a
-    &lt;provider-url&gt;. Note that the URL used for authentication should use ldaps:// since
+    authentication url can be overridden using &lt;LDAP authentication URL&gt; in addition to providing a
+    &lt;LDAP server URL&gt;. 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 &lt;ldap-context-factory&gt; in the configuration.
+    overridden by specifying &lt;LDAP context factory&gt; in the configuration.
   </para>
   </section>
 
-  <section>
+  <section id="Java-Broker-Security-Kerberos-Provider">
   <title>Kerberos</title>
 
   <para>
-    Kereberos Authentication is configured using the &lt;kerberos-auth-manager&gt; element within
-    the &lt;security&gt; 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 &lt;external-auth-manager&gt; element to
-      the &lt;security&gt; 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
+# &lt;user name&gt;: &lt;user password&gt;
+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 &lt;security&gt; 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>
 

Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml?rev=1480672&r1=1480671&r2=1480672&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml Thu May  9 15:04:59 2013
@@ -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>

Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml?rev=1480672&r1=1480671&r2=1480672&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml Thu May  9 15:04:59 2013
@@ -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">
-        <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.
-        </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>
 
+    <section role="h2" id="Java-Broker-SSL-Keystore">
+        <title>Keystore Configuration</title>
         <para>
-            The certAlias element is an optional way of specifying which certificate the broker should use
-            if the keystore contains multiple entries.
+            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>
+
+        <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.
-        </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 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.
+            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>
+
+        <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>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>

Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security.xml?rev=1480672&r1=1480671&r2=1480672&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security.xml Thu May  9 15:04:59 2013
@@ -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>

Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml?rev=1480672&r1=1480671&r2=1480672&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml Thu May  9 15:04:59 2013
@@ -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
 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>

Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml?rev=1480672&r1=1480671&r2=1480672&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml Thu May  9 15:04:59 2013
@@ -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>
+  <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>
 
-    <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>
+    Alternatively, the DerbyMessageStore can configured in Virtual Host configuration xml.
+    For details, see <xref linkend="Java-Broker-Stores-Derby-Store-Configuration"/>.
+  </para>
 
 </section>

Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml?rev=1480672&r1=1480671&r2=1480672&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml Thu May  9 15:04:59 2013
@@ -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

Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml?rev=1480672&r1=1480671&r2=1480672&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml Thu May  9 15:04:59 2013
@@ -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>

Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-SQL-Store.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-SQL-Store.xml?rev=1480672&r1=1480671&r2=1480672&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-SQL-Store.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores-SQL-Store.xml Thu May  9 15:04:59 2013
@@ -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>

Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores.xml?rev=1480672&r1=1480671&r2=1480672&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores.xml (original)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Stores.xml Thu May  9 15:04:59 2013
@@ -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"/>

Added: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml?rev=1480672&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml (added)
+++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml Thu May  9 15:04:59 2013
@@ -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>
+&lt;virtualhosts&gt;
+    ...
+    &lt;virtualhost&gt;                 <co id="Java-Broker-Virtual-Hosts-Configuration-Multiple-1"/>
+        &lt;name&gt;test&lt;/name&gt;
+        &lt;test&gt;
+          ...
+        &lt;/test&gt;
+    &lt;/virtualhost&gt;
+
+    &lt;virtualhost&gt;                 <co id="Java-Broker-Virtual-Hosts-Configuration-Multiple-2"/>
+        &lt;name&gt;development&lt;/name&gt;
+        &lt;development&gt;
+          ...
+        &lt;/development&gt;
+    &lt;/virtualhost&gt;
+    ...
+&lt;/virtualhosts&gt;
+        </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>
+&lt;virtualhost&gt;
+...
+    &lt;name&gt;test&lt;/name&gt;
+    &lt;test&gt;
+      ...
+      &lt;security&gt;                          <co id="Java-Broker-Virtual-Hosts-Configuration-Security-ACL-1"/>
+        ...
+        &lt;acl&gt;<replaceable>${conf}/vhost_test.acl</replaceable>&lt;/acl&gt; <co  id="Java-Broker-Virtual-Hosts-Configuration-Security-ACL-2"/>
+        ...
+      &lt;/security&gt;
+      ...
+    &lt;/test&gt;
+&lt;/virtualhost&gt;
+        </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 &lt;priority&gt;true&lt;/priority&gt; 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



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message