QPID-6108: [Java Broker Documentation] Add HA operational log messages, section related to configuration encryption and SCRAM-SHA providers.
git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1630597 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml
index 7416679..90a0b1a 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml
@@ -26,9 +26,7 @@
<appendix id="Java-Broker-Appendix-Operation-Logging">
<title>Operational Logging</title>
-
- <para> TODO add HA operation log messages</para>
-
+
<para>The Broker will, by default, produce structured log messages in response to key events in
the lives of objects within the Broker. These consise messages are designed to allow the user to
understand the actions of the Broker in retrospect. This is valuable for problem diagnosis and
@@ -137,6 +135,17 @@
scoped by the owning connection.</para>
</entry>
</row>
+ <row>
+ <entry morerows="1">Group</entry>
+ <entry> [grp(/<replaceable>groupname</replaceable>)/vhn(/<replaceable>virtualhostnode
+ name</replaceable>)]</entry>
+ </row>
+ <row>
+ <entry>
+ <para>Used for HA. Used for operations performed by the system itself often as a result
+ of actions performed on another node..</para>
+ </entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -219,6 +228,15 @@
<para>A virtualhost/message store on the Broker.</para>
</entry>
</row>
+ <row>
+ <entry morerows="1">HA Group</entry>
+ <entry> [grp(/<replaceable>group name</replaceable>)]</entry>
+ </row>
+ <row>
+ <entry>
+ <para>A HA group</para>
+ </entry>
+ </row>
</tbody>
</tgroup>
</table>
@@ -870,8 +888,9 @@
</row>
<row>
<entry>
- <para>Indicates that a message store has been created. The message store is responsible for the storage
- of the messages themselves, including the message body and any headers.</para>
+ <para>Indicates that a message store has been created. The message store is responsible
+ for the storage of the messages themselves, including the message body and any
+ headers.</para>
</entry>
</row>
<row id="Java-Broker-Appendix-Operation-Logging-Message-MST-1002">
@@ -973,8 +992,9 @@
</row>
<row>
<entry>
- <para>Indicates that a transaction store has been created. The transaction store is responsible for the storage
- of messages instances, that is, the presence of a message on a queue.</para>
+ <para>Indicates that a transaction store has been created. The transaction store is
+ responsible for the storage of messages instances, that is, the presence of a message
+ on a queue.</para>
</entry>
</row>
<row id="Java-Broker-Appendix-Operation-Logging-Message-TXN-1002">
@@ -983,8 +1003,8 @@
</row>
<row>
<entry>
- <para>Indicates that the transaction store is using <replaceable>path</replaceable> for the
- location of the store.</para>
+ <para>Indicates that the transaction store is using <replaceable>path</replaceable> for
+ the location of the store.</para>
</entry>
</row>
<row id="Java-Broker-Appendix-Operation-Logging-Message-TXN-1003">
@@ -1007,11 +1027,13 @@
</row>
<row id="Java-Broker-Appendix-Operation-Logging-Message-MST-TXN">
<entry morerows="1">TXN-1005</entry>
- <entry>Recovered <replaceable>number</replaceable> messages for queue <replaceable>name</replaceable>.</entry>
+ <entry>Recovered <replaceable>number</replaceable> messages for queue
+ <replaceable>name</replaceable>.</entry>
</row>
<row>
<entry>
- <para>Indicates that recovery recovered the given number of message instances for the given queue.</para>
+ <para>Indicates that recovery recovered the given number of message instances for the
+ given queue.</para>
</entry>
</row>
<row id="Java-Broker-Appendix-Operation-Logging-Message-TXN-1006">
@@ -1043,8 +1065,9 @@
</row>
<row>
<entry>
- <para>Indicates that a configuration store has been created. The configuration store is responsible
- for the storage of the definition of objects such as queues, exchanges, and bindings.</para>
+ <para>Indicates that a configuration store has been created. The configuration store is
+ responsible for the storage of the definition of objects such as queues, exchanges,
+ and bindings.</para>
</entry>
</row>
<row id="Java-Broker-Appendix-Operation-Logging-Message-CFG-1002">
@@ -1053,8 +1076,8 @@
</row>
<row>
<entry>
- <para>Indicates that the configuration store is using <replaceable>path</replaceable> for the
- location of the store.</para>
+ <para>Indicates that the configuration store is using <replaceable>path</replaceable>
+ for the location of the store.</para>
</entry>
</row>
<row id="Java-Broker-Appendix-Operation-Logging-Message-CFG-1003">
@@ -1087,4 +1110,152 @@
</tbody>
</tgroup>
</table>
+
+ <table pgwide="1" id="Java-Broker-Appendix-Operation-Logging-Message-List-HA">
+ <title>HA Log Messages</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Message Id</entry>
+ <entry>Message Text / Purpose</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row id="Java-Broker-Appendix-Operation-Logging-Message-HA-1001">
+ <entry morerows="1">HA-1001</entry>
+ <entry>Created</entry>
+ </row>
+ <row>
+ <entry>
+ <para>This HA node has been created.</para>
+ </entry>
+ </row>
+ <row id="Java-Broker-Appendix-Operation-Logging-Message-HA-1002">
+ <entry morerows="1">HA-1002</entry>
+ <entry>Deleted</entry>
+ </row>
+ <row>
+ <entry>
+ <para>This HA node has been deleted</para>
+ </entry>
+ </row>
+ <row id="Java-Broker-Appendix-Operation-Logging-Message-HA-1003">
+ <entry morerows="1">HA-1003</entry>
+ <entry>Added : Node : '<replaceable>name</replaceable>'
+ (<replaceable>host:port</replaceable>)</entry>
+ </row>
+ <row>
+ <entry>
+ <para>A new node has been added to the group.</para>
+ </entry>
+ </row>
+ <row id="Java-Broker-Appendix-Operation-Logging-Message-HA-1004">
+ <entry morerows="1">HA-1004</entry>
+ <entry>Removed : Node : '<replaceable>name</replaceable>'
+ (<replaceable>host:port</replaceable>)</entry>
+ </row>
+ <row>
+ <entry>
+ <para>The node has been removed from the group. This removal is permanent.</para>
+ </entry>
+ </row>
+ <row id="Java-Broker-Appendix-Operation-Logging-Message-HA-1005">
+ <entry morerows="1">HA-1005</entry>
+ <entry>Joined : Node : '<replaceable>name</replaceable>'
+ (<replaceable>host:port</replaceable>)</entry>
+ </row>
+ <row>
+ <entry>
+ <para>The node has become reachable. This may be as a result of the node being
+ restarted, or a network problem may have been resolved.</para>
+ </entry>
+ </row>
+ <row id="Java-Broker-Appendix-Operation-Logging-Message-HA-1006">
+ <entry morerows="1">HA-1006</entry>
+ <entry>Left : Node : '<replaceable>name</replaceable>'
+ (<replaceable>host:port</replaceable>)</entry>
+ </row>
+ <row>
+ <entry>
+ <para>The node is no longer reachanble. This may be as a result of the node being
+ stopped or a network partition may be preventing it from being connected. The node is
+ still a member of the group.</para>
+ </entry>
+ </row>
+ <row id="Java-Broker-Appendix-Operation-Logging-Message-HA-1007">
+ <entry morerows="1">HA-1007</entry>
+ <entry>HA-1007 : Master transfer requested : to '<replaceable>name</replaceable>'
+ (<replaceable>host:port</replaceable>)</entry>
+ </row>
+ <row>
+ <entry>
+ <para>Indicates that a master transfer operation has been requested.</para>
+ </entry>
+ </row>
+ <row id="Java-Broker-Appendix-Operation-Logging-Message-HA-1008">
+ <entry morerows="1">HA-1008</entry>
+ <entry>HA-1008 : Intruder detected : Node '<replaceable>name</replaceable>'
+ (<replaceable>host:port</replaceable>)</entry>
+ </row>
+ <row>
+ <entry>
+ <para>Indicates that an unexpected node has joined the group. The virtualhost node will
+ go into the ERROR state in response to the condition.</para>
+ </entry>
+ </row>
+ <row id="Java-Broker-Appendix-Operation-Logging-Message-HA-1009">
+ <entry morerows="1">HA-1009</entry>
+ <entry>HA-1009 : Insufficient replicas contactable</entry>
+ </row>
+ <row>
+ <entry>
+ <para>This node (which was in the master role) no longer has sufficient replica in
+ contact in order to complete transactions.</para>
+ </entry>
+ </row>
+ <row id="Java-Broker-Appendix-Operation-Logging-Message-HA-1010">
+ <entry morerows="1">HA-1010</entry>
+ <entry>HA-1010 : Role change reported: Node : '<replaceable>name</replaceable>'
+ (<replaceable>host:port</replaceable>) : from <replaceable>role</replaceable> to
+ <replaceable>role</replaceable></entry>
+ </row>
+ <row>
+ <entry>
+ <para>Indicates that the node has changed role within the group.</para>
+ </entry>
+ </row>
+ <row id="Java-Broker-Appendix-Operation-Logging-Message-HA-1011">
+ <entry morerows="1">HA-1011</entry>
+ <entry>HA-1011 : Minimum group size : <replaceable>new group size</replaceable></entry>
+ </row>
+ <row>
+ <entry>
+ <para>The quorum requirements from completing elections or transactions has been
+ changed.</para>
+ </entry>
+ </row>
+ <row id="Java-Broker-Appendix-Operation-Logging-Message-HA-1012">
+ <entry morerows="1">HA-1012</entry>
+ <entry>HA-1012 : Priority : <replaceable>priority</replaceable></entry>
+ </row>
+ <row>
+ <entry>
+ <para>The priority of the object node has been changed. Zero indicates that the node
+ cannot be elected master.</para>
+ </entry>
+ </row>
+ <row id="Java-Broker-Appendix-Operation-Logging-Message-HA-1013">
+ <entry morerows="1">HA-1013</entry>
+ <entry>HA-1013 : Designated primary : <replaceable>true|false</replaceable></entry>
+ </row>
+ <row>
+ <entry>
+ <para>This node has been designated primary and can now operate solo. Applies to two
+ node groups only.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
</appendix>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts.xml
index 997f324..cabc04f 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts.xml
@@ -24,6 +24,8 @@
<title>Concepts</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="concepts/Java-Broker-Concepts-Overview.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="concepts/Java-Broker-Concepts-Broker.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
href="concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml"/>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml b/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml
index f9a8a25..a71c37d 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml
@@ -36,7 +36,8 @@
<section role="h3" id="Java-Broker-Installation-Prerequistes-Java">
<title>Java Platform</title>
<para> The Java Broker is an 100% Java implementation and as such it can be used on any
- operating system supporting Java 1.7 or higher. This includes Linux, Solaris, Mac OS X, and
+ operating system supporting Java 1.7 or higher<footnote><para>Java Cryptography Extension (JCE)
+ Unlimited Strength required for some features</para></footnote>. This includes Linux, Solaris, Mac OS X, and
Windows XP/Vista/7/8.</para>
<para> The broker has been tested with Java implementations from both Oracle and IBM. Whatever
platform you chose, it is recommended that you ensure it is patched with any critical
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Introduction.xml b/qpid/doc/book/src/java-broker/Java-Broker-Introduction.xml
index 8db30b6..1eb33d8 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Introduction.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Introduction.xml
@@ -36,7 +36,7 @@
<para><emphasis>Headline features</emphasis></para>
<itemizedlist mark="circle">
<listitem>
- <para>100% Java implementation - runs on any platform supporting Java 1.6 or higher</para>
+ <para>100% Java implementation - runs on any platform supporting Java 1.7 or higher</para>
</listitem>
<listitem>
<para>Messaging clients support in Java, C++, Python.</para>
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 817c8f2..44faea5 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,41 +26,12 @@
<section id="Java-Broker-Security-Authentication-Providers">
<title>Authentication Providers</title>
-
- <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>
<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
@@ -117,8 +88,9 @@
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>
+ <para>Use SSL on the broker's AMQP, HTTP and JMX ports to protect the password during
+ transmission to the Broker. The Broker enforces this restriction automatically on AMQP
+ and HTTP ports.</para>
</listitem>
<listitem>
<para>Authenticate to the Directory using SSL (i.e. ldaps://) to protect the password
@@ -127,14 +99,16 @@
</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> The LDAP Authentication Provider works in the following manner. If not in <literal>bind
+ without search</literal> mode, it first connects to the Directory 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
+ <para> If the search returns a match, or is configured in <literal>bind without search</literal>
+ mode, 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>
@@ -192,21 +166,20 @@
<para>
<emphasis role="bold">Note:</emphasis> The External Authentication Provider should typically
- only be used on the AMQP ports, in conjunction with <link
+ only be used on the AMQP/HTTP 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>
+ username. As such you should configure another Authentication Provider for use on JMX
+ ports.</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>
+ be configured. If attribute "Use the full DN as the Username" is set to "true" the full DN is
+ used as an authenticated principal name. If attribute "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">
@@ -214,8 +187,23 @@
<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>
+ Provider does not require specification of any additional attributes on creation. </para>
+ </section>
+ <section id="Java-Broker-Security-ScramSha-Providers">
+ <title>SCRAM SHA Providers</title>
+ <para>The SCRAM SHA Providers uses the Broker configuration itself to store the database of
+ users. (Unlike the <link linkend="Java-Broker-Security-PlainPasswordFile-Provider"
+ >Plain</link> and <link linkend="Java-Broker-Security-Base64MD5PasswordFile-Provider"
+ >Base64MD5</link> providers that follow, there is no separate password file). The users'
+ passwords are stored as salted SHA digested password. This can be further encrypted using the
+ facilities described in <xref linkend="Java-Broker-Security-Configuration-Encryption"
+ />.</para>
+ <para>There are two varients of this provider, SHA1 and SHA256. SHA256 is recommended whenever
+ possible. SHA1 is provided with compatibility with clients utilising JDK 1.6 (which does not
+ support SHA256).</para>
+ <para>For these providers user credentials can be added, removed or changed using
+ Management.</para>
</section>
<section id="Java-Broker-Security-PlainPasswordFile-Provider">
@@ -223,19 +211,15 @@
<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>
+ creation. On Provider deletion the password file is deleted as well.</para>
+ <para>For these providers user credentials can be added, removed or changed using
+ Management.</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>
+ pairs separated by colon character. This file must not be modified externally whilst the
+ Broker is running.</para>
<programlisting>
# password file format
# <user name>: <user password>
@@ -247,16 +231,16 @@
<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>
+ 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.</para>
+ <section>
+ <title>Base64MD5 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. The password is stored MD5 digest/Base64 encoded. This
+ file must not be modified externally whilst the Broker is running.</para>
+ </section>
</section>
</section>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml
index 4e7b95a..9fe2a46 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml
@@ -23,10 +23,52 @@
<section id="Java-Broker-Security-Configuration-Encryption">
<title>Configuration Encryption</title>
- <para>
- QPID-6017 : TODO
- Describe mechanism available to secure secrets within the configuration.
- Mention that full strength JVM required.
- </para>
-
+ <para> The Broker is capable of encypting passwords and other security items stored in the
+ Broker's configuration. This is means that items such as keystore/truststore passwords, JDBC
+ passwords, and LDAP passwords can be stored in the configure in a form that is difficult to
+ read.</para>
+ <para>The Broker ships with an encryptor implementation called <literal>AESKeyFile</literal>. This
+ uses a securely generated random key of 256bit<footnote><para>Java Cryptography Extension (JCE)
+ Unlimited Strength required</para></footnote> to encrypt the secrets stored within a key
+ file. Of course, the key itself must be guarded carefully, otherwise the passwords encrypted
+ with it may be compromised. For this reason, the Broker that the file's permissions allow the
+ file to be read exclusively by the user account used for running the Broker.</para>
+ <important>
+ <para>If the keyfile is lost or corrupted, the secrets will be irrecoverable.</para>
+ </important>
+ <section id="Java-Broker-Security-Configuration-Encryption-Configuration">
+ <title>Configuration</title>
+ <para>To use <literal>AESKeyFile</literal>, first stop the Broker, then edit the Broker's
+ configuration file ${QPID_WORK}/config.json. Insert a Broker attribute called
+ <literal>confidentialConfigurationEncryptionProvider</literal> with value
+ <literal>AESKeyFile</literal>. On restarting the Broker, it will generate a keyfile in
+ location <literal>${QPID_WORK}/.keys/</literal>. Any existing passwords contained with the
+ configuration will be automatically encrypted, as will any new or changed ones in
+ future.</para>
+ <example>
+ <title>Enanbling password encryption</title>
+ <screen>
+ {
+ "id" : "3f183a59-abc3-40ad-8e14-0cac9de2cac4",
+ "name" : "${broker.name}",
+ "confidentialConfigurationEncryptionProvider" : "AESKeyFile",
+ ....
+ }
+ </screen>
+ </example>
+ <para>Note that passwords stored by the Authentication Providers <link
+ linkEnd="Java-Broker-Security-PlainPasswordFile-Provider">PlainPasswordFile</link> and.
+ <link linkEnd="Java-Broker-Security-Base64MD5PasswordFile-Provider">PlainPasswordFile</link>
+ with the external password files are <emphasis>not</emphasis> encrypted by the key. Use the
+ Scram Authentication Managers instead; these make use of the Configuration Encryption when
+ storing the users' passwords. </para>
+ </section>
+ <section id="Java-Broker-Security-Configuration-Encryption-Alternate-Implementations">
+ <title>Alternate Implementations</title>
+ <para>If the <literal>AESKeyFile</literal> encryptor implementation does not meet the needs of
+ the user, perhaps owing to the security standards of their institution, the
+ <literal>ConfigurationSecretEncrypter</literal> interface is designed as an extension point.
+ Users may implement their own implementation of ConfigurationSecretEncrypter perhaps to employ
+ stonger encryption or delegating the storage of the key to an Enterprise Password Safe.</para>
+ </section>
</section>
diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml
index 50678c2..5b729bc 100644
--- a/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml
+++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml
@@ -29,23 +29,6 @@
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-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 <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>GroupFile Provider</title>
diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml
index 5bf1a31..d361efb 100644
--- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml
+++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml
@@ -27,27 +27,5 @@
Many <emphasis>Authentication Providers</emphasis> can be configured on the Broker at the same time, from which
each <emphasis>Port</emphasis> can be assigned one.
</para>
- <para>
- The following authentication providers are supported:
- <itemizedlist>
- <listitem><para><link linkend= "Java-Broker-Security-Anonymous-Provider">Anonymous</link>:
- allows anonymous connections to the broker</para></listitem>
- <listitem><para><link linkend= "Java-Broker-Security-External-Provider">External</link>:
- delegates to external mechanisms such as SSL Client Certificate Authentication</para></listitem>
- <listitem><para><link linkend= "Java-Broker-Security-Kerberos-Provider">Kerberos</link>:
- uses Kerberos to authenticate connections via GSS-API.</para></listitem>
- <listitem><para><link linkend= "Java-Broker-Security-LDAP-Provider">SimpleLDAP</link>:
- authenticate users against an LDAP server.</para></listitem>
- <listitem><para><link linkend= "Java-Broker-Security-PlainPasswordFile-Provider">PlainPasswordFile</link>:
- authenticate users against credentials stored in plain text in a local file.</para></listitem>
- <listitem><para><link linkend= "Java-Broker-Security-Base64MD5PasswordFile-Provider">Base64MD5PasswordFile</link>:
- authenticate users against credentials stored encoded in a local file.</para></listitem>
- </itemizedlist>
- </para>
- <para>
- The Password File based providers can perform explicit management (adding, removing, changing passwords)
- of users via the Brokers management interfaces. The other providers offer no ability to manage users as they either have no scope
- for user management (e.g Anonymous) or delegate this task to other systems (e.g LDAP).
- </para>
- <para>The configuration details for Authentication Providers are covered in <xref linkend= "Java-Broker-Security-Authentication-Providers"/>.</para>
+ <para>Some Authentication Providers offer facilities for creation and deletion of users.</para>
</section>
diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml
index 70e4047..9019317 100644
--- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml
+++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml
@@ -21,43 +21,6 @@
-->
<section id="Java-Broker-Concepts-Broker">
<title>Broker</title>
- <para>The Java Broker comprises of a number of entities. This section summaries the purpose of
- each of the entities and describes the relationships between them. These details are developed
- further in the sub-sections that follow.</para>
- <para>The most important entity is the <emphasis>Virtualhost</emphasis>. A virtualhost is an
- independent namespace in which messaging is performed. A <emphasis>virtualhost</emphasis> exists
- in a container called a <emphasis>virtualhost node</emphasis>. A virtualhost node has exactly
- one virtualhost.</para>
- <para><emphasis>Ports</emphasis> accept connections for messaging and management. The Broker
- supports any number of ports. When connecting for messaging, the user specifies a virtualhost
- name to indicate the virtualhost to which it is to be connected.</para>
- <para><emphasis>Authentication Providers</emphasis> assert the identity of the user as it connects
- for messaging or management. The Broker supports any number of authentication providers. Each
- port is associated with exactly one authentication provider. The port uses the authentication
- provider to assert the identity of the user as new connections are received.</para>
- <para><emphasis>Group Providers</emphasis> provide mechanisms that provide grouping of users. A
- Broker supports zero or more group providers.</para>
- <para><emphasis>Access Control Provider</emphasis> allows the abilities of users (or groups of
- users) to be restrained. A Broker can have zero or one access control providers.</para>
- <para><emphasis>Keystores</emphasis> provide a repositories of certificates and are used when the
- Broker accepts SSL connections. Any number of keystore providers can be defined. Keystores are
- be associated with Ports defined to accepts SSL.</para>
- <para><emphasis>Truststores</emphasis> provide a repositories of trust and are used to validate a
- peer. Any number of truststore provides can be defined. Truststores can be associated with Ports
- and other entities that form SSL connections.</para>
- <para><emphasis>Remote Replication Nodes</emphasis> are used when the high availability feature is
- in use. It is the remote representation of other virtualhost nodes that form part of the same
- group.</para>
-
- <para>The following diagram depicts the Broker model: <figure>
- <title>Broker Model</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/Broker-Model.png" format="PNG" scalefit="1"/>
- </imageobject>
- <textobject>
- <phrase>Broker Model</phrase>
- </textobject>
- </mediaobject>
- </figure> These concepts will be expanded upon in the forthcoming pages. </para>
+ <para>The <emphasis>Broker</emphasis> is the outermost entity within the system.</para>
+ <para>The Broker is backed by storage. This storage is used to record the durable entities that exist beneath it.</para>
</section>
diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml
new file mode 100644
index 0000000..f83500e
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Overview.xml
@@ -0,0 +1,77 @@
+<?xml version="1.0"?>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+<section id="Java-Broker-Concepts-Overview">
+ <title>Overview</title>
+ <para>The Broker comprises of a number of entities. This section summaries the purpose of
+ each of the entities and describes the relationships between them. These details are developed
+ further in the sub-sections that follow.</para>
+ <para>The most important entity is the <emphasis>Virtualhost</emphasis>. A virtualhost is an
+ independent namespace in which messaging is performed. A <emphasis>virtualhost</emphasis> exists
+ in a container called a <emphasis>virtualhost node</emphasis>. A virtualhost node has exactly
+ one virtualhost.</para>
+ <para><emphasis>Ports</emphasis> accept connections for messaging and management. The Broker
+ supports any number of ports. When connecting for messaging, the user specifies a virtualhost
+ name to indicate the virtualhost to which it is to be connected.</para>
+ <para><emphasis>Authentication Providers</emphasis> assert the identity of the user as it connects
+ for messaging or management. The Broker supports any number of authentication providers. Each
+ port is associated with exactly one authentication provider. The port uses the authentication
+ provider to assert the identity of the user as new connections are received.</para>
+ <para><emphasis>Group Providers</emphasis> provide mechanisms that provide grouping of users. A
+ Broker supports zero or more group providers.</para>
+ <para><emphasis>Access Control Provider</emphasis> allows the abilities of users (or groups of
+ users) to be restrained. A Broker can have zero or one access control providers.</para>
+ <para><emphasis>Keystores</emphasis> provide a repositories of certificates and are used when the
+ Broker accepts SSL connections. Any number of keystore providers can be defined. Keystores are
+ be associated with Ports defined to accepts SSL.</para>
+ <para><emphasis>Truststores</emphasis> provide a repositories of trust and are used to validate a
+ peer. Any number of truststore provides can be defined. Truststores can be associated with Ports
+ and other entities that form SSL connections.</para>
+ <para><emphasis>Remote Replication Nodes</emphasis> are used when the high availability feature is
+ in use. It is the remote representation of other virtualhost nodes that form part of the same
+ group.</para>
+ <para>These concepts will be developed over the forthcoming pages. The diagrams below also help
+ put these entities in context of one and other.</para>
+ <para><figure>
+ <title>Message Flow</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/Broker-MessageFlow.png" format="PNG" scalefit="1"/>
+ </imageobject>
+ <textobject>
+ <phrase>Message Flow through the Broker</phrase>
+ </textobject>
+ </mediaobject>
+ </figure></para>
+ <para><figure>
+ <title>Broker Structure</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/Broker-Model.png" format="PNG" scalefit="1"/>
+ </imageobject>
+ <textobject>
+ <phrase>Broker Structure</phrase>
+ </textobject>
+ </mediaobject>
+ </figure>
+ </para>
+
+</section>
diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml
index 37b5429..a12b589 100644
--- a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml
+++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml
@@ -21,19 +21,18 @@
-->
<section id="Java-Broker-Concepts-Ports">
-<title>Ports</title>
- <para>
- The Broker supports configuration of <emphasis>Ports</emphasis> to specify the particular AMQP messaging
- and HTTP/JMX management connectivity it offers for use.
- </para>
- <para>
- Each Port is configured with the particular <emphasis>Protocols</emphasis> and <emphasis>Transports</emphasis> it supports, as well as the <emphasis>Authentication Provider</emphasis> to be used to authenticate connections. Where SSL is in use, the <emphasis>Port</emphasis> configuration also defines which <emphasis>Keystore</emphasis> to use and (where supported) which <emphasis>TrustStore(s)</emphasis> and whether Client Certificates should be requested/required.
- </para>
- <para>
- Different <emphasis>Ports</emphasis> can support different protocols, and many <emphasis>Ports</emphasis> can be configured on the Broker.</para>
- <para>
- The following AMQP protocols are currently supported by the Broker:
- <itemizedlist>
+ <title>Ports</title>
+ <para> The Broker supports configuration of <emphasis>Ports</emphasis> to specify the particular
+ AMQP messaging and HTTP/JMX management connectivity it offers for use. </para>
+ <para> Each Port is configured with the particular <emphasis>Protocols</emphasis> and
+ <emphasis>Transports</emphasis> it supports, as well as the <emphasis>Authentication
+ Provider</emphasis> to be used to authenticate connections. Where SSL is in use, the
+ <emphasis>Port</emphasis> configuration also defines which <emphasis>Keystore</emphasis>
+ to use and (where supported) which <emphasis>TrustStore(s)</emphasis> and whether Client
+ Certificates should be requested/required. </para>
+ <para> Different <emphasis>Ports</emphasis> can support different protocols, and many
+ <emphasis>Ports</emphasis> can be configured on the Broker.</para>
+ <para> The following AMQP protocols are currently supported by the Broker: <itemizedlist>
<listitem><para><emphasis>AMQP 0-8</emphasis></para></listitem>
<listitem><para><emphasis>AMQP 0-9</emphasis></para></listitem>
<listitem><para><emphasis>AMQP 0-9-1</emphasis></para></listitem>
@@ -42,7 +41,20 @@
</itemizedlist>
</para>
- <para>
- Addittionally, HTTP and JMX ports can be configured for use by the associated management plugins.
- </para>
+ <para> Addittionally, HTTP and JMX ports can be configured for use by the associated management
+ plugins. </para>
+ <para>This diagram explains how Ports, <link
+ linkEnd="Java-Broker-Concepts-Authentication-Providers">Authentication Providers</link>
+ and an Access Control Provider work together to allow an application to form a connection to
+ a Virtualhost.<figure>
+ <title>Control flow during Authentication</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/Broker-PortAuthFlow.png" format="PNG" scalefit="1"/>
+ </imageobject>
+ <textobject>
+ <phrase>Control flow during Authentication</phrase>
+ </textobject>
+ </mediaobject>
+ </figure></para>
</section>
diff --git a/qpid/doc/book/src/java-broker/images/Broker-MessageFlow.png b/qpid/doc/book/src/java-broker/images/Broker-MessageFlow.png
new file mode 100644
index 0000000..b687dfe
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/images/Broker-MessageFlow.png
Binary files differ
diff --git a/qpid/doc/book/src/java-broker/images/Broker-PortAuthFlow.png b/qpid/doc/book/src/java-broker/images/Broker-PortAuthFlow.png
new file mode 100644
index 0000000..4df2fa1
--- /dev/null
+++ b/qpid/doc/book/src/java-broker/images/Broker-PortAuthFlow.png
Binary files differ
diff --git a/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml
index 9e2bfc4..33c3557 100644
--- a/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml
+++ b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml
@@ -50,7 +50,7 @@
<example>
<title>Web Management Console - Authentication</title>
<screenshot>
- <graphic fileref="images/Management-Web-Auth.png" width="600px"/>
+ <graphic fileref="images/Management-Web-Auth.png" width="800px"/>
</screenshot>
</example>
</section>
@@ -61,7 +61,7 @@
<example>
<title>Web Management Orientation - Console</title>
<screenshot>
- <graphic fileref="images/Management-Web-Console.png" width="600px"/>
+ <graphic fileref="images/Management-Web-Console.png" width="800px"/>
</screenshot>
</example>
<para>
@@ -93,7 +93,7 @@
<example>
<title>Web Management Orientation - Tab</title>
<screenshot>
- <graphic fileref="images/Management-Web-Tab.png" width="600px"/>
+ <graphic fileref="images/Management-Web-Tab.png" width="800px"/>
</screenshot>
</example>
<para>The elements of a tab are now explained: <itemizedlist>
diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml
index e979705..d4248ca 100644
--- a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml
+++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml
@@ -23,17 +23,50 @@
<section id="Java-Broker-Management-Managing-Authentication-Providers">
<title>Authentication Providers</title>
<para>
- <link linkend="Java-Broker-Concepts-Authentication-Providers">Authentication Providers</link> are used by <link linkend="Java-Broker-Concepts-Ports">Ports</link> to
- authenticate connections. </para>
+ <link linkend="Java-Broker-Concepts-Authentication-Providers">Authentication
+ Providers</link> are used by <link linkend="Java-Broker-Concepts-Ports">Ports</link> to
+ authenticate connections.</para>
<para>See <xref linkend="Java-Broker-Security-Authentication-Providers"/></para>
-
+
+ <section id="Java-Broker-Management-Managing-Authentication-Providers-Types">
+ <title>Types</title>
+ <para> The following authentication providers are supported: <itemizedlist>
+ <listitem><para><link linkend="Java-Broker-Security-Anonymous-Provider"
+ >Anonymous</link>: allows anonymous connections to the
+ Broker</para></listitem>
+ <listitem><para><link linkend="Java-Broker-Security-External-Provider"
+ >External</link>: delegates to external mechanisms such as SSL Client
+ Certificate Authentication</para></listitem>
+ <listitem><para><link linkend="Java-Broker-Security-Kerberos-Provider"
+ >Kerberos</link>: uses Kerberos to authenticate connections via
+ GSS-API.</para></listitem>
+ <listitem><para><link linkend="Java-Broker-Security-LDAP-Provider"
+ >SimpleLDAP</link>: authenticate users against an LDAP
+ server.</para></listitem>
+ <listitem><para><link linkend="Java-Broker-Security-ScramSha-Providers"
+ >ScramSha</link>: authenticate users against credentials stored in a
+ local database</para></listitem>
+ <listitem><para><link linkend="Java-Broker-Security-PlainPasswordFile-Provider"
+ >PlainPasswordFile</link>: authenticate users against credentials stored
+ in plain text in a local file.</para></listitem>
+ <listitem><para><link linkend="Java-Broker-Security-Base64MD5PasswordFile-Provider"
+ >Base64MD5PasswordFile</link>: authenticate users against credentials
+ stored encoded in a local file.</para></listitem>
+ </itemizedlist>
+ <para>The last three providers offer user management facilities too, that is, users can
+ be created, deleted and passwords reset.</para>
+ </para>
+ </section>
+
<section id="Java-Broker-Management-Managing-Authentication-Providers-Attributes">
<title>Attributes</title>
- <para><itemizedlist>
+ <para>
+ <itemizedlist>
<listitem>
- <para><emphasis>Name the authentication</emphasis>.</para>
+ <para><emphasis>Name the authentication provider</emphasis>.</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
<para>Other attributes are provider specific.</para>
</section>
<section id="Java-Broker-Management-Managing-Authentication-Providers-Children">
diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml
index 7c1f1e0..a8e3e91 100644
--- a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml
+++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml
@@ -48,7 +48,7 @@
<title>Context</title>
<para>
<itemizedlist>
- <listitem><para><emphasis>broker.flowToDiskThreshold</emphasis> Control the <link linkend="Java-Broker-Runtime-Flow-To-Disk">flow to disk</link> feature.</para></listitem>
+ <listitem><para><emphasis>broker.flowToDiskThreshold</emphasis> Controls the <link linkend="Java-Broker-Runtime-Flow-To-Disk">flow to disk</link> feature.</para></listitem>
</itemizedlist>
</para>
</section>
diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Entities-Matrix.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Entities-Matrix.xml
index 342798f..3ac1214 100644
--- a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Entities-Matrix.xml
+++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Entities-Matrix.xml
@@ -118,6 +118,19 @@
<entry>No</entry>
<entry>No</entry>
</row>
+ <row>
+ <entry>Users</entry>
+ <entry>C//D</entry>
+ <entry>C/D</entry>
+ <entry>No</entry>
+ </row>
+ <row>
+ <entry>Groups</entry>
+ <entry>C//D</entry>
+ <entry>No</entry>
+ <entry>No</entry>
+ </row>
+
</tbody>
</tgroup>
</table>
