diff options
| author | Keith Wall <kwall@apache.org> | 2014-10-06 06:56:59 +0000 |
|---|---|---|
| committer | Keith Wall <kwall@apache.org> | 2014-10-06 06:56:59 +0000 |
| commit | 1cff5b63b5503feaa555c9f31ddc057fe9a18fdd (patch) | |
| tree | 2af0b085d86b1c258b8946ffc3332d9b037117c8 | |
| parent | 5d1236947bf2fb8117e8976149fbffa385022c0d (diff) | |
| download | qpid-python-1cff5b63b5503feaa555c9f31ddc057fe9a18fdd.tar.gz | |
QPID-6108: [Java Broker Documentation] Updates for changes made during 0.30
* Remove references to virtualhost.xml
* Rework concepts section
* Rework management section to separate means of management from management of the entities themselves
* Remove references message stores
* Update JVM defect to Java 7
* ACL updates
* Add Flow to Disk
Still further changes required flagged by TODO.
git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1629579 13f79535-47bb-0310-9956-ffa450edef68
78 files changed, 3271 insertions, 3228 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 83211d103a..4075859fe9 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 @@ -21,25 +21,21 @@ --> <book xmlns:xi="http://www.w3.org/2001/XInclude"> -<title>AMQP Messaging Broker (Java)</title> + <title>AMQP Messaging Broker (Java)</title> -<xi:include href="Java-Broker-Introduction.xml"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Installation.xml"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Getting-Started.xml"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts.xml"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Configuring-And-Managing.xml"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Ports.xml"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Virtual-Hosts.xml"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Exchanges.xml"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Queues.xml"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Stores.xml"/> -<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"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Environment-Variables.xml"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-System-Properties.xml"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Operational-Logging-Messages.xml"/> -<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Queue-Alerts.xml"/> + <xi:include href="Java-Broker-Introduction.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Installation.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Getting-Started.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Initial-Configuration.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Management-Channels.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Management-Managing-Entities.xml"/> + <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-Miscellaneous.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Environment-Variables.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-System-Properties.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Operational-Logging-Messages.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Appendix-Queue-Alerts.xml"/> </book> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml index 50b6fb2550..7416679951 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-Operational-Logging-Messages.xml @@ -26,6 +26,9 @@ <appendix id="Java-Broker-Appendix-Operation-Logging"> <title>Operational Logging</title> + + <para> TODO add HA operation log messages</para> + <para>The Broker will, by default, produce structured log messages in response to key events in the lives of objects within the Broker. These consise messages are designed to allow the user to understand the actions of the Broker in retrospect. This is valuable for problem diagnosis and diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Appendix-System-Properties.xml b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-System-Properties.xml index 0c71c17c71..bee52f47b2 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Appendix-System-Properties.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Appendix-System-Properties.xml @@ -43,16 +43,6 @@ </row> </thead> <tbody> - <row id="Java-Broker-Appendix-System-Properties-Shared-Msg-Group"> - <entry>qpid.shared_msg_group</entry> - <entry> - <literal>qpid.no-group</literal> - </entry> - <entry> - <para>Controls the default group for groups operating in 'shared groups' mode. See <xref - linkend="Java-Broker-Queues-OtherTypes-Message-Grouping"/></para> - </entry> - </row> <row id="Java-Broker-Appendix-System-Properties-Broker-Heartbeat-Timeout-Factor"> <entry>qpid.broker_heartbeat_timeout_factor</entry> <entry>2</entry> @@ -92,24 +82,6 @@ <para>If set true, the Broker will produce operational logging messages.</para> </entry> </row> - <row id="Java-Broker-Appendix-System-Properties-Broker-Amqp-Protocol-Excludes"> - <entry>qpid.broker_default_amqp_protocol_excludes</entry> - <entry>none</entry> - <entry> - <para>Controls the AMQP protocol versions supported by the Broker. The value of this - property is a comma separated list of AMQP protocol versions whose support should be - disabled.</para> - </entry> - </row> - <row id="Java-Broker-Appendix-System-Properties-Broker-Amqp-Protocol-Includes"> - <entry>qpid.broker_default_amqp_protocol_includes</entry> - <entry>none</entry> - <entry> - <para>Controls the AMQP protocol versions supported by the Broker. The value of this - property is a comma separated list of AMQP protocol versions whose support should be - enabled.</para> - </entry> - </row> <row id="Java-Broker-Appendix-System-Properties-Broker-Default-Supported-Protocol-Version-Reply"> <entry>qpid.broker_default_supported_protocol_version_reply</entry> <entry>none</entry> 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 deleted file mode 100644 index ea9f7d8fae..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Queues.xml +++ /dev/null @@ -1,35 +0,0 @@ -<?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-Queues"> -<title>Queues</title> -<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">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> -</section> 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 deleted file mode 100644 index 6f5f1f38ba..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Virtual-Hosts.xml +++ /dev/null @@ -1,58 +0,0 @@ -<?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-Virtual-Hosts"> -<title>Virtual Hosts</title> -<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: - <figure> - <title>Virtual Host 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>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> - <listitem><para><link linkend="Java-Broker-Stores-SQL-Store">JDBC Message Store</link></para></listitem> - <listitem><para><link linkend="Java-Broker-Stores-Derby-Store">Derby Message Store</link></para></listitem> - <listitem><para><link linkend="Java-Broker-Stores-BDB-Store">Berkeley DB Message Store</link></para></listitem> - <listitem><para><link linkend="Java-Broker-Stores-HA-BDB-Store">Berkeley DB HA Message Store</link></para></listitem> - <listitem><para><link linkend="Java-Broker-Stores-Memory-Store">Memory Message Store</link></para></listitem> - </itemizedlist> -</para> -<para>Virtual Hosts configuration is covered in <xref linkend="Java-Broker-Virtual-Hosts"/>.</para> -</section> 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 2981add7fb..997f324805 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Concepts.xml @@ -20,40 +20,25 @@ --> -<chapter id="Java-Broker-Concepts"> - <title>Concepts</title> +<chapter id="Java-Broker-Concepts"> + <title>Concepts</title> - <section id="Java-Broker-Concepts-Broker"> - <title>Broker</title> - <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: - <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> - - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Virtual-Hosts.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Exchanges.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Queues.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Ports.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Authentication-Providers.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Concepts-Other-Services.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="concepts/Java-Broker-Concepts-Broker.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="concepts/Java-Broker-Concepts-RemoteReplicationNodes.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="concepts/Java-Broker-Concepts-Virtualhosts.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="concepts/Java-Broker-Concepts-Exchanges.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="concepts/Java-Broker-Concepts-Queues.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="concepts/Java-Broker-Concepts-Ports.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="concepts/Java-Broker-Concepts-Authentication-Providers.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="concepts/Java-Broker-Concepts-Other-Services.xml"/> </chapter> 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 deleted file mode 100644 index 072effa798..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Config-Files.xml +++ /dev/null @@ -1,372 +0,0 @@ -<?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-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> - 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-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 -sp ./my-broker-configuration.json - </screen> - - <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 -icp ./my-initial-configuration.json - </screen> - - <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> - 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 -os -icp ./my-initial-configuration.json - </screen> - <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 -st memory - </screen> - <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> - - <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> - <para> - NOTE: When running the broker on Windows and starting it via the qpid-server.bat file, the "name=value" argument MUST be quoted. - </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 'Initial configuration' File</title> - <programlisting><![CDATA[ -{ - "name" : "Broker", - "defaultVirtualHost" : "default", - "modelVersion" : "1.0", - "storeVersion" : 1, - "authenticationproviders" : [ { - "name" : "passwordFile", - "path" : "${qpid.work_dir}/etc/passwd", - "type" : "PlainPasswordFile" - } ], - "ports" : [ { - "authenticationProvider" : "passwordFile", - "name" : "HTTP", - "port" : "8080", - "protocols" : [ "HTTP" ] - }, { - "authenticationProvider" : "passwordFile", - "name" : "JMX_CONNECTOR", - "port" : "9099", - "protocols" : [ "JMX_RMI" ] - }, { - "name" : "RMI_REGISTRY", - "port" : "8999", - "protocols" : [ "RMI" ] - }, { - "name" : "AMQP", - "port" : "5672" - } ], - "virtualhosts" : [ { - "name" : "default", - "storePath" : "${qpid.work_dir}/derbystore/default", - "storeType" : "DERBY" - } ], - "plugins" : [ { - "name" : "jmxManagement", - "pluginType" : "MANAGEMENT-JMX" - }, { - "name" : "httpManagement", - "pluginType" : "MANAGEMENT-HTTP" - } ] -} -]]></programlisting> - <para>In the configuration above the following entries are stored: - <itemizedlist> - <listitem><para>Authentication Provider of type <emphasis>PlainPasswordFile</emphasis> with name "passwordFile"</para></listitem> - <listitem><para>Four Port entries: "AMQP", "HTTP", "RMI_REGISTRY", "JMX_CONNECTOR"</para></listitem> - <listitem><para>Virtual Host with name "default" and DERBY message store type at location "${qpid.work_dir}/derbystore/default".</para></listitem> - <listitem><para>Two management plugins: "jmxManagement" of type "MANAGEMENT-JMX" and "httpManagement" of type "MANAGEMENT-HTTP".</para></listitem> - <listitem><para>Broker attributes are stored as a root entry.</para></listitem> - </itemizedlist> - </para> - </example> - </section> - - <section id="Java-Broker-Attributes-Configuring"> - <title>Configuring Broker Attributes</title> - - <para>The Broker Attributes 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 attributes can be changed from Web Management Console by clicking on "Edit" button - on "Broker Attributes" panel from Broker tab. - </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 deleted file mode 100644 index 7ec2428414..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-REST-API.xml +++ /dev/null @@ -1,296 +0,0 @@ -<?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-Configuring-And-Managing-REST-API"> -<title>REST API</title> - <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> - - <table> - <title>Rest services</title> - <tgroup cols="6"> - <thead> - <row> - <entry>REST Service URL</entry> - <entry>Description</entry> - <entry>GET</entry> - <entry>PUT</entry> - <entry>POST</entry> - <entry>DELETE</entry> - </row> - </thead> - <tbody> - <row> - <entry><para>/rest/broker</para></entry> - <entry><para>Rest service to manage broker instance</para></entry> - <entry><para>Retrieves the details of broker configuration</para></entry> - <entry><para>Updates broker attributes</para></entry> - <entry><para>Not implemented yet</para></entry> - <entry><para>Not implemented yet</para></entry> - </row> - <row> - <entry><para>/rest/authenticationprovider</para> - <para>/rest/authenticationprovider/<authentication provider name></para> - </entry> - <entry>Rest service to manage authentication providers on the broker</entry> - <entry>Retrieves the details about authentication providers</entry> - <entry>Creates or updates authentication providers</entry> - <entry>Not implemented yet</entry> - <entry>Deletes authentication providers</entry> - </row> - <row> - <entry><para>/rest/user</para> - <para>/rest/user/<authentication provider name>/<user name></para> - </entry> - <entry>Rest service to manage user account</entry> - <entry>Retrieves the details about user account</entry> - <entry>Creates user account, updates user password</entry> - <entry>Not implemented yet</entry> - <entry>Deletes user account</entry> - </row> - <row> - <entry><para>/rest/groupprovider</para> - <para>/rest/groupprovider/<group provider name></para> - </entry> - <entry>Rest service to manage group providers</entry> - <entry>Retrieves the details about group provider(s)</entry> - <entry>Creates group provider</entry> - <entry>Not implemented yet</entry> - <entry>Deletes groups providers</entry> - </row> - <row> - <entry><para>/rest/group</para> - <para>/rest/group/<group provider name>/<group name></para> - </entry> - <entry>Rest service to manage user group</entry> - <entry>Retrieves the details about user group</entry> - <entry>Creates group</entry> - <entry>Not implemented yet</entry> - <entry>Deletes group</entry> - </row> - <row> - <entry><para>/rest/groupmember</para> - <para>/rest/groupmember/<group provider name >/<group name>/<user name></para> - </entry> - <entry>Rest service to manage group member(s)</entry> - <entry>Retrieves the details about group member(s)</entry> - <entry>Add user to group</entry> - <entry>Not implemented yet</entry> - <entry>Deletes user from group</entry> - </row> - <row> - <entry> - <para>/rest/port</para> - <para>/rest/port/<port name></para> - </entry> - <entry>Rest service to manage broker ports(s)</entry> - <entry>Retrieves the details about the broker port(s)</entry> - <entry>Creates or updates port</entry> - <entry>Not implemented yet</entry> - <entry>Deletes ports</entry> - </row> - <row> - <entry> - <para>/rest/queue</para> - <para>/rest/queue/<virtual host name>/<queue name></para> - </entry> - <entry>Rest service to manage queue(s)</entry> - <entry>Retrieves the details about the queue(s)</entry> - <entry>Creates queue</entry> - <entry>Not implemented yet</entry> - <entry>Deletes queue</entry> - </row> - <row> - <entry> - <para>/rest/exchange</para> - <para>/rest/exchange/<virtual host name>/<exchange name></para> - </entry> - <entry>Rest service to manage exchange(s)</entry> - <entry>Retrieves the details about the exchange(s)</entry> - <entry>Creates exchange</entry> - <entry>Not implemented yet</entry> - <entry>Deletes exchange</entry> - </row> - <row> - <entry> - <para>/rest/binding</para> - <para>/rest/binding/<virtual host name>/<exchange name>/<queue name>/<binding name></para> - </entry> - <entry>Rest service to manage binding(s)</entry> - <entry>Retrieves the details about the binding(s)</entry> - <entry>Binds a queue to an exchange</entry> - <entry>Not implemented yet</entry> - <entry>Deletes binding</entry> - </row> - <row> - <entry> - <para>/rest/connection</para> - <para>/rest/connection/<virtual host name>/<connection name></para> - </entry> - <entry>Rest service to manage connection(s)</entry> - <entry>Retrieves the details about the connection(s)</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - </row> - <row> - <entry> - <para>/rest/session</para> - <para>/rest/session/<virtual host name>/<connection name>/<session name></para> - </entry> - <entry>Rest service to manage session(s)</entry> - <entry>Retrieves the details about the session(s)</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - </row> - <row> - <entry> - <para>/rest/message/<virtual host name>/<queue name></para> - </entry> - <entry>Rest service to manage messages(s)</entry> - <entry>Retrieves the details about the messages(s)</entry> - <entry>Not implemented yet</entry> - <entry>Copies, moves messages</entry> - <entry>Deletes messages</entry> - </row> - <row> - <entry> - <para>/rest/message-content/<virtual host name>/<queue name></para> - </entry> - <entry>Rest service to retrieve message content</entry> - <entry>Retrieves the message content</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - </row> - <row> - <entry> - <para>/rest/logrecords</para> - </entry> - <entry>Rest service to retrieve broker logs</entry> - <entry>Retrieves the broker logs</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - </row> - <row> - <entry> - <para>/rest/sasl</para> - </entry> - <entry>Sasl authentication</entry> - <entry>Retrieves user current authentication status and broker supported SASL mechanisms</entry> - <entry>Authenticates user using supported SASL mechanisms</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - </row> - <row> - <entry> - <para>/rest/logout</para> - </entry> - <entry>Log outs</entry> - <entry>Log outs user</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - </row> - <row> - <entry> - <para>/rest/accesscontrolprovider</para> - </entry> - <entry>Rest service to manage access control providers</entry> - <entry>Retrieves the details about access control providers</entry> - <entry>Creates access control provider</entry> - <entry>Not implemented yet</entry> - <entry>Deletes access control provider(s)</entry> - </row> - <row> - <entry> - <para>/rest/keystore</para> - </entry> - <entry>Rest service to manage KeyStores</entry> - <entry>Retrieves the details about KeyStore</entry> - <entry>Creates or updates KeyStore</entry> - <entry>Not implemented yet</entry> - <entry>Deletes KeyStore(s)</entry> - </row> - <row> - <entry> - <para>/rest/truststore</para> - </entry> - <entry>Rest service to manage TrustStore</entry> - <entry>Retrieves the details about TrustStore</entry> - <entry>Creates or updates TrustStore</entry> - <entry>Not implemented yet</entry> - <entry>Deletes TrustStore(s)</entry> - </row> - <row> - <entry> - <para>/rest/plugin</para> - </entry> - <entry>Rest service to manage plugins</entry> - <entry>Retrieves the details about plugins</entry> - <entry>Updates plugin attributes</entry> - <entry>Not implemented yet</entry> - <entry>Not implemented yet</entry> - </row> - </tbody> - </tgroup> - </table> - <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> - replacing of <emphasis><exchange></emphasis> with "asterisks" (http://localhost:8080/rest/binding/<vhost>/*/<queue>/<binding>) - will result in the GET response containing the list of bindings for all of the exchanges in the virtual host having the given name and given queue. - 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> - <example> - <title>Examples of queue creation using curl (authenticating as user admin):</title> - <programlisting><![CDATA[ -#create a durable queue -curl --user admin -X PUT -d '{"durable":true}' http://localhost:8080/rest/queue/<vhostname>/<queuename> -#create a durable priority queue -curl --user admin -X PUT -d '{"durable":true,"type":"priority"}' http://localhost:8080/rest/queue/<vhostname>/<queuename> - ]]></programlisting> - </example><example> - <title>Example of binding a queue to an exchange using curl</title> - <programlisting><![CDATA[ -curl --user admin -X PUT -d '{}' http://localhost:8080/rest/binding/<vhostname>/<exchangename>/<queue-name>/<binding-name> - ]]></programlisting> - </example> - <para> - NOTE: These curl examples utilise unsecure HTTP transport. To use the examples it is first necessary enable Basic - authentication for HTTP within the HTTP Management Configuration (it is off by default). - For details see <xref linkend="Java-Broker-Configuring-And-Managing-HTTP-Management-Plugin-Configuration"/> - </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 deleted file mode 100644 index faf496d61d..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Console.xml +++ /dev/null @@ -1,36 +0,0 @@ -<?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-Configuring-And-Managing-Web-Console"> - <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 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"> - <graphic fileref="images/Management-Web-Console.png" width="600px"/> - </ulink> -</section> 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 deleted file mode 100644 index 76d29093ad..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Web-Management.xml +++ /dev/null @@ -1,64 +0,0 @@ -<?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-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-Exchanges.xml b/qpid/doc/book/src/java-broker/Java-Broker-Exchanges.xml deleted file mode 100644 index 7fe0df1410..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Exchanges.xml +++ /dev/null @@ -1,51 +0,0 @@ -<?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. - ---> - -<chapter id="Java-Broker-Exchanges"> - <title>Exchanges</title> - - <section id="Java-Broker-Exchanges-Configuring"> - <title>Configuring Virtual Host Exchanges</title> - - <para>The Virtual Host Exchanges can be configured using - <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link>, - <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link> and Virtual Host configuration file.</para> - - <para>The following Exchange managing operations are available from Web Management Console: - <itemizedlist> - <listitem><para>A new Exchange can be added by clicking on "Add Exchange" on the Virtual Host tab.</para></listitem> - <listitem><para>An existing Exchange details can be viewed the Exchange tab. - Exchange tab is shown after clicking on Exchange name in Broker object tree or by clicking on Exchange row in Exchanges grid on Virtual Host tab.</para></listitem> - <listitem><para>An existing Exchange can be deleted by clicking on "Delete Exchange" button - on Virtual Host tab or "Delete Exchange" button on the Exchange tab.</para></listitem> - <listitem><para>An existing Queue can be bound to the Exchange by clicking on "Add Binding" button - on the Exchange tab.</para></listitem> - <listitem><para>An existing Queue binding can be deleted from Exchange by clicking on "Delete Binding" button - on the Exchange tab.</para></listitem> - </itemizedlist> - </para> - - <para>An example of configuring Exchanges in Virtual Host configuration file is provided - in <xref linkend="Java-Broker-Virtual-Host-Configuration-Exchange"/>.</para> - </section> - -</chapter> 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 d597cf1aeb..bef23434d2 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 @@ -34,9 +34,9 @@ </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"/>. + <xref linkend="Java-Broker-Initial-Configuration"/>. The broker is fully configurable via its Web Management Console, for details of this see - <xref linkend="Java-Broker-Configuring-And-Managing-Web-Console"/>. + <xref linkend="Java-Broker-Management-Channel-Web-Console"/>. </para> </section> <section role="h2" id="Java-Broker-Getting-Started-Starting-Stopping-Windows"> @@ -63,7 +63,7 @@ <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 from the - <link linkend="Java-Broker-Configuring-And-Managing-JMX-Management">JMX management plugin</link>.</para> + <link linkend="Java-Broker-Management-Channel-JMX">JMX management plugin</link>.</para> </section> <section role="h2" id="Java-Broker-Getting-Started-Starting-Stopping-Unix"> <title>Starting/Stopping the broker on Unix</title> @@ -90,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 the <link linkend="Java-Broker-Configuring-And-Managing-JMX-Management">JMX management plugin</link>.</para> + the Shutdown MBean from the <link linkend="Java-Broker-Management-Channel-JMX">JMX management plugin</link>.</para> </section> <section role="h2" id="Java-Broker-Getting-Started-LogFile"> <title>Log file</title> @@ -105,9 +105,9 @@ <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"/>. + <xref linkend="Java-Broker-Initial-Configuration"/>. The broker is fully configurable via its Web Management Console, for details of this see - <xref linkend="Java-Broker-Configuring-And-Managing-Web-Console"/>. + <xref linkend="Java-Broker-Management-Channel-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> @@ -171,5 +171,4 @@ means do not check for changes. ]]></screen> </section> - </chapter> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml b/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml index 7e779dacfe..d838bee626 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-High-Availability.xml @@ -41,9 +41,8 @@ <section role="h3" id="Java-Broker-High-Availability-OfferingsOfJavaBroker"> <title>HA offerings of the Java Broker</title> - <para>The Java Broker's HA offering became available at release <emphasis role="bold">0.18</emphasis>. HA is provided by way of the HA - features built into the <ulink url="&oracleBdbProductOverviewUrl;">Java Edition of the Berkley Database (BDB JE)</ulink> and as such - is currently only available to Java Broker users who use the optional BDB JE based persistence store. This + <para>HA is provided by way of the HA features built into the <ulink url="&oracleBdbProductOverviewUrl;">Java Edition of the Berkley Database + (BDB JE)</ulink> and as such is currently only available to Java Broker users who use the optional BDB JE based persistence store. This <emphasis role="bold">optional</emphasis> store requires the use of BDB JE which is licensed under the Sleepycat Licence, which is not compatible with the Apache Licence and thus BDB JE is not distributed with Qpid. Users who elect to use this optional store for the broker have to provide this dependency.</para> @@ -286,96 +285,13 @@ <section role="h3" id="Java-Broker-High-Availability-MultiNodeCluster"> <title>Multi Node Cluster</title> - <para>Multi node clusters, that is clusters where the number of nodes is three or more, are not yet - ready for use.</para> + <para>Multi node clusters are now supported. TODO expand</para> </section> - <section role="h3" id="Java-Broker-High-Availability-Configuration"> - <title>Configuring a Virtual Host to be a node</title> - <para>To configure a virtualhost as a cluster node, configure the virtualhost.xml in the following manner:</para> - <para> - - <example> - <title>Configuring a VirtualHost to use the BDBHAMessageStore</title> - <programlisting language="xml"><![CDATA[ -<virtualhosts> - <virtualhost> - <name>vhostname</name> - <vhostname> - <store> - <class>org.apache.qpid.server.store.berkeleydb.BDBHAMessageStore</class> - <environment-path>${QPID_WORK}/bdbhastore/vhostname</environment-path> - <highAvailability> - <groupName>myclustername</groupName> - <nodeName>mynode1</nodeName> - <nodeHostPort>node1host:port</nodeHostPort> - <helperHostPort>node1host:port</helperHostPort> - <durability>NO_SYNC\,NO_SYNC\,SIMPLE_MAJORITY</durability> - <coalescingSync>true|false</coalescingSync> - <designatedPrimary>true|false</designatedPrimary> - </highAvailability> - </store> - ... - </vhostname> - </virtualhost> -</virtualhosts>]]></programlisting> - </example> - </para> - <para>The <varname>groupName</varname> is the name of logical name of the cluster. All nodes within the - cluster must use the same <varname>groupName</varname> in order to be considered part of the cluster.</para> - <para>The <varname>nodeName</varname> is the logical name of the node. All nodes within the cluster must have a - unique name. It is recommended that the node name should be chosen from a different nomenclature from that of - the servers on which they are hosted, in case the need arises to move node to a new server in the future.</para> - <para>The <varname>nodeHostPort</varname> is the hostname and port number used by this node to communicate with the - the other nodes in the cluster. For the hostname, an IP address, hostname or fully qualified hostname may be used. - For the port number, any free port can be used. It is important that this address is stable over time, as BDB - records and uses this address internally.</para> - <para>The <varname>helperHostPort</varname> is the hostname and port number that new nodes use to discover other - nodes within the cluster when they are newly introduced to the cluster. When configuring the first node, set the - <varname>helperHostPort</varname> to its own <varname>nodeHostPort</varname>. For the second and subsequent nodes, - set their <varname>helperHostPort</varname> to that of the first node.</para> - <para><varname>durability</varname> controls the <link linkend="Java-Broker-High-Availability-DurabilityGuarantee">durability</link> - guarantees made by the cluster. It is important that all nodes use the same value for this property. The default value is - NO_SYNC\,NO_SYNC\,SIMPLE_MAJORITY. Owing to the internal use of Apache Commons Config, it is currently necessary - to escape the commas within the durability string.</para> - <para><varname>coalescingSync</varname> controls the <link linkend="Java-Broker-High-Availability-DurabilityGuarantee_CoalescingSync">coalescing-sync</link> - mode of Qpid. It is important that all nodes use the same value. If omitted, it defaults to true.</para> - <para>The <varname>designatedPrimary</varname> is applicable only to the <link linkend="Java-Broker-High-Availability-TwoNodeCluster">two-node - case.</link> It governs the behaviour of a node when the other node fails or becomes uncontactable. If true, - the node will be designated as primary at startup and will be able to continue operating as a single node master. - If false, the node will transition to an unavailable state until a third-party manually designates the node as - primary or the other node is restored. It is suggested that the node that normally fulfils the role of master is - set true in config file and the node that is normally replica is set false. Be aware that setting both nodes to - true will lead to a failure to start up, as both cannot be designated at the point of contact. Designating both - nodes as primary at runtime (using the JMX interface) will lead to a <link linkend="Java-Broker-High-Availability-TwoNodeSplitBrain">split-brain</link> - in the case of network partition and must be avoided.</para> - <note><para>Usage of domain names in <varname>helperHostPort</varname> and <varname>nodeHostPort</varname> is more preferebale - over IP addresses due to the tendency of more frequent changes of the last over the former. - If server IP address changes but domain name remains the same the HA cluster can continue working as normal - in case when domain names are used in cluster configuration. In case when IP addresses are used and they are changed with the time - than Qpid <link linkend="Java-Broker-High-Availability-JMXAPI">JMX API for HA</link> can be used to change the addresses or remove the nodes from the cluster.</para></note> - - <section role="h4" id="Java-Broker-High-Availability-Configuration_BDBEnvVars"> - <title>Passing BDB environment and replication configuration options</title> - <para>It is possible to pass BDB <ulink url="&oracleBdbJavaDocUrl;com/sleepycat/je/EnvironmentConfig.html">environment</ulink> and - <ulink url="&oracleBdbJavaDocUrl;com/sleepycat/je/rep/ReplicationConfig.html">replication</ulink> configuration options from the - virtualhost.xml.</para> - <para>Environment configuration options are passed as described in <xref linkend="Java-Broker-Stores-BDB-Store-Configuration_BDBEnvVars"/></para> - <para>Replication configuration option are passed using <varname>repConfig</varname> elements with the <varname>store</varname> element.</para> - <para>For example, to override the BDB replication configuration option <varname>je.rep.electionsPrimaryRetries</varname>.</para> - <programlisting language="xml"><![CDATA[ - ... - </highAvailability> - ... - <repConfig> - <name>je.rep.electionsPrimaryRetries</name> - <value>3</value> - </repConfig> - ... - </store>]]></programlisting> - </section> + <section role="h3" id="Java-Broker-High-Availability-Creating-A-Grouop"> + <title>Creating a Group</title> + <para>TODO</para> </section> - <section role="h3" id="Java-Broker-High-Availability-DurabilityGuarantee"> <title>Durability Guarantees</title> <para>The term <ulink url="http://en.wikipedia.org/wiki/ACID#Durability">durability</ulink> is used to mean that once a @@ -482,9 +398,9 @@ the value greater than 1000 milliseconds. If it is desired that clients re-connect automatically after a master to replica failure, <varname>cyclecount</varname> should be tuned so that the retry period is longer than the expected length of time to perform the failover.</para> - <example><title>Example of connection URL for the HA Cluster</title><![CDATA[ + <example><title>Example of connection URL for the HA Cluster</title><para><![CDATA[ amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672?connectdelay='2000'&retries='3';tcp://localhost:5671?connectdelay='2000'&retries='3';tcp://localhost:5673?connectdelay='2000'&retries='3''&failover='roundrobin?cyclecount='30'' - ]]></example> + ]]></para></example> </section> @@ -706,8 +622,7 @@ Current state of node: Node-5001 from group: TestClusterGroup <para>In case when a Replica goes down (or falls behind the Master in 2 node cluster where the Master is designated primary) and the Master continues running, the non-replicated store files are kept on the Masters disk for the period of time as specified in <emphasis>je.rep.repStreamTimeout</emphasis> JE setting in order to replicate this data later - when the Replica is back. This setting is set to 1 hour by default by the broker. The setting can be overridden as described in - <xref linkend="Java-Broker-High-Availability-Configuration_BDBEnvVars"/>.</para> + when the Replica is back. This setting is set to 1 hour by default by the broker.</para> <para>Depending from the application publishing/consuming rates and message sizes, the disk space might become overfull during this period of time due to preserved logs. Please, make sure to allocate enough space on your disk to avoid this from happening. diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Initial-Configuration.xml b/qpid/doc/book/src/java-broker/Java-Broker-Initial-Configuration.xml new file mode 100644 index 0000000000..ccdce918c6 --- /dev/null +++ b/qpid/doc/book/src/java-broker/Java-Broker-Initial-Configuration.xml @@ -0,0 +1,360 @@ +<?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. + +--> + +<chapter id="Java-Broker-Initial-Configuration"> + <title>Initial Configuration</title> + + + <section id="Java-Broker-Initial-Configuration-Introduction"> + <title>Introduction</title> + <para>This section describes how to perform initial configuration on the command line. Once + the Broker is started, subsequent management is perfomed using the <link + linkend="Java-Broker-Management-Channel">Management interfaces</link></para> + <para> The configuration for each component is stored as an entry in the broker + configuration store, currently implemented as a JSON file which persists changes to + disk, BDB or Derby databadse 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> 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-Initial-Configuration-Location" + >store location</link> then one will be initialised with the current <link + linkend="Java-Broker-Initial-Configuration-Initial-Config-Location">'Initial + Configuration'</link>. Unless otherwise requested to <link + linkend="Java-Broker-Initial-Configuration-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-Initial-Configuration-Location"> + <title>Configuration Store Location</title> + <para> The broker will default to using <link + linkend="Java-Broker-Initial-Configuration-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 -sp ./my-broker-configuration.json + </screen> + + <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-Initial-Configuration-Initial-Config-Location">'Initial + Configuration'</link>. </para> + </section> + + <section id="Java-Broker-Initial-Configuration-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-Initial-Configuration-Create-Initial-Config">user-created + one</link>:</para> + <screen> +$ ./qpid-server -icp ./my-initial-configuration.json + </screen> + + <para> If a Configuration Store already exists at the current <link + linkend="Java-Broker-Initial-Configuration-Location">store location</link> then the + current 'Initial Configuration' will be ignored unless otherwise requested to <link + linkend="Java-Broker-Initial-Configuration-Location">overwrite the configuration + store</link> + </para> + </section> + + <section id="Java-Broker-Initial-Configuration-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> 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-Initial-Configuration-Type">Configuration Store Type</link>. </para> + <para> It can be useful to use <link + linkend="Java-Broker-Initial-Configuration-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-Initial-Configuration-Overwrite-Config-Store"> + <title>Overwriting An Existing Configuration Store</title> + <para> If a configuration store already exists at the configured <link + linkend="Java-Broker-Initial-Configuration-Location">store location</link> then it + is used and the current <link + linkend="Java-Broker-Initial-Configuration-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 -os -icp ./my-initial-configuration.json + </screen> + <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-Initial-Configuration-Type">Configuration Store Type</link> may + also be useful. </para> + </section> + + <section id="Java-Broker-Initial-Configuration-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-Initial-Configuration-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 -st memory + </screen> + <para> This can be useful when running tests, or always wishing to start the broker with the + same <link linkend="Java-Broker-Initial-Configuration-Initial-Config-Location">'Initial + Configuration'</link> + </para> + </section> + + <section id="Java-Broker-Initial-Configuration-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> + + <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-Initial-Configuration-Location" + >overwrite the configuration store</link>) these new values will be used for the + port numbers instead. </para> + <para> NOTE: When running the broker on Windows and starting it via the qpid-server.bat + file, the "name=value" argument MUST be quoted. </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 'Initial configuration' File</title> + <programlisting><![CDATA[ +{ + "name": "${broker.name}", + "modelVersion": "2.0", + "defaultVirtualHost" : "default", + "authenticationproviders" : [ { + "name" : "passwordFile", + "type" : "PlainPasswordFile", + "path" : "${qpid.home_dir}${file.separator}etc${file.separator}passwd", + "preferencesproviders" : [{ + "name": "fileSystemPreferences", + "type": "FileSystemPreferences", + "path" : "${qpid.work_dir}${file.separator}user.preferences.json" + }] + } ], + "ports" : [ { + "name" : "AMQP", + "port" : "${qpid.amqp_port}", + "authenticationProvider" : "passwordFile" + }, { + "name" : "HTTP", + "port" : "${qpid.http_port}", + "authenticationProvider" : "passwordFile", + "protocols" : [ "HTTP" ] + }, { + "name" : "RMI_REGISTRY", + "port" : "${qpid.rmi_port}", + "protocols" : [ "RMI" ] + }, { + "name" : "JMX_CONNECTOR", + "port" : "${qpid.jmx_port}", + "authenticationProvider" : "passwordFile", + "protocols" : [ "JMX_RMI" ] + }], + "virtualhostnodes" : [ { + "name" : "default", + "type" : "JSON", + "virtualHostInitialConfiguration" : "{ \"type\" : \"DERBY\" }" + } ], + "plugins" : [ { + "type" : "MANAGEMENT-HTTP", + "name" : "httpManagement" + }, { + "type" : "MANAGEMENT-JMX", + "name" : "jmxManagement" + } ] +} +]]></programlisting> + <para>In the configuration above the following entries are stored: <itemizedlist> + <listitem> + <para> Authentication Provider of type + <emphasis>PlainPasswordFile</emphasis> with name "passwordFile". + </para> + </listitem> + <listitem> + <para> Four Port entries: "AMQP", "HTTP", "RMI_REGISTRY", "JMX_CONNECTOR". + </para> + </listitem> + <listitem> + <para> Virtualhost Node called default. On initial startup, it + virtualHostInitialConfiguration will cause a virtualhost to be created + with the same name. The confiuration will be stored in a + <emphasis>JSON</emphasis> configuration store, the message data will + be stored in a <emphasis>DERBY</emphasis> message store.</para> + </listitem> + <listitem> + <para>Two management plugins: "jmxManagement" of type "MANAGEMENT-JMX" and + "httpManagement" of type "MANAGEMENT-HTTP".</para> + </listitem> + <listitem> + <para>Broker attributes are stored as a root entry.</para> + </listitem> + </itemizedlist> + </para> + </example> + </section> + +</chapter> 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 822caaad4a..f9a8a25fd9 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Installation.xml @@ -35,43 +35,43 @@ <title>Prerequisites</title> <section role="h3" id="Java-Broker-Installation-Prerequistes-Java"> <title>Java Platform</title> - <para> - The Java Broker is an 100% Java implementation and as such it can be used on any operating - system supporting Java 1.6 or higher. This includes Linux, Solaris, Mac OS X, and Windows XP/Vista/7/8.</para> - <para> - The broker has been tested with Java implementations from both Oracle and IBM. Whatever - platform you chose, it is recommended that you ensure it is patched with any critical updates made - available from the vendor. - </para> - <para> - Verify that your JVM is installed properly by following <link linkend="Java-Broker-Miscellaneous-JVM-Verification">these instructions.</link> + <para> The Java Broker is an 100% Java implementation and as such it can be used on any + operating system supporting Java 1.7 or higher. This includes Linux, Solaris, Mac OS X, and + Windows XP/Vista/7/8.</para> + <para> The broker has been tested with Java implementations from both Oracle and IBM. Whatever + platform you chose, it is recommended that you ensure it is patched with any critical + updates made available from the vendor. </para> + <para> Verify that your JVM is installed properly by following <link + linkend="Java-Broker-Miscellaneous-JVM-Verification">these instructions.</link> </para> </section> <section role="h3" id="Java-Broker-Installation-Prerequistes-Disk"> <title>Disk</title> <para>The Java Broker installation requires approximately 20MB of free disk space.</para> - <para>The Java Broker also requires a working directory. The working directory is used for - the message store, that is, the area of the file-system used to record persistent messages whilst they - are passing through the Broker. The working directory is also used for the default location of the log file. - The size of the working directory will depend on the how the Broker is used.</para> - <para>The performance of the file system hosting the work directory is key to the performance of Broker as - a whole. For best performance, choose a device that has low latency and one that is uncontended by other - applications.</para> - <para>Be aware that there are additional considerations if you are considering hosting the working directory on NFS. See - <xref linkend="Java-Broker-Stores"/> for further details.</para> + <para>The Java Broker also requires a working directory. The working directory is used for the + message store, that is, the area of the file-system used to record persistent messages + whilst they are passing through the Broker. The working directory is also used for the + default location of the log file. The size of the working directory will depend on the how + the Broker is used.</para> + <para>The performance of the file system hosting the work directory is key to the performance + of Broker as a whole. For best performance, choose a device that has low latency and one + that is uncontended by other applications.</para> + <para>Be aware that there are additional considerations if you are considering hosting the + working directory on NFS.</para> </section> <section role="h3" id="Java-Broker-Installation-Prerequistes-Memory"> <title>Memory</title> <para>Qpid caches messages on the heap for performance reasons, so in general, the Broker will - benefit from as much heap as possible. However, on a 32bit JVM, the maximum addressable memory range - for a process is 4GB, after leaving space for the JVM's own use this will give a maximum heap size - of approximately ~3.7GB.</para> + benefit from as much heap as possible. However, on a 32bit JVM, the maximum addressable + memory range for a process is 4GB, after leaving space for the JVM's own use this will give + a maximum heap size of approximately ~3.7GB.</para> </section> <section role="h3" id="Java-Broker-Installation-Prerequistes-OperatingSystemAccount"> <title>Operating System Account</title> - <para>Installation or operation of Qpid does <emphasis>not</emphasis> require a privileged account (i.e. root - on UNIX platforms or Administrator on Windows). However it is suggested that you use an dedicated account - (e.g. qpid) for the installation and operation of the Java Broker.</para> + <para>Installation or operation of Qpid does <emphasis>not</emphasis> require a privileged + account (i.e. root on UNIX platforms or Administrator on Windows). However it is suggested + that you use an dedicated account (e.g. qpid) for the installation and operation of the Java + Broker.</para> </section> </section> @@ -79,33 +79,28 @@ <title>Download</title> <section role="h3" id="Java-Broker-Installation-Download-Release"> <title>Broker Release</title> - <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 - matches that available on the site. Instrutions are given on the download page. - </para> - </section> - <section role="h3" id="Java-Broker-Installation-Download-OptionalDependencies"> - <title>Optional Dependencies</title> - <para>The broker has an optional message store implementations backed by Oracle BDB JE. If you wish to use these - stores you will need to provide the optional Oracle BDB JE dependency. For more details, see <xref linkend="Java-Broker-Stores-BDB-Store"></xref> + <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 matches that available on the site. Instrutions are given on the download page. </para> </section> </section> <section role="h2" id="Java-Broker-Installation-InstallationWindows"> <title>Installation on Windows</title> - <para> - Firstly, verify that your JVM is installed properly by following - <link linkend="Java-Broker-Miscellaneous-JVM-Verification-Windows">these instructions.</link> + <para> Firstly, verify that your JVM is installed properly by following <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 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> + <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 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; @@ -120,36 +115,34 @@ </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 - file and is used for the storage of persistent messages. The work directory can be set on the - command-line (for the lifetime of the command interpreter), but you will normally want to set - the environment variable permanently via the Advanced System Settings in the Control Panel.</para> + <para>Qpid requires a work directory. This directory is used for the default location of the + Qpid log file and is used for the storage of persistent messages. The work directory can be + set on the command-line (for the lifetime of the command interpreter), but you will normally + want to set the environment variable permanently via the Advanced System Settings in the + Control Panel.</para> <screen>set QPID_WORK=C:\qpidwork</screen> - <para>If the directory referred to by <link linkend="Java-Broker-Appendix-Environment-Variables-Qpid-Work">QPID_WORK</link> does not exist, the Java Broker will attempt to create it - on start-up.</para> - </section> - <section role="h3" id="Java-Broker-Installation-InstallationWindows-OptionalDependencies"> - <title>Optional Dependencies</title> - <para>The broker has optional message store implementations backed by Oracle BDB JE. If you wish to use these - stores you will need to provide the optional Oracle BDB JE dependency. For more details, see <xref linkend="Java-Broker-Stores-BDB-Store"></xref> - </para> + <para>If the directory referred to by <link + linkend="Java-Broker-Appendix-Environment-Variables-Qpid-Work">QPID_WORK</link> does not + exist, the Java Broker will attempt to create it on start-up.</para> </section> </section> <section role="h2" id="Java-Broker-Installation-InstallationUnix"> <title>Installation on UNIX platforms</title> - <para> - Firstly, verify that your JVM is installed properly by following - <link linkend="Java-Broker-Miscellaneous-JVM-Verification-Unix">these instructions.</link> + <para> Firstly, verify that your JVM is installed properly by following <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 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>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 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 &unixBrokerDownloadFileName;</programlisting> - <para>The extraction of the broker package will have created a directory &unixExtractedBrokerDirName; within /usr/local/qpid</para> + <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 . @@ -163,21 +156,23 @@ drwxr-xr-x 34 qpid qpid 1156 25 Jul 23:22 lib </screen> <section role="h3" id="Java-Broker-Installation-InstallationUnix-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 - file and is used for the storage of persistent messages. The work directory can be set on the - command-line (for the lifetime of the current shell), but you will normally want to set - the environment variable permanently the user's shell profile file (~/.bash_profile for Bash etc).</para> + <para>Qpid requires a work directory. This directory is used for the default location of the + Qpid log file and is used for the storage of persistent messages. The work directory can be + set on the command-line (for the lifetime of the current shell), but you will normally want + to set the environment variable permanently the user's shell profile file (~/.bash_profile + for Bash etc).</para> <screen><![CDATA[export QPID_WORK=/var/qpidwork]]> </screen> - <para>If the directory referred to by <link linkend="Java-Broker-Appendix-Environment-Variables-Qpid-Work">QPID_WORK</link> does not exist, the Java Broker will attempt to create it - on start-up. - </para> - </section> - <section role="h3" id="Java-Broker-Installation-InstallationUnix-OptionalDependencies"> - <title>Optional Dependencies</title> - <para>The broker has an optional message store implementations backed by Oracle BDB JE. If you wish to use these - stores you will need to provide the optional Oracle BDB JE dependency. For more details, see <xref linkend="Java-Broker-Stores-BDB-Store"></xref> - </para> + <para>If the directory referred to by <link + linkend="Java-Broker-Appendix-Environment-Variables-Qpid-Work">QPID_WORK</link> does not + exist, the Java Broker will attempt to create it on start-up. </para> </section> </section> + <section role="h2" id="Java-Broker-Installation-OptionalDependencies"> + <title>Optional Dependencies</title> + <para>If you wish to utilise storage options using Oracle BDB JE or an External Database, see + <xref linkend="Java-Broker-Miscellaneous-Installing-Oracle-BDB-JE"/> and <xref + linkend="Java-Broker-Miscellaneous-Installing-External-JDBC-Driver"/> for details of + installing their dependencies.</para> + </section> </chapter> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Introduction.xml b/qpid/doc/book/src/java-broker/Java-Broker-Introduction.xml index 651389d0ac..8db30b6f0b 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Introduction.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Introduction.xml @@ -67,11 +67,11 @@ External, and file-based authentication mechanisms.</para> </listitem> <listitem> - <para>Pluggable message store architecture with implementations based on <ulink + <para>Pluggable storage architecture with implementations including <ulink url="http://db.apache.org/derby/">Apache Derby</ulink>, <ulink url="&oracleBdbProductOverviewUrl;">Oracle BDB JE</ulink><footnote> <para>Oracle BDB JE must be downloaded separately.</para> - </footnote>, and Memory Store</para> + </footnote>, and External Database</para> </listitem> <listitem> <para>Web based management interface and programmatic management interfaces via REST and JMX diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Management-Channels.xml b/qpid/doc/book/src/java-broker/Java-Broker-Management-Channels.xml new file mode 100644 index 0000000000..80fbb308bc --- /dev/null +++ b/qpid/doc/book/src/java-broker/Java-Broker-Management-Channels.xml @@ -0,0 +1,49 @@ +<?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. + +--> + +<chapter id="Java-Broker-Management-Channel"> + <title>Management Channels</title> + <para>The Broker can be managed over a number of different channels.</para> + <itemizedlist> + <listitem> + <para>HTTP - The primary channel for management. The HTTP interace comprises of a Web + Console and a REST API.</para> + </listitem> + <listitem> + <para>JMX - The Broker provides a JMX compilent management interface. This is not currently + undergoing further development and is retained largely for backward compatibility. It is + suggested the new users favour the Web Console/REST API.</para> + </listitem> + <listitem> + <para>AMQP - The AMQP protocols 0-8..0-10 allow for some management of Exchanges, Queue and + Bindings. This will be superceded by AMQP 1.0 Management. It is suggested that new users + favour the Management facilities provided by the Web Console/REST API.</para> + </listitem> + </itemizedlist> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="management/channels/Java-Broker-Management-Channel-HTTP.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="management/channels/Java-Broker-Management-Channel-Web-Console.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="management/channels/Java-Broker-Management-Channel-REST-API.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="management/channels/Java-Broker-Management-Channel-JMX.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="management/channels/Java-Broker-Management-Channel-AMQP-Intrinsic.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="management/channels/Java-Broker-Management-Channel-QMF.xml"/> +</chapter> + diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Management-Managing-Entities.xml b/qpid/doc/book/src/java-broker/Java-Broker-Management-Managing-Entities.xml new file mode 100644 index 0000000000..82b14fb0a7 --- /dev/null +++ b/qpid/doc/book/src/java-broker/Java-Broker-Management-Managing-Entities.xml @@ -0,0 +1,114 @@ +<?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. + +--> + +<chapter id="Java-Broker-Management-Managing-Entities"> + <title>Managing Entities</title> + <para>This section describes how to manage entities within the Broker. The principles underlying + entity management are the same regardless of entity type. For this reason, this section begins + with a general description that applies to all.</para> + <para>Since not all channels support the management of all entity type, this section commences + with a table showing which entity type is supported by each channel.</para> + + <section id="Java-Broker-Management-Managing-Entities-General"> + <title>General Description</title> + <para>The following description applies to all entities within the Broker regardless of their + type.</para> + <para> + <itemizedlist> + <listitem> + <para>All entities have a parent, and may have children. The parent of the Broker is + called the System Context. It has no parent.</para> + </listitem> + <listitem> + <para>Entities have one or more attributes. For example a <literal>name</literal>, an + <literal>id</literal> or a <literal>maximumQueueDepth</literal></para> + </listitem> + <listitem> + <para>Entities can be durable or non-durable. Durable entities survive a restart. + Non-durable entities will not.</para> + </listitem> + <listitem> + <para>Attributes may have a default value. If an attribute value is not specified the + default value is used.</para> + </listitem> + <listitem> + <para>Attributes values can be expressed as a simple value (e.g. <literal>myName</literal> + or <literal>1234</literal>), in terms of context variables + (e.g.<literal>${foo}</literal> or <literal>/data/${foo}/</literal>).</para> + </listitem> + <listitem> + <para>Each entity has own zero or more context variables.</para> + </listitem> + <listitem> + <para>The System Context entity (the ultimate ancestor of all object) has a context too. + It is read only and is populated with all Java System Properties. Thus it can be + influenced from the Broker's external environment. See <link + linkend="Java-Broker-Appendix-Environment-Variables-Qpid-Opts">QPID_OPTS </link> + environment variable.</para> + </listitem> + <listitem> + <para>When resolving an attribute's value, if the value contains a variable + (e.g.<literal>${foo}</literal>), the variable is first resolved using the entity's own + context variables. If the entity has no definition for the context variable, the + entity's parent is tried, then its grandparent and so forth, all the way until the + SystemContext is reached.</para> + </listitem> + <listitem> + <para>Some entities support state and have a lifecycle.</para> + </listitem> + </itemizedlist> + </para> + <para>What follows now is a section dedicated to each entity type. For each entity type key + features are described along with the entities key attributes, key context variables, details + of the entities lifecycle and any other operations.</para> + </section> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-Entities-Matrix.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-Broker.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-VirtualhostNodes.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-Virtualhosts.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-RemoteReplicationNodes.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-Exchanges.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-Queues.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-Ports.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-Keystores.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-Truststores.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-Group-Providers.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-Access-Control-Providers.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-Plugins-HTTP.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" + href="management/managing/Java-Broker-Management-Managing-Plugins-JMX.xml"/> +</chapter> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Miscellaneous.xml b/qpid/doc/book/src/java-broker/Java-Broker-Miscellaneous.xml index 4b3bdeb15b..c1fc9255d9 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Miscellaneous.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Miscellaneous.xml @@ -31,50 +31,73 @@ <title>JVM Installation verification</title> <section role="h2" id="Java-Broker-Miscellaneous-JVM-Verification-Windows"> <title>Verify JVM on Windows</title> - <para> - Firstly confirm that the JAVA_HOME environment variable is set correctly by typing the - following at the command prompt: - </para> + <para> Firstly confirm that the JAVA_HOME environment variable is set correctly by typing the + following at the command prompt: </para> <programlisting><![CDATA[echo %JAVA_HOME%]]></programlisting> - <para> - If JAVA_HOME is set you will see something similar to the following: - </para> - <screen><![CDATA[c:"\PROGRA~1"\Java\jdk1.6.0_24\]]> + <para> If JAVA_HOME is set you will see something similar to the following: </para> + <screen><![CDATA[c:"\PROGRA~1"\Java\jdk1.7.0_60\]]> </screen> - <para> - Then confirm that a Java installation (1.6 or higher) is available: - </para> + <para> Then confirm that a Java installation (1.7 or higher) is available: </para> <programlisting><![CDATA[java -version]]></programlisting> - <para> - If java is available on the path, output similar to the following will be seen: - </para> - <screen><![CDATA[java version "1.6.0_24" -Java(TM) SE Runtime Environment (build 1.6.0_24-b07) -Java HotSpot(TM) 64-Bit Server VM (build 19.1-b02, mixed mode)]]></screen> + <para> If java is available on the path, output similar to the following will be seen: </para> + <screen><![CDATA[java version "1.7.0_60" +Java(TM) SE Runtime Environment (build 1.7.0_60-b19) +Java HotSpot(TM) 64-Bit Server VM (build 24.60-b09, mixed mode)]]></screen> </section> <section role="h2" id="Java-Broker-Miscellaneous-JVM-Verification-Unix"> <title>Verify JVM on Unix</title> - <para> - Firstly confirm that the JAVA_HOME environment variable is set correctly by typing the - following at the command prompt: - </para> + <para> Firstly confirm that the JAVA_HOME environment variable is set correctly by typing the + following at the command prompt: </para> <programlisting><![CDATA[echo $JAVA_HOME]]></programlisting> - <para> - If JAVA_HOME is set you will see something similar to the following: - </para> - <screen><![CDATA[/usr/java/jdk1.6.0_35]]> + <para> If JAVA_HOME is set you will see something similar to the following: </para> + <screen><![CDATA[/usr/java/jdk1.7.0_60]]> </screen> - <para> - Then confirm that a Java installation (1.6 or higher) is available: - </para> + <para> Then confirm that a Java installation (1.7 or higher) is available: </para> <programlisting><![CDATA[java -version]]></programlisting> - <para> - If java is available on the path, output similar to the following will be seen: - </para> - <screen><![CDATA[java version "1.6.0_35" -Java(TM) SE Runtime Environment (build 1.6.0_35-b10-428-11M3811) -Java HotSpot(TM) 64-Bit Server VM (build 20.10-b01-428, mixed mode)]]></screen> + <para> If java is available on the path, output similar to the following will be seen: </para> + <screen><![CDATA[java version "1.7.0_60" +Java(TM) SE Runtime Environment (build 1.7.0_60-b19) +Java HotSpot(TM) 64-Bit Server VM (build 24.60-b09, mixed mode)]]></screen> </section> </section> + <section role="h2" id="Java-Broker-Miscellaneous-Installing-External-JDBC-Driver"> + <title>Installing External JDBC Driver</title> + <para>In order to use a JDBC Virtualhost Node or a JDBC Virtualhost, you must make the + Database's JDBC 4.0 compatible drivers available on the Broker's classpath. To do this copy + the driver's JAR file into the <literal>${QPID_HOME}/lib/opt</literal> folder.</para> + <programlisting>Unix: +cp <literal>driver</literal>.jar qpid-broker-&qpidCurrentRelease;/lib/opt</programlisting> + + <programlisting>Windows: +copy <literal>driver</literal>.jar qpid-broker-&qpidCurrentRelease;\lib\opt</programlisting> + + </section> + <section role="h2" id="Java-Broker-Miscellaneous-Installing-Oracle-BDB-JE"> + <title>Installing Oracle BDB JE</title> + <para> The Oracle BDB JE is not distributed with Apache Qpid owing to license considerations.. </para> + <para>If you wish to use a BDB Virtualhost Node, BDB Virtualhost, or BDB HA Virtualhost Node you + must make the BDB JE's JDBC 4.0 compatible drivers= available on the Broker's classpath. </para> + <para> Download the Oracle BDB JE &oracleBdbProductVersion; release <ulink + url="&oracleJeDownloadUrl;">from the Oracle website.</ulink> + </para> + <para> The download has a name in the form je-&oracleBdbProductVersion;.tar.gz. It is + recommended that you confirm the integrity of the download by verifying the MD5. </para> + <para>Copy the je-&oracleBdbProductVersion;.jar from within the release into + <literal>${QPID_HOME}/lib/opt</literal> folder.</para> + + <programlisting>Unix: +cp je-&oracleBdbProductVersion;.jar qpid-broker-&qpidCurrentRelease;/lib/opt</programlisting> + + <programlisting>Windows: +copy je-&oracleBdbProductVersion;.jar qpid-broker-&qpidCurrentRelease;\lib\opt</programlisting> + + </section> + + + + + + + </chapter> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml b/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml deleted file mode 100644 index 37d675eacc..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Ports.xml +++ /dev/null @@ -1,92 +0,0 @@ -<?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. - ---> - -<chapter id="Java-Broker-Ports"> - <title>Broker Ports</title> - <para>This section guides through the process of configuring of Broker AMQP and non-AMQP ports.</para> - - <section id="Java-Broker-Ports-Configuring"> - <title>Configuring Broker Ports</title> - <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 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 - on Port name in the Broker object tree or after clicking on a Port row in the Ports grid on the Broker tab.</para></listitem> - <listitem><para>An existing Port can be edited by clicking on "Edit" button on the Port tab.</para></listitem> - <listitem><para>An existing Port can be deleted by clicking on "Delete Port" button - on Broker tab or "Delete" button on the Port tab.</para></listitem> - </itemizedlist> - </para> - - <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 (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> - 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> - - <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 for Ports 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> - 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> - Following deletion of an active HTTP or JMX 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> - -</chapter> 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 deleted file mode 100644 index bde97f1a36..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Queues-OtherTypes.xml +++ /dev/null @@ -1,471 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!DOCTYPE entities [ -<!ENTITY % entities SYSTEM "commonEntities.xml"> -%entities; -]> -<!-- - - 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-Queues-OtherTypes"> - <title>Queue Types</title> - - <section role="h2" id="Java-Broker-Queues-OtherTypes-Introduction"> - <title>Introduction</title> - <para> In addition to the standard queue type where messages are delivered in the same order - that they were sent, the Java Broker supports three additional queue types which allows for - alternative delivery behaviours. These are - <link linkend="Java-Broker-Queues-OtherTypes-Priority">priority-queues</link>, - <link linkend="Java-Broker-Queues-OtherTypes-Sorted">sorted-queues</link>-, - <link linkend="Java-Broker-Queues-OtherTypes-LVQ">last-value-queues</link> (LVQs). - Additionally, Java Broker supports <link linkend="Java-Broker-Queues-OtherTypes-Message-Grouping">message grouping</link>. - </para> - <para> In the following sections, the semantics of each queue type is described, followed by a - description of how instances of these queue can be created via <link - linkend="Java-Broker-Queues-OtherTypes-CreateUsingConfig">configuration</link>, <link - linkend="Java-Broker-Queues-OtherTypes-CreateUsingJmsOrJmx">programmatically</link> or - <link linkend="Java-Broker-Queues-OtherTypes-CreateUsingManagement">Web Management Console</link>.</para> - <para>The final section discusses the importance of using a <link - linkend="Java-Broker-Queues-OtherTypes-SetLowPrefetch">low client pre-fetch</link> with these queued. - </para> - </section> - - <section role="h2" id="Java-Broker-Queues-OtherTypes-Priority"> - <title>Priority Queues</title> - <para>In a priority queue, messages on the queue are delivered in an order determined by the - <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#getJMSPriority()">JMS priority message - header</ulink> within the message. By default Qpid supports the 10 priority levels mandated - by JMS, with priority value 0 as the lowest priority and 9 as the highest. </para> - <para>It is possible to reduce the effective number of priorities if desired.</para> - <para>JMS defines the <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#DEFAULT_PRIORITY"> - default message priority</ulink> as 4. Messages sent without a specified priority use this - default. </para> - </section> - <section role="h2" id="Java-Broker-Queues-OtherTypes-Sorted"> - <title>Sorted Queues</title> - <para>Sorted queues allow the message delivery order to be determined by value of an arbitrary - <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#getStringProperty()">JMS message - property</ulink>. Sort order is alpha-numeric and the property value must have a type - java.lang.String.</para> - <para>Messages sent to a sorted queue without the specified JMS message property will be - inserted into the 'last' position in the queue.</para> - </section> - <section role="h2" id="Java-Broker-Queues-OtherTypes-LVQ"> - <title>Last Value Queues (LVQ)</title> - <para>LVQs (or conflation queues) are special queues that automatically discard any message when - a newer message arrives with the same key value. The key is specified by arbitrary <ulink - url="&oracleJeeDocUrl;javax/jms/Message.html#getPropertyNames()">JMS message - property</ulink>.</para> - <para>An example of an LVQ might be where a queue represents prices on a stock exchange: when - you first consume from the queue you get the latest quote for each stock, and then as new - prices come in you are sent only these updates. </para> - <para>Like other queues, LVQs can either be browsed or consumed from. When browsing an - individual subscriber does not remove the message from the queue when receiving it. This - allows for many subscriptions to browse the same LVQ (i.e. you do not need to create and bind - a separate LVQ for each subscriber who wishes to receive the contents of the LVQ).</para> - <para>Messages sent to an LVQ without the specified property will be delivered as normal and - will never be "replaced".</para> - </section> - <section role="h2" id="Java-Broker-Queues-OtherTypes-Create"> - <title>Creating a Priority, Sorted or LVQ Queue</title> - <para>To create a priority, sorted or LVQ queue, it can be defined in the virtualhost - configuration file, can be created programmtically from a client via AMQP (using - an extension to JMS), using JMX, using REST interfaces or created in Web Management Console. - These methods are described below. </para> - <para>Once a queue is created you cannot change its type (without deleting it and re-creating). - Also note you cannot currently mix the natures of these queue types, for instance, you cannot - define a queue which it both an LVQ and a priority-queue.</para> - <section role="h2" id="Java-Broker-Queues-OtherTypes-CreateUsingManagement"> - <title>Using Web Management Console</title> - <para>On clicking on "Add Queue" button on Virtual Host tab the pop-up dialog to create a queue is displayed.</para> - <para>For a Simple queue a Queue Type "Standard" should be selected</para> - <para>For a Priority queue a Queue Type "Priority" and the priority value (10 by default) should be selected.</para> - <para>For a Sorted queue a Queue Type "Sorted" and Sort Message Property should be specified.</para> - <para>For a LVQ queue a Queue Type "LVQ" and LVQ Message Property should be specified.</para> - <para>Additionally, for each type of the queue Flow Control Thresholds and Alert Thresholds can be specified in optional fields.</para> - <para>Also, a Dead Letter Queue can be configured for the Queue by checking "Create DLQ" check box. - The maximum number of delivery retries before message is sent to the DLQ can be specified in "Maximum Delivery Retries" field. - 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-CreateUsingJmsOrJmx"> - <title>Using JMX or AMQP</title> - <para>To create a priority, sorted or LVQ queue programmatically from JMX or using a Qpid - extension to JMS, pass the appropriate queue-declare arguments.</para> - <table> - <title>Queue-declare arguments understood for priority, sorted and LVQ queues</title> - <tgroup cols="4"> - <thead> - <row> - <entry>Queue type</entry> - <entry>Argument name</entry> - <entry>Argument name</entry> - <entry>Argument Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>priority</entry> - <entry>x-qpid-priorities</entry> - <entry>java.lang.Integer</entry> - <entry>Specifies a priority queue with given number priorities</entry> - </row> - <row> - <entry>sorted</entry> - <entry>qpid.queue_sort_key</entry> - <entry>java.lang.String</entry> - <entry>Specifies sorted queue with given message property used to sort the - entries</entry> - </row> - <row> - <entry>lvq</entry> - <entry>qpid.last_value_queue_key</entry> - <entry>java.lang.String</entry> - <entry>Specifies lvq queue with given message property used to conflate the - entries</entry> - </row> - </tbody> - </tgroup> - </table> - <para>The following example illustrates the creation of the a LVQ queue from a - javax.jms.Session object. Note that this utilises a Qpid specific extension to JMS and - involves casting the session object back to its Qpid base-class.</para> - <example> - <title>Creation of an LVQ using the Qpid extension to JMS</title> - <programlisting><![CDATA[Map<String,Object> arguments = new HashMap<String, Object>(); -arguments.put("qpid.last_value_queue_key","ISIN"); -AMQDestination amqQueue = (AMQDestination) context.lookup("myqueue"); -((AMQSession<?,?>) session).createQueue( - AMQShortString.valueOf(amqQueue.getQueueName()), - amqQueue.isAutoDelete(), - amqQueue.isDurable(), - amqQueue.isExclusive(), - arguments); -]]></programlisting> - - </example> - <para> The following example illustrates the creation of the sorted queue from a the JMX - interface using the ManagedBroker interface. </para> - <example> - <title>Creation of a sorted queue using JMX</title> - <programlisting><![CDATA[Map<String, Object> environment = new HashMap<String, Object>(); -environment.put(JMXConnector.CREDENTIALS, new String[] {"admin","password"}); -// Connect to service -JMXServiceURL url = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://localhost:8999/jmxrmi"); -JMXConnector jmxConnector = JMXConnectorFactory.connect(url, environment); -MBeanServerConnection mbsc = jmxConnector.getMBeanServerConnection(); -// Object name for ManagedBroker for virtualhost myvhost -ObjectName objectName = new ObjectName("org.apache.qpid:type=VirtualHost.VirtualHostManager,VirtualHost=myvhost"); -// Get the ManagedBroker object -ManagedBroker managedBroker = JMX.newMBeanProxy(mbsc, objectName, ManagedBroker.class);; - -// Create the queue passing arguments -Map<String,Object> arguments = new HashMap<String, Object>(); -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-Binding"> - <title>Binding queues to exchanges</title> - <para>Queues can be bound to the broker exchanges in the virtualhost - configuration file or programmtically from a client using AMQP bind API (using - an extension to JMS), using JMX API, using REST interfaces or Web Management Console.</para> - <para>A queue can be bound to different exchanges at the same time. - Also, a queue can be bound to the same exchange multiple times. - Differenent binding keys can be used to bind a queue to the same topic or direct exchanges.</para> - <para>Binding attributes can be specified on binding creation to allow filtering of messages accepted by the queue using a selector expression - or/and specifying whether messages published by its own connection should be delivered to it.</para> - <section role="h3" id="Java-Broker-Queues-OtherTypes-BindingUsingManagement"> - <title>Using Web Management Console</title> - <para>A queue can be bound to an exchange by clicking on "Add Binding" button on a Queue tab or an Exchange tab.</para> - </section> - <section role="h3" id="Java-Broker-Queues-OtherTypes-BindingUsingJmsOrJmx"> - <title>Using JMX or AMQP</title> - <para>The following example illustrates the creation of queue binding to topic exchange with JMS client.</para> - <example> - <title>Binding a queue using JMS</title> - <programlisting><![CDATA[ConnectionFactory connectionFactory = ... -Connection connection = connectionFactory.createConnection(); -AMQSession<?, ?> session = (AMQSession<?,?>)connection.createSession(false, Session.AUTO_ACKNOWLEDGE); - -... - -AMQShortString queueName = new AMQShortString("testQueue"); -AMQShortString routingKey = new AMQShortString("testRoutingKey"); -AMQDestination destination = (AMQDestination) session.createQueue(queueName.asString()); - -... - -// binding arguments -Map<String, Object> arguments = new HashMap<String, Object>(); -arguments.put("x-filter-jms-selector", "application='app1'"); - -// create binding -session.bindQueue(queueName, routingKey, FieldTable.convertToFieldTable(arguments), - new AMQShortString("amq.topic"), destination);]]></programlisting> - </example> - <para> The following example illustrates the creation of queue binding to topic exchange with JMX - interface using the ManagedExchange interface. </para> - <example> - <title>Binding a queue using JMX</title> - <programlisting><![CDATA[Map<String, Object> environment = new HashMap<String, Object>(); -environment.put(JMXConnector.CREDENTIALS, new String[] {"admin","password"}); - -// Connect to service -JMXServiceURL url = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://localhost:8999/jmxrmi"); -JMXConnector jmxConnector = JMXConnectorFactory.connect(url, environment); -MBeanServerConnection mbsc = jmxConnector.getMBeanServerConnection(); - -// Object name for topic Exchange MBean for virtualhost 'default' -ObjectName objectName = new ObjectName("org.apache.qpid:type=VirtualHost.Exchange," - + "VirtualHost=\"default\",name=\"amq.topic\",ExchangeType=topic"); - -// Get the ManagedExchange object -ManagedExchange topicExchange = JMX.newMBeanProxy(mbsc, objectName, ManagedExchange.class);; - -// Create the binding arguments -Map<String,Object> arguments = new HashMap<String, Object>(); -arguments.put("x-filter-jms-selector", "application='app1'"); - -// create binding -topicExchange.createNewBinding("queue", "testBindingKey", arguments);]]></programlisting> - </example> - </section> - <section role="h3" id="Java-Broker-Queues-OtherTypes-BindingUsingConfig"> - <title>Using configuration</title> - <para>How to bind queues in the Virtual Host configuration file is shown in <xref linkend="Java-Broker-Virtual-Host-Binding-Queue"/>.</para> - </section> - </section> - - <section role="h2" id="Java-Broker-Queues-OtherTypes-Message-Grouping"> - <title> - Messaging Grouping - </title> - <para> - The broker allows messaging applications to classify a set of related messages as - belonging to a group. This allows a message producer to indicate to the consumer - that a group of messages should be considered a single logical operation with - respect to the application. - </para> - <para> - The broker can use this group identification to enforce policies controlling how - messages from a given group can be distributed to consumers. For instance, the - broker can be configured to guarantee all the messages from a particular group are - processed in order across multiple consumers. - </para> - <para> - For example, assume we have a shopping application that manages items in a virtual - shopping cart. A user may add an item to their shopping cart, then change their - mind and remove it. If the application sends an <emphasis>add</emphasis> message to the broker, - immediately followed by a <emphasis>remove</emphasis> message, they will be queued in the proper - order - <emphasis>add</emphasis>, followed by <emphasis>remove</emphasis>. - </para> - <para> - However, if there are multiple consumers, it is possible that once a consumer - acquires the <emphasis>add</emphasis> message, a different consumer may acquire the - <emphasis>remove</emphasis> message. This allows both messages to be processed in parallel, - which could result in a "race" where the <emphasis>remove</emphasis> operation is incorrectly - performed before the <emphasis>add</emphasis> operation. - </para> - <section role="h3" id="Java-Broker-Queues-OtherTypes-GroupingMessages"> - <title> - Grouping Messages - </title> - <para> - In order to group messages, the application would designate a particular - message header as containing a message's <emphasis>group identifier</emphasis>. The group - identifier stored in that header field would be a string value set by the message - producer. Messages from the same group would have the same group identifier - value. The key that identifies the header must also be known to the message - consumers. This allows the consumers to determine a message's assigned group. - </para> - <para> - The header that is used to hold the group identifier, as well as the values used - as group identifiers, are totally under control of the application. - </para> - </section> - <section role="h3" id="Java-Broker-Queues-OtherTypes-BrokerRole"> - <title> - The Role of the Broker in Message Grouping - </title> - <para> - The broker will apply the following processing on each grouped message: - <itemizedlist> - <listitem>Enqueue a received message on the destination queue.</listitem> - <listitem>Determine the message's group by examining the message's group identifier header.</listitem> - <listitem>Enforce <emphasis>consumption ordering</emphasis> among messages belonging - to the same group. <emphasis>Consumption ordering</emphasis> means one of two things - depending on how the queue has been configured. - <itemizedlist> - <listitem> - In default mode, a group gets assigned to a single consumer for - the lifetime of that consumer, and the broker will pass all subsequent messages in - the group to that consumer. - </listitem> - <listitem> - In 'shared groups' mode (which gives the same behaviour - as the Qpid C++ Broker) the broker enforces a looser guarantee, namely that all the - <emphasis>currently unacknowledged messages</emphasis> in a group are sent to the - same consumer, but the consumer used may change over time even if the consumers do not. - This means that only one consumer can be processing messages from a particular group at - any given time, however if the consumer acknowledges all of its acquired messages then - the broker <emphasis>may</emphasis> pass the next pending message in that group to a - different consumer. - </listitem> - </itemizedlist> - </listitem> - </itemizedlist> - </para> - <para> - The absence of a value in the designated group header field of a message is treated as follows: - <itemizedlist> - <listitem> - In default mode, failure for a message to specify a group is treated as a desire for the message - not to be grouped at all. Such messages will be distributed to any available consumer, without - the ordering quarantees imposed by grouping. - </listitem> - <listitem> - In 'shared groups' mode (which gives the same behaviour as the Qpid C++ Broker) the broker assigns messages - without a group value to a 'default group'. Therefore, all such "unidentified" messages are considered by - the broker as part of the same group, which will handled like any other group. The name of - this default group is "qpid.no-group", although it can be customised as detailed below. - </listitem> - </itemizedlist> - </para> - <para> - Note that message grouping has no effect on queue browsers. - </para> - <para> - Note well that distinct message groups would not block each other from delivery. - For example, assume a queue contains messages from two different message groups - - say group "A" and group "B" - and they are enqueued such that "A"'s messages are - in front of "B". If the first message of group "A" is in the process of being - consumed by a client, then the remaining "A" messages are blocked, but the - messages of the "B" group are available for consumption by other consumers - even - though it is "behind" group "A" in the queue. - </para> - </section> - <section role="h3" id="Java-Broker-Queues-OtherTypes-BrokerConfig"> - <title> - Broker Message Grouping Configuration - </title> - <para> - In order for the broker to determine a message's group, the key for the header - that contains the group identifier must be provided to the broker via - configuration. This is done on a per-queue basis, when the queue is first - configured. - </para> - <para> - This means that message group classification is determined by the message's destination - queue. - </para> - <para> - Specifically, the queue "holds" the header key that is used to find the message's - group identifier. All messages arriving at the queue are expected to use the same - header key for holding the identifer. Once the message is enqueued, the broker - looks up the group identifier in the message's header, and classifies the message - by its group. - </para> - <para> - Message group support is specified by providing one or more of the following settings - in the arguments map that is used when declaring the queue (e.g. when calling - <code>AMQSession.createQueue()</code>). - <table> - <title>Queue Declare Message Group Configuration Arguments</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Key</entry> - <entry>Value</entry> - </row> - </thead> - <tbody> - <row> - <entry>qpid.group_header_key</entry> - <entry>The name of the message header that holds the group identifier value. - The values in this header may be of any supported type (i.e. not just strings). - </entry> - </row> - <row> - <entry>qpid.shared_msg_group</entry> - <entry>Provide a value of "1" to switch on - <link linkend="Java-Broker-Queues-OtherTypes-BrokerRole">'shared groups' mode</link>.</entry> - </row> - <row> - <entry>qpid.default_msg_group</entry> - <entry>The value to use as the default group when operating in - <link linkend="Java-Broker-Queues-OtherTypes-BrokerRole">'shared groups' mode</link>.</entry> - </row> - </tbody> - </tgroup> - </table> - </para> - <para> - The default group for groups operating in 'shared groups' mode can be updated broker-wide using a system property as follows, - however do note that the queue declaration argument detailed above takes precedence: - </para> - <para> - -Dqpid.broker_default-shared-message-group="your.default.shared.group" - </para> - <para> - It is important to note that there is no need to provide the actual group - identifer values that will be used. The broker learns these values as messages are - received. Also, there is no practical limit - aside from resource limitations - - to the number of different groups that the broker can track at run time. - </para> - </section> - </section> - - <section role="h2" id="Java-Broker-Queues-OtherTypes-SetLowPrefetch"> - <title>Using low pre-fetch with special queue types</title> - <para>Qpid clients receive buffered messages in batches, sized according to the pre-fetch value. - The current default is 500. </para> - <para>However, if you use the default value you will probably <emphasis>not</emphasis> see - desirable behaviour when using priority, sorted, lvq or grouped queues. Once the broker has sent a - message to the client its delivery order is then fixed, regardless of the special behaviour of - the queue. </para> - <para>For example, if using a priority queue and a prefetch of 100, and 100 messages arrive with - priority 2, the broker will send these messages to the client. If then a new message arrives - will priority 1, the broker cannot leap frog messages of lower priority. The priority 1 will - be delivered at the front of the next batch of messages to be sent to the client.</para> - <para> So, you need to set the prefetch values for your client (consumer) to make this sensible. - To do this set the Java system property <varname>max_prefetch</varname> on the client - environment (using -D) before creating your consumer. </para> - <para>A default for all client connections can be set via a system property: </para> - <programlisting> --Dmax_prefetch=1 -</programlisting> - <para> The prefetch can be also be adjusted on a per connection basis by adding a - <varname>maxprefetch</varname> value to the <ulink url="&qpidjmsdocClientConectionUrl;">Connection URLs</ulink> - </para> - <programlisting> -amqp://guest:guest@client1/development?maxprefetch='1'&brokerlist='tcp://localhost:5672' -</programlisting> - <para>Setting the Qpid pre-fetch to 1 will give exact queue-type semantics as perceived by the - client however, this brings a performance cost. You could test with a slightly higher - pre-fetch to trade-off between throughput and exact semantics.</para> - </section> -</section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Background-Recovery.xml index cf9d9497dd..e5a87df190 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Other-Tooling.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Background-Recovery.xml @@ -20,7 +20,7 @@ --> -<section id="Java-Broker-Configuring-And-Managing-Other-Tooling"> -<title>Other Tooling</title> - +<section id="Java-Broker-Runtime-Background-Recovery"> + <title>Background Recovery</title> + <para>TODO-QPID-5907</para> </section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control.xml index cf7660aed7..bc279157c2 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Disk-Space-Management-Producer-Flow-Control.xml @@ -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)/test)/ch:1] [con:2(guest@anonymous(713 <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)/test)/ch:1] [con:2(guest@anonymous(713 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)/test)/ch:1] [con:2(guest@anonymous(713 <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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Flow-To-Disk.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Flow-To-Disk.xml new file mode 100644 index 0000000000..f2dbb162e1 --- /dev/null +++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Flow-To-Disk.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml index 7ee4b7a5cd..fe42cf0203 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Handling-Undeliverable-Messages.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml index dc5a5b510d..23d84ac1de 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Log-Files.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml index 8ef8528ee1..2813274c61 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime-Producer-Transaction-Timeout.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml b/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml index 6eaa6a1ca0..6394ad4d2b 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Runtime.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml index 1ad7f6715c..d0dcd18279 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-ACLs.xml @@ -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 diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml index 538d08d8e9..817c8f2621 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-Authentication-Providers.xml @@ -26,113 +26,136 @@ <section id="Java-Broker-Security-Authentication-Providers"> <title>Authentication Providers</title> - <para> - In order to successfully establish a connection to the Java Broker, the connection must be - authenticated. The Java Broker supports a number of different authentication schemes, each - with its own "authentication provider". Any number of Authentication Providers can be configured - on the Broker at the same time. - </para> - - <para> - The Authentication Providers can be configured using <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> - and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>. - </para> - - <para>The following Authentication Provider managing operations are available from Web Management Console: - <itemizedlist> - <listitem><para>A new Authentication Provider can be added by clicking onto "Add Provider" on the Broker tab.</para></listitem> - <listitem><para>An Authentication Provider details can be viewed on the Authentication Provider tab. - The tab is displayed after clicking onto Authentication Provider name in the Broker object tree or after clicking - onto Authentication Provider row in Authentication Providers grid on the Broker tab.</para></listitem> - <listitem><para>Editing of Authentication Provider can be performed by clicking on "Edit" button - on Authentication Provider tab.</para></listitem> - <listitem><para>An existing Authentication Provider can be deleted by clicking on "Delete Provider" button - on Broker tab or "Delete" button on the Authentication Provider tab.</para></listitem> - </itemizedlist> - The Authentication Provider type and name cannot be changed for existing providers as editing of name and type - is unsupported at the moment. Only provider specific attributes can be modified in the editing dialog - and stored in the broker configuration store. - </para> + + <para>TODO SCRAM-SHA</para> + <para> In order to successfully establish a connection to the Java Broker, the connection must be + authenticated. The Java Broker supports a number of different authentication schemes, each with + its own "authentication provider". Any number of Authentication Providers can be configured on + the Broker at the same time. </para> + + <para> The Authentication Providers can be configured using <link + linkend="Java-Broker-Management-Channel-REST-API">REST Management interfaces</link> and <link + linkend="Java-Broker-Management-Channel-Web-Console">Web Management Console</link>. </para> + + <para>The following Authentication Provider managing operations are available from Web Management + Console: <itemizedlist> + <listitem> + <para>A new Authentication Provider can be added by clicking onto "Add Provider" on the + Broker tab.</para> + </listitem> + <listitem> + <para>An Authentication Provider details can be viewed on the Authentication Provider tab. + The tab is displayed after clicking onto Authentication Provider name in the Broker object + tree or after clicking onto Authentication Provider row in Authentication Providers grid + on the Broker tab.</para> + </listitem> + <listitem> + <para>Editing of Authentication Provider can be performed by clicking on "Edit" button on + Authentication Provider tab.</para> + </listitem> + <listitem> + <para>An existing Authentication Provider can be deleted by clicking on "Delete Provider" + button on Broker tab or "Delete" button on the Authentication Provider tab.</para> + </listitem> + </itemizedlist> The Authentication Provider type and name cannot be changed for existing + providers as editing of name and type is unsupported at the moment. Only provider specific + attributes can be modified in the editing dialog and stored in the broker configuration store. </para> <important> - Only unused Authentication Provider can be deleted. For delete requests attempting to delete Authentication Provider - associated with the Ports, the errors will be returned and delete operations will be aborted. It is possible to change - the Authentication Provider on Port at runtime. However, the Broker restart is required for changes on Port to take effect. + <para> Only unused Authentication Provider can be deleted. For delete requests attempting to + delete Authentication Provider associated with the Ports, the errors will be returned and + delete operations will be aborted. It is possible to change the Authentication Provider on + Port at runtime. However, the Broker restart is required for changes on Port to take effect. + </para> </important> <section id="Java-Broker-Security-LDAP-Provider"> - <title>Simple LDAP Authentication Provider</title> - - <para> - SimpleLDAPAuthenticationProvider authenticates connections against a Directory (LDAP). - </para> - <para> - To create a SimpleLDAPAuthenticationProvider the following mandatory fields are required: - <itemizedlist> - <listitem><para><emphasis>LDAP server URL</emphasis> is the URL of the server, for example, <literal>ldaps://example.com:636</literal></para></listitem> - <listitem><para><emphasis>Search context</emphasis> is the distinguished name of the search base object. It defines the location from which - the search for users begins, for example, <literal>dc=users,dc=example,dc=com</literal></para></listitem> - <listitem><para><emphasis>Search filter</emphasis> is a DN template to find an LDAP user entry by provided user name, for example, <literal>(uid={0})</literal></para></listitem> - </itemizedlist> - Additionally, the following optional fields can be specified: - <itemizedlist> - <listitem><para><emphasis>LDAP context factory</emphasis> is a fully qualified class name for the JNDI LDAP context factory. - This class must implement the <ulink url="&oracleJdkDocUrl;javax/naming/spi/InitialContextFactory.html">InitialContextFactory</ulink> - interface and produce instances of <ulink url="&oracleJdkDocUrl;javax/naming/directory/DirContext.html">DirContext</ulink>. - If not specified a default value of <literal>com.sun.jndi.ldap.LdapCtxFactory</literal> is used.</para></listitem> - <listitem><para><emphasis>LDAP authentication URL</emphasis> is the URL of LDAP server for performing "ldap bind". If not - specified, the <emphasis>LDAP server URL</emphasis> will be used for both searches and authentications.</para></listitem> - <listitem><para><emphasis>Truststore name</emphasis> is a name of <link linkend="SSL-Truststore-ClientCertificate">configured truststore</link>. - Use this if connecting to a Directory over SSL (i.e. ldaps://) which is protected by a certificate signed by a private CA (or - utilising a self-signed certificate).</para></listitem> - </itemizedlist> - </para> - - <important> - In order to protect the security of the user's password, when using LDAP authentication, you must: - <itemizedlist> - <listitem><para>Use SSL on the broker's AMQP, JMX, and HTTP ports to protect the password during - transmission to the Broker.</para></listitem> - <listitem><para>Authenticate to the Directory using SSL (i.e. ldaps://) to protect the password - during transmission from the Broker to the Directory.</para></listitem> - </itemizedlist> - </important> + <title>Simple LDAP Authentication Provider</title> + + <para> SimpleLDAPAuthenticationProvider authenticates connections against a Directory (LDAP). </para> + <para> To create a SimpleLDAPAuthenticationProvider the following mandatory fields are required: <itemizedlist> + <listitem> + <para><emphasis>LDAP server URL</emphasis> is the URL of the server, for example, + <literal>ldaps://example.com:636</literal></para> + </listitem> + <listitem> + <para><emphasis>Search context</emphasis> is the distinguished name of the search base + object. It defines the location from which the search for users begins, for example, + <literal>dc=users,dc=example,dc=com</literal></para> + </listitem> + <listitem> + <para><emphasis>Search filter</emphasis> is a DN template to find an LDAP user entry by + provided user name, for example, <literal>(uid={0})</literal></para> + </listitem> + </itemizedlist> Additionally, the following optional fields can be specified: <itemizedlist> + <listitem> + <para><emphasis>LDAP context factory</emphasis> is a fully qualified class name for the + JNDI LDAP context factory. This class must implement the <ulink + url="&oracleJdkDocUrl;javax/naming/spi/InitialContextFactory.html" + >InitialContextFactory</ulink> interface and produce instances of <ulink + url="&oracleJdkDocUrl;javax/naming/directory/DirContext.html">DirContext</ulink>. If + not specified a default value of <literal>com.sun.jndi.ldap.LdapCtxFactory</literal> is + used.</para> + </listitem> + <listitem> + <para><emphasis>LDAP authentication URL</emphasis> is the URL of LDAP server for + performing "ldap bind". If not specified, the <emphasis>LDAP server URL</emphasis> will + be used for both searches and authentications.</para> + </listitem> + <listitem> + <para><emphasis>Truststore name</emphasis> is a name of <link + linkend="Java-Broker-Management-Managing-Truststores-Attributes">configured + truststore</link>. Use this if connecting to a Directory over SSL (i.e. ldaps://) + which is protected by a certificate signed by a private CA (or utilising a self-signed + certificate).</para> + </listitem> + </itemizedlist> + </para> - <para> - The LDAP Authentication Provider works in the following manner. It first connects to the Directory anonymously - and searches for the ldap entity which is identified by the username. The search begins at the distinguished name - identified by <literal>Search Context</literal> and uses the username as a filter. The search scope is sub-tree - meaning the search will include the base object and the subtree extending beneath it. - </para> - - <para> - If the search returns a match, the Authentication Provider then attempts to bind to the LDAP server with the given - name and the password. Note that - <ulink url="&oracleJdkDocUrl;javax/naming/Context.html#SECURITY_AUTHENTICATION">simple security authentication</ulink> - is used so the Directory receives the password in the clear. - </para> + <important> + <para>In order to protect the security of the user's password, when using LDAP authentication, + you must: </para> + <itemizedlist> + <listitem> + <para>Use SSL on the broker's AMQP, JMX, and HTTP ports to protect the password during + transmission to the Broker.</para> + </listitem> + <listitem> + <para>Authenticate to the Directory using SSL (i.e. ldaps://) to protect the password + during transmission from the Broker to the Directory.</para> + </listitem> + </itemizedlist> + </important> + + <para> The LDAP Authentication Provider works in the following manner. It first connects to the + Directory anonymously and searches for the ldap entity which is identified by the username. + The search begins at the distinguished name identified by <literal>Search Context</literal> + and uses the username as a filter. The search scope is sub-tree meaning the search will + include the base object and the subtree extending beneath it. </para> + + <para> If the search returns a match, the Authentication Provider then attempts to bind to the + LDAP server with the given name and the password. Note that <ulink + url="&oracleJdkDocUrl;javax/naming/Context.html#SECURITY_AUTHENTICATION">simple security + authentication</ulink> is used so the Directory receives the password in the clear. </para> </section> <section id="Java-Broker-Security-Kerberos-Provider"> - <title>Kerberos</title> + <title>Kerberos</title> - <para> - Kereberos Authentication Provider uses java GSS-API SASL mechanism to authenticate the connections. - </para> + <para> Kereberos Authentication Provider uses java GSS-API SASL mechanism to authenticate the + connections. </para> - <para> - Configuration of kerberos is done through system properties (there doesn't seem to be a way - around this unfortunately). - </para> + <para> Configuration of kerberos is done through system properties (there doesn't seem to be a + way around this unfortunately). </para> - <programlisting> + <programlisting> export JAVA_OPTS=-Djavax.security.auth.useSubjectCredsOnly=false -Djava.security.auth.login.config=qpid.conf ${QPID_HOME}/bin/qpid-server </programlisting> - <para>Where qpid.conf would look something like this:</para> + <para>Where qpid.conf would look something like this:</para> - <programlisting><![CDATA[ + <programlisting><![CDATA[ com.sun.security.jgss.accept { com.sun.security.auth.module.Krb5LoginModule required useKeyTab=true @@ -145,109 +168,95 @@ com.sun.security.jgss.accept { principal="<name>/<host>"; };]]></programlisting> - <para> - Where realm, kdc, keyTab and principal should obviously be set correctly for the environment - where you are running (see the existing documentation for the C++ broker about creating a keytab - file). - </para> + <para> Where realm, kdc, keyTab and principal should obviously be set correctly for the + environment where you are running (see the existing documentation for the C++ broker about + creating a keytab file). </para> - <para> - Note: You may need to install the "Java Cryptography Extension (JCE) Unlimited Strength - Jurisdiction Policy Files" appropriate for your JDK in order to get Kerberos support working. - </para> + <para> Note: You may need to install the "Java Cryptography Extension (JCE) Unlimited Strength + Jurisdiction Policy Files" appropriate for your JDK in order to get Kerberos support working. </para> - <para> - Since Kerberos support only works where SASL authentication is available (e.g. not for JMX - authentication) you may wish to also include an alternative Authentication Provider - configuration, and use this for JMX and HTTP ports. - </para> + <para> Since Kerberos support only works where SASL authentication is available (e.g. not for + JMX authentication) you may wish to also include an alternative Authentication Provider + configuration, and use this for JMX and HTTP ports. </para> </section> <section id="Java-Broker-Security-External-Provider"> <title>External (SSL Client Certificates)</title> - <para> - When <link linkend="SSL-Truststore-ClientCertificate"> requiring SSL Client Certificates</link> be - presented the External Authentication Provider can be used, such that the user is authenticated based on - trust of their certificate alone, and the X500Principal from the SSL session is then used as the username - for the connection, instead of also requiring the user to present a valid username and password. - </para> + <para> When <link linkend="Java-Broker-Management-Managing-Truststores"> requiring SSL Client + Certificates</link> be presented the External Authentication Provider can be used, such that + the user is authenticated based on trust of their certificate alone, and the X500Principal + from the SSL session is then used as the username for the connection, instead of also + requiring the user to present a valid username and password. </para> <para> - <emphasis role="bold">Note:</emphasis> The External Authentication Provider should typically only be used on the - AMQP ports, in conjunction with <link linkend="SSL-Truststore-ClientCertificate">SSL client certificate - authentication</link>. It is not intended for other uses such as the JMX management port and will treat any - non-sasl authentication processes on these ports as successful with the given username. As such you should - configure another Authentication Provider for use on non-AMQP ports. Perhaps the only exception to this - would be where the broker is embedded in a container that is itself externally protecting the HTTP interface - and then providing the remote users name. - </para> - - <para>On creation of External Provider the use of full DN or username CN as a principal name can be configured. - If field "Use the full DN as the Username" is set to "true" the full DN is used as an authenticated principal name. - If field "Use the full DN as the Username" is set to "false" the user name CN part is used as the authenticated principal name. - Setting the field to "false" is particular useful when <link linkend="Java-Broker-Security-ACLs">ACL</link> is required, - as at the moment, ACL does not support commas in the user name. - </para> + <emphasis role="bold">Note:</emphasis> The External Authentication Provider should typically + only be used on the AMQP ports, in conjunction with <link + linkend="Java-Broker-Management-Managing-Ports">SSL client certificate + authentication</link>. It is not intended for other uses such as the JMX management port and + will treat any non-sasl authentication processes on these ports as successful with the given + username. As such you should configure another Authentication Provider for use on non-AMQP + ports. Perhaps the only exception to this would be where the broker is embedded in a container + that is itself externally protecting the HTTP interface and then providing the remote users + name. </para> + + <para>On creation of External Provider the use of full DN or username CN as a principal name can + be configured. If field "Use the full DN as the Username" is set to "true" the full DN is used + as an authenticated principal name. If field "Use the full DN as the Username" is set to + "false" the user name CN part is used as the authenticated principal name. Setting the field + to "false" is particular useful when <link linkend="Java-Broker-Security-ACLs">ACL</link> is + required, as at the moment, ACL does not support commas in the user name. </para> </section> <section id="Java-Broker-Security-Anonymous-Provider"> <title>Anonymous</title> - <para> - The Anonymous Authentication Provider will allow users to connect with or without credentials and result - in their identification on the broker as the user ANONYMOUS. This Provider does not require specification - of any additional fields on creation. - </para> + <para> The Anonymous Authentication Provider will allow users to connect with or without + credentials and result in their identification on the broker as the user ANONYMOUS. This + Provider does not require specification of any additional fields on creation. </para> </section> <section id="Java-Broker-Security-PlainPasswordFile-Provider"> <title>Plain Password File</title> - <para> - The PlainPasswordFile Provider uses local file to store and manage user credentials. - When creating an authentication provider the path to the file needs to be specified. - If specified file does not exist an empty file is created automatically on Authentication Provider creation. - On Provider deletion the password file is deleted as well. For this Provider - user credentials can be added, removed or changed using REST management interfaces and web management console. - </para> - <para> - On navigating to the Plain Password File Provider tab (by clicking onto provider name from Broker tree or provider - row in providers grid on Broker tab) the list of existing credentials is displayed on the tab with the buttons "Add User" - and "Delete Users" to add new user credentials and delete the existing user credentials respectively. - On clicking into user name on Users grid the pop-up dialog to change the password is displayed. - </para> + <para> The PlainPasswordFile Provider uses local file to store and manage user credentials. When + creating an authentication provider the path to the file needs to be specified. If specified + file does not exist an empty file is created automatically on Authentication Provider + creation. On Provider deletion the password file is deleted as well. For this Provider user + credentials can be added, removed or changed using REST management interfaces and web + management console. </para> + <para> On navigating to the Plain Password File Provider tab (by clicking onto provider name + from Broker tree or provider row in providers grid on Broker tab) the list of existing + credentials is displayed on the tab with the buttons "Add User" and "Delete Users" to add new + user credentials and delete the existing user credentials respectively. On clicking into user + name on Users grid the pop-up dialog to change the password is displayed. </para> <section> - <title>Plain Password File Format</title> - <para> - The user credentials are stored on the single file line as user name and user password pairs separated by colon character. - </para> - <programlisting> + <title>Plain Password File Format</title> + <para> The user credentials are stored on the single file line as user name and user password + pairs separated by colon character. </para> + <programlisting> # password file format # <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> - diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml index 9a07c37861..4e7b95a3d7 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-Configuration-Encryption.xml @@ -1,4 +1,5 @@ <?xml version="1.0" encoding="utf-8"?> + <!-- Licensed to the Apache Software Foundation (ASF) under one @@ -20,10 +21,12 @@ --> -<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-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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml index 34ea443ef7..50678c2888 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Security-Group-Providers.xml @@ -29,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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml deleted file mode 100644 index 0a5ec0ec97..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Security-SSL.xml +++ /dev/null @@ -1,112 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!DOCTYPE entities [ -<!ENTITY % entities SYSTEM "commonEntities.xml"> -%entities; -]> -<!-- - - 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-Security-SSL"> -<title>SSL</title> - - <para> - This section guides through the details of configuration of Keystores and Trsustores - required for enabling of SSL transport and Client Certificate Authentication on Broker ports. - The details how to configure SSL on Broker ports are provided in <xref linkend="Java-Broker-Ports"/>. - </para> - - <section role="h2" id="Java-Broker-SSL-Keystore"> - <title>Keystore Configuration</title> - <para> - A Keystore can be added/deleted/edited using <link linkend="Java-Broker-Configuring-And-Managing-REST-API"> - REST Management interfaces</link> and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console"> - Web Management Console</link>. Any number of Keystores can be configured on the Broker. - SSL ports can be configured with different Keystores. - </para> - - <para>The following Keystore managing operations are available from - <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>: - <itemizedlist> - <listitem><para>A new Keystore can be added by clicking on "Add Key Store" button on the Broker tab.</para></listitem> - <listitem><para>Keystore details can be viewed on the Keystore tab which is displayed after clicking - on Keystore name in the Broker object tree or after clicking on Keystore row in Keystores grid on the Broker tab.</para></listitem> - <listitem><para>Editing of Keystore can be performed by clicking on "Edit" button on the Keystore tab. - Changing of Keystore name is unsupported at the moment. If changed Keystore is used by the Port - the changes on Port object will take effect after Broker restart.</para></listitem> - <listitem><para>An existing Keystore can be deleted by clicking on "Delete Key Store" button on Broker tab - or hitting "Delete" button on the Keystore tab. Only unused Keystores can be deleted. - The deletion of the Keystore configured on any Broker Port is not allowed.</para></listitem> - </itemizedlist> - </para> - - <para> - The "Keystore certificate alias" field is an optional way of specifying which certificate the broker should use - if the keystore contains multiple entries. Optionally "Key manager factory algorithm" and "Key store type" can - be specified on Keystore creation. - </para> - - <important> - <para> - The password of the certificate used by the Broker <emphasis role="bold">must</emphasis> - match the password of the keystore itself. This is a restriction of the Qpid Broker - implementation. If using the <ulink url="&oracleKeytool;">keytool</ulink> utility, - note that this means the argument to the <option>-keypass</option> option must match - the <option>-storepass</option> option. - </para> - </important> - </section> - - <section role="h2" id="SSL-Truststore-ClientCertificate"> - <title>Truststore / Client Certificate Authentication</title> - <para> - The SSL trustore and related Client Certificate Authentication behaviour can be configured - by adding a Trustore configured object and associating it with the SSL port. - A Truststore can be added/deleted/edited using <link linkend="Java-Broker-Configuring-And-Managing-REST-API"> - REST Management interfaces</link> and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console"> - Web Management Console</link>. Any number of Trustores can be configured on the Broker. - Multiple Trustores can be configured on Broker SSL Ports. - </para> - - <para>The following Truststore managing operations are available from - <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>: - <itemizedlist> - <listitem><para>A new Truststore can be added by clicking on "Add Trust Store" button on the Broker tab.</para></listitem> - <listitem><para>Truststore details can be viewed on the Truststore tab which is displayed after clicking - onto Truststore name in the Broker object tree or after clicking onto Truststore row in Truststores grid on the Broker tab.</para></listitem> - <listitem><para>Trustore can be edited by clicking onto "Edit" button on the Trustore tab. - Changing of Trustore name is unsupported at the moment.</para></listitem> - <listitem><para>An existing Trustore can be deleted by clicking onto "Delete Trust Store" button - on Broker tab or "Delete" button on the Truststore tab. Only unused Truststores can be deleted. - The deletion of the Truststore configured on any Broker Port is not allowed.</para></listitem> - </itemizedlist> - </para> - - <para>When "Peers Only" option is selected for the Truststore it will allow logging in for the clients - with the certificate exactly matching the certificate loaded in the Truststore database, - thus, authenticating the connections with self signed certificates not nessesary signed by CA. - </para> - - <para>"Trust manager factory algorithm" and "Trust store type" can - be optionally specified for the Trustore. - </para> - - </section> -</section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Security.xml b/qpid/doc/book/src/java-broker/Java-Broker-Security.xml index 858a27abb0..d9f1c4c68c 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Security.xml +++ b/qpid/doc/book/src/java-broker/Java-Broker-Security.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml deleted file mode 100644 index d6c779f2f3..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-BDB-Store.xml +++ /dev/null @@ -1,78 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!DOCTYPE entities [ -<!ENTITY % entities SYSTEM "commonEntities.xml"> -%entities; -]> -<!-- - - 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-Stores-BDB-Store"> - <title>BDB Message Store</title> - <para> - The Java broker has an <emphasis>optional</emphasis> message store implementation backed by Oracle BDB JE. - This section will detail where to download the optional dependency from, how to add it to the broker installation, - and provide an example configuration for using the BDBMessageStore. - </para> - - <para> - The BDBMessageStore can be selected on Virtual Host creation - via <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> - and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>. - For details, see <xref linkend="Java-Broker-Virtual-Hosts"/>. - </para> - - <para> - Alternatively, the BDBMessageStore can configured in Virtual Host configuration xml. - For details, see <xref linkend="Java-Broker-Stores-BDB-Store-Configuration"/>. - </para> - - <section role="h3" id="Java-Broker-Stores-BDB-Store-BDBJE-Download"> - <title>Oracle BDB JE download</title> - <para> - The BDB based message store is optional due to its dependency on Oracle BDB JE, which is distributed under the Sleepycat - licence. As a result of this, the dependency cant be distributed by the Apache Qpid project as part of the broker release package. - </para> - <para> - If you wish to use the BDBMessageStore, then you must download the Oracle BDB JE &oracleBdbProductVersion; release - <ulink url="&oracleJeDownloadUrl;">from the Oracle website.</ulink> - </para> - <para> - The download has a name in the form je-&oracleBdbProductVersion;.tar.gz. It is recommended that you - confirm the integrity of the download by verifying the MD5. - </para> - </section> - - <section role="h3" id="Java-Broker-Stores-BDB-Store-BDBJE-Installation"> - <title>Oracle BDB JE jar installation</title> - <para> - If you wish to use the BDBMessageStore, copy the je-&oracleBdbProductVersion;.jar from within the release - downloaded <link linkend="Java-Broker-Stores-BDB-Store-BDBJE-Download">above</link> into the 'opt' sub-directory - of the brokers 'lib' directory. - </para> - - <programlisting>Unix: -cp je-&oracleBdbProductVersion;.jar qpid-broker-&qpidCurrentRelease;/lib/opt</programlisting> - - <programlisting>Windows: -copy je-&oracleBdbProductVersion;.jar qpid-broker-&qpidCurrentRelease;\lib\opt</programlisting> - </section> - -</section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml deleted file mode 100644 index b8cd7a17d5..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-Derby-Store.xml +++ /dev/null @@ -1,42 +0,0 @@ -<?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-Stores-Derby-Store"> -<title>Derby Message Store</title> - <para> - The Java broker has a message store implementation backed by Apache Derby. - This section will detail configuration for using the DerbyMessageStore. - </para> - - <para> - The DerbyMessageStore can be selected on Virtual Host creation - via <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> - and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>. - For details, see <xref linkend="Java-Broker-Virtual-Hosts"/>. - </para> - - <para> - Alternatively, the DerbyMessageStore can configured in Virtual Host configuration xml. - For details, see <xref linkend="Java-Broker-Stores-Derby-Store-Configuration"/>. - </para> - -</section> 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 deleted file mode 100644 index ee9102f293..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-HA-BDB-Store.xml +++ /dev/null @@ -1,63 +0,0 @@ -<?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-Stores-HA-BDB-Store"> - <title>High Availability BDB Message Store</title> - <para> - The Java broker has an <emphasis>optional</emphasis> High Availability message store implementation backed by Oracle BDB JE HA. - This section references information on where to download the optional dependency from, how to add it to the broker - installation, and how to configure the BDBHAMessageStore. - </para> - <para> - For more detailed information about use of this store, see <xref linkend="Java-Broker-High-Availability"></xref>. - </para> - - <section role="h3" id="Java-Broker-Stores-HA-BDB-Store-BDBJE-Download"> - <title>Oracle BDB JE download</title> - <para> - For details, see <xref linkend="Java-Broker-Stores-BDB-Store-BDBJE-Download"></xref>. - </para> - </section> - - <section role="h3" id="Java-Broker-Stores-HA-BDB-Store-BDBJE-Installation"> - <title>Oracle BDB JE jar installation</title> - <para> - For details, see <xref linkend="Java-Broker-Stores-BDB-Store-BDBJE-Installation"></xref>. - </para> - </section> - - <section role="h3" id="Java-Broker-Stores-HA-BDB-Store-Configuration"> - <title>Configuration</title> - <para> - 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> - <para> - A general configuration example is shown <link linkend="Java-Broker-High-Availability-Configuration">here</link>, however it - is strongly recommended you examine the wider context of <xref linkend="Java-Broker-High-Availability"></xref> for a fuller - discussion of the various configuration options and how to use them. - </para> - </section> - -</section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml deleted file mode 100644 index cb04929e0c..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-Memory-Store.xml +++ /dev/null @@ -1,47 +0,0 @@ -<?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-Stores-Memory-Store"> - <title>Memory Message Store</title> - <para> - The Java broker has an in-memory message store implementation. - This section will detail configuration for using the MemoryMessageStore. - </para> - <para> - Note: when using this store, the broker will store both persistent and non-persistent messages - in memory, which is to say that neither will be available following a broker restart, and the - ability to store new messages will be entirely constrained by the JVM heap size. - </para> - - <para> - The MemoryMessageStore can be selected on Virtual Host creation - via <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> - and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>. - For details, see <xref linkend="Java-Broker-Virtual-Hosts"/>. - </para> - - <para> - Alternatively, the MemoryMessageStore can configured in Virtual Host configuration xml. - For details, see <xref linkend="Java-Broker-Stores-Memory-Store-Configuration"/>. - </para> - -</section> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores-SQL-Store.xml b/qpid/doc/book/src/java-broker/Java-Broker-Stores-SQL-Store.xml deleted file mode 100644 index f41b8af0e6..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Stores-SQL-Store.xml +++ /dev/null @@ -1,51 +0,0 @@ -<?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-Stores-SQL-Store"> -<title>SQL Message Store</title> -<para> - The Java broker has a message store implementation backed by JDBC API. - This section will detail configuration for using the JDBCMessageStore. - </para> - - <para> - The JDBCMessageStore can be selected on Virtual Host creation - via <link linkend="Java-Broker-Configuring-And-Managing-REST-API">REST Management interfaces</link> - and <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>. - For details, see <xref linkend="Java-Broker-Virtual-Hosts"/>. - </para> - - <para> - Alternatively, the JDBCMessageStore can configured in Virtual Host configuration xml. - For details, see <xref linkend="Java-Broker-Stores-JDBC-Store-Configuration"/>. - </para> - - <section role="h3" id="Java-Broker-Stores-JDBC-Store-Driver"> - <title>JDBC driver</title> - <para> - Only JDBC 4.0 compatible drivers can be used with JDBCMessageStore as it does not register a driver class explicitly. - In order to use a JDBCMessageStore a driver library is required to be present in the Broker classpath. - For the standard Broker distribution a driver library can be put into ${QPID_HOME}/lib/opt folder. - </para> - </section> - -</section> 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 deleted file mode 100644 index 43007a3242..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts-Configuration.xml +++ /dev/null @@ -1,685 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<!DOCTYPE entities [ -<!ENTITY % entities SYSTEM "commonEntities.xml"> -%entities; -]> -<!-- - - 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. - ---> -<chapter id="Java-Broker-Virtual-Hosts-Configuration-File"> - <title>Virtual Host XML configuration file</title> - - <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> - <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 role="h3" id="Java-Broker-Stores-Memory-Store-Configuration"> - <title>Configuring MemoryMessageStore</title> - <para> - An example of MemoryMessageStore configuration for a virtual host is shown below: - </para> - - <example> - <title>Configuring a VirtualHost to use the MemoryMessageStore</title> - <programlisting><![CDATA[ -<virtualhosts> - <virtualhost> - <name>vhostname</name> - <vhostname> - <store> - <class>org.apache.qpid.server.store.MemoryMessageStore</class - </store> - ... - </vhostname> - </virtualhost> -</virtualhosts> - ]]></programlisting> - </example> - </section> - - <section role="h3" id="Java-Broker-Stores-BDB-Store-Configuration"> - <title>Configuring BDBMessageStore</title> - <para> - In order to use the BDBMessageStore, you must configure it for each VirtualHost desired by updating the store element - to specify the associated store class and provide a directory location for the data to be written, as shown below. - </para> - - <example> - <title>Configuring a VirtualHost to use the BDBMessageStore</title> - <programlisting><![CDATA[ -<virtualhosts> - <virtualhost> - <name>vhostname</name> - <vhostname> - <store> - <class>org.apache.qpid.server.store.berkeleydb.BDBMessageStore</class> - <environment-path>${QPID_WORK}/bdbstore/vhostname</environment-path> - </store> - ... - </vhostname> - </virtualhost> -</virtualhosts> - ]]></programlisting> - </example> - - <section role="h4" id="Java-Broker-Stores-BDB-Store-Configuration_BDBEnvVars"> - <title>Passing BDB environment configuration options</title> - <para>It is possible to pass BDB <ulink url="&oracleBdbJavaDocUrl;com/sleepycat/je/EnvironmentConfig.html"> - environment</ulink> from the virtualhost.xml. Environment configuration options are passed using - <varname>envConfig</varname> elements within the <varname>store</varname> element.</para> - <para>For example, to override the BDB environment configuration options <varname>je.cleaner.threads</varname> and - <varname>je.log.fileMax</varname></para> - <example> - <title>Configuring BDB Environment Configuration</title> - <programlisting language="xml"><![CDATA[ - <store> - ... - <envConfig> - <name>je.cleaner.threads</name> - <value>2</value> - </envConfig> - <envConfig> - <name>je.log.fileMax</name> - <value>5000000</value> - </envConfig> - ... - </store>]]></programlisting> - </example> - </section> - </section> - - <section role="h3" id="Java-Broker-Stores-BDBHA-Store-Configuration"> - <title>Configuring BDBHAMessageStore</title> - <para>See <xref linkend="Java-Broker-High-Availability-Configuration"/></para> - </section> - - <section role="h3" id="Java-Broker-Stores-Derby-Store-Configuration"> - <title>Configuring DerbyMessageStore</title> - <para> - In order to use the DerbyMessageStore, you must configure it for each VirtualHost desired by updating the store element - to specify the associated store class and provide a directory location for the data to be written, as shown below. - </para> - - <example> - <title>Configuring a VirtualHost to use the DerbyMessageStore</title> - <programlisting><![CDATA[ -<virtualhosts> - <virtualhost> - <name>vhostname</name> - <vhostname> - <store> - <class>org.apache.qpid.server.store.DerbyMessageStore</class> - <environment-path>${QPID_WORK}/derbystore/vhostname</environment-path> - </store> - ... - </vhostname> - </virtualhost> -</virtualhosts> - ]]></programlisting> - </example> - </section> - - <section role="h3" id="Java-Broker-Stores-JDBC-Store-Configuration"> - <title>Configuring JDBCMessageStore</title> - <para> - JDBCMessageStore can be configured on VirtualHost as in example shown below: - </para> - - <example> - <title>Configuring a VirtualHost to use the JDBCMessageStore</title> - <programlisting><![CDATA[ -<virtualhosts> - <virtualhost> - <name>vhostname</name> - <vhostname> - <store> - <class>org.apache.qpid.server.store.jdbc.JDBCMessageStore</class> - <connectionUrl>jdbc:oracle:thin:guest@guest//localhost:1521/orcl</connectionUrl> - </store> - ... - </vhostname> - </virtualhost> -</virtualhosts> -]]></programlisting> - </example> - </section> - - - <section role="h3" id="Java-Broker-Virtual-Host-Configuration-Exchange"> - <title>Configuring Exchanges</title> - <para> - To declare Exchanges within Virtual Host configuration, add the appropriate xml - to the virtualhost.xml configuration file within the <varname>exchanges</varname> element. - An example of such declaration is shown below: - </para> - - <example> - <title>Configuring Exchanges on VirtualHost</title> - <programlisting><![CDATA[ -<virtualhosts> - <virtualhost> - <name>vhostname</name> - ... - <exchanges> - <exchange> - <type>direct</type> - <name>test.direct</name> - <durable>true</durable> - </exchange> - <exchange> - <type>topic</type> - <name>test.topic</name> - </exchange> - </exchanges> - ... - </vhostname> - </virtualhost> -</virtualhosts> -]]></programlisting> - </example> - </section> - - <section role="h2" id="Java-Broker-Virtual-Host-Declare-Queues"> - <title>Configuring Queues</title> - <para>To create a priority, sorted or LVQ queue within configuration, add the appropriate xml - to the virtualhost.xml configuration file within the <varname>queues</varname> - element.</para> - <section role="h3" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig-Simple"> - <title>Simple</title> - <para>For declaration of a simple queue define a queue entry in the virtual host configuration as in example below</para> - <example> - <title>Configuring a simple queue</title> - <programlisting><![CDATA[<queue> - <name>my-simple-queue</name> - <my-simple-queue> - <exchange>amq.direct</exchange> - <durable>true</durable> - </my-simple-queue> -</queue>]]></programlisting> - </example> - </section> - <section role="h3" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig-Priority"> - <title>Priority</title> - <para> To defining a priority queue, add a <priority>true</priority> element. By - default the queue will have 10 distinct priorities. </para> - <example> - <title>Configuring a priority queue</title> - <programlisting><![CDATA[<queue> - <name>myqueue</name> - <myqueue> - <exchange>amq.direct</exchange> - <priority>true</priority> - </myqueue> -</queue>]]></programlisting> - </example> - <para> If you require fewer priorities, it is possible to specify a - <varname>priorities</varname> element (whose value is a integer value between 2 and 10 - inclusive) which will give the queue that number of distinct priorities. When messages are - sent to that queue, their effective priority will be calculated by partitioning the - priority space. If the number of effective priorities is 2, then messages with priority - 0-4 are treated the same as "lower priority" and messages with priority 5-9 are treated - equivalently as "higher priority". </para> - <example> - <title>Configuring a priority queue with fewer priorities</title> - <programlisting><![CDATA[<queue> - <name>myqueue</name> - <myqueue> - <exchange>amq.direct</exchange> - <priority>true</priority> - <priorities>4</priorities> - </myqueue> -</queue>]]></programlisting> - </example> - </section> - <section role="h3" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig-Sorted"> - <title>Sorted</title> - <para> To define a sorted queue, add a <varname>sortKey</varname> element. The value of the - <varname>sortKey</varname> element defines the message property to use the value of when - sorting the messages put onto the queue. </para> - <example> - <title>Configuring a sorted queue</title> - <programlisting><![CDATA[<queue> - <name>myqueue</name> - <myqueue> - <exchange>amq.direct</exchange> - <sortKey>message-property-to-sort-by</sortKey> - </myqueue> -</queue>]]></programlisting> - </example> - </section> - <section role="h3" id="Java-Broker-Queues-OtherTypes-CreateUsingConfig-LVQ"> - <title>LVQ</title> - <para> To define a LVQ, add a <varname>lvq</varname> element with the value - <constant>true</constant>. Without any further configuration this will define an LVQ - which uses the JMS message property <constant>qpid.LVQ_key</constant> as the key for - replacement. </para> - <example> - <title>Configuring a LVQ queue</title> - <programlisting><![CDATA[<queue> - <name>myqueue</name> - <myqueue> - <exchange>amq.direct</exchange> - <lvq>true</lvq> - </myqueue> -</queue>]]></programlisting> - </example> - <para> If you wish to define your own property then you can do so using the - <varname>lvqKey</varname> element.</para> - <example> - <title>Configuring a LVQ queue with custom message property name</title> - <programlisting><![CDATA[<queue> - <name>myqueue</name> - <myqueue> - <exchange>amq.direct</exchange> - <lvq>true</lvq> - <lvqKey>ISIN</lvqKey> - </myqueue> -</queue>]]></programlisting> - </example> - </section> - <section role="h3" id="Java-Broker-Virtual-Host-Configuring-Queue-With-Arguments"> - <title>Configuring queue with arguments</title> - <para>Queue arguments can be configured in virtual host configuration file. - An element <emphasis>argument</emphasis> is used to specify a queue argument as a name-value pair separated with equal character. - Any number of queue arguments can be provided for a queue in their own <emphasis>argument</emphasis> elements.</para> - <para>The following example demonstrates how to configure queue with two arguments.</para> - <example> - <title>Setting arbitrary queue arguments</title> - <programlisting><![CDATA[ -<queue> - <name>myQueue</name> - <myQueue> - <argument>qpid.group_header_key=JMSXgroupID</argument> - <argument>qpid.shared_msg_group=1</argument> - </myQueue> -</queue>]]></programlisting> - </example> - </section> - </section> - - <section role="h2" id="Java-Broker-Virtual-Host-Binding-Queue"> - <title>Queue Binding</title> - <para>A queue can be bound to an exchange in virtual host configuration file by providing an exchange name in element <emphasis>exchange</emphasis> - within the queue configuration element having the same name as a queue. If exchange element is omitted in queue configuration - then such queue is bound to a default exchange only. With configuration file it is only possible to bind queue to a single exchange.</para> - <para>An element <emphasis>routingKey</emphasis> is used to specify a custom binding key. It is an optional element, and, - if it is not set then queue is bound to an exchange with a binding key equals to a queue name. Any number of binding keys can be configured. - </para> - <para> - Binding arguments can be set with each binding key. An element <emphasis>bindingArgument</emphasis> is used to specify a binding argument - as a name-value pair separated with equal character. Any number of binding arguments can be provided for a binding key in their own <emphasis>bindingArgument</emphasis> elements. - All of them should be contained within an element having the same name as a binding key.</para> - <para>The following example demonstrates how to bind queue <emphasis>testQueue</emphasis> to a default topic exchange - using routing key <emphasis>testRoutingKey</emphasis> and binding arguments for message selector and no local.</para> - <example> - <title>Queue Binding Example</title> - <programlisting><![CDATA[<queue> - <name>testQueue</name> - <testQueue> - <exchange>amq.topic</exchange> - <routingKey>testRoutingKey</routingKey> - <testRoutingKey> - <bindingArgument>x-filter-jms-selector=application='app1'</bindingArgument> - <bindingArgument>x-qpid-no-local=</bindingArgument> - </testRoutingKey> - </testQueue> -</queue>]]> - </programlisting> - </example> - </section> - - <section role="h2" id="Java-Broker-Virtual-Host-Configure-Flow-Control"> - <title>Configuring of Producer Flow Control</title> - <para>Flow control capacity and flow resume capacity are required to set on a queue or virtual host to enable Producer flow control.</para> - - <example> - <title>Configuring a queue depth limit</title> - <programlisting> - <![CDATA[ -<queue> - <name>test</name> - <test> - <exchange>amq.direct</exchange> - - <!-- set the queue capacity to 10Mb --> - <capacity>10485760</capacity> - - <!-- set the resume capacity to 8Mb --> - <flowResumeCapacity>8388608</flowResumeCapacity> - </test> -</queue> - ]]> - </programlisting> - </example> - - The default for all queues on a virtual host can also be set - - <example> - <title>Configuring of default queue depth limit on virtualhost</title> - <programlisting> - <![CDATA[ -<virtualhosts> - <virtualhost> - <name>localhost</name> - <localhost> - - <!-- set the queue capacity to 10Mb --> - <capacity>10485760</capacity> - - <!-- set the resume capacity to 8Mb --> - <flowResumeCapacity>8388608</flowResumeCapacity> - </localhost> - </virtualhost> -</virtualhosts> - ]]> - </programlisting> - </example> - </section> - - <section role="h2" id="Java-Broker-Virtual-Host-Configure-Disk-Quotas"> - <title>Configuring of Disk Quota-based Flow Control</title> - <para> - An example of quota configuration for the BDB message store is provided below. - </para> - - <example> - <title>Configuring a limit on a store</title> - <programlisting> - <![CDATA[ -<store> - <class>org.apache.qpid.server.store.berkeleydb.BDBMessageStore</class> - <environment-path>${work}/bdbstore/test</environment-path> - <overfull-size>50000000</overfull-size> - <underfull-size>45000000</underfull-size> -</store> - ]]> - </programlisting> - </example> - </section> - - -<section role="h3" - id="Java-Broker-Virtual-Host-Transaction-Timeout-Configuring"> - <title>Configuring Transaction Timeouts</title> - <para> The JMS transaction timeouts are configured on each virtual host defined in the XML - configuration files.</para> - <para> The default values for each of the parameters is 0, indicating that the particular check - is disabled.</para> - <para> Any or all of the parameters can be set, using the desired value in milliseconds, and will - be checked each time the housekeeping process runs, usually set to run every 30 seconds in - standard configuration. The meaning of each property is as follows:</para> - <para> - <itemizedlist> - <listitem> - <para>openWarn - the time a transaction can be open for (with activity occurring on it) after - which a warning alert will be issued.</para> - </listitem> - <listitem> - <para>openClose - the time a transaction can be open for before the connection it is on is - closed.</para> - </listitem> - <listitem> - <para>idleWarn - the time a transaction can be idle for (with no activity occurring on it) - after which a warning alert will be issued.</para> - </listitem> - <listitem> - <para>idleClose - the time a transaction can be idle for before the connection it is on is - closed.</para> - </listitem> - </itemizedlist> - </para> - <para> The virtualhosts configuration is shown below, and must occur inside the - //virtualhosts/virtualhost/name/ elements: </para> - <example> -<title>Configuring producer transaction timeout</title> - <programlisting><![CDATA[ -<transactionTimeout> - <openWarn>10000</openWarn> - <openClose>20000</openClose> - <idleWarn>5000</idleWarn> - <idleClose>15000</idleClose> -</transactionTimeout> - ]]></programlisting> - </example> - </section> - - <section role="h2" id="Java-Broker-Virtual-Host-Configuring-DLQ"> - <title>Configuring DLQs/Maximum Delivery Count</title> - <para>In the below configuration it can be seen that DLQs/Maximum Delivery Count are enabled at - the virtual host "localhost" with maximum delivery count set to 5 and disable for virtual host "dev-only".</para> - <para>As 'dev-only-main-queue' has its own configuration specified, this value overrides all - others and causes the features to be enabled for this queue. In contrast to this, - 'dev-only-other-queue' does not specify its own value and picks up the false value specified for - its parent virtualhost, causing the DLQ/Maximum Delivery Count features to be disabled for this - queue. Any such queue in the 'dev-only' virtualhost which does not specify its own configuration - value will have the DLQ/Maximum Delivery Count feature disabled.</para> - <para>The queue 'localhost-queue' has the DLQ/Maximum Delivery Count features disabled. - Any other queue in the 'localhost' virtualhost which does not specify - its own configuration value will have the features enabled (inherited from parent virtual host).</para> - - <example> - <title>Enabling DLQs and maximum delivery count at virtualhost and queue level within - virtualhosts.xml</title> - <programlisting><![CDATA[<virtualhosts> - ... - <virtualhost> - <name>dev-only</name> - <dev-only> - <queues> - <deadLetterQueues>false</deadLetterQueues> - <maximumDeliveryCount>0</maximumDeliveryCount> - <queue> - <name>dev-only-main-queue</name> - <dev-only-main-queue> - <deadLetterQueues>true</deadLetterQueues> - <maximumDeliveryCount>3</maximumDeliveryCount> - </dev-only-main-queue> - </queue> - <queue> - <name>dev-only-other-queue</name> - </queue> - </queues> - </dev-only> - </virtualhost> - <virtualhost> - <name>localhost</name> - <localhost> - <queues> - <deadLetterQueues>true</deadLetterQueues> - <maximumDeliveryCount>5</maximumDeliveryCount> - <queue> - <name>localhost-queue</name> - <deadLetterQueues>false</deadLetterQueues> - </queue> - </queues> - </localhost> - </virtualhost> - ... -</virtualhosts>]]> - </programlisting> - </example> - </section> - - - <section role="h2" id="Java-Broker-Virtual-Host-Configuration-File-Example"> - <title>An example of virtual host configuration file</title> - <example> - <title>An example of virtual host configuration file</title> - <programlisting><![CDATA[ -<?xml version="1.0" encoding="ISO-8859-1"?> -<virtualhosts> - <virtualhost> - <name>localhost</name> - <localhost> - <store> - <class>org.apache.qpid.server.store.MemoryMessageStore</class> - <!--<class>org.apache.qpid.server.store.derby.DerbyMessageStore</class> - <environment-path>${QPID_WORK}/derbystore/localhost</environment-path>--> - </store> - - <housekeeping> - <threadCount>2</threadCount> - <checkPeriod>20000</checkPeriod> - </housekeeping> - - <exchanges> - <exchange> - <type>direct</type> - <name>test.direct</name> - <durable>true</durable> - </exchange> - <exchange> - <type>topic</type> - <name>test.topic</name> - </exchange> - </exchanges> - <queues> - <exchange>amq.direct</exchange> - <maximumQueueDepth>4235264</maximumQueueDepth> - <!-- 4Mb --> - <maximumMessageSize>2117632</maximumMessageSize> - <!-- 2Mb --> - <maximumMessageAge>600000</maximumMessageAge> - <!-- 10 mins --> - <maximumMessageCount>50</maximumMessageCount> - <!-- 50 messages --> - - <queue> - <name>queue</name> - </queue> - <queue> - <name>ping</name> - </queue> - <queue> - <name>test-queue</name> - <test-queue> - <exchange>test.direct</exchange> - <durable>true</durable> - </test-queue> - </queue> - <queue> - <name>test-ping</name> - <test-ping> - <exchange>test.direct</exchange> - </test-ping> - </queue> - - </queues> - </localhost> - </virtualhost> - - <virtualhost> - <name>development</name> - <development> - <store> - <class>org.apache.qpid.server.store.MemoryMessageStore</class> - <!--<class>org.apache.qpid.server.store.derby.DerbyMessageStore</class> - <environment-path>${QPID_WORK}/derbystore/development</environment-path>--> - </store> - - <queues> - <minimumAlertRepeatGap>30000</minimumAlertRepeatGap> - <maximumMessageCount>50</maximumMessageCount> - <queue> - <name>queue</name> - <queue> - <exchange>amq.direct</exchange> - <maximumQueueDepth>4235264</maximumQueueDepth> - <!-- 4Mb --> - <maximumMessageSize>2117632</maximumMessageSize> - <!-- 2Mb --> - <maximumMessageAge>600000</maximumMessageAge> - <!-- 10 mins --> - </queue> - </queue> - <queue> - <name>ping</name> - <ping> - <exchange>amq.direct</exchange> - <maximumQueueDepth>4235264</maximumQueueDepth> - <!-- 4Mb --> - <maximumMessageSize>2117632</maximumMessageSize> - <!-- 2Mb --> - <maximumMessageAge>600000</maximumMessageAge> - <!-- 10 mins --> - </ping> - </queue> - </queues> - </development> - </virtualhost> - - <virtualhost> - <name>test</name> - <test> - <store> - <!--<class>org.apache.qpid.server.store.MemoryMessageStore</class>--> - <class>org.apache.qpid.server.store.derby.DerbyMessageStore</class> - <environment-path>${QPID_WORK}/derbystore/test</environment-path> - </store> - - <queues> - <minimumAlertRepeatGap>30000</minimumAlertRepeatGap> - <maximumMessageCount>50</maximumMessageCount> - <queue> - <name>queue</name> - <queue> - <exchange>amq.direct</exchange> - <maximumQueueDepth>4235264</maximumQueueDepth> - <!-- 4Mb --> - <maximumMessageSize>2117632</maximumMessageSize> - <!-- 2Mb --> - <maximumMessageAge>600000</maximumMessageAge> - <!-- 10 mins --> - </queue> - </queue> - <queue> - <name>ping</name> - <ping> - <exchange>amq.direct</exchange> - <maximumQueueDepth>4235264</maximumQueueDepth> - <!-- 4Mb --> - <maximumMessageSize>2117632</maximumMessageSize> - <!-- 2Mb --> - <maximumMessageAge>600000</maximumMessageAge> - <!-- 10 mins --> - </ping> - </queue> - </queues> - </test> - </virtualhost> -</virtualhosts> - ]]></programlisting> - </example> - </section> - -</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 deleted file mode 100644 index b240d85d4f..0000000000 --- a/qpid/doc/book/src/java-broker/Java-Broker-Virtual-Hosts.xml +++ /dev/null @@ -1,69 +0,0 @@ -<?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. - ---> - -<chapter id="Java-Broker-Virtual-Hosts"> - <title>Virtual Hosts</title> - - <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-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: - <itemizedlist> - <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> - </para> - - <para>The following Virtual Host Managing operations are available from - <link linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management Console</link>: - <itemizedlist> - <listitem><para>A new Virtual Host can be added into Broker by pressing "Add Virtual Host" button - on the Broker tab.</para></listitem> - <listitem><para>The existing Virtual Host(s) can be removed by pressing "Remove Virtual Host" button on the Broker tab.</para></listitem> - <listitem><para>The Virtual Host details can be viewed on the Virtual Host tab. - This tab can be displayed after clicking onto Virtual Host Name in the Broker object tree - or onto the Virtual Host row in the Virtual Hosts grid on the Broker tab.</para></listitem> - <listitem><para>Queues can be configured (added/removed) from Virtual Host tab</para></listitem> - <listitem><para>Exchange can be configured (added/removed) from Virtual Host tab</para></listitem> - <listitem><para>Existing Exchange/Queue tabs can be navigated from Virtual Host tab</para></listitem> - </itemizedlist> - </para> - </section> - -</chapter> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml index dd7c291c77..5bf1a31087 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Authentication-Providers.xml +++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Authentication-Providers.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml new file mode 100644 index 0000000000..70e4047866 --- /dev/null +++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Broker.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Exchanges.xml index 9033ad29c6..5eb02dc5dd 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Exchanges.xml +++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Exchanges.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Other-Services.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Other-Services.xml index d0368329b6..854a8001d6 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Other-Services.xml +++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Other-Services.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Ports.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml index 027e3a1697..37b54299e4 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Concepts-Ports.xml +++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Ports.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml new file mode 100644 index 0000000000..3839e8cf89 --- /dev/null +++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Queues.xml @@ -0,0 +1,30 @@ +<?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-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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Stores.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-RemoteReplicationNodes.xml index 2524c9855c..b9162fd8e3 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Stores.xml +++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-RemoteReplicationNodes.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="utf-8"?> <!-- Licensed to the Apache Software Foundation (ASF) under one @@ -20,11 +20,8 @@ --> -<chapter id="Java-Broker-Stores"> - <title>Virtual Host Message Stores</title> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Stores-Memory-Store.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Stores-Derby-Store.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Stores-SQL-Store.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Stores-BDB-Store.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Stores-HA-BDB-Store.xml"/> -</chapter> +<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> diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml new file mode 100644 index 0000000000..064c44b22f --- /dev/null +++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhost-Nodes.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml new file mode 100644 index 0000000000..ecc898627e --- /dev/null +++ b/qpid/doc/book/src/java-broker/concepts/Java-Broker-Concepts-Virtualhosts.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/images/Broker-Model.png b/qpid/doc/book/src/java-broker/images/Broker-Model.png Binary files differindex e74f608bf1..8dd0118010 100644 --- a/qpid/doc/book/src/java-broker/images/Broker-Model.png +++ b/qpid/doc/book/src/java-broker/images/Broker-Model.png diff --git a/qpid/doc/book/src/java-broker/images/Management-Web-Auth.png b/qpid/doc/book/src/java-broker/images/Management-Web-Auth.png Binary files differnew file mode 100644 index 0000000000..df28ef3d2c --- /dev/null +++ b/qpid/doc/book/src/java-broker/images/Management-Web-Auth.png diff --git a/qpid/doc/book/src/java-broker/images/Management-Web-Console.png b/qpid/doc/book/src/java-broker/images/Management-Web-Console.png Binary files differindex de7344a08c..953a572bfc 100644 --- a/qpid/doc/book/src/java-broker/images/Management-Web-Console.png +++ b/qpid/doc/book/src/java-broker/images/Management-Web-Console.png diff --git a/qpid/doc/book/src/java-broker/images/Management-Web-Tab.png b/qpid/doc/book/src/java-broker/images/Management-Web-Tab.png Binary files differnew file mode 100644 index 0000000000..f0958477e6 --- /dev/null +++ b/qpid/doc/book/src/java-broker/images/Management-Web-Tab.png diff --git a/qpid/doc/book/src/java-broker/images/VirtualHost-Model.png b/qpid/doc/book/src/java-broker/images/VirtualHost-Model.png Binary files differindex 011026bcfb..bea811f27f 100644 --- a/qpid/doc/book/src/java-broker/images/VirtualHost-Model.png +++ b/qpid/doc/book/src/java-broker/images/VirtualHost-Model.png diff --git a/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-AMQP-Intrinsic.xml b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-AMQP-Intrinsic.xml new file mode 100644 index 0000000000..475e7da84f --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-AMQP-Intrinsic.xml @@ -0,0 +1,29 @@ +<?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-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> diff --git a/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-HTTP.xml b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-HTTP.xml new file mode 100644 index 0000000000..30f9277303 --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-HTTP.xml @@ -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> diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-JMX.xml index 026213c157..4af4764c0d 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-JMX.xml +++ b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-JMX.xml @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE entities [ -<!ENTITY % entities SYSTEM "commonEntities.xml"> +<!ENTITY % entities SYSTEM "../../commonEntities.xml"> %entities; ]> <!-- @@ -24,10 +24,10 @@ --> -<section id="Java-Broker-Configuring-And-Managing-JMX-Management"> +<section id="Java-Broker-Management-Channel-JMX"> <title>JMX Management</title> - <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Introduction"> + <section id="Java-Broker-Management-Channel-JMX-Introduction"> <title>Introduction</title> <para>The JMX management plugin provides a series of managed beans (MBeans) allowing you to control and monitor the Broker via an industry compliant interface. This provides a @@ -39,15 +39,15 @@ plugin.</para> <important> <para>For new development work, the reader is directed towards the strategic <link - linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management + linkend="Java-Broker-Management-Channel-Web-Console">Web Management Console</link> and the <link - linkend="Java-Broker-Configuring-And-Managing-REST-API">REST API</link>. Use the + linkend="Java-Broker-Management-Channel-REST-API">REST API</link>. Use the Web/REST interfaces in preference to JMX whenever possible. The JMX interface may be withdrawn in a future release.</para> </important> </section> - <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-DefaultConfiguration"> + <section id="Java-Broker-Management-Channel-JMX-Plugin-DefaultConfiguration"> <title>Default Configuration</title> <para>By default, the Broker is shipped with JMX enabled.</para> <para>The RMI registry port runs on port <literal>8999</literal> and the JMX connector on @@ -56,11 +56,11 @@ url="&oracleJdkDocUrl;java/lang/management/ManagementFactory.html#getPlatformMBeanServer()" >Platform MBeanServer</ulink>.</para> <para>To change these settings, use the <link - linkend="Java-Broker-Configuring-And-Managing-Web-Console">Web Management + linkend="Java-Broker-Management-Channel-Web-Console">Web Management interface</link>.</para> </section> - <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-ConnectingToJMX"> + <section id="Java-Broker-Management-Channel-JMX-Plugin-ConnectingToJMX"> <title>Connecting to JMX</title> <para>The following example uses Jconsole to illustrates how to connect to JMX and assume the defaults described above. Jconsole is a management tool that comes with the JDK. It @@ -74,14 +74,14 @@ <para>To start Jconsole on the command line, type:</para> <programlisting><![CDATA[jconsole]]></programlisting> <section - id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-ConnectingToJMX-Local"> + id="Java-Broker-Management-Channel-JMX-Plugin-ConnectingToJMX-Local"> <title>Local</title> <para>To connect to a Broker running locally, simply select the process from the list. You can identify the Broker by looking for its classname <literal>org.apache.qpid.server.Main</literal>.</para> </section> <section - id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-ConnectingToJMX-Remote"> + id="Java-Broker-Management-Channel-JMX-Plugin-ConnectingToJMX-Remote"> <title>Remote</title> <para>To connect to a broker running remotely, provide the hostname and port number of the <emphasis>RMI registry port</emphasis> (e.g. <literal>hostname:8999</literal>) @@ -99,7 +99,7 @@ <title>Qpid MBean hierarchy</title> <graphic fileref="images/JMX-Connect-MBeans.png"/> </figure> - <section id="Java-Broker-Configuring-And-Managing-JMX-Management-Plugin-ConnectingToJMX-SSL"> + <section id="Java-Broker-Management-Channel-JMX-Plugin-ConnectingToJMX-SSL"> <title>Connecting to a remote Broker protected by SSL</title> <para>If you are connecting to a remote Broker whose JMX connector port has been secured with SSL certificate signed by a private CA (or a self-signed certificate), you will @@ -109,7 +109,7 @@ </section> </section> - <section id="Java-Broker-Configuring-And-Managing-JMX-Example-Client"> + <section id="Java-Broker-Management-JMX-Example-Client"> <title>Example JMX Client</title> <para>The following java snippet illustrates a JMX client that connects to Qpid over JMX passing a userid and password, looks up the <ulink @@ -119,7 +119,7 @@ <para>A full introduction to custom JMX clients is beyond the scope of this book. For this the reader is directed toward Oracle's <ulink url="&oracleJmxTutorial;">JMX tutorial.</ulink></para> - <example id="Java-Broker-Configuring-And-Managing-JMX-Example-Client-Code"> + <example id="Java-Broker-Management-JMX-Example-Client-Code"> <title>JMX Client illustrating the creation of a new queue</title> <programlisting language="java"> Map<String, Object< environment = new HashMap<String, Object>(); @@ -140,7 +140,7 @@ managedBroker.createNewQueue("myqueue", null, true);</programlisting> <literal>qpid-management-common</literal> artefact.</para> </section> - <section id="Java-Broker-Configuring-And-Managing-JMX-Management-MBeans"> + <section id="Java-Broker-Management-Channel-JMX-MBeans"> <title>The MBeans</title> <para>The following table summarises the available MBeans. The MBeans are self-describing: each attribute and operation carry a description describing their purpose. This diff --git a/qpid/doc/book/src/java-broker/Java-Broker-Queues.xml b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-QMF.xml index 9338ab8462..6e91bbb6c1 100644 --- a/qpid/doc/book/src/java-broker/Java-Broker-Queues.xml +++ b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-QMF.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="utf-8"?> <!-- Licensed to the Apache Software Foundation (ASF) under one @@ -20,7 +20,7 @@ --> -<chapter id="Java-Broker-Queues"> - <title>Queues</title> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Java-Broker-Queues-OtherTypes.xml"/> -</chapter> +<section id="Java-Broker-Management-Channel-QMF"> + <title>QMF</title> + <para>QMF is provided by an optional plugin.</para> +</section> diff --git a/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml new file mode 100644 index 0000000000..754af01563 --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-REST-API.xml @@ -0,0 +1,354 @@ +<?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-REST-API"> + <title>REST API</title> + <para> This section provides a brief overview of the REST interface, which can be used directly to + monitor and manage the Broker instance.. </para> + + <para>The 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 REST API is versioned with the version number built into the URL. The general form of + the the URL is <literal>/api/<version></literal>. For convience the alias + <literal>latest</literal> signifies the latest supported version. There are also some + ancillary service prefixed by <literal>/service</literal>.</para> + + <para>The table below lists the available REST services with brief description how they can be + used.</para> + + <table> + <title>Rest services</title> + <tgroup cols="6"> + <thead> + <row> + <entry>REST Service URL</entry> + <entry>Description</entry> + <entry>GET</entry> + <entry>PUT</entry> + <entry>POST</entry> + <entry>DELETE</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <para>/api/<ver>/broker</para> + </entry> + <entry> + <para>Rest service to manage broker instance</para> + </entry> + <entry> + <para>Retrieves the details of broker configuration</para> + </entry> + <entry> + <para>Updates broker attributes</para> + </entry> + <entry> + <para>Not implemented yet</para> + </entry> + <entry> + <para>Not implemented yet</para> + </entry> + </row> + <row> + <entry> + <para>/api/<ver>/authenticationprovider</para> + <para>/api/<ver>/authenticationprovider/<authentication provider + name></para> + </entry> + <entry>Rest service to manage authentication providers on the broker</entry> + <entry>Retrieves the details about authentication providers</entry> + <entry>Creates or updates authentication providers</entry> + <entry>Not implemented yet</entry> + <entry>Deletes authentication providers</entry> + </row> + <row> + <entry> + <para>/api/<ver>/accesscontrolprovider</para> + </entry> + <entry>Rest service to manage access control providers</entry> + <entry>Retrieves the details about access control providers</entry> + <entry>Creates access control provider</entry> + <entry>Not implemented yet</entry> + <entry>Deletes access control provider(s)</entry> + </row> + <row> + <entry> + <para>/api/<ver>/user</para> + <para>/api/<ver>/user/<authentication provider name>/<user + name></para> + </entry> + <entry>Rest service to manage user account</entry> + <entry>Retrieves the details about user account</entry> + <entry>Creates user account, updates user password</entry> + <entry>Not implemented yet</entry> + <entry>Deletes user account</entry> + </row> + <row> + <entry> + <para>/api/<ver>/groupprovider</para> + <para>/api/<ver>/groupprovider/<group provider name></para> + </entry> + <entry>Rest service to manage group providers</entry> + <entry>Retrieves the details about group provider(s)</entry> + <entry>Creates group provider</entry> + <entry>Not implemented yet</entry> + <entry>Deletes groups providers</entry> + </row> + <row> + <entry> + <para>/api/<ver>/group</para> + <para>/api/<ver>/group/<group provider name>/<group name></para> + </entry> + <entry>Rest service to manage user group</entry> + <entry>Retrieves the details about user group</entry> + <entry>Creates group</entry> + <entry>Not implemented yet</entry> + <entry>Deletes group</entry> + </row> + <row> + <entry> + <para>/api/<ver>/groupmember</para> + <para>/api/<ver>/groupmember/<group provider name >/<group + name>/<user name></para> + </entry> + <entry>Rest service to manage group member(s)</entry> + <entry>Retrieves the details about group member(s)</entry> + <entry>Add user to group</entry> + <entry>Not implemented yet</entry> + <entry>Deletes user from group</entry> + </row> + <row> + <entry> + <para>/api/<ver>/port</para> + <para>/api/<ver>/port/<port name></para> + </entry> + <entry>Rest service to manage broker ports(s)</entry> + <entry>Retrieves the details about the broker port(s)</entry> + <entry>Creates or updates port</entry> + <entry>Not implemented yet</entry> + <entry>Deletes ports</entry> + </row> + <row> + <entry> + <para>/api/<ver>/keystore</para> + </entry> + <entry>Rest service to manage KeyStores</entry> + <entry>Retrieves the details about KeyStore</entry> + <entry>Creates or updates KeyStore</entry> + <entry>Not implemented yet</entry> + <entry>Deletes KeyStore(s)</entry> + </row> + <row> + <entry> + <para>/api/<ver>/truststore</para> + </entry> + <entry>Rest service to manage TrustStore</entry> + <entry>Retrieves the details about TrustStore</entry> + <entry>Creates or updates TrustStore</entry> + <entry>Not implemented yet</entry> + <entry>Deletes TrustStore(s)</entry> + </row> + <row> + <entry> + <para>/api/<ver>/plugin</para> + </entry> + <entry>Rest service to manage plugins</entry> + <entry>Retrieves the details about plugins</entry> + <entry>Updates plugin attributes</entry> + <entry>Not implemented yet</entry> + <entry>Not implemented yet</entry> + </row> + <row> + <entry> + <para>/api/<ver>/virtualhostnode</para> + <para>/api/<ver>/virtualhostnode/<virtualhostnode name></para> + </entry> + <entry>Rest service to manage virtualhost node(s)</entry> + <entry>Retrieves the details about the virtualhost node(s)</entry> + <entry>Creates/Updates virtualhost node</entry> + <entry>Not implemented yet</entry> + <entry>Deletes virtualhost node</entry> + </row> + <row> + <entry> + <para>/api/<ver>/virtualhost</para> + <para>/api/<ver>/virtualhost/<virtualhostnode name>/<virtualhost + name></para> + </entry> + <entry>Rest service to manage virtualhost(s)</entry> + <entry>Retrieves the details about the virtualhost(s)</entry> + <entry>Creates/Updates virtualhost</entry> + <entry>Not implemented yet</entry> + <entry>Deletes virtualhost</entry> + </row> + <row> + <entry> + <para>/api/<ver>/queue</para> + <para>/api/<ver>/queue/<virtualhostnode name>/<virtualhost + name>/<queue name></para> + </entry> + <entry>Rest service to manage queue(s)</entry> + <entry>Retrieves the details about the queue(s)</entry> + <entry>Creates queue</entry> + <entry>Not implemented yet</entry> + <entry>Deletes queue</entry> + </row> + <row> + <entry> + <para>/api/<ver>/exchange</para> + <para>/api/<ver>/exchange/<virtualhostnode name>/<virtualhost + name>/<exchange name></para> + </entry> + <entry>Rest service to manage exchange(s)</entry> + <entry>Retrieves the details about the exchange(s)</entry> + <entry>Creates exchange</entry> + <entry>Not implemented yet</entry> + <entry>Deletes exchange</entry> + </row> + <row> + <entry> + <para>/api/<ver>/binding</para> + <para>/api/<ver>/binding/<virtualhostnode name>/<virtualhost + name>/<exchange name>/<queue name>/<binding name></para> + </entry> + <entry>Rest service to manage binding(s)</entry> + <entry>Retrieves the details about the binding(s)</entry> + <entry>Binds a queue to an exchange</entry> + <entry>Not implemented yet</entry> + <entry>Deletes binding</entry> + </row> + <row> + <entry> + <para>/api/<ver>/connection</para> + <para>/api/<ver>/connection/<virtualhostnode name>/<virtualhost + name>/<connection name></para> + </entry> + <entry>Rest service to manage connection(s)</entry> + <entry>Retrieves the details about the connection(s)</entry> + <entry>Not implemented yet</entry> + <entry>Not implemented yet</entry> + <entry>Not implemented yet</entry> + </row> + <row> + <entry> + <para>/api/<ver>/session</para> + <para>/api/<ver>/session/<virtualhostnode name>/<virtualhost + name>/<connection name>/<session name></para> + </entry> + <entry>Rest service to manage session(s)</entry> + <entry>Retrieves the details about the session(s)</entry> + <entry>Not implemented yet</entry> + <entry>Not implemented yet</entry> + <entry>Not implemented yet</entry> + </row> + <row> + <entry> + <para>/service/message/<virtualhost name>/<queue name></para> + </entry> + <entry>Rest service to manage messages(s)</entry> + <entry>Retrieves the details about the messages(s)</entry> + <entry>Not implemented yet</entry> + <entry>Copies, moves messages</entry> + <entry>Deletes messages</entry> + </row> + <row> + <entry> + <para>/service/message-content/<virtualhost name>/<queue name></para> + </entry> + <entry>Rest service to retrieve message content</entry> + <entry>Retrieves the message content</entry> + <entry>Not implemented yet</entry> + <entry>Not implemented yet</entry> + <entry>Not implemented yet</entry> + </row> + <row> + <entry> + <para>/service/logrecords</para> + </entry> + <entry>Rest service to retrieve broker logs</entry> + <entry>Retrieves the broker logs</entry> + <entry>Not implemented yet</entry> + <entry>Not implemented yet</entry> + <entry>Not implemented yet</entry> + </row> + <row> + <entry> + <para>/service/sasl</para> + </entry> + <entry>Sasl authentication</entry> + <entry>Retrieves user current authentication status and broker supported SASL + mechanisms</entry> + <entry>Authenticates user using supported SASL mechanisms</entry> + <entry>Not implemented yet</entry> + <entry>Not implemented yet</entry> + </row> + <row> + <entry> + <para>/service/logout</para> + </entry> + <entry>Log outs</entry> + <entry>Log outs user</entry> + <entry>Not implemented yet</entry> + <entry>Not implemented yet</entry> + <entry>Not implemented yet</entry> + </row> + </tbody> + </tgroup> + </table> + <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/api/latest/binding/<vhost node>/<vhost>/<exchange>/<queue>/<binding> + replacing of <emphasis><exchange></emphasis> with "asterisks" + (http://localhost:8080/api/<ver>/binding/<vhost node>/<vhost>/*/<queue>/<binding>) + will result in the GET response containing the list of bindings for all of the exchanges in the + virtualhost having the given name and given queue. If <emphasis><binding></emphasis> and + <emphasis><queue></emphasis> are omitted in binding REST URL + (http://localhost:8080/api/<ver>/binding/<vhost node>/<vhost>/<exchangename>) the GET + request will result in returning all bindings for all queues for the given exchange in the + virtual host. </para> + <example> + <title>Examples of queue creation using curl (authenticating as user admin):</title> + <programlisting><![CDATA[ +#create a durable queue +curl --user admin -X PUT -d '{"durable":true}' http://localhost:8080/api/latest/queue/<vhostnode name>/<vhostname>/<queuename> +#create a durable priority queue +curl --user admin -X PUT -d '{"durable":true,"type":"priority"}' http://localhost:8080/api/latest/queue/<vhostnode name>/<vhostname>/<queuename> + ]]></programlisting> + </example> + <example> + <title>Example of binding a queue to an exchange using curl</title> + <programlisting><![CDATA[ +curl --user admin -X PUT -d '{}' http://localhost:8080/api/latest/binding/<vhostnode name>/<vhostname>/<exchangename>/<queue-name>/<binding-name> + ]]></programlisting> + </example> + <para> NOTE: These curl examples utilise unsecure HTTP transport. To use the examples it is first + necessary enable Basic authentication for HTTP within the HTTP Management Configuration (it is + off by default). For details see <xref + linkend="Java-Broker-Management-Managing-Plugin-HTTP"/> + </para> +</section> diff --git a/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml new file mode 100644 index 0000000000..9e2bfc4f63 --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/channels/Java-Broker-Management-Channel-Web-Console.xml @@ -0,0 +1,119 @@ +<?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-Web-Console"> + <title>Web Management Console</title> + <para> The Web Management Console provides a simple and intuitive interface for the Management + and Control of the Broker. From here, all aspects of the Broker can be controled, including: <itemizedlist> + <listitem> + <para>add, remove and monitor queues</para> + </listitem> + <listitem> + <para>inspect, move, copy or delete messages</para> + </listitem> + <listitem> + <para>add, remove and monitor virtualhosts</para> + </listitem> + <listitem> + <para>configure and control high availabiliy</para> + </listitem> + </itemizedlist> + </para> + <para>The remainder of the section provides an introduction to the web managemnet console and + its use.</para> + <section id="Java-Broker-Management-Channel-Web-Console-Accessing"> + <title>Accessing the Console</title> + <para>The Web Management Console is provided by the HTTP Management Plugin. Providing the + HTTP Management Plugin is in its default configuration, the Web Management Console can + be accessed by pointing a brower at the following URL:</para> + <para><literal>http://myhost.mydomain.com:8080</literal></para> + <para>The Console will prompt you to login using a username and password.</para> + <example> + <title>Web Management Console - Authentication</title> + <screenshot> + <graphic fileref="images/Management-Web-Auth.png" width="600px"/> + </screenshot> + </example> + </section> + <section id="Java-Broker-Management-Channel-Web-Console-Orientation"> + <title>Orientation</title> + <para>After you have logged on you will see a screen similar to the following. The elements + of the screen are now explained.</para> + <example> + <title>Web Management Orientation - Console</title> + <screenshot> + <graphic fileref="images/Management-Web-Console.png" width="600px"/> + </screenshot> + </example> + <para> + <itemizedlist> + <listitem> + <para><emphasis>A</emphasis> - Hierarchy view. Expandable/collapsable view showing all entities + within the Broker. Double click on an entity name to cause its tab to be + opened. </para> + </listitem> + <listitem> + <para><emphasis>B</emphasis> - Tab. Shows the details of an entity including its attributes and its + child entities. </para> + </listitem> + <listitem> + <para><emphasis>C</emphasis> - Occluded tab. Click tab name to bring the tab to the front.</para> + </listitem> + <listitem> + <para><emphasis>D</emphasis> - Auto restore check box. Checked tabs will be automatically restored on + subsequent login.</para> + </listitem> + <listitem> + <para><emphasis>E</emphasis> - Close. Click to close the tab.</para> + </listitem> + <listitem> + <para><emphasis>F</emphasis> - User Menu. Access to Preferences, Logout and Help.</para> + </listitem> + </itemizedlist> + </para> + <example> + <title>Web Management Orientation - Tab</title> + <screenshot> + <graphic fileref="images/Management-Web-Tab.png" width="600px"/> + </screenshot> + </example> + <para>The elements of a tab are now explained: <itemizedlist> + <listitem> + <para><emphasis>1</emphasis> - Attribute Panel. Shows the attributes of the entity. Click the panel + title bar opens/closes the panel.</para> + </listitem> + <listitem> + <para><emphasis>2</emphasis> - Child Panels. Panels containing a table listing the children of the entity. Click the panel + title bar opens/closes the panel.</para> + </listitem> + <listitem> + <para><emphasis>3</emphasis> - Child Row. Row summarizing a child entity. Double click to open the + child tab.</para> + </listitem> + <listitem> + <para><emphasis>4</emphasis> - Child Operations. Buttons to add a new child or perform operations on existing children.</para> + </listitem> + </itemizedlist> + </para> + </section> + +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Access-Control-Providers.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Access-Control-Providers.xml new file mode 100644 index 0000000000..5e05545daf --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Access-Control-Providers.xml @@ -0,0 +1,29 @@ +<?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-Managing-Access-Control-Providers"> + <title>Access Control Providers</title> + <para>An <link linkend="Java-Broker-Concepts-Access-Control-Providers">Access Control + Provider</link> governs who may do what within the Broker. It governs both messaging and + management.</para> + <para>See <xref linkend="Java-Broker-Security-ACLs"/></para> +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml new file mode 100644 index 0000000000..e97970549f --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Authentication-Providers.xml @@ -0,0 +1,51 @@ +<?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-Managing-Authentication-Providers"> + <title>Authentication Providers</title> + <para> + <link linkend="Java-Broker-Concepts-Authentication-Providers">Authentication Providers</link> are used by <link linkend="Java-Broker-Concepts-Ports">Ports</link> to + authenticate connections. </para> + <para>See <xref linkend="Java-Broker-Security-Authentication-Providers"/></para> + + <section id="Java-Broker-Management-Managing-Authentication-Providers-Attributes"> + <title>Attributes</title> + <para><itemizedlist> + <listitem> + <para><emphasis>Name the authentication</emphasis>.</para> + </listitem> + </itemizedlist></para> + <para>Other attributes are provider specific.</para> + </section> + <section id="Java-Broker-Management-Managing-Authentication-Providers-Children"> + <title>Children</title> + <para>None</para> + </section> + <section id="Java-Broker-Management-Managing-Authentication-Providers-Lifecycle"> + <title>Lifecycle</title> + <para>Not supported</para> + <important> + <para>When updating an existing authentication provider, changes become effective until + the Broker is restarted.</para> + </important> + </section> +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml new file mode 100644 index 0000000000..7c1f1e0c43 --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Broker.xml @@ -0,0 +1,83 @@ +<?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-Managing-Broker"> + <title>Broker</title> + <para>The <link linkend="Java-Broker-Concepts-Broker">Broker</link> is the principal entity. It is + composed on a number of other entities that colabrate together to provide message broker + facilities.</para> + <para>The Broker can only be managed via the HTTP management channel.</para> + <section id="Java-Broker-Management-Managing-Broker-Attributes"> + <title>Attributes</title> + <para><itemizedlist> + <listitem> + <para><emphasis>Name the Broker</emphasis>. This helps distinguish between Brokers in + environments that have many.</para> + </listitem> + <listitem> + <para><emphasis>Default Virtualhost</emphasis>. The default virtualhost is the one that + messaging clients will connect to if they do not specify a virtualhost name when they + form the connect to the Broker.</para> + </listitem> + <listitem> + <para><emphasis>Heartbeating</emphasis>. Enables heartbeats between Broker and Clients. + Heartbeats help discover severed TCP/IP connections in a timely manner.</para> + </listitem> + </itemizedlist></para> + </section> + <section id="Java-Broker-Management-Managing-Broker-Context"> + <title>Context</title> + <para> + <itemizedlist> + <listitem><para><emphasis>broker.flowToDiskThreshold</emphasis> Control the <link linkend="Java-Broker-Runtime-Flow-To-Disk">flow to disk</link> feature.</para></listitem> + </itemizedlist> + </para> + </section> + <section id="Java-Broker-Management-Managing-Broker-Children"> + <title>Children</title> + <para><itemizedlist> + <listitem> + <para><link linkend="Java-Broker-Management-Managing-Virtualhost-Nodes">Virtualhost + nodes</link></para> + </listitem> + <listitem> + <para><link linkend="Java-Broker-Management-Managing-Ports">Ports</link></para> + </listitem> + <listitem> + <para>Authentication Providers</para> + </listitem> + <listitem> + <para>Key Stores / Trust Stores</para> + </listitem> + <listitem> + <para>Group Providers</para> + </listitem> + <listitem> + <para>Access Control Providers</para> + </listitem> + </itemizedlist></para> + </section> + <section id="Java-Broker-Management-Managing-Broker-Lifecycle"> + <title>Lifecycle</title> + <para>Not supported</para> + </section> +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Entities-Matrix.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Entities-Matrix.xml new file mode 100644 index 0000000000..342798f5bc --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Entities-Matrix.xml @@ -0,0 +1,130 @@ +<?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-Managing-Entities-Matrix"> + <title>Entity/Management Channel Support Matrix</title> + <para>This tables indicates which management channels support the creation (C), update (U), or + deletion (D) of different entities within the Broker.</para> + <table frame="all"> + <title>Entity/Management Matrix</title> + <tgroup cols="4" align="left" colsep="1" rowsep="1"> + <colspec colname="entity"/> + <colspec colname="http"/> + <colspec colname="jmx"/> + <colspec colname="amqp"/> + <thead> + <row> + <entry>Entity</entry> + <entry>HTTP</entry> + <entry>JMX</entry> + <entry>AMQP</entry> + </row> + </thead> + <tbody> + <row> + <entry>Broker</entry> + <entry>U</entry> + <entry>No</entry> + <entry>No</entry> + </row> + <row> + <entry>Virtualhost Node</entry> + <entry>C/U/D</entry> + <entry>No</entry> + <entry>No</entry> + </row> + <row> + <entry>Virtualhost</entry> + <entry>C/U/D</entry> + <entry>No</entry> + <entry>No</entry> + </row> + <row> + <entry>Remote Replication Node</entry> + <entry>U/D</entry> + <entry>No</entry> + <entry>No</entry> + </row> + <row> + <entry>Exchange</entry> + <entry>C/D</entry> + <entry>C/D</entry> + <entry>C/D</entry> + </row> + <row> + <entry>Queue</entry> + <entry>C/D</entry> + <entry>C/U/D</entry> + <entry>C/D</entry> + </row> + <row> + <entry>Binding</entry> + <entry>C/D</entry> + <entry>C/D</entry> + <entry>C/D</entry> + </row> + <row> + <entry>Port</entry> + <entry>C/U/D</entry> + <entry>No</entry> + <entry>No</entry> + </row> + <row> + <entry>Authentication Providers</entry> + <entry>C/U/D</entry> + <entry>No</entry> + <entry>No</entry> + </row> + <row> + <entry>Group Providers</entry> + <entry>C//D</entry> + <entry>No</entry> + <entry>No</entry> + </row> + <row> + <entry>Access Control Provider</entry> + <entry>C//D</entry> + <entry>No</entry> + <entry>No</entry> + </row> + <row> + <entry>Keystores</entry> + <entry>C//D</entry> + <entry>No</entry> + <entry>No</entry> + </row> + <row> + <entry>Truststores</entry> + <entry>C//D</entry> + <entry>No</entry> + <entry>No</entry> + </row> + </tbody> + </tgroup> + </table> + <important> + <title>Note</title> + <para>It is currently only possible to modify a entity's context using the HTTP channel. + Furthermore, when using the JMX channel, it is not possible to assign non-String type + attributes in terms of context variables.</para> + </important> +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Exchanges.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Exchanges.xml new file mode 100644 index 0000000000..e24733c5b3 --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Exchanges.xml @@ -0,0 +1,79 @@ +<?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-Managing-Exchanges"> + <title>Exchanges</title> + <para><link linkend="Java-Broker-Concepts-Exchanges">Exchanges</link> can be managed using the + HTTP, JMX or AMQP channels.</para> + <section id="Java-Broker-Management-Managing-Exchanges-Types"> + <title>Types</title> + <para><itemizedlist> + <listitem> + <para>Direct</para> + </listitem> + <listitem> + <para>Topic</para> + </listitem> + <listitem> + <para>Fanout</para> + </listitem> + <listitem> + <para>Headers</para> + </listitem> + </itemizedlist> + </para> + </section> + <section id="Java-Broker-Management-Managing-Exchanges-Attributes"> + <title>Attributes</title> + <para><itemizedlist> + <listitem> + <para><emphasis>Name of the exchange</emphasis>. Message producers refer to this name when + producing messages.</para> + </listitem> + <listitem> + <para><emphasis>Type of the exchange</emphasis>. Can be either <link + linkend="Java-Broker-Concepts-Exchanges-Types-Direct">direct</link>, <link + linkend="Java-Broker-Concepts-Exchanges-Types-Topic">topic</link>, <link + linkend="Java-Broker-Concepts-Exchanges-Types-Fanout">fanout</link>, or <link + linkend="Java-Broker-Concepts-Exchanges-Types-Headers">headers</link>.</para> + </listitem> + <listitem> + <para><emphasis>Durable</emphasis>. Whether the exchange survives a restart.</para> + </listitem> + </itemizedlist></para> + </section> + <section id="Java-Broker-Management-Managing-Exchanges-Children"> + <title>Children</title> + <para> + <itemizedlist> + <listitem> + <para>Binding</para> + </listitem> + </itemizedlist> + </para> + </section> + <section id="Java-Broker-Management-Managing-Exchanges-Lifecycle"> + <title>Lifecycle</title> + <para>Not supported</para> + </section> + +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Group-Providers.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Group-Providers.xml new file mode 100644 index 0000000000..330b451550 --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Group-Providers.xml @@ -0,0 +1,26 @@ +<?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-Managing-Group-Providers"> + <title>Group Providers</title> + <para>See <xref linkend="Java-Broker-Security-Group-Providers"/></para> +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Keystores.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Keystores.xml new file mode 100644 index 0000000000..5e582027ae --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Keystores.xml @@ -0,0 +1,74 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE entities [ +<!ENTITY % entities SYSTEM "../../commonEntities.xml"> +%entities; +]> +<!-- + + 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-Managing-Keystores"> + <title>Keystores</title> + <para>A <link linkend="Java-Broker-Concepts-Keystores">Keystore</link> is required by a Port + in order to use SSL.</para> + <section id="Java-Broker-Management-Managing-Keystores-Attributes"> + <title>Attributes</title> + <para><itemizedlist> + <listitem> + <para><emphasis>Name the keystore</emphasis>. Used to identify the + keystore.</para> + </listitem> + <listitem> + <para><emphasis>Path</emphasis>. Path to keystore file</para> + </listitem> + <listitem> + <para><emphasis>Keystore password</emphasis>. Password used to secure the keystore<important> + <para> The password of the certificate used by the Broker <emphasis + role="bold">must</emphasis> match the password of the keystore + itself. This is a restriction of the Qpid Broker implementation. If + using the <ulink url="&oracleKeytool;">keytool</ulink> utility, note + that this means the argument to the <option>-keypass</option> option + must match the <option>-storepass</option> option. </para> + </important></para> + </listitem> + <listitem> + <para><emphasis>Certificate Alias</emphasis>. An optional way of specifying + which certificate the broker should use if the keystore contains multiple + entries.</para> + </listitem> + <listitem> + <para><emphasis>Manager Factory Algorithm</emphasis>. In keystores the have more + than one certificate, the alias identifies the certificate to be + used.</para> + </listitem> + <listitem> + <para><emphasis>Key Store Type</emphasis>. Type of Keystore.</para> + </listitem> + </itemizedlist></para> + </section> + <section id="Java-Broker-Management-Managing-Keystores-Children"> + <title>Children</title> + <para>None</para> + </section> + <section id="Java-Broker-Management-Managing-Keystores-Lifecycle"> + <title>Lifecycle</title> + <para>Not supported</para> + </section> +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-HTTP.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-HTTP.xml new file mode 100644 index 0000000000..963a1cfbe8 --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-HTTP.xml @@ -0,0 +1,63 @@ +<?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-Managing-Plugin-HTTP"> + <title>HTTP Plugin</title> + <para>The HTTP Plugin provides the <link linkend="Java-Broker-Management-Channel-HTTP">HTTP managenenent channel</link> comprising of the <link linkend="Java-Broker-Management-Channel-Web-Console">Web + Managemnt Console</link> and the <link linkend="Java-Broker-Management-Channel-REST-API">REST API</link>.</para> + <section id="Java-Broker-Management-Managing-Plugin-HTTP-Attributes"> + <title>Attributes</title> + <para> + <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> + </para> + </section> + <section id="Java-Broker-Management-Managing-Plugin-HTTP-Children"> + <title>Children</title> + <para>None</para> + </section> + <section id="Java-Broker-Management-Managing-Plugin-HTTP-Lifecycle"> + <title>Lifecycle</title> + <para>Not supported<important><para>NOTE: Changes to the Session Timeout attribute only take + effect at broker restart. </para></important></para> + </section> +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-JMX.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-JMX.xml new file mode 100644 index 0000000000..6a9e5ae9d4 --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Plugins-JMX.xml @@ -0,0 +1,29 @@ +<?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-Managing-Plugins-JMX"> + <title>JMX Plugin</title> + <para> + The JMX Plugin provides the <link linkend="Java-Broker-Management-Channel-JMX">JMX managenenent channel</link>. + </para> + <para>TODO</para> +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Ports.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Ports.xml new file mode 100644 index 0000000000..86fa3dfb82 --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Ports.xml @@ -0,0 +1,95 @@ +<?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-Managing-Ports"> + <title>Ports</title> + <para>Ports provide TCP/IP connectivity for messaging and management. A port is defined to use a + protocol. This can be an AMQP protocol for messaging or HTTP/JMX for management.</para> + <para>A port is defined to have one or more transports. A transport can either be plain (TCP) or + SSL. When SSL is in use, the port can be configured to accept or require client + authentication.</para> + <para>Any number of ports defined to use AMQP or HTTP protocols can be defined. JMX is limited + to a single port instance per JMX protocol type.</para> + <para>Ports can only be managed by the HTTP management channel.</para> + <section id="Java-Broker-Management-Managing-Ports-Attributes"> + <title>Attributes</title> + <para><itemizedlist> + <listitem> + <para><emphasis>Name the port</emphasis>.</para> + </listitem> + <listitem> + <para><emphasis>Port number</emphasis>.</para> + </listitem> + <listitem> + <para><emphasis>Binding address</emphasis>. Used to limit port binding to a + single network interface.</para> + </listitem> + <listitem> + <para><emphasis>Authentication Provider</emphasis>. The <link + linkend="Java-Broker-Concepts-Authentication-Providers">authentication + provider</link> used to authenticate incoming connections.</para> + </listitem> + <listitem> + <para><emphasis>Protocol(s)</emphasis>. A list of protocols to be supported by + the port. For messaging choose one or more AMQP protocols. For management + choose HTTP or on one the two JMX protocols.</para> + </listitem> + <listitem> + <para><emphasis>Transports</emphasis>. A list of transports supported by the + port. For messaging or HTTP management chose TCP, SSL or both. For JMX, the + TCP/SSL combination is not supported.</para> + </listitem> + <listitem> + <para><emphasis>Keystore</emphasis>. <link + linkend="Java-Broker-Management-Managing-Keystores">Keystore</link> + containing the Broker's private key. Required if the SSL is in use.</para> + </listitem> + <listitem> + <para><emphasis>Want/Need Client Auth</emphasis>. Client authentication can be + either accepted if offered (want), or demanded (need). When Client + Certificate Authentication is in use a Truststore must be configured. When + using Client Certificate Authentication it may be desirable to use the <link + linkend="Java-Broker-Security-External-Provider">External Authentication + Provider</link>.</para> + <para>JMX does not support client authentication.</para> + </listitem> + <listitem> + <para><emphasis>Truststore</emphasis>. <link + linkend="Java-Broker-Management-Managing-Truststores">Trust store</link> + contain an issuer certificate or the public keys of the clients themselves + if peers only is desired.</para> + </listitem> + </itemizedlist></para> + </section> + <section id="Java-Broker-Management-Managing-Ports-Children"> + <title>Children</title> + <para>None</para> + </section> + <section id="Java-Broker-Management-Managing-Ports-Lifecycle"> + <title>Lifecycle</title> + <para>Not supported</para> + <important> + <para>When updating an existing port, changes to SSL settings, binding address and port + numbers do not become effective until the Broker is restarted.</para> + </important> + </section> +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml new file mode 100644 index 0000000000..608552be90 --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Queues.xml @@ -0,0 +1,324 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE entities [ +<!ENTITY % entities SYSTEM "../../commonEntities.xml"> +%entities; +]> +<!-- + + 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-Managing-Queues"> + <title>Queues</title> + <para><link linkend="Java-Broker-Concepts-Queues">Queue</link>s are named entities that + hold/buffer messages for later delivery to consumer applications.</para> + <para>Queues can be managed using the HTTP, JMX or AMQP channels.</para> + <section id="Java-Broker-Management-Managing-Queues-Types"> + <title>Types</title> + <para>The Broker supports four different queue types, each with different delivery semantics.<itemizedlist> + <listitem> + <para><link linkend="Java-Broker-Management-Managing-Queues-Types-Standard" + >Standard</link> - a simple First-In-First-Out (FIFO) queue</para> + </listitem> + <listitem> + <para><link linkend="Java-Broker-Management-Managing-Queues-Types-Priority" + >Priority</link> - delivery order depends on the priority of each message</para> + </listitem> + <listitem> + <para><link linkend="Java-Broker-Management-Managing-Queues-Types-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-Management-Managing-Queues-Types-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> + <section id="Java-Broker-Management-Managing-Queues-Types-Standard"> + <title>Standard</title> + <para>A simple First-In-First-Out (FIFO) queue</para> + </section> + <section id="Java-Broker-Management-Managing-Queues-Types-Priority"> + <title>Priority</title> + <para>In a priority queue, messages on the queue are delivered in an order determined by the + <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#getJMSPriority()">JMS priority message + header</ulink> within the message. By default Qpid supports the 10 priority levels + mandated by JMS, with priority value 0 as the lowest priority and 9 as the highest. </para> + <para>It is possible to reduce the effective number of priorities if desired.</para> + <para>JMS defines the <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#DEFAULT_PRIORITY"> + default message priority</ulink> as 4. Messages sent without a specified priority use this + default. </para> + </section> + <section id="Java-Broker-Management-Managing-Queues-Types-Sorted"> + <title>Sorted Queues</title> + <para>Sorted queues allow the message delivery order to be determined by value of an arbitrary + <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#getStringProperty()">JMS message + property</ulink>. Sort order is alpha-numeric and the property value must have a type + java.lang.String.</para> + <para>Messages sent to a sorted queue without the specified JMS message property will be + inserted into the 'last' position in the queue.</para> + </section> + <section id="Java-Broker-Management-Managing-Queues-Types-LVQ"> + <title>Last Value Queues (LVQ)</title> + <para>LVQs (or conflation queues) are special queues that automatically discard any message + when a newer message arrives with the same key value. The key is specified by arbitrary + <ulink url="&oracleJeeDocUrl;javax/jms/Message.html#getPropertyNames()">JMS message + property</ulink>.</para> + <para>An example of an LVQ might be where a queue represents prices on a stock exchange: when + you first consume from the queue you get the latest quote for each stock, and then as new + prices come in you are sent only these updates. </para> + <para>Like other queues, LVQs can either be browsed or consumed from. When browsing an + individual subscriber does not remove the message from the queue when receiving it. This + allows for many subscriptions to browse the same LVQ (i.e. you do not need to create and + bind a separate LVQ for each subscriber who wishes to receive the contents of the + LVQ).</para> + <para>Messages sent to an LVQ without the specified property will be delivered as normal and + will never be "replaced".</para> + </section> + </section> + <section id="Java-Broker-Management-Managing-Queues-Attributes"> + <title>Attributes</title> + <para><itemizedlist> + <listitem> + <para><emphasis>Name of the queue</emphasis>. Message consumers and browsers refer to this + name when they wish to subscribe to queue to receive messages from it.</para> + </listitem> + <listitem> + <para><emphasis>Type of the queue</emphasis>. Can be either <link + linkend="Java-Broker-Management-Managing-Queues-Types-Standard">standard</link>, <link + linkend="Java-Broker-Management-Managing-Queues-Types-Priority">priority</link>, <link + linkend="Java-Broker-Management-Managing-Queues-Types-Sorted">sorted</link>, or <link + linkend="Java-Broker-Management-Managing-Queues-Types-LVQ">lvq</link>.</para> + </listitem> + <listitem> + <para><emphasis>Durable</emphasis>. Whether the queue survives a restart. Messages on a + non durable queue do not survive a restart even if they are marked persistent.</para> + </listitem> + <listitem> + <para><emphasis>Maximum/Minimum TTL</emphasis>. Defines a maximum and minimum + time-to-live. Messages arriving with ttl larger than the maximum will be overridden by + the maximum. Similarly, messages arriving with tll less than the miniumum (or no ttl at + all), will be overridden by the minimum.</para> + <para>Changing these values affects only new arrivals, existing messages already on the + queue are not affected.</para> + </listitem> + <listitem> + <para><emphasis>Message persistent override</emphasis>. Allow message persistent settings + of incoming messages to be overridden. Changing this value affects only new arrivals, + existing messages on the queue are not affected. </para> + </listitem> + <listitem> + <para><emphasis>Queue capacity</emphasis>. Queues have the ability to limit the of the + cumulative size of all the messages contained within the store. This feature is + described in detail <xref linkend="Java-Broker-Runtime-Disk-Space-Management"/>.</para> + </listitem> + <listitem> + <para><emphasis>Alerting Thresholds</emphasis>. Queues have the ability to alert on a + variety of conditions: totol queue depth exceeded a number or size, message age exceeded + a threshold, message size exceeded a threshold. These thresholds are soft. See <xref + linkend="Java-Broker-Appendix-Queue-Alerts"/></para> + </listitem> + <listitem> + <para><emphasis>Maximum Delivery Count/Alternate Exchange</emphasis>. See <xref + linkend="Java-Broker-Runtime-Handling-Undeliverable-Messages"/></para> + </listitem> + <listitem> + <para><emphasis>Message Groups</emphasis>. See <xref + linkend="Java-Broker-Management-Managing-Queues-Message-Grouping"/></para> + </listitem> + </itemizedlist></para> + </section> + <section id="Java-Broker-Management-Managing-Queue-Children"> + <title>Children</title> + <para> + <itemizedlist> + <listitem> + <para>Binding</para> + </listitem> + </itemizedlist> + </para> + </section> + <section id="Java-Broker-Management-Managing-Queue-Lifecycle"> + <title>Lifecycle</title> + <para>Not supported</para> + </section> + <section id="Java-Broker-Management-Managing-Queues-QueueDeclareArguments"> + <title>Queue Declare Arguments</title> + <para>To create a priority, sorted or LVQ queue programmatically from JMX or AMQP, pass the + appropriate queue-declare arguments.</para> + <table> + <title>Queue-declare arguments understood for priority, sorted and LVQ queues</title> + <tgroup cols="4"> + <thead> + <row> + <entry>Queue type</entry> + <entry>Argument name</entry> + <entry>Argument name</entry> + <entry>Argument Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>priority</entry> + <entry>x-qpid-priorities</entry> + <entry>java.lang.Integer</entry> + <entry>Specifies a priority queue with given number priorities</entry> + </row> + <row> + <entry>sorted</entry> + <entry>qpid.queue_sort_key</entry> + <entry>java.lang.String</entry> + <entry>Specifies sorted queue with given message property used to sort the + entries</entry> + </row> + <row> + <entry>lvq</entry> + <entry>qpid.last_value_queue_key</entry> + <entry>java.lang.String</entry> + <entry>Specifies lvq queue with given message property used to conflate the + entries</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section id="Java-Broker-Management-Managing-Queues-Message-Grouping"> + <title>Messaging Grouping</title> + <para> The broker allows messaging applications to classify a set of related messages as + belonging to a group. This allows a message producer to indicate to the consumer that a group + of messages should be considered a single logical operation with respect to the application. </para> + <para> The broker can use this group identification to enforce policies controlling how messages + from a given group can be distributed to consumers. For instance, the broker can be configured + to guarantee all the messages from a particular group are processed in order across multiple + consumers. </para> + <para> For example, assume we have a shopping application that manages items in a virtual + shopping cart. A user may add an item to their shopping cart, then change their mind and + remove it. If the application sends an <emphasis>add</emphasis> message to the broker, + immediately followed by a <emphasis>remove</emphasis> message, they will be queued in the + proper order - <emphasis>add</emphasis>, followed by <emphasis>remove</emphasis>. </para> + <para> However, if there are multiple consumers, it is possible that once a consumer acquires + the <emphasis>add</emphasis> message, a different consumer may acquire the + <emphasis>remove</emphasis> message. This allows both messages to be processed in parallel, + which could result in a "race" where the <emphasis>remove</emphasis> operation is incorrectly + performed before the <emphasis>add</emphasis> operation. </para> + <section id="Java-Broker-Management-Managing-Queues-GroupingMessages"> + <title>Grouping Messages</title> + <para> In order to group messages, the application would designate a particular message header + as containing a message's <emphasis>group identifier</emphasis>. The group identifier stored + in that header field would be a string value set by the message producer. Messages from the + same group would have the same group identifier value. The key that identifies the header + must also be known to the message consumers. This allows the consumers to determine a + message's assigned group. </para> + <para> The header that is used to hold the group identifier, as well as the values used as + group identifiers, are totally under control of the application. </para> + </section> + <section id="Java-Broker-Management-Managing-Queues-BrokerRole"> + <title> The Role of the Broker in Message Grouping </title> + <para> The broker will apply the following processing on each grouped message: <itemizedlist> + <listitem> + <para>Enqueue a received message on the destination queue.</para> + </listitem> + <listitem> + <para>Determine the message's group by examining the message's group identifier + header.</para> + </listitem> + <listitem> + <para>Enforce <emphasis>consumption ordering</emphasis> among messages belonging to the + same group. <emphasis>Consumption ordering</emphasis> means one of two things + depending on how the queue has been configured. </para> + <itemizedlist> + <listitem> + <para> In default mode, a group gets assigned to a single consumer for the lifetime + of that consumer, and the broker will pass all subsequent messages in the group to + that consumer. </para> + </listitem> + <listitem> + <para>In 'shared groups' mode (which gives the same behaviour as the Qpid C++ + Broker) the broker enforces a looser guarantee, namely that all the + <emphasis>currently unacknowledged messages</emphasis> in a group are sent to + the same consumer, but the consumer used may change over time even if the + consumers do not. This means that only one consumer can be processing messages + from a particular group at any given time, however if the consumer acknowledges + all of its acquired messages then the broker <emphasis>may</emphasis> pass the + next pending message in that group to a different consumer. </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </para> + <para> The absence of a value in the designated group header field of a message is treated as + follows: <itemizedlist> + <listitem> + <para> In default mode, failure for a message to specify a group is treated as a desire + for the message not to be grouped at all. Such messages will be distributed to any + available consumer, without the ordering quarantees imposed by grouping. </para> + </listitem> + <listitem> + <para> In 'shared groups' mode (which gives the same behaviour as the Qpid C++ Broker) + the broker assigns messages without a group value to a 'default group'. Therefore, all + such "unidentified" messages are considered by the broker as part of the same group, + which will handled like any other group. The name of this default group is + "qpid.no-group", although it can be customised as detailed below. </para> + </listitem> + </itemizedlist> + </para> + <para> Note that message grouping has no effect on queue browsers.</para> + <para> Note well that distinct message groups would not block each other from delivery. For + example, assume a queue contains messages from two different message groups - say group "A" + and group "B" - and they are enqueued such that "A"'s messages are in front of "B". If the + first message of group "A" is in the process of being consumed by a client, then the + remaining "A" messages are blocked, but the messages of the "B" group are available for + consumption by other consumers - even though it is "behind" group "A" in the queue. </para> + </section> + + </section> + <section id="Java-Broker-Management-Managing-Queues-SetLowPrefetch"> + <title>Using low pre-fetch with special queue types</title> + <para>Qpid clients receive buffered messages in batches, sized according to the pre-fetch value. + The current default is 500. </para> + <para>However, if you use the default value you will probably <emphasis>not</emphasis> see + desirable behaviour when using priority, sorted, lvq or grouped queues. Once the broker has + sent a message to the client its delivery order is then fixed, regardless of the special + behaviour of the queue. </para> + <para>For example, if using a priority queue and a prefetch of 100, and 100 messages arrive with + priority 2, the broker will send these messages to the client. If then a new message arrives + will priority 1, the broker cannot leap frog messages of lower priority. The priority 1 will + be delivered at the front of the next batch of messages to be sent to the client.</para> + <para> So, you need to set the prefetch values for your client (consumer) to make this sensible. + To do this set the Java system property <varname>max_prefetch</varname> on the client + environment (using -D) before creating your consumer. </para> + <para>A default for all client connections can be set via a system property: </para> + <programlisting> +-Dmax_prefetch=1 +</programlisting> + <para> The prefetch can be also be adjusted on a per connection basis by adding a + <varname>maxprefetch</varname> value to the <ulink url="&qpidjmsdocClientConectionUrl;" + >Connection URLs</ulink> + </para> + <programlisting> +amqp://guest:guest@client1/development?maxprefetch='1'&brokerlist='tcp://localhost:5672' +</programlisting> + <para>Setting the Qpid pre-fetch to 1 will give exact queue-type semantics as perceived by the + client however, this brings a performance cost. You could test with a slightly higher + pre-fetch to trade-off between throughput and exact semantics.</para> + </section> + + +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-RemoteReplicationNodes.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-RemoteReplicationNodes.xml new file mode 100644 index 0000000000..83f94d2fed --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-RemoteReplicationNodes.xml @@ -0,0 +1,112 @@ +<?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-Managing-RemoteReplicationNodes"> + <title>Remote Replication Nodes</title> + <para>Used for HA only. A <link linkend="Java-Broker-Concepts-RemoteReplicationNodes">remote replication node</link> is a representation of another virtualhost node + in the group. Remote replication nodes are not created directly. Instead the system + automatically creates a remote replciation node for every node in the group. It serves to + provide a view of the whole group from every node in the system.</para> + <section id="Java-Broker-Management-Managing-RemoteReplicationNodes-Attributes"> + <title>Attributes</title> + <para><itemizedlist> + <listitem> + <para><emphasis>Name the remote replication node</emphasis>. This is the name of the + remote virtualhost node</para> + </listitem> + <listitem> + <para><emphasis>Role</emphasis>. Indicates the role that the remote node is playing in the + group at this moment. <itemizedlist> + <listitem> + <para><emphasis>MASTER</emphasis> - Remote node is a master.</para> + </listitem> + <listitem> + <para><emphasis>REPLICA</emphasis> - Remote node is a replica.</para> + </listitem> + <listitem> + <para><emphasis>UNREACHABLE</emphasis> - Remote node unreachanble from this node. + This remote note may be down, or an network problem may prevent it from being + contacted.</para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para><emphasis>Join time</emphasis>. Time when first contact was established with this + node.</para> + </listitem> + <listitem> + <para><emphasis>Last known transaction id</emphasis>. Last transaction id reported + processed by node. This is an internal transaction counter and does not relate to any + value available to the messaging clients. This value can only be used to determine the + node is up to date relative to others in the group.</para> + </listitem> + </itemizedlist></para> + </section> + <section id="Java-Broker-Management-Managing-RemoteReplicationNodes-Children"> + <title>Children</title> + <para>None</para> + </section> + <section id="Java-Broker-Management-Managing-RemoteReplicationNodes-Lifecycle"> + <title>Lifecycle</title> + <para> + <itemizedlist> + <listitem> + <para><emphasis>Delete</emphasis>. Causes the remote node to be permanently removed from + the group. This operation should be used when the virtualhost node cannot be deleted + from its own Broker, for instance, if a Broker has been destroyed by machine + failure.</para> + </listitem> + </itemizedlist> + </para> + </section> + <section id="Java-Broker-Management-Managing-RemoteReplication-Nodes-Operations"> + <title>Operations</title> + <para> + <itemizedlist> + <listitem> + <para><emphasis>Transfer Master</emphasis>. Initiates a process where a master is moved to + anther node in the group. The transfer sequence is as follows. <orderedlist> + <listitem> + <para>Group waits until the proposed master is reasonable up to date.</para> + </listitem> + <listitem> + <para>Any in-flight transactions on the current master are blocked.</para> + </listitem> + <listitem> + <para>The current master awaits the proposed master to become up to date.</para> + </listitem> + <listitem> + <para>The mastership is transfered. This will automatically disconnect messaging + clients from the old master, and in-flight transactions are rolled back. Messaging + clients reconnect to the new master.</para> + </listitem> + <listitem> + <para>The old master will rejoin as a replica.</para> + </listitem> + </orderedlist> + </para> + </listitem> + </itemizedlist> + </para> + </section> +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Truststores.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Truststores.xml new file mode 100644 index 0000000000..fb4f8efcaf --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Truststores.xml @@ -0,0 +1,76 @@ +<?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-Managing-Truststores"> + <title>Truststores</title> + <para> A <link linkend="Java-Broker-Concepts-Truststores">Truststore</link> is required by a + Port in order to SSL client authentication. Some authentication provides also use a + truststore when connecting to authentication systems that are protected by a private issuer + SSL certificate.</para> + <section id="Java-Broker-Management-Managing-Truststores-Attributes"> + <title>Attributes</title> + <para><itemizedlist> + <listitem> + <para><emphasis>Name the truststore</emphasis>. Used to identify the + truststore.</para> + </listitem> + <listitem> + <para><emphasis>Path</emphasis>. Path to truststore file</para> + </listitem> + <listitem> + <para><emphasis>Truststore password</emphasis>. Password used to secure the truststore<important> + <para> The password of the certificate used by the Broker <emphasis + role="bold">must</emphasis> match the password of the keystore + itself. </para> + </important></para> + </listitem> + <listitem> + <para><emphasis>Certificate Alias</emphasis>. An optional way of specifying + which certificate the broker should use if the keystore contains multiple + entries.</para> + </listitem> + <listitem> + <para><emphasis>Manager Factory Algorithm</emphasis>. In keystores the have more + than one certificate, the alias identifies the certificate to be + used.</para> + </listitem> + <listitem> + <para><emphasis>Key Store Type</emphasis>. Type of Keystore.</para> + </listitem> + <listitem> + <para><emphasis>Peers only</emphasis>. When "Peers Only" option is selected for + the Truststore it will allow logging in for the clients with the certificate + exactly matching the certificate loaded in the Truststore database, thus, + authenticating the connections with self signed certificates not nessesary + signed by CA.</para> + </listitem> + </itemizedlist></para> + </section> + <section id="Java-Broker-Management-Managing-Truststores-Children"> + <title>Children</title> + <para>None</para> + </section> + <section id="Java-Broker-Management-Managing-Truststores-Lifecycle"> + <title>Lifecycle</title> + <para>Not supported</para> + </section> +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-VirtualHostNodes.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-VirtualHostNodes.xml new file mode 100644 index 0000000000..1d9643e2c7 --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-VirtualHostNodes.xml @@ -0,0 +1,124 @@ +<?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-Managing-Virtualhost-Nodes"> + <title>Virtualhost Nodes</title> + <para>Virtualhost nodes can only be managed by the HTTP management channel.</para> + <section id="Java-Broker-Management-Managing-Virtualhost-Nodes-Types"> + <title>Types</title> + <para> The following virtualhost nodes types are supported. <itemizedlist> + <listitem><para>BDB - Node backed with Oracle BDB <footnote> + <para>Oracle BDB JE is optional. See <xref + linkend="Java-Broker-Miscellaneous-Installing-Oracle-BDB-JE"/>.</para> + </footnote></para></listitem> + <listitem><para>BDB HA - Node backed with Oracle BDB utilising High Availablity</para></listitem> + <listitem><para>DERBY - Node backed with Apache Derby</para></listitem> + <listitem><para>JDBC - Node backed with an external database <footnote> + <para>JDBC 4.0 compatible drivers must be available. See <xref + linkend="Java-Broker-Miscellaneous-Installing-External-JDBC-Driver"/></para> + </footnote></para></listitem> + <listitem><para>JSON - Node backed with a file containing json</para></listitem> + <listitem><para>Memory - In-memory node (changes lost on Broker restart)</para></listitem> + </itemizedlist> + </para> + </section> + <section id="Java-Broker-Management-Managing-Virtualhost-Nodes-Attributes"> + <title>Attributes</title> + <para><itemizedlist> + <listitem> + <para><emphasis>Name the virtualhost node</emphasis>.</para> + </listitem> + <listitem> + <para><emphasis>Store Path or JDBC URL.</emphasis> Refers the location used to store the + configuration of the virtualhost.</para> + </listitem> + <listitem> + <para><emphasis>Role</emphasis> (HA only). The role that this node is currently playing in the + group. <itemizedlist> + <listitem> + <para>MASTER - Virtualhost node is a master.</para> + </listitem> + <listitem> + <para>REPLICA - Virtualhost node is a replica.</para> + </listitem> + <listitem> + <para>WAITING - Virtualhost node is awaiting an election result, or may be awaiting + more nodes to join in order that an election may be held.</para> + </listitem> + <listitem> + <para>DETACHED - Virtualhost node is disconnected from the group.</para> + </listitem> + </itemizedlist></para> + </listitem> + <listitem> + <para><emphasis>Priority</emphasis> (HA only). The priority of this node when elections occurs. The attribute can be used to make it more likely for a node to be elected than other nodes, or disallow the node from never being elected at all. See <xref linkend="Java-Broker-High-Availability"/></para> + </listitem> + <listitem> + <para><emphasis>Minimum Number Of Nodes</emphasis> (HA only - groups of three or more). Allows the number of nodes required to hold an election to be reduced in order that service can be restore when less than quorum nodes are present. See <xref linkend="Java-Broker-High-Availability"/></para> + </listitem> + <listitem> + <para><emphasis>Designated Primary</emphasis> (HA only - groups of two). Allows a single node in a two node group to operate solo. See <xref linkend="Java-Broker-High-Availability"/></para> + </listitem> + </itemizedlist></para> + </section> + <section id="Java-Broker-Management-Managing-Virtualhost-Node-Children"> + <title>Children</title> + <para> + <itemizedlist> + <listitem> + <para><link linkend="Java-Broker-Management-Managing-Virtualhosts">Virtualhost</link></para> + </listitem> + <listitem> + <para><link linkend="Java-Broker-Management-Managing-RemoteReplicationNodes">Remote Replication Nodes</link></para> + </listitem> + </itemizedlist> + </para> + </section> + <section id="Java-Broker-Management-Managing-Virtualhost-Node-Lifecycle"> + <title>Lifecycle</title> + <para> + <itemizedlist> + <listitem> + <para><emphasis>Stop</emphasis>. Stops the virtualhost node. This closes any existing + messaging connections to the virtualhost and prevents new ones. Any inflight + transactions are rolled back. Non durable queues and exchanges are lost. Transient + messages or persistent messages on non-durable queues are lost.</para> + <para>When HA is in use, stopping the virtualhost node stops the virtualhost node from + participating in the group. If the node was in the master role, the remaining nodes will + try to conduct an election and elect a new master. If the node was in the replica role, + the node will cease to keep up to date with later transactions. A stopped node does not + vote in elections. Other nodes in the group will report the stopped node as + unreachable.</para> + </listitem> + <listitem> + <para><emphasis>Start</emphasis>. Activates the virtualhost node.</para> + </listitem> + <listitem> + <para><emphasis>Delete</emphasis>. Deletes the virtualhost node and the virtualhost + contained within it. All exchanges and queues, any the messages contained within it are + removed. In the HA case, deleting the virtualhost node causes it be be removed + permantently from the group.</para> + </listitem> + </itemizedlist> + </para> + </section> +</section> diff --git a/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Virtualhosts.xml b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Virtualhosts.xml new file mode 100644 index 0000000000..b570d87ae7 --- /dev/null +++ b/qpid/doc/book/src/java-broker/management/managing/Java-Broker-Management-Managing-Virtualhosts.xml @@ -0,0 +1,117 @@ +<?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-Managing-Virtualhosts"> + <title>VirtualHosts</title> + <para>A virtualhost is a independent namespace in which messaging is performed. Virtualhosts are + responsible for the storage of message data.</para> + <para>Virtualhosts can only be managed by the HTTP management channel.</para> + <section id="Java-Broker-Management-Managing-Virtualhosts-Types"> + <title>Types</title> + <para>The following virtualhost types are supported. <itemizedlist> + <listitem> + <para>BDB - Virtualhost backed with Oracle BDB <footnote> + <para>Oracle BDB JE is optional. See <xref + linkend="Java-Broker-Miscellaneous-Installing-Oracle-BDB-JE"/>.</para> + </footnote></para> + </listitem> + <listitem> + <para>BDB HA - Virtualhost backed with Oracle BDB utilising High Availablity</para> + </listitem> + <listitem> + <para>DERBY - Virtualhost backed with Apache Derby</para> + </listitem> + <listitem> + <para>JDBC - Virtualhost backed with an external database <footnote> + <para>JDBC 4.0 compatible drivers must be available. See <xref + linkend="Java-Broker-Miscellaneous-Installing-External-JDBC-Driver"/></para> + </footnote></para> + </listitem> + <listitem> + <para>Memory - In-memory node (changes lost on Broker restart)</para> + </listitem> + <listitem> + <para>Provided - Virtualhost that colocates message data within the parent virtualhost + node <footnote> + <para>Not available if Virtualhost Node type is JSON.</para> + </footnote>.</para> + </listitem> + </itemizedlist> + </para> + </section> + <section id="Java-Broker-Management-Managing-Virtualhost-Attributes"> + <title>Attributes</title> + <para><itemizedlist> + <listitem> + <para><emphasis>Name the virtualhost</emphasis>. This is the name the messaging clients + refer to when forming a connection to the Broker.</para> + </listitem> + <listitem> + <para><emphasis>Store Path/JDBC URL</emphasis>. Refers the file system location or + database URL used to store the message data.</para> + </listitem> + <listitem> + <para><emphasis>Store overflow/underflow</emphasis>. Some virtualhosts have the ability to + limit the of the cumulative size of all the messages contained within the store. This + feature is described in detail <xref linkend="Java-Broker-Runtime-Disk-Space-Management" + />.</para> + </listitem> + <listitem> + <para><emphasis>Store transaction timeouts</emphasis>. Warns of long running producer + transactions. See <xref linkend="Java-Broker-Runtime-Producer-Transaction-Timeout" + /></para> + </listitem> + </itemizedlist></para> + </section> + <section id="Java-Broker-Management-Managing-Virtualhost-Children"> + <title>Children</title> + <para> + <itemizedlist> + <listitem> + <para><link linkend="Java-Broker-Management-Managing-Exchanges">Exchange</link></para> + </listitem> + <listitem> + <para><link linkend="Java-Broker-Management-Managing-Queues">Queue</link></para> + </listitem> + <listitem> + <para>Connection</para> + </listitem> + </itemizedlist> + </para> + </section> + <section id="Java-Broker-Management-Managing-Virtualhost-Lifecycle"> + <title>Lifecycle</title> + <para> + <itemizedlist> + <listitem> + <para><emphasis>Stop</emphasis>. Stops the virtualhost. This closes any existing messaging + connections to the virtualhost and prevents new ones. Any inflight transactions are + rolled back. Non durable queues and non durable exchanges are lost. Transient messages + or persistent messages on non-durable queues are lost.</para> + </listitem> + <listitem> + <para><emphasis>Start</emphasis>. Activates the virtualhost.</para> + </listitem> + </itemizedlist> + </para> + </section> +</section> diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml index 956981ecdc..5db6d4aa19 100644 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml +++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-Book.xml @@ -28,9 +28,6 @@ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Getting-And-Dependencies.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Examples.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Understanding.xml"/> - <!-- TODO: - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-JMS-Extensions.xml"/> - --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-JNDI-Properties-Format.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Connection-URL.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Binding-URL.xml"/> @@ -42,7 +39,8 @@ --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Appendix-Exceptions.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-Appendix-Maven.xml"/> - + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="JMS-Client-JMS-Extensions.xml"/> + </book> diff --git a/qpid/doc/book/src/jms-client-0-8/JMS-Client-JMS-Extensions.xml b/qpid/doc/book/src/jms-client-0-8/JMS-Client-JMS-Extensions.xml index bdc7832c88..2b78407897 100644 --- a/qpid/doc/book/src/jms-client-0-8/JMS-Client-JMS-Extensions.xml +++ b/qpid/doc/book/src/jms-client-0-8/JMS-Client-JMS-Extensions.xml @@ -26,8 +26,66 @@ --> -<chapter id="JMS-Client-0-8-JMS-Extensions"> +<appendix id="JMS-Client-0-8-Appendix-JMS-Extensions"> <title>JMS Extensions</title> + <para>This section illustrates using Qpid specific JMX extentions for the managament of queues, + exchanges and bindings.</para> + <para> + <important>It is not recommended that these extensions are normally used. Instead, the reader is + directed towards the Managment interfaces of the Broker.</important></para> + <section id="JMS-Client-0-8-Appendix-JMS-Extensions-Queue"> + <title>Queue Management</title> + <para>These extensions allow queues to be created or removed.</para> + <section id="JMS-Client-0-8-Appendix-JMS-Extensions-Queue-Creation"> + <title>Queue creation</title> + <para>The following example illustrates the creation of the a LVQ queue from a + javax.jms.Session object. Note that this utilises a Qpid specific extension to JMS and + involves casting the session object back to its Qpid base-class.</para> + <example> + <title>Creation of an LVQ using the Qpid extension to JMS</title> + <programlisting><![CDATA[Map<String,Object> arguments = new HashMap<String, Object>(); +arguments.put("qpid.last_value_queue_key","ISIN"); +AMQDestination amqQueue = (AMQDestination) context.lookup("myqueue"); +((AMQSession<?,?>) session).createQueue( + AMQShortString.valueOf(amqQueue.getQueueName()), + amqQueue.isAutoDelete(), + amqQueue.isDurable(), + amqQueue.isExclusive(), + arguments); +]]></programlisting> + </example> + </section> + <section id="JMS-Client-0-8-Appendix-JMS-Extensions-Binding"> + <title>Binding Management</title> + <para>These extensions allow bindings to be created or removed.</para> - <para>TODO</para> -</chapter> + <section id="JMS-Client-0-8-Appendix-JMS-Extensions-Binding-Creation"> + <title>Binding creation</title> + <para>The following example illustrates the creation of queue binding to topic exchange with + JMS client.</para> + <example> + <title>Binding a queue using JMS</title> + <programlisting><![CDATA[ConnectionFactory connectionFactory = ... +Connection connection = connectionFactory.createConnection(); +AMQSession<?, ?> session = (AMQSession<?,?>)connection.createSession(false, Session.AUTO_ACKNOWLEDGE); + +... + +AMQShortString queueName = new AMQShortString("testQueue"); +AMQShortString routingKey = new AMQShortString("testRoutingKey"); +AMQDestination destination = (AMQDestination) session.createQueue(queueName.asString()); + +... + +// binding arguments +Map<String, Object> arguments = new HashMap<String, Object>(); +arguments.put("x-filter-jms-selector", "application='app1'"); + +// create binding +session.bindQueue(queueName, routingKey, FieldTable.convertToFieldTable(arguments), + new AMQShortString("amq.topic"), destination);]]></programlisting> + </example> + </section> + </section> + </section> +</appendix> |
