diff options
Diffstat (limited to 'qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Config-Files.xml')
| -rw-r--r-- | qpid/doc/book/src/java-broker/Java-Broker-Configuring-And-Managing-Config-Files.xml | 286 |
1 files changed, 142 insertions, 144 deletions
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 66d471fb37..a184fea671 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 @@ -21,158 +21,156 @@ --> <section id="Java-Broker-Configuring-And-Managing-Config-Files"> -<title>Config Files</title> +<title>Broker Configuration</title> - <para> - This section shows how to configure and manage broker. - </para> + <para>This section provides the details about broker configuration store.</para> - <section role="h2" id="Java-Broker-Configuring-And-Managing-Config-Files-Configuration"> - <title>Configuration file</title> - <para>Broker can be configured using XML configuration files. By default, broker is looking for configuration file at ${QPID_HOME}/etc/config.xml. The default configuration location can be overridden by specifying command line option <emphasis>-c <path to configuration></emphasis> on broker start up.</para> - </section> - - <section role="h2" id="Java-Broker-Configuring-And-Managing-Config-Files-Management"> - <title>Management Configuration</title> - <para> - Management interfaces can be configured in <emphasis>management</emphasis> section of broker configuration file. The example of the management section is provided below. + <section id="Java-Broker-Configuring-And-Managing-Configuration-Store-Introduction"> + <title>Configuration store</title> + <para>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: + <itemizedlist> + <listitem><para>Broker</para></listitem> + <listitem><para>Port</para></listitem> + <listitem><para>Authentication Provider</para></listitem> + <listitem><para>Virtual Host</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> - <example> - <title>Management configuration</title> - <programlisting><![CDATA[ - <broker> - ... - <management> - <enabled>true</enabled> - <jmxport> - <registryServer>8999</registryServer> - </jmxport> - <ssl> - <enabled>false</enabled> - <keyStorePath>${conf}/qpid.keystore</keyStorePath> - <keyStorePassword>password</keyStorePassword> - </ssl> - <http> - <enabled>true</enabled> - </http> - <https> - <enabled>false</enabled> - </https> - </management> - ... - </broker>]]></programlisting> - </example> - </section> - <section role="h2" id="Java-Broker-Configuring-And-Managing-Config-Files-JMX-Management"> - <title>JMX Management Configuration</title> + <para>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.</para> + <para>The predefined initial configuration can be overridden using command line argument <emphasis>-icp</emphasis> + with path to the initial configuration as in the example below:</para> + <screen> +$ ./qpid-server -icp ./my-initial-configuration.json + </screen> + <para>In this example the initial configuration from file "./my-initial-configuration.json" is used + to create the broker configuration store on the broker startup.</para> + <para>If broker configuration store already exists the command line argument <emphasis>-icp</emphasis> with the path + to a custom initial configuration is ignored. The command line argument <emphasis>-os</emphasis> 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:</para> + <screen> +$ ./qpid-server -os -icp ./my-initial-configuration.json + </screen> <para> - JMX management can be configured in <emphasis>management</emphasis> section of broker configuration file. - </para> - <para>An <emphasis>enabled</emphasis> element in the <emphasis>management</emphasis> section is used to enable or disable the JMX interfaces. Setting it to <emphasis>true</emphasis> causes the broker to start the management plugin if such is available on the broker classpath.</para> - <para>JMX management requires two ports which can be configured in <emphasis>jmxport</emphasis> sub-section of <emphasis>management</emphasis>: + The default initial configuration can be retrieved from the broker and stored into a file + using a command line argument <emphasis>-cic <path to file ></emphasis>, for example:</para> + <screen> +$ ./qpid-server -cic ./initial-config.json + </screen> + <para>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.</para> + <para>The default initial configuration declares four ports: <itemizedlist> - <listitem><para>RMI port (8999 by default) can be configured in an element <emphasis>jmxport/registryServer</emphasis></para></listitem> - <listitem><para>Connector port can be configured in an element <emphasis>jmxport/connectorServer</emphasis>. If configuration element <emphasis>connectorServer</emphasis> is not provided than the connector port defaults to <emphasis>100 + registryServer port</emphasis>.</para></listitem> + <listitem><para><emphasis>AMQP</emphasis>, the default port number is 5672. The port number + can be overridden using configuration parameter <emphasis>qpid.amqp_port</emphasis>.</para></listitem> + <listitem><para><emphasis>HTTP</emphasis>, the default port number is 8080. The port number + can be overridden using configuration parameter <emphasis>qpid.HTTP_port</emphasis>.</para></listitem> + <listitem><para><emphasis>RMI</emphasis>, the default port number is 8999. The port number + can be overridden using configuration parameter <emphasis>qpid.rmi_port</emphasis>.</para></listitem> + <listitem><para><emphasis>JMX</emphasis>, the default port number is 9099. The port number + can be overridden using configuration parameter <emphasis>qpid.jmx_port</emphasis>.</para></listitem> </itemizedlist> + It is also possible to override the port numbers in a default initial configuration using a command line + argument <emphasis>-prop</emphasis> like in an example below: </para> - <example> - <title>Enabling JMX Management and configuring JMX ports</title> - <programlisting> -<broker> -... -<management> - <emphasis><enabled>true</enabled></emphasis> <co id="java-broker-example-jmx-management-0"/> - <jmxport> - <emphasis><registryServer>7999</registryServer></emphasis> <co id="java-broker-example-jmx-management-1"/> - <emphasis><connectorServer>7998</connectorServer></emphasis> <co id="java-broker-example-jmx-management-2"/> - </jmxport> -</management> -... -</broker></programlisting> - </example> - <para>In the snippet above the following is configured:</para> - <calloutlist> - <callout arearefs="java-broker-example-jmx-management-0"><para>Enable JMX management</para></callout> - <callout arearefs="java-broker-example-jmx-management-1"><para>Set RMI port to 7999</para></callout> - <callout arearefs="java-broker-example-jmx-management-2"><para>Set connector port to 7998</para></callout> - </calloutlist> - <para>SSL can be configured to use on the connector port in the sub-section <emphasis>ssl</emphasis> of the <emphasis>management</emphasis> section. See <xref linkend="Java-Broker-Configuring-And-Managing-Config-Files-SSL-keystore-configuration"/> for details.</para> - <para>In order to use SSL with JMX management an element <emphasis>ssl/enabled</emphasis> needs to be set to <emphasis>true</emphasis>.</para> - </section> - <section role="h2" id="Java-Broker-Configuring-And-Managing-Config-Files-SSL-keystore-configuration"> - <title>Management SSL key store configuration</title> - <para> - This section describes how to configure the key store to use in SSL connections in both JMX and Web management interfaces. + <screen> +$ ./qpid-server -prop qpid.amqp_port=10000 -prop qpid.http_port=10001 -prop qpid.jmx_port=10002 -prop qpid.rmi_port=10003 + </screen> + <para>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 <emphasis>-os</emphasis> + can be used to force (re)creation of broker configuration store from initial store. </para> - <para>The following examples demonstrates how to configure keystore for management</para> - <example> - <title>Management key store configuration</title> - <programlisting> -<broker> -... -<management> -... - <ssl> - <enabled>true</enabled> <co id="java-broker-example-management-keystore-0"/> - <keyStorePath>${conf}/qpid.keystore</keyStorePath> <co id="java-broker-example-management-keystore-1"/> - <keyStorePassword>password</keyStorePassword> <co id="java-broker-example-management-keystore-2"/> - </ssl> -... -</management> -... -</broker></programlisting> - </example> - <calloutlist> - <callout arearefs="java-broker-example-management-keystore-0"><para>Enable SSL on JMX connector port only. This setting does not effect the web management interfaces.</para></callout> - <callout arearefs="java-broker-example-management-keystore-1"><para>Set path to the key store file</para></callout> - <callout arearefs="java-broker-example-management-keystore-2"><para>Set keystore password</para></callout> - </calloutlist> + <para>The command line argument <emphasis>-sp</emphasis> 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.</para> + <screen> +$ ./qpid-server -sp ./my-broker-configuration.json + </screen> + <para>In the example above the broker is started with configuration store at "./my-broker-configuration.json".</para> </section> - <section role="h2" id="Java-Broker-Configuring-And-Managing-Config-Files-Web-Management"> - <title>Web Management Configuration</title> - <para> - Web management can be configured in <emphasis>management</emphasis> section of broker configuration file. - </para> - <para>Sub-section <emphasis>http</emphasis> is used to enable web management on http port.</para> - <para>Sub-section <emphasis>https</emphasis> is used to enable web management on https port.</para> - <para>The following example shows how to configure http and https ports</para> + + <section id="Java-Broker-Configuring-And-Managing-Configuration-Store-Example"> + <title>Example of JSON configuration store</title> + <para>The JSON configuration store is used as a default configuration store. + An example of the JSON store is provided below:</para> <example> - <title>Enabling web management</title> - <programlisting> -<broker> -... -<management> -... - <http> - <enabled>true</enabled> <co id="java-broker-example-management-web-0"/> - <port>9090</port> <co id="java-broker-example-management-web-1"/> - <basic-auth>false</basic-auth> <co id="java-broker-example-management-web-2"/> - <sasl-auth>true</sasl-auth> <co id="java-broker-example-management-web-3"/> - <session-timeout>600</session-timeout> <co id="java-broker-example-management-web-4"/> - </http> + <title>JSON configuration store</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> - <https> - <enabled>true</enabled> <co id="java-broker-example-management-web-5"/> - <port>9443</port> <co id="java-broker-example-management-web-6"/> - <sasl-auth>true</sasl-auth> <co id="java-broker-example-management-web-7"/> - <basic-auth>true</basic-auth> <co id="java-broker-example-management-web-8"/> - </https> -... -</management> -... -</broker></programlisting> - </example> - <calloutlist> - <callout arearefs="java-broker-example-management-web-0"><para>Enable web management on http port. Default is true.</para></callout> - <callout arearefs="java-broker-example-management-web-1"><para>Set web management http port to 9090. Default is 8080.</para></callout> - <callout arearefs="java-broker-example-management-web-2"><para>Disable basic authentication on http port for REST services only. Default is false.</para></callout> - <callout arearefs="java-broker-example-management-web-3"><para>Enable SASL authentication on http port for REST services and web console. Default is true.</para></callout> - <callout arearefs="java-broker-example-management-web-4"><para>Set session timeout in seconds. Default is 15 minutes.</para></callout> - <callout arearefs="java-broker-example-management-web-5"><para>Enable web management on https port. Default is false.</para></callout> - <callout arearefs="java-broker-example-management-web-6"><para>Set web management https port to 9443. Default is 8443.</para></callout> - <callout arearefs="java-broker-example-management-web-7"><para>Enable SASL authentication on https port for REST services and web console. Default is true.</para></callout> - <callout arearefs="java-broker-example-management-web-8"><para>Enable basic authentication on https port for REST services only. Default is true.</para></callout> - </calloutlist> - <note><para>Please configure the keystore to use with the https web management port. See <xref linkend="Java-Broker-Configuring-And-Managing-Config-Files-SSL-keystore-configuration"/> for details.</para></note> - </section> -</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>
\ No newline at end of file |