QPID-6108: [Java Broker Documentation] Updates for changes made during 0.30

* Remove references to virtualhost.xml
* Rework concepts section
* Rework management section to separate means of management from management of the entities themselves
* Remove references message stores
* Update JVM defect to Java 7
* ACL updates
* Add Flow to Disk

Still further changes required flagged by TODO.

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

1 files changed, 173 insertions, 164 deletions

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 538d08d8e9..817c8f2621 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,113 +26,136 @@
 
 <section id="Java-Broker-Security-Authentication-Providers">
   <title>Authentication Providers</title>
-  <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 provider". Any number of Authentication Providers can be configured
-    on the Broker at the same time.
-  </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>
-
-  <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>
+  
+  <para>TODO SCRAM-SHA</para>
+  <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 provider". Any number of Authentication Providers can be configured on
+    the Broker at the same time. </para>
+
+  <para> The Authentication Providers can be configured using <link
+      linkend="Java-Broker-Management-Channel-REST-API">REST Management interfaces</link> and <link
+      linkend="Java-Broker-Management-Channel-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.
+    <para> 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.
+    </para>
   </important>
 
   <section id="Java-Broker-Security-LDAP-Provider">
-  <title>Simple LDAP Authentication Provider</title>
-
-  <para>
-    SimpleLDAPAuthenticationProvider authenticates connections against a Directory (LDAP).
-  </para>
-  <para>
-    To create a SimpleLDAPAuthenticationProvider the following mandatory fields are required:
-    <itemizedlist>
-      <listitem><para><emphasis>LDAP server URL</emphasis> is the URL of the server, for example, <literal>ldaps://example.com:636</literal></para></listitem>
-      <listitem><para><emphasis>Search context</emphasis> is the distinguished name of the search base object. It defines the location from which
-        the search for users begins, for example, <literal>dc=users,dc=example,dc=com</literal></para></listitem>
-      <listitem><para><emphasis>Search filter</emphasis> is a DN template to find an LDAP user entry by provided user name, for example, <literal>(uid={0})</literal></para></listitem>
-    </itemizedlist>
-    Additionally, the following optional fields can be specified:
-    <itemizedlist>
-      <listitem><para><emphasis>LDAP context factory</emphasis> is a fully qualified class name for the JNDI LDAP context factory.
-        This class must implement the <ulink url="&oracleJdkDocUrl;javax/naming/spi/InitialContextFactory.html">InitialContextFactory</ulink>
-        interface and produce instances of <ulink url="&oracleJdkDocUrl;javax/naming/directory/DirContext.html">DirContext</ulink>.
-        If not specified a default value of <literal>com.sun.jndi.ldap.LdapCtxFactory</literal> is used.</para></listitem>
-      <listitem><para><emphasis>LDAP authentication URL</emphasis> is the URL of LDAP server for performing "ldap bind". If not
-        specified, the <emphasis>LDAP server URL</emphasis> will be used for both searches and authentications.</para></listitem>
-      <listitem><para><emphasis>Truststore name</emphasis> is a name of <link linkend="SSL-Truststore-ClientCertificate">configured truststore</link>.
-        Use this if connecting to a Directory over SSL (i.e. ldaps://) which is protected by a certificate signed by a private CA (or
-        utilising a self-signed certificate).</para></listitem>
-    </itemizedlist>
-  </para>
-
-  <important>
-    In order to protect the security of the user's password, when using LDAP authentication, you must:
-    <itemizedlist>
-      <listitem><para>Use SSL on the broker's AMQP, JMX, and HTTP ports to protect the password during
-        transmission to the Broker.</para></listitem>
-      <listitem><para>Authenticate to the Directory using SSL (i.e. ldaps://) to protect the password
-        during transmission from the Broker to the Directory.</para></listitem>
-    </itemizedlist>
-  </important>
+    <title>Simple LDAP Authentication Provider</title>
+
+    <para> SimpleLDAPAuthenticationProvider authenticates connections against a Directory (LDAP). </para>
+    <para> To create a SimpleLDAPAuthenticationProvider the following mandatory fields are required: <itemizedlist>
+        <listitem>
+          <para><emphasis>LDAP server URL</emphasis> is the URL of the server, for example,
+              <literal>ldaps://example.com:636</literal></para>
+        </listitem>
+        <listitem>
+          <para><emphasis>Search context</emphasis> is the distinguished name of the search base
+            object. It defines the location from which the search for users begins, for example,
+              <literal>dc=users,dc=example,dc=com</literal></para>
+        </listitem>
+        <listitem>
+          <para><emphasis>Search filter</emphasis> is a DN template to find an LDAP user entry by
+            provided user name, for example, <literal>(uid={0})</literal></para>
+        </listitem>
+      </itemizedlist> Additionally, the following optional fields can be specified: <itemizedlist>
+        <listitem>
+          <para><emphasis>LDAP context factory</emphasis> is a fully qualified class name for the
+            JNDI LDAP context factory. This class must implement the <ulink
+              url="&oracleJdkDocUrl;javax/naming/spi/InitialContextFactory.html"
+              >InitialContextFactory</ulink> interface and produce instances of <ulink
+              url="&oracleJdkDocUrl;javax/naming/directory/DirContext.html">DirContext</ulink>. If
+            not specified a default value of <literal>com.sun.jndi.ldap.LdapCtxFactory</literal> is
+            used.</para>
+        </listitem>
+        <listitem>
+          <para><emphasis>LDAP authentication URL</emphasis> is the URL of LDAP server for
+            performing "ldap bind". If not specified, the <emphasis>LDAP server URL</emphasis> will
+            be used for both searches and authentications.</para>
+        </listitem>
+        <listitem>
+          <para><emphasis>Truststore name</emphasis> is a name of <link
+              linkend="Java-Broker-Management-Managing-Truststores-Attributes">configured
+              truststore</link>. Use this if connecting to a Directory over SSL (i.e. ldaps://)
+            which is protected by a certificate signed by a private CA (or utilising a self-signed
+            certificate).</para>
+        </listitem>
+      </itemizedlist>
+    </para>
 
-  <para>
-    The LDAP Authentication Provider works in the following manner.  It first connects to the Directory anonymously
-    and searches for the ldap entity which is identified by the username. The search begins at the distinguished name
-    identified by <literal>Search Context</literal> and uses the username as a filter.  The search scope is sub-tree
-    meaning the search will include the base object and the subtree extending beneath it.
-  </para>
-
-  <para>
-    If the search returns a match, the Authentication Provider then attempts to bind to the LDAP server with the given
-    name and the password.  Note that
-    <ulink url="&oracleJdkDocUrl;javax/naming/Context.html#SECURITY_AUTHENTICATION">simple security authentication</ulink>
-    is used so the Directory receives the password in the clear.
-  </para>
+    <important>
+      <para>In order to protect the security of the user's password, when using LDAP authentication,
+        you must: </para>
+      <itemizedlist>
+        <listitem>
+          <para>Use SSL on the broker's AMQP, JMX, and HTTP ports to protect the password during
+            transmission to the Broker.</para>
+        </listitem>
+        <listitem>
+          <para>Authenticate to the Directory using SSL (i.e. ldaps://) to protect the password
+            during transmission from the Broker to the Directory.</para>
+        </listitem>
+      </itemizedlist>
+    </important>
+
+    <para> The LDAP Authentication Provider works in the following manner. It first connects to the
+      Directory anonymously and searches for the ldap entity which is identified by the username.
+      The search begins at the distinguished name identified by <literal>Search Context</literal>
+      and uses the username as a filter. The search scope is sub-tree meaning the search will
+      include the base object and the subtree extending beneath it. </para>
+
+    <para> If the search returns a match, the Authentication Provider then attempts to bind to the
+      LDAP server with the given name and the password. Note that <ulink
+        url="&oracleJdkDocUrl;javax/naming/Context.html#SECURITY_AUTHENTICATION">simple security
+        authentication</ulink> is used so the Directory receives the password in the clear. </para>
   </section>
 
   <section id="Java-Broker-Security-Kerberos-Provider">
-  <title>Kerberos</title>
+    <title>Kerberos</title>
 
-  <para>
-    Kereberos Authentication Provider uses java GSS-API SASL mechanism to authenticate the connections.
-  </para>
+    <para> Kereberos Authentication Provider uses java GSS-API SASL mechanism to authenticate the
+      connections. </para>
 
-  <para>
-    Configuration of kerberos is done through system properties (there doesn't seem to be a way
-    around this unfortunately).
-  </para>
+    <para> Configuration of kerberos is done through system properties (there doesn't seem to be a
+      way around this unfortunately). </para>
 
-  <programlisting>
+    <programlisting>
     export JAVA_OPTS=-Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf
     ${QPID_HOME}/bin/qpid-server
   </programlisting>
 
-  <para>Where qpid.conf would look something like this:</para>
+    <para>Where qpid.conf would look something like this:</para>
 
-  <programlisting><![CDATA[
+    <programlisting><![CDATA[
 com.sun.security.jgss.accept {
     com.sun.security.auth.module.Krb5LoginModule required
     useKeyTab=true
@@ -145,109 +168,95 @@ com.sun.security.jgss.accept {
     principal="<name>/<host>";
 };]]></programlisting>
 
-  <para>
-    Where realm, kdc, keyTab and principal should obviously be set correctly for the environment
-    where you are running (see the existing documentation for the C++ broker about creating a keytab
-    file).
-  </para>
+    <para> Where realm, kdc, keyTab and principal should obviously be set correctly for the
+      environment where you are running (see the existing documentation for the C++ broker about
+      creating a keytab file). </para>
 
-  <para>
-    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> 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>
+    <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="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 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> When <link linkend="Java-Broker-Management-Managing-Truststores"> requiring SSL Client
+        Certificates</link> be 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>
-      <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 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>
-
-    <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>
+      <emphasis role="bold">Note:</emphasis> The External Authentication Provider should typically
+      only be used on the AMQP ports, in conjunction with <link
+        linkend="Java-Broker-Management-Managing-Ports">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 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>
+
+    <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="Java-Broker-Security-Anonymous-Provider">
     <title>Anonymous</title>
 
-    <para>
-      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>
+    <para> 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>
 
   </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>
-    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>
+    <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> 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>
+      <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>
 
   <section id="Java-Broker-Security-Base64MD5PasswordFile-Provider">
     <title>Base64MD5 Password File</title>
-    <para>
-      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>
-    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>
+    <para> 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> 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>
   </section>
 </section>
-