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