path: root/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Config-Files.xml

<?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>