From 1cff5b63b5503feaa555c9f31ddc057fe9a18fdd Mon Sep 17 00:00:00 2001 From: Keith Wall Date: Mon, 6 Oct 2014 06:56:59 +0000 Subject: 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 --- .../Java-Broker-Initial-Configuration.xml | 360 +++++++++++++++++++++ 1 file changed, 360 insertions(+) create mode 100644 qpid/doc/book/src/java-broker/Java-Broker-Initial-Configuration.xml (limited to 'qpid/doc/book/src/java-broker/Java-Broker-Initial-Configuration.xml') 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 @@ + + + + + Initial Configuration + + +
+ Introduction + This section describes how to perform initial configuration on the command line. Once + the Broker is started, subsequent management is perfomed using the Management interfaces + 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: + + Broker + + + Virtual Host + + + Port + + + Authentication Provider + + + Access Control Provider + + + Group Provider + + + Key store + + + Trust store + + + Plugin + + + + + 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 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 -sp ./my-broker-configuration.json + + + 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 -icp ./my-initial-configuration.json + + + 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 + + + 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 -os -icp ./my-initial-configuration.json + + 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 -st memory + + 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. + + 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 running the broker on Windows and starting it via the qpid-server.bat + file, the "name=value" argument MUST be quoted. + +
+ +
+ Example of JSON 'Initial Configuration' + An example of the default 'Initial Configuration' JSON file the broker uses is + provided below: + + JSON 'Initial configuration' File + + In the configuration above the following entries are stored: + + Authentication Provider of type + PlainPasswordFile with name "passwordFile". + + + + Four Port entries: "AMQP", "HTTP", "RMI_REGISTRY", "JMX_CONNECTOR". + + + + 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 + JSON configuration store, the message data will + be stored in a DERBY message store. + + + Two management plugins: "jmxManagement" of type "MANAGEMENT-JMX" and + "httpManagement" of type "MANAGEMENT-HTTP". + + + Broker attributes are stored as a root entry. + + + + +
+ + -- cgit v1.2.1