| <?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. |
| |
| --> |
| |
| <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Java-Broker-Initial-Configuration"> |
| <title>Initial Configuration</title> |
| |
| |
| <section xml: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 performed 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 database 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 Nodes</para> |
| </listitem> |
| <listitem> |
| <para>Loggers</para> |
| </listitem> |
| <listitem> |
| <para>Ports</para> |
| </listitem> |
| <listitem> |
| <para>Authentication Providers (optionally with Users for managing users Authentication Providers)</para> |
| </listitem> |
| <listitem> |
| <para>Access Control Providers</para> |
| </listitem> |
| <listitem> |
| <para>Group Providers (optionally with Groups and GroupMembers for managing groups Group Providers)</para> |
| </listitem> |
| <listitem> |
| <para>Key stores</para> |
| </listitem> |
| <listitem> |
| <para>Trust stores</para> |
| </listitem> |
| <listitem> |
| <para>Plugins</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 xml: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 xml:id="Java-Broker-Initial-Configuration-Initial-Config-Location"> |
| <title>'Initial Configuration' Location</title> |
| <para> The 'Initial Configuration' JSON file is used when initialising 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 xml: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 Broker's 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-Initial-Configuration-Example"/> |
| </para> |
| |
| </section> |
| |
| <section xml: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 xml:id="Java-Broker-Initial-Configuration-Type"> |
| <title>Configuration Store Type</title> |
| <para> There are currently several implementations of the pluggable Broker Configuration Store: |
| <variablelist> |
| <varlistentry> |
| <term>JSON</term> |
| <listitem><para>the default one which persists content to disk in a JSON file</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>Memory</term> |
| <listitem><para>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></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>DERBY</term> |
| <listitem><para>stores configuration in embedded derby store</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>BDB</term> |
| <listitem><para>stores configuration in Berkeley DB store</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>JDBC</term> |
| <listitem><para>stores configuration in external RDBMS using JDBC</para></listitem> |
| </varlistentry> |
| </variablelist> |
| </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 alternative, |
| 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> |
| <para>Another example of broker startup with configuration in DERBY network server</para> |
| <screen> |
| $ ./qpid-server -st JDBC \ |
| -prop "systemConfig.connectionUrl=jdbc:derby://localhost:1527/path/to/store;create=true" \ |
| -prop "systemConfig.username=test" -prop "systemConfig.password=password" |
| </screen> |
| </section> |
| |
| <section xml:id="Java-Broker-Initial-Configuration-Configuration-Properties"> |
| <title>Customising Configuration using Configuration Properties</title> |
| <para> It is possible 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 ConfigurationProperties 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.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-Initial-Configuration-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 value 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 xml:id="Java-Broker-Initial-Configuration-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> |
| { |
| "name": "\${broker.name}", |
| "modelVersion": "6.0", |
| "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" |
| }] |
| } ], |
| "brokerloggers" : [ { |
| "name" : "logfile", |
| "type" : "File", |
| "fileName" : "\${qpid.work_dir}\${file.separator}log\${file.separator}qpid.log", |
| "brokerloginclusionrules" : [ { |
| "name" : "Root", |
| "type" : "NameAndLevel", |
| "level" : "WARN", |
| "loggerName" : "ROOT" |
| }, { |
| "name" : "Qpid", |
| "type" : "NameAndLevel", |
| "level" : "INFO", |
| "loggerName" : "org.apache.qpid.*" |
| }, { |
| "name" : "Operational", |
| "type" : "NameAndLevel", |
| "level" : "INFO", |
| "loggerName" : "qpid.message.*" |
| } ] |
| }, { |
| "name" : "memory", |
| "type" : "Memory", |
| "brokerloginclusionrules" : [ { |
| "name" : "Root", |
| "type" : "NameAndLevel", |
| "level" : "WARN", |
| "loggerName" : "ROOT" |
| }, { |
| "name" : "Qpid", |
| "type" : "NameAndLevel", |
| "level" : "INFO", |
| "loggerName" : "org.apache.qpid.*" |
| }, { |
| "name" : "Operational", |
| "type" : "NameAndLevel", |
| "level" : "INFO", |
| "loggerName" : "qpid.message.*" |
| } ] |
| } ], |
| "ports" : [ { |
| "name" : "AMQP", |
| "port" : "\${qpid.amqp_port}", |
| "authenticationProvider" : "passwordFile", |
| "virtualhostaliases" : [ { |
| "name" : "nameAlias", |
| "type" : "nameAlias" |
| }, { |
| "name" : "defaultAlias", |
| "type" : "defaultAlias" |
| }, { |
| "name" : "hostnameAlias", |
| "type" : "hostnameAlias" |
| } ] |
| }, { |
| "name" : "HTTP", |
| "port" : "\${qpid.http_port}", |
| "authenticationProvider" : "passwordFile", |
| "protocols" : [ "HTTP" ] |
| }], |
| "virtualhostnodes" : [ { |
| "name" : "default", |
| "type" : "JSON", |
| "defaultVirtualHostNode" : "true", |
| "virtualHostInitialConfiguration" : "\\\${qpid.initial_config_virtualhost_config}" |
| } ], |
| "plugins" : [ { |
| "type" : "MANAGEMENT-HTTP", |
| "name" : "httpManagement" |
| } ] |
| } |
| </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> Two Port entries: "AMQP", "HTTP" |
| </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 configuration 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>One management plugin: "httpManagement" of type "MANAGEMENT-HTTP".</para> |
| </listitem> |
| <listitem> |
| <para>Broker attributes are stored as a root entry.</para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| </example> |
| </section> |
| |
| </chapter> |
