doc/java-broker/src/docbkx/Java-Broker-Initial-Configuration.xml - qpid-broker-j - Git at Google

 <?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>User Connection Limit 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>. 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.
         </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-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">
                     <colspec colnum="1" colname="name" colwidth="1*"/>
                     <colspec colnum="2" colname="description" colwidth="1*"/>
                     <colspec colnum="3" colname="value" colwidth="1*"/>
                     <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 at first broker
             startup 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" : "9.0",
     "authenticationproviders" : [ {
       "name" : "plain",
       "type" : "Plain",
       "users" : [ {
       "name" : "guest",
       "type" : "managed",
       "password" : "guest"
       } ]
     } ],
     "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" : "Statistics",
       "type" : "NameAndLevel",
       "level" : "INFO",
       "loggerName" : "qpid.statistics.*"
     } ]
   }, {
     "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.*"
     }, {
       "name" : "Statistics",
       "type" : "NameAndLevel",
       "level" : "INFO",
       "loggerName" : "qpid.statistics.*"
     } ]
   } ],
   "ports" : [  {
     "name" : "AMQP",
     "port" : "\${qpid.amqp_port}",
     "authenticationProvider" : "plain",
     "virtualhostaliases" : [ {
        "name" : "nameAlias",
        "type" : "nameAlias"
     }, {
         "name" : "defaultAlias",
         "type" : "defaultAlias"
     }, {
         "name" : "hostnameAlias",
         "type" : "hostnameAlias"
     } ]
   }, {
     "name" : "HTTP",
     "port" : "\${qpid.http_port}",
     "authenticationProvider" : "plain",
     "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 <emphasis>default</emphasis>.</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>

     <section xml:id="Java-Broker-Virtual-Host-Initial-Configuration">
         <title>Virtualhost Initial Configuration</title>
         <para>
             <emphasis>Virtualhost</emphasis> initial configuration can be specified in <emphasis>Virtualhost node</emphasis>
             attribute <emphasis>virtualHostInitialConfiguration</emphasis>. On first startup,
             the <emphasis>virtualhost</emphasis> is created based on provided initial configuration.
             You can define there manageable <emphasis>Virtualhost</emphasis> attributes and children like exchanges, queues, etc.
         </para>
         <para>
             The attribute <varname>virtualHostInitialConfiguration</varname> can have a value of <emphasis>URL</emphasis>
             to an external resource where <emphasis>virtualhost</emphasis> initial configuration is provided in json format, or,
             it can hold a string value with initial configuration in stringified json format. If required, you can
             specify initial configuration as context variable which can be resolved as <emphasis>URL</emphasis>
             to external resource or stringified json.
         </para>
         <example>
         <title>Example of virtual host initial configuration provided as stringified JSON</title>
         <programlisting>
             ...
             "virtualhostnodes" : [ {
             "name" : "default",
             "type" : "JSON",
             "defaultVirtualHostNode" : "true",
             "virtualHostInitialConfiguration" : "{\"type\":\"BDB\",\"nodeAutoCreationPolicies\":[{\"patterns\":\".*\",\"createdOnPublish\":\"true\",\"createdOnConsume\":\"true\",\"nodeType\":\"queue\"}]}"
             } ]
             ...</programlisting>
         </example>
         <para>After creation of <emphasis>virtualhost</emphasis> the value of
             <varname>virtualHostInitialConfiguration</varname> is set to an empty string.</para>
     </section>
 </chapter>
	<?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>User Connection Limit 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>. 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.
	</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-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">
	<colspec colnum="1" colname="name" colwidth="1*"/>
	<colspec colnum="2" colname="description" colwidth="1*"/>
	<colspec colnum="3" colname="value" colwidth="1*"/>
	<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 at first broker
	startup 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" : "9.0",
	"authenticationproviders" : [ {
	"name" : "plain",
	"type" : "Plain",
	"users" : [ {
	"name" : "guest",
	"type" : "managed",
	"password" : "guest"
	} ]
	} ],
	"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" : "Statistics",
	"type" : "NameAndLevel",
	"level" : "INFO",
	"loggerName" : "qpid.statistics.*"
	} ]
	}, {
	"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.*"
	}, {
	"name" : "Statistics",
	"type" : "NameAndLevel",
	"level" : "INFO",
	"loggerName" : "qpid.statistics.*"
	} ]
	} ],
	"ports" : [ {
	"name" : "AMQP",
	"port" : "\${qpid.amqp_port}",
	"authenticationProvider" : "plain",
	"virtualhostaliases" : [ {
	"name" : "nameAlias",
	"type" : "nameAlias"
	}, {
	"name" : "defaultAlias",
	"type" : "defaultAlias"
	}, {
	"name" : "hostnameAlias",
	"type" : "hostnameAlias"
	} ]
	}, {
	"name" : "HTTP",
	"port" : "\${qpid.http_port}",
	"authenticationProvider" : "plain",
	"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 <emphasis>default</emphasis>.</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>

	<section xml:id="Java-Broker-Virtual-Host-Initial-Configuration">
	<title>Virtualhost Initial Configuration</title>
	<para>
	<emphasis>Virtualhost</emphasis> initial configuration can be specified in <emphasis>Virtualhost node</emphasis>
	attribute <emphasis>virtualHostInitialConfiguration</emphasis>. On first startup,
	the <emphasis>virtualhost</emphasis> is created based on provided initial configuration.
	You can define there manageable <emphasis>Virtualhost</emphasis> attributes and children like exchanges, queues, etc.
	</para>
	<para>
	The attribute <varname>virtualHostInitialConfiguration</varname> can have a value of <emphasis>URL</emphasis>
	to an external resource where <emphasis>virtualhost</emphasis> initial configuration is provided in json format, or,
	it can hold a string value with initial configuration in stringified json format. If required, you can
	specify initial configuration as context variable which can be resolved as <emphasis>URL</emphasis>
	to external resource or stringified json.
	</para>
	<example>
	<title>Example of virtual host initial configuration provided as stringified JSON</title>
	<programlisting>
	...
	"virtualhostnodes" : [ {
	"name" : "default",
	"type" : "JSON",
	"defaultVirtualHostNode" : "true",
	"virtualHostInitialConfiguration" : "{\"type\":\"BDB\",\"nodeAutoCreationPolicies\":[{\"patterns\":\".*\",\"createdOnPublish\":\"true\",\"createdOnConsume\":\"true\",\"nodeType\":\"queue\"}]}"
	} ]
	...</programlisting>
	</example>
	<para>After creation of <emphasis>virtualhost</emphasis> the value of
	<varname>virtualHostInitialConfiguration</varname> is set to an empty string.</para>
	</section>
	</chapter>