Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control.xml URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control.xml?rev=1629579&r1=1629578&r2=1629579&view=diff ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control.xml (original) +++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control.xml Mon Oct 6 06:56:59 2014 @@ -26,10 +26,9 @@ <section role="h2" id="Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control-GeneralInformation"> <title>General Information</title> <para> - The Qpid 0.6 release introduced a simplistic producer-side flow control mechanism - into the Java Messaging Broker, causing producers to be flow-controlled when they - attempt to send messages to an overfull queue. Qpid 0.18 introduced a similar - mechanism triggered by an overfull persistent message store on a virtual host. + The Java Broker supports a flow control mechanism to which can be used to prevent either a single queue + or an entire virtualhost exceeding configured limits. These two mechanisms are described + next. </para> </section> <section role="h2" id="Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control-ServerConfiguration"> @@ -41,23 +40,17 @@ which is "overfull". The producer flow control will be rescinded when all Queues on which a producer is blocking become "underfull". A Queue is defined as overfull when the size (in bytes) of the messages on the queue exceeds the - "capacity" of the Queue. A Queue becomes "underfull" when its size becomes - less than the "flowResumeCapacity". + <emphasis>capacity</emphasis> of the Queue. A Queue becomes "underfull" when its + size becomes less than the <emphasis>resume capacity</emphasis>. </para> <para> - Examples how to configure flow control in virtual host configuration are provided in - <xref linkend="Java-Broker-Virtual-Host-Configure-Flow-Control"/>. + The capacity and resume capacity can be specified when the queue is created. This + can be done using the Flow Control Settings wintin the Queue creation dialogue. </para> - <para> - Where no flowResumeCapacity is set, the flowResumeCapacity is set to be equal - to the capacity. Where no capacity is set, capacity is defaulted to 0 meaning - there is no capacity limit. - </para> - <important>Flow control can be configured globally for all virtual hosts by specifying threshold values for Broker flow control attributes.</important> <section role="h4"> <title>Broker Log Messages</title> <para> - There are four new Broker log messages that may occur if flow control through queue capacity limits is enabled. + There are four Broker log messages that may occur if flow control through queue capacity limits is enabled. Firstly, when a capacity limited queue becomes overfull, a log message similar to the following is produced </para> <programlisting> @@ -84,8 +77,8 @@ MESSAGE [con:2(guest@anonymous(713889609 <section role="h3"> <title>Disk quota-based flow control</title> <para> - Since version 0.18 of Qpid Broker, flow control can be triggered when a - configured disk quota is exceeded. This is supported by the BDB and Derby message stores. + Flow control can also be triggered when a configured disk quota is exceeded. This is supported by the BDB and + Derby virtualhosts. </para> <para> This functionality blocks all producers on reaching the disk overflow limit. When consumers @@ -96,15 +89,17 @@ MESSAGE [con:2(guest@anonymous(713889609 Two limits can be configured: </para> <para> - overfull limit - the maximum space on disk (in bytes) which can be used by store. + overfull limit - the maximum space on disk (in bytes). </para> <para> underfull limit - when the space on disk drops below this limit, producers are allowed to resume publishing. </para> <para> - An example how to configure disk quota-based flow control in virtual host configuration is provided in - <xref linkend="Java-Broker-Virtual-Host-Configure-Disk-Quotas"/>. + The overfull and underful limit can be specified when a new virtualhost is created or an exiting + virtualhost is edited. This can be done using the Store Overflow and Store Underfull settings + within the virtual host creation and edit dialogue. If editing an existing virtualhost, the virtualhost + must be restarted for the new values to take effect. </para> <para> @@ -117,7 +112,7 @@ MESSAGE [con:2(guest@anonymous(713889609 <section role="h4"> <title>Broker Log Messages for quota flow control</title> <para> - There are 2 new broker log messages that may occur if flow control through disk quota limits is enabled. + There are two broker log messages that may occur if flow control through disk quota limits is enabled. When the virtual host is blocked due to exceeding of the disk quota limit the following message appears in the broker log <programlisting>
Added: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Flow-To-Disk.xml URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Flow-To-Disk.xml?rev=1629579&view=auto ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Flow-To-Disk.xml (added) +++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Flow-To-Disk.xml Mon Oct 6 06:56:59 2014 @@ -0,0 +1,42 @@ +<?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-Runtime-Flow-To-Disk"> + <title>Flow to Disk</title> + <para>Flow to disk limits the amount of heap memory that can be occupied by messages. Once this + limit is reached any new transient messages and all existing transient messages will be + transferred to disk. Newly arriving transient messages will continue to go to the disk until the + cumulative size of all messages falls below the limit once again.</para> + <para>By default the Broker makes 40% of the max available memory for messages. This memory is + divided between all the queues across all virtual hosts defined on the Broker with a percentage + calculated according to their current queue size.</para> + <para>For example if there are two queues, one containing 75MB and the second 100MB messages + respectively and the Broker has 1GB heap memory with the default of 40% available for messages. + The first queue will have a target size of 170MB and the second 230MB. Once 400MB is taken by + messages, messages will begin to flow to disk. New messages will cease to flow to disk when + their cumulative size falls beneath 400MB.</para> + <para>Target queue sizes are refreshed periodically according to the housekeeping cycle.</para> + <para>Flow to disk is configured by Broker context variable + <literal>broker.flowToDiskThreshold</literal>. It is expressed as a size in bytes and defaults + to 40% of the JVM maximum heap size.</para> + <para>TODO: implement log message when flow to disk activates/deactives</para> +</section> 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=1629579&r1=1629578&r2=1629579&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 Mon Oct 6 06:56:59 2014 @@ -70,11 +70,8 @@ the Management interfaces, but is not possible to determine this information from a message client. Specifically, the optional JMS message header <property>JMSXDeliveryCount</property> is not supported.</para> - <para>Maximum Delivery Count can be enabled via management (see <xref - linkend="Java-Broker-Configuring-And-Managing"/>) using the the queue declare property - <property>x-qpid-maximum-delivery-count</property> or via <link - linkend="Java-Broker-Runtime-Handling-Undeliverable-Messages-Configuration">configuration</link> - as illustrated below.</para> + <para>Maximum Delivery Count can be specified when a new queue is created or using the the + queue declare property <property>x-qpid-maximum-delivery-count</property></para> </section> <section role="h2" id="Java-Broker-Runtime-Handling-Undeliverable-Messages-Dead-Letter-Queues"> @@ -86,10 +83,8 @@ onto the DLQ and removed from the original queue. </para> <para>The DLQ feature causes generation of a Dead Letter Exchange and a Dead Letter Queue. These are named convention QueueName<emphasis>_DLE</emphasis> and QueueName<emphasis>_DLQ</emphasis>.</para> - <para>DLQs can be enabled via management (see <xref linkend="Java-Broker-Configuring-And-Managing" - />) using the queue declare property <property>x-qpid-dlq-enabled</property> or via <link - linkend="Java-Broker-Runtime-Handling-Undeliverable-Messages-Configuration">configuration</link> - as illustrated below.</para> + <para>DLQs can be enabled when a new queue is created + or using the queue declare property <property>x-qpid-dlq-enabled</property>.</para> <caution> <title>Avoid excessive queue depth</title> <para>Applications making use of DLQs <emphasis>should</emphasis> make provision for the frequent @@ -99,16 +94,4 @@ depths should not be permitted to develop.</para> </caution> </section> - - <section role="h2" id="Java-Broker-Runtime-Handling-Undeliverable-Messages-Configuration"> - <title>Configuration</title> - <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> - - </section> Modified: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml?rev=1629579&r1=1629578&r2=1629579&view=diff ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml (original) +++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml Mon Oct 6 06:56:59 2014 @@ -22,7 +22,7 @@ <section id="Java-Broker-Runtime-Log-Files"> <title>Log Files</title> - <para> The Broker uses the <ulink href="http://logging.apache.org/log4j/1.2/";>Apache Log4J</ulink> + <para> The Broker uses the <ulink url="http://logging.apache.org/log4j/1.2/";>Apache Log4J</ulink> Logging Framework for all logging activity. </para> <para> In the Broker's shipped configuration, all logging is directed to log file <literal><link linkend="Java-Broker-Appendix-Environment-Variables-Qpid-Work" @@ -47,7 +47,7 @@ <para>Logging can be reconfigured either by changing the logging configuration file <literal><link linkend="Java-Broker-Appendix-Environment-Variables-Qpid-Home" >${QPID_HOME}</link>/etc/log4j.xml</literal> or at runtime using the Logging Management MBean, - see <xref linkend="Java-Broker-Configuring-And-Managing-JMX-Management-MBeans"/> for + see <xref linkend="Java-Broker-Management-Channel-JMX-MBeans"/> for details.</para> <section id="Java-Broker-Runtime-Log-Files-Enable-Debug"> <title>Enabling Debug</title> 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=1629579&r1=1629578&r2=1629579&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 Mon Oct 6 06:56:59 2014 @@ -45,9 +45,9 @@ <title>Purpose</title> <para> This feature has been introduced to address the scenario where an open transaction on the broker holds an open transaction on the persistent store. This can have undesirable consequences - if the store does not time out or close long-running transactions, such as with <link - linkend="Java-Broker-Stores-BDB-Store">BDB</link>. This can can result in a rapid increase in - disk usage size, bounded only by available space, due to growth of the transaction log. </para> + if the store does not time out or close long-running transactions, such as with BDB. This can can + result in a rapid increase in disk usage size, bounded only by available space, due to growth of + the transaction log. </para> </section> <section role="h2" id="Java-Broker-Runtime-Producer-Transaction-Timeout-Scope"> <title>Scope</title> @@ -113,9 +113,8 @@ CHN-1003 : Close]]> <title>Configuration</title> <section role="h3" id="Java-Broker-Runtime-Producer-Transaction-Timeout-Configuration-Overview"> <title>Configuration</title> - <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>The transaction timeouts can be specified when a new virtualhost is created or an exiting + virtualhost is edited.</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, and configure production settings appropriately for both warning and closure. Ideally @@ -134,11 +133,5 @@ CHN-1003 : Close]]> producer hanging or leaving a transaction idle or open, and closed, and must take appropriate action to handle that scenario.</para> </section> - <section role="h3" - id="Java-Broker-Runtime-Producer-Transaction-Timeout-Configuration-Virtualhosts"> - <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-Runtime.xml URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml?rev=1629579&r1=1629578&r2=1629579&view=diff ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml (original) +++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml Mon Oct 6 06:56:59 2014 @@ -22,9 +22,14 @@ <chapter id="Java-Broker-Runtime"> <title>Runtime</title> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="Java-Broker-Runtime-Log-Files.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="Java-Broker-Runtime-Disk-Space-Management.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="Java-Broker-Runtime-Producer-Transaction-Timeout.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="Java-Broker-Runtime-Handling-Undeliverable-Messages.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="Java-Broker-Close-On-No-Route.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="Java-Broker-Runtime-Log-Files.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; + href="Java-Broker-Runtime-Disk-Space-Management.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; + href="Java-Broker-Runtime-Producer-Transaction-Timeout.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; + href="Java-Broker-Runtime-Handling-Undeliverable-Messages.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="Java-Broker-Close-On-No-Route.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="Java-Broker-Runtime-Flow-To-Disk.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="Java-Broker-Runtime-Background-Recovery.xml"/> </chapter> 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=1629579&r1=1629578&r2=1629579&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 Mon Oct 6 06:56:59 2014 @@ -43,8 +43,8 @@ </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>. + The ACL 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 ACL Provider managing operations are available from Web Management Console: @@ -195,7 +195,7 @@ <row> <entry> <command>CREATE</command> </entry> <entry> <para> Applied when an object is created, such as bindings, queues, exchanges</para> </entry> - <entry><para>EXCHANGE, QUEUE, USER, GROUP</para></entry> + <entry><para>VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP</para></entry> <entry><para>see properties on the corresponding object type</para></entry> </row> <row> @@ -219,7 +219,7 @@ <row> <entry> <command>DELETE</command> </entry> <entry> <para> Applied when objects are deleted </para> </entry> - <entry><para>EXCHANGE, QUEUE, USER, GROUP</para></entry> + <entry><para>VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP</para></entry> <entry><para>see properties on the corresponding object type</para></entry> </row> <row> @@ -231,7 +231,7 @@ <row> <entry> <command>UPDATE</command> </entry> <entry> <para> Applied when an object is updated </para> </entry> - <entry><para>EXCHANGE, QUEUE, USER, GROUP</para></entry> + <entry><para>VIRTUALHOSTNODE, VIRTUALHOST, EXCHANGE, QUEUE, USER, GROUP</para></entry> <entry><para>see EXCHANGE and QUEUE properties</para></entry> </row> <row> @@ -262,9 +262,15 @@ </thead> <tbody> <row> + <entry> <command>VIRTUALHOSTNODE</command> </entry> + <entry> <para>A virtualhostnode or remote replication node</para> </entry> + <entry><para>ALL, CREATE, UPDATE, DELETE</para> </entry> + <entry><para>name</para> </entry> + </row> + <row> <entry> <command>VIRTUALHOST</command> </entry> <entry> <para>A virtualhost</para> </entry> - <entry><para>ALL, ACCESS</para> </entry> + <entry><para>ALL, CREATE, UPDATE, DELETE, ACCESS</para> </entry> <entry><para>name</para> </entry> </row> <row> @@ -593,11 +599,17 @@ ACL DENY-LOG all all <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 +# Broker, 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 +# create/update/delete on virtualhost node and children +ACL ALLOW-LOG webadmins CREATE VIRTUALHOSTNODE +ACL ALLOW-LOG webadmins UPDATE VIRTUALHOSTNODE +ACL ALLOW-LOG webadmins DELETE VIRTUALHOSTNODE +ACL ALLOW-LOG webadmins CREATE VIRTUALHOST +ACL ALLOW-LOG webadmins UPDATE VIRTUALHOST +ACL ALLOW-LOG webadmins DELETE VIRTUALHOST ACL ALLOW-LOG webadmins CREATE QUEUE ACL ALLOW-LOG webadmins UPDATE QUEUE ACL ALLOW-LOG webadmins DELETE QUEUE 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=1629579&r1=1629578&r2=1629579&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 Mon Oct 6 06:56:59 2014 @@ -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> - 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> + <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> + + <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> - 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> 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> 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> - <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> + <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="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 # <user name>: <user password> 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> - Copied: qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml (from r1629242, qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml) URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml?p2=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml&p1=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml&r1=1629242&r2=1629579&rev=1629579&view=diff ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml (original) +++ qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml Mon Oct 6 06:56:59 2014 @@ -1,4 +1,5 @@ <?xml version="1.0" encoding="utf-8"?> + <!-- Licensed to the Apache Software Foundation (ASF) under one @@ -20,7 +21,12 @@ --> -<section id="Java-Broker-Configuring-And-Managing-Other-Tooling"> -<title>Other Tooling</title> +<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> </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=1629579&r1=1629578&r2=1629579&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 Mon Oct 6 06:56:59 2014 @@ -29,8 +29,8 @@ 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 <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> 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=1629579&r1=1629578&r2=1629579&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 Mon Oct 6 06:56:59 2014 @@ -22,8 +22,8 @@ <chapter id="Java-Broker-Security"> <title>Security</title> - <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"/> + <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-Configuration-Encryption.xml"/> </chapter> Copied: qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml (from r1629242, qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Authentication-Providers.xml) URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml?p2=qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml&p1=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Authentication-Providers.xml&r1=1629242&r2=1629579&rev=1629579&view=diff ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Authentication-Providers.xml (original) +++ qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml Mon Oct 6 06:56:59 2014 @@ -23,7 +23,7 @@ <section id="Java-Broker-Concepts-Authentication-Providers"> <title>Authentication Providers</title> <para> - <emphasis>Authentication Providers</emphasis> are used to authenticate connections to <emphasis>Ports</emphasis>. + <emphasis>Authentication Providers</emphasis> are used by <emphasis>Ports</emphasis> to authenticate connections. 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> Added: qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml?rev=1629579&view=auto ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml (added) +++ qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml Mon Oct 6 06:56:59 2014 @@ -0,0 +1,63 @@ +<?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-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> +</section> Copied: qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Exchanges.xml (from r1629242, qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml) URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Exchanges.xml?p2=qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Exchanges.xml&p1=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml&r1=1629242&r2=1629579&rev=1629579&view=diff ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml (original) +++ qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Exchanges.xml Mon Oct 6 06:56:59 2014 @@ -22,8 +22,8 @@ <section id="Java-Broker-Concepts-Exchanges"> <title>Exchanges</title> - <para>An <emphasis>Exchange</emphasis> is a named entity within the <emphasis>Virtual Host</emphasis> which receives - messages from producers and routes them to matching <emphasis>Queue</emphasis>s within the <emphasis>Virtual Host</emphasis>.</para> + <para>An <emphasis>Exchange</emphasis> is a named entity within the <emphasis>Virtualhost</emphasis> which receives + messages from producers and routes them to matching <emphasis>Queue</emphasis>s within the <emphasis>Virtualhost</emphasis>.</para> <para>The server provides a set of exchange types with each exchange type implementing a different routing algorithm. For details of how these exchanges types work see <xref linkend="Java-Broker-Concepts-Exchanges-Types"/> below.</para> <para>The server predeclares a number of exchange instances with names starting with "<literal>amq.</literal>". These are defined in @@ -31,15 +31,14 @@ <para>Applications can make use the pre-declared exchanges, or they may declare their own. The number of exchanges within a virtual host is limited only by resource constraints.</para> <para>The behaviour when an exchange is unable to route a message to any queue is defined in <xref linkend="Java-Broker-Concepts-Exchanges-UnroutableMessage"/></para> - <para>Exchange configuration is covered in <xref linkend="Java-Broker-Exchanges"/>.</para> <section id="Java-Broker-Concepts-Exchanges-Predeclared"> <title>Predeclared Exchanges</title> <para>Each virtual host pre-declares the following exchanges: <itemizedlist> - <listitem>amq.direct (an instance of a direct exchange)</listitem> - <listitem>amq.topic (an instance of a topic exchange)</listitem> - <listitem>amq.fanout (an instance of a fanout exchange)</listitem> - <listitem>amq.match (an instance of a headers exchange)</listitem> + <listitem><para>amq.direct (an instance of a direct exchange)</para></listitem> + <listitem><para>amq.topic (an instance of a topic exchange)</para></listitem> + <listitem><para>amq.fanout (an instance of a fanout exchange)</para></listitem> + <listitem><para>amq.match (an instance of a headers exchange)</para></listitem> </itemizedlist> </para> <para>The conceptual "<literal>default exchange</literal>" always exists, effectively a special instance of @@ -53,10 +52,10 @@ <para> The following Exchange types are supported. <itemizedlist> - <listitem>Direct</listitem> - <listitem>Topic</listitem> - <listitem>Fanout</listitem> - <listitem>Headers</listitem> + <listitem><para>Direct</para></listitem> + <listitem><para>Topic</para></listitem> + <listitem><para>Fanout</para></listitem> + <listitem><para>Headers</para></listitem> </itemizedlist> These exchange types are described in the following sub-sections.</para> @@ -179,10 +178,10 @@ <para>The binding argument <literal>x-match</literal> is understood by exchange type headers. It can take two values, dictating how the rest of the name value pairs are treated during matching.</para> <itemizedlist> - <listitem><literal>all</literal> implies that all the other pairs must match the headers property of a message for that message to be routed - (i.e. an AND match)</listitem> - <listitem><literal>any</literal> implies that the message should be routed if any of the fields in the headers property match one of the - fields in the arguments table (i.e. an OR match)</listitem> + <listitem><para><literal>all</literal> implies that all the other pairs must match the headers property of a message for that message to be routed + (i.e. an AND match)</para></listitem> + <listitem><para><literal>any</literal> implies that the message should be routed if any of the fields in the headers property match one of the + fields in the arguments table (i.e. an OR match)</para></listitem> </itemizedlist> <para>A field in the bind arguments matches a field in the message if either the field in the bind arguments has no value and a field of the same name is present in the message headers or if the field in the bind arguments has a value and a field of the same name exists in the @@ -193,12 +192,12 @@ <title>Unrouteable Messages</title> <para>If an exchange is unable to route a message to any queues, the Broker will: <itemizedlist> - <listitem>If using AMQP 0-10 protocol, and an alternate exchange has been set on the exchange, the message is routed to the alternate exchange. + <listitem><para>If using AMQP 0-10 protocol, and an alternate exchange has been set on the exchange, the message is routed to the alternate exchange. The alternate exchange routes the message according to its routing algorithm and its binding table. If the messages is still unroutable, - the message is discarded.</listitem> - <listitem>If using AMQP protocols 0-8..0-9-1, and the publisher set the mandatory flag and the<link linkend="Java-Broker-Close-Connection-When-No-Route"> - close when no route</link> feature did not close the connection, the message is returned to the Producer.</listitem> - <listitem>Otherwise, the message is discarded.</listitem> + the message is discarded.</para></listitem> + <listitem><para>If using AMQP protocols 0-8..0-9-1, and the publisher set the mandatory flag and the<link linkend="Java-Broker-Close-Connection-When-No-Route"> + close when no route</link> feature did not close the connection, the message is returned to the Producer.</para></listitem> + <listitem><para>Otherwise, the message is discarded.</para></listitem> </itemizedlist> </para> </section> Copied: qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Other-Services.xml (from r1629242, qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Other-Services.xml) URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Other-Services.xml?p2=qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Other-Services.xml&p1=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Other-Services.xml&r1=1629242&r2=1629579&rev=1629579&view=diff ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Other-Services.xml (original) +++ qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Other-Services.xml Mon Oct 6 06:56:59 2014 @@ -44,7 +44,7 @@ <title>Keystores</title> <para><emphasis>Keystores</emphasis> are used to configure details of keystores holding SSL keys and certificates for the SSL transports on Ports.</para> - <para>Keystore configuration and management is covered in <xref linkend="Java-Broker-SSL-Keystore"/>.</para> + <para>Keystore configuration and management is covered in <xref linkend="Java-Broker-Management-Managing-Keystores"/>.</para> </section> <section id="Java-Broker-Concepts-Truststores"> @@ -52,7 +52,7 @@ <para><emphasis>Truststores </emphasis> are used to configure details of keystores holding SSL certificates for trusting Client Certificate on SSL ports. </para> - <para>Truststore configuration and management is covered in <xref linkend="SSL-Truststore-ClientCertificate"/>.</para> + <para>Truststore configuration and management is covered in <xref linkend="Java-Broker-Management-Managing-Truststores"/>.</para> </section> </section> Copied: qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml (from r1629242, qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Ports.xml) URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml?p2=qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml&p1=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Ports.xml&r1=1629242&r2=1629579&rev=1629579&view=diff ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Ports.xml (original) +++ qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml Mon Oct 6 06:56:59 2014 @@ -45,6 +45,4 @@ <para> Addittionally, HTTP and JMX ports can be configured for use by the associated management plugins. </para> - - <para>Configuration details for the Ports are covered in <xref linkend="Java-Broker-Ports"/>.</para> </section> Copied: qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml (from r1629242, qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing.xml) URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml?p2=qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml&p1=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing.xml&r1=1629242&r2=1629579&rev=1629579&view=diff ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing.xml (original) +++ qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml Mon Oct 6 06:56:59 2014 @@ -20,10 +20,11 @@ --> -<chapter id="Java-Broker-Configuring-And-Managing"> - <title>Configuring And Managing</title> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="Java-Broker-Configuring-And-Managing-Config-Files.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="Java-Broker-Configuring-And-Managing-Web-Management.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="Java-Broker-Configuring-And-Managing-JMX.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="Java-Broker-Configuring-And-Managing-Other-Tooling.xml"/> -</chapter> +<section id="Java-Broker-Concepts-Queues"> + <title>Queues</title> + <para><emphasis>Queue</emphasis>s are named entities within a <link linkend="Java-Broker-Concepts-Virtualhosts">Virtualhost</link> that + hold/buffer messages for later delivery to consumer applications. An <link + linkend="Java-Broker-Concepts-Exchanges">Exchange</link> for passing messages to a queue. + Consumers subscribe to a queue in order to receive messages for it. </para> + <para>The Broker supports different queue types, each with different delivery semantics. It also also messages on a queue to be treated as a group.</para> +</section> Copied: qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-RemoteReplicationNodes.xml (from r1629242, qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml) URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-RemoteReplicationNodes.xml?p2=qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-RemoteReplicationNodes.xml&p1=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml&r1=1629242&r2=1629579&rev=1629579&view=diff ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml (original) +++ qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-RemoteReplicationNodes.xml Mon Oct 6 06:56:59 2014 @@ -20,7 +20,8 @@ --> -<section id="Java-Broker-Configuring-And-Managing-Other-Tooling"> -<title>Other Tooling</title> - +<section id="Java-Broker-Concepts-RemoteReplicationNodes"> + <title>Remote Replication Nodes</title> + <para>Used for HA only. A <emphasis>remote replication node</emphasis> is a representation of + another virtualhost node in the group.</para> </section> Added: qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml?rev=1629579&view=auto ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml (added) +++ qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml Mon Oct 6 06:56:59 2014 @@ -0,0 +1,37 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +--> + +<section id="Java-Broker-Concepts-Virtualhost-Nodes"> + <title>Virtualhost Nodes</title> + <para>A <emphasis>virtualhost node</emphasis> is a container for the virtualhost. It has exactly + one virtualhost.</para> + <para>A <emphasis>virtualhost node</emphasis> is backed by storage. This storage is used to record + the durable entities that exist beneath the virtualhost node (the virtualhost, queues, exchanges + etc).</para> + <para>When HA is in used, it is the virtualhost nodes of many Brokers that come together to form + the group. The virtualhost nodes together elect a master. When the high availability feature is + in use, the virtualhost node has <link linkend="Java-Broker-Concepts-RemoteReplicationNodes" + >remote replications nodes</link>. There is a remote replication node corresponding to each + remote virtualhost node that form part of the group.</para> + + +</section> Added: qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml?rev=1629579&view=auto ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml (added) +++ qpid/trunk/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml Mon Oct 6 06:56:59 2014 @@ -0,0 +1,60 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +--> + +<section id="Java-Broker-Concepts-Virtualhosts"> + <title>Virtualhosts</title> + <para>A virtualhost is a namespace in which messaging is performed. Virtualhosts are independent; + the messaging goes on a within a virtualhost is independent of any messaging that goes on in + another virtualhost. For instance, a queue named <emphasis>foo</emphasis> defined in one + virtualhost is completely independent of a queue named <emphasis>foo</emphasis> in another + virtualhost.</para> + <para>A virtualhost is identified by a name which must be unique broker-wide. Clients use the name + to identify the virtualhost to which they wish to connect when they connect.</para> + <para>A virtualhost exists in a container called a virtualhost node.</para> + <para>The virtualhost 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><emphasis>Exchanges</emphasis> is a named entity within the Virtual Host which receives + messages from producers and routes them to matching Queues.</para> + <para><emphasis>Queues</emphasis> are named entities that hold messages for delivery to consumer + applications.</para> + <para><emphasis>Bindings</emphasis> are relationships between Exchanges and Queue that facilitate + routing of messages from the Exchange to the Queue.</para> + <para><emphasis>Connections</emphasis> represent a live connection to the virtualhost from a + messaging client.</para> + <para>A <emphasis>Session</emphasis> represents a context for the production or consumption of + messages. Connection support many Sessions.</para> + <para>A <emphasis>Consumer</emphasis> represents a live consumer that is attached to queue.</para> + <para> The following diagram depicts the Virtualhost model: <figure> + <title>Virtualhost Model</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/VirtualHost-Model.png" format="PNG" scalefit="1"/> + </imageobject> + <textobject> + <phrase>Virtual Host Model</phrase> + </textobject> + </mediaobject> + </figure> + </para> + <para>A <emphasis>virtualhost</emphasis> is backed by storage which is used to store the messages.</para> +</section> Modified: qpid/trunk/qpid/doc/book/src/java-broker/images/Broker-Model.png URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/images/Broker-Model.png?rev=1629579&r1=1629578&r2=1629579&view=diff ============================================================================== Files qpid/trunk/qpid/doc/book/src/java-broker/images/Broker-Model.png (original) and qpid/trunk/qpid/doc/book/src/java-broker/images/Broker-Model.png Mon Oct 6 06:56:59 2014 differ Added: qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Auth.png URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Auth.png?rev=1629579&view=auto ============================================================================== Files qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Auth.png (added) and qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Auth.png Mon Oct 6 06:56:59 2014 differ Modified: qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Console.png URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Console.png?rev=1629579&r1=1629578&r2=1629579&view=diff ============================================================================== Files qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Console.png (original) and qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Console.png Mon Oct 6 06:56:59 2014 differ Added: qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Tab.png URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Tab.png?rev=1629579&view=auto ============================================================================== Files qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Tab.png (added) and qpid/trunk/qpid/doc/book/src/java-broker/images/Management-Web-Tab.png Mon Oct 6 06:56:59 2014 differ Modified: qpid/trunk/qpid/doc/book/src/java-broker/images/VirtualHost-Model.png URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/images/VirtualHost-Model.png?rev=1629579&r1=1629578&r2=1629579&view=diff ============================================================================== Files qpid/trunk/qpid/doc/book/src/java-broker/images/VirtualHost-Model.png (original) and qpid/trunk/qpid/doc/book/src/java-broker/images/VirtualHost-Model.png Mon Oct 6 06:56:59 2014 differ Copied: qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-AMQP-Intrinsic.xml (from r1629242, qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml) URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-AMQP-Intrinsic.xml?p2=qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-AMQP-Intrinsic.xml&p1=qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml&r1=1629242&r2=1629579&rev=1629579&view=diff ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml (original) +++ qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-AMQP-Intrinsic.xml Mon Oct 6 06:56:59 2014 @@ -20,7 +20,10 @@ --> -<section id="Java-Broker-Configuring-And-Managing-Other-Tooling"> -<title>Other Tooling</title> - +<section id="Java-Broker-Management-Channel-AMQP-Intrinstic"> + <title>AMQP Intrinstic Management</title> + <para>The AMQP protocols 0-8..0-10 allow for creation, deletion and query of Exchanges, Queue + and Bindings.</para> + <para>The exact details of how to utilise this commands depends of the client. See the + documentation accompanying the client for details.</para> </section> Added: qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-HTTP.xml URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-HTTP.xml?rev=1629579&view=auto ============================================================================== --- qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-HTTP.xml (added) +++ qpid/trunk/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-HTTP.xml Mon Oct 6 06:56:59 2014 @@ -0,0 +1,58 @@ +<?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-Management-Channel-HTTP"> + <title>HTTP Management</title> + + <section id="Java-Broker-Management-Channel-HTTP-Introduction"> + <title>Introduction</title> + <para>The HTTP Management plugin provides a HTTP based API for monitoring and control of the + Broker. The plugin actually provides two interfaces:</para> + + <para><itemizedlist> + <listitem> + <para><link linkend="Java-Broker-Management-Channel-Web-Console">Web Management + Console</link> - rich web based interface for the management of the + Broker.</para> + </listitem> + <listitem> + <para><link linkend="Java-Broker-Management-Channel-REST-API">REST API</link> - + REST API providing complete programatic management of the Broker.</para> + </listitem> + </itemizedlist></para> + + <para>The Web Management Console itself uses the REST API, so every function you can perform + through the Web Management Console can be also be scripted and intergrated into other + systems. This provides a simple integration point allowing the Broker to monitored and + controled from systems such as Naoios or BMC Control-M.</para> + </section> + + <section id="Java-Broker-Management-Channel-HTTP-DefaultConfiguration"> + <title>Default Configuration</title> + <para>By default, the Broker is shipped with HTTP enabled running port 8080. The HTTP plugin + is configured to require SASL authentication. The port is not SSL protected.</para> + <!-- TODO describe what to do if the port conflicts --> + <para>The settings can be changed by configuring the HTTP plugin and/or the port configured + to serve HTTP.</para> + </section> + +</section> --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org
