diff options
| author | Robert Gemmell <robbie@apache.org> | 2013-05-20 11:35:52 +0000 |
|---|---|---|
| committer | Robert Gemmell <robbie@apache.org> | 2013-05-20 11:35:52 +0000 |
| commit | 997c7889204ad680af0721e514aeb05ff595ba06 (patch) | |
| tree | 7d743a355beff0c8b28270e397929832d80f4d33 | |
| parent | 15c153786db8646645a4d31dd43260e3a018dff9 (diff) | |
| download | qpid-python-997c7889204ad680af0721e514aeb05ff595ba06.tar.gz | |
QPID-4685: additional documentation updates following broker configuration model changes
merged from trunk r1484370
git-svn-id: https://svn.apache.org/repos/asf/qpid/branches/0.22@1484436 13f79535-47bb-0310-9956-ffa450edef68
21 files changed, 613 insertions, 372 deletions
diff --git a/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml b/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml index 9f5872926c..2beb77d965 100644 --- a/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml +++ b/qpid/doc/book/src/java-broker/AMQP-Messaging-Broker-Java-Book.xml @@ -36,6 +36,7 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Security.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Runtime.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-High-Availability.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Virtual-Hosts-Configuration.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Miscellaneous.xml"/> </book> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Authentication-Providers.xml index 706df1f4a7..dd7c291c77 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Authentication-Providers.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Authentication-Providers.xml @@ -21,32 +21,33 @@ --> <section id="Java-Broker-Concepts-Authentication-Providers"> -<title>Authentication Providers</title> -<para><emphasis>Authentication Providers</emphasis> authenticate AMQP and non-AMQP connections on Broker <emphasis>Ports</emphasis>. -Multiple <emphasis>Authentication Providers</emphasis> can be configured on the Broker at the same time, -however, only one can be assigned to the concrete Port.</para> -<para> - The following authentication providers are implemented and supported: - <itemizedlist> - <listitem><para><link linkend= "Java-Broker-Security-Anonymous-Provider">Anonymous</link> - allows anonymous connections to the broker</para></listitem> - <listitem><para><link linkend= "Java-Broker-Security-External-Provider">External</link> - delegates authentication to the external authentication mechanisms like Client Certificate Authentication etc</para></listitem> - <listitem><para><link linkend= "Java-Broker-Security-Kerberos-Provider">Kerberos</link> - uses GSS-API SASL mechanism to authenticate connections</para></listitem> - <listitem><para><link linkend= "Java-Broker-Security-LDAP-Provider">SimpleLDAP</link> - authenticate users against LDAP server.</para></listitem> - <listitem><para><link linkend= "Java-Broker-Security-PlainPasswordFile-Provider">PlainPasswordFile</link> - authenticate users against credentials stored in local file.</para></listitem> - <listitem><para><link linkend= "Java-Broker-Security-Base64MD5PasswordFile-Provider">Base64MD5PasswordFile</link> - similar to the above but the password credentials are encoded and different SASL mechanisms are used for authentication.</para></listitem> - </itemizedlist> -</para> -<para><emphasis>Authentication Providers</emphasis> can be split into two categories: - <itemizedlist> - <listitem><para><emphasis>User managing providers</emphasis> allowing to add/delete credentials using Broker management interfaces.</para></listitem> - <listitem><para><emphasis>User non-managing providers</emphasis> using externally stored credentials for authentication.</para></listitem> - </itemizedlist> -</para> -<para>The configuration details for Authentication Providers are covered in <xref linkend= "Java-Broker-Security-Authentication-Providers"/>.</para> + <title>Authentication Providers</title> + <para> + <emphasis>Authentication Providers</emphasis> are used to authenticate connections to <emphasis>Ports</emphasis>. + 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> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml index 47c7b72b4d..1692fdc038 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml @@ -22,23 +22,30 @@ <section id="Java-Broker-Concepts-Exchanges"> <title>Exchanges</title> -<para><emphasis>Exchange</emphasis> is the named entity within the <emphasis>Virtual Host</emphasis> which receives messages from producer applications and -optionally routes them to message queues within the <emphasis>Virtual Host</emphasis>. The message routing occurs based on exchange routing algorithm -and queue <emphasis>Bindings</emphasis>.</para> +<para>An <emphasis>Exchange</emphasis> is a named entity within the <emphasis>Virtual Host</emphasis> which receives +messages from producers and routes them to matching message <emphasis>Queue</emphasis>s within the <emphasis>Virtual Host</emphasis>. +Message routing occurs based on the particular Exchange's routing algorithm and its configured queue <emphasis>Binding</emphasis>s.</para> <para> -The following <emphasis>Exchanges</emphasis> are implemented and supported by the <emphasis>Broker</emphasis>: +The following <emphasis>Exchange</emphasis> types are supported by the <emphasis>Broker</emphasis>: <itemizedlist> - <listitem><para><emphasis>Direct Exchange</emphasis> provides routing of messages to zero or more queues based on an exact match between -the routing key of the message, and the binding key used to bind the queue to the exchange + <listitem><para><emphasis>Direct</emphasis>: routes messages to queues based on an exact match between + the routing key of the message, and the binding key used to bind the queue to the exchange </para></listitem> - <listitem><para><emphasis>Topic Exchange</emphasis> provides routing to bound queues based on a pattern match between the binding key and the -routing key of the message. This exchange type is used to support the classic publish/subscribe paradigm using a topic namespace as the -addressing model to select and deliver messages across multiple consumers based on a partial or full match on a topic pattern. + <listitem><para><emphasis>Topic</emphasis>: routes messages to queues based on heirarchical pattern matching between the routing + key for each message and the binding keys used to bind Queues to the Exchange. This exchange type is used to support the classic + publish/subscribe paradigm using a topic namespace as the addressing model to select and deliver messages across multiple + consumers based on a partial or full match on a topic pattern. + </para> + <para> + Binding and routing keys for this Exchange use a "." deliminator to seperate words representing different levels of the heirarchy, + with special meaning given to use of * and # as a word within a binding key such that a * matches any single word in a routing + key and # matches zero or more words, allowing a binding key to match many routing keys for published messages. For example, + a binding key of <emphasis>a.b.#</emphasis> would match the routing keys <emphasis>a.b</emphasis>, <emphasis>a.b.c</emphasis>, and + <emphasis>a.b.c.d</emphasis>, but not the routing key <emphasis>a.z</emphasis>.</para></listitem> + <listitem><para><emphasis>Fanout</emphasis>: routes messages to all queues bound to the exchange, regardless of the message's routing key. </para></listitem> - <listitem><para><emphasis>Fanout Exchange</emphasis> provides routing of messages to all bound queues regardless of the message's routing key. - </para></listitem> - <listitem><para><emphasis>Headers Exchange</emphasis> provides routing based on header properties within the AMQP message. - The message is passed to the queue if the headers property matches the arguments with which the queue was bound. + <listitem><para><emphasis>Headers</emphasis>: routes messages to queues based on header properties within the AMQP message. + The message is passed to a queue if the header properties of the message satisfy header matching arguments table with which the queue was bound. </para></listitem> </itemizedlist> </para> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Other-Services.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Other-Services.xml index df1600273b..d0368329b6 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Other-Services.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Other-Services.xml @@ -22,34 +22,37 @@ <section id="Java-Broker-Concepts-Other-Services"> <title>Other Services</title> -<para>The Broker can also contain Access Control Providers, Group Providers, Keystore, Trustores and Management Plugins.</para> + <para> + The Broker can also have <emphasis>Access Control Providers</emphasis>, <emphasis>Group Providers</emphasis>, + <emphasis>Keystores</emphasis>, <emphasis>Trustores</emphasis> and [Management] <emphasis>Plugins</emphasis> configured. + </para> <section id="Java-Broker-Concepts-Access-Control-Providers"> <title>Access Control Providers</title> - <para><emphasis>Access Control Providers</emphasis> are used to authorize the access to the various Broker objects.</para> - <para>The ACL configuration and management details are covered in <xref linkend="Java-Broker-Security-ACLs"/>.</para> + <para><emphasis>Access Control Providers</emphasis> are used to authorize various operations relating to Broker objects.</para> + <para>Access Control Provider configuration and management details are covered in <xref linkend="Java-Broker-Security-ACLs"/>.</para> </section> <section id="Java-Broker-Concepts-Group-Providers"> <title>Group Providers</title> - <para><emphasis>Group Providers</emphasis> are used to aggregate Broker authenticated principals into groups - which can be used to define ACL rules applicable to the whole group.</para> - <para>The Group Provider configuration and management is covered in <xref linkend="Java-Broker-Security-Group-Providers"/>.</para> + <para><emphasis>Group Providers</emphasis> are used to aggregate authenticated user principals into groups + which can be then be used in Access Control rules applicable to the whole group.</para> + <para>Group Provider configuration and management is covered in <xref linkend="Java-Broker-Security-Group-Providers"/>.</para> </section> - <section id="Java-Broker-Keystore-Providers"> + <section id="Java-Broker-Concepts-Keystores"> <title>Keystores</title> - <para><emphasis>Keystore</emphasis> are used to configure keystores holding SSL keys and certificates + <para><emphasis>Keystores</emphasis> are used to configure details of keystores holding SSL keys and certificates for the SSL transports on Ports.</para> - <para>The Keystore configuration and management is covered in <xref linkend="Java-Broker-SSL-Keystore"/>.</para> + <para>Keystore configuration and management is covered in <xref linkend="Java-Broker-SSL-Keystore"/>.</para> </section> - <section id="Java-Broker-Truststore-Providers"> + <section id="Java-Broker-Concepts-Truststores"> <title>Truststores</title> - <para><emphasis>Truststore </emphasis> are used to configure keystores holding SSL certificates - for Client Certificate Authentication on SSL ports. + <para><emphasis>Truststores </emphasis> are used to configure details of keystores holding SSL certificates + for trusting Client Certificate on SSL ports. </para> - <para>The Truststore configuration and management is covered in <xref linkend="SSL-Truststore-ClientCertificate"/>.</para> + <para>Truststore configuration and management is covered in <xref linkend="SSL-Truststore-ClientCertificate"/>.</para> </section> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Ports.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Ports.xml index d3ef268f52..027e3a1697 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Ports.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Ports.xml @@ -22,29 +22,29 @@ <section id="Java-Broker-Concepts-Ports"> <title>Ports</title> -<para><emphasis>Port</emphasis> is a named broker entity serving as a communications end-point -and providing the AMQP transport layer over the given TCP port. The particular AMQP protocols can be configured on the Port. -As result, different <emphasis>Ports</emphasis> can support different protocols. Any number of <emphasis>Ports</emphasis> -can be configured on the Broker.</para> -<para> - The following AMQP protocols are currently supported by the Broker: - <itemizedlist> - <listitem><para><emphasis>AMQP 0.8</emphasis></para></listitem> - <listitem><para><emphasis>AMQP 0.9</emphasis></para></listitem> - <listitem><para><emphasis>AMQP 0.9.1</emphasis></para></listitem> - <listitem><para><emphasis>AMQP 0.10</emphasis></para></listitem> - <listitem><para><emphasis>AMQP 1.0</emphasis></para></listitem> - </itemizedlist> -</para> -<para>Ports are also responsible for the authentication of all incoming connections -by mean of <emphasis>Authentication Provider</emphasis> configured on the Port. -Each Port can have its own <emphasis>Authentication Provider</emphasis>.</para> - -<para>Both TCP and SSL transports are supported and can be configured on the <emphasis>Ports</emphasis>. -AMQP ports also support Client Certificate Authentication.</para> - -<para>Besides AMQP ports HTTP and JMX ports can be configured for use by management plugins. -They can be configured by specifying HTTP and RMI/JMX_RMI protocols respectively.</para> - -<para>Configuration details for the Ports are covered in <xref linkend="Java-Broker-Ports"/>.</para> + <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> + <listitem><para><emphasis>AMQP 0-10</emphasis></para></listitem> + <listitem><para><emphasis>AMQP 1.0</emphasis></para></listitem> + </itemizedlist> + </para> + + <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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Queues.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Queues.xml index ae6ea04269..ea9f7d8fae 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Queues.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Queues.xml @@ -22,17 +22,13 @@ <section id="Java-Broker-Concepts-Queues"> <title>Queues</title> -<para>Message queues are named entities that store messages in memory or on the disk and deliver them in sequence -to connected consumer applications.</para> -<para>The queues are hosted by the <link linkend="Java-Broker-Concepts-Virtual-Hosts">Virtual Hosts</link>. -Any number of queues can be created on <emphasis>Virtual Host</emphasis>.</para> -<para>The following types of Queues are currently supported: +<para><emphasis>Queue</emphasis>s are named entities within a <emphasis>Virtual Host</emphasis> that hold/buffer messages for delivery to consumer applications.</para> +<para>Different types of <emphasis>Queue</emphasis> have different delivery semantics. The following Queues types are currently supported: <itemizedlist> - <listitem><para><link linkend="Java-Broker-Queues">Simple</link> is a simple FIFO queue</para></listitem> - <listitem><para><link linkend="Java-Broker-Queues-OtherTypes-Priority">Priority</link> where messages delivery order depends from the message priority</para></listitem> - <listitem><para><link linkend="Java-Broker-Queues-OtherTypes-Sorted">Sorted</link> where messages delivery order depends from the message sorting key value</para></listitem> - <listitem><para><link linkend="Java-Broker-Queues-OtherTypes-LVQ">Last Value Queue</link> automatically discards older message when - a newer message arrives with the same key value</para></listitem> + <listitem><para><link linkend="Java-Broker-Queues">Standard</link>: a simple First-In-First-Out (FIFO) queue</para></listitem> + <listitem><para><link linkend="Java-Broker-Queues-OtherTypes-Priority">Priority</link>: delivery order depends on the priority of each message</para></listitem> + <listitem><para><link linkend="Java-Broker-Queues-OtherTypes-Sorted">Sorted</link>: delivery order depends on the value of the sorting key property in each message</para></listitem> + <listitem><para><link linkend="Java-Broker-Queues-OtherTypes-LVQ">Last Value Queue</link>: also known as an LVQ, retains only the last (newest) message received with a given LVQ key value.</para></listitem> </itemizedlist> </para> <para>Queue configuration details are covered in <xref linkend="Java-Broker-Queues"/>.</para> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Virtual-Hosts.xml b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Virtual-Hosts.xml index bf9367bf15..6f5f1f38ba 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Virtual-Hosts.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Virtual-Hosts.xml @@ -22,9 +22,10 @@ <section id="Java-Broker-Concepts-Virtual-Hosts"> <title>Virtual Hosts</title> -<para>Broker comprises from one or many <emphasis>Virtual Hosts</emphasis>. -<emphasis>Virtual Host</emphasis> can be defined as a collection of exchanges, message queues and associated objects and -is an independent server domain that share a common authentication, encryption and transport environment. +<para>A Broker has one or more <emphasis>Virtual Host</emphasis>s. Each <emphasis>Virtual Host</emphasis> +has an independant namespace for its collection of <emphasis>Exchanges</emphasis>, <emphasis>Queues</emphasis>, +and associated objects. Client <emphasis>Connection</emphasis>s are made a specific <emphasis>Virtual Host</emphasis>, +with one being configured as the default for clients that can't or don't specify which they wish to connect to. </para> <para> The following diagram depicts the Virtual Host model: @@ -40,9 +41,9 @@ is an independent server domain that share a common authentication, encryption a </mediaobject> </figure> </para> -<para>Each <emphasis>Virtual Host</emphasis> has its own <emphasis>Message Store</emphasis> -which is used to store the persistent messages from all <link linkend="Java-Broker-Concepts-Queues">Queues</link> -declared on the <emphasis>Virtual Host</emphasis>.</para> +<para>Each <emphasis>Virtual Host</emphasis> has its own <emphasis>Message Store</emphasis> which is used to store persistent +messages on durable <emphasis>Queues</emphasis> it contains, as well as the configuration of any durable +<emphasis>Queues</emphasis>, <emphasis>Exchanges</emphasis>, and <emphasis>Bindings</emphasis> made during its operation.</para> <para> The following message stores are currently supported: <itemizedlist> 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 0ebf6124a0..2981add7fb 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts.xml @@ -25,13 +25,13 @@ <section id="Java-Broker-Concepts-Broker"> <title>Broker</title> - <para>The Qpid Broker can be defined as a collection of <emphasis>Virtual Hosts</emphasis> (independent containers of <emphasis>Queues</emphasis>, - <emphasis>Exchanges</emphasis>, etc) sharing the same authentication model provided by the broker <emphasis>Authentication Providers</emphasis> - and the transport model defined as <emphasis>Port</emphasis> configured objects. The authorization model is either provided by the broker - <emphasis>Access Control Providers</emphasis> or <emphasis>Access Control List</emphasis> defined on the <emphasis>Virtual Hosts</emphasis>. - The Broker also provides the management plugins to manage and configure Broker's and Virtual Hosts' configured objects. - Additionally, <emphasis>Keystores</emphasis> and <emphasis>Truststores</emphasis> can be defined on the broker level to configure Port SSL transports. - The <emphasis>Group Providers</emphasis> can be configured to use groups with <emphasis>ACL Providers</emphasis>. + <para> + The Qpid Broker has one or more <emphasis>Virtual Hosts</emphasis> (independent containers of <emphasis>Queues</emphasis>, + <emphasis>Exchanges</emphasis>, etc) sharing a connection, authentication, and access control model via the configured + <emphasis>Ports</emphasis>, <emphasis>Authentication Providers</emphasis>, <emphasis>Group providers</emphasis> and + <emphasis>Access Control Providers</emphasis>. <emphasis>Keystores</emphasis> and <emphasis>Truststores</emphasis> can + be defined on the broker level and linked to <emphasis>Ports</emphasis> configured with an SSL transport. The Broker + also provides management plugins to allow configuring and monitoring it. </para> <para> The following diagram depicts the Broker model: @@ -46,6 +46,7 @@ </textobject> </mediaobject> </figure> + These concepts will be expanded upon in the forthcoming pages. </para> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Config-Files.xml b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Config-Files.xml index a184fea671..8dfb8de5c1 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Config-Files.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Config-Files.xml @@ -20,91 +20,288 @@ --> -<section id="Java-Broker-Configuring-And-Managing-Config-Files"> -<title>Broker Configuration</title> +<section id="Java-Broker-Configuring-And-Managing-Configuration-Store"> +<title>Broker Configuration Store</title> + <section id="Java-Broker-Configuring-And-Managing-Configuration-Store-Introduction"> + <title>Introduction</title> + <para> + The Broker supports configuration of all its primary components via its HTTP management interface, using + the <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>. + </para> + <para> + The configuration for each component is stored as an entry in the broker configuration store, currently implemented as either a JSON file + which persists changes to disk, or an in-memory store which does not. + The following components configuration is stored there: + <itemizedlist> + <listitem><para>Broker</para></listitem> + <listitem><para>Virtual Host</para></listitem> + <listitem><para>Port</para></listitem> + <listitem><para>Authentication Provider</para></listitem> + <listitem><para>Access Control Provider</para></listitem> + <listitem><para>Group Provider</para></listitem> + <listitem><para>Key store</para></listitem> + <listitem><para>Trust store</para></listitem> + <listitem><para>Plugin</para></listitem> + </itemizedlist> + </para> - <para>This section provides the details about broker configuration store.</para> + <para> + Broker startup involves two configuration related items, the 'Initial Configuration' and the Configuration Store. When the broker is started, + if a Configuration Store does not exist at the current <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Location">store location</link> + then one will be initialised with the current <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Initial-Config-Location">'Initial Configuration'</link>. + Unless otherwise requested to <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Location">overwrite the configuration store</link> then + subsequent broker restarts will use the existing configuration store and ignore the contents of the 'Initial Configuration'. + </para> + </section> - <section id="Java-Broker-Configuring-And-Managing-Configuration-Store-Introduction"> - <title>Configuration store</title> - <para>The Broker has a configuration store and provides management interfaces to manage the broker components. - The configuration for each broker component is stored in the store as a configuration entry. - The following configuration entries can be stored there: - <itemizedlist> - <listitem><para>Broker</para></listitem> - <listitem><para>Port</para></listitem> - <listitem><para>Authentication Provider</para></listitem> - <listitem><para>Virtual Host</para></listitem> - <listitem><para>Access Control Provider</para></listitem> - <listitem><para>Group Provider</para></listitem> - <listitem><para>Key store</para></listitem> - <listitem><para>Trust store</para></listitem> - <listitem><para>Plugin</para></listitem> - </itemizedlist> - </para> - <para>When broker is started for a first time a configuration store is created automatically from - the internal initial configuration. The created broker configuration is placed into broker working folder - if the broker configuration store location is not specified.</para> - <para>The predefined initial configuration can be overridden using command line argument <emphasis>-icp</emphasis> - with path to the initial configuration as in the example below:</para> + <section id="Java-Broker-Configuring-And-Managing-Configuration-Store-Location"> + <title>Configuration Store Location</title> + <para> + The broker will default to using <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Configuration-Properties">${qpid.work_dir}</link>/config.json + as the path for its configuration store unless otherwise instructed. + </para> + <para> + The command line argument <emphasis>-sp</emphasis> (or <emphasis>--store-path</emphasis>) can optionally be used to specify a different + relative or absolute path to use for the broker configuration store: + </para> <screen> -$ ./qpid-server -icp ./my-initial-configuration.json +$ ./qpid-server -sp ./my-broker-configuration.json </screen> - <para>In this example the initial configuration from file "./my-initial-configuration.json" is used - to create the broker configuration store on the broker startup.</para> - <para>If broker configuration store already exists the command line argument <emphasis>-icp</emphasis> with the path - to a custom initial configuration is ignored. The command line argument <emphasis>-os</emphasis> can be used - to force the (re)creation of broker configuration store from initial store even when broker configuration store exists. - The example below demonstrates this:</para> + + <para> + If no configuration store exists at the specified/defaulted location when the broker starts then one will be initialised using the current + <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Initial-Config-Location">'Initial Configuration'</link>. + </para> + </section> + + <section id="Java-Broker-Configuring-And-Managing-Configuration-Store-Initial-Config-Location"> + <title>'Initial Configuration' Location</title> + <para> + The 'Initial Configuration' JSON file is used when initialiasing new broker configuration stores. The broker will default to using + an internal file within its jar unless otherwise instructed. + </para> + <para> + The command line argument <emphasis>-icp </emphasis> (or <emphasis>--initial-config-path</emphasis>) can be used to override the brokers + internal file and supply a <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Create-Initial-Config">user-created one</link>:</para> <screen> -$ ./qpid-server -os -icp ./my-initial-configuration.json +$ ./qpid-server -icp ./my-initial-configuration.json </screen> + <para> - The default initial configuration can be retrieved from the broker and stored into a file - using a command line argument <emphasis>-cic <path to file ></emphasis>, for example:</para> + If a Configuration Store already exists at the current <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Location">store location</link> + then the current 'Initial Configuration' will be ignored unless otherwise requested to <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Location">overwrite the configuration store</link> + </para> + </section> + + <section id="Java-Broker-Configuring-And-Managing-Configuration-Store-Create-Initial-Config"> + <title>Creating an 'Initial Configuration' JSON File</title> + + <para> + It is possible to have the broker output its default internal 'Initial Configuration' file to disk using the command line argument + <emphasis>-cic</emphasis> (or <emphasis>--create-initial-config</emphasis>). If the option is used without providing a path, a file called + <emphasis>initial-config.json</emphasis> will be created in the current directory, or alternatively the file can be created at a specified location: + </para> <screen> $ ./qpid-server -cic ./initial-config.json </screen> - <para>In the example above the broker default initial configuration saved at "./initial-config.json". - A custom initial configuration can be created from the default one by using this command line argument.</para> - <para>The default initial configuration declares four ports: - <itemizedlist> - <listitem><para><emphasis>AMQP</emphasis>, the default port number is 5672. The port number - can be overridden using configuration parameter <emphasis>qpid.amqp_port</emphasis>.</para></listitem> - <listitem><para><emphasis>HTTP</emphasis>, the default port number is 8080. The port number - can be overridden using configuration parameter <emphasis>qpid.HTTP_port</emphasis>.</para></listitem> - <listitem><para><emphasis>RMI</emphasis>, the default port number is 8999. The port number - can be overridden using configuration parameter <emphasis>qpid.rmi_port</emphasis>.</para></listitem> - <listitem><para><emphasis>JMX</emphasis>, the default port number is 9099. The port number - can be overridden using configuration parameter <emphasis>qpid.jmx_port</emphasis>.</para></listitem> - </itemizedlist> - It is also possible to override the port numbers in a default initial configuration using a command line - argument <emphasis>-prop</emphasis> like in an example below: + + <para> + The 'Initial Configuration' JSON file shares a common format with the brokers JSON Configuration Store implementation, so it is + possible to use a brokers Configuration Store output as an initial configuration. Typically 'Initial Configuration' files would + not to contain IDs for the configured entities, so that IDs will be generated when the configuration store is initialised and + prevent use of the same IDs across multiple brokers, however it may prove useful to include IDs if using the Memory + <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Type">Configuration Store Type</link>. + </para> + <para> + It can be useful to use <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Configuration-Properties">Configuration Properties</link> + within 'Initial Configuration' files to allow a degree of customisation with an otherwise fixed file. + </para> + <para> + For an example file, see <xref linkend="Java-Broker-Configuring-And-Managing-Configuration-Initial-Config-Example"/> + </para> + + </section> + + <section id="Java-Broker-Configuring-And-Managing-Configuration-Store-Overwrite-Config-Store"> + <title>Overwriting An Existing Configuration Store</title> + <para> + If a configuration store already exists at the configured <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Location">store location</link> + then it is used and the current <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Initial-Config-Location">'Initial Configuration'</link> + is ignored. + </para> + <para> + The command line argument <emphasis>-os</emphasis> (or <emphasis>--overwrite-store</emphasis>) can be used to + force a new broker configuration store to be initialised from the current 'Initial Configuration' even if one exists: </para> <screen> -$ ./qpid-server -prop qpid.amqp_port=10000 -prop qpid.http_port=10001 -prop qpid.jmx_port=10002 -prop qpid.rmi_port=10003 +$ ./qpid-server -os -icp ./my-initial-configuration.json </screen> - <para>In the example above, port number 10000 is specified for AMQP port, port number 10001 is specified for HTTP port, - port number 10002 is specified for JMX port and port number 1003 is specified for RMI port. When specified, - these port numbers will be used to create the broker configuration store from initial configuration on first broker start-up. - If configuration store already exists the settings will not have any effect. The command line argument <emphasis>-os</emphasis> - can be used to force (re)creation of broker configuration store from initial store. - </para> - <para>The command line argument <emphasis>-sp</emphasis> is used to specify a relative or absolute path to a broker - configuration store to start broker with. If the store at specified location does not exist it will be created from - the initial configuration. It is not required to provide the path to configuration store on broker on start-up.</para> + <para> + This can be useful to effectively play configuration into one or more broker to pre-configure them to a particular state, or alternatively + to ensure a broker is always started with a fixed configuration. In the latter case, use of the Memory + <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Type">Configuration Store Type</link> may also be useful. + </para> + </section> + + <section id="Java-Broker-Configuring-And-Managing-Configuration-Store-Type"> + <title>Configuration Store Type</title> + <para> + There are currently two implementations of the pluggable Broker Configuration Store, the default one which persists content to disk + in a JSON file, and another which operates only in-memory and so does not retain changes across broker restarts and always relies on the current + <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Initial-Config-Location">'Initial Configuration'</link> + to provide the configuration to start the broker with. + </para> + <para> + The command line argument <emphasis>-st</emphasis> (or <emphasis>--store-type</emphasis>) can be used to override the + default <emphasis>json</emphasis>)configuration store type and allow choosing an alterative, such as <emphasis>memory</emphasis>) + </para> <screen> -$ ./qpid-server -sp ./my-broker-configuration.json +$ ./qpid-server -st memory </screen> - <para>In the example above the broker is started with configuration store at "./my-broker-configuration.json".</para> - </section> + <para> + This can be useful when running tests, or always wishing to start the broker with the same + <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Initial-Config-Location">'Initial Configuration'</link> + </para> + </section> + + <section id="Java-Broker-Configuring-And-Managing-Configuration-Store-Configuration-Properties"> + <title>Customising Configuration using Configuration Properties</title> + <para> + It is posible for 'Initial Configuration' (and Configuration Store) files to contain ${properties} that can be resolved to + String values at startup, allowing a degree of customisation using a fixed file. Configuration Property values can be set + either via Java System Properties, or by specifying ConfigurationPproperties on the broker command line. + If both are defined, System Property values take precedence. + </para> + + <para> + The broker has the following set of core configuration properties, with the indicated default values if not otherwise configured by the user: + <table> + <title>Base Configuration Properties</title> + <tgroup cols="3"> + <thead> + <row> + <entry> + Name + </entry> + <entry> + Description + </entry> + <entry> + Value + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + qpid.amqp_port + </entry> + <entry> + Port number used for the brokers default AMQP messaging port + </entry> + <entry> + "5672" + </entry> + </row> + <row> + <entry> + qpid.http_port + </entry> + <entry> + Port number used for the brokers default HTTP management port + </entry> + <entry> + "8080" + </entry> + </row> + <row> + <entry> + qpid.rmi_port + </entry> + <entry> + Port number used for the brokers default RMI Registry port, to + advertise the JMX ConnectorServer. + </entry> + <entry> + "8999" + </entry> + </row> + <row> + <entry> + qpid.jmx_port + </entry> + <entry> + Port number used for the brokers default JMX port + </entry> + <entry> + "9099" + </entry> + </row> + <row> + <entry> + qpid.home_dir + </entry> + <entry> + Location of the broker installation directory, which contains + the 'lib' directory and the 'etc' directory often used to store + files such as group and ACL files. + </entry> + <entry> + Defaults to the value set into the QPID_HOME system property if it + is set, or remains unset otherwise unless configured by the user. + </entry> + </row> + <row> + <entry> + qpid.work_dir + </entry> + <entry> + Location of the broker working directory, which might contain + the persistent message store and broker configuration store files. + </entry> + <entry> + Defaults to the value set into the QPID_WORK system property if it + is set, or the 'work' subdirectory of the JVMs current working directory. + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + + <para> + Use of these core properties can be seen in the <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Initial-Config-Example">default 'Initial Configuration' example</link>. + </para> - <section id="Java-Broker-Configuring-And-Managing-Configuration-Store-Example"> - <title>Example of JSON configuration store</title> - <para>The JSON configuration store is used as a default configuration store. - An example of the JSON store is provided below:</para> + <para> + Configuration Properties can be set on the command line using the <emphasis>-prop</emphasis> (or <emphasis>--configuration-property</emphasis>) command line argument: + </para> + + <screen> +$ ./qpid-server -prop qpid.amqp_port=10000 -prop qpid.http_port=10001 + </screen> + <para> + In the example above, property used to set the port number of the default AMQP port is specified with the value 10000, overriding the default value of 5672, and similarly the vlaue 10001 is used to override the default HTTP port number of 8080. + When using the 'Initial Configuration' to initialise a new Configuration Store (either at first broker startup, when requesting to + <link linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Location">overwrite the configuration store</link>) these new values will be used for the port numbers instead. + </para> + <para> + NOTE: when saving the broker Configuration Store, either during initialisation when generating any required IDs for the 'Initial Configuration', or when required following user-prompted change via the managmenet interface, values are + stored in their resolved state. As such, if a Configuration Store already exists when the broker is started, it is likely that setting a Configuration Property to a value different than it was previously set could have no effect. + </para> + + + + + + </section> + + <section id="Java-Broker-Configuring-And-Managing-Configuration-Initial-Config-Example"> + <title>Example of JSON 'Initial Configuration'</title> + <para> + An example of the default 'Initial Configuration' JSON file the broker uses is provided below:</para> <example> - <title>JSON configuration store</title> + <title>JSON 'Initial configuration' File</title> <programlisting><![CDATA[ { "name" : "Broker", @@ -173,4 +370,4 @@ $ ./qpid-server -sp ./my-broker-configuration.json </section> -</section>
\ No newline at end of file +</section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml index 498494d81a..5b4ea42d2b 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml @@ -20,17 +20,34 @@ --> -<section id="Java-Broker-Configuring-And-Managing-JMX"> - <title>JMX Plugin</title> - - <para>JMX Management Plugin exposes JMX management interfaces to manage the Broker. - It is included into initial configuration by default and starts the RMI registry and JMX connector on pre-configured RMI and JMX ports. - If any or both JMX Ports are missed but JMX Management Plugin entry is present in the Broker configuration the Broker fails to start. - Only one JMX Management Plugin can be configured on the Broker. - </para> - - <para>JMX Management Plugin can start its own MBean server or can use a platform MBean server. - By default, the platform MBean server is used. This is controlled by the value of the plugin attribute "Use Platform MBean Server". - The value of this attribute can be changed through REST management interface but takes effect only on next Broker restart.</para> - +<section id="Java-Broker-Configuring-And-Managing-JMX-Management"> + <title>JMX Management</title> + + <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Introduction"> + <title>Introduction</title> + <para> + The brokers JMX Management Plugin provides the support for creating JMX MBeans for broker objects such as Queues, Exchanges, Connections etc. + </para> + <para> + It is included into the brokers Initial Configuration by default, and is responsible for servicing the RMI and JMX_RMI ports configured on the broker, with the former serving as the RMI Registry used to advertise the actual JMX Connector Server started on the latter. + </para> + </section> + + + <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-Configuration"> + <title>JMX Management Plugin Configuration</title> + + <para> + The JMX Management Plugin can be configured through the <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link> + and underlying REST management interface. By double-clicking on the JMX Management Plugin name in the object tree a tab for the plugin + is displayed with its current settings, which can be changed by clicking on the "Edit" button. + + The following attributes can be set on the JMX Management Plugin: + <itemizedlist> + <listitem><para><emphasis>Use Platform MBean Server</emphasis>. The JMX Management Plugin can start its own MBean Server or it can use the JVMs 'Platform MBean Server'. + By default this is true, and the Platform MBean Server is used.</para></listitem> + </itemizedlist> + NOTE: Changes to the "Use Platform MBean Server" attribute only take effect at broker restart. + </para> + </section> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-REST-API.xml b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-REST-API.xml index 66dc737354..1178b987ff 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-REST-API.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-REST-API.xml @@ -22,12 +22,13 @@ <section id="Java-Broker-Configuring-And-Managing-REST-API"> <title>REST API</title> - <section id="Java-Broker-Configuring-And-Managing-REST-API-Overview"> - <title>REST API Overview</title> - <para>This section provides an overview of REST management interfaces.</para> - <para>If web management plugin is configured - the REST interfaces can be used to monitor and manage the Broker instance.</para> - <para>The Qpid broker REST interfaces support traditional REST model which uses the GET method requests to retrieve + <para> + The brokers <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link> makes calls to an underlying REST API + to manage the broker. This section provides a brief overview of the REST interface, which can be used directly to monitor and manage the Broker + instance although it is still evolving toward being fully considered a seperately supported interface. + </para> + + <para>The brokers REST interface support traditional REST model which uses the GET method requests to retrieve the information about broker configured objects, DELETE method requests to delete the configured object, PUT to create or update the configured object and POST to perform the configured objects updates not available with the PUT requests.</para> <para>The table below lists the available REST services with brief description how they can be used.</para> @@ -37,7 +38,7 @@ <tgroup cols="6"> <thead> <row> - <entry>Rest service URL</entry> + <entry>REST Service URL</entry> <entry>Description</entry> <entry>GET</entry> <entry>PUT</entry> @@ -263,7 +264,7 @@ </tbody> </tgroup> </table> - <para>Rest URLs are hierarchical. It is permitted to replace rest URL elements with an "asterisks" in GET requests to denote + <para>The REST URLs are hierarchical. It is permitted to replace rest URL elements with an "asterisks" in GET requests to denote all object of a particular type. Additionally, trailing object type in the URL hierarchy can be omitted. In this case GET request will return all of the object underneath of the current object.</para> <para>For example, for binding URL http://localhost:8080/rest/binding/<vhost>/<exchange>/<queue>/<binding> @@ -272,7 +273,7 @@ If <emphasis><binding></emphasis> and <emphasis><queue></emphasis> are omitted in binding REST URL (http://localhost:8080/rest/binding/<vhostname>/<exchangename>) the GET request will result in returning all bindings for all queues for the given exchange in the virtual host. - </para> + </para> <example> <title>Examples of queue creation using curl:</title> <programlisting><![CDATA[ @@ -287,6 +288,9 @@ curl -X PUT -d '{"durable":true,"type":"priority"}' http://localhost:8080/rest/ curl -X PUT -d '{}' http://localhost:8080/rest/binding/<vhostname>/<exchangename>/<queue-name>/<binding-name> ]]></programlisting> </example> - <para>Qpid broker Web Management Console calls rest interfaces internally to manage the broker.</para> - </section> + <para> + NOTE: the above examples were performed after editing the + <link linkend="Java-Broker-Configuring-And-Managing-HTTP-Management-Plugin-Configuration">HTTP Management Plugin Configuration</link> + to enable HTTP Basic Authentication on connections not using SSL (i.e HTTPS). + </para> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Console.xml b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Console.xml index 6e3b44dab8..faf496d61d 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Console.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Console.xml @@ -21,12 +21,13 @@ --> <section id="Java-Broker-Configuring-And-Managing-Web-Console"> - <title>Web Console</title> - <para>If web management is configured the Web Mnagement Console can be accessed from web browser - using URL http(s)://<hostname>:<port>/management, where</para> + <title>Web Management Console</title> + <para> + The Web Management Console can be accessed from a web browser using the URL: http(s)://<hostname>:<port>/management where: + </para> <itemizedlist> - <listitem><para><emphasis>hostname</emphasis> is the broker host</para></listitem> - <listitem><para><emphasis>port</emphasis> is the HTTP(s) port number</para></listitem> + <listitem><para><emphasis>hostname</emphasis> is the broker hostname</para></listitem> + <listitem><para><emphasis>port</emphasis> is the HTTP(S) port number</para></listitem> </itemizedlist> <para>For authenticated and authorized user the page like below should be displayed on navigation to the management URL:</para> <ulink url="images/Management-Web-Console.png"> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Management.xml b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Management.xml index 1c6a7c4d20..76d29093ad 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Management.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Management.xml @@ -20,34 +20,45 @@ --> -<section id="Java-Broker-Configuring-And-Managing-Web-Management"> - <title>Web Management</title> - - <para>Web Management Plugin exposes REST management interfaces and provides the Web Management Console to configure the Broker. - It is included into initial configuration by default and starts the servlet container on pre-configured HTTP ports. - If no HTTP Port is configured but Web Management Plugin entry is present in the Broker configuration the Broker fails to start. - Only one Web Management Plugin can be configured on the Broker. - </para> - - <para>Web Management itself can be configured through REST management interfaces and Web Management Console. - The following attributes can be set on Web Management Plugin: - <itemizedlist> - <listitem><para><emphasis>Basic Authentication for HTTP</emphasis> is flag to enable/disable - Basic Authentication on HTTP ports. It is set to false by default.</para></listitem> - <listitem><para><emphasis>Basic Authentication for HTTPS</emphasis> is flag to enable/disable - Basic Authentication on HTTPS ports. It is set to true by default.</para></listitem> - <listitem><para><emphasis>SASL Authentication for HTTP</emphasis> is flag to enable/disable - SASL Authentication on HTTP ports. It is set to true by default.</para></listitem> - <listitem><para><emphasis>SASL Authentication for HTTPS</emphasis> is flag to enable/disable - SASL Authentication on HTTPS ports. It is set to true by default.</para></listitem> - <listitem><para><emphasis>Session timeout</emphasis> is the timeout in seconds to close the HTTP session. - It is set to 10 minutes by default.</para></listitem> - </itemizedlist> - On clicking on Web Management Plugin name in Broker object tree the tab for Web Management Plugin is displayed with current plugin settings. - The plugin attributes can be changed by clicking on "Edit" button in Plugin tab. The changes will take effect only after Broker is restarted. - </para> +<section id="Java-Broker-Configuring-And-Managing-HTTP-Management"> + <title>HTTP Management</title> + <section id="Java-Broker-Configuring-And-Managing-HTTP-Management-Introduction"> + <title>Introduction</title> + <para> + The brokers HTTP Management Plugin provides the <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link> + to enable fully configuring the Broker, via an underlying <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST management interface</link>. + </para> + <para> + It is included into the brokers Initial Configuration by default, and is responsible for servicing the HTTP ports configured on the broker. + </para> + </section> + + <!-- INCLUDE --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Configuring-And-Managing-Web-Console.xml"/> + + <section id="Java-Broker-Configuring-And-Managing-HTTP-Management-Plugin-Configuration"> + <title>HTTP Management Plugin Configuration</title> + + <para> + The HTTP Management Plugin itself can be configured through the <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link> + and underlying REST management interface. By double-clicking on the Http Management Plugin name in the object tree a tab for the plugin + is displayed with its current settings, which can be changed by clicking on the "Edit" button. + + The following attributes can be set on the HTTP Management Plugin: + <itemizedlist> + <listitem><para><emphasis>Basic Authentication for HTTP</emphasis>. It is set to false (disabled) by default.</para></listitem> + <listitem><para><emphasis>Basic Authentication for HTTPS</emphasis>. It is set to true (enabled) by default.</para></listitem> + <listitem><para><emphasis>SASL Authentication for HTTP</emphasis>. It is set to true (enabled) by default.</para></listitem> + <listitem><para><emphasis>SASL Authentication for HTTPS</emphasis>. It is set to true (enabled) by default.</para></listitem> + <listitem><para><emphasis>Session timeout</emphasis> is the timeout in seconds to close the HTTP session. + It is set to 10 minutes by default.</para></listitem> + </itemizedlist> + NOTE: Changes to the Session Timeout attribute only take effect at broker restart. + </para> + </section> + + <!-- INCLUDE --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Configuring-And-Managing-REST-API.xml"/> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Getting-Started.xml b/qpid/doc/book/src/java-broker/Java-Broker-Getting-Started.xml index e90dadd126..c982984a82 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Getting-Started.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Getting-Started.xml @@ -26,18 +26,21 @@ <chapter id="Java-Broker-Getting-Started"> <title>Getting Started</title> - <para> - This section describes how to start the Java Broker for the first time. - The Broker configuration details and configuration command line arguments are described in <xref linkend="Java-Broker-Configuring-And-Managing-Configuration-Store-Introduction"/>. - </para> - - <section role="h2" id="Java-Broker-Getting-Started-Starting"> - <title>Starting/Stopping the Broker</title> - <para>To start the Broker, use the <command>qpid-server</command> script (UNIX) or <command>qpid-server.bat</command> (Windows) - provided within distribution.</para> + + <section role="h2" id="Java-Broker-Getting-Started-Introduction"> + <title>Introduction</title> + <para> + This section describes how to start and stop the Java Broker, and outlines the various command line options. + </para> + <para> + For additional details about the broker configuration store and related command line arguments see + <xref linkend="Java-Broker-Configuring-And-Managing-Configuration-Store"/>. + The broker is fully configurable via its Web Management Console, for details of this see + <xref linkend="Java-Broker-Configuring-And-Managing-Web-Console"/>. + </para> </section> <section role="h2" id="Java-Broker-Getting-Started-Starting-Stopping-Windows"> - <title>Starting/Stopping on Windows</title> + <title>Starting/Stopping the broker on Windows</title> <para>Firstly change to the installation directory used during the <link linkend="Java-Broker-Installation-InstallationWindows">installation</link> and ensure that the <link linkend="Java-Broker-Installation-InstallationWindows-SettingQPIDWORK">QPID_WORK environment variable is set</link>.</para> <para>Now use the <command>qpid-server.bat</command> to start the server</para> @@ -59,11 +62,11 @@ [Broker] BRK-1004 : Qpid Broker Ready</screen> <para>The BRK-1004 message confirms that the Broker is ready for work. The MNG-1002 and BRK-1002 confirm the ports to which the Broker is listening (for HTTP/JMX management and AMQP respectively).</para> - <para>To stop the Broker, use Control-C or use the Shutdown MBean made from the <xref - linkend="Java-Broker-Configuring-And-Managing-JMX"/></para> + <para>To stop the Broker, use Control-C or use the Shutdown MBean from the + <link linkend="Java-Broker-Configuring-And-Managing-JMX-Management">JMX management plugin</link>.</para> </section> <section role="h2" id="Java-Broker-Getting-Started-Starting-Stopping-Unix"> - <title>Starting/Stopping on Unix</title> + <title>Starting/Stopping the broker on Unix</title> <para>Firstly change to the installation directory used during the <link linkend="Java-Broker-Installation-InstallationUnix">installation</link> and ensure that the <link linkend="Java-Broker-Installation-InstallationUnix-SettingQPIDWORK">QPID_WORK environment variable is set</link>.</para> <para>Now use the <command>qpid-server</command> script to start the server:</para> @@ -87,7 +90,7 @@ which the Broker is listening (for HTTP/JMX management and AMQP respectively).</para> <para>To stop the Broker, use Control-C from the controlling shell, use the <command>bin/qpid.stop</command> script, use <command>kill -TERM <pid></command>, or - the Shutdown MBean from <xref linkend="Java-Broker-Configuring-And-Managing-JMX"/></para> + the Shutdown MBean from the <link linkend="Java-Broker-Configuring-And-Managing-JMX-Management">JMX management plugin</link>.</para> </section> <section role="h2" id="Java-Broker-Getting-Started-LogFile"> <title>Log file</title> @@ -99,65 +102,71 @@ </section> <section role="h2" id="Java-Broker-Getting-Started-CommandLine"> <title>Using the command line</title> - <para>The Java Broker understands a number of command line options which may be used to override the configuration.</para> - <para>To see usage information for all command line options, use the option <option>--help</option></para> + <para>The Java Broker understands a number of command line options which may be used to customise the configuration.</para> + <para> + For additional details about the broker configuration and related command line arguments see + <xref linkend="Java-Broker-Configuring-And-Managing-Configuration-Store"/>. + The broker is fully configurable via its Web Management Console, for details of this see + <xref linkend="Java-Broker-Configuring-And-Managing-Web-Console"/>. + </para> + <para>To see usage information for all command line options, use the <option>--help</option> option</para> <programlisting><![CDATA[bin/qpid-server --help]]></programlisting> <screen><![CDATA[usage: Qpid [-cic <path>] [-h] [-icp <path>] [-l <file>] [-mm] [-mmhttp <port>] [-mmjmx <port>] [-mmpass <password>] [-mmqv] [-mmrmi <port>] [-os] [-sp <path>] [-st <type>] [-v] [-w <period>] - -cic <path> create a copy of the initial config + -cic <path> Create a copy of the initial config --create-initial-config <path> file, either to an optionally specified file path, or as initial-config.json in the current directory - -h, print this message + -h, Print this message --help - -icp <path> set the location of initial JSON config + -icp <path> Set the location of initial JSON config --initial-config-path <path> to use when creating/overwriting a broker configuration store - -l <file> use the specified log4j xml configuration + -l <file> Use the specified log4j xml configuration --logconfig <file> file. By default looks for a file named etc/log4j.xml in the same directory as the configuration file - -mm start broker in management mode, - disabling the AMQP ports + -mm Start broker in management mode, + --management-mode disabling the AMQP ports - -mmhttp <port> override http management port in + -mmhttp <port> Override http management port in --management-mode-http-port <port> management mode - -mmjmx override jmx connector port in + -mmjmx Override jmx connector port in --management-mode-jmx-connector-port <port> management mode -mmpass <password> Set the password for the management --management-mode-password <password> mode user mm_admin - -mmqv make virtualhosts stay in the quiesced + -mmqv Make virtualhosts stay in the quiesced --management-mode-quiesce-virtualhosts state during management mode. - -mmrmi <port> override jmx rmi registry port in + -mmrmi <port> Override jmx rmi registry port in --management-mode-rmi-registry-port <port> management mode - -os overwrite the broker configuration store + -os Overwrite the broker configuration store --overwrite-store with the current initial configuration - -prop,--config-property <name=value> set a configuration property to use when - resolving variables in the broker + -prop <name=value> Set a configuration property to use when + --config-property <name=value> resolving variables in the broker configuration store, with format 'name=value' - -sp <path> use given configuration store location + -sp <path> Use given configuration store location --store-path <path> - -st <type> use given broker configuration store type + -st <type> Use given broker configuration store type --store-type <type> - -v print the version information and exit + -v Print the version information and exit --version - -w <period> monitor the log file configuration file + -w <period> Monitor the log file configuration file --logwatch <period> for changes. Units are seconds. Zero means do not check for changes. ]]></screen> 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 7b41c01541..e96bd891f0 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml @@ -79,7 +79,7 @@ <title>Download</title> <section role="h3" id="Java-Broker-Installation-Download-Release"> <title>Broker Release</title> - <para>You can download the latest qpid-java-broker-&qpidCurrentRelease;.tar.gz package from the <ulink + <para>You can download the latest Java broker package from the <ulink url="&qpidDownloadUrl;">Download Page</ulink>. </para> <para> It is recommended that you confirm the integrity of the download by verifying the PGP signature @@ -101,14 +101,13 @@ <link linkend="Java-Broker-Miscellaneous-JVM-Verification-Windows">these instructions.</link> </para> <para>Now chose a directory for Qpid broker installation. This directory will be used for the Qpid JARs and configuration files. - It need not be the same location as the store used for the persistent messages or the log file (you will chose this - location later). For the remainder this example we will assumed that location c:\qpid has been chosen.</para> - <para>Now using WinZip<footnote><para>WinZip is a Registered Trademark of WinZip International LLC</para></footnote> (or similar) - extract the Qpid package qpid-java-broker-&qpidCurrentRelease;.tar.gz into the directory.</para> - <para>The extraction of the Qpid package will have created a directory qpid-broker-&qpidCurrentRelease; within c:\qpid</para> - <screen>Volume in drive C has no label - - Directory of c:\qpid\qpid-broker-&qpidCurrentRelease; + It need not be the same location as the work directory used for the persistent message store or the log file (you will choose this + location later). For the remainder this example we will assume that location c:\qpid has been chosen.</para> + <para>Next extract the &windowsBrokerDownloadFileName; package into the directory, using either the zip file handling offered + by Windows (right click the file and select 'Extract All') or a third party tool of your choice.</para> + <para>The extraction of the broker package will have created a directory &windowsExtractedBrokerDirName; within c:\qpid</para> + <screen> + Directory of c:\qpid\&windowsExtractedBrokerDirName; 07/25/2012 11:22 PM . 09/30/2012 10:51 AM .. @@ -118,8 +117,7 @@ 07/20/2012 08:10 PM 65,925 LICENSE 07/20/2012 08:10 PM 3,858 NOTICE 07/20/2012 08:10 PM 1,346 README.txt - 3 File(s) 71,129 bytes - 5 Dir(s) 743,228,796,928 bytes free</screen> +</screen> <section role="h3" id="Java-Broker-Installation-InstallationWindows-SettingQPIDWORK"> <title>Setting the working directory</title> <para>Qpid requires a work directory. This directory is used for the default location of the Qpid log @@ -145,14 +143,14 @@ <link linkend="Java-Broker-Miscellaneous-JVM-Verification-Unix">these instructions.</link> </para> <para>Now chose a directory for Qpid broker installation. This directory will be used for the Qpid JARs and configuration files. - It need not be the same location as the store used for the persistent messages or the log file (you will chose this - location later). For the remainder this example we will assumed that location /usr/local/qpid has been chosen.</para> - <para>Extract the Qpid package qpid-java-broker-&qpidCurrentRelease;.tar.gz into the directory.</para> + It need not be the same location as the work directory used for the persistent message store or the log file (you will choose this + location later). For the remainder this example we will assume that location /usr/local/qpid has been chosen.</para> + <para>Next extract the &unixBrokerDownloadFileName; package into the directory.</para> <programlisting>mkdir /usr/local/qpid cd /usr/local/qpid -tar xvzf qpid-java-broker-&qpidCurrentRelease;.tar.gz></programlisting> - <para>The extraction of the Qpid package will have created a directory qpid-broker-x.x</para> - <screen>ls -la qpid-broker-&qpidCurrentRelease;/ +tar xvzf &unixBrokerDownloadFileName;></programlisting> + <para>The extraction of the broker package will have created a directory &unixExtractedBrokerDirName; within /usr/local/qpid</para> + <screen>ls -la &unixExtractedBrokerDirName;/ total 152 drwxr-xr-x 8 qpid qpid 272 25 Jul 23:22 . drwxr-xr-x 45 qpid qpid 1530 30 Sep 10:51 .. diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml b/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml index e4661d6b7e..c322045336 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml @@ -26,11 +26,13 @@ <section id="Java-Broker-Ports-Configuring"> <title>Configuring Broker Ports</title> - <para>The Broker Ports can be configured using - <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> - and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>.</para> + <para> + The Broker Ports can be configured using the + <link linkend="Java-Broker-Configuring-And-Managing-HTTP-Management-Introduction">HTTP management interfaces</link>. + </para> - <para>The following Port managing operations are available from Web Management Console: + <para>The following Port managing operations are available from the + <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>: <itemizedlist> <listitem><para>A new Port can be created by clicking "Add Port" button on the Broker tab.</para></listitem> <listitem><para>An existing Port details are displayed on the Port tab after clicking @@ -44,50 +46,45 @@ <para>Three different types of ports can be created: <itemizedlist> <listitem><para>AMQP ports accepting connections for supported AMQP protocols.</para></listitem> - <listitem><para>HTTP ports accepting connections for HTTP and HTTPS protocols and used by web management plugin.</para></listitem> - <listitem><para>RMI ports supporting RMI and JMX_RMI protocols and used by JMX management plugin.</para></listitem> + <listitem><para>HTTP ports accepting connections for HTTP and HTTPS (by selecting the SSL transport) and used by web management plugin.</para></listitem> + <listitem><para>JMX related ports supporting RMI and JMX_RMI protocols and used by JMX management plugin.</para></listitem> </itemizedlist> </para> - <para>On creation or editing of AMQP port the port protocols can be specified from the list of supported AMQP protocols. - Any number of AMQP ports with any combination of supported protocols can be configured on the Broker.</para> - - <para>It is possible to create any number of HTTP/HTTPS ports. However, only two JMX ports are recommended - to configure on the Broker: one with RMI protocol and another with JMX_RMI protocol. - The creation of more JMX protocols might result in unexpected behavior. When more then two JMX ports are configured - the JMX plugin will pick up only two of them (having different RMI protocols) in indeterministic order.</para> - - <para>Both TCP and SSL transports are supported by AMQP and HTTP ports. - The Keystore is required to configure on Port for SSL transport support. - The details of Keystore configuration are covered in <xref linkend="Java-Broker-SSL-Keystore"/>. - SSL transport is also supported by the JMX connector port (having protocol set to "JMX_RMI") - but JMX RMI port (having protocol set to "RMI") does not support SSL transport.</para> - - <para>Client Certificate Authentication can be configured with AMQP ports only. This requires configuring - of one or more Trustores on the Port and setting of needClientAuthentication and wantClientAuthentication attributes. - They allow control of whether the client must present an SSL certificate. Only one of these elements is needed but both - may be used at the same time. A socket's client authentication setting is one of three states: - required (needClientAuth = true), requested (wantClientAuth = true), or none desired (both false, the default). - If both elements are set to true, needClientAuth takes precedence. When using Client Certificate Authentication - it may be desirable to use the External Authentication Provider, for details see <xref linkend="Java-Broker-Security-External-Provider"/>. - The details how to configure Trustores are covered in <xref linkend="SSL-Truststore-ClientCertificate"/>.</para> - - <para>An Authentication Provider is required to configure on AMQP, HTTP and JMX connector(having protocol set to "JMX_RMI") ports. - JMX RMI port (having protocol set to "RMI") does not require setting of Authentication Provider. - For Authentication Provider configuration details see <xref linkend="Java-Broker-Security-Authentication-Providers"/></para> + <para> + It is possible to create any number of HTTP and AMQP (supporting any mixture of AMQP versions) ports, however only + two JMX-related ports can recommended to configure on the Broker: one with the RMI protocol for the RMI Registry to + advertise the JMX Connector Server and another with the JMX_RMI protocol for the JMX Connector Server itself. + </para> - <important> - Neither Port type no name can be changed for existing Port as editing of name and type is unsupported at the moment. - </important> + <para> + A configured <link linkend="Java-Broker-Security-Authentication-Providers">Authentication Provider</link> must be + selected on ports using the AMQP, HTTP and JMX_RMI protocols. + </para> + + <para> + SSL can be enabled forPorts with protocols that support it by selecting the 'SSL' transport, at which + point a configured <link linkend="Java-Broker-SSL-Keystore">KeyStore</link> must also be selected for the Port. + </para> + + <para> + Client Certificate Authentication can be configured for AMQP ports. This requires selecting one or more configured + <link linkend="SSL-Truststore-ClientCertificate">TrustStores</link> on the Port and setting the <emphasis>needClientAuthentication</emphasis> + and <emphasis>wantClientAuthentication</emphasis> attributes as desired. + They allow control of whether the client must present an SSL certificate, allowing for three possible states: + required (needClientAuth = true), requested (wantClientAuth = true), or none desired (both false, the default). + If both elements are set to true, needClientAuth takes precedence. When using Client Certificate Authentication + it may be desirable to use the <link linkend="Java-Broker-Security-External-Provider">External Authentication Provider</link>. + </para> <important> - The changes of port attributes will take effect only after broker restart. + Changes to port attributes will take effect only after broker restart. You should restart the broker + immediately if you require the attribute change sto take effect. </important> <important> - On deletion of active Port all opened connections remain opened until they are closed by the clients or Broker is shutdown - or connection Virtual Hosts are deleted or stopped. When Port is deleted with active connections, the creation of another Port - having the same port number as deleted one fails. + Following deletion of an active Port, the port remains bound until the Broker is restarted. You should restart the broker + immediately if you require preventing new connections on the port or disconnecting existing clients. </important> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml b/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml index 8642e20cd0..87ba0cfb29 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml @@ -105,10 +105,6 @@ However, configuring of maximum delivery retries on a queue without DLQ(AlternateExchange) will result in messages being discarded after the limit is reached.</para> </section> - <section role="h2" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig"> - <title>Using configuration</title> - <para>How to declare queues in the Virtual Host configuration file is described in <xref linkend="Java-Broker-Virtual-Host-Declare-Queues"/>.</para> - </section> <section role="h2" id="Java-Broker-Queues-OtherTypes-CreateUsingJmsOrJmx"> <title>Using JMX or AMQP</title> <para>To create a priority, sorted or LVQ queue programmatically from JMX or using a Qpid @@ -186,6 +182,10 @@ arguments.put("qpid.queue_sort_key","myheader"); managedBroker.createNewQueue("myqueue", null, true, arguments);]]></programlisting> </example> </section> + <section role="h2" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig"> + <title>Using configuration</title> + <para>How to declare queues in the Virtual Host configuration file is described in <xref linkend="Java-Broker-Virtual-Host-Declare-Queues"/>.</para> + </section> </section> <section role="h2" id="Java-Broker-Queues-OtherTypes-Message-Grouping"> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml index 880814a0be..ee9102f293 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml @@ -48,7 +48,8 @@ <section role="h3" id="Java-Broker-Stores-HA-BDB-Store-Configuration"> <title>Configuration</title> <para> - In order to use the BDBHAMessageStore, you must configure it for each VirtualHost desired by updating the store element + In order to use the BDBHAMessageStore, you must use a <link linkend="Java-Broker-Virtual-Hosts-Configuration-File">Virtual Host XML configuration file</link> + when <link linkend="Java-Broker-Virtual-Hosts-Configuring-Managing">defining a VirtualHost</link>, configuring it for each VirtualHost desired by updating the store element to specify the associated store class, provide a directory location for the data to be written, and configure the replication group and policies used by BDB JA HA. </para> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml b/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml index 97a6558ba3..14f9f08147 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml @@ -19,43 +19,31 @@ under the License. --> +<chapter id="Java-Broker-Virtual-Hosts-Configuration-File"> + <title>Virtual Host XML configuration file</title> - <section id="Java-Broker-Virtual-Hosts-Configuration-File"> - <title>Configuring Virtual Host using configuration file</title> - <para>This section describes how to configure Virtual Host using configuration XML.</para> - <para>Virtual Host configuration XML can hold configuration for a single Virtual Host or multiple Virtual Hosts. - When multiple Virtual Hosts are configured a section for the each virtual host needs to be added. It should contain a tag - having the same name as virtual host. + <section id="Java-Broker-Virtual-Hosts-Configuration-File-Introduction"> + <title>Introduction</title> + <para> + This chapter describes how to configure Virtual Hosts using an XML file. </para> -<programlisting> -<virtualhosts> - ... - <virtualhost> <co id="Java-Broker-Virtual-Hosts-Configuration-Multiple-1"/> - <name>test</name> - <test> - ... - </test> - </virtualhost> - - <virtualhost> <co id="Java-Broker-Virtual-Hosts-Configuration-Multiple-2"/> - <name>development</name> - <development> - ... - </development> - </virtualhost> - ... -</virtualhosts> - </programlisting> - <calloutlist> - <callout arearefs="Java-Broker-Virtual-Hosts-Configuration-Multiple-1"><para>A configuration section for a virtual host "test"</para></callout> - <callout arearefs="Java-Broker-Virtual-Hosts-Configuration-Multiple-2"><para>A configuration section for a virtual host "development"</para></callout> - </calloutlist> + <para> + This is no longer the preferred approach for + <link linkend="Java-Broker-Virtual-Hosts-Configuring-Managing">defining a VirtualHost</link> and will likely be removed + in a future release, however it is currently neccessary to support certain use cases such as per-virtualhost attribute + configuration, and specialised store configuration such as for the <link linkend="Java-Broker-Stores-HA-BDB-Store">BDB HA Message Store</link> + </para> + <para> + Each XML Virtual Host configuration file can hold configuration for a single Virtual Host or multiple Virtual Hosts. + For an example file (with multiple VirtualHosts), see <xref linkend="Java-Broker-Virtual-Host-Configuration-File-Example"/> + </para> + </section> <section id="Java-Broker-Virtual-Hosts-Configuration-File-ACL"> <title>Configuring ACL</title> <para><xref linkend="Java-Broker-Security-ACLs"/> provides the details of ACL, rules, formats, etc.</para> <para> - To apply an ACL on a single virtualhost named <replaceable>test</replaceable>, add the following to the config.xml: + To apply an ACL on a single virtualhost named <replaceable>test</replaceable>, add the following to the virtualhosts.xml: </para> <programlisting> @@ -489,7 +477,7 @@ </section> - <section role="h2" id="Java-Broker-Virtual-Host-Configuration-Example"> + <section role="h2" id="Java-Broker-Virtual-Host-Configuration-File-Example"> <title>An example of virtual host configuration file</title> <example> <title>An example of virtual host configuration file</title> @@ -502,7 +490,7 @@ <store> <class>org.apache.qpid.server.store.MemoryMessageStore</class> <!--<class>org.apache.qpid.server.store.derby.DerbyMessageStore</class> - <environment-path>${QPID_WORK}/derbystore</environment-path>--> + <environment-path>${QPID_WORK}/derbystore/localhost</environment-path>--> </store> <housekeeping> @@ -562,7 +550,7 @@ <store> <class>org.apache.qpid.server.store.MemoryMessageStore</class> <!--<class>org.apache.qpid.server.store.derby.DerbyMessageStore</class> - <environment-path>${QPID_WORK}/derbystore</environment-path>--> + <environment-path>${QPID_WORK}/derbystore/development</environment-path>--> </store> <queues> @@ -602,7 +590,7 @@ <store> <!--<class>org.apache.qpid.server.store.MemoryMessageStore</class>--> <class>org.apache.qpid.server.store.derby.DerbyMessageStore</class> - <environment-path>${QPID_WORK}/derbystore</environment-path> + <environment-path>${QPID_WORK}/derbystore/test</environment-path> </store> <queues> @@ -640,4 +628,4 @@ </example> </section> -</section>
\ No newline at end of file +</chapter> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts.xml b/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts.xml index 0a8f754aa0..b240d85d4f 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts.xml @@ -25,23 +25,29 @@ <section id="Java-Broker-Virtual-Hosts-Configuring-Managing"> <title>Configuring And Managing</title> - <para>One or more Virtual Hosts can be configured on the Broker. The - <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> - and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link> - can be used to add and delete Virtual Hosts.</para> + <para> + One or more Virtual Hosts can be configured on the Broker. The + <link linkend="Java-Broker-Configuring-And-Managing-HTTP-Management-Introduction">HTTP management interfaces</link> + can be used to add and delete Virtual Hosts. + </para> - <para>A new Virtual Host can be created in two ways by specifying either: + <para>A new Virtual Host can be created in two ways: <itemizedlist> - <listitem><para>A <link linkend="Java-Broker-Stores">store type</link> and a store path</para></listitem> - <listitem><para>A path to Virtual Host XML configuration file</para></listitem> + <listitem> + <para> + <emphasis>Supplying simply a <link linkend="Java-Broker-Stores">store type</link> and a store path</emphasis>: In this case, + the virtual host attributes are currently derived from default attribute values defined on the broker. This is the preferred approach. + </para> + </listitem> + <listitem> + <para> + <emphasis>Supplying the path to a <link linkend="Java-Broker-Virtual-Hosts-Configuration-File">Virtual Host XML configuration file</link></emphasis>: In this case, specific per-virtualhost attribute configuration + can be set in the file, as well as pre-configuring queues, exchanges, etc. This is no longer the preferred approach and will likely be removed in + a future release, however it is currently still neccessary to support certain use-cases such as per-virtualhost attribute configuration, and + specialised store configuration such as for the <link linkend="Java-Broker-Stores-HA-BDB-Store">BDB HA Message Store</link>. + </para> + </listitem> </itemizedlist> - In first case the virtual host attributes are derived from Broker global attributes. - In the second case, the Virtual Host specific configuration can be set in the configuration XML, - for example, alert thresholds, message store, queues, exchanges, ACL etc. The first way of Virtual Host creation - is more preferable as it will reduce the burden of configuration changes when migrating to a newer version, - especially, when the support of Virtual Host configuration XML will be removed. However, the second way - is the only way at the moment to configure <link linkend="Java-Broker-Stores-HA-BDB-Store">HA Message Store</link>, - Virtual Host <link linkend="Java-Broker-Security-ACLs">ACL</link> and virtual host specific attributes. </para> <para>The following Virtual Host Managing operations are available from @@ -58,9 +64,6 @@ <listitem><para>Existing Exchange/Queue tabs can be navigated from Virtual Host tab</para></listitem> </itemizedlist> </para> - </section> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Virtual-Hosts-Configuration.xml"/> - </chapter> diff --git a/qpid/doc/book/src/java-broker/commonEntities.xml b/qpid/doc/book/src/java-broker/commonEntities.xml index 9a8efa2e8f..865fb50edf 100644 --- a/qpid/doc/book/src/java-broker/commonEntities.xml +++ b/qpid/doc/book/src/java-broker/commonEntities.xml @@ -25,6 +25,11 @@ <!ENTITY qpidCurrentRelease "0.22"> +<!ENTITY windowsBrokerDownloadFileName "qpid-java-broker-&qpidCurrentRelease;.zip"> +<!ENTITY windowsExtractedBrokerDirName "qpid-broker-&qpidCurrentRelease;"> +<!ENTITY unixBrokerDownloadFileName "qpid-java-broker-&qpidCurrentRelease;.tar.gz"> +<!ENTITY unixExtractedBrokerDirName "qpid-broker-&qpidCurrentRelease;"> + <!-- Oracle javadoc --> <!ENTITY oracleJdkDocUrl "http://oracle.com/javase/6/docs/api/"> <!ENTITY oracleJeeDocUrl "http://docs.oracle.com/javaee/6/api/"> |